llm

type CallStat struct {
	// Purpose names what the call was for: a chat Purpose or an embed.Purpose,
	// which is why the field is a plain string.
	Purpose  string
	Identity Identity
	Usage    Usage
	// Items is the number of inputs in the call. Embedding batches set it so
	// throughput per item is derivable from Duration; chat calls leave it 0.
	Items    int
	Duration time.Duration
	// Error is the failure text when the call returned no result, empty on
	// success. Failures are recorded because a call that times out or errors
	// is exactly what a sink exists to make countable. Such a row carries no
	// tokens, and an identity only when the failure was attributed.
	Error string
}

type Error struct {
	Identity Identity
	Err      error
}

type Identity struct {
	Provider string
	Model    string
	// Variant is the behaviour-affecting configuration the model ran under —
	// a reasoning effort, a thinking budget — carried so calls at different
	// settings measure apart. Canonical form is comma-separated key=value in
	// sorted key order ("reasoning_effort=high"); empty at model defaults.
	//
	// The boundary is what the request carries, not what the setting means:
	// a value sent as its own field is a variant, a value inside the model
	// identifier is the model.
	Variant string
}

type Purpose string

type Request struct {
	Purpose Purpose
	// SystemPrompt is the stable prefix, cacheable by providers that can.
	SystemPrompt string
	// UserPrompt is the per-call variable part.
	UserPrompt string
}

type Result struct {
	Text string
	// Identity is required on success: what actually served this call.
	Identity Identity
	Usage    Usage
}

type Runner interface {
	Run(ctx context.Context, req Request) (Result, error)
}

type RunnerFunc func(context.Context, Request) (Result, error)

type StatsSink interface {
	RecordCall(ctx context.Context, stat CallStat)
}

type Usage struct {
	InputTokens       int
	OutputTokens      int
	CacheReadTokens   int
	CacheCreateTokens int
	CostUSD           float64
}