llm

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 2, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	FinishReasonStop          = "stop"
	FinishReasonLength        = "length"
	FinishReasonToolCalls     = "tool_calls"
	FinishReasonContentFilter = "content_filter"
	FinishReasonError         = "error"
	FinishReasonOther         = "other"
)

Canonical finish reason values per unified spec section 3.8.

Variables

This section is empty.

Functions

func DataURI 

func DataURI(mimeType string, data []byte) string

func DefaultSleep 

func DefaultSleep(ctx context.Context, d time.Duration) error

func ErrorFromHTTPStatus 

func ErrorFromHTTPStatus(provider string, statusCode int, message string, raw any, retryAfter *time.Duration) error

func ExpandTilde 

func ExpandTilde(path string) string

func InferMimeTypeFromPath 

func InferMimeTypeFromPath(path string) string

func IsAuthenticationError 

func IsAuthenticationError(err error) bool

func IsLocalPath 

func IsLocalPath(s string) bool

func NewAbortError 

func NewAbortError(message string) error

func NewInvalidToolCallError 

func NewInvalidToolCallError(message string) error

func NewNetworkError 

func NewNetworkError(provider, message string) error

func NewNoObjectGeneratedError 

func NewNoObjectGeneratedError(message string, rawText string) error

func NewRequestTimeoutError 

func NewRequestTimeoutError(provider string, message string) error

NewRequestTimeoutError constructs a non-HTTP timeout error (e.g., context deadline exceeded) that matches the unified error hierarchy. These timeouts are not retried by default (spec).

func NewStreamError 

func NewStreamError(provider, message string) error

func NewUnsupportedToolChoiceError 

func NewUnsupportedToolChoiceError(provider, mode string) error

func ParseRetryAfter 

func ParseRetryAfter(v string, now time.Time) *time.Duration

ParseRetryAfter parses the Retry-After header value. Supported forms: - integer seconds - HTTP-date (RFC 7231)

func ParseSSE 

func ParseSSE(ctx context.Context, r io.Reader, fn func(ev SSEEvent) error) error

ParseSSE parses Server-Sent Events from r and invokes fn for each complete event. It handles "event:" and "data:" lines and emits an event on blank-line boundaries.

func RegisterEnvAdapterFactory 

func RegisterEnvAdapterFactory(factory EnvAdapterFactory)

RegisterEnvAdapterFactory registers a factory that can construct a ProviderAdapter from environment variables. Provider packages should call this from init().

func Retry 

func Retry[T any](ctx context.Context, policy RetryPolicy, sleep SleepFunc, randFloat func() float64, fn func() (T, error)) (T, error)

Retry runs fn and retries retryable errors with exponential backoff and jitter.

Semantics: - policy.MaxRetries is the number of retries (not counting the initial attempt). - Jitter is +/- 50% (factor in [0.5, 1.5]) per unified-llm-spec.md. - If err provides RetryAfter:

  • if RetryAfter <= policy.MaxDelay (or MaxDelay <= 0), it overrides calculated backoff.
  • if RetryAfter > policy.MaxDelay, Retry aborts immediately (no retry) per spec.

func SetDefaultClient 

func SetDefaultClient(c *Client)

SetDefaultClient sets the module-level default client and disables lazy env initialization.

func ValidateToolName 

func ValidateToolName(name string) error

Tool names must match the strict common subset across providers: [a-zA-Z][a-zA-Z0-9_]* with a max length of 64.

func WithTimeout 

func WithTimeout(ctx context.Context, d time.Duration) (context.Context, context.CancelFunc)

WithTimeout wraps ctx in a context with the given timeout. A zero or negative timeout returns the input context unchanged.

func WrapContextError 

func WrapContextError(provider string, err error) error

WrapContextError converts context cancellation/deadline errors into the SDK error hierarchy (AbortError/RequestTimeoutError). Other errors are returned unchanged.

Types

type AbortError 

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

func (*AbortError) Error 

func (e *AbortError) Error() string

func (*AbortError) Provider 

func (e *AbortError) Provider() string

func (*AbortError) RetryAfter 

func (e *AbortError) RetryAfter() *time.Duration

func (*AbortError) Retryable 

func (e *AbortError) Retryable() bool

func (*AbortError) StatusCode 

