AQVEN is a Python framework and a local Studio for building reliable LLM workflows: multi-step pipelines of models, tools and human review.
Your coding agent runs the experiments. You see the evidence and decide.
Documentation · Quickstart · Use cases · Studio · llms.txt
AQVEN keeps an AI workflow as typed files in your repository: a flow, one file per step, prompts in
Markdown, and declared types, agents and tools. aqven check validates every connection and simulates
every flow before you spend a token. Studio, a local browser app in the same install, shows each run
step by step. Your coding agent (Claude Code, Codex or any MCP client) works on the same files through AQVEN's
MCP server, and runs experiments whose verdicts AQVEN computes.
Note
AQVEN is in alpha: expect changes between releases. It is source-available, not open source. See License.
| Find | "What am I missing?" Your agent explores cases and variants you wouldn't try yourself. | | Explain | "Why did this fail?" Follow a bad answer back to the step where it started. | | Compare | "What should I change?" Models and prompts side by side, with cost and latency. | | Confirm | "Can I trust this change?" A verdict on held-out cases that is allowed to say inconclusive. | | Build | "How do I keep it readable as it grows?" Typed files in your repo, checked before a run costs a token. |
You need uv. AQVEN runs on Python 3.14, and uv fetches it for you.
uv tool install aqven
aqven new my_project --template minimal --provider openrouter
aqven new writes the project, installs its environment with uv sync and generates typed Python
models. It also prepares the project for a coding agent: AGENTS.md, CLAUDE.md, an .mcp.json that
registers AQVEN's MCP server, and Claude Code hooks that run aqven check as the agent works.
A real run needs a model key: copy my_project/.env.example to my_project/.env and set
OPENROUTER_API_KEY in it. A run spends against whichever key it finds, in .env or exported in
your shell, so a real run is never free. aqven check needs neither a key nor the network.
| Platform | Status |
|---|---|
| Linux | The full CI suite runs on ubuntu-latest on every change. |
| macOS | Primary development platform. The install path and the offline aqven check are smoke-tested from a built wheel by the Platform smoke workflow; the full test suite is not yet run on macOS in CI. |
| Windows | The install path is not yet proven: the Platform smoke workflow builds and installs the wheel on a Windows runner and runs aqven check , but nothing beyond that is tested there. If it breaks for you,open an issue — help making AQVEN a proven Windows citizen is welcome. |
Python version policy. AQVEN requires >=3.14,<3.15: the engine runs on exactly one minor
version, so step code behaves the same everywhere. uv fetches 3.14 for you. Python 3.15 was
released in October 2026; support is planned, and it will land in a release when the engine, its
dependencies and CI are green on it — we are not promising a date.
Start Claude Code in the project and approve the aqven server when it asks:
cd my_project
claude
Then hand it a task. It builds the flow, runs aqven check after every change, and works in rounds:
Build a flow that reads an incoming support e-mail and returns its intent (defect, delivery or question) and a one-line summary.
Done means: the intent is right on more than 90% of held-out cases, and a case costs under $0.002.
Work in rounds: explore on working cases, confirm once on held-out cases. Stop when every "done" criterion is confirmed, or when you have spent $5.
Then report FINDINGS.md, the decisions you made and the risks that are left.
Open Studio next to it to watch every run, or chat from there: its chat panel runs Claude Code or Codex on the same project.
uv run aqven dev my_project
For Codex, Cursor or another MCP client, see
How to set up a coding agent outside Studio.
aqven new already puts AQVEN's skills into the project; to have them in Claude Code everywhere, install
them as a plugin: /plugin marketplace add lastonoga/AQVEN, then /plugin install aqven@aqven.
Check the new project:
cd my_project
uv run aqven check my_project
errors: 0, warnings: 0
aqven check validates every file, then simulates a run of every flow with stand-ins for the model
calls. Run it after every change. With a key in .env, run the flow for real, one line per event as it
happens:
echo '{"text": "How long does a light strip last?", "tone": "friendly"}' > question.json
uv run aqven run answer_question --root my_project --input question.json
This is the project, trimmed to the files that define the workflow:
my_project/
AGENTS.md CLAUDE.md .mcp.json .claude/ pyproject.toml
my_project/
aqven.yaml
agents/assistant.yaml
tools/count_words.yaml
types/enums/tone.yaml types/records/question.yaml types/records/answer.yaml
flows/answer_question/
flow.yaml
nodes/prepare/ prepare.node.yaml prepare.py
nodes/reply/ reply.node.yaml reply.inference.yaml reply.prompt.md
flows/answer_question/flow.yaml declares the input, the output and the order of the steps:
apiVersion: "aqven/v1"
kind: "Flow"
description: "Cleans up a question and answers it in the requested tone"
input: "Question"
output: "Answer"
returns:
- name: "reply"
from: "$reply.out.reply"
- name: "tone"
from: "$input.tone"
order:
- "prepare"
- "reply"
flows/answer_question/nodes/reply/reply.node.yaml is a model step. It takes text from the
prepare step and tone from the flow input:
apiVersion: "aqven/v1"
kind: "Node"
node: "llm"
description: "Answers the prepared question with the assistant agent"
agent: "assistant"
in:
- name: "text"
from: "$prepare.out.text"
- name: "tone"
from: "$input.tone"
reply.prompt.md is the prompt, a file of its own. reply.inference.yaml declares the typed input
and output of the call.
Answer the question in a {{ tone }} tone, in at most 120 words.
If you are not sure a draft fits, count its words with the count_words tool.
<question>{{ text }}</question>
{{ output_format }}
Now break one reference: change $prepare.out.text to $prepare.out.txt and check again.
$ uv run aqven check my_project
flows/answer_question/nodes/reply/reply.node.yaml:8:3: error E_REF_MISSING in[0].from: reference $prepare.out.txt: the value has no field txt
errors: 1, warnings: 0
The check exits with code 1, so a hook or a CI job stops there. It also catches a value whose type
doesn't fit the slot (E_BINDING_TYPE), a prompt variable the inference doesn't declare
(E_PROMPT_VARIABLE_UNDECLARED) and a switch that misses a case (E_SWITCH_NOT_EXHAUSTIVE).
→ All diagnostics
The quickstart walks through AQVEN's full example,
--template showcase: a support flow with every node kind, human approval and experiments.
One run proves one case, and aqven check proves the wiring. Neither says how the workflow behaves on
real inputs. The agent finds out in rounds, and you make the decisions:
- You set the goal, what "done" means in numbers, and a budget.
- The agent builds the simplest flow that works, writes cases with expected outputs, and runs
aqven checkafter every change. - You read the first traces it hands you, failing runs first, and note the first thing that went wrong in each.
- The agent groups your notes into failure modes you agree on, and writes one experiment per mode before any data.
- The agent explores on working cases, one change between series, then confirms once on held-out
cases, the half of each dataset it never sees case by case. The server writes the verdict
(
confirmed,refutedorinconclusive), and the finding lands inFINDINGS.md. - You decide which limits are requirements, how much quality a cheaper step may lose, and any spend above the project cap. An agent can start a series but never approve its spend.
A verdict holds for the cases, checks and versions it measured. It is evidence for a decision, not a guarantee about every future output.
→ A day with AQVEN · How an agent takes a task through the research loop
| Part | What it is |
|---|---|
| Flows and nodes | Ten node kinds — llm ,code ,tool ,human ,switch ,parallel ,map ,loop ,call ,narrow — composed into a typed graph |
| Types | Records, enums, unions, IDs, values and media, checked at every boundary. A model can't return a field that isn't declared |
| Prompts | Plain text, Liquid templates with shared fragments, or a Python function. Always a file of its own, never a string inside YAML |
| Agents and providers | An agent is a model with its settings and output mode, in its own file. The provider catalog has 28 entries through Pydantic AI, from OpenAI, Anthropic and Google to OpenRouter, Mistral, DeepSeek, Groq and Ollama |
| Tools | Python functions or MCP servers, with a declared read ,write orexternal effect |
| Human review | A step that waits on a person, with a timeout and a default |
| Cases | Datasets of tagged cases with expected outputs, split by a hash of each name into working and held-out halves |
| Experiments and findings | An experiment writes one question down before any data. A series answers it across variants and cases. A verdict on held-out cases becomes a finding in FINDINGS.md |
| Durable execution | A run survives a crash and resumes where it left off |
| Studio | The local browser app. Flow shows a workflow's graph, runs and cases.Research shows experiments and series, and launches a series toExplore orConfirm |
| MCP server | The same tools Studio's chat uses, for any MCP client: flow_patch for cross-file edits,aqven_check ,prompt_preview ,run_start ,series_start and more |
- One prompt, one model call. Call the model's SDK directly; a flow adds files you don't need.
- You only want to trace an app you already have. AQVEN runs workflows written in its own files. A tracing tool fits better.
- You need a hosted service for a team. AQVEN runs locally, on your machine.
- You can't run Python 3.14. The engine requires exactly 3.14, and your step code runs on it (seeTested platforms for the version policy).
- You need an OSI-approved open-source license. AQVEN is source-available.
| Tracing tools | Visual builders | AQVEN | |
|---|---|---|---|
| Where the logic lives | Your code | Their platform | Files in your repo |
| Checked before it runs | No | No | Yes |
| Yours if the vendor disappears | Yes | No | Yes |
| Adds to the app you already have | Yes | No | No: the workflow moves into AQVEN files |
Tracing tools means products such as Langfuse, LangSmith and Arize Phoenix. Visual builders means products such as n8n, Dify and Flowise.
Pydantic AI calls the models, DBOS checkpoints every run on SQLite, the official MCP Python SDK serves and consumes MCP, FastAPI serves Studio and the API, and python-liquid renders prompt templates. → What this is built on
What is AQVEN? A Python framework and a local Studio for building reliable LLM workflows. A workflow is a set of typed files in your repository: a flow, one file per step, prompts in Markdown, and declared types, agents and tools. AQVEN checks the files before a run, runs the flow with checkpoints, and runs experiments on cases to tell you whether a change helped.
Is AQVEN open source? No. It is source-available under the AQVEN License 1.0.0, which is based on the PolyForm Shield License 1.0.0. You may use it for any purpose, including production and commercial products, and the workflows you build are yours to sell. You may not use it to provide a product that competes with AQVEN, and you may redistribute AQVEN itself only free of charge and for a non-commercial purpose. See License.
Which Python version does it need? Python 3.14. uv fetches it for you.
Which coding agents does it work with? Claude Code and Codex, from Studio's chat or from your own terminal, and any other MCP client, such as Cursor, through AQVEN's MCP server.
Which model providers can I use? The provider catalog has 28 entries through Pydantic AI, from OpenAI, Anthropic and Google to OpenRouter, Mistral, DeepSeek, Groq and Ollama.
Do I need an account or a hosted service? No. AQVEN runs on your machine. aqven check needs neither a
model key nor the network; a real run needs a key for the provider you choose.
What does aqven check do? It validates every file, type reference, binding and prompt, then simulates
a run of every flow with stand-ins for the model calls, so most wiring mistakes surface before a run costs
a token.
Does a "confirmed" verdict guarantee quality? No. A verdict holds for the cases, checks and versions it measured. It is evidence for a decision, not a guarantee about every future output.
How is AQVEN different from an eval library? Eval libraries typically score the outputs of an app you already have. AQVEN also holds the workflow itself as typed files that are checked before they run, and its experiments write the question down before any data and give a verdict on held-out cases that is allowed to say "inconclusive". If you only need to score an existing app, an eval library is the lighter choice.
- Docs:aqvenstudio.com . For an agent,llms.txt indexes every page in Markdown.
- Bugs and ideas:GitHub Issues .
AQVEN is source-available, not open source, under the AQVEN License 1.0.0 — based on the PolyForm Shield License 1.0.0, with one addition.
- You may use it for any purpose, including in production and in commercial products you build with it: the AI workflows you create with AQVEN are yours, and selling them is explicitly permitted.
- You may not use AQVEN — original or modified — to provide a product that competes with it.
- You may redistribute copies of AQVEN itself only free of charge and for a non-commercial purpose. The right to sell AQVEN itself stays with the licensor.
Copyright Kirill Burkhanov. Full terms: LICENSE.