openai

package
v0.0.0-...-a3db3a9 Latest Latest
Warning

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

Go to latest
Published: Aug 25, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DialResponsesWebSocket

func DialResponsesWebSocket(ctx context.Context, accessToken string, opts ...DialOption) (*websocket.Conn, error)

DialResponsesWebSocket connects to the OpenAI Responses API WebSocket endpoint. The returned connection can be passed to WithConn().

Types

type AllowedToolsToolChoice

type AllowedToolsToolChoice struct {
	Type  string `json:"type"`  // "allowed_tools"
	Mode  string `json:"mode"`  // "auto" | "required"
	Tools []any  `json:"tools"` // entries like {type:function,name:...}, {type:custom,name:...}, hosted/mcp, etc.
}

AllowedToolsToolChoice represents the object to constrain allowed tools. Example:

{
  "type": "allowed_tools",
  "mode": "auto", // or "required"
  "tools": [
    {"type": "function", "name": "get_weather"},
    {"type": "custom", "name": "my_custom"}
  ]
}

type Annotation

type Annotation interface {
	// contains filtered or unexported methods
}

Annotation is an interface for different annotation types

type CacheControl

type CacheControl struct {
	Type string `json:"type"`
	TTL  string `json:"ttl,omitempty"`
}

CacheControl represents a cache control directive on a content part.

type ChatAllowedTool

type ChatAllowedTool struct {
	Type     string                 `json:"type"` // "function" | "custom"
	Function *ChatAllowedToolFunc   `json:"function,omitempty"`
	Custom   *ChatAllowedToolCustom `json:"custom,omitempty"`
	// Name is the flat Responses-style reference used for custom tools when
	// the endpoint forwards tool_choice to the Responses API.
	Name string `json:"name,omitempty"`
}

type ChatAllowedToolCustom

type ChatAllowedToolCustom struct {
	Name string `json:"name"`
}

type ChatAllowedToolFunc

type ChatAllowedToolFunc struct {
	Name string `json:"name"`
}

type ChatAllowedToolsChoice

type ChatAllowedToolsChoice struct {
	Type  string            `json:"type"` // "allowed_tools"
	Mode  string            `json:"mode"` // "auto" | "required"
	Tools []ChatAllowedTool `json:"tools"`
}

type ChatCompletionsAPI

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

func New

func New(accessToken, model string) *ChatCompletionsAPI

func NewChatCompletionsAPI

func NewChatCompletionsAPI(accessToken, model string) *ChatCompletionsAPI

func (*ChatCompletionsAPI) BuildPayload

func (m *ChatCompletionsAPI) BuildPayload(
	systemPrompt content.Content,
	messages []llms.Message,
	toolbox *tools.Toolbox,
	jsonOutputSchema *tools.ValueSchema,
) (map[string]any, error)

BuildPayload constructs the request payload without sending it. This is exported so wrapper providers (e.g. OpenRouter) can modify the payload before calling DoRequest.

BuildPayload does not fetch remote audio URLs. Use BuildPayloadWithContext or Generate when content.AudioURL contains an http(s) URL that must be encoded as input_audio.data.

func (*ChatCompletionsAPI) BuildPayloadWithContext

func (m *ChatCompletionsAPI) BuildPayloadWithContext(
	ctx context.Context,
	systemPrompt content.Content,
	messages []llms.Message,
	toolbox *tools.Toolbox,
	jsonOutputSchema *tools.ValueSchema,
) (map[string]any, error)

BuildPayloadWithContext constructs the request payload and resolves http(s) audio URLs to base64 data before encoding the Chat Completions request.

func (*ChatCompletionsAPI) Company

func (m *ChatCompletionsAPI) Company() string

func (*ChatCompletionsAPI) DoRequest

func (m *ChatCompletionsAPI) DoRequest(ctx context.Context, payload map[string]any) llms.ProviderStream

DoRequest sends a pre-built payload and returns a streaming response. This is exported so wrapper providers (e.g. OpenRouter) can build/modify a payload via BuildPayload and then send it.

func (*ChatCompletionsAPI) Generate

func (m *ChatCompletionsAPI) Generate(
	ctx context.Context,
	systemPrompt content.Content,
	messages []llms.Message,
	toolbox *tools.Toolbox,
	jsonOutputSchema *tools.ValueSchema,
) llms.ProviderStream

func (*ChatCompletionsAPI) Model

func (m *ChatCompletionsAPI) Model() string

func (*ChatCompletionsAPI) SetHTTPClient

func (m *ChatCompletionsAPI) SetHTTPClient(client *http.Client)

func (*ChatCompletionsAPI) WithAssistantReasoningReplay

func (m *ChatCompletionsAPI) WithAssistantReasoningReplay() *ChatCompletionsAPI

WithAssistantReasoningReplay encodes assistant Thought items as reasoning_details so they can be replayed on OpenAI-compatible providers that support preserved reasoning continuity.

func (*ChatCompletionsAPI) WithCacheControlPromptHints

func (m *ChatCompletionsAPI) WithCacheControlPromptHints() *ChatCompletionsAPI

WithCacheControlPromptHints encodes CacheHint items as cache_control on content parts instead of using prompt_cache_retention.

func (*ChatCompletionsAPI) WithCustomPayloadValue

func (m *ChatCompletionsAPI) WithCustomPayloadValue(key string, value any) *ChatCompletionsAPI

WithCustomPayloadValue sets a custom key-value pair in the request payload. Use this for provider-specific parameters not covered by other methods. WARNING: Do not override core fields (stream, model, messages) as this will break response parsing or cause unexpected behavior.

func (*ChatCompletionsAPI) WithEndpoint

func (m *ChatCompletionsAPI) WithEndpoint(endpoint, company string) *ChatCompletionsAPI

WithEndpoint sets the endpoint (and company name) so OpenAI-compatible API endpoints can be used.

func (*ChatCompletionsAPI) WithFlatCustomTools

func (m *ChatCompletionsAPI) WithFlatCustomTools() *ChatCompletionsAPI

