cayu.providers.base

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.

AuxiliaryInferenceUnsupportedError

from cayu.providers import AuxiliaryInferenceUnsupportedError

The registered adapter cannot safely prepare managed auxiliary inference.

Bases: ModelProviderError.

init (method)

AuxiliaryInferenceUnsupportedError.__init__(*, provider: str) -> None

error_payload_fields (method)

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

copy_input_token_count_result

from cayu.providers import copy_input_token_count_result

copy_input_token_count_result(result: InputTokenCountResult | None) -> InputTokenCountResult | None

Release source · Runtime guarantees · Capability guides

copy_model_context_pressure_profile

from cayu.providers import copy_model_context_pressure_profile

copy_model_context_pressure_profile(profile: ModelContextPressureProfile | None) -> ModelContextPressureProfile

Release source · Runtime guarantees · Capability guides

copy_model_stream_event

from cayu.providers import copy_model_stream_event

copy_model_stream_event(event: ModelStreamEvent) -> ModelStreamEvent

Release source · Runtime guarantees · Capability guides

copy_usage_dialect

from cayu.providers import copy_usage_dialect

Validate and detach a provider’s declared usage-accounting dialect.

Provider attributes are extension-owned and remain mutable after registration. Accept exact built-in strings for compatibility, but never invoke methods on a provider-owned str subclass while establishing accounting authority.

copy_usage_dialect(value: object, field_name: str='usage_dialect') -> UsageDialect

Release source · Runtime guarantees · Capability guides

InputTokenCountConfidence

from cayu.providers import InputTokenCountConfidence

Bases: StrEnum.

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
HIGH	class attribute	'high'
MEDIUM	class attribute	'medium'
LOW	class attribute	'low'
UNAVAILABLE	class attribute	'unavailable'

Release source · Runtime guarantees · Capability guides

InputTokenCountMethod

from cayu.providers import InputTokenCountMethod

How a provider counted one model request before submission.

Bases: StrEnum.

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
OFFICIAL	class attribute	'official'
LOCAL_TOKENIZER	class attribute	'local_tokenizer'
HEURISTIC	class attribute	'heuristic'
UNAVAILABLE	class attribute	'unavailable'

Release source · Runtime guarantees · Capability guides

InputTokenCountResult

from cayu.providers import InputTokenCountResult

Provider-neutral input token count for a model request.

Official provider counters should use method="official" and confidence="high". Official remote counters can add latency and consume provider rate limits. Their billing behavior is provider-specific and should be documented in metadata when known. Local tokenizers and heuristics are useful for observability, but callers should not treat them as hard provider-limit guarantees.

Bases: BaseModel.

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
input_tokens	int | None	Field(default=None, ge=0, le=MAX_DURABLE_JSON_INTEGER)
method	InputTokenCountMethod	required
confidence	InputTokenCountConfidence	required
components	dict[str, int]	Field(default_factory=dict)
metadata	dict[str, Any]	Field(default_factory=dict)

validate_method (method)

InputTokenCountResult.validate_method(value: object) -> InputTokenCountMethod

validate_confidence (method)

InputTokenCountResult.validate_confidence(value: object) -> InputTokenCountConfidence

copy_components (method)

InputTokenCountResult.copy_components(value: dict[str, Any]) -> dict[str, int]

copy_metadata (method)

InputTokenCountResult.copy_metadata(value: dict[str, Any]) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

ModelCompletion

from cayu.providers import ModelCompletion

Provider-neutral completion metadata for a model step.

Bases: BaseModel.

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
finish_reason	ModelFinishReason	required
raw_finish_reason	str | None	None
status	str | None	None
end_turn	bool | None	None

validate_finish_reason (method)

ModelCompletion.validate_finish_reason(value: object) -> ModelFinishReason

validate_optional_clean_string (method)

ModelCompletion.validate_optional_clean_string(value: str | None, info) -> str | None

validate_end_turn (method)

ModelCompletion.validate_end_turn(value: object) -> bool | None

Release source · Runtime guarantees · Capability guides

ModelContextOverflowError

from cayu.providers import ModelContextOverflowError

