ai

package
v0.107.24 Latest Latest
Warning

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

Go to latest
Published: Nov 6, 2026 License: Apache-2.0 Imports: 37 Imported by: 0

Documentation

Index

Constants

View Source
const (
	AttachmentImage = "image"
	AttachmentFile  = "file"
)

AttachmentKind names the provider-neutral attachment classes.

View Source
const (
	APIChatCompletions = "openai-completions"
	APIResponses       = "openai-responses"
	APIMessages        = "anthropic-messages"
	APIGemini          = "google-generative-ai"
	APIGoogleGemini    = "google-gemini"
)
View Source
const (
	NormalizeMaxDim = 2000

	NormalizeMaxBytes = 5 * 1024 * 1024

	NormalizeMaxPixels = 64_000_000
)
View Source
const DefaultMaxAttempts = 8
View Source
const ImageTokenFloor = 85
View Source
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

func CacheEndpointHost(endpoint string) string

CacheEndpointHost uses the parsed hostname, never a substring of an untrusted URL.

func ContextLimitFromError added in v0.107.13

func ContextLimitFromError(err error) int

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 DecodeImageSize(data []byte) (w, h int, ok bool)

func ImageTokens

func ImageTokens(w, h int) int

func IsContextLimit

func IsContextLimit(err error) bool

func NormalizeImage

func NormalizeImage(ext string, data []byte) (string, []byte)

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 SupportedAPI(api string) bool

func TruncatedToolCalls added in v0.107.13

func TruncatedToolCalls(msg Message) bool

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 NewAnthropic(baseURL, apiKey string) *Anthropic

func (*Anthropic) Clone

func (c *Anthropic) Clone() Client

func (*Anthropic) Complete

func (c *Anthropic) Complete(ctx context.Context, req Request) (string, Usage, error)

func (*Anthropic) Models

func (c *Anthropic) Models(ctx context.Context) ([]ModelInfo, error)

func (*Anthropic) Stream

func (c *Anthropic) Stream(ctx context.Context, req Request, onText, onThink func(string), onToolCall func(id, name, args string)) (Message, Usage, error)

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

type CacheObservation struct {
	Protocol       string
	ParametersHash string
	MessagesHash   []string
}

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 CacheOptions struct {
	Retention             string
	SessionAffinity       bool
	ControlFormat         string
	SupportsLong          bool
	SupportsKey           *bool
	AffinityFormat        string
	ResponsesCacheOptions bool
}

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 ClientOptions struct {
	API        string
	BaseURL    string
	APIKey     string
	MaxRetries int
	Cache      CacheOptions
	IsFullURL  bool
	ModelsURL  string
	Headers    map[string]string
	UseProxy   bool
}

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 NewGemini added in v0.107.0

func NewGemini(baseURL, apiKey string) *Gemini

func NewGeminiWithOptions added in v0.107.0

func NewGeminiWithOptions(baseURL, apiKey string, isFullURL bool, modelsURL string, headers map[string]string) *Gemini

func (*Gemini) Clone added in v0.107.0

func (c *Gemini) Clone() Client

func (*Gemini) Complete added in v0.107.0

func (c *Gemini) Complete(ctx context.Context, req Request) (string, Usage, error)

func (*Gemini) Endpoint added in v0.107.0

func (c *Gemini) Endpoint() string

func (*Gemini) Models added in v0.107.0

func (c *Gemini) Models(ctx context.Context) ([]ModelInfo, error)

func (*Gemini) SetCacheKey added in v0.107.0

func (c *Gemini) SetCacheKey(string)

func (*Gemini) SetMaxRetries added in v0.107.0

func (c *Gemini) SetMaxRetries(n int)

func (*Gemini) SetOnRetry added in v0.107.0

func (c *Gemini) SetOnRetry(fn func(RetryEvent))

func (*Gemini) SetUseProxy added in v0.107.6