WithFlatCustomTools declares custom (grammar/text) tools in the flat Responses-API shape — {"type":"custom","name":…,"format":{…}} — instead of Chat Completions' nested {"custom":{…}} wrapper, and references them the same way in tool_choice. Use this for OpenAI-compatible gateways that forward the tools array verbatim into a Responses API request (OpenRouter does; verified live 2026-08-15 — the nested shape is rejected upstream with "Missing required parameter: 'tools[0].name'" while the flat shape gets grammar-constrained decoding).

func (*ChatCompletionsAPI) WithHeader

func (m *ChatCompletionsAPI) WithHeader(key, value string) *ChatCompletionsAPI

WithHeader sets an additional HTTP header on requests made by this client.

func (*ChatCompletionsAPI) WithIncludeUsage

func (m *ChatCompletionsAPI) WithIncludeUsage(include bool) *ChatCompletionsAPI

WithIncludeUsage sets whether to include stream_options.include_usage in requests.

func (*ChatCompletionsAPI) WithMaxCompletionTokens

func (m *ChatCompletionsAPI) WithMaxCompletionTokens(maxCompletionTokens int) *ChatCompletionsAPI

func (*ChatCompletionsAPI) WithPromptCacheRetention

func (m *ChatCompletionsAPI) WithPromptCacheRetention(retention string) *ChatCompletionsAPI

WithPromptCacheRetention enables extended prompt caching with the given retention duration (e.g. "24h") when content contains a "long" cache hint. This is an OpenAI-specific feature.

func (*ChatCompletionsAPI) WithServerTools

func (m *ChatCompletionsAPI) WithServerTools(serverTools ...any) *ChatCompletionsAPI

WithServerTools appends provider-executed tools to the request's tools array, after any function tools from the toolbox. Each entry is marshaled verbatim, so callers pass the provider's exact tool shape (e.g. OpenRouter's {"type": "openrouter:web_search", ...}). Server tools run inside the provider's request loop and never surface as client tool calls, so they are not part of the toolbox and are exempt from tool_choice constraints.

func (*ChatCompletionsAPI) WithThinking

func (m *ChatCompletionsAPI) WithThinking(effort Effort) *ChatCompletionsAPI

func (*ChatCompletionsAPI) WithVerbosity

func (m *ChatCompletionsAPI) WithVerbosity(verbosity Verbosity) *ChatCompletionsAPI

func (*ChatCompletionsAPI) WithoutPromptCacheRetention

func (m *ChatCompletionsAPI) WithoutPromptCacheRetention() *ChatCompletionsAPI

WithoutPromptCacheRetention disables prompt_cache_retention even when content contains a long cache hint.

type ChatCompletionsStream

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

func (*ChatCompletionsStream) Audio

func (s *ChatCompletionsStream) Audio() (string, string)

func (*ChatCompletionsStream) Err

func (s *ChatCompletionsStream) Err() error

func (*ChatCompletionsStream) Image

func (s *ChatCompletionsStream) Image() (string, string)

func (*ChatCompletionsStream) Iter

func (s *ChatCompletionsStream) Iter() func(yield func(llms.StreamStatus) bool)

func (*ChatCompletionsStream) Message

func (s *ChatCompletionsStream) Message() llms.Message

func (*ChatCompletionsStream) Search

Search implements the optional provider-run search capability: one aggregated activity for all citations the stream carried. The query is unknown at this API level — the provider composes it server-side and only the citations surface.

func (*ChatCompletionsStream) Text

func (s *ChatCompletionsStream) Text() string

func (*ChatCompletionsStream) Thought

func (s *ChatCompletionsStream) Thought() content.Thought

func (*ChatCompletionsStream) ToolCall

func (s *ChatCompletionsStream) ToolCall() llms.ToolCall

func (*ChatCompletionsStream) Usage

func (s *ChatCompletionsStream) Usage() llms.Usage

type ChatToolChoice

type ChatToolChoice struct {
	Type     string              `json:"type"` // "function" or "tool"; for string modes, send string directly
	Function *ChatToolChoiceFunc `json:"function,omitempty"`
	Name     string              `json:"name,omitempty"`
}

ChatToolChoice for Chat Completions API https://platform.openai.com/docs/guides/function-calling#additional-configurations Accepts: "none" | "auto" | {"type":"function","function":{"name":string}} | {"type":"tool","name":string}

type ChatToolChoiceFunc

type ChatToolChoiceFunc struct {
	Name string `json:"name"`
}

type ClickAction

type ClickAction struct {
	Type   string `json:"type"` // "click"
	X      int    `json:"x"`
	Y      int    `json:"y"`
	Button string `json:"button"` // "left", "right", "wheel", "back", "forward"
}

ClickAction implements ComputerAction

type CodeInterpreterCall

type CodeInterpreterCall struct {
	Type        string                  `json:"type"` // "code_interpreter_call"
	ID          string                  `json:"id"`
	ContainerID string                  `json:"container_id"`
	Code        *string                 `json:"code"`
	Status      string                  `json:"status"`
	Outputs     []CodeInterpreterOutput `json:"outputs"`
}

CodeInterpreterCall implements ResponseItem

type CodeInterpreterContainerAuto

type CodeInterpreterContainerAuto struct {
	Type    string   `json:"type"` // "auto"
	FileIDs []string `json:"file_ids,omitempty"`
}

CodeInterpreterContainerAuto represents auto container configuration

type CodeInterpreterImage

type CodeInterpreterImage struct {
	Type string `json:"type"` // "image"
	URL  string `json:"url"`
}

CodeInterpreterImage implements CodeInterpreterOutput

type CodeInterpreterLogs

type CodeInterpreterLogs struct {
	Type string `json:"type"` // "logs"
	Logs string `json:"logs"`
}

CodeInterpreterLogs implements CodeInterpreterOutput

type CodeInterpreterOutput

type CodeInterpreterOutput interface {
	// contains filtered or unexported methods
}

CodeInterpreterOutput is an interface for code interpreter outputs

type CodeInterpreterTool

type CodeInterpreterTool struct {
	Type      string `json:"type"`      // "code_interpreter"
	Container any    `json:"container"` // string (container ID) or CodeInterpreterContainerAuto
}

CodeInterpreterTool implements ResponseTool

type ComparisonFilter

type ComparisonFilter struct {
	Type  string `json:"type"` // "eq", "ne", "gt", "gte", "lt", "lte"
	Key   string `json:"key"`
	Value any    `json:"value"` // string, number, or boolean
}

ComparisonFilter implements FileSearchFilter

type CompoundFilter

type CompoundFilter struct {
	Type    string             `json:"type"` // "and", "or"
	Filters []FileSearchFilter `json:"filters"`
}

CompoundFilter implements FileSearchFilter

type ComputerAction

type ComputerAction interface {
	// contains filtered or unexported methods
}

ComputerAction is an interface for computer actions

type ComputerCall

type ComputerCall struct {
	Type                string         `json:"type"` // "computer_call"
	ID                  string         `json:"id"`
	CallID              string         `json:"call_id"`
	Action              ComputerAction `json:"action"`
	Status              string         `json:"status"`
	PendingSafetyChecks []SafetyCheck  `json:"pending_safety_checks"`
}

ComputerCall implements ResponseItem

type ComputerCallOutput

type ComputerCallOutput struct {
	Type                     string         `json:"type"` // "computer_call_output"
	ID                       string         `json:"id,omitempty"`
	CallID                   string         `json:"call_id"`
	Output                   ComputerOutput `json:"output"`
	Status                   string         `json:"status,omitempty"`
	AcknowledgedSafetyChecks []SafetyCheck  `json:"acknowledged_safety_checks,omitempty"`
}

ComputerCallOutput implements ResponseItem

type ComputerOutput

type ComputerOutput struct {
	Type     string `json:"type"` // "computer_screenshot"
	FileID   string `json:"file_id,omitempty"`
	ImageURL string `json:"image_url,omitempty"`
}

ComputerOutput represents computer call output

type ComputerUseTool

type ComputerUseTool struct {
	Type          string `json:"type"` // "computer_use_preview"
	DisplayWidth  int    `json:"display_width"`
	DisplayHeight int    `json:"display_height"`
	Environment   string `json:"environment"`
}

ComputerUseTool implements ResponseTool

type ContainerFileCitation

type ContainerFileCitation struct {
	Type        string `json:"type"` // "container_file_citation"
	ContainerID string `json:"container_id"`
	FileID      string `json:"file_id"`
	Filename    string `json:"filename"`
	StartIndex  int    `json:"start_index"`
	EndIndex    int    `json:"end_index"`
}

ContainerFileCitation implements Annotation

type ContentList

type ContentList []ContentPart

ContentList is a list of content parts with custom JSON marshaling.

func ConvertContent

func ConvertContent(c content.Content) ContentList

ConvertContent converts content.Content to a ContentList for the OpenAI API. CacheHint and Thought items are skipped by default.

func ConvertContentWithOptions

func ConvertContentWithOptions(c content.Content, opts chatMessageEncodingOptions) ContentList

ConvertContentWithOptions converts content.Content to a ContentList for the OpenAI-compatible Chat Completions API, with optional provider-specific encodings such as cache_control on content parts.

func (ContentList) MarshalJSON

func (cl ContentList) MarshalJSON() ([]byte, error)

func (*ContentList) UnmarshalJSON

func (cl *ContentList) UnmarshalJSON(data []byte) error

type ContentPart

type ContentPart struct {
	Type         string        `json:"type"`
	Text         *string       `json:"text,omitempty"`
	ImageURL     *imageURL     `json:"image_url,omitempty"`
	InputAudio   *inputAudio   `json:"input_audio,omitempty"`
	VideoURL     *videoURL     `json:"video_url,omitempty"`
	CacheControl *CacheControl `json:"cache_control,omitempty"`
}

ContentPart represents a single part of a message's content array.

type CustomToolCall

type CustomToolCall struct {
	Type   string `json:"type"` // "custom_tool_call"
	ID     string `json:"id,omitempty"`
	Name   string `json:"name"`
	Input  string `json:"input"`
	CallID string `json:"call_id"`
	Status string `json:"status,omitempty"` // "in_progress", "completed", "incomplete"
}

CustomToolCall implements ResponseItem for custom tools (grammar/text tools)

type CustomToolCallOutput

type CustomToolCallOutput struct {
	Type   string `json:"type"` // "custom_tool_call_output"
	ID     string `json:"id,omitempty"`
	CallID string `json:"call_id"`
	Output string `json:"output"`
}

CustomToolCallOutput implements ResponseInput for the result of a custom (grammar/text) tool call. The Responses API requires this item type when the call was a custom_tool_call; a function_call_output paired with a custom call is rejected.

type CustomToolSchema

type CustomToolSchema struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Format      map[string]any `json:"format,omitempty"`
}

