Documentation
¶
Overview ¶
Package usage provides persistent token usage and cost tracking for LLM interactions. Records are append-only and indexed by timestamp, session, and conversation for efficient aggregation queries.
Index ¶
- func ComputeCost(model string, inputTokens, outputTokens int, ...) float64
- func ResolveProvider(model string) string
- type GroupedSummary
- type Record
- type Store
- func (s *Store) Close() error
- func (s *Store) Record(ctx context.Context, rec Record) error
- func (s *Store) Summary(start, end time.Time) (*Summary, error)
- func (s *Store) SummaryByModel(start, end time.Time) ([]GroupedSummary, error)
- func (s *Store) SummaryByRole(start, end time.Time) ([]GroupedSummary, error)
- func (s *Store) SummaryByTask(start, end time.Time) ([]GroupedSummary, error)
- type Summary
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ComputeCost ¶
func ComputeCost(model string, inputTokens, outputTokens int, pricing map[string]config.PricingEntry) float64
ComputeCost calculates the USD cost for a model's token usage based on the pricing table. Models not in the table are treated as free (local/Ollama models).
func ResolveProvider ¶
ResolveProvider infers the LLM provider from the model name. Models starting with "claude-" are Anthropic; everything else is assumed to be Ollama (local).
Types ¶
type GroupedSummary ¶
GroupedSummary pairs a grouping key (model name, role, task name) with its aggregated usage totals. Slices of GroupedSummary preserve the SQL ordering (highest cost first).
type Record ¶
type Record struct {
ID string
Timestamp time.Time
RequestID string
SessionID string
ConversationID string
Model string
Provider string // "anthropic", "ollama"
InputTokens int
OutputTokens int
CostUSD float64
Role string // "interactive", "delegate", "scheduled", "auxiliary"
TaskName string // "email_poll", "periodic_reflection", etc. (empty for interactive)
}
Record represents a single LLM interaction's token usage and cost.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is an append-only SQLite store for token usage records. All public methods are safe for concurrent use (SQLite serializes writes).
func NewStore ¶
NewStore creates a usage store at the given database path. The schema is created automatically on first use.
func (*Store) Record ¶
Record persists a usage record. If rec.ID is empty, a UUIDv7 is generated. The context is used for cancellation only.
func (*Store) SummaryByModel ¶
func (s *Store) SummaryByModel(start, end time.Time) ([]GroupedSummary, error)
SummaryByModel returns per-model aggregated totals for records within [start, end), ordered by cost descending.
func (*Store) SummaryByRole ¶
func (s *Store) SummaryByRole(start, end time.Time) ([]GroupedSummary, error)
SummaryByRole returns per-role aggregated totals for records within [start, end), ordered by cost descending.
func (*Store) SummaryByTask ¶
func (s *Store) SummaryByTask(start, end time.Time) ([]GroupedSummary, error)
SummaryByTask returns per-task aggregated totals for records within [start, end), ordered by cost descending. Records with empty task_name are grouped under the key "".
Source Files