soev_agents.ports

An adapter that calls a model: it sends a ChatRequest and returns the model's output.

A model step calls it with the request that it built from the trace. The adapter maps the whole response of its API to one ModelOutput, which the step records. Translate the transient errors of the API to TransientError in the adapter, and let every other error propagate.

from collections.abc import AsyncIterator

from soev_agents.domain import ModelOutput
from soev_agents.ports import ChatRequest, Fragment, UserMessage


class EchoModel:
    def resolve(self, model: str | None) -> str:
        return model or "echo"

    async def complete(self, request: ChatRequest, *, model: str | None = None) -> ModelOutput:
        last = request.messages[-1]
        text = last.content if isinstance(last, UserMessage) and isinstance(last.content, str) else ""
        return ModelOutput(content=text, model=self.resolve(model), finish_reason="stop")

    async def stream_complete(
        self, request: ChatRequest, *, model: str | None = None
    ) -> AsyncIterator[Fragment | ModelOutput]:
        output = await self.complete(request, model=model)
        yield output.content
        yield output

What one model call sends: the messages and the tools that the model can call.

A ChatModel that can show what it sends for a request, without a call.

Not every adapter can. replay uses it to show what the adapter changes in each request that it rebuilds.

A request in the shape that the adapter's client sends, prepared but not sent.

PreparesRequests.prepare returns it.

One message of a ChatRequest: the instructions, a user message, an earlier output or a tool result.

A system message: the instructions to the model.

A message from the user to the model.

An earlier output of the model, sent back to the model.

The result of one tool call that the model made, sent back to the model.

A tool that the model can call.

tool_def makes one from a tool.

One part of a user message: a text or an image.

A text in the parts of a user message.

A picture in the parts of a user message.

A piece of a model's output while it arrives: a string of the output's text, or a ReasoningDelta.

A piece of the model's reasoning, which the adapter yields while the model's output arrives.

The complete reasoning is in ModelOutput.reasoning.

A store that keeps the trace of each thread, as a log of StoredEvents.

The store knows no event class, so it works unchanged for every event type that an agent defines. It seals each event at append, and it hands out the lease that lets one process at a time run a thread. InMemoryTraceStore, SqliteTraceStore and PostgresTraceStore are the built-in stores.

An event as TraceStore takes and returns it.

The store reads the bookkeeping fields, such as stream and seq. It keeps payload as JSON and never reads it. encode makes the StoredEvent of an event, and EventTypes.decode reads it back.

One event of a thread's log, with its position.

TraceStore.read yields entries that hold a StoredEvent. The runtime hands on the decoded event with the same position.

The right to run one thread, as TraceStore.acquire handed it out.

Another owner holds the thread's lease, and that lease has not expired.

TraceStore.acquire raises it. Nothing changes. The caller decides to wait, to give up, or only to read.

The lease that a call names is no longer the thread's current lease.

TraceStore.append and TraceStore.renew raise it. The lease expired and another acquisition replaced it, or its owner took a new one. Nothing lands. The process that holds the current lease continues the thread from its tail.

An event to append is sealed already.

TraceStore.append raises it when an event of the batch has its seq or ts set. Appending is what seals an event into the log, and a fact is sealed only once. Nothing of the batch lands.

An append names a position that a stream moved past.

TraceStore.append raises it when a stream in expected grew after the caller read it. The batch never lands. The writer reads again and decides again. It does not retry the same append, because what landed can change the decision.

A passive watcher of runs: it gets each HTTP request, run, recorded event, model call and tool call.

An observer must only watch: it must not change what is recorded or what a model gets. When a method raises, the runtime logs a warning, and the run continues unchanged. Give an observer to create_app as observer. OtelObserver is the built-in observer.

The kind of a call that an Observer gets: "model" for a model call, "tool" for a tool call.

A call to the outside world failed for a reason that is not in the call itself.

The service was down, slow or unreachable. The same call can succeed later, so the failed step can run again. Any failure that is not raised as this error is permanent.

Model adapters raise it, and a step or a tool can raise it. When a step raises it, the runner records a transient Failure, and the node runs again when the thread runs again. When a tool raises it, the model reads its message as the result of the call.

The backend rejected the query itself.

A tool raises it, so that the model can fix the query and call again. The model reads its message as the result of the call. The backend responded, which tells this error apart from TransientError.

An adapter that is unavailable or not configured refused the call.

Its message is worded for the model. When a tool raises it, the model reads the message as the result of the call. An adapter from refusing raises it for every call.