type DialOption

type DialOption func(*dialConfig)

DialOption configures DialResponsesWebSocket.

func WithDialEndpoint

func WithDialEndpoint(endpoint string) DialOption

WithDialEndpoint overrides the default WebSocket endpoint.

type Effort

type Effort string
const (
	// EffortNone disables reasoning entirely. The GPT-5.x reasoning
	// family (5.2, 5.4, 5.5, …) accepts it; the older o-series /
	// gpt-5 generation expose EffortMinimal as their lightest tier
	// instead. Which one a given model accepts is documented on its
	// model page; OpenAI returns a 400 if you send the wrong one.
	EffortNone    Effort = "none"
	EffortMinimal Effort = "minimal"
	EffortLow     Effort = "low"
	EffortMedium  Effort = "medium"
	EffortHigh    Effort = "high"
	EffortXHigh   Effort = "xhigh"
)

type FileCitation

type FileCitation struct {
	Type     string `json:"type"` // "file_citation"
	FileID   string `json:"file_id"`
	Filename string `json:"filename"`
	Index    int    `json:"index"`
}

FileCitation implements Annotation

type FilePath

type FilePath struct {
	Type   string `json:"type"` // "file_path"
	FileID string `json:"file_id"`
	Index  int    `json:"index"`
}

FilePath implements Annotation

type FileSearchCall

type FileSearchCall struct {
	Type    string             `json:"type"` // "file_search_call"
	ID      string             `json:"id"`
	Queries []string           `json:"queries"`
	Status  string             `json:"status"` // "in_progress", "searching", "incomplete", "failed"
	Results []FileSearchResult `json:"results,omitempty"`
}

FileSearchCall implements ResponseItem

type FileSearchFilter

type FileSearchFilter interface {
	// contains filtered or unexported methods
}

FileSearchFilter is an interface for file search filters