Provider-neutral signal that a model request was too large for context.

Provider adapters should raise this only for clear context-window or request-size overflow responses. Runtime recovery can then shrink model-facing context and retry without depending on provider-specific exception classes. Overflow is never retryable as-is (retryable=False); recovery must shrink context first.

Bases: ModelProviderError.

init (method)

ModelContextOverflowError.__init__(message: str, *, provider: 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)

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

ModelContextPressureProfile

from cayu.providers import ModelContextPressureProfile

Provider-supplied local context-pressure estimation hints.

Bases: BaseModel.

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
image_min_tokens	int	Field(default=32, ge=0)
document_min_tokens	int	Field(default=0, ge=0)
document_bytes_per_token	int	Field(default=3, ge=1)
tool_schema_chars_per_token	int	Field(default=4, ge=1)

Release source · Runtime guarantees · Capability guides

ModelFinishReason

from cayu.providers import ModelFinishReason

Bases: StrEnum.

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
STOP	class attribute	'stop'
TOOL_CALLS	class attribute	'tool_calls'
LENGTH	class attribute	'length'
CONTENT_FILTER	class attribute	'content_filter'
ERROR	class attribute	'error'
UNKNOWN	class attribute	'unknown'

Release source · Runtime guarantees · Capability guides

ModelProvider

from cayu.providers import ModelProvider

Normalizes provider-specific model streams.

Bases: ABC.

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	str	required
billing_provider_name	str | None	None
usage_dialect	UsageDialect	UsageDialect.AUTO
supports_native_structured_output	bool	False

prepare_auxiliary_request (method)

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

Prepare one bounded request without dispatch, credentials, or I/O.

Supporting adapters return a detached request with their native output token cap. They must preserve model/messages, reject tools and raw options, and must not hide additional provider dispatches. Transparent wrappers delegate this hook. Default unsupported keeps ordinary custom providers usable without granting them managed inference capability.

stream_deadlines (property)

ModelProvider.stream_deadlines() -> ProviderStreamDeadlines

Return immutable dispatch deadlines for this provider.

runtime_stream (method)

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

ModelProvider.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Optional application-versioned identity for opaque adapter behavior.

provider_operation_mode (property)

ModelProvider.provider_operation_mode() -> ProviderOperationMode

Explicit dispatch mode; capability support alone never enables it.

provider_operations (property)

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

ModelProvider.context_pressure_profile() -> ModelContextPressureProfile

request_cache_policy (method)

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

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

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

Project privacy-safe provider-visible options for local measurement.

Implementations must return copied JSON, omit arbitrary metadata and secret-bearing extension fields, and perform no I/O.

request_fingerprint_options (method)

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

Project complete effective provider-visible options for local analysis.

The runtime keeps this copied value ephemeral: it supplies keyed HMAC input when configured and identifies which non-allowlisted option categories are active, but the value and its field names are never persisted. Built-in adapters override this hook so ignored namespaces, defaults, and normalized controls follow their payload-building semantics. The default conservatively treats every non-runtime request option as provider-visible. Implementations must be deterministic, side-effect free, and perform no I/O.

preflight_model_target (method)

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

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

Reject thinking controls whose semantics this adapter has not established.

Routed runs call this side-effect-free hook for every configured target and again for the actual selected request before dispatch. Adapters must preserve native effort values and their documented best-effort controls; passing preflight does not guarantee an unknown backend model accepts them. Transparent wrappers delegate the hook. The default accepts only None.

preflight_portable_messages (method)

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

Reject portable messages or active tools this adapter cannot render.

The runtime calls this side-effect-free hook before durably adopting a different provider/model target and during native peer queue admission. Peer admission may invoke it on a storage worker thread while holding the receiving transaction: it must complete synchronously, return None, perform no I/O, and never reenter storage. Adapters must explicitly override this method to admit system messages, tool history, active tool definitions, or file attachments. The conservative default accepts only user/assistant text with no active tools, so an existing custom provider cannot silently claim support for request material its renderer may reject.

preflight_hosted_tools (method)

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

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

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

Reject targeted-tool authority that this provider cannot project.

supports_tool_discovery_projection (method)

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

