Documentation
¶
Overview ¶
Package cost computes USD cost attribution for agent token usage.
Pricing is expressed in USD per 1,000,000 tokens, broken out by token class (input, output, cache write, cache read). A built-in table covers common model families (claude-*, gpt-*, gemini-*) with a conservative fallback for unknown models. The table can be overridden or extended from a JSON config file at ~/.hawk/trace-pricing.json.
Index ¶
Constants ¶
const PricingConfigEnv = "TRACE_PRICING_CONFIG"
PricingConfigEnv overrides the pricing config file path when set. Used in tests to avoid touching the real home directory.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Breakdown ¶
type Breakdown struct {
// Model is the model ID the cost was computed for.
Model string `json:"model"`
// Pricing is the rate table applied (USD per 1M tokens).
Pricing ModelPricing `json:"pricing"`
// PricingMatched reports whether the model matched a known table entry.
// When false, fallback pricing was used.
PricingMatched bool `json:"pricing_matched"`
// Per-class dollar costs.
Input float64 `json:"input"`
Output float64 `json:"output"`
CacheWrite float64 `json:"cache_write"`
CacheRead float64 `json:"cache_read"`
// Subagents is the total dollar cost attributed to spawned subagents, if
// any token usage recorded subagent tokens. It is already included in the
// returned total.
Subagents float64 `json:"subagents,omitempty"`
// Total is the sum of all per-class costs (including subagents) in USD.
Total float64 `json:"total"`
}
Breakdown is the per-token-class dollar decomposition of a cost computation, all in USD.
func ComputeCost ¶
func ComputeCost(usage agent.TokenUsage, model string) (total float64, breakdown Breakdown)
ComputeCost computes the USD cost of a token usage record under the given model, using the built-in pricing table merged with any config-file overrides. Unknown models fall back to the fallback pricing. Subagent token usage (TokenUsage.SubagentTokens) is recursively included in the total and reported separately in the breakdown.
func ComputeCostWith ¶
func ComputeCostWith(table *Table, usage agent.TokenUsage, model string) (total float64, breakdown Breakdown)
ComputeCostWith is ComputeCost using an explicit pricing table. It performs no I/O, which makes it convenient for tests and for callers that have already loaded a table.
type ModelPricing ¶
type ModelPricing struct {
// Input is the price per 1M fresh (non-cached) input tokens.
Input float64 `json:"input"`
// Output is the price per 1M generated output tokens.
Output float64 `json:"output"`
// CacheWrite is the price per 1M tokens written to the prompt cache.
CacheWrite float64 `json:"cache_write"`
// CacheRead is the price per 1M tokens read from the prompt cache.
CacheRead float64 `json:"cache_read"`
}
ModelPricing holds the USD price per 1,000,000 tokens for each token class.
type Table ¶
type Table struct {
// contains filtered or unexported fields
}
Table maps model-ID prefixes to pricing. Look up rates with PricingFor.
func LoadTable ¶
LoadTable returns the built-in pricing table with any overrides from the config file at ~/.hawk/trace-pricing.json (or the path named by TRACE_PRICING_CONFIG) merged in. A missing config file is not an error and yields the built-in table unchanged. Entries in the file replace built-in entries with the same key and add new keys.
func (*Table) PricingFor ¶
func (t *Table) PricingFor(model string) (pricing ModelPricing, matched bool)
PricingFor returns the pricing for a model, matching the longest model-ID prefix in the table. Matching is case-insensitive. If no prefix matches, the fallback pricing is returned along with matched=false.
Source Files