provider

Documentation

Overview

Package provider defines the model-provider boundary used by SuperCode.

Index

• Constants
• Variables
• func ModelSelector(providerName, model string) string
• func NewBoundedResponseBody(body io.ReadCloser, limit int64) io.ReadCloser
• func RedactedError(prefix string, err error, secrets ...string) error
• func SecureHTTPClient(base *http.Client) *http.Client
• type HTTPDoer
  • func SecureHTTPDoer(next HTTPDoer) HTTPDoer
• type Image
• type Message
• type MessageRole
• type ModelInfo
• type ModelResolver
• type Provider
• type Request
  • func (r Request) Validate() error
• type Response
• type Route
• type Router
  • func NewRouter(routes []Route) (*Router, error)
  • func (r *Router) Generate(ctx context.Context, request Request) (Response, error)
  • func (r *Router) Models() []ModelInfo
  • func (r *Router) Resolve(selector string) (ModelInfo, error)
  • func (r *Router) ResolveModel(selector string) (ModelInfo, error)
  • func (r *Router) Stream(ctx context.Context, request Request) (Stream, error)
• type Stream
• type StreamEvent
• type StreamEventType
• type ToolCall
• type ToolDefinition
• type Usage

Constants

const MaxHTTPResponseBytes = int64(64 * 1024 * 1024)

Variables

var (
	ErrEmptyModel  = errors.New("model is required")
	ErrEmptyPrompt = errors.New("prompt is required")
)

var ErrHTTPResponseTooLarge = errors.New("provider response exceeds the 64 MiB limit")

Functions

func ModelSelector

func ModelSelector(providerName, model string) string

func NewBoundedResponseBody

func NewBoundedResponseBody(body io.ReadCloser, limit int64) io.ReadCloser

func RedactedError

func RedactedError(prefix string, err error, secrets ...string) error

func SecureHTTPClient

func SecureHTTPClient(base *http.Client) *http.Client

SecureHTTPClient bounds decompressed response bodies and rejects cross-origin redirects so API keys and custom authentication headers cannot be forwarded to a different endpoint. The returned client is an independent shallow copy.

Types

type HTTPDoer

type HTTPDoer interface {
	Do(*http.Request) (*http.Response, error)
}

func SecureHTTPDoer

func SecureHTTPDoer(next HTTPDoer) HTTPDoer

SecureHTTPDoer adds the response-body boundary to SDK-specific clients. A concrete *http.Client should be passed through SecureHTTPClient as well so redirect policy can be enforced before the request is followed.

type Image

type Image struct {
	MIMEType string `json:"mime_type"`
	Data     string `json:"data,omitempty"`
	Detail   string `json:"detail,omitempty"`
	// Ref is a session-store relative asset path. Provider adapters receive
	// hydrated Data; they never need to understand this persistence detail.
	Ref string `json:"ref,omitempty"`
}

Image is an inline image returned by a tool or supplied by a user. Data is base64 without a data-URL prefix so persistence remains provider neutral.

type Message

type Message struct {
	Role       MessageRole `json:"role"`
	Content    string      `json:"content,omitempty"`
	ToolCalls  []ToolCall  `json:"tool_calls,omitempty"`
	ToolCallID string      `json:"tool_call_id,omitempty"`
	Images     []Image     `json:"images,omitempty"`
}

Message is a provider-neutral conversation message.

type MessageRole

type MessageRole string

MessageRole identifies a portable conversation message role.

const (
	MessageRoleUser      MessageRole = "user"
	MessageRoleAssistant MessageRole = "assistant"
	MessageRoleTool      MessageRole = "tool"
)

type ModelInfo

type ModelInfo struct {
	Selector string
	ID       string
	Provider string
}

ModelInfo identifies one configured model without exposing adapter-specific types. Selector is the stable value used by sessions and requests; ID is the model name sent to the remote provider.

type ModelResolver

type ModelResolver interface {
	ResolveModel(string) (ModelInfo, error)
}

ModelResolver canonicalizes user-facing model IDs when a provider routes across multiple named endpoints.

type Provider

type Provider interface {
	Generate(ctx context.Context, request Request) (Response, error)
	Stream(ctx context.Context, request Request) (Stream, error)
}

Provider supports both collected and streaming generation. Future providers implement this interface without leaking their SDK types into the application.

type Request

type Request struct {
	Model        string
	Instructions string
	Prompt       string
	// History contains completed user and assistant messages from previous
	// turns. The current Prompt is appended by the provider adapter.
	History           []Message
	Tools             []ToolDefinition
	Images            []Image
	ReasoningEffort   string
	ServiceTier       string
	ParallelToolCalls *bool
}

Request is the smallest provider-neutral request needed by the first SuperCode version. Provider-specific options must stay in provider adapters.

func (Request) Validate

func (r Request) Validate() error

Validate checks fields required by every provider.

type Response

type Response struct {
	ID           string
	Model        string
	Text         string
	ToolCalls    []ToolCall
	FinishReason string
	Usage        Usage
}

Response is the provider-neutral result returned to the application.

type Route

type Route struct {
	Name     string
	Models   []string
	Provider Provider
}

Route binds a named configured endpoint to its provider implementation. An empty Models list makes the route a legacy catch-all route.

type Router

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

Router dispatches provider-neutral requests by their configured model selector. Qualified selectors use the stable "provider/model" form.

func NewRouter

func NewRouter(routes []Route) (*Router, error)

func (*Router) Generate

func (r *Router) Generate(ctx context.Context, request Request) (Response, error)

func (*Router) Models

func (r *Router) Models() []ModelInfo

func (*Router) Resolve

func (r *Router) Resolve(selector string) (ModelInfo, error)

func (*Router) ResolveModel

func (r *Router) ResolveModel(selector string) (ModelInfo, error)

func (*Router) Stream

func (r *Router) Stream(ctx context.Context, request Request) (Stream, error)

type Stream

type Stream interface {
	Next() bool
	Current() StreamEvent
	Err() error
	Close() error
}

Stream is a pull-based provider-neutral response stream.

type StreamEvent

type StreamEvent struct {
	Type     StreamEventType
	Delta    string
	Response *Response
}

StreamEvent contains either a text delta or the final response.

type StreamEventType

type StreamEventType string

StreamEventType identifies a provider-neutral streaming event.

const (
	StreamEventTextDelta StreamEventType = "text_delta"
	StreamEventCompleted StreamEventType = "completed"
)

type ToolCall

type ToolCall struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

ToolCall is a provider-neutral function call requested by a model.

type ToolDefinition

type ToolDefinition struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Parameters  json.RawMessage `json:"parameters"`
}

ToolDefinition describes a model-callable tool without exposing provider SDK types to the agent runtime.

type Usage

type Usage struct {
	InputTokens  int64
	OutputTokens int64
	TotalTokens  int64
}

Usage contains the portable token counters exposed by model providers.