LLM Price Snapshot (lobster.pricing)

Overview

Lobster AI 1.2.0 adds lobster.pricing, an offline lookup of LLM list prices. The rates come from a committed snapshot of the public models.dev registry (lobster/pricing/prices.json), plus a small set of hand-reviewed entries (lobster/pricing/overrides.json).

• No runtime fetch. Nothing is downloaded at run time, and importing the package performs no I/O. The data files are read on first use.
• Exact keys. Model IDs are matched exactly; nothing is normalized or stripped. Bedrock global., us. and eu. routes are distinct entries, and the same model under different providers is a different key.
• Unknown is None, never 0. An unknown provider, an unknown model, or a model without a cost entry returns None. There is no fallback to a similar model or a default price. A rate of 0 is a real zero.

Looking Up Rates

from lobster.pricing import SNAPSHOT, get_rates

rates = get_rates("bedrock", "us.anthropic.claude-sonnet-4-5-20250929-v1:0")
if rates is None:
    print("No price known for this exact provider/model pair")
else:
    print(rates.input, rates.output)          # Decimal, USD per 1M tokens
    print(rates.cache_read, rates.cache_write)
    print(rates.source)                       # "models.dev" or "override"

print(SNAPSHOT.snapshot_id, SNAPSHOT.fetched_at)

get_rates(provider, model_id) -> Rates | None accepts an engine provider ID or its models.dev ID:

ollama (local models) and omics-os are not market providers and always return None.

Rates

for_context(rates, input_tokens) returns the rates of the highest context tier strictly exceeded by input_tokens. It selects rates only; it never computes a cost.

SNAPSHOT

SNAPSHOT identifies the packaged data: snapshot_id, source_url, source_sha256 (of the raw models.dev response), fetched_at (UTC), schema_version, overrides_sha256, and lobster_version.

Reviewed Overrides

overrides.json covers gaps in the registry. Each entry names an exact engine provider and model ID and must record its source_url (https), the date it was checked (checked_at), and its reviewer. A reviewed override for an exact pair takes precedence over the snapshot.

Refreshing the Snapshot

The snapshot is regenerated with:

make update-pricing

This runs scripts/update_pricing.py, which fetches https://models.dev/api.json, keeps only the cost objects of the supported providers verbatim, and writes prices.json and a coverage report (coverage.json). An unreachable, truncated, oversized or invalid source exits non-zero and leaves the existing files untouched. The result is committed and reviewed like any other source change.

Token Usage Evidence

lobster.pricing.usage.normalize_usage(usage_metadata, raw_usage, provider) normalizes token counts reported by different providers into one NormalizedUsage: logical_input, output_incl_reasoning, cache_read, cache_write, reasoning, basis, and complete. When the evidence is missing, invalid, conflicting or ambiguous, complete is False, the logical totals are None, and a warning is logged. It never guesses a count and never applies rates.

The token tracking callback now records these counts on each invocation as additive fields: logical_input_tokens, logical_output_tokens, cache_read_tokens, cache_write_tokens, reasoning_tokens, input_token_basis, usage_source, and usage_complete. The usage summary adds usage_complete, missing_usage_invocations, pending_usage_invocations and duplicate_usage_invocations. It also adds attempt_coverage: "callback_only", because only callbacks that are actually received are counted.

Unchanged: input_tokens, output_tokens, cost_usd and total_cost_usd keep their existing meaning and are still computed from the existing model pricing configuration (MODEL_PRICING). The new fields do not reprice them.

Attribution

Price data is derived from models.dev (models.dev), MIT License, Copyright (c) 2025 models.dev. The full license text is included in prices.json under source.license_text.