spec

package
v0.6.2 Latest Latest
Warning

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

 Go to latest Published: Jan 21, 2026 License: MIT Imports: 3 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	DefaultAuthorizationHeaderKey = "Authorization"
	DefaultAPITimeout             = 300 * time.Second

	DefaultAnthropicOrigin                 = "https://api.anthropic.com"
	DefaultAnthropicChatCompletionPrefix   = "/v1/messages"
	DefaultAnthropicAuthorizationHeaderKey = "x-api-key"

	DefaultOpenAIOrigin                = "https://api.openai.com"
	DefaultOpenAIChatCompletionsPrefix = "/v1/chat/completions"

	DefaultFileDataMIME  = "application/octet-stream"
	DefaultImageDataMIME = "image/png"
)
View Source 
const DefaultWebSearchToolName string = "webSearchToolChoice"

Variables

View Source 
var OpenAIChatCompletionsDefaultHeaders = map[string]string{"content-type": "application/json"}

Functions

This section is empty.

Types

type CacheControl 

type CacheControl struct {
	Kind CacheControlKind `json:"kind"`

	// Exactly one of the below should be non-nil, depending on Kind.
	CacheControlEphemeral *CacheControlEphemeral `json:"cacheControlEphemeral,omitempty"`
}

type CacheControlEphemeral 

type CacheControlEphemeral struct {
	TTL string `json:"ttl,omitzero"`
}

type CacheControlKind 

type CacheControlKind string
const (
	CacheControlKindEphemeral CacheControlKind = "ephemeral"
)

type Citation 

type Citation struct {
	Kind CitationKind `json:"kind"`

	URLCitation *URLCitation `json:"urlCitation,omitempty"`
}

type CitationConfig 

type CitationConfig struct {
	Enabled bool `json:"enabled"`
}

type CitationKind 

type CitationKind string
const (
	CitationKindURL CitationKind = "urlCitation"
)

type CompletionDebugger 

type CompletionDebugger interface {
	// HTTPClient is called once when the provider initializes its SDK client.
	//
	// The debugger can:
	//   - wrap base (change Transport),
	//   - ignore base and create a new client,
	//   - or return nil to say "use provider's default client".
	HTTPClient(base *http.Client) *http.Client

	// StartSpan is called at the beginning of FetchCompletion.
	//
	// It can:
	//   - inspect the request to decide whether to debug,
	//   - attach per-request state to the context (e.g., via context keys),
	//   - return a span handle that will be ended when the call finishes.
	//
	// If span is nil, no debugging will be performed for this call.
	StartSpan(
		ctx context.Context,
		info *CompletionSpanStart,
	) (ctxWithSpan context.Context, span CompletionSpan)
}

CompletionDebugger is the long-lived "client" object for a provider.

Provider code (e.g., OpenAIResponsesAPI) owns one CompletionDebugger. Callers don't touch this directly.

type CompletionProvider 

type CompletionProvider interface {
	InitLLM(ctx context.Context) error
	DeInitLLM(ctx context.Context) error
	GetProviderInfo(ctx context.Context) *ProviderParam
	IsConfigured(ctx context.Context) bool
	SetProviderAPIKey(ctx context.Context, apiKey string) error
	FetchCompletion(
		ctx context.Context,
		fetchCompletionRequest *FetchCompletionRequest,
		opts *FetchCompletionOptions,
	) (*FetchCompletionResponse, error)
}

type CompletionSpan 

type CompletionSpan interface {
	// End is called exactly once, just before FetchCompletion returns.
	//
	// It can:
	//   - pull any per-request state from the context,
	//   - inspect raw/normalized responses and errors,
	//   - return arbitrary data to attach to Response.DebugDetails.
	//
	// Returning nil means "no debug details for this call".
	End(info *CompletionSpanEnd) any
}

CompletionSpan is the per-request handle. Only provider code sees this; external callers never construct it.

type CompletionSpanEnd 

type CompletionSpanEnd struct {
	// Raw SDK response (e.g. *responses.Response for OpenAI). May be nil.
	ProviderResponse any

	// Error from the provider/stream if any.
	Err error

	// Normalized response object that the caller is about to return.
	// May be nil. MUST be treated as read-only.
	Response *FetchCompletionResponse
}

type CompletionSpanStart 

type CompletionSpanStart struct {
	Provider ProviderName
	Model    ModelName

	// Original request and options for this completion.
	// These may be nil and MUST be treated as read-only.
	Request *FetchCompletionRequest
	Options *FetchCompletionOptions
}

