ai

package
v0.41.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 15 Imported by: 0

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

View Source
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

View Source
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")
)
View Source
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

func ComputeCost(provider, model string, inTokens, outTokens int64) float64

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

func ListAnthropicModels(ctx context.Context, apiKey string) ([]string, error)

ListAnthropicModels returns every model the Anthropic Messages API advertises. All of them support messages, so no client-side filtering.

func ListGeminiModels

func ListGeminiModels(ctx context.Context, apiKey string) ([]string, error)

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

func ListOpenAIModels(ctx context.Context, apiKey string) ([]string, error)

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

func Reserved(ctx context.Context) bool

Reserved reports whether ctx carries a budget reservation (see WithReservation).

func ServedModelLabel added in v0.41.13

func ServedModelLabel(model string) string

ServedModelLabel maps the model id a response reports to a fixed label set so the metric's cardinality stays bounded.

func SplitModelName

func SplitModelName(name string) (provider, model string)

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

func WithReservation(ctx context.Context) context.Context

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.

func WithRoute added in v0.41.13

func WithRoute(ctx context.Context, r Route) context.Context

WithRoute tags ctx with the route of the call about to be made.

func WithTaste added in v0.41.20

func WithTaste(ctx context.Context, t Taste) context.Context

WithTaste marks ctx with the metering the operator key applies. Without a Taste on ctx the operator key refuses the call (ErrOperatorDenied): a route that forgot it fails closed.

func WithUnmetered added in v0.41.20

func WithUnmetered(ctx context.Context) context.Context

WithUnmetered marks ctx as carrying a budget reservation and no taste metering.

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

func NewAnalyzer(p Provider) *Analyzer

NewAnalyzer returns an analyzer backed by p. p must be non-nil; the settings manager guards against that before calling.

func (*Analyzer) Complete

func (a *Analyzer) Complete(ctx context.Context, system, user string) (string, TokenUsage, error)

Complete is a convenience passthrough so domain code doesn't have to reach into Provider directly.

func (*Analyzer) ModelName

func (a *Analyzer) ModelName() string

ModelName is the "provider:model" short identifier used in logs.

func (*Analyzer) Provider

func (a *Analyzer) Provider() Provider

Provider returns the underlying Provider so callers that need full control (custom prompts, streaming) can reach through.

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

func NewRecorder(db *sql.DB) (*Recorder, error)

NewRecorder wires a Recorder to an already-open *sql.DB (we reuse the shots database to avoid a second file).

func (*Recorder) Record

func (r *Recorder) Record(ctx context.Context, rec Record)

Record stores a single call. Failures in the recorder are logged but never bubble up — we don't want telemetry to break user-facing flows.

func (*Recorder) Summarize

func (r *Recorder) Summarize(ctx context.Context, days, recent int) (*UsageSummary, error)

Summarize returns rollups for the last `days` days plus the N most recent raw records. `days<=0` means "all time".

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.

const (
	RouteRecap      Route = "recap"
	RouteEfficiency Route = "efficiency"
	RouteAdvice     Route = "advice"
	RoutePing       Route = "ping"
	RouteOther      Route = "other"
)

func RouteFrom added in v0.41.13

func RouteFrom(ctx context.Context) Route

RouteFrom returns the route on ctx, or 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.

func TasteFrom added in v0.41.20

func TasteFrom(ctx context.Context) (Taste, bool)

TasteFrom returns the Taste on ctx.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL