cayu.providers.openai

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

build_openai_embedding_payload

from cayu.providers import build_openai_embedding_payload

build_openai_embedding_payload(request: TextEmbeddingRequest) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

build_openai_payload

from cayu.providers import build_openai_payload

build_openai_payload(request: ModelRequest, *, stream: bool=False, reasoning_state: str='inline', chain: bool=True) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

HttpxOpenAITransport

from cayu.providers import HttpxOpenAITransport

HTTP transport with explicit certifi-backed TLS verification.

Owns one shared httpx.AsyncClient (created lazily) that is reused across requests so each model call does not pay for a fresh TLS handshake. Close it with aclose when the transport is no longer needed.

init (method)

HttpxOpenAITransport.__init__(*, allow_http: bool=False) -> None

aclose (method)

async HttpxOpenAITransport.aclose() -> None

create_response (method)

async HttpxOpenAITransport.create_response(*, url: str, headers: Mapping[str, str], payload: Mapping[str, Any], timeout_s: float) -> Mapping[str, Any]

stream_response_events (method)

async HttpxOpenAITransport.stream_response_events(*, url: str, headers: Mapping[str, str], payload: Mapping[str, Any], timeout_s: float, transport_idle_timeout_s: float, protocol_idle_timeout_s: float, semantic_progress_timeout_s: float, absolute_stream_timeout_s: float) -> AsyncIterator[Mapping[str, Any]]

retrieve_response (method)

async HttpxOpenAITransport.retrieve_response(*, url: str, headers: Mapping[str, str], timeout_s: float) -> Mapping[str, Any]

reconnect_response_events (method)

async HttpxOpenAITransport.reconnect_response_events(*, url: str, headers: Mapping[str, str], starting_after: int, timeout_s: float, transport_idle_timeout_s: float, protocol_idle_timeout_s: float, semantic_progress_timeout_s: float, absolute_stream_timeout_s: float) -> AsyncIterator[Mapping[str, Any]]

cancel_response (method)

async HttpxOpenAITransport.cancel_response(*, url: str, headers: Mapping[str, str], timeout_s: float) -> Mapping[str, Any]

Release source · Runtime guarantees · Capability guides

openai_embedding_result

from cayu.providers import openai_embedding_result

openai_embedding_result(response: Mapping[str, Any], *, requested_count: int) -> TextEmbeddingResult

Release source · Runtime guarantees · Capability guides

openai_response_events

from cayu.providers import openai_response_events

openai_response_events(response: Mapping[str, Any], *, reasoning_state: str='inline') -> list[ModelStreamEvent]

Release source · Runtime guarantees · Capability guides

OpenAIAPIError

from cayu.providers import OpenAIAPIError

Raised when the OpenAI HTTP API returns an error response.

param carries the OpenAI error body’s param field (the request field the error refers to, e.g. "previous_response_id"); it is OpenAI-specific, so it lives here rather than on ModelProviderError.

Bases: OpenAIError, ModelProviderError.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
param	str | None	None
classification_origin	str | None	None
classification_reason	str | None	None

init (method)

OpenAIAPIError.__init__(message: str, *, status_code: int | None=None, error_type: str | None=None, error_code: str | None=None, param: str | None=None, request_id: str | None=None, retryable: bool | None=None, retry_after_s: float | None=None, response_body: str | None=None, classification_origin: str | None=None, classification_reason: str | None=None) -> None

error_payload_fields (method)

OpenAIAPIError.error_payload_fields() -> dict[str, Any]

JSON-safe structured fields for model stream error payloads.

Key naming mirrors runtime context-overflow event payloads: the provider’s own error identity uses the provider_error_* prefix so it cannot collide with the Python-exception error_type key.

Release source · Runtime guarantees · Capability guides

OpenAIBackgroundTransport

from cayu.providers import OpenAIBackgroundTransport

Additional transport operations required by explicit background mode.

Bases: OpenAITransport, Protocol.

create_response (method)

async OpenAIBackgroundTransport.create_response(*, url: str, headers: Mapping[str, str], payload: Mapping[str, Any], timeout_s: float) -> Mapping[str, Any]

POST a non-streaming Responses API payload and return decoded JSON.

stream_response_events (method)

OpenAIBackgroundTransport.stream_response_events(*, url: str, headers: Mapping[str, str], payload: Mapping[str, Any], timeout_s: float, transport_idle_timeout_s: float, protocol_idle_timeout_s: float, semantic_progress_timeout_s: float, absolute_stream_timeout_s: float) -> AsyncIterator[Mapping[str, Any]]

POST a streaming Responses API payload and yield decoded SSE data objects.

retrieve_response (method)

async OpenAIBackgroundTransport.retrieve_response(*, url: str, headers: Mapping[str, str], timeout_s: float) -> Mapping[str, Any]

GET one existing Responses API object.

reconnect_response_events (method)

OpenAIBackgroundTransport.reconnect_response_events(*, url: str, headers: Mapping[str, str], starting_after: int, timeout_s: float, transport_idle_timeout_s: float, protocol_idle_timeout_s: float, semantic_progress_timeout_s: float, absolute_stream_timeout_s: float) -> AsyncIterator[Mapping[str, Any]]