type FileSearchResult

type FileSearchResult struct {
	FileID     string            `json:"file_id,omitempty"`
	Filename   string            `json:"filename,omitempty"`
	Score      float64           `json:"score,omitempty"`
	Text       string            `json:"text,omitempty"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

FileSearchResult represents a file search result

type FileSearchTool

type FileSearchTool struct {
	Type           string            `json:"type"` // "file_search"
	VectorStoreIDs []string          `json:"vector_store_ids"`
	Filters        *FileSearchFilter `json:"filters,omitempty"`
	MaxNumResults  *int              `json:"max_num_results,omitempty"`
	RankingOptions *RankingOptions   `json:"ranking_options,omitempty"`
}

FileSearchTool implements ResponseTool

type FindAction

type FindAction struct {
	Type    string `json:"type"` // "find"
	Pattern string `json:"pattern"`
	URL     string `json:"url"`
}

FindAction implements WebSearchAction

type FunctionCall

type FunctionCall struct {
	Type      string `json:"type"` // "function_call"
	ID        string `json:"id,omitempty"`
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
	CallID    string `json:"call_id"`
	Status    string `json:"status,omitempty"` // "in_progress", "completed", "incomplete"
}

FunctionCall implements ResponseItem for function calls

type FunctionCallOutput

type FunctionCallOutput struct {
	Type   string `json:"type"` // "function_call_output"
	ID     string `json:"id,omitempty"`
	CallID string `json:"call_id"`
	Output string `json:"output"`
	Status string `json:"status,omitempty"` // "in_progress", "completed", "incomplete"
}

FunctionCallOutput implements ResponseInput and ResponseItem

type FunctionTool

type FunctionTool struct {
	Type        string             `json:"type"` // "function"
	Name        string             `json:"name"`
	Description string             `json:"description,omitempty"`
	Parameters  *tools.ValueSchema `json:"parameters"`
	Strict      bool               `json:"strict"`
}

FunctionTool implements ResponseTool

type FunctionToolChoice

type FunctionToolChoice struct {
	Type string `json:"type"` // "function"
	Name string `json:"name"`
}

FunctionToolChoice represents a function tool choice

type HostedToolChoice

type HostedToolChoice struct {
	Type string `json:"type"` // file_search, web_search_preview, computer_use_preview, code_interpreter, image_generation
}

HostedToolChoice represents a hosted tool choice

type ImageGenerationCall

type ImageGenerationCall struct {
	Type   string  `json:"type"` // "image_generation_call"
	ID     string  `json:"id"`
	Status string  `json:"status,omitempty"`
	Result *string `json:"result,omitempty"` // base64 encoded image
}

ImageGenerationCall implements ResponseItem

type ImageGenerationTool

type ImageGenerationTool struct {
	Type              string          `json:"type"`                         // "image_generation"
	Model             string          `json:"model,omitempty"`              // default: "gpt-image-1"
	Quality           string          `json:"quality,omitempty"`            // "low", "medium", "high", "auto"
	Size              string          `json:"size,omitempty"`               // "1024x1024", "1024x1536", "1536x1024", "auto"
	OutputFormat      string          `json:"output_format,omitempty"`      // "png", "webp", "jpeg"
	OutputCompression int             `json:"output_compression,omitempty"` // default: 100
	Background        string          `json:"background,omitempty"`         // "transparent", "opaque", "auto"
	Moderation        string          `json:"moderation,omitempty"`         // default: "auto"
	PartialImages     int             `json:"partial_images,omitempty"`     // 0-3, default: 0
	InputImageMask    *InputImageMask `json:"input_image_mask,omitempty"`
}

ImageGenerationTool implements ResponseTool

type InputContent

type InputContent interface {
	// contains filtered or unexported methods
}

InputContent is an interface for content types within messages

type InputFile

type InputFile struct {
	Type     string `json:"type"` // "input_file"
	FileID   string `json:"file_id,omitempty"`
	FileData string `json:"file_data,omitempty"`
	Filename string `json:"filename,omitempty"`
}

InputFile implements InputContent for file content

type InputImage

type InputImage struct {
	Type     string `json:"type"` // "input_image"
	ImageURL string `json:"image_url,omitempty"`
	FileID   string `json:"file_id,omitempty"`
	Detail   string `json:"detail"` // "high", "low", "auto"
}

InputImage implements InputContent for image content

type InputImageMask

type InputImageMask struct {
	FileID   string `json:"file_id,omitempty"`
	ImageURL string `json:"image_url,omitempty"`
}

InputImageMask represents an image mask for inpainting

type InputMessage

type InputMessage struct {
	Type    string         `json:"type"` // "message"
	Role    string         `json:"role"` // "user", "assistant", "system", "developer"
	Content []InputContent `json:"content,omitempty"`
	Status  string         `json:"status,omitempty"` // "in_progress", "completed", "incomplete"
	ID      string         `json:"id,omitempty"`
}

InputMessage implements ResponseInput for message input

type InputText

type InputText struct {
	Type string `json:"type"` // "input_text"
	Text string `json:"text"`
}

InputText implements InputContent for text content

type InputTokensDetails

type InputTokensDetails struct {
	CachedTokens int `json:"cached_tokens"`
}

InputTokensDetails represents input token details Note: Similar to ChatCompletions API but with fewer fields

type ItemReference

type ItemReference struct {
	Type string `json:"type,omitempty"` // "item_reference"
	ID   string `json:"id"`
}

ItemReference implements ResponseItem

type LocalShellAction

type LocalShellAction struct {
	Type             string            `json:"type"` // "exec"
	Command          []string          `json:"command"`
	Env              map[string]string `json:"env"`
	TimeoutMs        *int              `json:"timeout_ms,omitempty"`
	User             *string           `json:"user,omitempty"`
	WorkingDirectory *string           `json:"working_directory,omitempty"`
}

LocalShellAction represents a local shell action

type LocalShellCall

type LocalShellCall struct {
	Type   string           `json:"type"` // "local_shell_call"
	ID     string           `json:"id"`
	CallID string           `json:"call_id"`
	Action LocalShellAction `json:"action"`
	Status string           `json:"status"`
}

LocalShellCall implements ResponseItem

type LocalShellCallOutput

type LocalShellCallOutput struct {
	Type   string  `json:"type"` // "local_shell_call_output"
	ID     string  `json:"id"`
	Output string  `json:"output"`
	Status *string `json:"status,omitempty"`
}

LocalShellCallOutput implements ResponseItem

type LocalShellTool

type LocalShellTool struct {
	Type string `json:"type"` // "local_shell"
}

LocalShellTool implements ResponseTool

type Logprob

type Logprob struct {
	Token       string       `json:"token"`
	Logprob     float64      `json:"logprob"`
	Bytes       []int        `json:"bytes"`
	TopLogprobs []TopLogprob `json:"top_logprobs"`
}

Logprob represents log probability information

type MCPApprovalRequest

type MCPApprovalRequest struct {
	Type        string `json:"type"` // "mcp_approval_request"
	ID          string `json:"id"`
	Name        string `json:"name"`
	Arguments   string `json:"arguments"`
	ServerLabel string `json:"server_label"`
}

MCPApprovalRequest implements ResponseItem

type MCPApprovalResponse

type MCPApprovalResponse struct {
	Type              string  `json:"type"` // "mcp_approval_response"
	ID                *string `json:"id,omitempty"`
	ApprovalRequestID string  `json:"approval_request_id"`
	Approve           bool    `json:"approve"`
	Reason            *string `json:"reason,omitempty"`
}

MCPApprovalResponse implements ResponseItem

type MCPCall

type MCPCall struct {
	Type        string  `json:"type"` // "mcp_call"
	ID          string  `json:"id"`
	Name        string  `json:"name"`
	Arguments   string  `json:"arguments"`
	ServerLabel string  `json:"server_label"`
	Output      *string `json:"output,omitempty"`
	Error       *string `json:"error,omitempty"`
}

MCPCall implements ResponseItem

type MCPListTools

type MCPListTools struct {
	Type        string    `json:"type"` // "mcp_list_tools"
	ID          string    `json:"id"`
	ServerLabel string    `json:"server_label"`
	Tools       []MCPTool `json:"tools"`
	Error       *string   `json:"error,omitempty"`
}

MCPListTools implements ResponseItem

type MCPTool

type MCPTool struct {
	Name        string         `json:"name"`
	InputSchema map[string]any `json:"input_schema"`
	Description *string        `json:"description,omitempty"`
	Annotations map[string]any `json:"annotations,omitempty"`
}

MCPTool represents an MCP tool

type MCPToolChoice

type MCPToolChoice struct {
	Type        string  `json:"type"` // "mcp"
	ServerLabel string  `json:"server_label"`
	Name        *string `json:"name,omitempty"`
}

MCPToolChoice represents an MCP tool choice

type MCPToolConfig

type MCPToolConfig struct {
	Type            string            `json:"type"` // "mcp"
	ServerLabel     string            `json:"server_label"`
	ServerURL       string            `json:"server_url"`
	Headers         map[string]string `json:"headers,omitempty"`
	AllowedTools    any               `json:"allowed_tools,omitempty"`    // array of strings or filter object
	RequireApproval any               `json:"require_approval,omitempty"` // string ("always", "never") or filter object
}

MCPToolConfig implements ResponseTool

type Message

type Message struct {
	Role             string            `json:"role"`
	Content          ContentList       `json:"content,omitempty"`
	ReasoningDetails []ReasoningDetail `json:"reasoning_details,omitempty"`
	ToolCalls        []toolCall        `json:"tool_calls,omitempty"`
	ToolCallID       string            `json:"tool_call_id,omitempty"`
}

Message represents a chat message in the OpenAI API format.

func MessagesFromLLM

func MessagesFromLLM(m llms.Message) []Message

MessagesFromLLM converts an llms.Message to the OpenAI API message format. It may return multiple messages if the input is a tool result with auxiliary content.

func MessagesFromLLMWithOptions

func MessagesFromLLMWithOptions(m llms.Message, opts chatMessageEncodingOptions) []Message

MessagesFromLLMWithOptions converts an llms.Message to the OpenAI-compatible chat message format with optional provider-specific encodings.

type OpenPageAction

type OpenPageAction struct {
	Type string `json:"type"` // "open_page"
	URL  string `json:"url"`
}

OpenPageAction implements WebSearchAction

type OutputContent

type OutputContent interface {
	// contains filtered or unexported methods
}

OutputContent is an interface for output content types

type OutputMessage

type OutputMessage struct {
	Type    string          `json:"type"` // "message"
	ID      string          `json:"id,omitempty"`
	Role    string          `json:"role"`             // "assistant"
	Status  string          `json:"status,omitempty"` // "in_progress", "completed", "incomplete"
	Content []OutputContent `json:"content"`
	Phase   string          `json:"phase,omitempty"` // "commentary", "final_answer"
}

OutputMessage implements ResponseItem for output messages

type OutputText

type OutputText struct {
	Type        string       `json:"type"` // "output_text"
	Text        string       `json:"text"`
	Annotations []Annotation `json:"annotations,omitempty"`
	Logprobs    []Logprob    `json:"logprobs,omitempty"`
}

OutputText implements OutputContent for text output

type OutputTokensDetails

type OutputTokensDetails struct {
	ReasoningTokens int `json:"reasoning_tokens"`
}

OutputTokensDetails represents output token details Note: Similar to ChatCompletions API but with fewer fields

type RankingOptions

type RankingOptions struct {
	Ranker         string  `json:"ranker,omitempty"`
	ScoreThreshold float64 `json:"score_threshold,omitempty"`
}

RankingOptions represents ranking options for file search

type RawTool

type RawTool struct {
	Body any
}

RawTool is a ResponseTool whose JSON body is provided verbatim by the caller. It exists so callers can express provider-specific server-side tools that go-llms does not model with a dedicated type — for example xAI's "web_search" and "x_search" Agent Tools. Body is marshaled as-is into the request's "tools" array, so it must include the tool's "type" discriminator.

func (RawTool) MarshalJSON

func (t RawTool) MarshalJSON() ([]byte, error)

type Reasoning

type Reasoning struct {
	Type             string             `json:"type"` // "reasoning"
	ID               string             `json:"id"`
	Summary          []ReasoningSummary `json:"summary"`
	Status           string             `json:"status,omitempty"` // "in_progress", "completed", "incomplete"
	EncryptedContent string             `json:"encrypted_content,omitempty"`
}

Reasoning implements ResponseItem for reasoning

type ReasoningConfig

type ReasoningConfig struct {
	Effort          string  `json:"effort,omitempty"`           // "low", "medium", "high", "xhigh"
	Summary         *string `json:"summary,omitempty"`          // "auto", "concise", "detailed"
	GenerateSummary *string `json:"generate_summary,omitempty"` // deprecated
}

ReasoningConfig represents reasoning configuration

type ReasoningDetail

type ReasoningDetail struct {
	Type      string `json:"type"`                // "reasoning.summary", "reasoning.text", or "reasoning.encrypted"
	ID        string `json:"id,omitempty"`        // stable identifier for replaying a logical reasoning block
	Summary   string `json:"summary,omitempty"`   // summary text for reasoning.summary blocks
	Text      string `json:"text,omitempty"`      // reasoning text (streamed per chunk)
	Data      string `json:"data,omitempty"`      // opaque encrypted reasoning token, replayed verbatim
	Signature string `json:"signature,omitempty"` // Anthropic signature (final chunk only)
	Format    string `json:"format,omitempty"`    // e.g. "anthropic-claude-v1"
	Index     *int   `json:"index,omitempty"`
}

ReasoningDetail represents a reasoning token entry from providers that stream thinking via the OpenAI-compatible format (e.g. OpenRouter).

type ReasoningSummary

type ReasoningSummary struct {
	Type string `json:"type"` // "summary_text"
	Text string `json:"text"`
}

ReasoningSummary represents reasoning summary content

type Refusal

type Refusal struct {
	Type    string `json:"type"` // "refusal"
	Refusal string `json:"refusal"`
}

Refusal implements OutputContent for refusals

type ResponseInput

type ResponseInput interface {
	// contains filtered or unexported methods
}

ResponseInput is an interface for all input types

type ResponseItem

type ResponseItem interface {
	// contains filtered or unexported methods
}

ResponseItem is a generic interface for response items

type ResponseStreamEvent

type ResponseStreamEvent struct {
	Type           string `json:"type"`
	SequenceNumber int    `json:"sequence_number"`

	// response.created, response.in_progress, response.completed, response.failed, response.incomplete, response.queued
	Response json.RawMessage `json:"response,omitempty"`

	// response.output_item.added/done
	Item        json.RawMessage `json:"item,omitempty"`
	OutputIndex *int            `json:"output_index,omitempty"`

	// content_part events
	ContentIndex *int            `json:"content_index,omitempty"`
	ItemID       string          `json:"item_id,omitempty"`
	Part         json.RawMessage `json:"part,omitempty"`

	// delta events
	Delta json.RawMessage `json:"delta,omitempty"`

	// .done events
	Arguments string `json:"arguments,omitempty"` // function_call_arguments.done
	Text      string `json:"text,omitempty"`      // output_text.done
	Refusal   string `json:"refusal,omitempty"`   // refusal.done
	Code      string `json:"code,omitempty"`      // code_interpreter_call_code.done

	// error event
	Error *StreamError `json:"error,omitempty"`

	// usage event
	Usage *responsesUsage `json:"usage,omitempty"`

	// other fields for specific events
	Annotation      json.RawMessage `json:"annotation,omitempty"`
	AnnotationIndex *int            `json:"annotation_index,omitempty"`
}

ResponseStreamEvent represents a streaming event from the Responses API.

type ResponseTool

type ResponseTool interface {
	// contains filtered or unexported methods
}

ResponseTool is an interface for all tool types

type ResponsesAPI

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

func NewResponsesAPI

func NewResponsesAPI(accessToken, model string) *ResponsesAPI

func (*ResponsesAPI) Company

func (m *ResponsesAPI) Company() string

func (*ResponsesAPI) Generate

func (m *ResponsesAPI) Generate(
	ctx context.Context,
	systemPrompt content.Content,
	messages []llms.Message,
	toolbox *tools.Toolbox,
	jsonOutputSchema *tools.ValueSchema,
) llms.ProviderStream

func (*ResponsesAPI) Model

func (m *ResponsesAPI) Model() string

func (*ResponsesAPI) SetHTTPClient

func (m *ResponsesAPI) SetHTTPClient(client *http.Client)

func (*ResponsesAPI) WithEndpoint

func (m *ResponsesAPI) WithEndpoint(endpoint, company string) *ResponsesAPI

WithEndpoint sets the endpoint (and company name) so OpenAI-compatible API endpoints can be used.

func (*ResponsesAPI) WithMaxOutputTokens

func (m *ResponsesAPI) WithMaxOutputTokens(maxOutputTokens int) *ResponsesAPI

func (*ResponsesAPI) WithMetadata

func (m *ResponsesAPI) WithMetadata(metadata map[string]string) *ResponsesAPI

func (*ResponsesAPI) WithParallelToolCalls

func (m *ResponsesAPI) WithParallelToolCalls(parallel bool) *ResponsesAPI

func (*ResponsesAPI) WithPreviousResponseID

func (m *ResponsesAPI) WithPreviousResponseID(id string) *ResponsesAPI

func (*ResponsesAPI) WithPromptCacheKey

func (m *ResponsesAPI) WithPromptCacheKey(key string) *ResponsesAPI

func (*ResponsesAPI) WithServiceTier

func (m *ResponsesAPI) WithServiceTier(tier string) *ResponsesAPI

func (*ResponsesAPI) WithStore

func (m *ResponsesAPI) WithStore(store bool) *ResponsesAPI

func (*ResponsesAPI) WithTemperature

func (m *ResponsesAPI) WithTemperature(temperature float64) *ResponsesAPI

func (*ResponsesAPI) WithThinking

func (m *ResponsesAPI) WithThinking(effort Effort) *ResponsesAPI

func (*ResponsesAPI) WithTool

func (m *ResponsesAPI) WithTool(tool ResponseTool) *ResponsesAPI

func (*ResponsesAPI) WithTopLogprobs

func (m *ResponsesAPI) WithTopLogprobs(topLogprobs int) *ResponsesAPI

func (*ResponsesAPI) WithTopP

func (m *ResponsesAPI) WithTopP(topP float64) *ResponsesAPI

func (*ResponsesAPI) WithTruncation

func (m *ResponsesAPI) WithTruncation(truncation string) *ResponsesAPI

func (*ResponsesAPI) WithUser

func (m *ResponsesAPI) WithUser(user string) *ResponsesAPI

func (*ResponsesAPI) WithVerbosity

func (m *ResponsesAPI) WithVerbosity(verbosity Verbosity) *ResponsesAPI

type ResponsesStream

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

func (*ResponsesStream) Audio

func (s *ResponsesStream) Audio() (string, string)

func (*ResponsesStream) Err

func (s *ResponsesStream) Err() error

func (*ResponsesStream) Image

func (s *ResponsesStream) Image() (string, string)

func (*ResponsesStream) Iter

func (s *ResponsesStream) Iter() func(yield func(llms.StreamStatus) bool)

func (*ResponsesStream) Message

func (s *ResponsesStream) Message() llms.Message

func (*ResponsesStream) Search

func (s *ResponsesStream) Search() llms.SearchActivity

Search returns the most recently completed provider-run search (web_search / x_search), read by the turn loop when it sees StreamStatusSearch.

func (*ResponsesStream) Text

func (s *ResponsesStream) Text() string

func (*ResponsesStream) Thought

func (s *ResponsesStream) Thought() content.Thought

func (*ResponsesStream) ToolArgumentFinalization

func (s *ResponsesStream) ToolArgumentFinalization() (json.RawMessage, bool)

ToolArgumentFinalization returns the independent provider-final argument snapshot for the active function call, when the protocol expects one.

func (*ResponsesStream) ToolCall

func (s *ResponsesStream) ToolCall() llms.ToolCall

func (*ResponsesStream) Usage

func (s *ResponsesStream) Usage() llms.Usage

type ResponsesToolChoice

type ResponsesToolChoice struct {
	Type     string                       `json:"type"`
	Function *ResponsesToolChoiceFunction `json:"function,omitempty"`
}

ResponsesToolChoice is a strongly-typed struct for forcing tool use in the Responses API. For function tools, the shape is: {"type":"function","function":{"name":"tool_name"}}

type ResponsesToolChoiceFunction

type ResponsesToolChoiceFunction struct {
	Name string `json:"name"`
}

type SafetyCheck

type SafetyCheck struct {
	ID      string `json:"id"`
	Code    string `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
}