func (e *AbortError) StatusCode() int

type AccessDeniedError 

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

func (*AccessDeniedError) Error 

func (e *AccessDeniedError) Error() string

func (*AccessDeniedError) Provider 

func (e *AccessDeniedError) Provider() string

func (*AccessDeniedError) RetryAfter 

func (e *AccessDeniedError) RetryAfter() *time.Duration

func (*AccessDeniedError) Retryable 

func (e *AccessDeniedError) Retryable() bool

func (*AccessDeniedError) StatusCode 

func (e *AccessDeniedError) StatusCode() int

type AudioData 

type AudioData struct {
	URL       string `json:"url,omitempty"`
	Data      []byte `json:"data,omitempty"`
	MediaType string `json:"media_type,omitempty"`
}

type AuthenticationError 

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

func (*AuthenticationError) Error 

func (e *AuthenticationError) Error() string

func (*AuthenticationError) Provider 

func (e *AuthenticationError) Provider() string

func (*AuthenticationError) RetryAfter 

func (e *AuthenticationError) RetryAfter() *time.Duration

func (*AuthenticationError) Retryable 

func (e *AuthenticationError) Retryable() bool

func (*AuthenticationError) StatusCode 

func (e *AuthenticationError) StatusCode() int

type ChanStream 

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

func NewChanStream 

func NewChanStream(cancel context.CancelFunc) *ChanStream

func (*ChanStream) Close 

func (s *ChanStream) Close() error

func (*ChanStream) CloseSend 

func (s *ChanStream) CloseSend()

CloseSend closes the event channel and marks the stream as finished. Provider adapters should call this exactly once when the underlying stream finishes.

func (*ChanStream) Events 

func (s *ChanStream) Events() <-chan StreamEvent

func (*ChanStream) Send 

func (s *ChanStream) Send(ev StreamEvent)

Send publishes a stream event, dropping it if the stream is already closed.

type Client 

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

func DefaultClient 

func DefaultClient() (*Client, error)

DefaultClient returns the module-level default client, lazily constructing it from environment variables on first use.

func NewClient 

func NewClient() *Client

func NewFromEnv 

func NewFromEnv() (*Client, error)

NewFromEnv constructs a Client by registering any provider adapters that can be constructed from environment variables. The first successfully registered provider becomes the default provider.

Note: providers are discovered via factories registered with RegisterEnvAdapterFactory.

func (*Client) Complete 

func (c *Client) Complete(ctx context.Context, req Request) (Response, error)

func (*Client) ProviderNames 

func (c *Client) ProviderNames() []string

func (*Client) Register 

func (c *Client) Register(adapter ProviderAdapter)

func (*Client) SetDefaultProvider 

func (c *Client) SetDefaultProvider(name string)

func (*Client) Stream 

func (c *Client) Stream(ctx context.Context, req Request) (Stream, error)

func (*Client) Use 

func (c *Client) Use(mw ...Middleware)

Use appends middleware to the client. Middleware is applied in registration order for the request phase and in reverse order for the response/event phases.

type CompleteFunc 

type CompleteFunc func(ctx context.Context, req Request) (Response, error)

type ConfigurationError 

type ConfigurationError struct {
	Message string
}

func (*ConfigurationError) Error 

func (e *ConfigurationError) Error() string

func (*ConfigurationError) Provider 

func (e *ConfigurationError) Provider() string

func (*ConfigurationError) RetryAfter 

func (e *ConfigurationError) RetryAfter() *time.Duration

func (*ConfigurationError) Retryable 

func (e *ConfigurationError) Retryable() bool

func (*ConfigurationError) StatusCode 

func (e *ConfigurationError) StatusCode() int

type ContentFilterError 

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

func (*ContentFilterError) Error 

func (e *ContentFilterError) Error() string

func (*ContentFilterError) Provider 

func (e *ContentFilterError) Provider() string

func (*ContentFilterError) RetryAfter 

func (e *ContentFilterError) RetryAfter() *time.Duration

func (*ContentFilterError) Retryable 

func (e *ContentFilterError) Retryable() bool

func (*ContentFilterError) StatusCode 

func (e *ContentFilterError) StatusCode() int

type ContentKind 

