cayu.tasks.topology

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.

`TaskTopologyChildBranch`

from cayu.tasks import TaskTopologyChildBranch

Direct task children of one explicitly expanded task.

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
`parent_task_id`	`str`	`required`
`children`	`tuple[TaskTopologyNode, ...]`	`Field(default=(), max_length=TASK_TOPOLOGY_MAX_BRANCH_LIMIT)`
`next_cursor`	`str \| None`	`None`
`has_more`	`StrictBool`	`False`

validate_parent_task_id (method)

TaskTopologyChildBranch.validate_parent_task_id(value: str) -> str

validate_shape (method)

TaskTopologyChildBranch.validate_shape() -> TaskTopologyChildBranch

Release source · Runtime guarantees · Capability guides

`TaskTopologyCycle`

from cayu.tasks import TaskTopologyCycle

Durable parent-task records contain a cycle reachable from the projection.

Bases: ValueError.

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

Release source · Runtime guarantees · Capability guides

`TaskTopologyInconsistent`

from cayu.tasks import TaskTopologyInconsistent

Durable task records cannot form a truthful bounded topology projection.

Bases: ValueError.

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

Release source · Runtime guarantees · Capability guides

`TaskTopologyNode`

from cayu.tasks import TaskTopologyNode

Payload-free bounded identity for one task topology node.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`id`	`str`	`required`
`type`	`str \| None`	`required`
`title`	`str \| None`	`required`
`status`	`TaskStatus`	`required`
`status_reason`	`str \| None`	`required`
`session_id`	`str \| None`	`required`
`parent_task_id`	`str \| None`	`required`
`assigned_agent_name`	`str \| None`	`required`
`created_at`	`datetime`	`required`
`updated_at`	`datetime`	`required`
`truncated_fields`	`tuple[TaskTopologyTruncatedField, ...]`	`()`

from_task (method)

TaskTopologyNode.from_task(task: Task) -> TaskTopologyNode

validate_id (method)

TaskTopologyNode.validate_id(value: str) -> str

validate_optional_ids (method)

TaskTopologyNode.validate_optional_ids(value: str | None, info) -> str | None

validate_optional_clean_display (method)

TaskTopologyNode.validate_optional_clean_display(value: str | None, info) -> str | None

validate_optional_display (method)

TaskTopologyNode.validate_optional_display(value: str | None, info) -> str | None

normalize_timestamps (method)

TaskTopologyNode.normalize_timestamps(value: datetime, info) -> datetime

validate_truncated_fields (method)

TaskTopologyNode.validate_truncated_fields(value: tuple[TaskTopologyTruncatedField, ...]) -> tuple[TaskTopologyTruncatedField, ...]

validate_display_omissions (method)

TaskTopologyNode.validate_display_omissions() -> TaskTopologyNode

Release source · Runtime guarantees · Capability guides

`TaskTopologyQuery`

from cayu.tasks import TaskTopologyQuery

Batched task links for explicitly expanded session and task branches.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`linked_session_ids`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=TASK_TOPOLOGY_MAX_EXPANDED_SESSIONS)`
`session_cursors`	`dict[str, str]`	`Field(default_factory=dict, max_length=TASK_TOPOLOGY_MAX_EXPANDED_SESSIONS)`
`expanded_parent_ids`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=TASK_TOPOLOGY_MAX_EXPANDED_PARENTS)`
`child_cursors`	`dict[str, str]`	`Field(default_factory=dict, max_length=TASK_TOPOLOGY_MAX_EXPANDED_PARENTS)`
`session_task_limit`	`StrictInt`	`Field(default=TASK_TOPOLOGY_DEFAULT_BRANCH_LIMIT, ge=1, le=TASK_TOPOLOGY_MAX_BRANCH_LIMIT)`
`child_limit`	`StrictInt`	`Field(default=TASK_TOPOLOGY_DEFAULT_BRANCH_LIMIT, ge=1, le=TASK_TOPOLOGY_MAX_BRANCH_LIMIT)`

copy_branch_ids (method)

TaskTopologyQuery.copy_branch_ids(value, info) -> tuple[str, ...]

copy_cursors (method)

TaskTopologyQuery.copy_cursors(value, info) -> dict[str, str]

validate_cursor_authority (method)

TaskTopologyQuery.validate_cursor_authority() -> TaskTopologyQuery

Release source · Runtime guarantees · Capability guides

`TaskTopologySessionBranch`

from cayu.tasks import TaskTopologySessionBranch

Tasks attached to one explicitly expanded session.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`session_id`	`str`	`required`
`tasks`	`tuple[TaskTopologyNode, ...]`	`Field(default=(), max_length=TASK_TOPOLOGY_MAX_BRANCH_LIMIT)`
`next_cursor`	`str \| None`	`None`
`has_more`	`StrictBool`	`False`

validate_session_id (method)

TaskTopologySessionBranch.validate_session_id(value: str) -> str

validate_shape (method)

TaskTopologySessionBranch.validate_shape() -> TaskTopologySessionBranch

Release source · Runtime guarantees · Capability guides

`TaskTopologyStoreResult`

from cayu.tasks import TaskTopologyStoreResult

Backend-neutral bounded task projection captured by one task-store snapshot.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`observed_at`	`datetime`	`required`
`session_branches`	`tuple[TaskTopologySessionBranch, ...]`	`Field(default=(), max_length=TASK_TOPOLOGY_MAX_EXPANDED_SESSIONS)`
`expanded_parents`	`tuple[TaskTopologyNode, ...]`	`Field(default=(), max_length=TASK_TOPOLOGY_MAX_EXPANDED_PARENTS)`
`child_branches`	`tuple[TaskTopologyChildBranch, ...]`	`Field(default=(), max_length=TASK_TOPOLOGY_MAX_EXPANDED_PARENTS)`

normalize_observed_at (method)

TaskTopologyStoreResult.normalize_observed_at(value: datetime) -> datetime

validate_shape (method)

TaskTopologyStoreResult.validate_shape() -> TaskTopologyStoreResult

validate_for_query (method)

TaskTopologyStoreResult.validate_for_query(query: TaskTopologyQuery) -> TaskTopologyStoreResult

Verify that a custom store honored the exact requested branches and bounds.

Release source · Runtime guarantees · Capability guides

`TaskTopologyTraversalLimitExceeded`

from cayu.tasks import TaskTopologyTraversalLimitExceeded

Task ancestry cannot be validated within the bounded topology contract.

Bases: ValueError.

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

Release source · Runtime guarantees · Capability guides