SafetyCheck represents a safety check

type ScreenshotAction

type ScreenshotAction struct {
	Type string `json:"type"` // "screenshot"
}

ScreenshotAction implements ComputerAction

type SearchAction

type SearchAction struct {
	Type  string `json:"type"` // "search"
	Query string `json:"query"`
}

SearchAction implements WebSearchAction

type StreamError

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

StreamError represents an error object in the stream.

type TextInput

type TextInput string

TextInput implements ResponseInput for simple text input

type TextResponseFormat

type TextResponseFormat struct {
	Type        string             `json:"type"`                  // "text", "json_object", "json_schema"
	Name        string             `json:"name,omitempty"`        // only for Type == "json_schema"
	Schema      *tools.ValueSchema `json:"schema,omitempty"`      // only for Type == "json_schema"
	Description string             `json:"description,omitempty"` // only for Type == "json_schema"
	Strict      bool               `json:"strict,omitempty"`      // only for Type == "json_schema"
}

TextResponseFormat represents the text response format configuration.

type Tool

type Tool struct {
	Type     string                `json:"type"`
	Function *tools.FunctionSchema `json:"function,omitempty"`
	Custom   *CustomToolSchema     `json:"custom,omitempty"`

	// Flat Responses-style custom tool declaration, used instead of Custom
	// when the endpoint forwards the tools array to the Responses API (see
	// WithFlatCustomTools). Empty for nested declarations.
	Name        string         `json:"name,omitempty"`
	Description string         `json:"description,omitempty"`
	Format      map[string]any `json:"format,omitempty"`
}