type ContentKind string
const (
	ContentText        ContentKind = "text"
	ContentImage       ContentKind = "image"
	ContentAudio       ContentKind = "audio"
	ContentDocument    ContentKind = "document"
	ContentToolCall    ContentKind = "tool_call"
	ContentToolResult  ContentKind = "tool_result"
	ContentThinking    ContentKind = "thinking"
	ContentRedThinking ContentKind = "redacted_thinking"
)

type ContentPart 

type ContentPart struct {
	Kind ContentKind `json:"kind"`

	Text       string          `json:"text,omitempty"`
	Image      *ImageData      `json:"image,omitempty"`
	Audio      *AudioData      `json:"audio,omitempty"`
	Document   *DocumentData   `json:"document,omitempty"`
	ToolCall   *ToolCallData   `json:"tool_call,omitempty"`
	ToolResult *ToolResultData `json:"tool_result,omitempty"`
	Thinking   *ThinkingData   `json:"thinking,omitempty"`

	// Data carries provider-specific payload for custom content kinds.
	Data any `json:"data,omitempty"`
}

type ContextLengthError 

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

func (*ContextLengthError) Error 

func (e *ContextLengthError) Error() string

func (*ContextLengthError) Provider 

func (e *ContextLengthError) Provider() string

func (*ContextLengthError) RetryAfter 

func (e *ContextLengthError) RetryAfter() *time.Duration

func (*ContextLengthError) Retryable 

func (e *ContextLengthError) Retryable() bool

func (*ContextLengthError) StatusCode 

func (e *ContextLengthError) StatusCode() int

type DocumentData 

type DocumentData struct {
	URL       string `json:"url,omitempty"`
	Data      []byte `json:"data,omitempty"`
	MediaType string `json:"media_type,omitempty"`
	FileName  string `json:"file_name,omitempty"`
}

type EnvAdapterFactory 

type EnvAdapterFactory func() (adapter ProviderAdapter, configured bool, err error)

type Error 

type Error interface {
	error
	Provider() string
	StatusCode() int
	Retryable() bool
	RetryAfter() *time.Duration
}

Error is the unified error interface returned by provider adapters and the client.

type FinishReason 

type FinishReason struct {
	Reason string `json:"reason"`
	Raw    string `json:"raw,omitempty"`
}

func NormalizeFinishReason 

func NormalizeFinishReason(provider, raw string) FinishReason

NormalizeFinishReason maps provider-specific finish reason strings to canonical values while preserving the provider raw value.

type GenerateObjectOptions 

type GenerateObjectOptions struct {
	GenerateOptions
	Schema map[string]any
	Strict bool
}

type GenerateOptions 

type GenerateOptions struct {
	Client *Client

	Model    string
	Provider string

	Prompt   *string
	Messages []Message
	System   *string

	Tools      []Tool
	ToolChoice *ToolChoice

	// MaxToolRounds is the maximum number of tool-execution rounds.
	// Nil means use the spec default (1).
	// A value of 0 disables automatic tool execution (passive tool mode).
	MaxToolRounds *int

	ResponseFormat  *ResponseFormat
	Temperature     *float64
	TopP            *float64
	MaxTokens       *int
	StopSequences   []string
	ReasoningEffort *string
	Metadata        map[string]string
	ProviderOptions map[string]any

	// Retry policy for each individual LLM call within generate().
	RetryPolicy *RetryPolicy
	Sleep       SleepFunc

	// Optional timeouts for the multi-step operation.
	TimeoutTotal   time.Duration
	TimeoutPerStep time.Duration
}

type GenerateResult 

type GenerateResult struct {
	Text         string
	Reasoning    string
	ToolCalls    []ToolCallData
	ToolResults  []ToolResultData
	FinishReason FinishReason
	Usage        Usage
	TotalUsage   Usage
	Steps        []StepResult
	Response     Response
	Output       any
}

func Generate 

func Generate(ctx context.Context, opts GenerateOptions) (*GenerateResult, error)

func GenerateObject 

func GenerateObject(ctx context.Context, opts GenerateObjectOptions) (*GenerateResult, error)

type ImageData 

type ImageData struct {
	URL       string `json:"url,omitempty"`
	Data      []byte `json:"data,omitempty"` // raw bytes; adapters base64-encode as needed
	MediaType string `json:"media_type,omitempty"`
	Detail    string `json:"detail,omitempty"` // "auto"|"low"|"high"
}

