soev for developers
Python packages to build, serve and evaluate agents that answer questions from your documents.
The idea
soev builds agents that answer questions from your documents. You choose where each part runs: the model endpoint, the vector store and the store of the traces. So you control where the data goes.
soev is a set of Python packages, and each package does one job. You install only the packages that you need.
Packages
| Package | Use it to | Also installs | Documentation |
|---|---|---|---|
| soev-agents | Build and run agents. The runtime records each turn in a typed trace, and HTTP entrypoints serve an agent. | soev-inference, soev-retrieval | Tutorials and reference |
| soev-inference | Call chat models of more than one provider, with endpoint profiles, request and response transforms, and structural validators. | No reference. The README describes a config root. | |
| soev-retrieval | Search a vector store through one protocol, with Weaviate and pgvector adapters and one contract suite that tests each store. | Reference | |
| soev-indexing | Parse and chunk PDF, text and delimited documents, and index them with a small pgvector pipeline. | soev-inference, soev-retrieval | Reference and commands |
| soev-evals | Evaluate agents, with evaluation contracts, scoring, judges and local run archives. It reaches an agent over HTTP. | Reference and commands | |
| soev-inspect | Show what each model call of a thread received. It replays the thread from a trace store. | soev-agents, soev-inference, soev-retrieval | Reference and commands |
| soev-server | Serve soev-agents plugins from a basic server that an API key protects, with document collections. | soev-agents, soev-indexing, soev-inference, soev-retrieval | Reference and commands |
Related project: Warren, a separate framework that runs independent items through a pipeline of workers over RabbitMQ, Kafka or memory.
One document, from start to end
soev-indexparses a PDF, cuts it into chunks, embeds each chunk, and writes the chunks into a collection.- An agent of soev-agents searches that collection with a tool. It can cite the passage behind each fact.
soev-serverserves the agent. A client starts a thread and sends each turn over HTTP.- The runtime records each turn in the trace of the thread, as typed events.
soev-inspectreplays that trace. It builds each model call of the thread again, and shows what it received.soev-evalssends the cases of an evaluation to the server, and scores the answers.
Where to start
- Build an agent: do the soev-agents tutorials. They start with one agent and a search tool.
- Use your own vector store: read the reference of
soev_retrieval. Its contract suite checks a new adapter. - Evaluate an agent: read the reference of
soev_evalsand its commands.
Each package has an overview with its install steps, and a reference. The reference shows each name with the
import path of its package, for example from soev_agents.runtime import Thread. Only these documented paths are
stable. A name can also be imported from the module that defines it, but that path can change in any release.
Names with a _ prefix are internal.