func Tools

func Tools(toolbox *tools.Toolbox) []Tool

type ToolChoice

type ToolChoice any

ToolChoice can be a string or an object (keep for backwards compatibility where needed)

type TopLogprob

type TopLogprob struct {
	Token   string  `json:"token"`
	Logprob float64 `json:"logprob"`
	Bytes   []int   `json:"bytes"`
}

TopLogprob represents top log probabilities

type TypeAction

type TypeAction struct {
	Type string `json:"type"` // "type"
	Text string `json:"text"`
}

TypeAction implements ComputerAction

type URLCitation

type URLCitation struct {
	Type       string `json:"type"` // "url_citation"
	URL        string `json:"url"`
	Title      string `json:"title"`
	StartIndex int    `json:"start_index"`
	EndIndex   int    `json:"end_index"`
}

URLCitation implements Annotation

type UserLocation

type UserLocation struct {
	Type     string `json:"type"` // "approximate"
	City     string `json:"city,omitempty"`
	Country  string `json:"country,omitempty"`
	Region   string `json:"region,omitempty"`
	Timezone string `json:"timezone,omitempty"`
}

UserLocation represents user location for web search

type Verbosity

type Verbosity string
const (
	VerbosityLow    Verbosity = "low"
	VerbosityMedium Verbosity = "medium"
	VerbosityHigh   Verbosity = "high"
)