Report an explicitly established provider/model discovery capability.

preflight_tool_discovery_projection (method)

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

Reject discovery authority that this provider cannot project.

billing_identity_for_request (method)

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

Resolve optional request context needed for commercial accounting.

billing_identity_for_completion (method)

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

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

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

Implement the provider’s raw, ungoverned adapter stream hook.

Direct calls bypass the provider-neutral normalized deadline guard. Governed model attempts must call runtime_stream instead.

Error contract: ModelContextOverflowError must propagate as an exception (never be flattened into an error event) so runtime context-overflow recovery can shrink context and retry. Other failures should surface as ModelStreamEvent.error(message, cause=exc) events so typed classification fields survive into the runtime payload.

Release source · Runtime guarantees · Capability guides

ModelProviderError

from cayu.providers import ModelProviderError

Provider-neutral structured model provider failure.

Provider adapters should raise subclasses of this (or wrap SDK/HTTP failures into it) instead of flattening failures to bare message strings. The typed fields let runtime code classify retries (status_code, retryable, retry_after_s) and let observability keep the provider’s own error identity (error_type, error_code, request_id) without re-parsing message text. retryable is tri-state: None means the provider did not classify the failure, leaving the decision to runtime retry policy.

Bases: RuntimeError.

init (method)

ModelProviderError.__init__(message: str, *, provider: 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, rejection_diagnostic: dict[str, str] | None=None) -> None

error_payload_fields (method)

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

ModelRequest

from cayu.providers import ModelRequest

Bases: BaseModel.

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
model	str	required
messages	list[Message]	required
tools	list[dict[str, Any]]	Field(default_factory=list)
hosted_tools	tuple[OpenAIWebSearch, ...]	()
targeted_tool_projection	TargetedToolProjectionRequest | None	None
tool_discovery_projection	ToolDiscoveryProjectionRequest | None	None
options	dict[str, Any]	Field(default_factory=dict)

copy_targeted_tool_projection (method)

ModelRequest.copy_targeted_tool_projection(value: object) -> TargetedToolProjectionRequest | None

copy_tool_discovery_projection (method)

ModelRequest.copy_tool_discovery_projection(value: object) -> ToolDiscoveryProjectionRequest | None

copy_messages (method)

ModelRequest.copy_messages(value)

copy_json_request_data (method)

ModelRequest.copy_json_request_data(value, info)

copy_hosted_tools (method)

ModelRequest.copy_hosted_tools(value: object) -> tuple[OpenAIWebSearch, ...]

validate_nonblank_model (method)

