llm

package
v0.0.9 Latest Latest
Warning

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

 Go to latest Published: Feb 17, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func PurposeFrom 

func PurposeFrom(ctx context.Context) string

PurposeFrom extracts the purpose label from the context.

func WithPurpose 

func WithPurpose(ctx context.Context, purpose string) context.Context

WithPurpose attaches a purpose label to the context for event logging.

Types

type AnthropicConfig 

type AnthropicConfig struct {
	APIKey string
	Model  string // Default: "claude-haiku"
}

AnthropicConfig holds Anthropic-specific configuration.

type AnthropicProvider 

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

AnthropicProvider implements Provider using the Anthropic SDK.

func NewAnthropicProvider 

func NewAnthropicProvider(cfg AnthropicConfig) (*AnthropicProvider, error)

NewAnthropicProvider creates a new Anthropic provider.

func (*AnthropicProvider) Generate 

func (p *AnthropicProvider) Generate(ctx context.Context, req Request) (*Response, error)

func (*AnthropicProvider) ModelID 

func (p *AnthropicProvider) ModelID() string

type Config 

type Config struct {
	// Provider selects which LLM provider to use.
	// Values: "anthropic", "openai", "gemini", "openrouter", "mock"
	Provider string

	Anthropic  AnthropicConfig
	OpenAI     OpenAIConfig
	Gemini     GeminiConfig
	OpenRouter OpenRouterConfig
	Retry      RetryConfig

	// Timeout is the maximum duration for a single LLM request
	// (including retries). Default: 30s.
	Timeout time.Duration
}

Config holds all LLM provider configuration.

func ConfigFromEnv 

func ConfigFromEnv() Config

ConfigFromEnv builds a Config from environment variables, falling back to defaults for unset values.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults.

func DiscoverConfig 

func DiscoverConfig() (Config, bool)

DiscoverConfig probes standard API key env vars in priority order (Gemini → OpenAI → Anthropic) and returns a Config for the first provider whose key is found. Returns (Config{}, false) if none found.

func (Config) Validate 

func (c Config) Validate() error

Validate checks that the selected provider has its required API key set.

type ErrInvalidResponse 

type ErrInvalidResponse struct {
	Content json.RawMessage
	Err     error
}

ErrInvalidResponse indicates the LLM returned content that does not conform to the requested schema.

func (*ErrInvalidResponse) Error 

func (e *ErrInvalidResponse) Error() string

func (*ErrInvalidResponse) Unwrap 

func (e *ErrInvalidResponse) Unwrap() error

type ErrMaxTokensExceeded 

type ErrMaxTokensExceeded struct {
	Content json.RawMessage
}

ErrMaxTokensExceeded indicates the response was truncated because it hit the MaxTokens limit.

func (*ErrMaxTokensExceeded) Error 

func (e *ErrMaxTokensExceeded) Error() string

type ErrProviderUnavailable 

type ErrProviderUnavailable struct {
	Err error
}

ErrProviderUnavailable indicates the provider is down or unreachable.

func (*ErrProviderUnavailable) Error 

func (e *ErrProviderUnavailable) Error() string

func (*ErrProviderUnavailable) Unwrap 

func (e *ErrProviderUnavailable) Unwrap() error

type ErrRateLimit 

type ErrRateLimit struct {
	RetryAfter time.Duration
	Err        error
}

ErrRateLimit indicates the provider returned a rate limit error (429).

func (*ErrRateLimit) Error 

func (e *ErrRateLimit) Error() string

func (*ErrRateLimit) Unwrap 

func (e *ErrRateLimit) Unwrap() error

type GeminiConfig 

type GeminiConfig struct {
	APIKey string
	Model  string // Default: "gemini-flash"
}

GeminiConfig holds Gemini-specific configuration.

type GeminiProvider 

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

GeminiProvider implements Provider using the Google Gemini SDK.

func NewGeminiProvider 