type InvalidRequestError 

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

func (*InvalidRequestError) Error 

func (e *InvalidRequestError) Error() string

func (*InvalidRequestError) Provider 

func (e *InvalidRequestError) Provider() string

func (*InvalidRequestError) RetryAfter 

func (e *InvalidRequestError) RetryAfter() *time.Duration

func (*InvalidRequestError) Retryable 

func (e *InvalidRequestError) Retryable() bool

func (*InvalidRequestError) StatusCode 

func (e *InvalidRequestError) StatusCode() int

type InvalidToolCallError 

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

func (*InvalidToolCallError) Error 

func (e *InvalidToolCallError) Error() string

func (*InvalidToolCallError) Provider 

func (e *InvalidToolCallError) Provider() string

func (*InvalidToolCallError) RetryAfter 

func (e *InvalidToolCallError) RetryAfter() *time.Duration

func (*InvalidToolCallError) Retryable 

func (e *InvalidToolCallError) Retryable() bool

func (*InvalidToolCallError) StatusCode 

func (e *InvalidToolCallError) StatusCode() int

type Message 

type Message struct {
	Role       Role          `json:"role"`
	Content    []ContentPart `json:"content"`
	Name       string        `json:"name,omitempty"`
	ToolCallID string        `json:"tool_call_id,omitempty"`
}

func Assistant 

func Assistant(text string) Message

func Developer 

func Developer(text string) Message

func System 

func System(text string) Message

func ToolResult 

func ToolResult(toolCallID string, content any, isError bool) Message

func ToolResultNamed 

func ToolResultNamed(toolCallID string, name string, content any, isError bool) Message

func User 

func User(text string) Message

func (Message) Text 

func (m Message) Text() string

type Middleware 

type Middleware interface {
	WrapComplete(next CompleteFunc) CompleteFunc
	WrapStream(next StreamFunc) StreamFunc
}

Middleware wraps provider calls for cross-cutting concerns. Middleware is applied in registration order for the request phase and in reverse order for the response/event phase.

type MiddlewareFunc 

type MiddlewareFunc struct {
	Complete func(ctx context.Context, req Request, next CompleteFunc) (Response, error)
	Stream   func(ctx context.Context, req Request, next StreamFunc) (Stream, error)
}

func (MiddlewareFunc) WrapComplete 

func (m MiddlewareFunc) WrapComplete(next CompleteFunc) CompleteFunc

func (MiddlewareFunc) WrapStream 

func (m MiddlewareFunc) WrapStream(next StreamFunc) StreamFunc

type ModelCatalog 

type ModelCatalog struct {
	Models []ModelInfo
	// contains filtered or unexported fields
}

func LoadModelCatalogFromOpenRouterJSON 

func LoadModelCatalogFromOpenRouterJSON(path string) (*ModelCatalog, error)

LoadModelCatalogFromOpenRouterJSON loads model metadata from OpenRouter's /api/v1/models payload shape: {"data":[...]}.

func (*ModelCatalog) GetLatestModel 

func (c *ModelCatalog) GetLatestModel(provider string, capability string) *ModelInfo

func (*ModelCatalog) GetModelInfo 

func (c *ModelCatalog) GetModelInfo(modelID string) *ModelInfo

func (*ModelCatalog) ListModels 

func (c *ModelCatalog) ListModels(provider string) []ModelInfo

type ModelInfo 

type ModelInfo struct {
	ID                   string   `json:"id"`
	Provider             string   `json:"provider"`
	DisplayName          string   `json:"display_name"`
	ContextWindow        int      `json:"context_window"`
	MaxOutputTokens      *int     `json:"max_output_tokens,omitempty"`
	SupportsTools        bool     `json:"supports_tools"`
	SupportsVision       bool     `json:"supports_vision"`
	SupportsReasoning    bool     `json:"supports_reasoning"`
	InputCostPerMillion  *float64 `json:"input_cost_per_million,omitempty"`
	OutputCostPerMillion *float64 `json:"output_cost_per_million,omitempty"`
	Aliases              []string `json:"aliases,omitempty"`
}

ModelInfo is the normalized model metadata entry, primarily sourced from OpenRouter model info in Kilroy. This is metadata-only and is not used as a provider call path.

