Architecture

This module is an isolated adapter from OpenAI’s Responses API to the public Spice Agent model contract.

The root package owns validated configuration and an instance-scoped Responses service. Client.Stream performs a deterministic, bounded translation from a validated model.Request; the request’s model is authoritative. The adapter prefetches the first SDK event before returning a stream so startup failures can be represented as model.ProviderError. One bounded pump then owns the raw SDK stream, allowing each Recv call to honor its own context without leaking one goroutine per deadline. Close may race with the sole Recv caller, cancels the operation, and joins that pump. Multiple concurrent Recv calls are not supported.

Only finalized function calls from the completed response become Spice tool calls. This prevents partial argument deltas from becoming executable work. Unknown tools, provider-hosted executable output, malformed arguments, duplicate call IDs, inconsistent final text, and limit violations fail closed. The adapter does not expose provider reasoning or raw SDK objects. Tool effects, replay safety, capabilities, and fingerprints are authoritative host policy and identity metadata. Translation deliberately sends only the function name, description, and JSON input schema to OpenAI, so policy-only changes cannot alter or disclose provider request content.

autoconfigure is the only library-default activation surface. It is selected solely by an explicit blank import and contributes one fallback model.Provider; an application-owned provider replaces it through ordinary Spice DI. The root package has no activation side effect.

The adapter may depend on spice-agent and openai-go; neither dependency may depend back on this repository. It does not own an agent loop, dispatcher, daemon, registry, service locator, or package scanner. Callers own contexts and engine metadata allowlists. No retry occurs after a stream has been returned.

An application-supplied http.Client and transport are trusted. Spice supplies the bounded request context and calls stream close, but cannot safely force-stop a transport that ignores both cancellation and close. Such a transport may prevent Close from joining and is outside this module’s cooperative contract.