usage

Documentation

Overview

Package usage tracks token + cost accounting for the agent loop.

Every model call returns a UsageMetadata block with input and output token counts; a Tracker accumulates these across a session. Pricing numbers come from a built-in table that callers may override per model via .agents/config.json (model.pricing).

Index

• type Pricing
  • func PriceFor(modelID string, cfg *config.Config) Pricing
  • func (p Pricing) CostUSD(inputTokens, outputTokens int) float64
  • func (p Pricing) IsZero() bool
• type Totals
• type Tracker
  • func NewTracker() *Tracker
  • func (t *Tracker) All() []Turn
  • func (t *Tracker) Append(model string, inputTokens, outputTokens int, p Pricing) Turn
  • func (t *Tracker) Duration() time.Duration
  • func (t *Tracker) Last() (Turn, bool)
  • func (t *Tracker) Totals() Totals
• type Turn

Types

type Pricing

type Pricing struct {
	InputPerMTok  float64 // USD per 1,000,000 input tokens
	OutputPerMTok float64 // USD per 1,000,000 output tokens
}

Pricing is the per-million-token rate for one model. Both fields are in USD and apply to a single direction (input or output).

func PriceFor

func PriceFor(modelID string, cfg *config.Config) Pricing

PriceFor returns the Pricing for modelID. Resolution order:

1. Explicit cfg override (cfg.Model.Pricing) when modelID matches cfg.Model.Name (case-insensitive).
2. Exact match in the built-in table.
3. Prefix match in the built-in table (longest first).
4. Zero pricing — caller should treat cost as unknown.

func (Pricing) CostUSD

func (p Pricing) CostUSD(inputTokens, outputTokens int) float64

CostUSD returns the dollar cost of (input, output) tokens at p.

func (Pricing) IsZero

func (p Pricing) IsZero() bool

IsZero reports whether neither rate is set (we don't know how to price this model).

type Totals

type Totals struct {
	Turns        int
	InputTokens  int
	OutputTokens int
	CostUSD      float64
}

Totals aggregates a slice of Turns.

type Tracker

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

Tracker accumulates per-turn usage for one Cogo session.

Thread-safe: the agent goroutine (or headless run loop) calls Append; the TUI's render path reads via Last/Totals/All.

func NewTracker

func NewTracker() *Tracker

NewTracker returns a tracker with its session-start time set to now.

func (*Tracker) All

func (t *Tracker) All() []Turn

All returns a copy of every recorded turn (for /stats rendering).

func (*Tracker) Append

func (t *Tracker) Append(model string, inputTokens, outputTokens int, p Pricing) Turn

Append records one turn's usage. Cost is computed via the supplied Pricing; pass a zero Pricing to skip cost tracking.

func (*Tracker) Duration

func (t *Tracker) Duration() time.Duration

Duration reports wall-clock time since NewTracker was called.

func (*Tracker) Last

func (t *Tracker) Last() (Turn, bool)

Last returns the most recently appended turn, or zero if none yet.

func (*Tracker) Totals

func (t *Tracker) Totals() Totals

Totals returns the cumulative usage across all turns.

type Turn

type Turn struct {
	Model        string
	InputTokens  int
	OutputTokens int
	CostUSD      float64
	At           time.Time
}

Turn captures one model call's resource use. Times are wall clock so summary lines can include session duration without a monotonic ref.