type NetworkError 

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

func (*NetworkError) Error 

func (e *NetworkError) Error() string

func (*NetworkError) Provider 

func (e *NetworkError) Provider() string

func (*NetworkError) RetryAfter 

func (e *NetworkError) RetryAfter() *time.Duration

func (*NetworkError) Retryable 

func (e *NetworkError) Retryable() bool

func (*NetworkError) StatusCode 

func (e *NetworkError) StatusCode() int

type NoObjectGeneratedError 

type NoObjectGeneratedError struct {
	RawText string
	// contains filtered or unexported fields
}

func (*NoObjectGeneratedError) Error 

func (e *NoObjectGeneratedError) Error() string

func (*NoObjectGeneratedError) Provider 

func (e *NoObjectGeneratedError) Provider() string

func (*NoObjectGeneratedError) RetryAfter 

func (e *NoObjectGeneratedError) RetryAfter() *time.Duration

func (*NoObjectGeneratedError) Retryable 

func (e *NoObjectGeneratedError) Retryable() bool

func (*NoObjectGeneratedError) StatusCode 

func (e *NoObjectGeneratedError) StatusCode() int

type NotFoundError 

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

func (*NotFoundError) Error 

func (e *NotFoundError) Error() string

func (*NotFoundError) Provider 

func (e *NotFoundError) Provider() string

func (*NotFoundError) RetryAfter 

func (e *NotFoundError) RetryAfter() *time.Duration

func (*NotFoundError) Retryable 

func (e *NotFoundError) Retryable() bool

func (*NotFoundError) StatusCode 

func (e *NotFoundError) StatusCode() int

type ProviderAdapter 

type ProviderAdapter interface {
	Name() string
	Complete(ctx context.Context, req Request) (Response, error)
	Stream(ctx context.Context, req Request) (Stream, error)
}

type ProviderExecutionPolicy 

type ProviderExecutionPolicy struct {
	ForceStream  bool
	MinMaxTokens int
	MaxMaxTokens int
	Reason       string
}

func ExecutionPolicy 

func ExecutionPolicy(provider, model string) ProviderExecutionPolicy

type ProviderToolLifecycle 

type ProviderToolLifecycle struct {
	ToolName      string
	CallID        string
	ArgumentsJSON string
	FullOutput    string
	Completed     bool
	IsError       bool
}

ProviderToolLifecycle captures provider-native tool lifecycle events that can be surfaced through generic progress telemetry.

func ParseCodexAppServerToolLifecycle 

func ParseCodexAppServerToolLifecycle(ev StreamEvent) (ProviderToolLifecycle, bool)

ParseCodexAppServerToolLifecycle maps codex-app-server item lifecycle provider events into a normalized tool lifecycle shape.

type ProviderToolOutputDelta 

type ProviderToolOutputDelta struct {
	ToolName string
	CallID   string
	Delta    string
}

ProviderToolOutputDelta captures provider-native streamed tool output chunks.

func ParseCodexAppServerToolOutputDelta 

func ParseCodexAppServerToolOutputDelta(ev StreamEvent) (ProviderToolOutputDelta, bool)

ParseCodexAppServerToolOutputDelta maps codex-app-server output/progress notifications into normalized tool output deltas.

type QuotaExceededError 

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

func (*QuotaExceededError) Error 

func (e *QuotaExceededError) Error() string

func (*QuotaExceededError) Provider 

func (e *QuotaExceededError) Provider() string

func (*QuotaExceededError) RetryAfter 

func (e *QuotaExceededError) RetryAfter() *time.Duration

func (*QuotaExceededError) Retryable 

func (e *QuotaExceededError) Retryable() bool

func (*QuotaExceededError) StatusCode 

func (e *QuotaExceededError) StatusCode() int

type RateLimitError 

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

func (*RateLimitError) Error 

func (e *RateLimitError) Error() string

func (*RateLimitError) Provider 

func (e *RateLimitError) Provider() string

func (*RateLimitError) RetryAfter 

func (e *RateLimitError) RetryAfter() *time.Duration

func (*RateLimitError) Retryable 

func (e *RateLimitError) Retryable() bool

func (*RateLimitError) StatusCode 

func (e *RateLimitError) StatusCode() int

type RateLimitInfo 

