Documentation
¶
Index ¶
- Constants
- func AttachmentData(p ContentPart) (mimeType, value string, isData bool, err error)
- func CacheEndpointHost(endpoint string) string
- func ContextLimitFromError(err error) int
- func DecodeImageSize(data []byte) (w, h int, ok bool)
- func ImageTokens(w, h int) int
- func IsContextLimit(err error) bool
- func NormalizeImage(ext string, data []byte) (string, []byte)
- func ObserveRuntimeDiagnostic(ctx context.Context, event RuntimeDiagnostic)
- func PartTokens(p ContentPart) int
- func SharedCacheMessages(previous, current CacheObservation) int
- func SupportedAPI(api string) bool
- func TruncatedToolCalls(msg Message) bool
- func WithCacheObserver(ctx context.Context, observe func(CacheObservation)) context.Context
- func WithRuntimeDiagnosticObserver(ctx context.Context, observe func(RuntimeDiagnostic)) context.Context
- func WithSearchObserver(ctx context.Context, observer func(HostedSearch)) context.Context
- type Anthropic
- func (c *Anthropic) Clone() Client
- func (c *Anthropic) Complete(ctx context.Context, req Request) (string, Usage, error)
- func (c *Anthropic) Models(ctx context.Context) ([]ModelInfo, error)
- func (c *Anthropic) Stream(ctx context.Context, req Request, onText, onThink func(string), ...) (Message, Usage, error)
- type CacheCapabilities
- type CacheObservation
- type CacheOptions
- type Client
- type ClientOptions
- type ContentPart
- type Cost
- type Gemini
- func (c *Gemini) Clone() Client
- func (c *Gemini) Complete(ctx context.Context, req Request) (string, Usage, error)
- func (c *Gemini) Endpoint() string
- func (c *Gemini) Models(ctx context.Context) ([]ModelInfo, error)
- func (c *Gemini) SetCacheKey(string)
- func (c *Gemini) SetMaxRetries(n int)
- func (c *Gemini) SetOnRetry(fn func(RetryEvent))
- func (c *Gemini) SetUseProxy(on bool)
- func (c *Gemini) Stream(ctx context.Context, req Request, onText, onThink func(string), ...) (Message, Usage, error)
- type HTTPError
- type HostedSearch
- type Message
- type ModelInfo
- type OpenAI
- func (c *OpenAI) Clone() Client
- func (c *OpenAI) Complete(ctx context.Context, req Request) (string, Usage, error)
- func (c *OpenAI) Endpoint() string
- func (c *OpenAI) Models(ctx context.Context) ([]ModelInfo, error)
- func (c *OpenAI) SetCacheKey(k string)
- func (c *OpenAI) SetCacheOptions(o CacheOptions)
- func (c *OpenAI) SetMaxRetries(n int)
- func (c *OpenAI) SetOnRetry(fn func(RetryEvent))
- func (c *OpenAI) SetUseProxy(on bool)
- func (c *OpenAI) Stream(ctx context.Context, req Request, onText, onThink func(string), ...) (Message, Usage, error)
- type OutputLimitError
- type Pricing
- type PromptSnapshot
- type ProviderReplay
- type QuestionAnswer
- type Request
- type Responses
- type RetryEvent
- type RuntimeDiagnostic
- type SearchSource
- type StopReason
- type TokenRates
- type Tool
- type ToolCall
- type Usage
- type UsageSummary
Constants ¶
const ( AttachmentImage = "image" AttachmentFile = "file" )
AttachmentKind names the provider-neutral attachment classes.
const ( APIChatCompletions = "openai-completions" APIResponses = "openai-responses" APIMessages = "anthropic-messages" APIGemini = "google-generative-ai" APIGoogleGemini = "google-gemini" )
const ( NormalizeMaxDim = 2000 NormalizeMaxBytes = 5 * 1024 * 1024 NormalizeMaxPixels = 64_000_000 )
const DefaultMaxAttempts = 8
const ImageTokenFloor = 85
const OriginBackground = "background"
OriginBackground marks a notice the runtime delivered on its own as a user-role message: a wait result, a managed process exit, a background subagent or workflow report, a goal continuation round, the new-context notice or the output-limit continuation reminder. Clients show it as a notice rather than as something the user typed.
Variables ¶
This section is empty.
Functions ¶
func AttachmentData ¶ added in v0.107.0
func AttachmentData(p ContentPart) (mimeType, value string, isData bool, err error)
func CacheEndpointHost ¶ added in v0.107.6
CacheEndpointHost uses the parsed hostname, never a substring of an untrusted URL.
func ContextLimitFromError ¶ added in v0.107.13
ContextLimitFromError returns the context window a provider reported when it rejected a prompt as too large, or 0 when the error states none. The window a model catalog advertises can exceed what a given endpoint accepts (relays often cap it lower), so this is the authoritative figure once seen.
func DecodeImageSize ¶
func ImageTokens ¶
func IsContextLimit ¶
func ObserveRuntimeDiagnostic ¶ added in v0.107.0
func ObserveRuntimeDiagnostic(ctx context.Context, event RuntimeDiagnostic)
func PartTokens ¶
func PartTokens(p ContentPart) int
func SharedCacheMessages ¶ added in v0.107.6
func SharedCacheMessages(previous, current CacheObservation) int
SharedCacheMessages counts whole matching messages; it deliberately does not estimate tokens.
func SupportedAPI ¶ added in v0.107.0
func TruncatedToolCalls ¶ added in v0.107.13
TruncatedToolCalls reports whether msg was cut off by the output limit while it was still emitting tool calls. Those calls were dropped unexecuted.
func WithCacheObserver ¶ added in v0.107.6
func WithCacheObserver(ctx context.Context, observe func(CacheObservation)) context.Context
func WithRuntimeDiagnosticObserver ¶ added in v0.107.0
func WithRuntimeDiagnosticObserver(ctx context.Context, observe func(RuntimeDiagnostic)) context.Context
func WithSearchObserver ¶ added in v0.107.0
func WithSearchObserver(ctx context.Context, observer func(HostedSearch)) context.Context
Types ¶
type CacheCapabilities ¶ added in v0.107.6
type CacheCapabilities struct {
SupportsPromptCacheKey *bool `json:"supportsPromptCacheKey,omitempty"`
SupportsLongRetention *bool `json:"supportsLongRetention,omitempty"`
SessionAffinityFormat string `json:"sessionAffinityFormat,omitempty"`
ResponsesCacheOptions bool `json:"responsesCacheOptions,omitempty"`
}
CacheCapabilities describes the API contract, not whether its cache will hit. Nil booleans retain endpoint defaults; explicit false supports strict relays.
func (CacheCapabilities) Validate ¶ added in v0.107.6
func (c CacheCapabilities) Validate() error
type CacheObservation ¶ added in v0.107.6
CacheObservation contains hashes of the final wire payload, never prompt text or credentials. Matching hashes indicate reusable structure, not provider cache hits or token counts.
type CacheOptions ¶
type Client ¶
type Client interface {
Models(context.Context) ([]ModelInfo, error)
Stream(context.Context, Request, func(string), func(string), func(id, name, args string)) (Message, Usage, error)
Complete(context.Context, Request) (string, Usage, error)
Clone() Client
SetCacheKey(string)
Endpoint() string
}
func NewClient ¶
func NewClient(opts ClientOptions) (Client, error)
type ClientOptions ¶
type ContentPart ¶
type ContentPart struct {
Type string `json:"type"`
Text string `json:"text,omitempty"`
ImageURL *struct {
URL string `json:"url"`
} `json:"image_url,omitempty"`
FileURL *struct {
URL string `json:"url"`
Filename string `json:"filename,omitempty"`
} `json:"file_url,omitempty"`
MimeType string `json:"mime_type,omitempty"`
W int `json:"w,omitempty"`
H int `json:"h,omitempty"`
}
func FilePart ¶ added in v0.107.0
func FilePart(mimeType, filename string, data []byte) ContentPart
func ImagePart ¶
func ImagePart(ext string, data []byte) ContentPart
func (ContentPart) Attachment ¶ added in v0.107.0
func (p ContentPart) Attachment() bool
func (ContentPart) DecodeDimensions ¶
func (p ContentPart) DecodeDimensions() (w, h int, ok bool)
type Cost ¶ added in v0.103.0
type Cost struct {
Input float64 `json:"input"`
Output float64 `json:"output"`
CacheRead float64 `json:"cacheRead"`
CacheWrite float64 `json:"cacheWrite"`
Total float64 `json:"total"`
}
func CalculateCost ¶ added in v0.103.0
func CalculateCost(u Usage, rates TokenRates) (Cost, bool)
type Gemini ¶ added in v0.107.0
type Gemini struct {
BaseURL string
APIKey string
IsFullURL bool
ModelsURL string
Headers http.Header
HTTP *http.Client
MaxRetries int
StreamIdle time.Duration
OnRetry func(RetryEvent)
// contains filtered or unexported fields
}
Gemini implements Google's native generateContent API while exposing the same provider-neutral Client interface as the other adapters.
func NewGeminiWithOptions ¶ added in v0.107.0
func (*Gemini) SetCacheKey ¶ added in v0.107.0
func (*Gemini) SetMaxRetries ¶ added in v0.107.0
func (*Gemini) SetOnRetry ¶ added in v0.107.0
func (c *Gemini) SetOnRetry(fn func(RetryEvent))
func (*Gemini) SetUseProxy ¶ added in v0.107.6
SetUseProxy selects the proxied or direct transport for this provider.
type HTTPError ¶
type HostedSearch ¶ added in v0.107.0
type Message ¶
type Message struct {
ID string `json:"id,omitempty"`
Role string `json:"role"`
Content string `json:"content"`
Parts []ContentPart `json:"-"`
// Reasoning is display-only; signed provider replay state is separate.
Reasoning string `json:"reasoning,omitempty"`
Replay *ProviderReplay `json:"-"`
ToolCalls []ToolCall `json:"tool_calls,omitempty"`
ToolCallID string `json:"tool_call_id,omitempty"`
HostedSearch []HostedSearch `json:"-"`
Name string `json:"name,omitempty"`
Authored bool `json:"authored,omitempty"`
// Origin marks a user-role message the user did not write; see OriginBackground.
Origin string `json:"origin,omitempty"`
SentAt *time.Time `json:"sent_at,omitempty"`
// PromptContext is a persisted request-only snapshot, not user-authored text.
PromptContext string `json:"prompt_context,omitempty"`
PromptSnapshots []PromptSnapshot `json:"prompt_snapshots,omitempty"`
Usage *Usage `json:"usage,omitempty"`
Model string `json:"model,omitempty"`
StopReason StopReason `json:"stop_reason,omitempty"`
RawStopReason string `json:"raw_stop_reason,omitempty"`
RewoundFrom string `json:"rewound_from,omitempty"`
}
func (Message) ContentParts ¶ added in v0.103.0
func (m Message) ContentParts() []ContentPart
func (Message) MarshalJSON ¶
func (Message) TextContent ¶
func (*Message) UnmarshalJSON ¶
type ModelInfo ¶
type ModelInfo struct {
ID string `json:"id"`
ContextLength int `json:"context_length,omitempty"`
MaxCompletionTokens int `json:"max_completion_tokens,omitempty"`
ReasoningEfforts []string `json:"reasoning_efforts,omitempty"`
Pricing *Pricing `json:"pricing,omitempty"`
OutputModalities []string `json:"output_modalities,omitempty"`
InputModalities []string `json:"input_modalities,omitempty"`
}
func (ModelInfo) SupportsVision ¶
type OpenAI ¶
type OpenAI struct {
BaseURL string
APIKey string
IsFullURL bool
ModelsURL string
Headers http.Header
HTTP *http.Client
MaxRetries int
// StreamIdle bounds how long a streaming response may deliver no bytes
// before the connection is treated as stalled. Zero uses the package
// default; a negative value disables the watchdog. Embedded by the
// Anthropic and Responses clients, so it covers those APIs too.
StreamIdle time.Duration
OnRetry func(RetryEvent)
CacheKey string
CacheRetention string
CacheSessionAffinity bool
CacheControlFormat string
SupportsLongCacheRetention bool
SupportsPromptCacheKey *bool
CacheSessionAffinityFormat string
ResponsesCacheOptions bool
}
func NewWithOptions ¶ added in v0.107.0
func (*OpenAI) SetCacheKey ¶
func (*OpenAI) SetCacheOptions ¶
func (c *OpenAI) SetCacheOptions(o CacheOptions)
func (*OpenAI) SetMaxRetries ¶
func (*OpenAI) SetOnRetry ¶
func (c *OpenAI) SetOnRetry(fn func(RetryEvent))
func (*OpenAI) SetUseProxy ¶ added in v0.107.6
SetUseProxy selects the proxied or direct transport for this provider.
type OutputLimitError ¶ added in v0.103.0
type OutputLimitError struct {
Reason string
}
func (*OutputLimitError) Error ¶ added in v0.103.0
func (e *OutputLimitError) Error() string
type Pricing ¶
type Pricing struct {
Prompt string `json:"prompt"`
Completion string `json:"completion"`
InputCacheRead string `json:"input_cache_read,omitempty"`
InputCacheWrite string `json:"input_cache_write,omitempty"`
}
func (Pricing) Rates ¶
func (p Pricing) Rates() *TokenRates
type PromptSnapshot ¶ added in v0.107.6
PromptSnapshot records the source and rendered value of backend-owned context.
type ProviderReplay ¶ added in v0.107.5
type ProviderReplay struct {
API string `json:"api"`
Endpoint string `json:"endpoint"`
Model string `json:"model"`
Blocks []json.RawMessage `json:"blocks"`
}
ProviderReplay is backend-owned state, scoped to the originating endpoint and model.
type QuestionAnswer ¶ added in v0.107.23
type QuestionAnswer struct {
Prompt string `json:"prompt,omitempty"`
QuestionID string `json:"question_id"`
// SelectedLabel is the user's own words when Custom is set; otherwise the
// chosen option's label, or, with SelectedLabels, the chosen labels joined
// by ", " for display.
SelectedLabel string `json:"selected_label"`
// SelectedLabels are the chosen options, each exactly one of the
// question's labels, in option order. Set whenever the answer carries a
// structured selection; Custom may add the user's own words beside them.
SelectedLabels []string `json:"selected_labels,omitempty"`
Custom bool `json:"custom,omitempty"`
}
QuestionAnswer is the user's answer to one question of a question tool call (question, AskUserQuestion). The /v1 protocol uses this shape for answers.
type Request ¶
type Request struct {
NativeWebSearch bool `json:"-"`
NativeSearchProvider string `json:"-"`
Model string `json:"model"`
Messages []Message `json:"messages"`
Tools []Tool `json:"tools,omitempty"`
MaxTokens int `json:"max_tokens,omitempty"`
ReasoningEffort string `json:"reasoning_effort,omitempty"`
Temperature *float64 `json:"temperature,omitempty"`
TopP *float64 `json:"top_p,omitempty"`
Stream bool `json:"stream"`
PromptCacheKey string `json:"prompt_cache_key,omitempty"`
PromptCacheRetention string `json:"prompt_cache_retention,omitempty"`
StreamOptions *struct {
IncludeUsage bool `json:"include_usage"`
} `json:"stream_options,omitempty"`
}
type RuntimeDiagnostic ¶ added in v0.107.0
type RuntimeDiagnostic struct {
Kind string
Provider string
From string
To string
Endpoint string
Attempt int
TargetIndex int
Error string
}
RuntimeDiagnostic carries routing facts only; headers and credentials are excluded.
type SearchSource ¶ added in v0.107.0
type StopReason ¶ added in v0.103.0
type StopReason string
const ( StopReasonStop StopReason = "stop" StopReasonLength StopReason = "length" StopReasonToolUse StopReason = "tool_use" StopReasonOther StopReason = "other" StopReasonError StopReason = "error" StopReasonCancelled StopReason = "cancelled" )
type TokenRates ¶ added in v0.103.0
type TokenRates struct {
Input float64 `json:"input"`
Output float64 `json:"output"`
CacheRead float64 `json:"cacheRead"`
CacheWrite float64 `json:"cacheWrite"`
}
func (TokenRates) Valid ¶ added in v0.103.0
func (r TokenRates) Valid() bool
type Tool ¶
type Tool struct {
Type string `json:"type"`
Function struct {
Name string `json:"name"`
Description string `json:"description"`
Parameters json.RawMessage `json:"parameters"`
} `json:"function"`
}
type ToolCall ¶
type ToolCall struct {
ID string `json:"id"`
Type string `json:"type"`
Function struct {
Name string `json:"name"`
Arguments string `json:"arguments"`
} `json:"function"`
// DurationMs, ExitCode, ExitStatus and TimedOut describe how the call ran,
// for display; requests never carry them.
DurationMs int64 `json:"duration_ms,omitempty"`
// ExitCode is nonzero for a failed call: the command's status when a shell
// tool reported one, else 1 for a result that reads as an error.
ExitCode int `json:"exit_code,omitempty"`
// ExitStatus is the exit status a shell tool reported, 0 included (see
// tools.Result.ExitCode); nil for other calls.
ExitStatus *int `json:"exit_status,omitempty"`
TimedOut bool `json:"timed_out,omitempty"`
// QuestionAnswers is what the user answered a question tool call, one
// entry per question; for display, like the fields above.
QuestionAnswers []QuestionAnswer `json:"question_answers,omitempty"`
}
type Usage ¶
type Usage struct {
PromptTokens int `json:"prompt_tokens"`
CompletionTokens int `json:"completion_tokens"`
PromptTokensDetails *struct {
CachedTokens int `json:"cached_tokens"`
} `json:"prompt_tokens_details,omitempty"`
PromptCacheHitTokens int `json:"prompt_cache_hit_tokens,omitempty"`
PromptCacheWriteTokens int `json:"prompt_cache_write_tokens,omitempty"`
}
func (Usage) CacheWrite ¶
Source Files
¶
- anthropic.go
- anthropic_stream.go
- anthropic_usage.go
- attachments.go
- cache_observer.go
- cache_policy.go
- compat.go
- content.go
- diagnostic_observer.go
- factory.go
- gemini.go
- http.go
- images.go
- message.go
- native_search.go
- normalize.go
- openai.go
- pricing.go
- question.go
- request_history.go
- responses.go
- responses_stream.go
- retry.go
- sse.go
- stop.go
- stream_idle.go
- stream_text.go
- usage.go