cayu.providers.gateway

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.

GatewayProvider

from cayu.providers import GatewayProvider

Chat inference plus read-only model discovery and generation lookup.

base_url is explicit and includes /v1. Model and usage fields are normal provider observations; a reported cost is not a local price estimate. Failed POSTs are not automatically retried with a new financial request.

Bases: ChatCompletionsProvider.

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	class attribute	True

prepare_auxiliary_request (method)

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

stream_deadlines (property)

GatewayProvider.stream_deadlines() -> ProviderStreamDeadlines

runtime_stream (method)

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

GatewayProvider.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque adapter behavior.

provider_operation_mode (property)

GatewayProvider.provider_operation_mode() -> ProviderOperationMode

Explicit dispatch mode; capability support alone never enables it.

provider_operations (property)

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

GatewayProvider.context_pressure_profile() -> ModelContextPressureProfile

request_cache_policy (method)

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

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

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

request_fingerprint_options (method)

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

preflight_model_target (method)

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

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

preflight_portable_messages (method)

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

preflight_hosted_tools (method)

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

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

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

Reject targeted-tool authority that this provider cannot project.

supports_tool_discovery_projection (method)

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

Report an explicitly established provider/model discovery capability.

preflight_tool_discovery_projection (method)

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

Reject discovery authority that this provider cannot project.

billing_identity_for_request (method)

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

Resolve optional request context needed for commercial accounting.

billing_identity_for_completion (method)

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

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

count_input_tokens (method)

async GatewayProvider.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 GatewayProvider.stream(request: ModelRequest) -> AsyncIterator[ModelStreamEvent]

init (method)

GatewayProvider.__init__(*, base_url: str, api_key: str | None=None, timeout_s: float=60.0, stream_deadlines: ProviderStreamDeadlines | None=None, transport: GatewayTransport | None=None) -> None

aclose (method)

async GatewayProvider.aclose() -> None

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

get_generation (method)

async GatewayProvider.get_generation(request_id: str) -> dict[str, Any]

Observe service-owned status and cost; never replay or settle a request.

get_models (method)

async GatewayProvider.get_models() -> list[dict[str, Any]]

Return the models currently visible to this inference key.

price_book (method)

async GatewayProvider.price_book() -> PriceBook

Fetch an optional local-budget snapshot, not financial authority.

Unsupported prices are omitted. An empty usable catalog raises ValueError. Each call performs one catalog lookup; existing policies are never mutated.

Release source · Runtime guarantees · Capability guides

GatewayTransport

from cayu.providers import GatewayTransport

Bases: ChatCompletionsTransport, Protocol.

stream_chat_completions (method)

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

read_json (method)

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

Perform one bounded authenticated GET without redirects or retries.

Release source · Runtime guarantees · Capability guides

HttpxGatewayTransport

from cayu.providers import HttpxGatewayTransport

Bases: HttpxChatCompletionsTransport.

init (method)

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

aclose (method)

async HttpxGatewayTransport.aclose() -> None

stream_chat_completions (method)

async HttpxGatewayTransport.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]]

read_json (method)

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

Release source · Runtime guarantees · Capability guides