type ContentItemFile 

type ContentItemFile struct {
	ID       string `json:"id,omitzero"`
	FileName string `json:"fileName,omitzero"`
	FileMIME string `json:"fileMIME,omitzero"`
	FileURL  string `json:"fileURL,omitzero"`

	FileData          string          `json:"fileData,omitzero"`
	AdditionalContext string          `json:"additionalContext,omitzero"`
	CitationConfig    *CitationConfig `json:"citationConfig"`
}

type ContentItemImage 

type ContentItemImage struct {
	ID        string      `json:"id,omitzero"`
	Detail    ImageDetail `json:"detail,omitzero"`
	ImageName string      `json:"imageName,omitzero"`
	ImageMIME string      `json:"imageMIME,omitzero"`
	ImageURL  string      `json:"imageURL,omitzero"`
	ImageData string      `json:"imageData,omitzero"`
}

type ContentItemKind 

type ContentItemKind string
const (
	ContentItemKindText    ContentItemKind = "text"
	ContentItemKindImage   ContentItemKind = "image"
	ContentItemKindFile    ContentItemKind = "file"
	ContentItemKindRefusal ContentItemKind = "refusal"
)

type ContentItemRefusal 

type ContentItemRefusal struct {
	Refusal string `json:"refusal"`
}

type ContentItemText 

type ContentItemText struct {
	Text      string     `json:"text"`
	Citations []Citation `json:"citations,omitempty"`
}

type Error 

type Error struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type FetchCompletionOptions 

type FetchCompletionOptions struct {
	// StreamHandler, if non-nil, is invoked with incremental streaming events
	// when ModelParam.Stream is true. Returning a non-nil error will stop
	// streaming early and propagate that error back to the caller.
	StreamHandler StreamHandler `json:"-"`
	StreamConfig  *StreamConfig `json:"streamConfig,omitempty"`
}

FetchCompletionOptions controls optional behaviors for FetchCompletion. A nil pointer is treated the same as &FetchCompletionOptions{}.

type FetchCompletionRequest 

type FetchCompletionRequest struct {
	ModelParam  ModelParam   `json:"modelParam"`
	Inputs      []InputUnion `json:"inputs"`
	ToolChoices []ToolChoice `json:"toolChoices,omitempty"`
}

type FetchCompletionResponse 

type FetchCompletionResponse struct {
	Outputs      []OutputUnion `json:"outputs,omitempty"`
	Usage        *Usage        `json:"usage,omitempty"`
	Error        *Error        `json:"error,omitempty"`
	DebugDetails any           `json:"debugDetails,omitempty"`
}

type ImageDetail 

type ImageDetail string
const (
	ImageDetailHigh ImageDetail = "high"
	ImageDetailLow  ImageDetail = "low"
	ImageDetailAuto ImageDetail = "auto"
)

type InputKind 

type InputKind string
const (
	InputKindInputMessage        InputKind = "inputMessage"
	InputKindOutputMessage       InputKind = "outputMessage"
	InputKindReasoningMessage    InputKind = "reasoningMessage"
	InputKindFunctionToolCall    InputKind = "functionToolCall"
	InputKindFunctionToolOutput  InputKind = "functionToolOutput"
	InputKindCustomToolCall      InputKind = "customToolCall"
	InputKindCustomToolOutput    InputKind = "customToolOutput"
	InputKindWebSearchToolCall   InputKind = "webSearchToolCall"
	InputKindWebSearchToolOutput InputKind = "webSearchToolOutput"
)

type InputOutputContent 

type InputOutputContent struct {
	ID           string        `json:"id"`
	Role         RoleEnum      `json:"role"`
	Status       Status        `json:"status,omitzero"`
	CacheControl *CacheControl `json:"cacheControl,omitempty"`

	Contents []InputOutputContentItemUnion `json:"contents,omitempty"`
}

type InputOutputContentItemUnion 

type InputOutputContentItemUnion struct {
	Kind ContentItemKind `json:"kind"`

	TextItem    *ContentItemText    `json:"textItem,omitempty"`
	RefusalItem *ContentItemRefusal `json:"refusalItem,omitempty"`
	ImageItem   *ContentItemImage   `json:"imageItem,omitempty"`
	FileItem    *ContentItemFile    `json:"fileItem,omitempty"`
}

type InputUnion 