ModelRequest.validate_nonblank_model(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

ModelStreamDeadlineError

from cayu.providers import ModelStreamDeadlineError

Typed content-free expiry of one dispatched model stream.

Bases: ModelProviderError.

init (method)

ModelStreamDeadlineError.__init__(*, provider: str, evidence: ProviderStreamDeadlineEvidence, stream_cleanup_failed: bool=False, recovery_disposition: ModelStreamRecoveryDisposition=MANUAL_MODEL_STREAM_RECOVERY_DISPOSITION) -> None

error_payload_fields (method)

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

Release source · Runtime guarantees · Capability guides

ModelStreamEvent

from cayu.providers import ModelStreamEvent

Provider-native stream event.

Provider adapters may expose this lower-level shape while normalizing SDK responses. Runtime code must convert these events into Cayu Event records before persisting, dashboarding, or forwarding them.

Bases: BaseModel.

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
type	ModelStreamEventType	required
delta	str	''
payload	dict[str, Any]	Field(default_factory=dict)
completion	ModelCompletion | None	None
tool_discovery_result	ToolDiscoveryProjectionResult | None	Field(default=None, exclude_if=lambda value: value is None)
recovery_metadata	ProviderOperationRecoveryMetadata | None	Field(default=None, exclude_if=lambda value: value is None)
provider_operation_status	ProviderOperationStatus | None	Field(default=None, exclude_if=lambda value: value is None)

copy_payload (method)

ModelStreamEvent.copy_payload(value: dict[str, Any]) -> dict[str, Any]

copy_completion (method)

ModelStreamEvent.copy_completion(value: ModelCompletion | None) -> ModelCompletion | None

copy_tool_discovery_result (method)

ModelStreamEvent.copy_tool_discovery_result(value: object) -> ToolDiscoveryProjectionResult | None

validate_type (method)

ModelStreamEvent.validate_type(value: object) -> ModelStreamEventType

validate_completion (method)

ModelStreamEvent.validate_completion() -> ModelStreamEvent

text_delta (method)

ModelStreamEvent.text_delta(delta: str, *, recovery_metadata: ProviderOperationRecoveryMetadata | dict[str, Any] | None=None) -> ModelStreamEvent

thinking (method)

ModelStreamEvent.thinking(delta: str='', *, provider_state: dict[str, Any] | None=None, recovery_metadata: ProviderOperationRecoveryMetadata | dict[str, Any] | None=None) -> ModelStreamEvent

A reasoning/thinking event.

delta is the (possibly empty) reasoning text. provider_state carries the opaque round-trip payload of a complete block — the Anthropic signature or redacted_thinking data. When present, the runtime materializes a standalone ThinkingPart; events without it accumulate as streamed text.

tool_call (method)

ModelStreamEvent.tool_call(*, name: str, arguments: dict[str, Any], id: str | None=None, recovery_metadata: ProviderOperationRecoveryMetadata | dict[str, Any] | None=None) -> ModelStreamEvent

hosted_tool_call (method)

ModelStreamEvent.hosted_tool_call(payload: dict[str, Any], *, recovery_metadata: ProviderOperationRecoveryMetadata | dict[str, Any] | None=None) -> ModelStreamEvent

citation (method)

ModelStreamEvent.citation(payload: dict[str, Any], *, recovery_metadata: ProviderOperationRecoveryMetadata | dict[str, Any] | None=None) -> ModelStreamEvent

completed (method)

ModelStreamEvent.completed(payload: dict[str, Any] | None=None, *, recovery_metadata: ProviderOperationRecoveryMetadata | dict[str, Any] | None=None) -> ModelStreamEvent

error (method)

ModelStreamEvent.error(message: str, *, cause: Exception | None=None, recovery_metadata: ProviderOperationRecoveryMetadata | dict[str, Any] | None=None, provider_operation_status: ProviderOperationStatus | None=None) -> ModelStreamEvent

An error event; cause preserves typed classification in the payload.

When cause is a ModelProviderError, its structured fields (provider, status_code, provider_error_type/provider_error_code, request_id, retryable, retry_after_s) join the payload so retry classification and observability survive the event boundary instead of collapsing to text. A ModelContextOverflowError cause additionally sets context_overflow: True so runtime overflow recovery keeps its typed signal even when a provider flattens the overflow into an error event instead of raising it as stream() requires.

Release source · Runtime guarantees · Capability guides

ModelStreamEventType

from cayu.providers import ModelStreamEventType

Bases: StrEnum.

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
TEXT_DELTA	class attribute	'text_delta'
THINKING	class attribute	'thinking'
TOOL_CALL	class attribute	'tool_call'
HOSTED_TOOL_CALL	class attribute	'hosted_tool_call'
CITATION	class attribute	'citation'
COMPLETED	class attribute	'completed'
ERROR	class attribute	'error'

Release source · Runtime guarantees · Capability guides

NativeStructuredOutputSchemaInvalid

from cayu.providers import NativeStructuredOutputSchemaInvalid

A strategy=NATIVE structured-output JSON Schema uses constructs the resolved provider’s native mode would reject at request time.

Raised by ModelProvider.preflight_native_structured_output_schema before any session is created or transitioned, so the caller can fix the schema (the message names the offending JSON path, e.g. $/properties/address) or retry with strategy="tool" (same JSON contract, provider-neutral transport). Subclasses ValueError so existing handlers (including the server’s 4xx mapping) keep working.

Bases: ValueError.

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

Release source · Runtime guarantees · Capability guides

normalize_model_completion

from cayu.providers import normalize_model_completion

Normalize known provider completion payloads without discarding raw fields.

normalize_model_completion(payload: dict[str, Any]) -> ModelCompletion

Release source · Runtime guarantees · Capability guides

TargetedToolProjectionRequest

from cayu.providers import TargetedToolProjectionRequest

Ephemeral provider projection anchored by one durable transcript marker.

Bases: BaseModel.

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
protocol	Literal['openai.additional_tools.v1']	OPENAI_ADDITIONAL_TOOLS_PROTOCOL
marker_id	str	Field(pattern='^sha256:[0-9a-f]{64}$')
tools	tuple[dict[str, Any], ...]	Field(min_length=1, max_length=32)

copy_tools (method)

TargetedToolProjectionRequest.copy_tools(value: object) -> tuple[dict[str, Any], ...]

validate_tools (method)

TargetedToolProjectionRequest.validate_tools() -> TargetedToolProjectionRequest

Release source · Runtime guarantees · Capability guides

ToolDiscoveryProjectionRequest

from cayu.providers import ToolDiscoveryProjectionRequest

Provider-native projection of Cayu’s durable discovery protocol.

Bases: BaseModel.

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
protocol	Literal['openai.tool_search.client.v1', 'openai.tool_search.hosted.v1']	OPENAI_CLIENT_TOOL_SEARCH_PROTOCOL
loaded_tools	tuple[dict[str, Any], ...]	Field(default=(), max_length=TOOL_DISCOVERY_PROJECTION_MAX_TOOLS)
candidate_tools	tuple[dict[str, Any], ...]	Field(default=(), max_length=TOOL_DISCOVERY_PROJECTION_MAX_TOOLS)
generation_id	str | None	Field(default=None, min_length=71, max_length=71)

validate_generation_id (method)

ToolDiscoveryProjectionRequest.validate_generation_id(value: str | None) -> str | None

copy_tools (method)

ToolDiscoveryProjectionRequest.copy_tools(value: object, info) -> tuple[dict[str, Any], ...]

validate_tools (method)

ToolDiscoveryProjectionRequest.validate_tools() -> ToolDiscoveryProjectionRequest

loaded_tool_names (property)

ToolDiscoveryProjectionRequest.loaded_tool_names() -> tuple[str, ...]

Return the canonical names without duplicating projection authority.

candidate_tool_names (property)

ToolDiscoveryProjectionRequest.candidate_tool_names() -> tuple[str, ...]

Return hosted candidate names without duplicating projection authority.

Release source · Runtime guarantees · Capability guides

ToolDiscoveryProjectionResult

from cayu.providers import ToolDiscoveryProjectionResult

Normalized provider evidence for one hosted discovery selection.

Bases: BaseModel.

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
protocol	Literal['openai.tool_search.hosted.v1']	OPENAI_HOSTED_TOOL_SEARCH_PROTOCOL
loaded_tools	tuple[dict[str, Any], ...]	Field(default=(), max_length=TOOL_DISCOVERY_PROJECTION_MAX_TOOLS)

copy_loaded_tools (method)

ToolDiscoveryProjectionResult.copy_loaded_tools(value: object) -> tuple[dict[str, Any], ...]

loaded_tool_names (property)

ToolDiscoveryProjectionResult.loaded_tool_names() -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

UsageDialect

from cayu.providers import UsageDialect

How a provider’s raw usage payload encodes token counters.

The runtime’s usage normalizer folds cache tokens differently per dialect (Anthropic reports cache read/write tokens in separate fields excluded from input_tokens; Gemini may exclude hidden thinking tokens from completion_tokens while including them in total_tokens; OpenAI nests cached input in *_tokens_details). A provider whose registered name is not one of the built-in aliases — Claude reached through Bedrock, a gateway, or a renamed adapter — must declare its dialect here so the normalizer folds cache tokens correctly instead of silently undercounting (and under-billing) them. AUTO (the default) lets the normalizer infer the dialect from the payload shape.

Bases: StrEnum.

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
AUTO	class attribute	'auto'
ANTHROPIC	class attribute	'anthropic'
GEMINI	class attribute	'gemini'
OPENAI	class attribute	'openai'
GENERIC	class attribute	'generic'

Release source · Runtime guarantees · Capability guides