Documentation
¶
Overview ¶
Package openai is a model provider for OpenAI-compatible Chat Completions endpoints.
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.
The limit is the request body. An endpoint that accepts the chat-completions body works here; one with its own body or signing scheme (a native messages API, or a cloud that signs requests) is a different protocol, and the seam for those is controller.ModelFunc, which this type satisfies.
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 request content this provider cannot represent: a content part, or the tools and tool choice offered to the model. It is returned rather than dropped: the log records the request the harness built, so silently sending less than that would make the journal describe a call that never happened, and replay would reproduce the wrong thing.
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: the model id ends up on every recorded MODEL_CALL event, so a client that cannot name one would write a journal that does not say what produced the completion. A base URL that is not absolute, a path that does not parse, or a query parameter set in both the base URL and the 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.
Source Files