type RateLimitInfo struct {
	RequestsRemaining *int   `json:"requests_remaining,omitempty"`
	RequestsLimit     *int   `json:"requests_limit,omitempty"`
	TokensRemaining   *int   `json:"tokens_remaining,omitempty"`
	TokensLimit       *int   `json:"tokens_limit,omitempty"`
	ResetAt           string `json:"reset_at,omitempty"`
}

func ParseRateLimitInfo 

func ParseRateLimitInfo(headers http.Header, now time.Time) *RateLimitInfo

ParseRateLimitInfo extracts informational rate limit metadata from response headers. The result is best-effort and intended for observability, not proactive throttling.

type Request 

type Request struct {
	Model    string    `json:"model"`
	Provider string    `json:"provider,omitempty"`
	Messages []Message `json:"messages"`

	Tools      []ToolDefinition `json:"tools,omitempty"`
	ToolChoice *ToolChoice      `json:"tool_choice,omitempty"`

	ResponseFormat  *ResponseFormat   `json:"response_format,omitempty"`
	Temperature     *float64          `json:"temperature,omitempty"`
	TopP            *float64          `json:"top_p,omitempty"`
	MaxTokens       *int              `json:"max_tokens,omitempty"`
	StopSequences   []string          `json:"stop_sequences,omitempty"`
	ReasoningEffort *string           `json:"reasoning_effort,omitempty"` // low|medium|high|none
	Metadata        map[string]string `json:"metadata,omitempty"`

	ProviderOptions map[string]any `json:"provider_options,omitempty"`
}

func ApplyExecutionPolicy 

func ApplyExecutionPolicy(req Request, policy ProviderExecutionPolicy) Request

func (Request) Validate 

func (req Request) Validate() error

type RequestTimeoutError 

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

func (*RequestTimeoutError) Error 

func (e *RequestTimeoutError) Error() string

func (*RequestTimeoutError) Provider 

func (e *RequestTimeoutError) Provider() string

func (*RequestTimeoutError) RetryAfter 

func (e *RequestTimeoutError) RetryAfter() *time.Duration

func (*RequestTimeoutError) Retryable 

func (e *RequestTimeoutError) Retryable() bool

func (*RequestTimeoutError) StatusCode 

func (e *RequestTimeoutError) StatusCode() int

type Response 

type Response struct {
	ID        string         `json:"id"`
	Model     string         `json:"model"`
	Provider  string         `json:"provider"`
	Message   Message        `json:"message"`
	Finish    FinishReason   `json:"finish_reason"`
	Usage     Usage          `json:"usage"`
	Raw       map[string]any `json:"raw,omitempty"`
	Warnings  []Warning      `json:"warnings,omitempty"`
	RateLimit *RateLimitInfo `json:"rate_limit,omitempty"`
}

func (Response) ReasoningText 

func (r Response) ReasoningText() string

func (Response) Text 

func (r Response) Text() string

func (Response) ToolCalls 

func (r Response) ToolCalls() []ToolCallData

type ResponseFormat 

type ResponseFormat struct {
	Type       string         `json:"type"`                  // "text", "json", "json_schema"
	JSONSchema map[string]any `json:"json_schema,omitempty"` // when type=json_schema
	Strict     bool           `json:"strict,omitempty"`
}

type RetryPolicy 

type RetryPolicy struct {
	// MaxRetries is the number of retry attempts (not counting the initial attempt).
	MaxRetries int

	// BaseDelay is the delay before the first retry attempt.
	BaseDelay time.Duration

	// MaxDelay caps the delay between retries.
	MaxDelay time.Duration

	// BackoffMultiplier controls exponential backoff growth (2.0 = double each retry).
	BackoffMultiplier float64

	// Jitter adds randomness to delays to reduce thundering-herd retries.
	Jitter bool

	// OnRetry is invoked before sleeping for a retry attempt.
	OnRetry func(err error, attempt int, delay time.Duration)
}

func DefaultRetryPolicy 

func DefaultRetryPolicy() RetryPolicy

type Role 

type Role string
const (
	RoleSystem    Role = "system"
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleTool      Role = "tool"
	RoleDeveloper Role = "developer"
)

type SSEEvent 

type SSEEvent struct {
	Event string
	Data  []byte
}

type ServerError 

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

func (*ServerError) Error 

