core

Documentation

Overview

Package core defines the provider abstraction, wire format types, and capability metadata that form the foundation of the routing engine.

Index

• Variables
• func DenormalizeResponse(nr *NormalizedResponse) *types.MessageResponse
• func ValidateRequest(req *NormalizedRequest) error
• type ExecuteResult
• type NormalizedError
  • func (e *NormalizedError) Error() string
  • func (e *NormalizedError) IsRetryable() bool
• type NormalizedMessage
• type NormalizedRequest
  • func NormalizeRequest(anthropicReq *types.MessageRequest) *NormalizedRequest
• type NormalizedResponse
• type NormalizedToolCall
• type NormalizedToolDef
• type NormalizedToolResult
• type NormalizedUsage
• type Provider
• type ProviderCapabilities
• type ProviderRegistry
  • func NewProviderRegistry() *ProviderRegistry
  • func (r *ProviderRegistry) Get(name string) (Provider, bool)
  • func (r *ProviderRegistry) List() []string
  • func (r *ProviderRegistry) MustGet(name string) Provider
  • func (r *ProviderRegistry) Register(p Provider) error
• type WireFormat
  • func (w WireFormat) String() string

Variables

var (
	ErrModelNotFound         = errors.New("model not found")
	ErrProviderNotFound      = errors.New("provider not found")
	ErrUnsupportedCapability = errors.New("capability not supported by model")
	ErrRateLimited           = errors.New("rate limited by provider")
	ErrStreamIdle            = errors.New("upstream stream idle")
	ErrClientDisconnected    = errors.New("client disconnected")
)

Sentinel errors for common provider and routing failures.

Functions

func DenormalizeResponse

func DenormalizeResponse(nr *NormalizedResponse) *types.MessageResponse

DenormalizeResponse converts a NormalizedResponse to an Anthropic MessageResponse.

func ValidateRequest

func ValidateRequest(req *NormalizedRequest) error

ValidateRequest checks a NormalizedRequest for structural validity.

Types

type ExecuteResult

type ExecuteResult struct {
	Body    []byte
	ModelID string
	Latency time.Duration
}

ExecuteResult holds the result of a non-streaming provider call.

type NormalizedError

type NormalizedError struct {
	Kind       string // "api_error", "rate_limit", "invalid_request", etc.
	Message    string
	Retryable  bool
	StatusCode int
	Provider   string
	ModelID    string
}

NormalizedError wraps a provider error with structured context.

func (*NormalizedError) Error

func (e *NormalizedError) Error() string

Error implements the error interface.

func (*NormalizedError) IsRetryable

func (e *NormalizedError) IsRetryable() bool

IsRetryable returns true if the error is safe to retry with a fallback model.

type NormalizedMessage

type NormalizedMessage struct {
	Role        string                 // "user", "assistant", "system", "tool"
	Content     string                 // Concatenated text content
	ToolCalls   []NormalizedToolCall   // Present on assistant messages
	ToolResults []NormalizedToolResult // Present on user messages with tool results
	ToolCallID  string                 // Deprecated: use ToolResults instead. Kept for backward compat.
	Thinking    string                 // Reasoning/thinking content (assistant only)
}

NormalizedMessage is a single message in the internal canonical format. All wire formats (Anthropic, OpenAI, Responses, Gemini) map to and from this representation.

type NormalizedRequest

type NormalizedRequest struct {
	Model           string
	SystemPrompt    string
	Messages        []NormalizedMessage
	MaxTokens       int
	Temperature     *float64
	TopP            *float64
	Stream          bool
	Tools           []NormalizedToolDef
	ReasoningEffort string // "low", "medium", "high"
	ThinkingBudget  int    // budget_tokens for thinking mode
}

NormalizedRequest is the canonical internal request format.

func NormalizeRequest

func NormalizeRequest(anthropicReq *types.MessageRequest) *NormalizedRequest

NormalizeRequest converts an Anthropic MessageRequest to a NormalizedRequest. This is a lossless extraction: all data from the Anthropic format survives.

type NormalizedResponse

type NormalizedResponse struct {
	ID         string
	Model      string
	Messages   []NormalizedMessage
	StopReason string // "end_turn", "max_tokens", "tool_use"
	Usage      NormalizedUsage
}

