openai

package module
v0.21.0 Latest Latest
Warning

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

 Go to latest Published: Sep 12, 2026 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package openai implements reusable OpenAI wire adapters for native and compatible provider endpoints.

Modalities exposed:

  • chat (Chat Completions) via NewChatCompletions — tool calling, streaming, native request extensions, vision input, audio input/output;
  • chat (Responses) via NewResponses — ordered reasoning and tool replay, streaming, multimodal input, and complete-request input-token counting through the native Responses endpoint;
  • embedding via NewEmbeddingModel — text-embedding-3-small/large with dimension truncation;
  • image via NewImageModel — DALL·E 3 and gpt-image-1;
  • moderation via NewModerationModel — omni-moderation-latest;
  • audio tts via NewAudioTTSModel — tts-1, tts-1-hd, gpt-4o-mini-tts;
  • audio transcription via NewAudioTranscriptionModel — whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe;
  • audio translation via NewAudioTranslationModel — whisper-1 translating any source language to English (implements transcription.Model).

Model id constants aren't exported here — they're maintained by openai-go (openai.ChatModelGPT5_6Sol, openai.EmbeddingModelTextEmbedding3Large, etc.). Import openai-go directly when you need them.

Provider-specific fields not modeled by Core reach the wire through request extensions scoped to the endpoint provider. Raw response details use that same namespace, so compatible endpoints never leak OpenAI provider metadata.

Responses Call and Stream share terminal-state mapping: incomplete generation preserves its stop reason, failed generation returns an error, and a stream ending before a terminal response returns chat.ErrInvalidResponse.

Provider packages with an OpenAI-compatible endpoint reuse the protocol through NewCompatibleChatCompletions and select one typed Dialect. This keeps provider-only fields such as reasoning_content out of OpenAI's native behavior while sharing the standard wire mapping. Moderation categories are named one field at a time, because the SDK types them as a struct rather than a map. A category OpenAI adds would arrive as a field nobody reads and a flagged input would come back unflagged for it, so a test reads the JSON names off ModerationCategories by reflection and requires the response to report exactly that set — silence is the failure mode here, and it is the one place silence is the whole problem.

Index

Constants

View Source 
const (
	// RequestExtensionKey identifies provider-owned Chat Completions fields
	// encoded as [RequestFields].
	RequestExtensionKey = "openai/request"
	// ResponseExtensionKey preserves the complete official Chat Completions
	// response after provider-neutral fields have been mapped.
	ResponseExtensionKey = "openai/response"
	// StreamChunkExtensionKey preserves each complete official Chat
	// Completions stream chunk.
	StreamChunkExtensionKey = "openai/stream_chunk"
)
View Source 
const (
	SpeechRequestExtensionKey        = "openai/speech_request"
	TranscriptionRequestExtensionKey = "openai/transcription_request"
	TranslationRequestExtensionKey   = "openai/translation_request"
	EmbeddingRequestExtensionKey     = "openai/embedding_request"
	ImageRequestExtensionKey         = "openai/image_request"
	ModerationRequestExtensionKey    = "openai/moderation_request"
)

Namespacing preserves provider-specific data without promoting it into the shared Core protocol or colliding with another provider.

View Source 
const (
	// ResponsesRequestExtensionKey stores official Responses API parameters in
	// a Core request for fields without a provider-neutral equivalent.
	ResponsesRequestExtensionKey = "openai/responses_request"
	// ResponsesResponseExtensionKey preserves the complete official Responses
	// API response, including output item types Core does not normalize.
	ResponsesResponseExtensionKey = "openai/responses_response"
)
View Source 
const DefaultMaxResponseBytes = int64(32 * 1024 * 1024)

DefaultMaxResponseBytes bounds how much synthesized audio is read into memory. A provider that returns an unexpectedly large asset would otherwise be able to exhaust the process before the response is ever validated.

Variables

This section is empty.

Functions

func NewTextReasoningPart 

