pricing

type Catalog ¶

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog is the merged view of all pricing sources, queried by model name. Construct with NewCatalog; consult with Lookup.

Layers are stored separately so the daily LiteLLM refresh can rewrite the external slice without touching the others, and so the precedence chain stays explicit (no "where did this rate come from" mystery).

func NewCatalog(opts Options) (*Catalog, error)

func (c *Catalog) Counts() CountByLayer

func (c *Catalog) Lookup(modelID string) (Rates, bool)

func (c *Catalog) LookupWithSource(modelID string) (Rates, string, bool)

type CountByLayer ¶

type CountByLayer struct {
	CfgOverride  int
	ProjectFile  int
	UserManual   int
	UserExternal int
	Builtin      int
}

CountByLayer reports how many model entries each layer holds. Surfaced via /pricing list and useful for tests that want to assert the expected number of rows landed in each layer.

type ExternalSource ¶

type ExternalSource struct {
	FetchedAt time.Time             `json:"fetched_at"`
	Source    string                `json:"source"` // canonical URL the data was pulled from
	ETag      string                `json:"etag,omitempty"`
	Models    map[string]ModelRates `json:"models,omitempty"`
}

ExternalSource is the auto-fetched section, populated by Refresh from LiteLLM's catalog. The fetched_at + etag fields drive cache-validity logic (skip refresh if <24h, send If-None-Match on revalidation).

type ManualSection ¶

type ManualSection struct {
	Models map[string]ModelRates `json:"models,omitempty"`
}

ManualSection is the operator-curated section. Round-trips intact across refreshes (the fetcher only rewrites External).

type ModelRates ¶

type ModelRates struct {
	InputPerMTok              float64   `json:"input_per_mtok,omitempty"`
	CachedInputPerMTok        float64   `json:"cached_input_per_mtok,omitempty"`
	CacheCreationInputPerMTok float64   `json:"cache_creation_input_per_mtok,omitempty"`
	OutputPerMTok             float64   `json:"output_per_mtok,omitempty"`
	UpdatedAt                 time.Time `json:"updated_at,omitempty"`
}

ModelRates is the on-disk per-model rate, mirroring config's PricingConfig field names so operator-edited files use the same spelling regardless of whether they live in pricing.json or in .agents/config.json's `model.pricing` override map.

func (m ModelRates) Rates() Rates

type Options ¶

type Options struct {
	// CfgOverride is the operator's per-model override from
	// .agents/config.json's `model.pricing` map. Highest precedence.
	CfgOverride map[string]ModelRates

	// AgentsDir is the resolved .agents/ directory (empty when no
	// project root was found). Catalog construction reads
	// <agentsDir>/pricing.json if present.
	AgentsDir string

	// UserHome is the per-user mast state directory (usually
	// ~/.mast). Catalog construction reads <UserHome>/pricing.json
	// if present (both manual + external sections).
	UserHome string
}

Options bundle the inputs NewCatalog needs to assemble the layered view. All fields are optional — an empty Options yields a catalog with only the compiled-in builtin layer (useful for tests + as the default before main.go wires the files in).

type ProjectFile ¶

type ProjectFile struct {
	Version int                   `json:"version"`
	Models  map[string]ModelRates `json:"models,omitempty"`
}

ProjectFile is the .agents/pricing.json shape — flat models map. Project files are always operator-curated (never auto-fetched), so no manual/external split is needed.

func LoadProjectFile(agentsDir string) (*ProjectFile, error)

type Rates ¶

type Rates struct {
	InputPerMTok              float64
	CachedInputPerMTok        float64
	CacheCreationInputPerMTok float64
	OutputPerMTok             float64
	UpdatedAt                 time.Time
}

Rates is the per-million-token cost for one model. CachedInputPerMTok is the rate applied to input tokens served from the provider's prompt cache (Gemini's `cachedContentTokenCount`, Anthropic's `cache_read_input_tokens`); a zero value means the cache-read rate isn't known and callers should bill cached tokens at InputPerMTok.

