cayu.tasks.records

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.

`Task`

from cayu.tasks import Task

Durable unit of work.

Tasks are intentionally generic. They can represent background jobs, workflow steps, external work items, orchestrator assignments, or a single-agent durable job.

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
`id`	`str`	`Field(default_factory=lambda: str(uuid4()))`
`type`	`str`	`required`
`title`	`str \| None`	`None`
`description`	`str \| None`	`None`
`status`	`TaskStatus`	`TaskStatus.PENDING`
`session_id`	`str \| None`	`None`
`session_instance_id`	`str \| None`	`None`
`parent_task_id`	`str \| None`	`None`
`assigned_agent_name`	`str \| None`	`None`
`graph_id`	`str \| None`	`Field(default=None, frozen=True)`
`prerequisite_task_ids`	`tuple[str, ...]`	`Field(default=(), frozen=True)`
`available_at`	`datetime \| None`	`None`
`worker_id`	`str \| None`	`None`
`lease_expires_at`	`datetime \| None`	`None`
`interrupted_handoff_id`	`str \| None`	`None`
`status_reason`	`str \| None`	`None`
`status_payload`	`dict[str, Any] \| None`	`None`
`input`	`dict[str, Any]`	`Field(default_factory=dict)`
`result`	`dict[str, Any] \| None`	`None`
`error`	`dict[str, Any] \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`
`created_at`	`datetime`	`Field(default_factory=lambda: datetime.now(UTC))`
`updated_at`	`datetime`	`Field(default_factory=lambda: datetime.now(UTC))`
`started_at`	`datetime \| None`	`None`
`completed_at`	`datetime \| None`	`None`
`invocation`	`TaskInvocation`	`Field(frozen=True)`
`schedule`	`TaskScheduleState \| None`	`None`
`retry_series`	`TaskRetrySeriesSnapshot \| None`	`None`
`work_contract`	`WorkContractRef \| None`	`Field(default=None, frozen=True)`

validate_graph_membership (method)

Task.validate_graph_membership() -> Task

preflight_work_contract_payloads (method)

Task.preflight_work_contract_payloads(value: object) -> object

copy_json_object (method)

Task.copy_json_object(value: dict[str, Any], info) -> dict[str, Any]

copy_optional_json_object (method)

Task.copy_optional_json_object(value: dict[str, Any] | None, info) -> dict[str, Any] | None

validate_nonblank_required_strings (method)

Task.validate_nonblank_required_strings(value: str, info) -> str

validate_optional_nonblank_strings (method)

Task.validate_optional_nonblank_strings(value: str | None, info) -> str | None

validate_session_instance_id (method)

Task.validate_session_instance_id(value: str | None) -> str | None

normalize_available_at (method)

Task.normalize_available_at(value: datetime | None) -> datetime | None

copy_schedule (method)

Task.copy_schedule(value: object) -> object

validate_schedule (method)

Task.validate_schedule() -> Task

copy_work_contract (method)

Task.copy_work_contract(value: object) -> object

validate_retry_and_work_contract_authority (method)

Task.validate_retry_and_work_contract_authority() -> Task

Release source · Runtime guarantees · Capability guides

`TaskRetryPolicy`

from cayu.tasks import TaskRetryPolicy

Serializable cumulative limits and backoff for one task retry series.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`max_attempts`	`StrictInt`	`Field(ge=1, le=100)`
`max_elapsed_seconds`	`StrictFloat \| None`	`Field(default=None, gt=0, le=31536000)`
`max_total_tokens`	`StrictInt \| None`	`Field(default=None, gt=0, le=MAX_DURABLE_JSON_INTEGER, description='Maximum cumulative reported tokens used for retry-successor admission; not an external-dispatch reservation.')`
`max_estimated_cost`	`Decimal \| None`	`Field(default=None, gt=0, description='Maximum cumulative reported estimated cost used for retry-successor admission; not an external-dispatch reservation.')`
`cost_currency`	`str`	`'USD'`
`initial_backoff_seconds`	`StrictFloat`	`Field(default=1.0, ge=0, le=86400)`
`backoff_multiplier`	`StrictFloat`	`Field(default=2.0, ge=1, le=100)`
`max_backoff_seconds`	`StrictFloat`	`Field(default=300.0, ge=0, le=86400)`

validate_bounds (method)

TaskRetryPolicy.validate_bounds() -> TaskRetryPolicy

validate_max_estimated_cost (method)