func NewGeminiProvider(ctx context.Context, cfg GeminiConfig) (*GeminiProvider, error)

NewGeminiProvider creates a new Gemini provider.

func (*GeminiProvider) Generate 

func (p *GeminiProvider) Generate(ctx context.Context, req Request) (*Response, error)

func (*GeminiProvider) ModelID 

func (p *GeminiProvider) ModelID() string

type LoggingProvider 

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

LoggingProvider is a decorator that records every LLM request as an event.

func (*LoggingProvider) Generate 

func (l *LoggingProvider) Generate(ctx context.Context, req Request) (*Response, error)

func (*LoggingProvider) ModelID 

func (l *LoggingProvider) ModelID() string

type Message 

type Message struct {
	Role    Role
	Content string
}

Message represents a single message in the conversation.

type MockProvider 

type MockProvider struct {
	Calls []Request
	// contains filtered or unexported fields
}

MockProvider is a deterministic Provider for testing. It returns canned responses in FIFO order and records all requests.

func NewMockProvider 

func NewMockProvider(responses ...MockResponse) *MockProvider

NewMockProvider creates a MockProvider with the given canned responses.

func (*MockProvider) AddResponse 

func (m *MockProvider) AddResponse(resp MockResponse)

AddResponse appends a canned response to the queue.

func (*MockProvider) CallCount 

func (m *MockProvider) CallCount() int

CallCount returns the number of Generate calls made.

func (*MockProvider) Generate 

func (m *MockProvider) Generate(_ context.Context, req Request) (*Response, error)

Generate returns the next canned response or ErrProviderUnavailable if the queue is empty.

func (*MockProvider) ModelID 

func (m *MockProvider) ModelID() string

ModelID returns "mock".

type MockResponse 

type MockResponse struct {
	Content json.RawMessage
	Usage   Usage
	Err     error
}

MockResponse is a canned response for the MockProvider.

type ModelCost 

type ModelCost struct {
	InputPerMTok  float64 // USD per 1M input tokens
	OutputPerMTok float64 // USD per 1M output tokens
}

ModelCost holds per-million-token pricing for a model. Prices are in USD per 1 million tokens, sourced from models.dev.

func LookupCost 

func LookupCost(modelID string) *ModelCost

LookupCost returns the pricing for a model ID, or nil if unknown.

func (ModelCost) Cost 

func (c ModelCost) Cost(inputTokens, outputTokens int) float64

Cost calculates the total USD cost for the given token counts.

type OpenAIConfig 

type OpenAIConfig struct {
	APIKey  string
	Model   string // Default: "gpt-4o-mini"
	BaseURL string // Optional. Override for OpenRouter or compatible APIs.
}

OpenAIConfig holds OpenAI-specific configuration.

type OpenAIProvider 

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

OpenAIProvider implements Provider using the OpenAI SDK. It also supports OpenRouter and other OpenAI-compatible APIs via BaseURL.

func NewOpenAIProvider 

func NewOpenAIProvider(cfg OpenAIConfig) (*OpenAIProvider, error)

NewOpenAIProvider creates a new OpenAI provider.

func (*OpenAIProvider) Generate 

func (p *OpenAIProvider) Generate(ctx context.Context, req Request) (*Response, error)

func (*OpenAIProvider) ModelID 

func (p *OpenAIProvider) ModelID() string

type OpenRouterConfig added in v0.0.4 

type OpenRouterConfig struct {
	APIKey  string
	Model   string // Default: "google/gemini-2.0-flash-exp"
	BaseURL string // Default: "https://openrouter.ai/api/v1"
}

OpenRouterConfig holds OpenRouter-specific configuration.

type OpenRouterProvider added in v0.0.4 

type OpenRouterProvider struct {
	*OpenAIProvider
}

OpenRouterProvider wraps OpenAIProvider with OpenRouter-specific defaults. OpenRouter exposes an OpenAI-compatible API, so the underlying SDK is reused.

