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
¶
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
¶
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
¶
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
¶
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
|
|
attend
async
¶
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
¶
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
¶
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
¶
Fail the turns in flight (backend_closed) and release the
transport.
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 ( |
None
|
client
|
Any
|
A |
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
|
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
client without url. |
node_id
instance-attribute
¶
This process's id among the backend's processes.
serve
async
¶
Serve executor, in place of one of its id served before; the executors that closed are let go.
claim_presence
async
¶
Kept in Redis, so of the room owner processes that see the same change, one alone publishes it.
executors
async
¶
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
|
required |
hosts
|
Collection[str] | Callable[[str], bool] | None
|
Which channel ids this executor declares: a collection of
ids and of prefixes ending in |
None
|
organizations
|
Collection[str] | None
|
The organizations whose rooms it serves: exact ids,
which leave out the rooms without an organization, and |
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
|
|
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
|
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 |
()
|
Raises:
| Type | Description |
|---|---|
TypeError
|
An entry of error_classes is not an |
ValueError
|
An entry of hosts holds a |
hosted
property
¶
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
¶
The organizations whose rooms it serves ("*" every one);
None for the rooms without an organization alone (RFC §10.6.7).
use_wiring ¶
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 ¶
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 ¶
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)
hosts_channel ¶
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 ¶
Whether it serves a room of organization_id, None for a room
without an organization (RFC §10.6.7).
reach_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 ¶
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).
close
async
¶
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
¶
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
|
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
|
host
|
OwnerHost | None
|
What the owner runs for its turns' |
None
|
events
|
OwnerEvents | None
|
Where the owner publishes what its turns published on their
executors (RFC §10.6.3), or |
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 |
()
|
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
|
Raises:
| Type | Description |
|---|---|
TypeError
|
An entry of error_classes is not an |
telemetry
instance-attribute
¶
The telemetry whose spans a turn runs under (RFC §10.6.9).
errors
instance-attribute
¶
The classes this owner rebuilds an error as (RFC §10.6.8).
run
async
¶
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 ¶
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 ¶
Stop naming name among room_id's hooks; whether it was.
control
async
¶
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
|
|
room_call
async
¶
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
¶
What a channel published after its turn ended (RFC §10.6.3); none once the client closed.
input_request ¶
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 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 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
¶
How long the owner waits for an executor to take the turn.
heartbeat_interval
class-attribute
instance-attribute
¶
How often each side tells the other it is still there.
heartbeat_timeout
class-attribute
instance-attribute
¶
How long a silence lasts before its side is taken for lost.
cancel
class-attribute
instance-attribute
¶
How long the owner waits for a cancelled turn's end.
input_hold_timeout
class-attribute
instance-attribute
¶
How long the owner holds an answer for a human-input request it does not know yet (RFC §10.6.5).
silent_intervals
property
¶
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.
TurnLink ¶
Bases: ABC
The owner's side of one turn.
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.
ExecutorLink ¶
Bases: ABC
The executor's side of one turn.
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 ¶
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 ¶
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
¶
An agent's identity; None for a channel that is no agent.
thinks_while_listening
class-attribute
instance-attribute
¶
It carries a thinker (RFC §6.4), which a discussion refuses.
takes_owner_tools
class-attribute
instance-attribute
¶
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
¶
How many recent room events the owner loads for its turns.
serializes_room_turns
class-attribute
instance-attribute
¶
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
¶
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 ¶
DeclaredChannel ¶
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
¶
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.
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
¶
Bounded by its own bound, not the channel's default call bound (RFC §21.6).
Reaching the room from a turn¶
TurnHost ¶
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).
reachable
property
¶
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 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 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
¶
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 an entry on the kit's status bus.
update_room_metadata
async
¶
Merge metadata into the room's: the room as stored after.
room_tasks
async
¶
The turn's room's background tasks, as task_status reads them
(RFC §23.4): state of the owner's process.
room_vision
async
¶
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
¶
The turn's room as the owner builds it now, as data (RFC §10.6.6).
call
async
¶
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 ¶
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
¶
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
¶
Run a host verb made after its turn ended: the verb's result, or its refusal as an error record.
room_publication
abstractmethod
async
¶
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.
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
¶
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
¶
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
¶
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
¶
The runtime's own blocks for the turn (a discussion's turn notes).
in_place
class-attribute
instance-attribute
¶
A discussion's turn: the event keeps its place in the history.
owner_tools
class-attribute
instance-attribute
¶
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
¶
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
¶
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
¶
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.
Channel control¶
RoomAttached ¶
Bases: BaseModel
The channel was attached to the room (RFC §10.6.3).
organization_id
class-attribute
instance-attribute
¶
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
¶
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
¶
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
¶
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
¶
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.
Errors¶
TurnLinkError ¶
Bases: RoomKitError
A turn the turn backend could not carry to its end (RFC §10.6.8).
Attributes:
| Name | Type | Description |
|---|---|---|
reason |
|
RemoteTurnError ¶
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, |
bases |
tuple[str, ...]
|
The classes that class derives from below |