Documentation
¶
Index ¶
- Constants
- func APISupportsNativeWebSearch(api, baseURL string) bool
- 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 SupportsNativeWebSearch(c Client) bool
- func SupportsNativeWebSearchForModel(c Client, model 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)
- func (c *Anthropic) SupportsNativeWebSearch() bool
- type CacheCapabilities
- type CacheObservation
- type CacheOptions
- type Client
- type ClientOptions
- type ContentPart
- type Cost
- type ElicitField
- type ElicitOption
- type Elicitation
- 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)
- func (c *Gemini) SupportsNativeWebSearch() bool
- type HTTPError
- type HostedSearch
- type Message
- type ModelInfo
- type NativeWebSearchSupporter
- 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)
- func (c *OpenAI) SupportsNativeWebSearch() bool
- func (c *OpenAI) SupportsNativeWebSearchForModel(model string) bool
- type OutputLimitError
- type Pricing
- type PromptSnapshot
- type ProviderReplay
- type QuestionAnswer
- type Request
- type Responses
- func (c *Responses) Clone() Client
- func (c *Responses) Complete(ctx context.Context, req Request) (string, Usage, error)
- func (c *Responses) Stream(ctx context.Context, req Request, onText, onThink func(string), ...) (Message, Usage, error)
- func (c *Responses) SupportsNativeWebSearch() bool
- func (c *Responses) SupportsNativeWebSearchForModel(string) bool
- 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 APISupportsNativeWebSearch ¶ added in v0.107.33
APISupportsNativeWebSearch is SupportsNativeWebSearch for a provider setting that has no client yet: the API family and, for Gemini, the endpoint.
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 SupportsNativeWebSearch ¶ added in v0.107.33
SupportsNativeWebSearch reports whether a request with NativeWebSearch set is served by the provider's own search. Clients that do not say are treated as unable, so a configured fallback search tool can stand in for them.
func SupportsNativeWebSearchForModel ¶ added in v0.107.35
SupportsNativeWebSearchForModel includes model-specific extensions such as DeepSeek Flash's Chat Completions tools. API-only settings remain conservative.
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 Anthropic ¶
type Anthropic struct{ *OpenAI }
func NewAnthropic ¶
func (*Anthropic) SupportsNativeWebSearch ¶ added in v0.107.33
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 ElicitField ¶ added in v0.107.26
type ElicitField struct {
// Name is the property name: the key of the field in the answer content.
Name string `json:"name"`
// Type is "string", "number", "integer", "boolean" or "array". A string
// field with Options is a single choice; an array field is always a
// multiple choice of Options.
Type string `json:"type"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
Required bool `json:"required,omitempty"`
// Default is the value to prefill: a string, number, boolean or, for an
// array field, a list of option values.
Default any `json:"default,omitempty"`
// Format is "email", "uri", "date" or "date-time" (string fields only).
Format string `json:"format,omitempty"`
MinLength *int `json:"min_length,omitempty"`
MaxLength *int `json:"max_length,omitempty"`
// Pattern is a regular expression the whole value must contain a match
// for, as in JSON Schema (unanchored; Go RE2 syntax).
Pattern string `json:"pattern,omitempty"`
Minimum *float64 `json:"minimum,omitempty"`
Maximum *float64 `json:"maximum,omitempty"`
// Options are the choices of a single (string) or multiple (array) choice
// field, in the server's order.
Options []ElicitOption `json:"options,omitempty"`
MinItems *int `json:"min_items,omitempty"`
MaxItems *int `json:"max_items,omitempty"`
// Sensitive marks a free-text field whose name or title reads like a
// secret (password, token, API key...). Clients mask its input and warn;
// K-brain leaves its value out of the journal and history.
Sensitive bool `json:"sensitive,omitempty"`
}
ElicitField is one input of an MCP elicitation form, flattened from the server's requestedSchema (see internal/elicit). The /v1 protocol uses this shape in elicitation.requested and in history.
type ElicitOption ¶ added in v0.107.26
ElicitOption is one choice of an elicitation field. Value goes into the answer; Label is what the user sees (Value when the server gave no title).
type Elicitation ¶ added in v0.107.26
type Elicitation struct {
// ElicitationID is the /v1 elicitation id; empty when the request never
// reached a /v1 client (TUI, or declined without asking).
ElicitationID string `json:"elicitation_id,omitempty"`
// Source is empty for an MCP server and "ssh" for the keyboard-interactive
// login of an SSHManager host (Server is then "ssh:<host name>").
Source string `json:"source,omitempty"`
Server string `json:"server"`
Message string `json:"message"`
Fields []ElicitField `json:"fields"`
// Action is "accept", "decline" or "cancel": what the MCP server received.
Action string `json:"action"`
// Reason says how the action came about: "user", "timeout", "cancelled",
// "no_client", "unattended" or "limit".
Reason string `json:"reason"`
// Content is the accepted answer without the values of Redacted fields.
Content map[string]any `json:"content,omitempty"`
Redacted []string `json:"redacted,omitempty"`
}
Elicitation records one elicitation an MCP server made during a tool call and how it ended, for the call's history. Display only: the model never sees it.
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.
func (*Gemini) SupportsNativeWebSearch ¶ added in v0.107.33
Gemini relays drop google_search whenever function tools are present, so only the official endpoint counts as serving it.
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 NativeWebSearchSupporter ¶ added in v0.107.33
type NativeWebSearchSupporter interface {
SupportsNativeWebSearch() bool
}
NativeWebSearchSupporter is implemented by clients that know whether their API runs provider-native web search. Wrappers forward to the client they route to.
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.
func (*OpenAI) SupportsNativeWebSearch ¶ added in v0.107.33
Chat Completions has no native search request shape.
func (*OpenAI) SupportsNativeWebSearchForModel ¶ added in v0.107.35
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 Responses ¶
type Responses struct{ *OpenAI }
func NewResponses ¶
func (*Responses) SupportsNativeWebSearch ¶ added in v0.107.33
func (*Responses) SupportsNativeWebSearchForModel ¶ added in v0.107.35
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"`
// Elicitations are the forms MCP servers asked the user to fill during
// the call and how each ended; for display.
Elicitations []Elicitation `json:"elicitations,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
- deepseek_functions.go
- deepseek_search.go
- diagnostic_observer.go
- elicitation.go
- factory.go
- gemini.go
- http.go
- images.go
- message.go
- native_search.go
- native_search_support.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