openai

Documentation

Overview

Package openai implements the OpenAI provider for the unified inference runtime. It owns the provider's model catalog, strict Spec decoding, and all wire compilers; core/inference never sees OpenAI concepts.

Operation coverage:

• Generate (unary + stream): Responses API by default — text, vision input, tool calling, reasoning effort, JSON/JSON-schema response formats. Set provider settings `api: chat` to switch a provider instance to Chat Completions. Chat mode drops Responses-only reasoning round-trips and rejects the hosted web_search tool at compile time; the rest of the generate surface (tools, vision, JSON formats, streaming) is equivalent. Reasoning models cannot switch reasoning off: reasoning_enabled: false rejects at compile time; true is a no-op (the default). Reasoning items decode into canonical reasoning parts (summary text, encrypted payload in the Signature slot, item id) and round-trip through context when id and payload survive; the request always includes reasoning.encrypted_content so round-trips stay possible. GenerateOptions.WebSearch attaches OpenAI's hosted web_search tool; web_search_call items and url_citation annotations surface on GenerateResponse.ProviderOutputs (never inside Message).
• Generate ImageIntent: Images API (gpt-image models).
• Generate AudioIntent: speech API (gpt-4o-mini-tts and friends).
• Embed: embeddings API (text-embedding-3 family).

Realtime (gpt-realtime) is intentionally absent: the pinned openai-go has no WebSocket coverage and this environment's module proxy cannot serve a newer SDK, so the GA protocol would be hand-rolled. It lands with a capable SDK or an accepted protocol dependency.

Credentials come exclusively from config profiles: `api_key` authenticates every OpenAI surface. The provider Spec redirects transport (base_url), scopes requests (organization, project), and declares extra models (models); the profile Spec is reserved and currently carries no settings.

Transcription (gpt-4o-transcribe family) is also absent for now: core/inference does not expose the transcription operation surface yet.

Deployments wire this package as an inference.Provider resource:

reg.MustRegister(openai.Factory())

and reference it from the inference assembly:

resources:
  provider.openai: {kind: inference.Provider, impl: openai, settings: {...}}
  infer: {kind: inference.Assembly, impl: unified, deps: {provider.openai: provider.openai}}

Retries

The provider Spec accepts `http_retries` (total wire attempts including the first). Nil keeps the openai-go default (two retries); 0 disables SDK-internal retries so the route Router owns the budget; N maps to option.WithMaxRetries(N-1). Retry-After and the SDK retry count are propagated onto ProviderFailure so Router backoff and trace wire_attempts can observe them.

Index

• Constants
• func Factory() resource.Factory
• func Register(r *resource.Registry) error
• type GenerateOptions
  • func (o GenerateOptions) ActiveFields() []inference.ExtensionField
  • func (o GenerateOptions) Clone() inference.Extension
  • func (o GenerateOptions) ExtensionID() string
  • func (o GenerateOptions) ProviderID() string
  • func (o GenerateOptions) Validate() error
• type GenerateWebSearch
• type GenerateWebSearchLocation
• type GenerateWebSearchToolChoice
• type ModelSpec
  • func (m ModelSpec) Validate() error
• type ProfileSettings
• type ProfileSpec
  • func (s ProfileSpec) Validate() error
• type ResourceSettings
• type Spec
  • func (s Spec) Validate() error
• type WebSearchOutput
  • func (o WebSearchOutput) Clone() inference.ProviderOutput
  • func (WebSearchOutput) ExtensionID() string
  • func (WebSearchOutput) ProviderID() string
  • func (o WebSearchOutput) Validate() error

Constants

const ResourceKind = "inference.Provider"

ResourceKind is the deployment resource kind implemented by the OpenAI provider driver.

const (
	// SecretAPIKey authenticates every OpenAI API surface.
	SecretAPIKey = "api_key"
)

Secret names owned by this provider. Profile secrets outside this set are rejected at build time so typos fail fast instead of silently missing.

Functions

func Factory

func Factory() resource.Factory

Factory returns the OpenAI provider deployment factory.

func Register

func Register(r *resource.Registry) error

Register adds the OpenAI provider factory to r.

Types

type GenerateOptions

type GenerateOptions struct {
	// Provider targets a deployment provider ID other than "openai".
	Provider string `json:"-"`
	// WebSearch attaches OpenAI's hosted web_search tool.
	WebSearch *GenerateWebSearch `json:"web_search,omitempty"`
}

GenerateOptions carries OpenAI Responses API settings that have no canonical representation.

func (GenerateOptions) ActiveFields

func (o GenerateOptions) ActiveFields() []inference.ExtensionField

func (GenerateOptions) Clone

func (o GenerateOptions) Clone() inference.Extension

func (GenerateOptions) ExtensionID

func (o GenerateOptions) ExtensionID() string

func (GenerateOptions) ProviderID

func (o GenerateOptions) ProviderID() string

func (GenerateOptions) Validate

func (o GenerateOptions) Validate() error

type GenerateWebSearch

