What each part does.
And how they connect.

OVMS runs the model: it generates text, decodes tool calls, batches requests and targets a device. It does not decide which model, which device, which parser, which tools, or when to start and stop. OVAT turns that gap into a config file, the way kubectl wraps the Kubernetes API rather than replacing it. One workflow.yml in, one wired agent out.

There are two ways to run the model. Through OVMS (model.provider: ovms, the default) is the agent path: ovat run, ovat bench and the terminal UI's /engine ovms. OVMS decodes tool calls, so the agent can use tools; Windows and Linux only. In-process, through openvino_genai (ovat chat, the terminal UI's /chat) needs no server and makes no tool calls: OVAT searches your documents first, then hands the passages to a local model. That path also works on macOS.

Four principles shape the code. The reasons behind each one, with the alternatives and measurements that settled them, are in docs/DECISIONS.md.

What you need depends on what you run. The Python extras come from pyproject.toml.

Every command is a Python function that Typer turns into ovat <command> from its type hints. There are eleven: run, chat, index, init, doctor, setup, serve, models, bench, telemetry and tui. A bare ovat opens the terminal UI.

The config is strict. WorkflowConfig is a pydantic model that forbids unknown keys. A typo such as max_iteration fails at once, by name, instead of being ignored while the default stays in charge.

Only one function loads it. _load_config() in cli/main.py turns three different failures into three plain sentences: the file is missing, the YAML does not parse, or the schema does not match. yaml.safe_load(f) or {} makes an empty or comments-only file a schema error that names the missing section.

Model text is data, not markup. Every value that reaches the console goes through esc(), because the console library reads [...] as a style tag. Model output, exception text and file paths are data.

Every engine exposes the same .run(text) -> text. The factory hands back one of them and the CLI never knows which. In C++ terms it is one interface with four implementations.

Two things keep the four consistent. Tool arguments for every engine are derived from each tool's own SCHEMA by agent/arg_models.py, so no engine keeps a second copy. And the server connection (URL, model, timeout, temperature, token cap) is described once, by LLMBackend.from_config in providers/backend.py, which all four read.

Token counts. OVMS returns token usage on every reply, and all four engines record prompt and completion tokens from its usage field, plus tool counts. The native loop records them per turn. The three framework engines record run totals in the same trace shape (agent/usage.py), summed from what each framework kept. A reply with no usage leaves the cell a dash, never 0.

Only LlamaIndex and the OpenAI Agents SDK own an event loop. Those two engines are async and call asyncio.run themselves, which cannot be re-entered, so they check for a running loop and raise a readable error rather than deadlock. LangChain calls invoke() synchronously. In the terminal UI all four work, because the chat screen runs the agent on a worker thread where no loop is running.

A model can only write text. The native loop in agent/loop.py is what turns its written request into a real function call. Each round has four beats: ask, read, act, report. Below, one real question from the RAG example goes round twice.

providers/base.py defines four abstract classes: the sockets. Each concrete class beside it is a plug. The config names a plug as a string, so swapping a backend is a YAML edit. The agent loop and all four engines only ever see the interface.

RAG means retrieval-augmented generation: find the right passages first, then let the model answer from them. OVAT does it in two phases. ovat index runs once; search_docs runs whenever the model asks, and ovat chat always searches first.

Each built-in tool follows one pattern: a plain *_impl() function you can unit test, a SCHEMA dictionary beside it that is the tool's contract, and a FastMCP wrapper so the same file also runs as a standalone MCP server.

MCP is a standard way for a program to offer tools to any agent. OVAT is an MCP client too: declare type: mcp_stdio, and the factory starts the server, asks it which tools it offers, and hands them to the loop in the same shape as the built-ins. The loop cannot tell them apart.

ovat setup picks the right OVMS archive for your OS (and, on Linux, your distribution), checks its SHA-256, and unpacks it into ~/.ovat/ovms. Nothing is added to PATH. It always takes the python_on build: the python_off build cannot do tool calling. The pinned version, OVMS 2026.4.1, lives in one place, ovms_installer.OVMS_VERSION, and ovat setup and ovat doctor both say when the installed binary differs from it.

It is a command rather than part of pip install because the archive is 126 to 185 MB, Linux needs three different builds, wheels have no post-install step, and macOS has no build at all.

core/device_manager.py asks OpenVINO which devices exist, then looks the answer up in a routing table. The result is a default suggestion: ovat doctor shows it, ovat init writes the suggested LLM device into a new workflow.yml, and the transcribe and describe_image tools use it when their own device: is not set. Any model can run on any device OpenVINO supports for it. In workflow.yml, model.device defaults to CPU, and whatever you set there wins. Pick a machine to see the suggestions.

OVAT collects machine and process metrics (CPU per core, RAM, threads, its own resident memory), NPU busy %, KV cache usage from ovms.log, power and bandwidth from Intel Unified Telemetry when it is installed, and the per-run agent trace: latency, tokens, tool calls, failure flags and peak memory.

Where a number comes from (a source) and where it goes (a sink) are separate contracts, so any source feeds any sink. The collector polls every source on its own thread, once a second by default, so a stuck sensor cannot slow the agent.

There is no OTLP exporter. OVAT's telemetry goes to a JSON Lines file or the live terminal UI page. Per-request OpenTelemetry spans come only from the optional plano gateway, which runs outside OVAT; OVAT has no OpenTelemetry dependency of its own. plano measures the transport (latency, time to first token, HTTP status); OVAT measures what the agent did.

Agent-to-agent (A2A) orchestration was a stretch goal in the project proposal, and the core toolkit works without it. It is out of scope, and there is no A2A code in OVAT.

All four end the same way: the agent answers fluently and has called nothing. That is the hardest kind of broken to notice, so the loop detects each one and sets a flag in the trace. ovat bench scores on those flags, not on the answer text, and ovat run checks the final answer for markup on every engine.

The project proposal described OVAT as nine numbered layers. This page is organised by what each part does instead; this list maps one to the other.