type InputUnion struct {
	Kind InputKind `json:"kind"`

	InputMessage        *InputOutputContent `json:"inputMessage,omitempty"`
	OutputMessage       *InputOutputContent `json:"outputMessage,omitempty"`
	ReasoningMessage    *ReasoningContent   `json:"reasoningMessage,omitempty"`
	FunctionToolCall    *ToolCall           `json:"functionToolCall,omitempty"`
	FunctionToolOutput  *ToolOutput         `json:"functionToolOutput,omitempty"`
	CustomToolCall      *ToolCall           `json:"customToolCall,omitempty"`
	CustomToolOutput    *ToolOutput         `json:"customToolOutput,omitempty"`
	WebSearchToolCall   *ToolCall           `json:"webSearchToolCall,omitempty"`
	WebSearchToolOutput *ToolOutput         `json:"webSearchToolOutput,omitempty"`
}

type ModelName 

type ModelName string

type ModelParam 

type ModelParam struct {
	Name                        ModelName       `json:"name"`
	Stream                      bool            `json:"stream"`
	MaxPromptLength             int             `json:"maxPromptLength"`
	MaxOutputLength             int             `json:"maxOutputLength"`
	Temperature                 *float64        `json:"temperature,omitempty"`
	Reasoning                   *ReasoningParam `json:"reasoning,omitempty"`
	SystemPrompt                string          `json:"systemPrompt"`
	Timeout                     int             `json:"timeout"`
	AdditionalParametersRawJSON *string         `json:"additionalParametersRawJSON"`
}

type OutputKind 

type OutputKind string
const (
	OutputKindOutputMessage       OutputKind = "outputMessage"
	OutputKindReasoningMessage    OutputKind = "reasoningMessage"
	OutputKindFunctionToolCall    OutputKind = "functionToolCall"
	OutputKindCustomToolCall      OutputKind = "customToolCall"
	OutputKindWebSearchToolCall   OutputKind = "webSearchToolCall"
	OutputKindWebSearchToolOutput OutputKind = "webSearchToolOutput"
)

type OutputUnion 

type OutputUnion struct {
	Kind OutputKind `json:"kind"`

	OutputMessage       *InputOutputContent `json:"outputMessage,omitempty"`
	ReasoningMessage    *ReasoningContent   `json:"reasoningMessage,omitempty"`
	FunctionToolCall    *ToolCall           `json:"functionToolCall,omitempty"`
	CustomToolCall      *ToolCall           `json:"customToolCall,omitempty"`
	WebSearchToolCall   *ToolCall           `json:"webSearchToolCall,omitempty"`
	WebSearchToolOutput *ToolOutput         `json:"webSearchToolOutput,omitempty"`
}

type ProviderName 

type ProviderName string

type ProviderParam 

type ProviderParam struct {
	Name                     ProviderName      `json:"name"`
	SDKType                  ProviderSDKType   `json:"sdkType"`
	APIKey                   string            `json:"apiKey"`
	Origin                   string            `json:"origin"`
	ChatCompletionPathPrefix string            `json:"chatCompletionPathPrefix"`
	APIKeyHeaderKey          string            `json:"apiKeyHeaderKey"`
	DefaultHeaders           map[string]string `json:"defaultHeaders"`
}

ProviderParam represents information about a provider.

type ProviderSDKType 

type ProviderSDKType string
const (
	ProviderSDKTypeAnthropic             ProviderSDKType = "providerSDKTypeAnthropicMessages"
	ProviderSDKTypeOpenAIChatCompletions ProviderSDKType = "providerSDKTypeOpenAIChatCompletions"
	ProviderSDKTypeOpenAIResponses       ProviderSDKType = "providerSDKTypeOpenAIResponses"
)

type ReasoningContent 

type ReasoningContent struct {
	ID           string        `json:"id"`
	Role         RoleEnum      `json:"role"`
	Status       Status        `json:"status,omitzero"`
	CacheControl *CacheControl `json:"cacheControl,omitempty"`

	Signature        string   `json:"signature,omitzero"`
	Summary          []string `json:"summary,omitempty"`
	Thinking         []string `json:"thinking,omitempty"`
	RedactedThinking []string `json:"redactedThinking,omitempty"`
	EncryptedContent []string `json:"encryptedContent,omitempty"`
}

type ReasoningLevel 

type ReasoningLevel string
const (
	ReasoningLevelNone    ReasoningLevel = "none"
	ReasoningLevelMinimal ReasoningLevel = "minimal"
	ReasoningLevelLow     ReasoningLevel = "low"
	ReasoningLevelMedium  ReasoningLevel = "medium"
	ReasoningLevelHigh    ReasoningLevel = "high"
	ReasoningLevelXHigh   ReasoningLevel = "xhigh"
)