type WebSearchAction

type WebSearchAction interface {
	// contains filtered or unexported methods
}

WebSearchAction is an interface for web search actions

type WebSearchCall

type WebSearchCall struct {
	Type   string          `json:"type"` // "web_search_call"
	ID     string          `json:"id"`
	Status string          `json:"status"`
	Action WebSearchAction `json:"action"`
}

WebSearchCall implements ResponseItem

type WebSearchTool

type WebSearchTool struct {
	Type              string        `json:"type"`                          // "web_search_preview" or "web_search_preview_2025_03_11"
	SearchContextSize string        `json:"search_context_size,omitempty"` // "low", "medium", "high"
	UserLocation      *UserLocation `json:"user_location,omitempty"`
}

WebSearchTool implements ResponseTool

type WebSocketResponsesAPI

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

WebSocketResponsesAPI implements llms.Provider using the OpenAI Responses API over a persistent WebSocket connection. This reduces per-turn overhead in tool-heavy workflows by keeping a connection open and using previous_response_id to send only incremental input.

func NewWebSocketResponsesAPI

func NewWebSocketResponsesAPI(accessToken, model string) *WebSocketResponsesAPI

NewWebSocketResponsesAPI creates a new WebSocket-based provider for the OpenAI Responses API. The WebSocket connection is established lazily on the first Generate() call. Call Close() when done.

