provider

Documentation

Overview

Package provider implements provider-specific LLM HTTP clients and wire-format adapters.

Index

• Constants
• func AnthropicToolsFromDefinitions(definitions []llm.ToolDefinition, oauth bool) []map[string]any
• func OpenAIChatToolsFromDefinitions(definitions []llm.ToolDefinition) []map[string]any
• func ResponseToolsFromDefinitions(definitions []llm.ToolDefinition) []map[string]any
• type Completer
• type CompletionRequest
• type ErrorDetails
• type HTTPCompletionClient
  • func NewHTTPCompletionClient() *HTTPCompletionClient
  • func (client *HTTPCompletionClient) Complete(ctx context.Context, request *CompletionRequest) (*llm.Response, error)
  • func (client *HTTPCompletionClient) Generate(ctx context.Context, request *llm.Request) (*llm.Response, error)
• type HookInput
• type HookOutput
• type RequestShape
  • func (shape *RequestShape) Payload() map[string]any
• type StatusError
  • func (err *StatusError) Error() string
  • func (err *StatusError) Unwrap() error
• type StreamEvent
• type StreamEventKind
• type ToolCall
• type ToolEvent

Constants

const (

	// ProviderCodeContextKey identifies a provider error code in structured error context.
	ProviderCodeContextKey = "provider_code"
	// ProviderTypeContextKey identifies a provider error type in structured error context.
	ProviderTypeContextKey = "provider_type"
	// ProviderRequestIDContextKey identifies a provider request ID in structured error context.
	ProviderRequestIDContextKey = "provider_request_id"
	// ProviderResponseIDContextKey identifies a provider response ID in structured error context.
	ProviderResponseIDContextKey = "provider_response_id"
	// ProviderParamContextKey identifies the provider request parameter associated with an error.
	ProviderParamContextKey = "provider_param"
	// ProviderBodyPreviewContextKey identifies a bounded provider response-body preview.
	ProviderBodyPreviewContextKey = "body_preview"
	// ProviderBodyTruncatedContextKey reports whether a provider response-body preview was truncated.
	ProviderBodyTruncatedContextKey = "body_truncated"
	// ProviderRequestShapeContextKey identifies safe request-shape diagnostics.
	ProviderRequestShapeContextKey = "request_shape"
)

const (
	// MaxRetryAfter bounds provider-directed waits to avoid unbounded or overflowing delays.
	MaxRetryAfter = 5 * time.Minute
)

Functions

func AnthropicToolsFromDefinitions

func AnthropicToolsFromDefinitions(definitions []llm.ToolDefinition, oauth bool) []map[string]any

AnthropicToolsFromDefinitions returns Anthropic tool declarations for definitions.

func OpenAIChatToolsFromDefinitions

func OpenAIChatToolsFromDefinitions(definitions []llm.ToolDefinition) []map[string]any

OpenAIChatToolsFromDefinitions returns OpenAI Chat Completions tool declarations for definitions.

func ResponseToolsFromDefinitions

func ResponseToolsFromDefinitions(definitions []llm.ToolDefinition) []map[string]any

ResponseToolsFromDefinitions returns OpenAI Responses API tool declarations for definitions.

Types

type Completer

type Completer interface {
	Complete(ctx context.Context, request *CompletionRequest) (*llm.Response, error)
}

Completer talks to provider APIs.

type CompletionRequest

type CompletionRequest struct {
	OnProviderObserve  llm.ProviderObserver
	OnProviderResponse llm.ProviderResponseObserver
	OnProviderRequest  llm.ProviderRequestHook
	OnRoundCheckpoint  llm.RoundCheckpoint
	ExecuteTools       llm.ToolExecutor
	OnEvent            func(*llm.StreamChunk)
	Request            llm.Request
	ProviderAttempt    int
}

CompletionRequest describes one provider-neutral generation request plus runtime callbacks.

type ErrorDetails

type ErrorDetails struct {
	Message       string
	Type          string
	Code          string
	Param         string
	BodyPreview   string
	BodyTruncated bool
}

