yaab.types¶
Core types: Event, EventType, Message, Role, RunContext, RunResult, Usage.
yaab.types ¶
Core shared types: messages, usage, run context, events, and results.
These are deliberately framework-neutral Pydantic models so they serialize cleanly into sessions, checkpoints, and the audit log.
ToolCall ¶
Bases: BaseModel
A model's request to invoke a tool.
Message ¶
Bases: BaseModel
A single conversation message in the canonical OpenAI-ish shape.
to_provider_dict ¶
Render to the dict shape LiteLLM/OpenAI expect.
Usage ¶
Bases: BaseModel
Token and cost accounting for a run, aggregated across model calls.
RunContext ¶
Bases: Generic[Deps]
Typed, dependency-injected context handed to tools and instructions.
Holds the caller-supplied deps (the DI payload), identity, the live
usage counter, and the run's shared state. state is a prefix-scoped
:class:~yaab.state.State — one object per run, shared by every agent,
sub-agent, workflow child, tool, and plugin, so a value written in one place
is read in another by key. Passing context explicitly keeps tools testable
and free of global state.
For backward compatibility state still behaves exactly like a dict
(ctx.state["k"], .get, .setdefault, in, iteration); the only
addition is that temp:/user:/app: prefixed keys route to their
own scope. A bare dict passed in is adopted as the session scope.
readonly ¶
readonly() -> RunContextView
A read-only projection for instruction rendering and routing.
Same deps/identity/usage, but .state is a
:class:~yaab.state.ReadonlyState so rendering and routing predicates
physically cannot mutate shared state.
RunContextView ¶
Bases: Generic[Deps]
A read-only projection of a :class:RunContext.
Exposes the same fields, but state is an immutable
:class:~yaab.state.ReadonlyState. Handed to instruction providers and
routing predicates — the surfaces where a write would be a bug.
Event ¶
Bases: BaseModel
An item in the Runner's typed event stream.
Pending ¶
Bases: BaseModel
One thing a human must decide before a paused run continues.
A paused :class:RunResult carries a list of these (one element for the
common single-approval case, several when one model turn guarded two tools).
One shape covers all three pause kinds: a guarded tool ("approval"), an
:func:~yaab.tools.builtin.ask_user question ("question"), or a graph
interrupt() ("flow_pause"). Every kind carries the same correlation
keys (approval_id/run_id/resume_id) so resume is uniform, with
kind-specific fields left nullable.
RunResult ¶
Bases: BaseModel, Generic[Output]
The result of an agent run.
output is defined and meaningful iff not paused. When a run pauses
for human sign-off (an approval gate, a question, or an explicit step pause)
it returns with paused=True; pause_value carries what the single
blocking human decision is, and pending lists every parked decision when
more than one is outstanding at once (e.g. concurrent branches each awaiting a
reviewer). output is then a placeholder (None for the common case) and
should not be read. Resume the same run to get a final, non-paused result.
Keeping one result type with this documented invariant avoids fragmenting
result shapes or weakening output's type for the common case.