func (e *ServerError) Error() string

func (*ServerError) Provider 

func (e *ServerError) Provider() string

func (*ServerError) RetryAfter 

func (e *ServerError) RetryAfter() *time.Duration

func (*ServerError) Retryable 

func (e *ServerError) Retryable() bool

func (*ServerError) StatusCode 

func (e *ServerError) StatusCode() int

type SleepFunc 

type SleepFunc func(ctx context.Context, d time.Duration) error

type StepResult 

type StepResult struct {
	Text         string
	Reasoning    string
	ToolCalls    []ToolCallData
	ToolResults  []ToolResultData
	FinishReason FinishReason
	Usage        Usage
	Response     Response
	Warnings     []Warning
}

type Stream 

type Stream interface {
	Events() <-chan StreamEvent
	Close() error
}

Stream is an asynchronous iterator of StreamEvent values. Implementations must be explicitly closed when the consumer is done to avoid leaking connections.

type StreamAccumulator 

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

StreamAccumulator collects StreamEvent values and produces a complete Response. It primarily exists to bridge streaming mode back to code that expects a Response.

func NewStreamAccumulator 

func NewStreamAccumulator() *StreamAccumulator

func (*StreamAccumulator) PartialResponse 

func (a *StreamAccumulator) PartialResponse() *Response

PartialResponse returns the best-effort accumulated response so far (may be nil).

func (*StreamAccumulator) Process 

func (a *StreamAccumulator) Process(ev StreamEvent)

func (*StreamAccumulator) Response 

func (a *StreamAccumulator) Response() *Response

Response returns the final accumulated response after FINISH, or nil if the stream has not completed.

type StreamError 

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

func (*StreamError) Error 

func (e *StreamError) Error() string

func (*StreamError) Provider 

func (e *StreamError) Provider() string

func (*StreamError) RetryAfter 

func (e *StreamError) RetryAfter() *time.Duration

func (*StreamError) Retryable 

func (e *StreamError) Retryable() bool

func (*StreamError) StatusCode 

func (e *StreamError) StatusCode() int

type StreamEvent 

type StreamEvent struct {
	Type StreamEventType `json:"type"`

	// Stream start metadata
	ID       string    `json:"id,omitempty"`
	Model    string    `json:"model,omitempty"`
	Warnings []Warning `json:"warnings,omitempty"`

	// Text events
	Delta  string `json:"delta,omitempty"`
	TextID string `json:"text_id,omitempty"`

	// Reasoning events
	ReasoningDelta string `json:"reasoning_delta,omitempty"`
	ReasoningID    string `json:"reasoning_id,omitempty"`
	Redacted       *bool  `json:"redacted,omitempty"`

	// Tool call events
	ToolCall *ToolCallData `json:"tool_call,omitempty"`

	// Finish event
	FinishReason *FinishReason `json:"finish_reason,omitempty"`
	Usage        *Usage        `json:"usage,omitempty"`
	Response     *Response     `json:"response,omitempty"`

	// Error event
	Err error `json:"-"`

	// Passthrough
	EventType string         `json:"event_type,omitempty"`
	Raw       map[string]any `json:"raw,omitempty"`
}

type StreamEventType 

type StreamEventType string
const (
	StreamEventStreamStart    StreamEventType = "STREAM_START"
	StreamEventTextStart      StreamEventType = "TEXT_START"
	StreamEventTextDelta      StreamEventType = "TEXT_DELTA"
	StreamEventTextEnd        StreamEventType = "TEXT_END"
	StreamEventReasoningStart StreamEventType = "REASONING_START"
	StreamEventReasoningDelta StreamEventType = "REASONING_DELTA"
	StreamEventReasoningEnd   StreamEventType = "REASONING_END"
	StreamEventToolCallStart  StreamEventType = "TOOL_CALL_START"
	StreamEventToolCallDelta  StreamEventType = "TOOL_CALL_DELTA"
	StreamEventToolCallEnd    StreamEventType = "TOOL_CALL_END"
	StreamEventStepFinish     StreamEventType = "STEP_FINISH"
	StreamEventFinish         StreamEventType = "FINISH"
	StreamEventError          StreamEventType = "ERROR"
	StreamEventProviderEvent  StreamEventType = "PROVIDER_EVENT"
)

type StreamFunc 

