cayu.runtime.retry_policy

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.

classify_retryable_error

from cayu import classify_retryable_error

Classify a failure into a retry reason and effective HTTP status code.

A typed status_code (e.g. from ModelProviderError.status_code) is preferred over the regex scan of error. A typed retryable flag is the provider’s own tri-state verdict: False short-circuits to a terminal decision, True is honored as a transient failure when neither the status code nor the message text already matched a configured pattern.

classify_retryable_error(*, policy: RetryPolicy, error: str, status_code: int | None=None, retryable: bool | None=None) -> tuple[RetryReason | None, int | None]

Release source · Runtime guarantees · Capability guides

copy_retry_policy

from cayu import copy_retry_policy

Validate policy and return it unchanged (default policy for None).

RetryPolicy is frozen with immutable field values, so sharing the instance is safe — the previous per-attempt field-by-field rebuild was a drift-prone no-op.

copy_retry_policy(policy: RetryPolicy | None) -> RetryPolicy

Release source · Runtime guarantees · Capability guides

retry_decision

from cayu import retry_decision

Classify one failed model attempt into a retry decision.

status_code, retryable, and retry_after_s are the typed fields a provider exposes on ModelProviderError. When supplied they take precedence over reparsing error text: status_code seeds classification directly, retryable=False forces a terminal decision, and retry_after_s overrides the computed backoff so a provider Retry-After directive is honored. They default to None so string-only callers keep the legacy regex behavior. unknown_provider_error=True identifies a provider failure that retained no safe retry classification after typed parsing. Such failures use the stricter max_unknown_attempts ceiling and never consume the caller’s full general retry budget by default. suppression carries existing runtime authority independently of the provider verdict and always prevents another attempt. disposition explains terminal decisions even when reason is absent. retryable_output marks a caller-validated output failure, independently of transport retry settings. It requires an explicit retryable verdict and no HTTP status; suppression and the general attempt ceiling still apply.

retry_decision(*, policy: RetryPolicy, attempt: int, error: str, status_code: int | None=None, retryable: bool | None=None, retry_after_s: float | None=None, unknown_provider_error: bool=False, retryable_output: bool=False, suppression: RetrySuppression | None=None) -> RetryDecision

Release source · Runtime guarantees · Capability guides

RetryPolicy

from cayu import RetryPolicy

Retry controls for one provider model step.

max_attempts includes the initial attempt. The default permits five total attempts for classified transient provider failures. Unknown provider failures retain the stricter max_unknown_attempts ceiling.

Frozen: policies are immutable value objects, so they can be shared across attempts and sessions without per-attempt defensive copies.

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
max_attempts	StrictInt	Field(default=5, ge=1, le=50)
max_unknown_attempts	StrictInt	Field(default=2, ge=1, le=50)
initial_delay_s	StrictFloat	Field(default=0.5, ge=0.0, le=600.0)
max_delay_s	StrictFloat	Field(default=30.0, ge=0.0, le=3600.0)
backoff_multiplier	StrictFloat	Field(default=2.0, ge=1.0, le=10.0)
jitter_s	StrictFloat	Field(default=0.5, ge=0.0, le=600.0)
retry_on_status_codes	tuple[StrictInt, ...]	Field(default=DEFAULT_RETRYABLE_STATUS_CODES, min_length=0, max_length=32)
retry_on_timeout	StrictBool	True
retry_on_connection_error	StrictBool	True
retry_on_rate_limit	StrictBool	True

validate_status_codes (method)

RetryPolicy.validate_status_codes(value: tuple[int, ...]) -> tuple[int, ...]

Release source · Runtime guarantees · Capability guides