ExAgent.Session.TurnPolicy behaviour (ExAgent v0.4.0)

Copy Markdown View Source

Decides the order in which session participants take turns.

A turn policy is a small, stateful module that sequences participants. The ExAgent.Session owns no scheduling logic of its own — it delegates "who acts next" and "may this participant act now" to the policy, so the same Session can drive a round-robin chat, an initiative-ordered combat, or a supervisor that delegates (Phase 4).

Callbacks

  • init/1 — build the policy state from options. opts carries
                        `:participants` (the initial list) plus any
                    policy-specific keys (e.g. `:order` for initiative).
  • next_participant/2 — return {:ok, id, new_state} for the next actor,
                        or `{:done, new_state}` when the sequence is
                    exhausted. `context` carries `%{shared_state: _, participants: _}`
                    for policies that need it.
  • can_act?/3 — whether participant_id may act right now (the
                        policy tracks the current actor).
  • participant_joined/2 / participant_left/2 — keep the policy's roster in
                        sync as participants come and go.

Built-in implementations

Summary

Types

context()
id()
state()

Callbacks

can_act?(state, participant_id, context)
init(opts)
next_participant(state, context)
participant_joined(state, t)
participant_left(state, id)

Functions

can_act?(state, id, ctx)
init(mod, opts)
next_participant(state, ctx)
participant_joined(state, participant)
participant_left(state, id)

Types

context()

@type context() :: %{
  shared_state: term(),
  participants: [ExAgent.Session.Participant.t()]
}

id()

@type id() :: term()

state()

@type state() :: term()

Callbacks

can_act?(state, participant_id, context)

@callback can_act?(state(), participant_id :: id(), context()) :: boolean()

init(opts)

@callback init(opts :: keyword()) :: state()

next_participant(state, context)

@callback next_participant(state(), context()) :: {:ok, id(), state()} | {:done, state()}

participant_joined(state, t)

(optional) 
@callback participant_joined(state(), ExAgent.Session.Participant.t()) :: state()

participant_left(state, id)

(optional) 
@callback participant_left(state(), id()) :: state()

Functions

can_act?(state, id, ctx)

@spec can_act?(state(), id(), context()) :: boolean()

init(mod, opts)

@spec init(
  module(),
  keyword()
) :: state()

next_participant(state, ctx)

@spec next_participant(state(), context()) :: {:ok, id(), state()} | {:done, state()}

participant_joined(state, participant)

@spec participant_joined(state(), ExAgent.Session.Participant.t()) :: state()

participant_left(state, id)

@spec participant_left(state(), id()) :: state()