type ReasoningParam 

type ReasoningParam struct {
	Type   ReasoningType  `json:"type"`
	Level  ReasoningLevel `json:"level"`
	Tokens int            `json:"tokens"`
}

type ReasoningType 

type ReasoningType string
const (
	ReasoningTypeHybridWithTokens ReasoningType = "hybridWithTokens"
	ReasoningTypeSingleWithLevels ReasoningType = "singleWithLevels"
)

type RoleEnum 

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

type Status 

type Status string
const (
	StatusNone       Status = ""
	StatusInProgress Status = "inProgress"
	StatusCompleted  Status = "completed"
	StatusIncomplete Status = "incomplete"
	StatusFailed     Status = "failed"
	StatusCancelled  Status = "cancelled"
	StatusQueued     Status = "queued"
	StatusSearching  Status = "searching"
)

type StreamConfig 

type StreamConfig struct {
	// FlushIntervalMillis is the maximum delay between flushes of buffered stream data to the StreamHandler.
	FlushIntervalMillis int `json:"flushIntervalMillis,omitempty"`
	// FlushChunkSize is the approximate target size (in bytes/characters) for chunks passed to the StreamHandler.
	FlushChunkSize int `json:"flushChunkSize,omitempty"`
}

StreamConfig controls low-level behavior of streaming delivery. All fields are optional; zero values mean "use library defaults".

type StreamContentKind 

type StreamContentKind string

StreamContentKind enumerates the kinds of streaming events that can be delivered while a completion is in progress. 

const (
	StreamContentKindText     StreamContentKind = "text"
	StreamContentKindThinking StreamContentKind = "thinking"
)

type StreamEvent 

type StreamEvent struct {
	Kind StreamContentKind `json:"kind"`

	// Optional metadata to help consumers correlate events across models/providers.
	Provider ProviderName `json:"provider,omitempty"`
	Model    ModelName    `json:"model,omitempty"`

	// Exactly one of the below will be non-nil depending on Kind.
	Text     *StreamTextChunk     `json:"text,omitempty"`
	Thinking *StreamThinkingChunk `json:"thinking,omitempty"`
}

type StreamHandler 

type StreamHandler func(event StreamEvent) error

type StreamTextChunk 

type StreamTextChunk struct {
	Text string `json:"text"`
}

type StreamThinkingChunk 

type StreamThinkingChunk struct {
	Text string `json:"text"`
}

type ToolCall 

type ToolCall struct {
	Type ToolType `json:"type"`

	ChoiceID     string        `json:"choiceID"`
	ID           string        `json:"id"`
	Role         RoleEnum      `json:"role"`
	Status       Status        `json:"status,omitzero"`
	CacheControl *CacheControl `json:"cacheControl,omitempty"`

	CallID                 string                       `json:"callID"`
	Name                   string                       `json:"name"`
	Arguments              string                       `json:"arguments,omitempty"`
	WebSearchToolCallItems []WebSearchToolCallItemUnion `json:"webSearchToolCallItems,omitempty"`
}

type ToolChoice 

type ToolChoice struct {
	Type ToolType `json:"type"`

	ID           string        `json:"id"`
	CacheControl *CacheControl `json:"cacheControl,omitempty"`

	Name        string `json:"name"`
	Description string `json:"description,omitzero"`

	Arguments          map[string]any           `json:"arguments,omitempty"`
	WebSearchArguments *WebSearchToolChoiceItem `json:"webSearchArguments,omitempty"`
}

type ToolOutput 

type ToolOutput struct {
	Type ToolType `json:"type"`

	ChoiceID     string        `json:"choiceID"`
	ID           string        `json:"id"`
	Role         RoleEnum      `json:"role"`
	Status       Status        `json:"status,omitzero"`
	CacheControl *CacheControl `json:"cacheControl,omitempty"`

	CallID    string `json:"callID"`
	Name      string `json:"name"`
	IsError   bool   `json:"isError"`
	Signature string `json:"signature,omitzero"`

	Contents                 []ToolOutputItemUnion          `json:"contents,omitempty"`
	WebSearchToolOutputItems []WebSearchToolOutputItemUnion `json:"webSearchToolOutputItems,omitempty"`
}

type ToolOutputItemUnion 

