Documentation
¶
Overview ¶
Package openai provides OpenAI-compatible Chat Completions and Responses protocol clients. New selects Chat Completions; NewResponses explicitly selects stateless Responses.
It speaks the HTTP wire protocol directly and depends on no vendor SDK, which is what keeps it in the core module: the protocol is an interoperable format that many endpoints implement, not a vendor. Point it at a different base URL and it drives a different service, including a self-hosted one or a gateway that fronts a provider with a non-compatible native API.
Endpoints vary in two ways that are not about the protocol at all: where the completions path sits, and how the request authenticates. WithPath and WithHeader cover both, so an endpoint that scopes the model into its path, pins an API version with a query string, or authenticates with something other than a bearer token is reached by configuration rather than by code.
Client accepts the Chat Completions body; ResponsesClient implements the separate Responses body. Other native APIs or signing schemes use controller.ModelFunc, which both clients satisfy.
Client.Model satisfies controller.ModelFunc, so it plugs straight into placement.New.
It is used only on the LIVE path. Replay serves recorded completions from the journal and never reaches a provider, which is what makes a replayed session free and byte-identical; see controller.Controller.Replay.
Index ¶
Constants ¶
const DefaultBaseURL = "https://api.openai.com/v1"
DefaultBaseURL is the public OpenAI endpoint. Any compatible service works by overriding it.
const DefaultPath = "/chat/completions"
DefaultPath is where the completions endpoint sits under the base URL. Endpoints that scope the model into the path, or that pin an API version with a query string, override it.
Variables ¶
var ErrUnsupportedPart = errors.New("openai: unsupported content part")
ErrUnsupportedPart reports unmapped request semantics or malformed/unsupported tool content. Both Client and ResponsesClient return it for request-side tools/tool-choice violations and for malformed or unsupported tool completions. Refusing rather than dropping content keeps the neutral request and recorded completion faithful to the supported protocol mapping.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client calls an OpenAI-compatible Chat Completions endpoint.
func New ¶
New builds a Client. A default model is required to identify fallback provider calls and usage. Direct calls and pre-policy invocations use it for empty or "echo" requests; the journal still hashes the original neutral request. Controller invocations with a recorded model default send the selected model literally, including "echo", without fallback or deployment mapping. A non-absolute base URL, invalid path, or query parameter set in both the base URL and path is an error.
func (*Client) Endpoint ¶
Endpoint returns the URL every completions request is sent to: the base URL's path joined with the path, the base URL's query ahead of the path's, and no fragment. It carries whatever userinfo and query the base URL has, so redact it (url.URL.Redacted) before logging.
func (*Client) Model ¶
func (c *Client) Model(ctx context.Context, req api.ModelRequest) (api.ModelResponse, error)
Model performs one live completion. It satisfies controller.ModelFunc.
ctx carries the turn's cancellation and deadline through to the HTTP request, so a cancelled execution abandons an in-flight completion rather than leaving it to finish unobserved.
func (*Client) StreamModel ¶
func (c *Client) StreamModel(ctx context.Context, req api.ModelRequest, onChunk func(string)) (api.ModelResponse, error)
StreamModel performs one live completion, reporting text as it arrives. It satisfies controller.StreamFunc.
onChunk sees partial output; the returned response is the complete message, which is what the host records. That split is deliberate: the chunks are a view of the call in progress, and the journal must not depend on whether anyone was watching.
type Option ¶
type Option func(*Client)
Option configures a Client.
func WithAPIKey ¶
WithAPIKey sets a bearer token. It is sugar for the Authorization header most compatible endpoints expect; an endpoint that authenticates differently uses WithHeader instead. Empty sends no header at all, which is what a local endpoint or a gateway that injects its own credential wants.
func WithBaseURL ¶
WithBaseURL points the client at a compatible endpoint other than the default. It must be an absolute URL. Its query string is kept and sent with every request, ahead of any query the path carries; a fragment is dropped, as HTTP never sends one.
func WithHTTPClient ¶
WithHTTPClient supplies the HTTP client, for custom transports, proxies, or tests. The client is copied, not modified: the copy refuses redirects that leave the base URL's origin and then applies h.CheckRedirect, if any, to the redirects it allows.
func WithHeader ¶
WithHeader sets a request header, replacing any previous value for the same name. It is how an endpoint that authenticates outside the bearer convention is reached (an api-key or x-api-key header), and how a gateway that needs routing or tenant headers is satisfied. Headers are sent only to the base URL's origin (scheme, host and port): a redirect to any other origin is refused rather than followed, so a credential set here never reaches a host the caller did not configure.
This exists because those endpoints differ from OpenAI only in the envelope: the request body they accept is identical, so requiring a separate provider implementation for them would be a recompile in exchange for nothing.
type ResponsesClient ¶ added in v0.3.0
type ResponsesClient struct {
// contains filtered or unexported fields
}
ResponsesClient calls the stateless Responses protocol. It shares transport options with Client, but does not change the Chat Completions client or infer a protocol.
func NewResponses ¶ added in v0.3.0
func NewResponses(opts ...Option) (*ResponsesClient, error)
NewResponses builds a Responses client. The /responses default is applied before caller options, so WithPath still overrides it. A default model is required.
func (*ResponsesClient) Endpoint ¶ added in v0.3.0
func (c *ResponsesClient) Endpoint() string
Endpoint returns the configured Responses endpoint. Redact secrets before logging.
func (*ResponsesClient) Model ¶ added in v0.3.0
func (c *ResponsesClient) Model(ctx context.Context, req api.ModelRequest) (api.ModelResponse, error)
Model performs one stateless Responses call. It satisfies controller.ModelFunc.
func (*ResponsesClient) StreamModel ¶ added in v0.3.0
func (c *ResponsesClient) StreamModel(ctx context.Context, req api.ModelRequest, onChunk func(string)) (api.ModelResponse, error)
StreamModel emits provisional text deltas only. The authoritative completed response, not the accumulated chunks, is returned for durable recording.
Source Files