Resume one stored background response after an accepted sequence.

cancel_response (method)

async OpenAIBackgroundTransport.cancel_response(*, url: str, headers: Mapping[str, str], timeout_s: float) -> Mapping[str, Any]

Cancel one existing Responses API object.

Release source · Runtime guarantees · Capability guides

OpenAIContextOverflowError

from cayu.providers import OpenAIContextOverflowError

Raised when OpenAI reports that the request exceeds context limits.

Bases: OpenAIAPIError, ModelContextOverflowError.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
param	str | None	None
classification_origin	str | None	None
classification_reason	str | None	None

init (method)

OpenAIContextOverflowError.__init__(message: str, *, status_code: int | None=None, error_type: str | None=None, error_code: str | None=None, request_id: str | None=None, response_body: str | None=None) -> None

error_payload_fields (method)

OpenAIContextOverflowError.error_payload_fields() -> dict[str, Any]

JSON-safe structured fields for model stream error payloads.

Key naming mirrors runtime context-overflow event payloads: the provider’s own error identity uses the provider_error_* prefix so it cannot collide with the Python-exception error_type key.

Release source · Runtime guarantees · Capability guides

OpenAIError

from cayu.providers import OpenAIError

Base error for OpenAI provider failures.

Bases: RuntimeError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

OpenAIProtocolError

from cayu.providers import OpenAIProtocolError

Responses validation failure with an allowlisted diagnostic identity.

reason_code is independent of the exception message. Unknown values are projected as unspecified; raw messages never supply diagnostic fields.

Bases: OpenAIError, OpenAIProtocolDiagnosticError.

init (method)

OpenAIProtocolError.__init__(message: str, *, reason_code: str='unspecified', source_diagnostic: SearchSourceDiagnostic | None=None, stream_diagnostic: SearchStreamDiagnostic | None=None, citation_diagnostic: CitationOffsetDiagnostic | None=None) -> None

Release source · Runtime guarantees · Capability guides

OpenAIProvider

from cayu.providers import OpenAIProvider

OpenAI Responses API adapter for Cayu’s provider-neutral runtime.

Bases: ModelProvider, TextEmbeddingProvider.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
name	class attribute	'openai'
billing_provider_name	str | None	None
usage_dialect	class attribute	UsageDialect.OPENAI
supports_native_structured_output	class attribute	True

prepare_auxiliary_request (method)

OpenAIProvider.prepare_auxiliary_request(request: ModelRequest, *, max_output_tokens: int) -> ModelRequest

stream_deadlines (property)

OpenAIProvider.stream_deadlines() -> ProviderStreamDeadlines

runtime_stream (method)

OpenAIProvider.runtime_stream(request: ModelRequest) -> AsyncIterator[ModelStreamEvent]

Open the governed model-attempt stream.

Runtime, application, example, and conformance callers must use this entrance so normalized semantic and absolute deadlines also guard opaque custom providers. Transparent provider wrappers must override this entrance and delegate to the wrapped provider’s runtime_stream; forwarding only the raw stream hook would add an opaque outer guard that cannot trust terminal evidence accepted by the wrapped adapter.

execution_profile_identity (property)

OpenAIProvider.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque adapter behavior.

provider_operation_mode (property)

OpenAIProvider.provider_operation_mode() -> ProviderOperationMode

provider_operations (property)

OpenAIProvider.provider_operations() -> ProviderOperationAdapter | None

context_pressure_profile (property)

OpenAIProvider.context_pressure_profile() -> ModelContextPressureProfile

request_cache_policy (method)

OpenAIProvider.request_cache_policy(request: ModelRequest) -> CachePolicy | None

Describe the effective provider-visible cache breakpoints, when known.

Implementations must be deterministic, side-effect free, and perform no I/O.

request_cache_projection (method)

OpenAIProvider.request_cache_projection(request: ModelRequest) -> RequestCacheProjection | None

Project the effective cache policy and provider-selected prefix.

Providers whose message preparation can filter or normalize content should override this hook and return the exact ephemeral prefix through the marker they applied. The default preserves compatibility with policy-only provider extensions and lets the runtime derive a provider-neutral prefix. Implementations must be deterministic, side-effect free, and perform no I/O.

request_footprint_options (method)

OpenAIProvider.request_footprint_options(request: ModelRequest) -> dict[str, Any]

request_fingerprint_options (method)

OpenAIProvider.request_fingerprint_options(request: ModelRequest) -> dict[str, Any]

preflight_model_target (method)

OpenAIProvider.preflight_model_target(*, model: str) -> None

Reject an unavailable provider/model target before runtime mutation.

This side-effect-free hook is called during initial-run admission before the session is created and again immediately before provider dispatch. Ordinary providers need no override. Applications may use it for credential-free inspection placeholders whose live execution must fail with a concrete setup diagnostic.

preflight_thinking (method)

OpenAIProvider.preflight_thinking(*, model: str, thinking: ThinkingConfig | None) -> None