type StreamFunc func(ctx context.Context, req Request) (Stream, error)

type StreamResult 

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

StreamResult is the high-level streaming generation result. It yields StreamEvent values over Events() and exposes the accumulated final response once the stream ends.

func StreamGenerate 

func StreamGenerate(ctx context.Context, opts GenerateOptions) (*StreamResult, error)

StreamGenerate is the high-level streaming API (spec stream()). It is equivalent to Generate(), but yields StreamEvent values incrementally and continues across tool-execution steps. Between tool steps it emits a STEP_FINISH event.

func (*StreamResult) Close 

func (r *StreamResult) Close() error

func (*StreamResult) Events 

func (r *StreamResult) Events() <-chan StreamEvent

func (*StreamResult) PartialResponse 

func (r *StreamResult) PartialResponse() *Response

func (*StreamResult) Response 

func (r *StreamResult) Response() (*Response, error)

type ThinkingData 

type ThinkingData struct {
	Text      string `json:"text"`
	Signature string `json:"signature,omitempty"`
	Redacted  bool   `json:"redacted,omitempty"`
}

type Tool 

type Tool struct {
	Definition ToolDefinition
	Execute    func(ctx context.Context, args any) (any, error)
	// contains filtered or unexported fields
}

type ToolCallData 

type ToolCallData struct {
	ID        string          `json:"id"`
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments,omitempty"` // raw JSON object
	Type      string          `json:"type,omitempty"`      // usually "function"
	// ThoughtSignature carries provider-specific thought-signature state (e.g., Gemini)
	// required to continue tool-calling turns safely.
	ThoughtSignature string `json:"thought_signature,omitempty"`
}

type ToolChoice 

type ToolChoice struct {
	Mode string `json:"mode"` // "auto", "none", "required"
	Name string `json:"name,omitempty"`
}

type ToolDefinition 

type ToolDefinition struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters,omitempty"` // JSON Schema (root object)
}

type ToolResultData 

type ToolResultData struct {
	ToolCallID string `json:"tool_call_id"`
	Name       string `json:"name,omitempty"`
	Content    any    `json:"content"`
	IsError    bool   `json:"is_error"`

	ImageData      []byte `json:"image_data,omitempty"`
	ImageMediaType string `json:"image_media_type,omitempty"`
}

type UnknownHTTPError 

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

func (*UnknownHTTPError) Error 

func (e *UnknownHTTPError) Error() string

func (*UnknownHTTPError) Provider 

func (e *UnknownHTTPError) Provider() string

func (*UnknownHTTPError) RetryAfter 

func (e *UnknownHTTPError) RetryAfter() *time.Duration

func (*UnknownHTTPError) Retryable 

func (e *UnknownHTTPError) Retryable() bool

func (*UnknownHTTPError) StatusCode 

func (e *UnknownHTTPError) StatusCode() int

type UnsupportedToolChoiceError 

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

func (*UnsupportedToolChoiceError) Error 

func (e *UnsupportedToolChoiceError) Error() string

func (*UnsupportedToolChoiceError) Provider 

func (e *UnsupportedToolChoiceError) Provider() string

func (*UnsupportedToolChoiceError) RetryAfter 

func (e *UnsupportedToolChoiceError) RetryAfter() *time.Duration

func (*UnsupportedToolChoiceError) Retryable 

func (e *UnsupportedToolChoiceError) Retryable() bool

func (*UnsupportedToolChoiceError) StatusCode 

func (e *UnsupportedToolChoiceError) StatusCode() int

type Usage 

type Usage struct {
	InputTokens      int  `json:"input_tokens"`
	OutputTokens     int  `json:"output_tokens"`
	TotalTokens      int  `json:"total_tokens"`
	ReasoningTokens  *int `json:"reasoning_tokens,omitempty"`
	CacheReadTokens  *int `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens *int `json:"cache_write_tokens,omitempty"`

	Raw map[string]any `json:"raw,omitempty"`
}

func (Usage) Add 

func (u Usage) Add(v Usage) Usage

type Warning 

type Warning struct {
	Message string `json:"message"`
	Code    string `json:"code,omitempty"`
}

Source Files

View all Source files

Directories

Path Synopsis
providers
anthropic
codexappserver
google
openai
openaicompat

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.