Skip to content

Turn Execution

Every turn of an intelligence channel runs through a turn backend (RFC §10.6).

Backend and Executor

TurnBackend

Bases: ABC

Carries turns between room owners and executors (RFC §10.6).

timeouts class-attribute instance-attribute

timeouts = None

The bounds every side of its turns keeps, when the backend sets them: its processes must agree on them (RFC §10.6.8).

submit abstractmethod async

submit(request)

Start a turn: an executor that declares its channel takes it. The backend marks request handed (request.hand_over()) as it gives it to an executor, before any wait on the executor's answer.

serve abstractmethod async

serve(executor)

Have executor take the turns of the channels it declares, from now until the backend closes or the executor does. A backend that carries work after a turn gives it a port to the owner (executor.reach_owner, RFC §10.6.3).

control abstractmethod async

control(message)

Carry a channel control message (RFC §10.6.3): room_attached and room_detached to the executors that may run the channel's turns (the owner's own alone for a channel it hosts, else every executor that declares the channel), answered by none; a committed_event to the executor that holds the room's state for the channel, else one that would take the room's turns, never moving the holder, answered by none; a channel_call to the executor that holds the room's state for the channel, else one that declares it, answered by its result, marked handed (message.hand_over()) as the backend gives it to that executor.

Raises:

Type Description
TurnLinkError

no_executor for a channel_call or a committed_event no executor takes.

attend async

attend(owner)

Have what executors send outside a turn reach owner (RFC §10.6.3), and place the turns of the channels its own executor (owner.executor) hosts on that executor alone, closed or not (RFC §10.6.7). Default: nothing reaches an owner outside a turn, and an executor's verbs made after their turn are refused.

claim_presence async

claim_presence(channel_id, room_id, online)

Record that channel_id is now online (or not) in room_id: True when it is a change, for the one caller that then publishes it there, False when it was already so (RFC §10.6.7). None forgets it, the channel detached from the room: its next attach there is a change. Default: kept in this process, which fits one room owner process. A backend shared by several keeps it where they all read it.

executors async

executors()

The executors this backend carries turns to, the owner's own executor aside, with what each declares and whether it is online (RFC §10.6.7, §10.6.8); a closed one is not listed. Default: none known, so the kit reads every agent it holds by its declaration alone as offline.

close abstractmethod async

close()

Fail the turns in flight (backend_closed) and release the transport.

InMemoryTurnBackend

InMemoryTurnBackend()

Bases: TurnBackend

Turns carried in this process, serialized like any other but a request's events (:class:CarriedRequest, RFC §10.6).

The turns of a channel the owner's own executor hosts go to it alone, and fail no_executor once it closed. Another channel's turns in a room go to the executor that took its last turn or channel call while it serves and declares the channel, else to the first that declares it; only to one serving the room's organization (RFC §10.6.7). Every executor is in this process, so a turn none declares fails at once with no_executor.

RedisTurnBackend

RedisTurnBackend(url=None, *, client=None, key_prefix='roomkit:turns', timeouts=None, _loop_back=False)

Bases: TurnBackend

Turns carried between processes by Redis (RFC §10.6).

One backend per process, given to the kit (RoomKit(turn_backend=...)) and to the executors that process serves (await backend.serve(executor)). An executor whose channels are given as a collection (TurnExecutor(build, hosts={"meteo"})) takes turns from every process; one given a predicate, as the kit's own, from its process only.

Parameters:

Name Type Description Default
url str | None

