cayu.providers.vertex

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.

HttpxVertexTransport

from cayu.providers import HttpxVertexTransport

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)

HttpxVertexTransport.__init__() -> None

aclose (method)

async HttpxVertexTransport.aclose() -> None

count_message_tokens (method)

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

create_message (method)

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

stream_message_events (method)

async HttpxVertexTransport.stream_message_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]]

Release source · Runtime guarantees · Capability guides

VertexAPIError

from cayu.providers import VertexAPIError

Raised when the Vertex AI HTTP API returns an error response.

Bases: VertexError, ModelProviderError.

init (method)

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

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

VertexContextOverflowError

from cayu.providers import VertexContextOverflowError

Raised when Vertex reports that the request exceeds context limits.

Bases: VertexAPIError, ModelContextOverflowError.

init (method)

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

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

VertexError

from cayu.providers import VertexError

Base error for Vertex provider failures.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

VertexProtocolError

from cayu.providers import VertexProtocolError

Raised when Vertex data does not match the expected Messages shape.

Bases: VertexError.

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

Release source · Runtime guarantees · Capability guides

VertexProvider

from cayu.providers import VertexProvider

Anthropic Claude models hosted on Google Cloud Vertex AI.

Sends the standard Anthropic Messages body to the regional :rawPredict endpoint with an OAuth bearer token, reusing the Anthropic payload builder and response parser. The body omits model (it is in the URL) and carries anthropic_version instead.

Notes: - Usage/cache accounting is Anthropic-shaped; this adapter declares usage_dialect = UsageDialect.ANTHROPIC so cache-token folding in normalize_usage_metrics survives a custom name. - For budget enforcement, register pricing rows under provider "vertex" (Vertex Claude rates differ from the direct Anthropic API).

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

prepare_auxiliary_request (method)

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

stream_deadlines (property)

VertexProvider.stream_deadlines() -> ProviderStreamDeadlines

runtime_stream (method)

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

VertexProvider.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque adapter behavior.

provider_operation_mode (property)

VertexProvider.provider_operation_mode() -> ProviderOperationMode

Explicit dispatch mode; capability support alone never enables it.

provider_operations (property)

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

VertexProvider.context_pressure_profile() -> ModelContextPressureProfile

request_cache_policy (method)

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

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

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

request_fingerprint_options (method)

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

preflight_model_target (method)

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

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

preflight_portable_messages (method)

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

preflight_hosted_tools (method)

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

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

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

Reject targeted-tool authority that this provider cannot project.

supports_tool_discovery_projection (method)

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

Report an explicitly established provider/model discovery capability.

preflight_tool_discovery_projection (method)

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

Reject discovery authority that this provider cannot project.

billing_identity_for_request (method)

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

Resolve optional request context needed for commercial accounting.

billing_identity_for_completion (method)

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

VertexProvider.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 VertexProvider.count_input_tokens(request: ModelRequest) -> InputTokenCountResult | None

Count input tokens via the Anthropic count-tokens endpoint on Vertex.

Vertex exposes the Anthropic Messages count-tokens API as a rawPredict call on the literal count-tokens model segment; unlike stream, the real model stays in the request body.

stream (method)

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

anthropic_version (property)

VertexProvider.anthropic_version() -> str

Return the immutable wire and reasoning-state protocol version.

init (method)

VertexProvider.__init__(*, project_id: str, region: str=DEFAULT_VERTEX_REGION, credentials: Any | None=None, service_account_info: Mapping[str, Any] | None=None, service_account_file: str | None=None, base_url: str | None=None, name: str='vertex', anthropic_version: str=DEFAULT_VERTEX_ANTHROPIC_VERSION, max_tokens: int=DEFAULT_VERTEX_MAX_TOKENS, timeout_s: float=DEFAULT_VERTEX_TIMEOUT_SECONDS, stream_deadlines: ProviderStreamDeadlines | None=None, transport: VertexTransport | None=None) -> None

aclose (method)

async VertexProvider.aclose() -> None

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

Release source · Runtime guarantees · Capability guides

VertexTransport

from cayu.providers import VertexTransport

Bases: Protocol.

count_message_tokens (method)

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

POST a count-tokens rawPredict payload and return decoded JSON.

create_message (method)

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

POST a Vertex rawPredict payload and return decoded JSON.

stream_message_events (method)

VertexTransport.stream_message_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 streamRawPredict payload and yield decoded SSE data objects.

Release source · Runtime guarantees · Capability guides