preflight_portable_messages (method)

OpenAIProvider.preflight_portable_messages(*, model: str, messages: list[Message], tools: list[dict[str, Any]]) -> None

preflight_hosted_tools (method)

OpenAIProvider.preflight_hosted_tools(*, model: str, hosted_tools: tuple[OpenAIWebSearch, ...], options: dict[str, Any]) -> None

supports_targeted_tool_projection (method)

OpenAIProvider.supports_targeted_tool_projection(*, model: str, protocol: str) -> bool

preflight_targeted_tool_projection (method)

OpenAIProvider.preflight_targeted_tool_projection(*, model: str, protocol: str) -> None

supports_tool_discovery_projection (method)

OpenAIProvider.supports_tool_discovery_projection(*, model: str, protocol: str) -> bool

preflight_tool_discovery_projection (method)

OpenAIProvider.preflight_tool_discovery_projection(*, model: str, protocol: str) -> None

billing_identity_for_request (method)

async OpenAIProvider.billing_identity_for_request(request: ModelRequest) -> BillingIdentity | None

Resolve optional request context needed for commercial accounting.

billing_identity_for_completion (method)

OpenAIProvider.billing_identity_for_completion(identity: BillingIdentity | None, payload: dict[str, Any]) -> BillingIdentity | None

Merge provider-reported completion facts into a request identity.

preflight_native_structured_output_schema (method)

OpenAIProvider.preflight_native_structured_output_schema(json_schema: dict[str, Any]) -> None

count_input_tokens (method)

async OpenAIProvider.count_input_tokens(request: ModelRequest) -> InputTokenCountResult | None

stream (method)

async OpenAIProvider.stream(request: ModelRequest) -> AsyncIterator[ModelStreamEvent]

embed_texts (method)

async OpenAIProvider.embed_texts(request: TextEmbeddingRequest) -> TextEmbeddingResult

init (method)

OpenAIProvider.__init__(*, api_key: str | None=None, name: str='openai', base_url: str=DEFAULT_OPENAI_BASE_URL, allow_http: bool=False, timeout_s: float | None=None, stream_deadlines: ProviderStreamDeadlines | None=None, transport: OpenAITransport | None=None, extra_headers: Mapping[str, str] | None=None, reasoning_state: str='inline', hosted_web_search_supported: bool | None=None, model_catalog: ModelCatalog | None=None, additional_tools_models: Iterable[str] | None=None, client_tool_search_models: Iterable[str] | None=None, hosted_tool_search_models: Iterable[str] | None=None, background: bool=False, streaming: bool=True) -> None

aclose (method)

async OpenAIProvider.aclose() -> None

Close the transport’s shared HTTP client, if it owns one.

Release source · Runtime guarantees · Capability guides

OpenAITransport

from cayu.providers import OpenAITransport

Bases: Protocol.

create_response (method)

async OpenAITransport.create_response(*, url: str, headers: Mapping[str, str], payload: Mapping[str, Any], timeout_s: float) -> Mapping[str, Any]

POST a non-streaming Responses API payload and return decoded JSON.

stream_response_events (method)

OpenAITransport.stream_response_events(*, url: str, headers: Mapping[str, str], payload: Mapping[str, Any], timeout_s: float, transport_idle_timeout_s: float, protocol_idle_timeout_s: float, semantic_progress_timeout_s: float, absolute_stream_timeout_s: float) -> AsyncIterator[Mapping[str, Any]]

POST a streaming Responses API payload and yield decoded SSE data objects.

Release source · Runtime guarantees · Capability guides

OpenAIUnsupportedSearchSourceError

from cayu.providers import OpenAIUnsupportedSearchSourceError

Hosted search returned a source discriminator this adapter cannot decode.

This is a terminal capability mismatch, not permission to repeat a hosted search. No source fields are coerced or omitted to manufacture success.

Bases: OpenAIProtocolError.

init (method)

OpenAIUnsupportedSearchSourceError.__init__(*, source_diagnostic: SearchSourceDiagnostic) -> None

Release source · Runtime guarantees · Capability guides

preflight_openai_native_structured_output_schema

from cayu.providers import preflight_openai_native_structured_output_schema

Reject a NATIVE structured-output schema OpenAI strict mode always refuses.

Checks only the structural rules that have been invariant since strict mode launched: the root must be an object schema, every object schema must set additionalProperties: false, every properties key must appear in required, and every $ref must resolve inside the document, carry no sibling keys beyond $defs/definitions, and point at a schema that itself satisfies these rules. Keyword-level limits are deliberately not checked: OpenAI has only ever relaxed them, so a denylist would falsely reject schemas the API now accepts. Violations outside this core still surface as an OpenAI-side 400.

Raises NativeStructuredOutputSchemaInvalid (a ValueError) with the offending JSON path for schema-rule violations, and TypeError when json_schema is not a dict (a caller error, matching the runtime’s copy/validate conventions).

preflight_openai_native_structured_output_schema(json_schema: dict[str, Any]) -> None

Release source · Runtime guarantees · Capability guides