The Redis server (redis://localhost:6379 by default). With client, still required: the process's beat thread connects with it.

None
client Any

A redis.asyncio client to use for the backend's writes and reads instead of connecting; its calls keep its own timeouts.

None
key_prefix str

The prefix of every key the backend writes.

'roomkit:turns'
timeouts TurnTimeouts | None

The heartbeat bounds (RFC §10.6.8), kept by the kit given this backend: give every process, and every executor's TurnExecutor(timeouts=...), the same.

None

Raises:

Type Description
ValueError

client without url.

node_id instance-attribute

node_id = uuid4().hex[:12]

This process's id among the backend's processes.

serve async

serve(executor)

Serve executor, in place of one of its id served before; the executors that closed are let go.

claim_presence async

claim_presence(channel_id, room_id, online)

Kept in Redis, so of the room owner processes that see the same change, one alone publishes it.

executors async

executors()

This process's executors as they stand, and the other processes' as their beats tell: online while beating within the heartbeat timeout, listed while their process has not withdrawn them.

TurnExecutor

TurnExecutor(build_channel, *, hosts=None, organizations=None, executor_id=None, timeouts=None, media_resolver=None, attached_media=None, telemetry=None, owns_channels=True, error_classes=(), max_channels=None)

Runs the turns of the channels it declares (RFC §10.6).

Parameters:

Name Type Description Default
build_channel ChannelFactory

The host's factory: the channel for a channel id, or None when it has none; sync or async. The executor builds each channel when a turn, a channel call or a committed event first needs it, wires it (RFC §10.6.2) and closes it when it closes.

required
hosts Collection[str] | Callable[[str], bool] | None

Which channel ids this executor declares: a collection of ids and of prefixes ending in * ("org-*"; "*" for every id), or a predicate; every id when omitted. Only a collection is told to the room owners of other processes: a predicate, or no hosts, takes the turns of its own process alone (RFC §10.6.7).

None
organizations Collection[str] | None

The organizations whose rooms it serves: exact ids, which leave out the rooms without an organization, and "*" for every organization and the rooms without one. Omitted, it serves the rooms without an organization alone (RFC §10.6.7, §17.2). A room's turn, channel call or committed event goes only to an executor serving the room's organization, and an executor refuses one of another.

None
executor_id str | None

The id the executor answers with; a random one when omitted.

None
timeouts TurnTimeouts | None

The heartbeat bounds it keeps.

None
media_resolver MediaResolver | None

The host's media resolver, given to its AI channels as the kit gives the ones it registers (RFC §6.4).

None
attached_media AttachedMedia | None

The host's attached-media reader (RFC §6.4).

None
telemetry TelemetryProvider | None

The telemetry its hooks and channels report to.

None
owns_channels bool

False when build_channel reads a registry whose owner wires and closes its channels (the kit's own executor).

True
max_channels int | None

How many built channels it keeps at most; no bound when omitted. Past it, the one used least recently that nothing runs on (a turn, a channel call, a committed event, a room's attach or detach) is let go as kit.release_channel lets it go: what it held for its rooms and the room does not keep (an ACP session) goes, and its next turn builds it anew (RFC §10.6.2). Unused with owns_channels=False.

None
error_classes Iterable[type[Exception]]

The host's exception classes an error raised on the room owner is rebuilt as here, with their subclasses, beyond RoomKit's and Python's built-in ones (RFC §10.6.8). Any other comes back as a RemoteTurnError.

()

Raises:

Type Description
TypeError

An entry of error_classes is not an Exception class, or organizations is one id given as a string or holds an entry that is not a string.

ValueError

An entry of hosts holds a * elsewhere than at its end, organizations is empty or holds a * in an id, or max_channels is below 1.

hooks property

hooks

The hooks of the triggers a turn fires (RFC §10.6.6).

wiring property

wiring

What the executor gives the channels it runs (RFC §10.6.2).

hosted property

hosted

The channel ids and prefixes it declares when they were given as a collection; None for a predicate or every id (RFC §10.6.7).

organizations property

organizations

The organizations whose rooms it serves ("*" every one); None for the rooms without an organization alone (RFC §10.6.7).

timeouts property

timeouts

The heartbeat bounds its turns keep (RFC §10.6.8).

closed property

closed

Whether the executor closed: it takes no more turns.

use_wiring

use_wiring(env)

Wire channels from env in place of what the executor was given: what the kit gives its own executor, before any channel is wired.

wire

wire(channel)

Give channel what its turns fire this executor's hooks through: the kit's own executor wires each channel the kit registers, another each channel its factory builds.

hook

hook(trigger, execution=SYNC, priority=0, name='', timeout=30.0, channel_types=None, channel_ids=None, directions=None, event_types=None, fail_closed=False)

Decorator to register a hook on a trigger a turn fires (ON_TOOL_CALL, BEFORE_TOOL_USE, ON_AI_RESPONSE...), with RoomKit.hook's options. An owner's trigger raises ValueError.

The kit's own executor (kit.turn_executor) fires these hooks for the turns it runs and for the tool calls the kit's process serves (realtime voice, conference). An executor a host builds runs its turns without them for now: the kit wires the channels it registers, and an executor that wires its own comes with the distributed backends.

room_hook

room_hook(name, trigger, execution=SYNC, priority=0, timeout=30.0, *, fail_closed=False)

Decorator to define a room hook named name on a trigger a turn fires (RFC §10.6.6): it runs for a room whose owner enabled the name (kit.enable_room_hook(room_id, name)), the turn's request naming it. Every executor that may run the room's turns defines it; one that does not is never given them. A name may carry a hook per trigger: defining it again on a trigger it carries replaces the first.

executor.room_hook("audit", HookTrigger.ON_TOOL_CALL)(fn)

remove_room_hook

remove_room_hook(name)

Forget the room hooks defined under name.

declares

declares(channel_id)

Whether this executor takes the turns of channel_id.

hosts_channel

hosts_channel(channel_id)

Whether channel_id is among the channels this executor was given (hosts=), whether or not it is closed. A backend reads it of the owner's own executor, whose live channels' turns no other executor takes, even once it closed (RFC §10.6.7).

serves

serves(organization_id)

Whether it serves a room of organization_id, None for a room without an organization (RFC §10.6.7).

reach_owner

reach_owner(owner)

Reach the room owner outside a turn through owner, which a backend gives the executors it serves (RFC §10.6.3): work a turn began sends its host verbs and publications there once the turn ended.

takes

takes(channel_id, room_hooks=(), organization_id=None)

Whether this executor takes a turn of channel_id whose room has the hooks named room_hooks, in organization_id (None: a room without an organization) (RFC §10.6.7).

take

take(link)

Start the turn link brought; it runs on its own task.

close async

close()

Take no more turns, and cut the ones running, but the turns this close runs under: waiting for them would wait for itself.

control async

control(message)

Apply a channel control message of the owner's (RFC §10.6.3): a channel_call's result; nothing for room_attached, room_detached, committed_event and channel_released. A room's attach or detach builds nothing: an executor holding no build of the channel has nothing to apply.

TurnClient

TurnClient(backend, *, executor=None, timeouts=None, tools=None, host=None, events=None, error_classes=(), telemetry=None)

Bases: RoomOwner

Runs turns through a backend and reads them back (RFC §10.6).

Parameters:

Name Type Description Default
backend TurnBackend

The turn backend.

required
executor TurnExecutor | None

An executor this client serves on the backend before its first turn (the kit's own), or None. It runs the channels it hosts only in the rooms it serves (RFC §10.6.7): the kit gives its own organizations={"*"}, and an owner serving rooms of several organizations gives it the same.

None
timeouts TurnTimeouts | None

The bounds the owner keeps.

None
tools OwnerTools | None

The tools the owner serves its turns (RFC §10.6.5), or None.

None
host OwnerHost | None

What the owner runs for its turns' TurnHost (RFC §10.6.5), or None.

None
events OwnerEvents | None

Where the owner publishes what its turns published on their executors (RFC §10.6.3), or None.

None
error_classes Iterable[type[Exception]]

The host's exception classes an error raised on an executor is rebuilt as here, with their subclasses, beyond RoomKit's and Python's built-in ones (RFC §10.6.8). Any other comes back as a RemoteTurnError.

()
telemetry TelemetryProvider | None

The telemetry whose spans a turn runs under, named in its request for an executor elsewhere to continue the trace (RFC §10.6.9), or None.

None

Raises:

Type Description
TypeError

An entry of error_classes is not an Exception class.

telemetry instance-attribute

telemetry = telemetry

The telemetry whose spans a turn runs under (RFC §10.6.9).

errors instance-attribute

errors = ErrorClasses(error_classes)

The classes this owner rebuilds an error as (RFC §10.6.8).

run async

run(event, binding, context, *, strategy_turn=False)

Run one turn of binding's channel on event: its output, its stream reading the executor's (RFC §10.6.4); a strategy's generation when strategy_turn (RFC §10.6.1).

enable_room_hook

enable_room_hook(room_id, name)

Name name among room_id's hooks on executor triggers: its turns' requests carry it, and only an executor that defines it takes them (RFC §10.6.6, §10.6.7). Synchronous and trusted, reading no room: :meth:RoomKit.enable_room_hook reads the room with the caller's organization first (RFC §17.2), as :meth:RoomKit.disable_room_hook does before :meth:disable_room_hook.

disable_room_hook

disable_room_hook(room_id, name)

Stop naming name among room_id's hooks; whether it was.

room_hook_names

room_hook_names(room_id)

The names of room_id's hooks on executor triggers.

control async

control(message)

Send a channel control message (RFC §10.6.3): a channel_call's result; nothing for room_attached, room_detached, committed_event and channel_released. After a room_detached, the room's next turn of the channel names no previous turn, so an executor that missed the message still drops the room's state (RFC §10.6.3). A committed_event goes where the room's turns would, the room's hooks named.

Raises:

Type Description
TurnLinkError

no_executor for a channel_call or a committed_event no executor takes.

room_call async

room_call(message)

A host verb an executor made after its turn ended (RFC §10.6.5), work that starts fresh once its turn is over (RFC §8.3); refused once the client closed, and cancelled by its close.

room_publication async

room_publication(message)

What a channel published after its turn ended (RFC §10.6.3); none once the client closed.

input_request

input_request(request_id, *, organization_id=None)

The open human-input request request_id of a turn this client started (RFC §10.6.5), as ON_USER_INPUT_REQUIRED reads it: its room, channel, tool call and the actor of its turn. None when no turn of this client holds it open, or, with organization_id, when its room is another organization's (RFC §17.2).

steer async

steer(room_id, channel_id, directive, *, turn_id=None, organization_id=None)

Steer the running turns of channel_id in room_id this client started (RFC §21.3, §10.6.8): the room's turn turn_id alone when given, else all of the room's turns for a Cancel and its most recent for any other directive; never a turn of another room. How many loops it reached. With organization_id, only the turns of that organization's rooms (RFC §17.2).

close async

close()

Close the own executor, which cuts its turns, stop holding every turn still open (a stream nobody read), wait for the calls its turns made to end (but the one running this close), then close the backend. Work of a turn that reaches it after this is refused.

TurnTimeouts dataclass

TurnTimeouts(accept=10.0, heartbeat_interval=2.0, heartbeat_timeout=10.0, cancel=5.0, input_hold_timeout=60.0)

The bounds both sides of a turn keep (RFC §10.6.8), in seconds.

accept class-attribute instance-attribute

accept = 10.0

How long the owner waits for an executor to take the turn.

heartbeat_interval class-attribute instance-attribute

heartbeat_interval = 2.0

How often each side tells the other it is still there.

heartbeat_timeout class-attribute instance-attribute

heartbeat_timeout = 10.0

How long a silence lasts before its side is taken for lost.

cancel class-attribute instance-attribute

cancel = 5.0

How long the owner waits for a cancelled turn's end.

input_hold_timeout class-attribute instance-attribute

input_hold_timeout = 60.0

How long the owner holds an answer for a human-input request it does not know yet (RFC §10.6.5).

silent_intervals property

silent_intervals

How many intervals in a row with no message make a side lost: counted per interval, so a stall of the counting side's own loop counts once.

Bases: ABC

The owner's side of one turn.

taken abstractmethod property

taken

Whether an executor took the request.

receive abstractmethod async

receive()

The next frame and its sequence number.

send abstractmethod async

send(message)

Send a control message to the executor.

release abstractmethod

release()

Forget the turn: later frames are dropped.

beat_heard

beat_heard()

Whether the executor that took the turn beat since this was last asked, outside the turn's messages: an executor in a process of its own beats from a thread its turn's work cannot stall (RFC §10.6.8). Default: it beats by messages alone.

Bases: ABC

The executor's side of one turn.

receive abstractmethod async

receive()

The next control message from the owner.

send abstractmethod async

send(frame)

Send a frame to the owner; its sequence number.

turn_context

turn_context()

The execution context the turn's work runs in: a fresh one, unless the backend shares the owner's process (RFC §10.6.5).

turn_ended

turn_ended()

Called by the executor once the turn's task ended, however it ended (its end sent or not): the link lets go of the turn. Default: nothing to let go of.

stream_context

stream_context()

The execution context the turn's stream advances in, once known; None means a fresh one, kept for the stream's life.

Channels held by their declaration

ChannelDeclaration

Bases: BaseModel

What the room's owner knows of a channel without its live object (RFC §10.6.2): enough to bind it, plan its turns and read it in a strategy. An executor builds the channel itself.

A field left out reads as an AI channel built with its defaults: channel.declaration() gives a live channel's own.

identity class-attribute instance-attribute

identity = None

An agent's identity; None for a channel that is no agent.

thinks_while_listening class-attribute instance-attribute

thinks_while_listening = False

It carries a thinker (RFC §6.4), which a discussion refuses.

takes_owner_tools class-attribute instance-attribute

takes_owner_tools = True

Its turns declare the tools its owner serves (RFC §10.6.5): an AI channel's do, an external agent's over ACP do not.

recent_events_window class-attribute instance-attribute

recent_events_window = Field(default=AI_CHANNEL_CONTEXT_EVENTS, ge=0)

How many recent room events the owner loads for its turns.

serializes_room_turns class-attribute instance-attribute

serializes_room_turns = False

Its turns in a room run one after the other, in the order they were asked, which the room's owner keeps (RFC §6.4).

steers_room_turns class-attribute instance-attribute

steers_room_turns = False

A message for a room where its turn runs is handed to that turn, read at its next stop, rather than waiting a turn of its own (RFC §6.4, §21.3). It implies serializes_room_turns.

AgentIdentity

Bases: BaseModel

What the room's owner reads of an agent (RFC §10.6.2, §19.1).

purpose class-attribute instance-attribute

purpose = None

What a supervisor's roster says of it as a worker (RFC §19.7.3).

voice class-attribute instance-attribute

voice = None

Its TTS voice (RFC §19.1).

auto_greet class-attribute instance-attribute

auto_greet = True

Whether the owner sends :attr:greeting when a session starts.

DeclaredChannel

DeclaredChannel(declaration)

Bases: Channel

An intelligence channel the kit knows by its declaration, with no object of it in this process.

The kit finds it wherever it looks a channel up: a binding takes its capabilities, routing plans its turns, a delegation names it. Its turns run on an executor whose host builds the channel; the kit's own executor never builds it, so with no such executor they fail with no_executor. Nothing here runs it: a message, a delivery or a turn handed to it is refused.

Raises:

Type Description
ValueError

declaration is not an intelligence channel's.

is_config_only property

is_config_only

Never: an executor builds it with its provider (RFC §19.1).

Owner-served tools

OwnerTools

Bases: ABC

The tools a room owner serves its turns (RFC §10.6.5): what it lists in a turn's request, and how it runs a call's handler.

declared abstractmethod

declared(channel_id, room_id)

The tools the owner serves channel_id's turns in room_id.

serve abstractmethod async

serve(request, call)

Run call's handler, under the call's context already installed: its answer. Raises what the handler raises, and UnservedToolCallError when nothing serves the call.

OwnerTool

Bases: BaseModel

A tool the room owner serves a turn, as the request lists it (RFC §10.6.5).

waits_by_design class-attribute instance-attribute

waits_by_design = False

Bounded by its own bound, not the channel's default call bound (RFC §21.6).

Reaching the room from a turn

TurnHost

TurnHost(call, *, between_turns=None, errors=ROOMKIT_ERRORS)

What a host's tool or hook on a turn's executor may ask of the room owner, each verb one call across the turn backend (RFC §10.6.5).

open property

open

Whether the turn it serves still runs.

reachable property

reachable

Whether a verb can still reach the owner: during the turn, or after it for the verbs :data:BETWEEN_TURNS names.

send_event async

send_event(room_id, channel_id, content, **options)

Send an event into a room, as RoomKit.send_event does: the same options, each a value the backend carries. The event is at least as deep as this context's floor, as the kit's own is: the body of an ASYNC hook on the executor sends at its trigger's depth after the turn too, which the owner no longer floors (RFC §8.3).

delegate async

delegate(room_id, agent_id, task, **options)

Delegate task to agent_id from room_id, in the background, as RoomKit.delegate does: the task's id, which :meth:wait_task waits.

wait_task async

wait_task(task_id, timeout=None)

The result of a task a host of this room delegated, once it ends, its failure kept (exception, RFC §23.3); None when timeout passes first, or for a task the room's hosts did not delegate.

post_status async

post_status(agent_id, action, status, *, detail='', metadata=None)

Post an entry on the kit's status bus.

update_room_metadata async

update_room_metadata(room_id, metadata, *, organization_id=None)

Merge metadata into the room's: the room as stored after.

add_observation async

add_observation(observation)

Store observation for its room.

room_tasks async

room_tasks()

The turn's room's background tasks, as task_status reads them (RFC §23.4): state of the owner's process.

room_vision async

room_vision()

What the turn's room's video last showed, as a turn's note (RFC §12.8.7); None when no camera of the room has a result.

room_context async

room_context()

The turn's room as the owner builds it now, as data (RFC §10.6.6).

call async

call(verb, arguments=None)

Run verb, one the host declared on the room owner (RoomKit.declare_host_verb), with arguments: its result, as data. The owner runs it under what this turn gave the call (its room, its actor, its chain depth) and refuses a verb it does not serve. After the turn, work it began still sends it, for the turn's room, and the owner serves it only when it was declared between_turns.

Raises:

Type Description
ValueError

verb is one of RoomKit's own, which its method sends, or the owner refused it.

RuntimeError

the turn ended and the backend reaches no owner then.

current_turn_host

current_turn_host()

The host of the turn the current code runs in (RFC §10.6.5): inside a call of a host tool during a turn and inside a hook its executor fires during it; after the turn ended, in work it began (a background thinker), for the verbs :data:BETWEEN_TURNS names, where the backend reaches the owner outside a turn. None anywhere else, in a tool the room owner serves included.

RoomOwner

Bases: ABC

What reaches a room owner outside a turn (RFC §10.6.3): the owner implements it, and an executor holds one its backend gave it.

executor class-attribute instance-attribute

executor = None

The owner's own executor, the one that runs the channels it holds live (the kit's), or None: a backend the owner attends places the turns of the channels it hosts (hosts_channel) on it alone, never on another executor, and once it closed fails them no_executor (RFC §10.6.7).

room_call abstractmethod async

room_call(message)

Run a host verb made after its turn ended: the verb's result, or its refusal as an error record.

room_publication abstractmethod async

room_publication(message)

Publish what a channel published after its turn ended.

RoomCall

Bases: BaseModel

A verb of a turn's host made after its turn ended (RFC §10.6.3, §10.6.5), answered by a :class:HostResult: the turn it belongs to names the room. The work starts fresh once its turn is over (RFC §8.3): what it sends is at the depth its arguments name.

turn_id instance-attribute

turn_id

The turn the work making the call began in.

chain_depth class-attribute instance-attribute

chain_depth = 0

Read by no owner: kept so that an executor sending it is still understood. What the call sends is at the depth its arguments name.

RoomPublication

Bases: BaseModel

A realtime publication or a framework event made after its turn ended (RFC §10.6.3), answered by nothing.

CommittedEvent

Bases: BaseModel

An event committed in the room that the channel's memory is handed (a discussion's, RFC §19.7.5 rule 3), answered by nothing (RFC §10.6.3).

organization_id class-attribute instance-attribute

organization_id = None

The room's organization (RFC §17.2): it goes only to an executor serving it (RFC §10.6.7).

room_hooks class-attribute instance-attribute

room_hooks = Field(default_factory=list)

The room's hooks on executor triggers, as a turn's request names them: the event goes to an executor that would take the room's turns.

Messages

TurnRequest

Bases: _HandedOver

What the owner sends an executor to start one turn.

strategy_turn class-attribute instance-attribute

strategy_turn = False

A generation a strategy's runner asks: the channel answers, past its speak policy and its thinker (RFC §10.6.1).

notes class-attribute instance-attribute

notes = Field(default_factory=list)

The runtime's own blocks for the turn (a discussion's turn notes).

in_place class-attribute instance-attribute

in_place = False

A discussion's turn: the event keeps its place in the history.

owner_tools class-attribute instance-attribute

owner_tools = Field(default_factory=list)

The tools the owner serves for the channel in the room: the channel declares them to its model, and a call to one is a tool_call.

room_hooks class-attribute instance-attribute

room_hooks = Field(default_factory=list)

The names of the room's hooks on the triggers the turn fires (RFC §10.6.6): the executor runs those it defines under them.

previous_turn class-attribute instance-attribute

previous_turn = None

The room's previous turn of the channel; None for its first, or its first since the channel was detached from the room. An executor holding the room's state for the channel that this turn did not leave drops it before the turn runs (RFC §10.6.2).

channel_rows class-attribute instance-attribute

channel_rows = Field(default_factory=list)

The channel's own rows of the room its turn reads (its tool calls, the instructions it read), each once, oldest first: the owner holds the store (RFC §10.6.3). Empty for a turn the owner's own executor runs.

PreviousTurn

Bases: BaseModel

The room's previous turn of the channel, the one the owner submitted last, ended or not (RFC §10.6.2); or its last channel call, which leaves the room's state as a turn does.

turn_id instance-attribute

turn_id

The turn's id, or the channel call's.

executor_id class-attribute instance-attribute

executor_id = None

The executor that took it; None when none had said so yet.

Channel control

RoomAttached

Bases: BaseModel

The channel was attached to the room (RFC §10.6.3).

organization_id class-attribute instance-attribute

organization_id = None

The room's organization (RFC §17.2): it goes only to an executor serving it (RFC §10.6.7).

RoomDetached

Bases: BaseModel

The channel was detached from the room: its state for the room is dropped (RFC §10.6.3).

organization_id class-attribute instance-attribute

organization_id = None

The room's organization (RFC §17.2): it goes only to an executor serving it (RFC §10.6.7).

ChannelCall

Bases: _HandedOver

A per-room verb of the channel (an ACP session's set_config_option), answered by a :class:ChannelResult (RFC §10.6.3).

organization_id class-attribute instance-attribute

organization_id = None

The room's organization (RFC §17.2): the call goes only to an executor serving it (RFC §10.6.7).

room_state class-attribute instance-attribute

room_state = Field(default_factory=dict)

What the room keeps for the channel, as the owner stores it: the channel takes it back when it holds none for the room.

previous_turn class-attribute instance-attribute

previous_turn = None

The room's previous turn or call of the channel: the executor drops a state it did not leave before the verb runs, as before a turn.

ChannelResult

Bases: BaseModel

The executor's answer to one channel_call: the verb's result as data, or what it raised.

executor_id class-attribute instance-attribute

executor_id = None

The executor that ran the verb.

room_state class-attribute instance-attribute

room_state = None

What the room keeps for the channel once the verb ran, when it changed (empty: nothing); None when it did not.

Errors

TurnLinkError

TurnLinkError(reason, message=None)

Bases: RoomKitError

A turn the turn backend could not carry to its end (RFC §10.6.8).

Attributes:

Name Type Description
reason

no_executor (no executor that hosts the channel took the turn), executor_lost (the executor fell silent), frame_lost (the link lost a message), frame_invalid (a message could not be read) or backend_closed (a turn backend closed: the owner's with the turn in flight, or the one a request was handed to; its executor is not lost).

RemoteTurnError

RemoteTurnError(message, *, kind, bases=())

Bases: RoomKitError

An error raised across the turn backend (by a turn on its executor, by a handler the room owner serves) of a class the side reading it does not rebuild (RFC §10.6.8): RoomKit's and Python's built-in ones are rebuilt by type, with the classes the host declared (error_classes); any other comes back as this one. It keeps the class it had, the attributes JSON carried, and is also an instance of the nearest ancestor of that class the side rebuilds: a host's ProviderError subclass still reads as a ProviderError.

Attributes:

Name Type Description
kind str

The class the error had, module:qualname.

bases tuple[str, ...]

The classes that class derives from below Exception, nearest first, each module:qualname.

__str__

__str__()

The message it was raised with, whichever ancestor it also reads as.