ledger

Documentation

Overview

Package ledger holds the cost-accounting readout types and pure aggregation logic carved off the agent Session god-object. The Session holds a *llm.Ledger (the metered gateway's shared record); this package defines the display types (BackendSpend, PurposeSpend) and the functions that turn ledger snapshots into sorted, display-ready slices. The functions take a Reader interface (satisfied by *llm.Ledger) so the ledger package depends only on llm, not on runtime.

Index

• func CacheStats(r Reader) (read, write int)
• func Spend(r Reader) (in, out, cacheRead, cacheWrite int, usd float64)
• func Tokens(r Reader) (in, out int)
• type BackendSpend
  • func SpendByBackend(r Reader) []BackendSpend
• type PurposeSpend
  • func SpendByPurpose(r Reader) []PurposeSpend
• type Reader

Functions

func CacheStats

func CacheStats(r Reader) (read, write int)

CacheStats returns cumulative prompt-cache token counts (read ≈ 10% cost; write = tokens written to the cache). Shown under /debug.

func Spend

func Spend(r Reader) (in, out, cacheRead, cacheWrite int, usd float64)

Spend returns the session's token breakdown and estimated cost in USD (priced per response under each call's model; rates are approximate). Powers /cost.

func Tokens

func Tokens(r Reader) (in, out int)

Tokens returns cumulative session token flow: total input the model saw (uncached + cache reads) and total output. Footer "↑in ↓out".

Types

type BackendSpend

type BackendSpend struct {
	Backend                                    string
	Calls                                      int
	In, Out, CacheRead, CacheWrite             int
	USD                                        float64
	InUSD, OutUSD, CacheReadUSD, CacheWriteUSD float64
	AvgLatencyMS                               int64
	Reasons                                    map[string]int
}

BackendSpend is one serving backend's slice of the session ledger (for /cost): who actually ran the calls, how fast, and what it cost at the served model's rate card (every backend is token-billed — the cheap lane + frontier APIs).

func SpendByBackend

func SpendByBackend(r Reader) []BackendSpend

SpendByBackend returns per-backend usage, busiest first. One entry ("anthropic") in a classic session; two once the hybrid router is live.

type PurposeSpend

type PurposeSpend struct {
	Purpose                        string
	Calls                          int
	In, Out, CacheRead, CacheWrite int
	USD                            float64
}

PurposeSpend is one purpose's slice of the session ledger (for /cost --by-purpose).

func SpendByPurpose

func SpendByPurpose(r Reader) []PurposeSpend

SpendByPurpose returns per-purpose usage, most expensive first — so /cost can show where the money actually went (e.g. explore scouts vs the main loop vs synthesis).

type Reader

type Reader interface {
	Total() llm.Stat
	ByBackend() map[string]llm.BackendStat
	ByPurpose() map[llm.Purpose]llm.Stat
}

Reader is the subset of *llm.Ledger the aggregation functions need. *llm.Ledger satisfies it; tests can substitute a fake. The ledger package depends on llm for Stat/BackendStat/Purpose, but never on runtime — so the import direction stays runtime → ledger → llm (a clean leaf below the hub).