type ToolOutputItemUnion struct {
	Kind ContentItemKind `json:"kind"`

	TextItem  *ContentItemText  `json:"textItem,omitempty"`
	ImageItem *ContentItemImage `json:"imageItem,omitempty"`
	FileItem  *ContentItemFile  `json:"fileItem,omitempty"`
}

type ToolType 

type ToolType string
const (
	ToolTypeFunction  ToolType = "function"
	ToolTypeCustom    ToolType = "custom"
	ToolTypeWebSearch ToolType = "webSearch"
)

type URLCitation 

type URLCitation struct {
	URL       string `json:"url"`
	Title     string `json:"title,omitzero"`
	CitedText string `json:"citedText,omitzero"`

	StartIndex     int64  `json:"startIndex,omitzero"`
	EndIndex       int64  `json:"endIndex,omitzero"`
	EncryptedIndex string `json:"encryptedIndex,omitzero"`
}

type Usage 

type Usage struct {
	InputTokensTotal    int64 `json:"inputTokensTotal"`
	InputTokensCached   int64 `json:"inputTokensCached"`
	InputTokensUncached int64 `json:"inputTokensUncached"`
	OutputTokens        int64 `json:"outputTokens"`
	ReasoningTokens     int64 `json:"reasoningTokens"`
}

type WebSearchToolCallFind 

type WebSearchToolCallFind struct {
	URL     string `json:"url"`
	Pattern string `json:"pattern"`
}

type WebSearchToolCallItemUnion 

type WebSearchToolCallItemUnion struct {
	Kind WebSearchToolCallKind `json:"kind"`

	SearchItem   *WebSearchToolCallSearch   `json:"searchItem,omitempty"`
	OpenPageItem *WebSearchToolCallOpenPage `json:"openPageItem,omitempty"`
	FindItem     *WebSearchToolCallFind     `json:"findItem,omitempty"`
}

type WebSearchToolCallKind 

type WebSearchToolCallKind string
const (
	WebSearchToolCallKindSearch   WebSearchToolCallKind = "search"
	WebSearchToolCallKindOpenPage WebSearchToolCallKind = "openPage"
	WebSearchToolCallKindFind     WebSearchToolCallKind = "find"
)

type WebSearchToolCallOpenPage 

type WebSearchToolCallOpenPage struct {
	URL string `json:"url"`
}

type WebSearchToolCallSearch 

type WebSearchToolCallSearch struct {
	Query   string                          `json:"query"`
	Sources []WebSearchToolCallSearchSource `json:"sources,omitempty"`
	Input   map[string]any                  `json:"input,omitempty"`
}

type WebSearchToolCallSearchSource 

type WebSearchToolCallSearchSource struct {
	URL string `json:"url"`
}

type WebSearchToolChoiceItem 

type WebSearchToolChoiceItem struct {
	MaxUses           int64                                `json:"max_uses,omitzero"`
	SearchContextSize string                               `json:"searchContextSize,omitzero"`
	AllowedDomains    []string                             `json:"allowed_domains,omitzero"`
	BlockedDomains    []string                             `json:"blocked_domains,omitzero"`
	UserLocation      *WebSearchToolChoiceItemUserLocation `json:"user_location,omitempty"`
}

type WebSearchToolChoiceItemUserLocation 

type WebSearchToolChoiceItemUserLocation struct {
	City     string `json:"city,omitzero"`
	Country  string `json:"country,omitzero"`
	Region   string `json:"region,omitzero"`
	Timezone string `json:"timezone,omitzero"`
}

type WebSearchToolOutputError 

type WebSearchToolOutputError struct {
	Code string `json:"code"`
}

type WebSearchToolOutputItemUnion 

type WebSearchToolOutputItemUnion struct {
	Kind WebSearchToolOutputKind `json:"kind"`

	SearchItem *WebSearchToolOutputSearch `json:"searchItem,omitempty"`
	ErrorItem  *WebSearchToolOutputError  `json:"errorItem,omitempty"`
}

type WebSearchToolOutputKind 

type WebSearchToolOutputKind string
const (
	WebSearchToolOutputKindSearch WebSearchToolOutputKind = "search"
	WebSearchToolOutputKindError  WebSearchToolOutputKind = "error"
)

type WebSearchToolOutputSearch 

type WebSearchToolOutputSearch struct {
	URL              string `json:"url"`
	Title            string `json:"title,omitzero"`
	EncryptedContent string `json:"encryptedContent,omitzero"`
	RenderedContent  string `json:"renderedContent,omitzero"`
	PageAge          string `json:"page_age,omitzero"`
}

Source Files

View all Source files

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.