CacheCreationInputPerMTok is the rate for input tokens that WRITE a cache entry — Anthropic's `cache_creation_input_tokens`, billed at a premium over base input rather than a discount. It is a single scalar and therefore holds exactly ONE write rate: the 5-minute-TTL one (1.25x base input), which is also the only one LiteLLM publishes (cache_creation_input_token_cost). Anthropic's 1-hour TTL costs 2x base input, so a caller that starts requesting `ttl: "1h"` at the cache_control site would be undercharged by 37.5% against this field; adding 1h support means adding a second rate here, not reusing this one. Gemini has no equivalent bucket: its explicit caches bill storage per hour, not per written token, so the field stays zero for Gemini rows. A zero value means the cache-write rate isn't known and callers should bill written tokens at InputPerMTok — which UNDERCOUNTS, so keep the builtin table populated (dev/regen-builtin-pricing pulls the rate from LiteLLM's cache_creation_input_token_cost). See go-steer/core-agent#263.

UpdatedAt records when the rate was last verified against its source (LiteLLM refresh time, generator run time for builtin entries, operator edit time for manual overrides). Zero when unknown. Surfaced through /pricing so operators can spot stale entries at a glance — issue #259 called out that hand-authored rates drift silently, and staleness visibility is the mitigation baked into the "regenerate builtin from LiteLLM" workflow that followed.

func (r Rates) CostUSD(inputTokens, outputTokens int) float64

func (r Rates) CostUSDWithCache(uncachedInputTokens, cachedInputTokens, outputTokens int) float64

func (r Rates) CostUSDWithCacheWrites(uncachedInputTokens, cacheReadTokens, cacheWriteTokens, outputTokens int) float64

func (r Rates) IsZero() bool

type RefreshOptions ¶

type RefreshOptions struct {
	// Source is the URL to fetch. Defaults to DefaultRefreshSource.
	Source string

	// Client is the HTTP client used. Defaults to a fresh one with
	// a 30s timeout — long enough for slow links, short enough that
	// startup doesn't hang forever.
	Client *http.Client

	// MinInterval is the minimum age the cache must reach before
	// Refresh actually fetches. Zero defaults to
	// DefaultRefreshInterval (24h). Set to a negative duration to
	// force a fetch regardless of cache age (used by the
	// /pricing refresh slash command).
	MinInterval time.Duration

	// Now is the clock Refresh uses to compute cache age. Tests
	// override to deterministically drive stale-vs-fresh. Defaults
	// to time.Now.
	Now func() time.Time
}

RefreshOptions controls the refresh fetch. All fields optional; defaults match a production launch (LiteLLM upstream, 24h cadence, no max-size cap, 30s timeout). Tests + air-gapped mirrors override Source; integration tests override Now for deterministic stale-vs-fresh decisions.

type RefreshOutcome ¶

type RefreshOutcome struct {
	Skipped       bool          // true when the cache was fresh enough to skip the fetch
	NotModified   bool          // true when the server replied 304 (cache still authoritative)
	NetworkFailed bool          // true when the fetch itself failed; cache was preserved
	NetworkError  error         // populated when NetworkFailed
	StaleAge      time.Duration // age of the cache at decision time; zero for fresh writes
	ModelCount    int           // number of models written to the external section (zero on Skipped/NotModified)
	FetchedAt     time.Time     // timestamp stored in the cache file (or pre-existing one for Skipped)
}

RefreshOutcome is the result of a Refresh call. Surfaced so the caller (daemon startup + a future /pricing refresh surface) can render a meaningful one-liner: "Refreshed 247 models from LiteLLM" / "Cache is 4h old; skipped" / "Using 6-day-old cache; network unreachable: connection refused".

func Refresh(ctx context.Context, userHome string, opts RefreshOptions) (RefreshOutcome, error)

type UserFile ¶

type UserFile struct {
	Version  int             `json:"version"`
	External *ExternalSource `json:"external,omitempty"`
	Manual   *ManualSection  `json:"manual,omitempty"`
}

UserFile is the ~/.mast/pricing.json shape — sectioned so the LiteLLM refresh can overwrite the `external` section without touching `manual` entries the operator hand-edited (or set via /pricing set).

func LoadUserFile(userHome string) (*UserFile, error)