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 PR B's daily 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 (PR C) 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 PR B's LiteLLM refresh; unused in PR A. 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 (PR B's fetcher only rewrites External).

type ModelRates ¶

type ModelRates struct {
	InputPerMTok       float64   `json:"input_per_mtok,omitempty"`
	CachedInputPerMTok float64   `json:"cached_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.

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 core-agent state directory (usually
	// ~/.core-agent). 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
	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.

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) 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 PR C's
	// /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 (cmd/core-agent startup + PR C's /pricing refresh slash) 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 ~/.core-agent/pricing.json shape — sectioned so PR B's daily refresh can overwrite the `external` section without touching `manual` entries the operator hand-edited (or set via /pricing set in PR C).

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