cayu.providers.chat_completions

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_chat_completions_payload

from cayu.providers import build_chat_completions_payload

build_chat_completions_payload(request: ModelRequest, *, stream: bool=False, clean_schemas: bool=True, strip_additional_properties: bool=False, options_key: str='openai', document_encoding: str=DEFAULT_DOCUMENT_ENCODING, include_usage: bool=True, provider_state_target_sha256: str | None=None) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

chat_completions_stream_events

from cayu.providers import chat_completions_stream_events

async chat_completions_stream_events(events: AsyncIterator[Mapping[str, Any]], *, requested_model: str | None=None, provider_state_target_sha256: str | None=None) -> AsyncIterator[ModelStreamEvent]

Release source · Runtime guarantees · Capability guides

ChatCompletionsAPIError

from cayu.providers import ChatCompletionsAPIError

Raised when the Chat Completions HTTP API returns an error response.

Bases: ChatCompletionsError, ModelProviderError.

init (method)

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

error_payload_fields (method)

ChatCompletionsAPIError.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

ChatCompletionsContextOverflowError

from cayu.providers import ChatCompletionsContextOverflowError

Raised when a Chat Completions provider reports context overflow.

Bases: ChatCompletionsAPIError, ModelContextOverflowError.

init (method)

ChatCompletionsContextOverflowError.__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)

ChatCompletionsContextOverflowError.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

ChatCompletionsError

from cayu.providers import ChatCompletionsError

Base error for Chat Completions provider failures.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

ChatCompletionsProtocolError

from cayu.providers import ChatCompletionsProtocolError

Raised when data does not match the expected Chat Completions shape.

Bases: ChatCompletionsError.

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

Release source · Runtime guarantees · Capability guides

ChatCompletionsProvider

from cayu.providers import ChatCompletionsProvider

Adapter for OpenAI-compatible /v1/chat/completions services.

Many providers expose the OpenAI Chat Completions wire format without the newer Responses API: Google Gemini (AI Studio), Azure OpenAI, Together, Fireworks, Mistral, Ollama, vLLM, and others. This single adapter targets that shared format so those providers work through Cayu’s provider-neutral runtime. OpenAIProvider remains the adapter for OpenAI’s Responses API.

The model is resolved from the agent’s AgentSpec (and ModelRequest), not from this provider, matching OpenAIProvider/AnthropicProvider.

Bases: ModelProvider.

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_chat'
billing_provider_name	str | None	None
usage_dialect	class attribute	UsageDialect.OPENAI
supports_native_structured_output	bool	False

prepare_auxiliary_request (method)

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

stream_deadlines (property)

ChatCompletionsProvider.stream_deadlines() -> ProviderStreamDeadlines

runtime_stream (method)

ChatCompletionsProvider.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)

ChatCompletionsProvider.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque adapter behavior.

provider_operation_mode (property)

ChatCompletionsProvider.provider_operation_mode() -> ProviderOperationMode

Explicit dispatch mode; capability support alone never enables it.

provider_operations (property)

ChatCompletionsProvider.provider_operations() -> ProviderOperationAdapter | None

Optional reconnectable-operation adapter.

Returning None preserves the ordinary synchronous stream path. Providers opt in explicitly by returning a composed adapter.

context_pressure_profile (property)

ChatCompletionsProvider.context_pressure_profile() -> ModelContextPressureProfile

request_cache_policy (method)

ChatCompletionsProvider.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)

ChatCompletionsProvider.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)

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

request_fingerprint_options (method)

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

preflight_model_target (method)

ChatCompletionsProvider.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)

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

preflight_portable_messages (method)

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

preflight_hosted_tools (method)

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

Reject provider-hosted authority this adapter cannot honor.

This hook is side-effect free and is called before a new session is created. The conservative default rejects every hosted tool so custom providers cannot silently omit registered execution authority.

supports_targeted_tool_projection (method)

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

Report an explicitly established provider/model projection capability.

The conservative default is unsupported. Implementations must not infer support from a model-name pattern because provider aliases and compatible endpoints can expose different wire contracts under the same model name.

preflight_targeted_tool_projection (method)

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

Reject targeted-tool authority that this provider cannot project.

supports_tool_discovery_projection (method)

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

Report an explicitly established provider/model discovery capability.

preflight_tool_discovery_projection (method)

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

Reject discovery authority that this provider cannot project.

billing_identity_for_request (method)

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

Resolve optional request context needed for commercial accounting.

billing_identity_for_completion (method)

ChatCompletionsProvider.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)

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

Optionally reject a NATIVE structured-output schema this adapter’s provider API would refuse, before any model request is made.

The runtime calls this at every entrance (after the supports_native_structured_output check, before any session is created or transitioned) with a caller-owned copy of the schema; implementations must not mutate it. Adapters should raise NativeStructuredOutputSchemaInvalid with a path-specific message. The default accepts everything: adapters without provider-specific schema rules stay source-compatible.

count_input_tokens (method)

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

Optionally count the input tokens for one request before submission.

Providers that need to call a remote counting endpoint should do so here. Remote counters are opt-in observability/calibration hooks, not default context-overflow enforcement. The default implementation is intentionally unavailable so existing providers remain source-compatible.

stream (method)

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

init (method)

ChatCompletionsProvider.__init__(*, api_key: str | None=None, name: str='openai_chat', base_url: str=DEFAULT_CHAT_COMPLETIONS_BASE_URL, endpoint_url: str | None=None, api_key_env: str=DEFAULT_CHAT_COMPLETIONS_API_KEY_ENV, auth_header: str=DEFAULT_CHAT_COMPLETIONS_AUTH_HEADER, auth_value_prefix: str=DEFAULT_CHAT_COMPLETIONS_AUTH_VALUE_PREFIX, allow_http: bool=False, stream_include_usage: bool=True, timeout_s: float=DEFAULT_CHAT_COMPLETIONS_TIMEOUT_SECONDS, stream_deadlines: ProviderStreamDeadlines | None=None, transport: ChatCompletionsTransport | None=None, extra_headers: Mapping[str, str] | None=None, openrouter_http_referer: str | None=None, openrouter_app_title: str | None=None, openrouter_router_metadata: bool=False, api_version: str | None=None, clean_schemas: bool=True, strip_additional_properties: bool | None=None, document_encoding: str=DEFAULT_DOCUMENT_ENCODING, usage_dialect: UsageDialect | str | None=None) -> None

aclose (method)

async ChatCompletionsProvider.aclose() -> None

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

Release source · Runtime guarantees · Capability guides

ChatCompletionsTransport

from cayu.providers import ChatCompletionsTransport

Bases: Protocol.

stream_chat_completions (method)

ChatCompletionsTransport.stream_chat_completions(*, 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 Chat Completions payload and yield decoded SSE data objects.

Release source · Runtime guarantees · Capability guides

HttpxChatCompletionsTransport

from cayu.providers import HttpxChatCompletionsTransport

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)

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

aclose (method)

async HttpxChatCompletionsTransport.aclose() -> None

stream_chat_completions (method)

async HttpxChatCompletionsTransport.stream_chat_completions(*, 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]]

Release source · Runtime guarantees · Capability guides