func NewTextReasoningPart(provider string, field TextReasoningField, text string) (corechat.Part, error)

NewTextReasoningPart records which compatible provider field supplied text reasoning so a later request can reconstruct the same wire shape.

Types

type AudioTTSModel 

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

AudioTTSModel implements the OpenAI-compatible speech protocol.

func NewAudioTTSModel 

func NewAudioTTSModel(_ context.Context, config AudioTTSModelConfig) (*AudioTTSModel, error)

NewAudioTTSModel rejects an invalid provider binding before the first speech call.

func (*AudioTTSModel) Call 

func (a *AudioTTSModel) Call(ctx context.Context, req *tts.Request) (*tts.Response, error)

func (*AudioTTSModel) Stream 

func (a *AudioTTSModel) Stream(ctx context.Context, req *tts.Request) iter.Seq2[*tts.Response, error]

type AudioTTSModelConfig 

type AudioTTSModelConfig struct {
	Provider         string
	APIKey           string
	DefaultOptions   tts.Options
	BaseURL          string
	HTTPClient       *http.Client
	MaxResponseBytes int64
}

AudioTTSModelConfig binds provider access and defaults shared by every speech call.

func (AudioTTSModelConfig) Validate 

func (a AudioTTSModelConfig) Validate() error

type AudioTranscriptionModel 

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

AudioTranscriptionModel implements the OpenAI-compatible transcription protocol.

func NewAudioTranscriptionModel 

func NewAudioTranscriptionModel(_ context.Context, config AudioTranscriptionModelConfig) (*AudioTranscriptionModel, error)

NewAudioTranscriptionModel rejects an invalid provider binding before the first transcription call.

func (*AudioTranscriptionModel) Call 

func (a *AudioTranscriptionModel) Call(ctx context.Context, req *transcription.Request) (*transcription.Response, error)

type AudioTranscriptionModelConfig 

type AudioTranscriptionModelConfig struct {
	Provider       string
	APIKey         string
	DefaultOptions transcription.Options
	BaseURL        string
	HTTPClient     *http.Client
}

AudioTranscriptionModelConfig binds provider access and defaults shared by every transcription call.

func (AudioTranscriptionModelConfig) Validate 

func (a AudioTranscriptionModelConfig) Validate() error

type AudioTranslationModel 

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

AudioTranslationModel exposes OpenAI's /audio/translations endpoint — it accepts audio in any supported language and returns the **English** translation. The wire shape is the same as transcription (audio in, text out), so it implements the transcription.Model interface and can drop into any code path that already uses transcription.

If the caller needs the original-language transcript instead of a translation, use AudioTranscriptionModel.

func NewAudioTranslationModel 

func NewAudioTranslationModel(_ context.Context, config AudioTranslationModelConfig) (*AudioTranslationModel, error)

NewAudioTranslationModel rejects an invalid provider binding before the first translation call.

func (*AudioTranslationModel) Call 

func (a *AudioTranslationModel) Call(ctx context.Context, req *transcription.Request) (*transcription.Response, error)

type AudioTranslationModelConfig 

type AudioTranslationModelConfig struct {
	Provider       string
	APIKey         string
	DefaultOptions transcription.Options
	BaseURL        string
	HTTPClient     *http.Client
}

AudioTranslationModelConfig configures the OpenAI /audio/translations backend. Only "whisper-1" is currently accepted by OpenAI — newer gpt-4o-transcribe models are transcription-only and reject translation calls.

func (AudioTranslationModelConfig) Validate 

func (a AudioTranslationModelConfig) Validate() error

type ChatCompletions added in v0.13.0 

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

ChatCompletions implements OpenAI's Chat Completions protocol and is also the reusable protocol base for provider packages exposing a compatible endpoint.

func NewChatCompletions added in v0.13.0 

func NewChatCompletions(_ context.Context, config ChatCompletionsConfig) (*ChatCompletions, error)