ErrorDetails contains safe, bounded provider error diagnostics.

type HTTPCompletionClient

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

HTTPCompletionClient is a small provider client for built-in API families.

func NewHTTPCompletionClient

func NewHTTPCompletionClient() *HTTPCompletionClient

NewHTTPCompletionClient creates an HTTP-backed completion client.

func (*HTTPCompletionClient) Complete

func (client *HTTPCompletionClient) Complete(
	ctx context.Context,
	request *CompletionRequest,
) (*llm.Response, error)

Complete sends a request to the selected provider.

func (*HTTPCompletionClient) Generate

func (client *HTTPCompletionClient) Generate(ctx context.Context, request *llm.Request) (*llm.Response, error)

Generate sends a provider-neutral request without runtime callbacks.

type HookInput

type HookInput struct {
	Payload map[string]any
	Headers map[string]string
	Attempt int
}

HookInput describes a provider request before it is sent.

type HookOutput

type HookOutput struct {
	Payload map[string]any
	Headers map[string]string
}

HookOutput describes the provider request after hook mutation.

type RequestShape

type RequestShape struct {
	Keys                    []string `json:"keys,omitempty"`
	ByteSize                int      `json:"byte_size,omitempty"`
	FunctionCallCount       int      `json:"function_call_count,omitempty"`
	FunctionCallOutputCount int      `json:"function_call_output_count,omitempty"`
	InputCount              int      `json:"input_count,omitempty"`
	KeyCount                int      `json:"key_count,omitempty"`
	MessageCount            int      `json:"message_count,omitempty"`
	ToolCount               int      `json:"tool_count,omitempty"`
	HasInclude              bool     `json:"has_include,omitempty"`
	HasParallelToolCalls    bool     `json:"has_parallel_tool_calls,omitempty"`
	HasPromptCacheKey       bool     `json:"has_prompt_cache_key,omitempty"`
	HasReasoning            bool     `json:"has_reasoning,omitempty"`
}

RequestShape contains safe, content-free metadata about an outbound provider request.

func (*RequestShape) Payload

func (shape *RequestShape) Payload() map[string]any

Payload returns the extension/lifecycle representation of the request shape.

type StatusError

type StatusError struct {
	Details *ErrorDetails

	RequestShape *RequestShape
	RequestID    string
	RetryAfter   time.Duration
	Status       int
	// contains filtered or unexported fields
}

StatusError is a typed, inspectable provider HTTP status error.

func (*StatusError) Error

func (err *StatusError) Error() string

func (*StatusError) Unwrap

func (err *StatusError) Unwrap() error

type StreamEvent

type StreamEvent struct {
	ToolEvent *ToolEvent      `json:"tool_event,omitempty"`
	Usage     *llm.Usage      `json:"usage,omitempty"`
	Kind      StreamEventKind `json:"kind"`
	Text      string          `json:"text,omitempty"`
}

StreamEvent is emitted while the provider client is producing a result.

type StreamEventKind

type StreamEventKind string

StreamEventKind identifies incremental provider/client activity.

const (
	// StreamEventTextDelta carries assistant text as it arrives.
	StreamEventTextDelta StreamEventKind = "text_delta"
	// StreamEventThinkingDelta carries model thinking/reasoning text as it arrives.
	StreamEventThinkingDelta StreamEventKind = "thinking_delta"
	// StreamEventToolStart announces a tool call before execution.
	StreamEventToolStart StreamEventKind = "tool_start"
	// StreamEventToolResult carries the completed tool call result.
	StreamEventToolResult StreamEventKind = "tool_result"
)

type ToolCall

type ToolCall struct {
	Metadata      map[string]any
	ArgumentsJSON string
	ID            string
	Name          string
	Arguments     tool.Arguments
}

ToolCall is a provider-returned local tool invocation.

type ToolEvent

type ToolEvent struct {
	Name          string
	ArgumentsJSON string
	DetailsJSON   string
	Result        string
	Error         string
	IsError       bool
}

ToolEvent captures one tool result for provider follow-up messages.