openai

type APIType ¶

type APIType string

APIType indicates which OpenAI API to use.

const (
	// APIChatCompletions uses the /v1/chat/completions endpoint.
	APIChatCompletions APIType = "chat"

	// APIResponses uses the /v1/responses endpoint (for codex models).
	APIResponses APIType = "responses"
)

type ChatStepChoice ¶ added in v0.15.2

type ChatStepChoice struct {
	Index        int                 `json:"index"`
	Message      ChatStepRespMessage `json:"message"`
	FinishReason string              `json:"finish_reason"`
}

ChatStepChoice is one completion choice. Message.Content is RawMessage so we can accept JSON null or a string transparently.

type ChatStepErrorEnvelope ¶ added in v0.15.2

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

ChatStepErrorEnvelope is the OpenAI/OpenRouter error response shape.

type ChatStepMessage ¶ added in v0.15.2

type ChatStepMessage struct {
	Role       string             `json:"role"`
	Content    json.RawMessage    `json:"content"`
	ToolCallID string             `json:"tool_call_id,omitempty"`
	ToolCalls  []ChatStepToolCall `json:"tool_calls,omitempty"`
}

ChatStepMessage is one entry in the messages array. Content is a json.RawMessage so callers can emit a JSON string OR JSON null (for assistant messages with tool_calls and empty text).

type ChatStepRequest ¶ added in v0.15.2

type ChatStepRequest struct {
	Model               string            `json:"model"`
	Messages            []ChatStepMessage `json:"messages"`
	Tools               []ChatStepToolDef `json:"tools,omitempty"`
	MaxTokens           int               `json:"max_tokens,omitempty"`
	MaxCompletionTokens int               `json:"max_completion_tokens,omitempty"`
	Temperature         float64           `json:"temperature,omitempty"`
}

ChatStepRequest is the on-the-wire request body for a Chat Completions tool-use call. Exported so OpenRouter can extend it with its provider-routing field by composition (see openrouter package).

MaxTokens vs MaxCompletionTokens: OpenAI's GPT-5+ and o-series reasoning models (o1, o3) reject max_tokens with HTTP 400 "Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead." BuildChatStepRequest routes the value to whichever field the model accepts (see usesMaxCompletionTokens). Only one of the two will be set on a given request — the omitempty tags keep the wire payload clean.

func BuildChatStepRequest(req *ai.Request) (*ChatStepRequest, *ai.AIError)

type ChatStepRespMessage ¶ added in v0.15.2

type ChatStepRespMessage struct {
	Role      string             `json:"role"`
	Content   json.RawMessage    `json:"content"`
	ToolCalls []ChatStepToolCall `json:"tool_calls,omitempty"`
}

ChatStepRespMessage is the assistant message inside a choice.

type ChatStepResponse ¶ added in v0.15.2

type ChatStepResponse struct {
	ID      string           `json:"id"`
	Object  string           `json:"object"`
	Model   string           `json:"model"`
	Choices []ChatStepChoice `json:"choices"`
	Usage   ChatStepUsage    `json:"usage"`
}

ChatStepResponse is the parsed response body for a Chat Completions call.

type ChatStepToolCall ¶ added in v0.15.2

type ChatStepToolCall struct {
	ID       string                   `json:"id"`
	Type     string                   `json:"type"`
	Function ChatStepToolCallFunction `json:"function"`
}

ChatStepToolCall is one tool invocation in an assistant message. Note that Function.Arguments is a JSON STRING (not an object) — OpenAI requires this.

type ChatStepToolCallFunction ¶ added in v0.15.2

type ChatStepToolCallFunction struct {
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments"`
}

ChatStepToolCallFunction carries the tool name and the arguments STRING. json.RawMessage is used because the wire value MUST be a JSON string literal containing JSON — re-encoding as Go string would double-escape.

type ChatStepToolDef ¶ added in v0.15.2

type ChatStepToolDef struct {
	Type     string                  `json:"type"`
	Function ChatStepToolDefFunction `json:"function"`
}

ChatStepToolDef is one entry in the tools array advertised to the model. Parameters is a decoded JSON Schema OBJECT (unlike Arguments which is a string).

type ChatStepToolDefFunction ¶ added in v0.15.2

type ChatStepToolDefFunction struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Parameters  json.RawMessage `json:"parameters"`
}

ChatStepToolDefFunction carries the tool's name, description, and the JSON-Schema parameters as a decoded object on the wire.

type ChatStepUsage ¶ added in v0.15.2

type ChatStepUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

ChatStepUsage is the token-usage block.

type Client ¶

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

Client implements ai.Provider for OpenAI's APIs. It supports both Chat Completions and Responses APIs.

func NewClient(apiKey string, opts ...ClientOption) *Client

func (c *Client) Generate(ctx context.Context, req *ai.Request) (*ai.Response, error)

func (c *Client) Name() string

func (c *Client) NewHandler(model string, opts ...ai.HandlerOption) *ai.Handler

func (c *Client) Step(ctx context.Context, req *ai.Request) (*ai.Response, error)

type ClientOption ¶

type ClientOption func(*Client)

ClientOption configures a Client.

func WithAPIType(apiType APIType) ClientOption

func WithBaseURL(url string) ClientOption

func WithHTTPClient(client *http.Client) ClientOption