func NewOpenRouterProvider added in v0.0.4 

func NewOpenRouterProvider(cfg OpenRouterConfig) (*OpenRouterProvider, error)

NewOpenRouterProvider creates a provider targeting the OpenRouter API.

type Provider 

type Provider interface {
	// Generate sends a prompt to the LLM and returns a structured response.
	// The request's Schema field, when set, instructs the provider to return
	// JSON conforming to that schema. The response Content will be the
	// validated JSON.
	Generate(ctx context.Context, req Request) (*Response, error)

	// ModelID returns the model identifier this provider is configured to use.
	ModelID() string
}

Provider is the core abstraction for LLM interaction. Consumers call Generate with a Request and receive structured JSON.

func NewProvider 

func NewProvider(ctx context.Context, cfg Config, eventRepo store.EventRepo) (Provider, error)

NewProvider creates a Provider from configuration. It returns the provider wrapped with retry and logging middleware.

func NewProviderFromEnv 

func NewProviderFromEnv(ctx context.Context, eventRepo store.EventRepo) (Provider, error)

NewProviderFromEnv auto-discovers LLM credentials from standard env vars (GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY) and creates a fully decorated provider. Returns an error if no credentials are found.

func WithLogging 

func WithLogging(p Provider, repo store.EventRepo, providerName string) Provider

WithLogging wraps a Provider with event logging.

func WithRetry 

func WithRetry(p Provider, cfg RetryConfig) Provider

WithRetry wraps a Provider with retry logic.

type Request 

type Request struct {
	// System is the system prompt. Sets the LLM's role and constraints.
	System string

	// Messages is the conversation history. For single-turn generation
	// (the common case in Mathiz), this contains one user message.
	Messages []Message

	// Schema is the JSON Schema the response must conform to.
	// When set, the provider uses its native structured output mechanism.
	// When nil, the response Content is raw text as json.RawMessage.
	Schema *Schema

	// MaxTokens is the maximum number of tokens in the response.
	MaxTokens int

	// Temperature controls randomness. Range: 0.0 - 1.0.
	// Default: 0.0 (deterministic) when not set.
	Temperature float64
}

Request describes what to send to the LLM.

type Response 

type Response struct {
	// Content is the generated output. When a Schema was provided in the
	// request, this is the validated JSON object. When no Schema was
	// provided, this is the raw text response wrapped as a JSON string.
	Content json.RawMessage

	// Usage reports token consumption for this request.
	Usage Usage

	// Model is the actual model that served the request.
	Model string

	// StopReason indicates why generation stopped.
	// Normalized to: "end", "max_tokens", "error"
	StopReason string
}

Response holds the LLM's output.

type RetryConfig 

type RetryConfig struct {
	MaxAttempts int
	InitialWait time.Duration
	MaxWait     time.Duration
	Multiplier  float64
}

RetryConfig configures retry behavior for transient failures.

type RetryProvider 

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

RetryProvider is a decorator that retries transient errors with exponential backoff and jitter.

func (*RetryProvider) Generate 

func (r *RetryProvider) Generate(ctx context.Context, req Request) (*Response, error)

func (*RetryProvider) ModelID 

func (r *RetryProvider) ModelID() string

type Role 

type Role string

Role is the message sender role. 

const (
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
)

type Schema 

type Schema struct {
	// Name identifies this schema (used as tool name for Anthropic,
	// schema name for OpenAI). Kebab-case, e.g. "math-question".
	Name string

	// Description is a human-readable description of what this schema
	// represents. Sent to the LLM to guide generation.
	Description string

	// Definition is the JSON Schema definition as a map.
	Definition map[string]any
}

Schema defines the JSON structure expected from the LLM.

type Usage 

type Usage struct {
	InputTokens  int
	OutputTokens int
	TotalTokens  int
}

Usage tracks token consumption for a single request.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.