soulfire.tasks.SoulFireTask¶

class soulfire.tasks.SoulFireTask[ResultT: google.protobuf.message.Message](client: soulfire.task_connect.BotTaskServiceClient, snapshot: soulfire.task_pb2.BotTask, result_type: type[ResultT], header_factory: HeaderFactory)[source]¶

A handle for a server task with a typed result.

Obtain a handle from SoulFireTasks start methods. Starting a task waits for server acceptance, not completion. The server’s lifecycle policies control its execution after acceptance.

Use wait() to inspect any terminal status, or result() to require successful completion and decode the result. Observing or interrupting these operations does not itself cancel the task. Call cancel() explicitly, or use a run_* stream or soulfire.SoulFireBot.collect() for ownership.

property id: str¶: Stable task identifier for later lookup, observation, or cancellation.

property snapshot: soulfire.task_pb2.BotTask¶

Last fetched task state, without a network request.

refresh(), wait(), and cancel() update this snapshot. Consuming events() directly does not update it.

property terminal: bool¶

Whether the cached snapshot is completed, cancelled, failed, or timed out.

This property does not fetch current state. Use refresh() for a new snapshot.

refresh(*, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[soulfire.task_pb2.BotTask, soulfire.errors.SoulFireOperationError][source]¶

Fetch current server state and update snapshot.

Returns:: An Effect that produces the latest BotTask. timeout_ms controls RPC timeout in milliseconds; headers adds request metadata.

events(*, after_revision: int | None = None, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → soulfire.streams.Stream[soulfire.task_pb2.BotTaskEvent, soulfire.errors.SoulFireOperationError][source]¶

Observe task revisions until the task ends.

Parameters:

after_revision – Resume after this revision. None uses the cached snapshot’s revision when the stream opens.
headers – Extra request metadata.
timeout_ms – RPC timeout in milliseconds.

Returns:

A lazy Stream of BotTaskEvent values. Direct consumption does not update snapshot. Closing this observer does not cancel the task.

wait(*, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[soulfire.task_pb2.BotTask, soulfire.errors.SoulFireOperationError][source]¶

Wait for the terminal state and update snapshot.

Returns immediately from the cached snapshot if it is already terminal. Otherwise, consumes task events and fetches state if the stream ends before it observes a terminal update.

Returns:: An Effect that produces BotTask for any terminal status, including failure or cancellation. Use result() to require success. timeout_ms controls RPC timeout in milliseconds.

cancel(reason: str = '', *, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[soulfire.task_pb2.BotTask, soulfire.errors.SoulFireOperationError][source]¶

Request task cancellation and update the cached snapshot.

Parameters:

reason – Explanation recorded with the cancellation request.
headers – Extra request metadata; the SDK adds any active control token.
timeout_ms – RPC timeout in milliseconds.

Returns:

An Effect that produces the server’s updated BotTask. Inspect its status when completion can race with cancellation.

result(*, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[ResultT, soulfire.errors.SoulFireOperationError][source]¶

Wait for successful completion and decode the typed task result.

A failed, cancelled, or timed-out task fails with SoulFireTaskError in the Effect error channel. A missing or incompatible result also fails. The error retains the task snapshot for status and failure inspection. Interrupting this wait does not itself cancel the server task.

Returns:: An Effect that produces the result type selected by the start method. timeout_ms controls RPC timeout in milliseconds.