type GenerateWebSearch struct {
	// SearchContextSize controls how much web search context the model can
	// consume: "low", "medium", or "high". Empty keeps the provider default.
	SearchContextSize string `json:"search_context_size,omitempty"`
	// AllowedDomains restricts search results to the listed domains and their
	// subdomains. Empty allows all domains.
	AllowedDomains []string `json:"allowed_domains,omitempty"`
	// UserLocation localizes results.
	UserLocation GenerateWebSearchLocation `json:"user_location,omitempty"`
	// ExternalWebAccess controls whether the model may load pages that are not
	// directly search-engine results.
	ExternalWebAccess *bool `json:"external_web_access,omitempty"`
	// ReturnTokenBudget controls the returned-token budget for reasoning web
	// search runs: "default" or "unlimited".
	ReturnTokenBudget string `json:"return_token_budget,omitempty"`
	// ToolChoice controls whether search is optional (auto) or mandatory
	// (required). Nil behaves as auto.
	ToolChoice *GenerateWebSearchToolChoice `json:"tool_choice,omitempty"`
}

GenerateWebSearch configures the hosted web_search tool.

type GenerateWebSearchLocation

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

GenerateWebSearchLocation is the approximate location for web search.

type GenerateWebSearchToolChoice

type GenerateWebSearchToolChoice struct {
	// Required forces the model to run web search when true.
	Required bool `json:"required"`
}

GenerateWebSearchToolChoice selects the web search tool choice mode.

type ModelSpec

type ModelSpec struct {
	Name string `json:"name"`
	Kind string `json:"kind"`
	// Capabilities declares the model's input/output content kinds, hosted
	// web search support, and reasoning control capability.
	Capabilities inference.ModelCapabilities `json:"capabilities,omitempty"`
	// Dimensions (embed) allows custom output dimensions.
	Dimensions bool `json:"dimensions,omitempty"`
}

ModelSpec declares one model outside the built-in catalog. Capabilities mirror the built-in catalog shape: content kinds, hosted web search, and the reasoning control capability (validated against the kind's compiler contract at merge time). Dimensions is the one control capability that no capability kind expresses and stays a separate flag.

func (ModelSpec) Validate

func (m ModelSpec) Validate() error

type ProfileSettings

type ProfileSettings struct {
	ID         string                `json:"id,omitempty"`
	Operations []inference.Operation `json:"operations,omitempty"`
	Secrets    map[string]string     `json:"secrets,omitempty"`
	Spec       json.RawMessage       `json:"spec,omitempty"`
}

ProfileSettings is one credential profile. Secrets maps the provider-owned secret name (api_key) to a resolved or ${env:NAME} referenced value.

type ProfileSpec

type ProfileSpec struct{}

ProfileSpec is the per-credential-profile configuration. OpenAI addresses models by public slug and every surface shares one API key, so no profile-scoped settings exist today; the struct is reserved so future account-scoped settings have a home without a config schema break.

func (ProfileSpec) Validate

func (s ProfileSpec) Validate() error

type ResourceSettings

type ResourceSettings struct {
	// ID is the stable provider identity used by model refs and the
	// inference assembly (e.g. "openai").
	ID string `json:"id"`
	// Spec is the provider-owned, credential-free configuration.
	Spec json.RawMessage `json:"spec,omitempty"`
	// Profiles declares one credential profile per API key/account.
	Profiles []ProfileSettings `json:"profiles,omitempty"`
}

ResourceSettings is the settings subtree of one OpenAI provider resource: the provider identity, credential-free spec, and one entry per credential profile. Secret values may carry ${env:NAME} references, resolved by the driver at build time.

type Spec

type Spec struct {
	// API selects the generate surface: "responses" (default) or
	// "chat" (Chat Completions). Chat mode is provider-wide and only
	// affects generate; embed / image / tts use their own endpoints.
	API string `json:"api,omitempty"`
	// BaseURL overrides the API base URL (gateways, proxies, Azure-style
	// compatible endpoints).
	BaseURL string `json:"base_url,omitempty"`
	// Organization sets the OpenAI-Organization header.
	Organization string `json:"organization,omitempty"`
	// Project sets the OpenAI-Project header.
	Project string `json:"project,omitempty"`
	// HTTPRetries bounds wire-level retries inside one logical inference
	// attempt, including the first. Zero disables SDK-internal retries so
	// the route Router owns the full retry budget; nil keeps the openai-go
	// default (two retries).
	HTTPRetries *resource.Int `json:"http_retries,omitempty"`
	// Models declares additional models beyond the built-in catalog or
	// overrides catalog entries by name.
	Models []ModelSpec `json:"models,omitempty"`
}

Spec is the provider-level configuration for OpenAI. It must stay credential-free: strict decoding rejects unknown keys, and credentials live only in profile secrets.

func (Spec) Validate

func (s Spec) Validate() error

type WebSearchOutput

type WebSearchOutput struct {
	Calls     []inference.WebSearchCall `json:"calls,omitempty"`
	Citations []inference.Citation      `json:"citations,omitempty"`
}

WebSearchOutput is the provider-owned structured output of OpenAI's hosted web_search tool. It lives outside Message: search calls are executed by the provider, and citations are display metadata rather than conversation parts.

func (WebSearchOutput) Clone

func (o WebSearchOutput) Clone() inference.ProviderOutput

func (WebSearchOutput) ExtensionID

func (WebSearchOutput) ExtensionID() string

func (WebSearchOutput) ProviderID

func (WebSearchOutput) ProviderID() string

func (WebSearchOutput) Validate

func (o WebSearchOutput) Validate() error