NewChatCompletions rejects an invalid provider binding before the first Chat Completions call.

func NewCompatibleChatCompletions added in v0.13.0 

func NewCompatibleChatCompletions(_ context.Context, config ChatCompletionsConfig, dialect Dialect) (*ChatCompletions, error)

NewCompatibleChatCompletions rejects an invalid compatible binding before the first call.

func (*ChatCompletions) Call added in v0.13.0 

func (c *ChatCompletions) Call(ctx context.Context, req *corechat.Request) (*corechat.Response, error)

func (*ChatCompletions) Stream added in v0.13.0 

func (c *ChatCompletions) Stream(ctx context.Context, req *corechat.Request) iter.Seq2[*corechat.ResponseDelta, error]

Stream performs one streaming Chat Completions request. Stable tool identity is retained in adapter-local state until each incomplete wire delta can be expressed as a Core response delta.

type ChatCompletionsConfig added in v0.13.0 

type ChatCompletionsConfig struct {
	APIKey         string
	DefaultOptions corechat.Options
	BaseURL        string
	HTTPClient     *http.Client
	Headers        http.Header
}

ChatCompletionsConfig configures an OpenAI Chat Completions adapter. DefaultOptions are copied during construction; callers may select the model per request.

func (ChatCompletionsConfig) Validate added in v0.13.0 

func (c ChatCompletionsConfig) Validate() error

type ChatOption added in v0.16.0 

type ChatOption string

ChatOption names one Core chat option by the OpenAI request field it travels as. It exists so a dialect can declare which of them its provider discards. 

const (
	ChatOptionFrequencyPenalty ChatOption = "frequency_penalty"
	ChatOptionPresencePenalty  ChatOption = "presence_penalty"
	ChatOptionReasoningEffort  ChatOption = "reasoning_effort"
)

type CompatibleRequest 

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

CompatibleRequest exposes the stable subset of a compatible request that a provider dialect may inspect. Provider-only top-level JSON fields are added with SetExtraField; OpenAI SDK wire types never cross this boundary.

func (*CompatibleRequest) Model 

func (c *CompatibleRequest) Model() string

Model returns the effective model after Core defaults and request options have been merged.

func (*CompatibleRequest) SetExtraField 

func (c *CompatibleRequest) SetExtraField(name string, value any) error

SetExtraField adds or replaces one provider-owned top-level JSON field.

func (*CompatibleRequest) Stream 

func (c *CompatibleRequest) Stream() bool

Stream reports whether the request will use the streaming endpoint.

func (*CompatibleRequest) Temperature 

func (c *CompatibleRequest) Temperature() (float64, bool)

Temperature returns the effective temperature when one was supplied.

func (*CompatibleRequest) TopP added in v0.16.0 

func (c *CompatibleRequest) TopP() (float64, bool)

TopP returns the effective nucleus-sampling value when one was supplied. It is exposed for the same reason as Temperature: a provider that overrides or bounds it can only say so about the value that will actually be sent, which is the merged one rather than the request's own.

type Dialect 

type Dialect struct {
	// Provider scopes provider-owned response and replay state.
	Provider        string
	PrepareRequest  func(source *corechat.Request, target *CompatibleRequest) error
	TokenLimitField TokenLimitField
	// NativeOutputFormat reports whether this compatible endpoint natively
	// supports a Core output format. A nil function means the full OpenAI response_format
	// surface is supported. Unsupported JSON formats use the shared prompt
	// fallback instead of sending an invalid native parameter.
	NativeOutputFormat func(corechat.OutputFormatType) bool
	// DisableRawRequestExtension prevents provider adapters from accepting an
	// arbitrary OpenAI request object when their documented request surface is
	// narrower than OpenAI's.
	DisableRawRequestExtension bool
	// IgnoredOptions names the Core options this endpoint accepts on the wire
	// and then discards. A compatible provider that publishes such a list --
	// Anthropic's marks reasoning_effort, presence_penalty and
	// frequency_penalty "Ignored" -- makes a populated option vanish between
	// Call and the model, which reads exactly like the adapter dropping it.
	// Naming them here refuses the option instead, so the caller learns at the
	// call that this endpoint cannot honor it.
	IgnoredOptions []ChatOption
	// MaxTemperature bounds Options.Temperature for a provider that documents a
	// narrower range than OpenAI's. Refusing beats sending an out-of-range
	// value, whose fate the provider decides: Anthropic's table says it is
	// "capped at 1", which alters the request silently, while others answer an
	// error further from the caller. Nil accepts whatever Core accepts.
	MaxTemperature *float64
	// contains filtered or unexported fields
}