func (*WebSocketResponsesAPI) Close

func (m *WebSocketResponsesAPI) Close() error

Close closes the WebSocket connection. If the connection was provided externally via WithConn, this is a no-op.

func (*WebSocketResponsesAPI) Company

func (m *WebSocketResponsesAPI) Company() string

func (*WebSocketResponsesAPI) Generate

func (m *WebSocketResponsesAPI) Generate(
	ctx context.Context,
	systemPrompt content.Content,
	messages []llms.Message,
	toolbox *tools.Toolbox,
	jsonOutputSchema *tools.ValueSchema,
) llms.ProviderStream

Generate sends a request over the WebSocket and returns a stream of events. Callers must fully iterate (or abandon via context cancellation) one stream before calling Generate again, as they share the same WebSocket connection.

func (*WebSocketResponsesAPI) Model

func (m *WebSocketResponsesAPI) Model() string

func (*WebSocketResponsesAPI) ResetChain

func (m *WebSocketResponsesAPI) ResetChain()

ResetChain clears the chaining state so the next Generate() sends a full payload. Use this when starting a new conversation on the same connection.

func (*WebSocketResponsesAPI) SetHTTPClient

func (m *WebSocketResponsesAPI) SetHTTPClient(_ *http.Client)

func (*WebSocketResponsesAPI) Warmup

func (m *WebSocketResponsesAPI) Warmup(ctx context.Context, instructions string, toolbox *tools.Toolbox) (string, error)

Warmup sends a request with generate:false over the WebSocket, which pre-loads tools and instructions on the server side. Returns the response ID that can be used for faster first turns. The provided context should have a timeout to avoid blocking indefinitely.

Warmup must not be called concurrently with Generate or while a stream from Generate is being iterated, as they share the same WebSocket connection.

func (*WebSocketResponsesAPI) WithConn

WithConn sets an externally managed WebSocket connection. The provider will not close this connection when Close() is called.

func (*WebSocketResponsesAPI) WithDebugger

WithDebugger sets a default debugger for this provider. It is used by Warmup and Generate as a fallback when the context does not already carry a debugger (via llms.WithDebugger). When used through LLM.WithDebugger, the debugger is injected into the context automatically, so calling this method is only necessary when invoking Warmup or Generate directly on the provider.

func (*WebSocketResponsesAPI) WithEndpoint

func (m *WebSocketResponsesAPI) WithEndpoint(endpoint, company string) *WebSocketResponsesAPI

WithEndpoint sets the WebSocket endpoint and company name.

func (*WebSocketResponsesAPI) WithMaxOutputTokens

func (m *WebSocketResponsesAPI) WithMaxOutputTokens(n int) *WebSocketResponsesAPI

func (*WebSocketResponsesAPI) WithMetadata

func (m *WebSocketResponsesAPI) WithMetadata(metadata map[string]string) *WebSocketResponsesAPI

func (*WebSocketResponsesAPI) WithParallelToolCalls

func (m *WebSocketResponsesAPI) WithParallelToolCalls(parallel bool) *WebSocketResponsesAPI

func (*WebSocketResponsesAPI) WithPromptCacheKey

func (m *WebSocketResponsesAPI) WithPromptCacheKey(key string) *WebSocketResponsesAPI

func (*WebSocketResponsesAPI) WithServiceTier

func (m *WebSocketResponsesAPI) WithServiceTier(tier string) *WebSocketResponsesAPI

func (*WebSocketResponsesAPI) WithStore

func (m *WebSocketResponsesAPI) WithStore(store bool) *WebSocketResponsesAPI

func (*WebSocketResponsesAPI) WithTemperature

func (m *WebSocketResponsesAPI) WithTemperature(t float64) *WebSocketResponsesAPI

func (*WebSocketResponsesAPI) WithThinking

func (m *WebSocketResponsesAPI) WithThinking(effort Effort) *WebSocketResponsesAPI

func (*WebSocketResponsesAPI) WithTool

func (*WebSocketResponsesAPI) WithTopLogprobs

func (m *WebSocketResponsesAPI) WithTopLogprobs(n int) *WebSocketResponsesAPI

func (*WebSocketResponsesAPI) WithTopP

func (*WebSocketResponsesAPI) WithTruncation

func (m *WebSocketResponsesAPI) WithTruncation(truncation string) *WebSocketResponsesAPI

func (*WebSocketResponsesAPI) WithUser

func (*WebSocketResponsesAPI) WithVerbosity

func (m *WebSocketResponsesAPI) WithVerbosity(verbosity Verbosity) *WebSocketResponsesAPI

type WebSocketStream

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

WebSocketStream implements llms.ProviderStream for WebSocket-based streaming.

func (*WebSocketStream) Audio

func (s *WebSocketStream) Audio() (string, string)

func (*WebSocketStream) Err

func (s *WebSocketStream) Err() error

func (*WebSocketStream) Image

func (s *WebSocketStream) Image() (string, string)

func (*WebSocketStream) Iter

func (s *WebSocketStream) Iter() func(yield func(llms.StreamStatus) bool)

func (*WebSocketStream) Message

func (s *WebSocketStream) Message() llms.Message

func (*WebSocketStream) Search

func (s *WebSocketStream) Search() llms.SearchActivity

func (*WebSocketStream) Text

func (s *WebSocketStream) Text() string

func (*WebSocketStream) Thought

func (s *WebSocketStream) Thought() content.Thought

func (*WebSocketStream) ToolArgumentFinalization

func (s *WebSocketStream) ToolArgumentFinalization() (json.RawMessage, bool)

ToolArgumentFinalization returns the independent provider-final argument snapshot for the active function call, when the protocol expects one.

func (*WebSocketStream) ToolCall

func (s *WebSocketStream) ToolCall() llms.ToolCall

func (*WebSocketStream) Usage

func (s *WebSocketStream) Usage() llms.Usage

Jump to

Keyboard shortcuts

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