cayu.runtime.loop_policies

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.

BeforeStopAction

from cayu import BeforeStopAction

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
COMPLETE	class attribute	'complete'
CONTINUE	class attribute	'continue'
INTERRUPT	class attribute	'interrupt'
FAIL	class attribute	'fail'

Release source · Runtime guarantees · Capability guides

BeforeStopContext

from cayu import BeforeStopContext

Immutable context passed to loop policies at the before-stop boundary.

init (method)

BeforeStopContext.__init__(*, session: Session, step_result: AssistantStepResult, classification: StepClassification, step: int, max_steps: int, metadata: dict[str, Any], messages: Sequence[Message]=(), continuation_message_indices: Iterable[int]=()) -> None

session (property)

BeforeStopContext.session() -> Session

step_result (property)

BeforeStopContext.step_result() -> AssistantStepResult

classification (property)

BeforeStopContext.classification() -> StepClassification

step (property)

BeforeStopContext.step() -> int

max_steps (property)

BeforeStopContext.max_steps() -> int

metadata (property)

BeforeStopContext.metadata() -> dict[str, Any]

messages (property)

BeforeStopContext.messages() -> tuple[Message, ...]

Durable conversation messages at this boundary, oldest first.

Includes tool results and runtime-authored continuation messages. An empty model step that produced nothing is not a message and is absent.

continuation_message_indices (property)

BeforeStopContext.continuation_message_indices() -> frozenset[int]

Positions of this policy’s retained, durably appended continuation sequence.

Release source · Runtime guarantees · Capability guides

BeforeStopDecision

from cayu import BeforeStopDecision

Control decision returned before Cayu marks a no-tool-call step complete.

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
action	BeforeStopAction	BeforeStopAction.COMPLETE
reason	str	'complete'
message	Message | None	None
metadata	dict[str, Any]	Field(default_factory=dict)

complete (method)

BeforeStopDecision.complete(reason: str='complete', **metadata: Any) -> BeforeStopDecision

continue_with (method)

BeforeStopDecision.continue_with(message: Message, *, reason: str='continue', metadata: dict[str, Any] | None=None) -> BeforeStopDecision

interrupt (method)

BeforeStopDecision.interrupt(reason: str, *, metadata: dict[str, Any] | None=None) -> BeforeStopDecision

fail (method)

BeforeStopDecision.fail(reason: str, *, metadata: dict[str, Any] | None=None) -> BeforeStopDecision

validate_reason (method)

BeforeStopDecision.validate_reason(value: str, info) -> str

copy_message (method)

BeforeStopDecision.copy_message(value: Message | None) -> Message | None

copy_metadata (method)

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

validate_action_payload (method)

BeforeStopDecision.validate_action_payload() -> BeforeStopDecision

Release source · Runtime guarantees · Capability guides

LoopPolicy

from cayu import LoopPolicy

execution_profile_identity (property)

LoopPolicy.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

name (property)

LoopPolicy.name() -> str

adoption_replay_identity (property)

LoopPolicy.adoption_replay_identity() -> str | None

Return stable, versioned identity for explicit profile-adoption replay.

Stateful request policies must override this property when they can be used with ResumeRequest.profile_adoption. The identity must change whenever configuration that can affect policy behavior changes. A missing identity fails that combination closed without affecting ordinary run or resume requests.

before_stop (method)

async LoopPolicy.before_stop(context: BeforeStopContext) -> BeforeStopDecision

Run when the model step has no tool calls and Cayu is about to complete.

Release source · Runtime guarantees · Capability guides

RequireFinalTool

from cayu import RequireFinalTool

Keep a turn going until one of tool_names has returned without error.

Some agents must end every turn through a specific tool, for example a clarification question or a recorded proposal. Models occasionally stop before calling one, sometimes with an empty step. This policy appends a reminder and lets the model continue, up to max_reminders times, and then interrupts (or fails) the session with a reason instead of completing it.

The turn is read from the durable conversation: messages after the latest user message other than this policy’s own durably receipted reminder. Matching reminder text in a real user message still starts a new turn. A tool result counts when its tool_name is listed and is_error is false, so tools should return is_error=True for failures. The policy keeps no state between calls; continuation provenance is checkpointed with each reminder so counts survive restarts and recovery.

Bases: LoopPolicy.

execution_profile_identity (property)

RequireFinalTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity

name (property)

RequireFinalTool.name() -> str

adoption_replay_identity (property)

RequireFinalTool.adoption_replay_identity() -> str

before_stop (method)

async RequireFinalTool.before_stop(context: BeforeStopContext) -> BeforeStopDecision

init (method)

RequireFinalTool.__init__(tool_names: Iterable[str], *, reminder: str | None=None, max_reminders: int=2, on_exhausted: BeforeStopAction=BeforeStopAction.INTERRUPT) -> None

tool_names (property)

RequireFinalTool.tool_names() -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides