soev_agents.domain

A thread's whole record: every event of every stream, in tree order.

A trace is a value: it holds events and has no identity of its own. A step, a router and a context builder each get a view of the thread as a Trace, never the thread itself. The query methods select events and apply no rule.

from soev_agents.domain import ModelOutput, ToolCall, Trace


def tool_calls(view: Trace) -> tuple[ToolCall, ...]:
    output = view.latest(ModelOutput)
    if output is not None and output.calls_tools:
        return output.tool_calls
    return ()

Make a trace of events.

The name of a stream, which gives the place of the stream in the tree of streams of the thread.

Each thread starts with one stream, root. A branch that a fan-out starts at the node search, after event 3 of the root, is root/search@3. A subagent's stream carries its index after #, as in root/research#0@7.

One recorded fact. Subclasses add their payload fields.

An event never changes. A step creates it with its payload fields only. The runner stamps stream, origin and version, and the store stamps seq and ts when it appends the event. Validation fails for an event with only one of seq and ts.

For an event type of your own, subclass Event with a type field whose default is the tag. Then add the class to the event_types of the agent whose threads record it.

from typing import Literal

from soev_agents.domain import Actor, Event


class Escalated(Event):
    type: Literal["escalated"] = "escalated"
    actor: Actor = "system"
    reason: str

Which kind of party produced an event: user, model, tool or system.

user is the party outside the system, whoever it is. The framework sets user on each Input and Cancelled that a caller produces. The runtime records actor but does not read it to decide anything.

The name of a node, unique in its graph. An event carries the name of the node that produced it.

Return the type tag of an event class or an element class.

The tag is the default of the class's type field. A store keeps an event or an element under its tag. To read it back, the framework looks the class up by the tag.

Raises:

• TypeError: The class has no type field with a string default.

The thread's first event: which registered agent runs it.

Something that arrives from outside: a user message, a task spec, an approval decision.

It starts or continues a thread. Its elements are recorded when it is accepted, so numbering reads the thread alone.

A fresh input opens a turn. An input that responds to a Request continues the turn that the request was made in. Subclass it for a typed input of your own, with a type of its own.

The agent halted because it needs input from outside.

A thread whose last event is a Request is waiting.

The Input that responds to a request is its response. The response continues the turn at the edge of the node that asked. A request has no default actor: the model for a clarification, system for a gate.

The runner stopped because the agent's graph had no work left in the turn.

Recorded because only the graph that ran the turn knows where its work ends, and that graph is not kept.

The turn was ended from outside the run.

A step raised instead of returning: no result exists for the node named in origin.

The run halted there. An error the agent can react to (a tool 404, an empty retrieval) is not a Failure: it is recorded as data on its own event type.

The turn made more model calls that call tools than its budget allows.

The tool calls of the last model output did not run, and the runtime told the model to give its final answer. The event records no setting of the budget.

One model output: the text, the tool calls it asks for, its reasoning, why it stopped and what it cost.

Whether it is a message or a tool call is read off tool_calls. A model step records it with the citation markers out of content and real ids in its tool calls. markers and each call's translated give back what the model wrote.

Why a model stopped, as the model adapter reports it.

stop is the end of the output, length a token limit, tool_calls a stop to call tools, and content_filter a stop by the provider's filter.

Token counts for one model call.

One tool call that the model asked for, with real ids for its element numbers and result handles.

Put each translated value back to get the call as the model wrote it.

One argument value that the model wrote as an element number or a result handle.

The call's arguments hold the real id or the call id that the value named instead.

The result of one tool call, linked to the call by call_id.

Each result has a result handle. The base is never recorded itself: ToolOutput carries what a tool returned, and Reopened names what is shown again.

The result of one tool call, linked by call_id. error is data the model reacts to.

Its elements are shown before text.

A tool error is never a Failure: the model reads error and continues. Subclass it for a tool that records typed fields, with a type of its own.

A picture that a tool shows the model with its result, such as a rendered page.

Content shown again that was shortened or removed earlier, named by its ids only.

What the model sees is drawn from the earlier results when the context is rendered, so nothing is stored twice.

A summary that replaces the events before a kept event in every later request to the model.

The kept event is the one at kept_from_seq in kept_from_stream. The thread keeps the events that the summary replaces.

The declaration, sealed before anything happens, that the agent will now act outside the thread.

kind is the declared verb, args the sealed argument.

For an intent without an EffectResult in the log, it is unknown whether the world changed.

The result of one intent, linked by intent_seq. error is data the graph routes on.

The runner stamps intent_seq. An effect result has no default actor: system if the runtime saw the result, user if a party outside the system reported the result.

Something the model is shown and can refer to again. Subclass Reference or Source, never this.

The class of an element tells what the element is. A class is stored under its name in kebab case (KnowledgeBase as knowledge-base) unless it declares type itself. So when you rename a class, its stored name changes too, and stored threads no longer read back. Declare the old name as type to rename safely.

An element is immutable. Add each subclass to the element_types of the agent whose threads record it.

An element the model can name, for example as a tool argument, but not cite: it saw no content of it.

Subclass it once for each kind of thing, such as a document in a listing or a knowledge base.

An element whose content the model saw, and so the only kind it can cite.

Subclass it once for each kind of thing, such as a passage or a web page. A source must name the element that it is part of in ref: validation fails without it.

An event that shows elements to the model.

The elements can be an input's attachments, a tool's documents and passages, or the retrieved sources of an agent's own event type. Every element shown is numbered by first appearance in the thread, so the model can cite it and name it to tools. Subclass it for an event type of your own that shows elements.

The element classes stored elements are read back into, by their type tag.

A set never changes: including returns a new one.

Make the set of element classes.

Raises:

• ValueError: Two element classes share a type tag.

A stored element has a type tag that is not among the element types that it is read with.

ElementTypes.decode raises it, and so does EventTypes.decode for an event that holds such an element. Add the element class to the agent's element_types. The error's argument is the unknown tag.

One number that a model output cited, at an offset in its cleaned text, and what it resolved to.

A marker that cites several numbers gives one citation for each number.

A citation marker that the model wrote, taken out of its text.

A marker records where it stood, the exact characters cut out there, and the numbers that it cited. Put each text back at its at to get the text as the model wrote it (see inserted).

One number inside a marker: what the model wrote, and the real id of the Source it named then.

Return text with each piece put in at its offset.

inserted(text, [(m.at, m.text) for m in markers]) gives back the text as the model wrote it.