llm

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 Usage struct {
	InputTokens       int
	OutputTokens      int
	CacheReadTokens   int
	CacheCreateTokens int
	CostUSD           float64
}