Dialect groups the independently typed request and response protocol facets selected by a provider adapter. One Chat Completions adapter has exactly one dialect.

func ReasoningContentDialect 

func ReasoningContentDialect(provider string) Dialect

ReasoningContentDialect maps the common reasoning_content extension while treating it as output-only state.

func ReasoningContentReplayDialect 

func ReasoningContentReplayDialect(provider string) Dialect

ReasoningContentReplayDialect maps reasoning_content and sends it back on every assistant message. Providers select this only when their protocol treats historical reasoning as replayable conversation state.

func ReasoningContentToolReplayDialect 

func ReasoningContentToolReplayDialect(provider string) Dialect

ReasoningContentToolReplayDialect maps reasoning_content and sends it back only on assistant messages containing tool calls.

func ReasoningDetailsDialect 

func ReasoningDetailsDialect(config ReasoningDetailsConfig) (Dialect, error)

ReasoningDetailsDialect preserves structured reasoning details losslessly in Core reasoning signatures. The resulting signatures are safe to concatenate while accumulating streaming deltas and are replayed only to the provider that produced them.

func ReasoningDialect 

func ReasoningDialect(provider string) Dialect

ReasoningDialect maps the reasoning extension as output-only state.

func ReasoningReplayDialect 

func ReasoningReplayDialect(provider string) Dialect

ReasoningReplayDialect maps the reasoning extension and sends it back on every assistant message.

func (Dialect) Validate 

func (d Dialect) Validate() error

type EmbeddingModel 

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

EmbeddingModel implements the OpenAI-compatible embedding protocol.

func NewEmbeddingModel 

func NewEmbeddingModel(_ context.Context, config EmbeddingModelConfig) (*EmbeddingModel, error)

NewEmbeddingModel rejects an invalid provider binding before the first embedding call.

func (*EmbeddingModel) Call 

func (e *EmbeddingModel) Call(ctx context.Context, req *embedding.Request) (response *embedding.Response, err error)

type EmbeddingModelConfig 

type EmbeddingModelConfig struct {
	Provider       string
	APIKey         string
	DefaultOptions embedding.Options
	BaseURL        string
	HTTPClient     *http.Client
}

EmbeddingModelConfig binds provider access and defaults shared by every embedding call.

func (EmbeddingModelConfig) Validate 

func (e EmbeddingModelConfig) Validate() error

type ImageModel 

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

ImageModel implements the OpenAI-compatible image protocol.

func NewImageModel 

func NewImageModel(_ context.Context, config ImageModelConfig) (*ImageModel, error)

NewImageModel rejects an invalid provider binding before the first image call.

func (*ImageModel) Call 

func (i *ImageModel) Call(ctx context.Context, req *image.Request) (*image.Response, error)

type ImageModelConfig 

type ImageModelConfig struct {
	Provider       string
	APIKey         string
	DefaultOptions image.Options
	BaseURL        string
	HTTPClient     *http.Client
}

ImageModelConfig binds provider access and defaults shared by every image call.

func (ImageModelConfig) Validate 

func (i ImageModelConfig) Validate() error

type ModerationModel 

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

ModerationModel implements the OpenAI-compatible moderation protocol.

func NewModerationModel 

func NewModerationModel(_ context.Context, config ModerationModelConfig) (*ModerationModel, error)