func (c *Gemini) SetUseProxy(on bool)

SetUseProxy selects the proxied or direct transport for this provider.

func (*Gemini) Stream added in v0.107.0

func (c *Gemini) Stream(ctx context.Context, req Request, onText, onThink func(string), onToolCall func(id, name, args string)) (Message, Usage, error)

type HTTPError

type HTTPError struct {
	Status      string
	Body        string
	StatusCode  int
	ShouldRetry string

	RetryAfter    time.Duration
	RetryAfterSet bool
}

func (*HTTPError) Error

func (e *HTTPError) Error() string

type HostedSearch added in v0.107.0

type HostedSearch struct {
	Type     string         `json:"type"`
	ID       string         `json:"id"`
	Provider string         `json:"provider,omitempty"`
	Status   string         `json:"status"`
	Queries  []string       `json:"queries"`
	Sources  []SearchSource `json:"sources"`
	Error    string         `json:"error,omitempty"`
}

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 (m Message) MarshalJSON() ([]byte, error)

func (Message) TextContent

func (m Message) TextContent() string

func (*Message) UnmarshalJSON

func (m *Message) UnmarshalJSON(data []byte) error

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

func (mi ModelInfo) SupportsVision() bool

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 New

func New(baseURL, apiKey string) *OpenAI

func NewWithOptions added in v0.107.0

func NewWithOptions(baseURL, apiKey string, full bool, modelsURL string, headers map[string]string) *OpenAI

func (*OpenAI) Clone

func (c *OpenAI) Clone() Client

func (*OpenAI) Complete

func (c *OpenAI) Complete(ctx context.Context, req Request) (string, Usage, error)

func (*OpenAI) Endpoint

func (c *OpenAI) Endpoint() string

func (*OpenAI) Models

func (c *OpenAI) Models(ctx context.Context) ([]ModelInfo, error)

func (*OpenAI) SetCacheKey

func (c *OpenAI) SetCacheKey(k string)

func (*OpenAI) SetCacheOptions

func (c *OpenAI) SetCacheOptions(o CacheOptions)

func (*OpenAI) SetMaxRetries

func (c *OpenAI) SetMaxRetries(n int)

func (*OpenAI) SetOnRetry

func (c *OpenAI) SetOnRetry(fn func(RetryEvent))

func (*OpenAI) SetUseProxy added in v0.107.6

func (c *OpenAI) SetUseProxy(on bool)

SetUseProxy selects the proxied or direct transport for this provider.

func (*OpenAI) Stream

func (c *OpenAI) Stream(ctx context.Context, req Request, onText, onThink func(string), onToolCall func(id, name, args string)) (Message, Usage, error)

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

type PromptSnapshot struct {
	Source string `json:"source"`
	Text   string `json:"text"`
}

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 NewResponses(baseURL, apiKey string) *Responses

func (*Responses) Clone

func (c *Responses) Clone() Client

func (*Responses) Complete

func (c *Responses) Complete(ctx context.Context, req Request) (string, Usage, error)

func (*Responses) Stream

func (c *Responses) Stream(ctx context.Context, req Request, onText, onThink func(string), onToolCall func(id, name, args string)) (Message, Usage, error)

type RetryEvent

type RetryEvent struct {
	Attempt int
	Max     int
	Delay   time.Duration
	Err     error
}

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 SearchSource struct {
	URL        string `json:"url"`
	Title      string `json:"title,omitempty"`
	SourceType string `json:"sourceType,omitempty"`
}

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"`
}

func NewTool

func NewTool(name, desc, schema string) Tool

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) Add added in v0.103.0

func (u *Usage) Add(other Usage)

func (Usage) CacheWrite

func (u Usage) CacheWrite() int

func (Usage) Cached

func (u Usage) Cached() int

type UsageSummary added in v0.103.0

type UsageSummary struct {
	Total     Usage
	Models    map[string]Usage
	Subagents map[string]Usage
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL