The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
// Package pricing estimates what a model call would cost at the provider's published list price.
//
// It exists so token reports can show a cost for every runtime, not only the ones that report
// one. It is report-time arithmetic and nothing more: no network access, no writes, and nothing
// it computes is ever stored in an event. `gen_ai.usage.cost_usd` stays the runtime-reported
// cost; a figure from this package is an estimate and callers must label it as one. The hook
// binary does not import this package.
//
// # The catalog
//
// The rates come from catalog.json, embedded in the binary. It is generated by
// internal/gen from the price list LiteLLM publishes as model_prices_and_context_window.json
// (https://github.com/BerriAI/litellm, MIT License, Copyright (c) 2023 Berri AI; the notice is in
// LICENSE.litellm next to this file). The catalog records the upstream URL, the upstream commit
// it was generated from, and the generation date, so a report can say whose prices it used and
// how old they are. It is regenerated by hand, never during a build or a test:
//
// cd cli/beacon && go run ./internal/pricing/internal/gen
//
// Only standard-tier rates are kept: input, output, cache read, cache write (the default
// five-minute TTL), the one-hour cache write where a provider publishes it, and long-context
// request bands. Batch, flex, priority and regional-endpoint surcharge variants are left out,
// because nothing in Beacon's usage record says a call used them. Rates are integer
// microdollars per million tokens, so $3.00/MTok is 3_000_000.
//
// # Token semantics
//
// Tokens mirrors Beacon's canonical gen_ai.usage record (docs/cli/token-usage.mdx, "Counts are
// kept disjoint"; pkg/asymptoteobserve TraceUsageV1):
//
// - Input is uncached input only. Cache reads and cache writes are separate counts and are
// never also inside Input (Beacon subtracts them on the runtimes that report input
// inclusively, Codex among them).
// - CacheCreation is every token written to the prompt cache. CacheCreation1h is the subset
// of those written with a one-hour TTL, so it is clamped to CacheCreation. It comes from
// gen_ai.usage.cache_creation.ephemeral_1h_input_tokens, which only some sources report;
// where it is absent the field is zero and every write is priced at the five-minute rate.
// - Reasoning is a breakdown of Output, not an addition to it. That is the gen_ai.usage
// contract (reasoning.output_tokens is a sub-field of output, as in the OTel GenAI
// semantic conventions), and docs/cli/token-usage.mdx says reasoning tokens "must not be
// charged a second time because they are already included in output". It is priced at the
// output rate only when Output is zero, which is the record of a runtime that reported
// reasoning and nothing else.
//
// # Long-context bands
//
// Several providers charge more for every token of a request whose prompt passes a size
// threshold (Anthropic and Gemini above 200k, OpenAI's newer models above 272k). That is a
// property of one API request, so Cost applies a band only when the caller says the tokens are
// one request. A sum over many requests cannot be banded -- forty 10k requests are not one 400k
// request -- and is always priced at base rates, which can understate a session that really did
// send long prompts.
//
// # Missing rates
//
// When a model publishes no cache-read rate, cache reads are priced at the input rate. When it
// publishes no cache-write rate, writes are priced at the input rate too. That matches how
// providers without a separate write price bill (OpenAI, Gemini's implicit caching, DeepSeek,
// xAI: a write is an ordinary input token) and turns an unpublished read discount into an upper
// bound instead of a guess. A missing one-hour write rate falls back to the five-minute rate.
// A zero in the upstream list is treated as unpublished, never as free: a token the model
// processed was not free, and an estimate that quietly drops it reads as a real saving. Each
// fallback that affected a non-zero count is reported on the Estimate.
//
// # Model resolution
//
// Lookup turns what a runtime called the model into a catalog entry by a strict ladder and
// never by substring or prefix similarity; see Lookup for the rungs. Two catalog entries that
// match at the same rung with different rates leave the model unpriced rather than picking one.
//
// # Overrides
//
// An operator can price what the catalog cannot -- internal models, releases newer than the
// catalog, gateway names -- and replace list prices with negotiated ones, in a local JSON file
// (schema "beacon.pricing.overrides/v1", default <BaseDir>/pricing/overrides.json, see
// DefaultOverridesPath and docs/cli/pricing.mdx). Beacon only reads that file: the CLI and the
// dashboard load it per run or per request, and nothing in Beacon writes it. Its rates are
// decimal US dollars per million tokens, converted exactly to integer microdollars; a value that
// is negative, zero, finer than a microdollar, quoted, or above MaxOverrideUSDPerMTok is refused
// with an error naming its key, and so is an unknown or repeated key. A row replaces the
// catalog row of every name that reaches it: an omitted cache rate is unpublished, priced by the
// fallbacks above, not inherited from the catalog. An alias sends a reported name to an exact
// row of the file or catalog key. Pricer.Lookup runs the same ladder over the file's names
// first, and the catalog sees only models no override name reaches. Resolution.Source and
// Alias say which list decided.
package pricing