NewModerationModel rejects an invalid provider binding before the first moderation call.

func (*ModerationModel) Call 

func (m *ModerationModel) Call(ctx context.Context, req *moderation.Request) (response *moderation.Response, err error)

type ModerationModelConfig 

type ModerationModelConfig struct {
	Provider       string
	APIKey         string
	DefaultOptions moderation.Options
	BaseURL        string
	HTTPClient     *http.Client
}

ModerationModelConfig binds provider access and defaults shared by every moderation call.

func (ModerationModelConfig) Validate 

func (m ModerationModelConfig) Validate() error

type ReasoningDetailsConfig 

type ReasoningDetailsConfig struct {
	Provider        string
	TextField       string
	DetailsField    string
	ReplayPlainText bool
}

ReasoningDetailsConfig describes the structured reasoning_details dialect shared by several OpenAI-compatible providers. Provider scopes opaque replay state so one provider's signed details are never sent to another provider.

func (ReasoningDetailsConfig) Validate 

func (r ReasoningDetailsConfig) Validate() error

type RequestFields 

type RequestFields map[string]any

RequestFields contains provider-owned top-level JSON fields that are not represented by Core. Fields owned by Core are rejected instead of allowing an extension to silently override the neutral request.

type Responses added in v0.13.0 

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

Responses adapts OpenAI's ordered Responses API output to the minimal Core chat Model and Streamer capabilities.

func NewResponses added in v0.13.0 

func NewResponses(_ context.Context, config ResponsesConfig) (*Responses, error)

NewResponses rejects an invalid provider binding before the first Responses call.

func (*Responses) Call added in v0.13.0 

func (r *Responses) Call(ctx context.Context, req *corechat.Request) (*corechat.Response, error)

func (*Responses) CountInputTokens added in v0.13.0 

func (r *Responses) CountInputTokens(ctx context.Context, req *corechat.Request) (int64, error)

CountInputTokens calls the provider's Responses input-token endpoint with the same provider request projection used by Call.

func (*Responses) Stream added in v0.13.0 

func (r *Responses) Stream(ctx context.Context, req *corechat.Request) iter.Seq2[*corechat.ResponseDelta, error]

Stream performs one streaming Responses API request and yields ordered Core response deltas.

type ResponsesConfig added in v0.13.0 

type ResponsesConfig struct {
	APIKey         string
	DefaultOptions corechat.Options
	BaseURL        string
	HTTPClient     *http.Client
	Headers        http.Header
}

ResponsesConfig configures an OpenAI Responses adapter. DefaultOptions are copied during construction; callers may select the model per request.

func (ResponsesConfig) Validate added in v0.13.0 

func (r ResponsesConfig) Validate() error

type TextReasoningField 

type TextReasoningField string

TextReasoningField identifies a provider's plain-text reasoning property. 

const (
	TextReasoningContent TextReasoningField = reasoningContentField
	TextReasoning        TextReasoningField = reasoningField
)

The vocabulary is closed because it names which response property a provider puts plain-text reasoning in. OpenAI-compatible vendors disagree on the field name, and reading the wrong one silently yields an empty reasoning part rather than an error.

type TokenLimitField 

type TokenLimitField string

TokenLimitField identifies the provider's wire field for Core's neutral Options.MaxOutputTokens value. OpenAI-compatible APIs are not uniform here: legacy-compatible providers accept max_tokens while newer protocols use max_completion_tokens. 

const (
	// TokenLimitMaxTokens selects the legacy-compatible max_tokens field.
	TokenLimitMaxTokens TokenLimitField = "max_tokens"
	// TokenLimitMaxCompletionTokens selects max_completion_tokens.
	TokenLimitMaxCompletionTokens TokenLimitField = "max_completion_tokens"
)

func (TokenLimitField) String 

func (t TokenLimitField) String() string

func (TokenLimitField) Valid 

func (t TokenLimitField) Valid() bool

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.