cayu.providers.anthropic

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.

anthropic_response_events

from cayu.providers import anthropic_response_events

anthropic_response_events(response: Mapping[str, Any], *, reasoning_provenance: ReasoningStateProvenance=_DEFAULT_ANTHROPIC_REASONING_PROVENANCE) -> list[ModelStreamEvent]

Release source · Runtime guarantees · Capability guides

anthropic_stream_events

from cayu.providers import anthropic_stream_events

Translate Anthropic Messages SSE events into Cayu model stream events.

Text streams incrementally as it arrives. Thinking and tool_use blocks are buffered per content-block index and emitted whole at content_block_stop: a thinking block’s signature is computed over its complete text (a partial block cannot round-trip), and tool_use arguments arrive as partial JSON that only parses once complete. Usage merges message_start input counts with the message_delta output counts. The error classes are parameterized so Anthropic-compatible hosts (Vertex) surface their own typed errors.

async anthropic_stream_events(events: AsyncIterator[Mapping[str, Any]], *, provider_label: str='Anthropic', api_error: Callable[..., Exception]=AnthropicAPIError, protocol_error: type[Exception]=AnthropicProtocolError, context_overflow_error: Callable[..., Exception]=AnthropicContextOverflowError, reasoning_provenance: ReasoningStateProvenance=_DEFAULT_ANTHROPIC_REASONING_PROVENANCE) -> AsyncIterator[ModelStreamEvent]

Release source · Runtime guarantees · Capability guides

AnthropicAPIError

from cayu.providers import AnthropicAPIError

Raised when the Anthropic HTTP API returns an error response.

Bases: AnthropicError, ModelProviderError.

init (method)

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

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

AnthropicContextOverflowError

from cayu.providers import AnthropicContextOverflowError

Raised when Anthropic reports that the request exceeds context limits.

Bases: AnthropicAPIError, ModelContextOverflowError.

init (method)

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

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

AnthropicError

from cayu.providers import AnthropicError

Base error for Anthropic provider failures.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

AnthropicProtocolError

from cayu.providers import AnthropicProtocolError

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

Bases: AnthropicError.

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

Release source · Runtime guarantees · Capability guides

AnthropicProvider

from cayu.providers import AnthropicProvider

Anthropic Messages API adapter for Cayu’s provider-neutral runtime.

The API key comes from one of two credential sources: a plain api_key string (or ANTHROPIC_API_KEY), or an async vault-backed path — pass api_key_ref (a SecretRef) plus credential_proxy (e.g. AllowlistProxy). With a ref, every request first authorizes the provider destination against the proxy and then resolves the key at the last moment, so raw credentials never live in provider config.

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

prepare_auxiliary_request (method)

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

stream_deadlines (property)

AnthropicProvider.stream_deadlines() -> ProviderStreamDeadlines

runtime_stream (method)

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

AnthropicProvider.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque adapter behavior.

provider_operation_mode (property)

AnthropicProvider.provider_operation_mode() -> ProviderOperationMode

Explicit dispatch mode; capability support alone never enables it.

provider_operations (property)

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

AnthropicProvider.context_pressure_profile() -> ModelContextPressureProfile

request_cache_policy (method)

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

request_cache_projection (method)

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

request_footprint_options (method)

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

request_fingerprint_options (method)

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

preflight_model_target (method)

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

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

preflight_portable_messages (method)

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

preflight_hosted_tools (method)

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

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

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

Reject targeted-tool authority that this provider cannot project.

supports_tool_discovery_projection (method)

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

Report an explicitly established provider/model discovery capability.

preflight_tool_discovery_projection (method)

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

Reject discovery authority that this provider cannot project.

billing_identity_for_request (method)

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

Resolve optional request context needed for commercial accounting.

billing_identity_for_completion (method)

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

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

stream (method)

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

anthropic_version (property)

AnthropicProvider.anthropic_version() -> str

Return the immutable wire and reasoning-state protocol version.

init (method)

AnthropicProvider.__init__(*, api_key: str | None=None, api_key_ref: SecretRef | None=None, credential_proxy: CredentialProxy | None=None, name: str='anthropic', base_url: str=DEFAULT_ANTHROPIC_BASE_URL, allow_http: bool=False, anthropic_version: str=DEFAULT_ANTHROPIC_VERSION, max_tokens: int=DEFAULT_ANTHROPIC_MAX_TOKENS, timeout_s: float=DEFAULT_ANTHROPIC_TIMEOUT_SECONDS, stream_deadlines: ProviderStreamDeadlines | None=None, transport: AnthropicTransport | None=None, extra_headers: Mapping[str, str] | None=None, cache_policy: CachePolicy | None=None) -> None

aclose (method)

async AnthropicProvider.aclose() -> None

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

Release source · Runtime guarantees · Capability guides

AnthropicTransport

from cayu.providers import AnthropicTransport

Bases: Protocol.

count_message_tokens (method)

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

POST a Messages token-count payload and return decoded JSON.

create_message (method)

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

POST a Messages API payload and return decoded JSON.

stream_message_events (method)

AnthropicTransport.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 streaming Messages API payload and yield decoded SSE data objects.

Release source · Runtime guarantees · Capability guides

build_anthropic_payload

from cayu.providers import build_anthropic_payload

build_anthropic_payload(request: ModelRequest, *, default_max_tokens: int=DEFAULT_ANTHROPIC_MAX_TOKENS, cache_policy: CachePolicy | None=None, reasoning_provenance: ReasoningStateProvenance=_DEFAULT_ANTHROPIC_REASONING_PROVENANCE) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

HttpxAnthropicTransport

from cayu.providers import HttpxAnthropicTransport

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)

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

aclose (method)

async HttpxAnthropicTransport.aclose() -> None

count_message_tokens (method)

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

create_message (method)

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

stream_message_events (method)

async HttpxAnthropicTransport.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