NormalizedResponse is the canonical internal response format.

type NormalizedToolCall

type NormalizedToolCall struct {
	ID        string
	Name      string
	Arguments string // JSON string
}

NormalizedToolCall represents a tool invocation in the internal format.

type NormalizedToolDef

type NormalizedToolDef struct {
	Name        string
	Description string
	InputSchema []byte // JSON bytes of the schema
}

NormalizedToolDef is a tool definition in the internal format.

type NormalizedToolResult

type NormalizedToolResult struct {
	ToolCallID string
	Content    string
}

NormalizedToolResult represents a single tool result in the normalized format.

type NormalizedUsage

type NormalizedUsage struct {
	InputTokens         int
	OutputTokens        int
	CacheReadTokens     int
	CacheCreationTokens int
}

NormalizedUsage holds token counts in the internal format.

type Provider

type Provider interface {
	// Name returns the provider identifier (e.g. "opencode-go", "opencode-zen").
	Name() string

	// Capabilities returns provider-level capabilities.
	Capabilities() ProviderCapabilities

	// ModelCapabilities returns per-model capabilities. Returns false if the
	// model is unknown to this provider.
	ModelCapabilities(modelID string) (ProviderCapabilities, bool)

	// WireFormat returns the wire format for the given model on this provider.
	WireFormat(modelID string) WireFormat

	// Execute sends a non-streaming request and returns the response.
	Execute(ctx context.Context, req *NormalizedRequest, model config.ModelConfig) (*ExecuteResult, error)

	// Stream sends a streaming request and returns an io.ReadCloser for SSE
	// events. The stream emits raw SSE bytes; the handler is responsible for
	// forwarding them.
	Stream(ctx context.Context, req *NormalizedRequest, model config.ModelConfig) (io.ReadCloser, error)

	// RoundTripName returns the model ID to use in the upstream request. This
	// may differ from the config's ModelID (e.g. for model overrides).
	RoundTripName(model config.ModelConfig) string

	// StreamIdleTimeout returns the maximum gap between bytes on an active
	// stream before it is treated as stuck and aborted.
	StreamIdleTimeout(model config.ModelConfig) time.Duration
}

Provider is the abstraction for an upstream LLM provider.

type ProviderCapabilities

type ProviderCapabilities struct {
	SupportsStreaming  bool
	SupportsTools      bool
	SupportsThinking   bool
	SupportsImageInput bool
	MaxContextLength   int // in tokens
	DefaultMaxTokens   int
	KnownModels        []string
}

ProviderCapabilities describes what a provider can do at the provider level. Per-model refinements are returned by ModelCapabilities.

type ProviderRegistry

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

ProviderRegistry provides thread-safe access to registered providers.

func NewProviderRegistry

func NewProviderRegistry() *ProviderRegistry

NewProviderRegistry creates a new provider registry.

func (*ProviderRegistry) Get

func (r *ProviderRegistry) Get(name string) (Provider, bool)

Get retrieves a provider by name. Returns false if not found.

func (*ProviderRegistry) List

func (r *ProviderRegistry) List() []string

List returns all registered provider names.

func (*ProviderRegistry) MustGet

func (r *ProviderRegistry) MustGet(name string) Provider

MustGet retrieves a provider by name, panicking if missing.

func (*ProviderRegistry) Register

func (r *ProviderRegistry) Register(p Provider) error

Register adds a provider. Returns an error if the name is already registered.

type WireFormat

type WireFormat int

WireFormat describes the upstream API format a provider uses for a given model.

const (
	// WireFormatOpenAIChat is the OpenAI Chat Completions format (/v1/chat/completions).
	WireFormatOpenAIChat WireFormat = iota
	// WireFormatAnthropic is the Anthropic Messages format (/v1/messages).
	WireFormatAnthropic
	// WireFormatOpenAIResponses is the OpenAI Responses format (/v1/responses).
	WireFormatOpenAIResponses
	// WireFormatGemini is the Google Gemini format (/v1/models/{id}).
	WireFormatGemini
)

func (WireFormat) String

func (w WireFormat) String() string

String returns a human-readable name for the wire format.