TaskRetryPolicy.validate_max_estimated_cost(value: Decimal | None) -> Decimal | None

validate_cost_currency (method)

TaskRetryPolicy.validate_cost_currency(value: str) -> str

Release source · Runtime guarantees · Capability guides

`TaskRetrySeriesDisposition`

from cayu.tasks import TaskRetrySeriesDisposition

Durable retry-series state or terminal reason.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`ACTIVE`	`class attribute`	`'active'`
`RETRY_SCHEDULED`	`class attribute`	`'retry_scheduled'`
`SUCCEEDED`	`class attribute`	`'succeeded'`
`NON_RETRYABLE_FAILURE`	`class attribute`	`'non_retryable_failure'`
`CANCELLED`	`class attribute`	`'cancelled'`
`ATTEMPTS_EXHAUSTED`	`class attribute`	`'attempts_exhausted'`
`ELAPSED_EXHAUSTED`	`class attribute`	`'elapsed_exhausted'`
`TOKENS_EXHAUSTED`	`class attribute`	`'tokens_exhausted'`
`COST_EXHAUSTED`	`class attribute`	`'cost_exhausted'`

Release source · Runtime guarantees · Capability guides

`TaskRetrySeriesSnapshot`

from cayu.tasks import TaskRetrySeriesSnapshot

Bounded cumulative retry authority carried by each durable attempt.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`series_id`	`str`	`required`
`causal_budget_id`	`str`	`required`
`authority_sha256`	`str`	`required`
`attempt`	`StrictInt`	`Field(ge=1, le=100)`
`policy`	`TaskRetryPolicy`	`required`
`started_at`	`datetime`	`required`
`cumulative_tokens`	`StrictInt`	`Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`cumulative_estimated_cost`	`Decimal`	`Field(default=Decimal(0), ge=0)`
`attempts_remaining`	`StrictInt`	`Field(ge=0, le=99)`
`tokens_remaining`	`StrictInt \| None`	`Field(default=None, ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`estimated_cost_remaining`	`Decimal \| None`	`Field(default=None, ge=0)`
`elapsed_deadline`	`datetime \| None`	`None`
`disposition`	`TaskRetrySeriesDisposition`	`TaskRetrySeriesDisposition.ACTIVE`
`predecessor_task_id`	`str \| None`	`None`
`successor_task_id`	`str \| None`	`None`
`next_eligible_at`	`datetime \| None`	`None`

validate_series_identity (method)

TaskRetrySeriesSnapshot.validate_series_identity(value: str, info) -> str

validate_authority_sha256 (method)

TaskRetrySeriesSnapshot.validate_authority_sha256(value: str) -> str

validate_optional_task_id (method)

TaskRetrySeriesSnapshot.validate_optional_task_id(value: str | None, info) -> str | None

normalize_started_at (method)

TaskRetrySeriesSnapshot.normalize_started_at(value: datetime) -> datetime

normalize_next_eligible_at (method)

TaskRetrySeriesSnapshot.normalize_next_eligible_at(value: datetime | None) -> datetime | None

normalize_elapsed_deadline (method)

TaskRetrySeriesSnapshot.normalize_elapsed_deadline(value: datetime | None) -> datetime | None

validate_estimated_costs (method)

TaskRetrySeriesSnapshot.validate_estimated_costs(value: Decimal | None, info) -> Decimal | None

validate_snapshot (method)

TaskRetrySeriesSnapshot.validate_snapshot() -> TaskRetrySeriesSnapshot

Release source · Runtime guarantees · Capability guides

`TaskStatus`

from cayu.tasks import TaskStatus

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`PENDING`	`class attribute`	`'pending'`
`WAITING_DEPENDENCIES`	`class attribute`	`'waiting_dependencies'`
`WAITING_GROUP`	`class attribute`	`'waiting_group'`
`DEPENDENCY_SKIPPED`	`class attribute`	`'dependency_skipped'`
`CLAIMED`	`class attribute`	`'claimed'`
`RUNNING`	`class attribute`	`'running'`
`PAUSED`	`class attribute`	`'paused'`
`BLOCKED`	`class attribute`	`'blocked'`
`NEEDS_ATTENTION`	`class attribute`	`'needs_attention'`
`COMPLETED`	`class attribute`	`'completed'`
`FAILED`	`class attribute`	`'failed'`
`CANCELLED`	`class attribute`	`'cancelled'`

Release source · Runtime guarantees · Capability guides