cachemetrics

Documentation

Overview

Package cachemetrics is the per-domain Store over aura.cache_metrics (PRD Slice 4 / Phase 6, D-02). It copies the canonical Store{pool,q} pattern proven in internal/identity and reused by internal/conversations (D-A4-01): a thin wrapper over the generated sqlc surface with pgtype boundary conversion (Pitfall 5) and %w error wrapping. No interface is declared here — the consumer (internal/runner) declares the narrow CacheMetricStore it needs (D-A2-02, "accept interfaces, return structs").

Scope: one append-only INSERT per completed assistant turn (Insert, written from the already-computed llm.Usage in runner_persist.go, D-02a) plus the two time-windowed reads consumed by `aura cache-stats --since=<window>` in 06-04 (ListSince + AggregateSince).

Index

• func NewInsertParams(p MetricParams) (sqlc.InsertCacheMetricParams, error)
• type Aggregate
• type Metric
• type MetricParams
• type Store
  • func New(pool *pgxpool.Pool) *Store
  • func (s *Store) AggregateSince(ctx context.Context, since time.Time) (Aggregate, error)
  • func (s *Store) Insert(ctx context.Context, p sqlc.InsertCacheMetricParams) error
  • func (s *Store) ListSince(ctx context.Context, since time.Time) ([]Metric, error)

Functions

func NewInsertParams

func NewInsertParams(p MetricParams) (sqlc.InsertCacheMetricParams, error)

NewInsertParams converts plain-Go MetricParams into the generated sqlc params the narrow CacheMetricStore.Insert consumes. Centralizing the pgtype conversion here keeps the runner persist seam a one-liner and the conversion logic un-duplicated (D-A4-01).

Types

type Aggregate

type Aggregate struct {
	Turns             int64
	TotalPromptTokens int64
	TotalCachedTokens int64
	TotalCostUSD      float64
}

Aggregate is the windowed roll-up of cache_metrics. The hit-rate ratio is left to the caller (06-04) so the divide-by-zero guard (TotalPromptTokens==0 → ratio 0) lives at the presentation boundary, not in SQL.

type Metric

type Metric struct {
	ConversationID string
	Seq            int
	TS             time.Time
	PromptTokens   int
	CachedTokens   int
	CostUSD        float64
}

Metric is the domain projection of one aura.cache_metrics row — plain Go types at the package boundary instead of the sqlc pgtype wrappers.

type MetricParams

type MetricParams struct {
	ConversationID string
	Seq            int
	PromptTokens   int
	CachedTokens   int
	CostUSD        float64
}

MetricParams is the plain-Go input the Runner passes when persisting a turn's metrics. It mirrors the AppendTurn ergonomics in internal/conversations: callers work in native Go types and NewInsertParams handles the pgtype boundary conversion (Pitfall 5).

type Store

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

Store wraps a pgx pool and the generated Queries — the canonical shape from internal/identity / internal/conversations.

func New

func New(pool *pgxpool.Pool) *Store

New builds a Store over an open pool.

func (*Store) AggregateSince

func (s *Store) AggregateSince(ctx context.Context, since time.Time) (Aggregate, error)

AggregateSince sums prompt/cached tokens + cost over the ts >= since window (SQL-side aggregation; the parameterized since is bound, T-06-02).

func (*Store) Insert

func (s *Store) Insert(ctx context.Context, p sqlc.InsertCacheMetricParams) error

Insert appends one immutable cache-metric row for a completed assistant turn. The caller passes the already-computed sqlc.InsertCacheMetricParams (the Runner reuses the per-turn llm.Usage + cost it has in hand — no wire-path touch, D-02a).

func (*Store) ListSince

func (s *Store) ListSince(ctx context.Context, since time.Time) ([]Metric, error)

ListSince returns the metric rows with ts >= since, in ts ASC order (the query window is parameterized; since is bound, never interpolated — T-06-02).