Documentation
¶
Overview ¶
Package ai hosts the hot-swappable LLM provider adapters (OpenAI, Anthropic, Google Gemini) used across Rivolt: weekly digest, trip planning, charging strategy, and anomaly explanations.
The code in this file is provider-agnostic. Domain features (digest, planner, coach) live in their own files and build on top of Provider.
Anthropic Claude provider on the official Go SDK.
Docs: https://docs.anthropic.com/en/api/messages
Google Gemini generateContent API provider.
Docs: https://ai.google.dev/api/generate-content
Model listing helpers — one per provider. Each returns the set of model IDs that can serve generateContent / chat completions, so the UI can offer a dropdown instead of asking the operator to type a model name.
These are plain functions (not methods on *Provider) because the settings UI needs to list models even when the selected model would otherwise be invalid — we don't want to construct a full provider just to list.
OpenAI Chat Completions provider. No SDK — one tiny HTTP call keeps the dependency surface small and makes auditing trivial.
Index ¶
- Constants
- Variables
- func ComputeCost(provider, model string, inTokens, outTokens int64) float64
- func ListAnthropicModels(ctx context.Context, apiKey string) ([]string, error)
- func ListGeminiModels(ctx context.Context, apiKey string) ([]string, error)
- func ListOpenAIModels(ctx context.Context, apiKey string) ([]string, error)
- func OperatorCostUSD(u OperatorUsage) float64
- func Reserved(ctx context.Context) bool
- func ServedModelLabel(model string) string
- func SplitModelName(name string) (provider, model string)
- func WithReservation(ctx context.Context) context.Context
- func WithRoute(ctx context.Context, r Route) context.Context
- func WithTaste(ctx context.Context, t Taste) context.Context
- func WithUnmetered(ctx context.Context) context.Context
- type Analyzer
- type AnthropicConfig
- type AnthropicProvider
- type CostBreak
- type GeminiConfig
- type GeminiProvider
- type OpenAIConfig
- type OpenAIProvider
- type OperatorObserver
- type OperatorUsage
- type Provider
- type Record
- type Recorder
- type Route
- type Taste
- type TokenUsage
- type UsageSummary
Constants ¶
const OperatorModel = "claude-opus-5-5"
OperatorModel is the model the operator key runs on. Users' own keys keep whatever model they have configured.
Variables ¶
var ( // ErrRefused means the model declined the request (stop_reason refusal). // The message is safe to show; callers must not retry. ErrRefused = errors.New("AI unavailable for this request") // ErrTruncated means the answer hit max_tokens, so any JSON in it is cut. ErrTruncated = errors.New("AI answer was cut off before it finished") // ErrOperatorDenied means the operator key was asked to spend without a // reserved budget unit. ErrOperatorDenied = errors.New("AI unavailable: no budget reserved for this request") )
var ( // ErrTasteUsed means the account has taken this month's free answers. ErrTasteUsed = errors.New("AI free taste used up for this month") // ErrTasteCeiling means the install-wide daily ceiling on free-taste spend is reached. ErrTasteCeiling = errors.New("AI free taste unavailable until tomorrow") )
Functions ¶
func ComputeCost ¶
ComputeCost returns the USD cost of a call using real token counts and the provider's published per-1M-token price. Unknown models fall back to a conservative rate so the dashboard shows *something*.
func ListAnthropicModels ¶
ListAnthropicModels returns every model the Anthropic Messages API advertises. All of them support messages, so no client-side filtering.
func ListGeminiModels ¶
ListGeminiModels returns the Gemini models that support generateContent, with the "models/" prefix stripped. Gemma and preview-only variants are included too — the user can pick, we don't gatekeep.
func ListOpenAIModels ¶
ListOpenAIModels returns the subset of OpenAI models usable with chat completions. We filter client-side since /v1/models returns every model including embeddings, moderation, TTS, etc.
func OperatorCostUSD ¶ added in v0.41.13
func OperatorCostUSD(u OperatorUsage) float64
OperatorCostUSD prices one model hop at the model that served it: cache reads at 0.1x and cache writes at 1.25x of that model's input rate.
func Reserved ¶ added in v0.41.13
Reserved reports whether ctx carries a budget reservation (see WithReservation).
func ServedModelLabel ¶ added in v0.41.13
ServedModelLabel maps the model id a response reports to a fixed label set so the metric's cardinality stays bounded.
func SplitModelName ¶
SplitModelName decomposes a Provider.Name() result (e.g. "anthropic:claude-haiku-4-5") into provider and model. Unknown shapes return (name, "").
func WithReservation ¶ added in v0.41.13
WithReservation marks ctx as carrying a reserved unit of the per-user daily AI budget for a user who has consented to AI. Only the operator key checks it: a call on the operator's money without a reservation is refused, so a background job or a route that forgot the budget gate never spends it.
Types ¶
type Analyzer ¶
type Analyzer struct {
// contains filtered or unexported fields
}
Analyzer wraps a Provider. It exists so call sites can hot-swap the backing provider without plumbing the raw Provider through every handler. Settings manager owns the single *Analyzer instance and rebuilds it when the operator changes API key / provider / model.
func NewAnalyzer ¶
NewAnalyzer returns an analyzer backed by p. p must be non-nil; the settings manager guards against that before calling.
func (*Analyzer) Complete ¶
Complete is a convenience passthrough so domain code doesn't have to reach into Provider directly.
type AnthropicConfig ¶
type AnthropicConfig struct {
APIKey string // required
Model string // default claude-haiku-4-5-20251001
BaseURL string // tests only; empty uses the SDK default
// Operator marks the key as the operator's: calls need a reserved budget
// unit, the system prompt is cached, and Observe sees every hop's usage.
Operator bool
Observe OperatorObserver
// ForceEffort sends the route's effort even for a model outside the modelFeatures allowlist. For the
// `rivolt ai-eval` side-by-side run only: a model that rejects the parameter answers 400.
ForceEffort bool
}
AnthropicConfig configures the provider.
type AnthropicProvider ¶
type AnthropicProvider struct {
// contains filtered or unexported fields
}
AnthropicProvider calls the Anthropic Messages API through the official SDK.
func NewAnthropic ¶
func NewAnthropic(cfg AnthropicConfig) (*AnthropicProvider, error)
NewAnthropic constructs a provider. Returns an error if no API key is set.
func (*AnthropicProvider) Complete ¶
func (p *AnthropicProvider) Complete(ctx context.Context, system, user string) (string, TokenUsage, error)
Complete sends a system+user prompt pair and returns the assistant text along with real token usage from the response.
func (*AnthropicProvider) Name ¶
func (p *AnthropicProvider) Name() string
Name reports a stable identifier for cache keying.
type CostBreak ¶
type CostBreak struct {
Calls int `json:"calls"`
InputTokens int64 `json:"input_tokens"`
OutputTokens int64 `json:"output_tokens"`
CostUSD float64 `json:"cost_usd"`
LastUsedUnix int64 `json:"last_used_unix,omitempty"`
}
CostBreak is the per-slice rollup shown in the dashboard.
type GeminiConfig ¶
type GeminiConfig struct {
APIKey string // required
Model string // default "gemini-1.5-flash"
Endpoint string // v1beta base URL; default official endpoint
Timeout time.Duration
}
GeminiConfig configures the provider.
type GeminiProvider ¶
type GeminiProvider struct {
// contains filtered or unexported fields
}
GeminiProvider calls the Google Generative Language API.
func NewGemini ¶
func NewGemini(cfg GeminiConfig) (*GeminiProvider, error)
NewGemini constructs a provider. Returns an error if no API key is set.
func (*GeminiProvider) Complete ¶
func (p *GeminiProvider) Complete(ctx context.Context, system, user string) (string, TokenUsage, error)
Complete sends the prompt pair and returns the assistant text along with real token usage from the response.
Gemini has no separate "system" role; we fold it into the request as system_instruction which is the documented equivalent.
func (*GeminiProvider) Name ¶
func (p *GeminiProvider) Name() string
Name reports a stable identifier for cache keying.
type OpenAIConfig ¶
type OpenAIConfig struct {
APIKey string // required
Model string // default "gpt-4o-mini"
Endpoint string // default official OpenAI chat endpoint
Timeout time.Duration
}
OpenAIConfig configures the provider. Zero values pick sensible defaults.
type OpenAIProvider ¶
type OpenAIProvider struct {
// contains filtered or unexported fields
}
OpenAIProvider calls the OpenAI Chat Completions API.
func NewOpenAI ¶
func NewOpenAI(cfg OpenAIConfig) (*OpenAIProvider, error)
NewOpenAI constructs a provider. Returns an error if no API key is set.
func (*OpenAIProvider) Complete ¶
func (p *OpenAIProvider) Complete(ctx context.Context, system, user string) (string, TokenUsage, error)
Complete sends a system+user prompt pair and returns the assistant text along with real token usage from the response.
func (*OpenAIProvider) Name ¶
func (p *OpenAIProvider) Name() string
Name reports a stable identifier for cache keying.
type OperatorObserver ¶ added in v0.41.13
type OperatorObserver func(OperatorUsage)
OperatorObserver receives the usage of every operator-key call.
type OperatorUsage ¶ added in v0.41.13
type OperatorUsage struct {
Route Route
Model string // fixed set, see ServedModelLabel
Input int64 // uncached input tokens
Output int64
CacheRead int64
CacheWrite int64
}
OperatorUsage is one model hop of an operator-key call, for metrics. Counts only; no prompt or answer text.
type Provider ¶
type Provider interface {
// Complete sends a system+user prompt pair and returns the assistant
// text along with real token usage parsed from the provider response.
// Implementations MUST return usage whenever the API gives it to them;
// a zero-valued TokenUsage is only acceptable when the upstream
// response omitted the counts (fall back to zeros, never estimate).
Complete(ctx context.Context, system, user string) (string, TokenUsage, error)
// Name returns a short identifier (e.g. "openai:gpt-4o-mini") used
// for cache keys and usage accounting. Changing model invalidates
// downstream caches automatically.
Name() string
}
Provider is the minimal contract every LLM backend must implement.
type Record ¶
type Record struct {
Time time.Time
Provider string // openai, anthropic, gemini
Model string // gpt-4o-mini, claude-haiku-4-5, ...
Feature string // analyze, coach, compare, digest, ask, name, transcribe, image
InputTokens int64
OutputTokens int64
DurationMs int64
ShotID string
OK bool
Err string
}
Record is the event we log for each LLM call.
type Recorder ¶
type Recorder struct {
// contains filtered or unexported fields
}
Recorder persists AI call metadata to SQLite.
func NewRecorder ¶
NewRecorder wires a Recorder to an already-open *sql.DB (we reuse the shots database to avoid a second file).
type Route ¶ added in v0.41.13
type Route string
Route names the feature a Complete call serves. It picks the effort and the max_tokens, and labels the operator token counter. Callers set it with WithRoute; an unset route is RouteOther.
type Taste ¶ added in v0.41.20
type Taste interface {
// Take reserves one unit before the call. Any error refuses the call: ErrTasteUsed and ErrTasteCeiling are the expected
// ones, anything else means the store could not answer and the operator key stays closed.
Take(ctx context.Context) error
// Refund gives the unit back after a provider failure (not after an answer, a refusal or a cut-off one).
Refund(ctx context.Context)
// Spent reports what the call cost the operator, in dollars.
Spent(ctx context.Context, usd float64)
}
Taste is the metering a free account's operator-key call goes through: a few answers a month on the operator's money. The provider takes it just before the model call, so a cached answer, a page load and a refused request never spend one.
var NoTaste Taste = noTaste{}
NoTaste is the metering of an account that is not on the free taste: Pro (within its daily cap), the admin ping and the model evaluation.
type TokenUsage ¶
type TokenUsage struct {
InputTokens int64 `json:"input_tokens"`
OutputTokens int64 `json:"output_tokens"`
}
TokenUsage is the real input/output token count reported by a provider for a single call. Zero values mean the provider didn't report counts.
type UsageSummary ¶
type UsageSummary struct {
Since time.Time `json:"since"`
TotalCalls int `json:"total_calls"`
TotalCostUSD float64 `json:"total_cost_usd"`
ByProvider map[string]CostBreak `json:"by_provider"`
ByFeature map[string]CostBreak `json:"by_feature"`
ByModel map[string]CostBreak `json:"by_model"`
Recent []Record `json:"recent"` // newest first
}
UsageSummary aggregates recent activity for the dashboard.