usage

Documentation

Overview

Package usage is the coding product's token and cost ledger. It is kept separate from any delivery mechanism: the ledger is written from the session event stream and read by whichever client asks for a report, so nothing here depends on HTTP.

Index

• type Event
• type EventPage
• type ModelSummary
• type Report
• type Store
  • func NewStore(dbPath string) (*Store, error)
  • func (s *Store) BackfillEntries(sessionID string, entries []transcript.Entry) error
  • func (s *Store) Close() error
  • func (s *Store) Events(provider, model string, since time.Time, offset, limit int) (EventPage, error)
  • func (s *Store) RecordEvent(sessionID string, event engine.Event) error
  • func (s *Store) Report(since time.Time) (Report, error)
• type Totals

Types

type Event

type Event struct {
	ID            string    `json:"id"`
	SessionID     string    `json:"sessionId"`
	Provider      string    `json:"provider"`
	Model         string    `json:"model"`
	ResponseModel string    `json:"responseModel,omitempty"`
	ResponseID    string    `json:"responseId,omitempty"`
	Timestamp     time.Time `json:"timestamp"`
	Usage         llm.Usage `json:"usage"`
}

Event is one billable provider response. It is stored independently from conversations so deleting a session does not rewrite usage history.

type EventPage

type EventPage struct {
	Events []Event `json:"events"`
	Total  int     `json:"total"`
	Limit  int     `json:"limit"`
	Offset int     `json:"offset"`
}

EventPage is a newest-first slice of individual provider requests.

type ModelSummary

type ModelSummary struct {
	Provider      string    `json:"provider"`
	Model         string    `json:"model"`
	Name          string    `json:"name"`
	ResponseModel string    `json:"responseModel,omitempty"`
	LastUsedAt    time.Time `json:"lastUsedAt"`
	Totals
}

ModelSummary groups usage by the requested provider and model.

type Report

type Report struct {
	Total       Totals         `json:"total"`
	Models      []ModelSummary `json:"models"`
	GeneratedAt time.Time      `json:"generatedAt"`
}

Report is an aggregate over a requested time range.

type Store

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

Store is a disk-backed, append-only, deduplicated usage ledger. SQLite owns event indexes and aggregation so process memory does not grow with history.

func NewStore

func NewStore(dbPath string) (*Store, error)

NewStore opens the SQLite ledger at dbPath.

func (*Store) BackfillEntries

func (s *Store) BackfillEntries(sessionID string, entries []transcript.Entry) error

BackfillEntries restores usage for both ordinary assistant responses and the direct model requests used to create compaction checkpoints.

func (*Store) Close

func (s *Store) Close() error

Close releases the database connection. Call it after every conversation manager using the ledger has stopped.

func (*Store) Events

func (s *Store) Events(
	provider, model string,
	since time.Time,
	offset, limit int,
) (EventPage, error)

Events returns a stable newest-first page. Filtering, counting, sorting and pagination stay inside SQLite rather than copying the complete ledger.

func (*Store) RecordEvent

func (s *Store) RecordEvent(sessionID string, event engine.Event) error

RecordEvent persists one live MessageCompleted event. Empty usage records are ignored because some providers emit terminal metadata without billing.

func (*Store) Report

func (s *Store) Report(since time.Time) (Report, error)

Report aggregates usage in SQLite. A zero since value includes the complete ledger; only the small set of grouped model rows enters process memory.

type Totals

type Totals struct {
	Requests     int64         `json:"requests"`
	Input        int64         `json:"input"`
	InputUnknown bool          `json:"inputUnknown,omitempty"`
	Output       int64         `json:"output"`
	CacheRead    int64         `json:"cacheRead"`
	CacheWrite   int64         `json:"cacheWrite"`
	TotalTokens  int64         `json:"totalTokens"`
	Cost         llm.UsageCost `json:"cost"`
}

Totals is an aggregate returned by the usage API.