Conversation-scoped GenServer for running a Spectre agent under supervision.
The session keeps the latest %Spectre.State{} in process memory and delegates
each turn to Spectre.ask/3. Applications that prefer durable state can
use a state MyApp.Store adapter in the agent DSL; sessions restore from that
adapter on start when no explicit state is supplied.
Summary
Functions
Returns the Agent module owned by a supervised session.
Handles one turn through a supervised session.
Returns a child spec for a supervised session.
Executes the session's current pending effect and commits its terminal state.
Replaces the current in-memory state.
Resolves the session's currently open policy from a trusted host decision.
Starts a conversation-scoped session process.
Returns the current in-memory Spectre state.
Handles one turn through a supervised session and returns a %Spectre.Turn{}.
Types
@type option() :: {:agent, module()} | {:state, Spectre.State.t() | map() | keyword()} | {:opts, keyword()} | {:name, GenServer.name()} | {:conversation_id, term()} | {:idle, timeout() | false | nil} | {:shutdown, timeout() | false | nil}
Functions
@spec agent(GenServer.server()) :: module()
Returns the Agent module owned by a supervised session.
@spec ask(GenServer.server(), Spectre.Input.t() | String.t() | map(), keyword()) :: {:ok, Spectre.Result.t()} | {:error, term()}
Handles one turn through a supervised session.
{:ok, result} = Spectre.Session.ask(session, "hello")@spec child_spec(keyword()) :: Supervisor.child_spec()
Returns a child spec for a supervised session.
children = [
{Spectre.Session,
agent: MyApp.Agents.ProjectAgent,
name: MyApp.ProjectAgentSession,
shutdown: :timer.minutes(10)}
]@spec execute(GenServer.server(), Spectre.Result.t(), keyword()) :: {:ok, Spectre.Result.t()} | {:error, term()}
Executes the session's current pending effect and commits its terminal state.
The state embedded in the supplied result is treated as a reference only; the Session's current state remains authoritative.
@spec reset(GenServer.server(), Spectre.State.t() | map() | keyword()) :: :ok | {:error, :instance_busy}
Replaces the current in-memory state.
:ok = Spectre.Session.reset(session, %Spectre.State{})@spec resolve_policy( GenServer.server(), Spectre.Result.t(), Spectre.Policy.resolution(), keyword() ) :: {:ok, Spectre.Result.t()} | {:error, term()}
Resolves the session's currently open policy from a trusted host decision.
The session uses its current state rather than trusting a potentially stale state embedded in the supplied result.
@spec start_link([option()]) :: GenServer.on_start()
Starts a conversation-scoped session process.
{:ok, pid} = Spectre.Session.start_link(agent: MyApp.Agent)@spec state(GenServer.server()) :: Spectre.State.t()
Returns the current in-memory Spectre state.
%Spectre.State{} = Spectre.Session.state(session)@spec turn(GenServer.server(), Spectre.Input.t() | String.t() | map(), keyword()) :: {:ok, Spectre.Turn.t()} | {:error, term()}
Handles one turn through a supervised session and returns a %Spectre.Turn{}.