# AQVEN > AQVEN is a Python framework and a local Studio for building reliable LLM workflows. Claude Code or Codex runs the experiments; you see the evidence and decide. AQVEN uses Pydantic AI for model-facing agents and DBOS for durable execution. The documentation links below point to Markdown copies of each page. ## What AQVEN is for - [Find](https://aqvenstudio.com/use-cases/#find): What am I missing? Your agent explores cases and variants you wouldn't try yourself. - [Explain](https://aqvenstudio.com/use-cases/#explain): Why did this fail? Follow a bad answer back to the step where it started. - [Compare](https://aqvenstudio.com/use-cases/#compare): What should I change? Models and prompts side by side, with cost and latency. - [Confirm](https://aqvenstudio.com/use-cases/#confirm): Can I trust this change? A verdict on held-out cases that is allowed to say inconclusive. - [Build](https://aqvenstudio.com/use-cases/#build): How do I keep it readable as it grows? Typed files in your repo, checked before a run costs a token. - [Home](https://aqvenstudio.com/): What AQVEN is, what it is for, and how to get started. - [Use cases](https://aqvenstudio.com/use-cases/): Find, explain, compare, confirm and build in detail, each with links to the docs. - [Compare](https://aqvenstudio.com/compare/): Why AQVEN when you already have traces and evals: the questions a score doesn't answer, who does which part, and when another tool fits better. - [Roadmap](https://aqvenstudio.com/roadmap/): Where the work is going: what is in motion now, what comes next, what is later, and how alpha feedback changes the order. ## Start - [Start](https://aqvenstudio.com/llms/start/index.md): Start here to see how AQVEN, a Python framework and a local Studio for AI workflows, lets your coding agent run the experiments while you see the evidence and decide. - [Quickstart](https://aqvenstudio.com/llms/start/quickstart.md): From an empty folder to your first run, in under 30 minutes. - [From a bad answer to a verified fix](https://aqvenstudio.com/llms/start/engineering-loop-walkthrough.md): One example, three moves — see the graph, find the cause, verify the fix. - [A day with AQVEN](https://aqvenstudio.com/llms/start/a-day-with-aqven.md): One working day of a small business owner and a coding agent, from a slow support desk to a workflow with findings behind it — who types what, and who decides what. - [Where to go next](https://aqvenstudio.com/llms/start/where-next.md): Three ways to work with AQVEN, and where to connect a provider or read about how it works. ## Engine - [How to reuse a flow as a step](https://aqvenstudio.com/llms/engine/call-node.md): Add a call node that runs another flow as a single step, passing it typed input and getting back whatever that flow declares as its own output. - [How to check your model providers are configured](https://aqvenstudio.com/llms/engine/check-providers.md): What aqven models check reports for each agent's models — the structured output modes they support, and, with --live, whether they actually work against the real provider — without running any flow. - [How to find a model's real structural limits](https://aqvenstudio.com/llms/engine/check-shapes.md): What aqven models shapes reports for an agent's models — the nesting depth, list length and enum size they actually handle correctly, found with real, billed API calls. - [How to check a project before committing](https://aqvenstudio.com/llms/engine/check.md): What check actually validates in a project — file shape, type references, bindings, prompts, and a simulated run of every flow — and how to read a real error. - [How to write a step in Python](https://aqvenstudio.com/llms/engine/code-node.md): Add a code node that runs a plain Python function, with typed parameters in and a typed record out. - [How to write a custom evaluator](https://aqvenstudio.com/llms/engine/custom-evaluator.md): When a built-in check can't express what you need, write your own evaluator. This page shows the one function signature every check shares and a worked example from the showcase project. - [How to keep case media as files in the project](https://aqvenstudio.com/llms/engine/dataset-media-files.md): Point a dataset case at an image, audio, video or document file in the project instead of a blob, keep private files out of git, move old blob-backed cases to files, and read the three media diagnostics. - [How to customize a node's display in Studio](https://aqvenstudio.com/llms/engine/display-templates.md): Replace the raw JSON Studio shows for a node's input or output with a template built from sections, cards, fields, badges, lists and media. - [How to handle a shape you don't know in advance](https://aqvenstudio.com/llms/engine/dynamic-shape.md): Declare a field Dynamic, describe its real shape as FieldSpec data your code builds at run time, and read the result back narrowed or as it is. - [How to write an experiment](https://aqvenstudio.com/llms/engine/experiments.md): Write experiments//experiment.yaml — a falsifiable description, the subject, the cases by tags, the one factor its variants change, the checks and one of four questions — with an example from the showcase project for each question kind, and four common designs — comparing flow designs, leaving inputs out, screening many candidates, measuring one stage. - [How to constrain a field's values](https://aqvenstudio.com/llms/engine/field-constraints.md): Every in and out field can carry length, range, pattern, and choice constraints that a model's answer must actually obey — one small example per constraint, plus what happens when one is broken. - [How to generate types and editor schemas](https://aqvenstudio.com/llms/engine/generate-types.md): What aqven generate and aqven schema each write to disk, when a type change does and doesn't show up, and how to point your editor at the schema files. - [How to pause for a person](https://aqvenstudio.com/llms/engine/human-node.md): Add a human node that suspends a run and waits for a person to submit a typed answer, with a deadline and a policy for what happens if nobody answers in time. - [How to prepare images for a flow](https://aqvenstudio.com/llms/engine/image-preparation.md): Keep photos at their native resolution, apply the EXIF orientation, choose between one image and native-resolution crops as Image[] by what the task needs, look at a contact sheet and at synthetic images before a series, and confirm in the trace what the model received. - [Engine](https://aqvenstudio.com/llms/engine/index.md): Write workflows as files — nodes, prompts, experiments, and the CLI that checks and runs them. - [How to see what's in a project and how it connects](https://aqvenstudio.com/llms/engine/inspect-project.md): What aqven tree lists and what aqven refs shows for one entity — its definition, what references it, and what it references — with real output from the showcase project. - [How to call a model](https://aqvenstudio.com/llms/engine/llm-node.md): Add an llm node that calls an agent through a typed inference, with its prompt in its own file. - [How to repeat a step with a limit](https://aqvenstudio.com/llms/engine/loop-node.md): Add a loop node that runs the same sequence of steps pass after pass, stopping on a policy or a hard cap, then picks which pass's output the node returns. - [Patterns in the showcase](https://aqvenstudio.com/llms/engine/lumen-patterns.md): Generated from the showcase project, file by file. A prompt variant slot, map, parallel, call and switch steps, and one experiment for each factor kind. - [How to run a step over a collection](https://aqvenstudio.com/llms/engine/map-node.md): Add a map node that runs one node once per item in a list, with a concurrency cap and a policy for what happens when one item fails. - [How to narrow a dynamic value to a type](https://aqvenstudio.com/llms/engine/narrow-node.md): Add a narrow node that validates a Dynamic value against one real record or union type, turning an open-ended blob into ordinary typed fields. - [How to branch into parallel steps](https://aqvenstudio.com/llms/engine/parallel-node.md): Add a parallel node that runs several branches against the same input at once, with a join policy that decides how their results become the node's one outcome. - [How to prepare audio, video, documents and text for a flow](https://aqvenstudio.com/llms/engine/preparing-audio-video-documents-and-text.md): Inspect PDFs, recordings, clips, long documents and tables before a model reads them, keep the originals, cut them at boundaries you can check, keep every piece within the provider's limits, look at each piece before a series, and confirm in the trace what the model received. - [How to write a prompt](https://aqvenstudio.com/llms/engine/prompts.md): Write a prompt as plain text, a Liquid template, or a Python function — AQVEN picks the level from what the file actually contains. - [How to read a series](https://aqvenstudio.com/llms/engine/read-a-series.md): Read a series in order — its status, the verdict sentence and its reason, the variants × metrics matrix, stability, the failing cases and the spend — and know what to do after each verdict. - [How to run a series](https://aqvenstudio.com/llms/engine/run-a-series.md): Start a series of an experiment from Studio, the terminal or an agent — pick Explore or Confirm, choose the size, read the launch plan, get the spend approved, stop it. - [How to run a flow from the terminal](https://aqvenstudio.com/llms/engine/run-locally.md): Every run flag beyond the quickstart basics — context, targeting a flow, JSON events, cassette replay, human answers — where the run goes when the project server is up, and what each exit code means. - [How to manage secrets](https://aqvenstudio.com/llms/engine/secrets.md): What aqven secrets reports for every secret a project declares — across providers, tools, and MCP servers — and how it decides whether one is set, without ever printing the value itself. - [Tested snippets](https://aqvenstudio.com/llms/engine/snippets.md): Copy-ready project files for the common tasks — a flow, llm, code, map, parallel, switch and call steps, prompt variants and fragments, a dataset, one experiment per factor kind, rate limits and the spend cap — every one of them passes aqven check. - [How to route by a value](https://aqvenstudio.com/llms/engine/switch-node.md): Add a switch node that runs a different node, binds a different value, or both, for each possible value of an enum or a discriminated union, with every value covered and no default case. - [How to give an agent a tool](https://aqvenstudio.com/llms/engine/tool-node.md): Add a tool node that runs a piece of code you wrote, with a typed contract, its own secrets, and an optional wait for a long-running job. ## Studio - [How to work with cases in Studio](https://aqvenstudio.com/llms/studio/cases.md): Browse a flow's saved cases, filter them by tag, add cases by CSV or through the chat, run one case, or select several and run a look over the stages you pick. - [How to use the AI chat in Studio](https://aqvenstudio.com/llms/studio/chat.md): Pick a backend, start a thread, and let an agent run commands, edit files, and call tools on this project without leaving Studio. - [Your first workflow in Studio](https://aqvenstudio.com/llms/studio/first-workflow.md): Open a project entirely from the browser — check your agent and provider keys, then land on a real graph. - [Studio](https://aqvenstudio.com/llms/studio/index.md): Build, run, and debug workflows visually — the same project, from the browser. - [How to investigate a run](https://aqvenstudio.com/llms/studio/investigate-a-run.md): Open a run, trace a result back to the exact node execution that produced it, and read its input, prompt, output, and checks. - [How to open an existing project in Studio](https://aqvenstudio.com/llms/studio/open-a-project.md): Reopen Studio on a project you already have, or point it at a different project without hunting for a project picker. - [How to read the dev console](https://aqvenstudio.com/llms/studio/read-the-dev-console.md): What the terminal running the project server prints for runs, steps, retries, series and file changes, how to see more or less of it, where the full log is kept, and where the thread stacks of a stuck server go. - [How to use Research in Studio](https://aqvenstudio.com/llms/studio/research.md): Switch to Research, find the experiments that moved last or need you, create an experiment and choose its cases, read an experiment page block by block, launch a series to explore or confirm, and hand the next hypothesis to the chat. - [How to respond to a human-review request](https://aqvenstudio.com/llms/studio/respond-to-a-review.md): Open the review queue, read what a paused run produced, and submit the answer its human node's form is waiting for. - [How to follow and read a series in Studio](https://aqvenstudio.com/llms/studio/series.md): Find a series on the Series tab, follow it live, approve its spend or stop it, and read its verdict, variants × metrics matrix, stability and cases down to each attempt's run. - [How to use Studio settings](https://aqvenstudio.com/llms/studio/settings.md): Add the model keys your workflows need, connect your coding agent, check the Studio chat sign-in, set the research spend cap, and update AQVEN, all from one Settings page. - [How to read a workflow's graph](https://aqvenstudio.com/llms/studio/understand-the-graph.md): Open a flow's canvas or its node list to see every step, how they connect, and what each one is configured to do. ## MCP & CLI - [How to check and test a project as an agent](https://aqvenstudio.com/llms/mcp-cli/check-and-test.md): Call aqven_check, pyright_check, and pytest_run over MCP to validate a project and its code, and read a failure correctly. - [How to connect AQVEN as an MCP server](https://aqvenstudio.com/llms/mcp-cli/connect-an-agent.md): Connect a coding agent to AQVEN as an MCP server, either through the simple stdio bridge or directly over streamable HTTP. - [How to edit a flow's structure as an agent](https://aqvenstudio.com/llms/mcp-cli/edit-a-flow.md): Use flow_patch's 11 operations and a compare-and-swap file check to restructure a flow safely, and handle a stale-file conflict correctly. - [How to run experiments and series as an agent](https://aqvenstudio.com/llms/mcp-cli/experiments-and-series.md): Write an experiment file, start a series with series_start, wait for its verdict with series_get, read its outputs with series_outputs, and stop one with series_cancel. - [MCP & CLI](https://aqvenstudio.com/llms/mcp-cli/index.md): Connect a coding agent to AQVEN over MCP, and drive a project with its 18 tools. - [How to preview a prompt as an agent](https://aqvenstudio.com/llms/mcp-cli/preview-a-prompt.md): Call prompt_preview to see the exact instructions, messages, attachments and resolved output mode an llm node sends, and read its two real failure modes. - [How to read a project's structure as an agent](https://aqvenstudio.com/llms/mcp-cli/read-project-structure.md): There's no MCP tool that lists or fetches a project's structure — an agent reads the flow files directly, the same way it reads any other code. - [How an agent takes a task to a reliable flow](https://aqvenstudio.com/llms/mcp-cli/research-loop.md): The loop a coding agent runs over MCP — contract, simplest flow, cases, a look, error analysis, hypotheses, Explore on working cases, Confirm on held-out cases, apply the finding — round after round until the flow holds. - [How to start and follow runs as an agent](https://aqvenstudio.com/llms/mcp-cli/runs.md): Call the 8 run_* MCP tools to start, watch, fork, and cancel a run — and the two places their shape genuinely differs from the same operations over REST. - [How to set up a coding agent outside Studio](https://aqvenstudio.com/llms/mcp-cli/set-up-an-agent-outside-studio.md): Register AQVEN's MCP server and paste one setup prompt into Claude Code, Codex, or any MCP client you start yourself, so it reads the project's rules and connects the way Studio's chat does. ## Integrations - [How to connect an external MCP server](https://aqvenstudio.com/llms/integrations/external-mcp-servers.md): Register a remote MCP server in aqven.yaml and give its tools to an agent, either the whole server or one named tool at a time. - [Integrations](https://aqvenstudio.com/llms/integrations/index.md): Connect a model provider, an external MCP server, or a credential your project needs. - [How to connect a model provider](https://aqvenstudio.com/llms/integrations/model-providers.md): Declare a provider in aqven.yaml, name a model on it, set the credential it needs, find and verify candidate models on any provider, and pass the request options only that provider takes. - [How to choose models on OpenRouter](https://aqvenstudio.com/llms/integrations/openrouter-model-selection.md): The aggregator case of choosing a model, on OpenRouter. Pick candidates from its public catalogue by what they read, what they cost and which parameters they take, read a model's upstream endpoints, route it with provider_options, handle rate limits per model, and prove the choice with a live probe. - [How to set a secret for a provider, tool, or MCP server](https://aqvenstudio.com/llms/integrations/secrets-and-environment.md): Copy .env.example to .env, and set the same ref:env/NAME value wherever a provider, a tool, or an MCP server declares it. ## Concepts - [Agent, Inference, and the llm node](https://aqvenstudio.com/llms/concepts/agent-inference-and-the-llm-node.md): An llm node is backed by three separately filed entities that vary independently, not one blob of config. - [Answer, refusal and unknown are different states](https://aqvenstudio.com/llms/concepts/answer-refusal-and-unknown.md): Every field a prompt asks about is required, "cannot tell" is its own value, and a missing answer reads as unknown, never as no. How to model the states of an answer so that code, checks and people downstream read it right. - [Cases that can answer the question](https://aqvenstudio.com/llms/concepts/case-construction.md): A dataset answers a question only when it has ground truth, negative controls from the same population, enough cases per compared group in each half, and inputs that look like production. Where cases come from, how to vet a source and label cases, and how the split shapes the count. - [Designing reliable workflows](https://aqvenstudio.com/llms/concepts/designing-reliable-workflows.md): More nodes, parallel branches, critic loops and judges are not automatically more reliable. What each construct assumes, when it fits, when it does not, and how to measure the choice on your own cases instead of arguing it. - [The engineering loop: from incident to verified fix](https://aqvenstudio.com/llms/concepts/engineering-loop.md): From an unexpected result to a verified fix — understand, investigate, test the change — and the same loop run in rounds until a flow holds. - [Experiments, series and findings](https://aqvenstudio.com/llms/concepts/experiments-series-and-findings.md): A run proves one case. An experiment writes a question down before any data, a series answers it on many cases, and a finding records the answer in the project. - [Files as source of truth](https://aqvenstudio.com/llms/concepts/files-as-source-of-truth.md): A workflow project is a tree of files on disk — a node is a folder, and identity is a path, not a stored id. - [Finding the node where a workflow went wrong](https://aqvenstudio.com/llms/concepts/finding-the-node-that-went-wrong.md): Every step execution has a 4-field address, not just a node name, because the same node can run more than once inside one run. - [Five cases of dynamic input and output shape](https://aqvenstudio.com/llms/concepts/five-dynamic-shape-cases.md): The five ways a node's input or output shape can vary at run time, from an allowed-set of values to a fully dynamic schema, and the rule for picking the least dynamic one that solves the task. - [How a series decides](https://aqvenstudio.com/llms/concepts/how-a-series-decides.md): The statistics behind a verdict in plain words — intervals against a margin, repeats grouped by case, how many cases a margin needs, the noise floor, judges and what counts as a failure. - [Hypotheses by category](https://aqvenstudio.com/llms/concepts/hypothesis-categories.md): Which failures deserve an experiment, a claim template for each category of failure seen in traces, how to set each one up with one factor, and which hypothesis to test first. - [Concepts](https://aqvenstudio.com/llms/concepts/index.md): The facts and decisions behind AQVEN, written once and linked from everywhere else. - [Scanning the literature before you test](https://aqvenstudio.com/llms/concepts/literature-scan.md): Before you rank hypotheses, look up what is already known about the riskiest assumptions — where to search, what to write down, how to mark what nobody has confirmed, and why the web is a source for the domain but never for the engine. - [Media has real limits on both sides of a model call](https://aqvenstudio.com/llms/concepts/media-has-real-limits-on-both-sides.md): Every modality a provider takes in or produces has a ceiling, and crossing it either reshapes your data silently or refuses the call outright — a rule worth knowing for any modality, not only the ones this page happened to research. - [Correctness needs ground truth and a control](https://aqvenstudio.com/llms/concepts/metrics-and-controls.md): Agreement is not correctness, a proxy is not a label, a check measures one claim, a rate belongs to its own cases, and the main metric is the job of the stage you test. How to pick checks and controls that can tell a working flow from one that only looks consistent. - [The research journal](https://aqvenstudio.com/llms/concepts/research-journal.md): EXPERIMENTS.md is the project's own record of what it learned, written after every series for a reader who wasn't in the conversation. Its sections, what an entry holds, and the rule for reporting results to a person. - [A run survives a process crash](https://aqvenstudio.com/llms/concepts/run-survives-a-crash.md): A flow run is one durable workflow that checkpoints as it goes, so a crash or restart resumes it automatically instead of losing it. - [How big an output schema can get](https://aqvenstudio.com/llms/concepts/schema-state-space.md): A provider builds your output schema into a state machine before the model writes a token. Nesting, list lengths, enums and string lengths multiply its size, and past a limit the call fails. How to keep outputs small, how the failures look, and when prompted mode helps. - [When a stage is done](https://aqvenstudio.com/llms/concepts/stage-exit-criteria.md): The exit criterion of every stage between a request and a reliable flow, the false exits that look like progress, the stage of the flow each experiment measures, and when to stop the whole loop or stop and ask. - [Ten kinds of nodes](https://aqvenstudio.com/llms/concepts/ten-kinds-of-nodes.md): Every node in an AQVEN flow is one of exactly ten kinds, each with its own how-to page. - [Three prompt levels](https://aqvenstudio.com/llms/concepts/three-prompt-levels.md): When to reach for a plain prompt, a Liquid template, or a Python function, and what each one gives up in exchange for what it gains. - [Two ways to change a project](https://aqvenstudio.com/llms/concepts/two-ways-to-change-a-project.md): A direct file edit is checked after the write by a project hook; flow_patch is checked before the write by a compare-and-swap that can reject it outright. - [The validity gate](https://aqvenstudio.com/llms/concepts/validity-gate.md): The questions an experiment has to pass before its first series — one factor, compared things as variants, ground truth and a negative control, the same population in both halves, synthetic cases that have their property, the current best in the comparison, a reachable margin — and which of them the engine checks for you. - [What happens when a model is called](https://aqvenstudio.com/llms/concepts/what-happens-when-a-model-is-called.md): Every model call lands on one of four outcomes before AQVEN parses anything, and each agent decides whether an error, a refusal or a truncation fails the node, retries the model, or falls back to the next one. - [What this is built on](https://aqvenstudio.com/llms/concepts/what-this-is-built-on.md): Proven components under one workflow language, not a homegrown runtime. ## Reference - [Accepted values](https://aqvenstudio.com/llms/reference/accepted-values.md): Generated enums from the AQVEN Python package. - [Agent specification](https://aqvenstudio.com/llms/reference/agents.md): Generated field reference from the AQVEN Python package. - [Python authoring API](https://aqvenstudio.com/llms/reference/authoring-api.md): Generated signatures for Python flow and inference builders. - [Built-in policies and evaluators](https://aqvenstudio.com/llms/reference/built-in-policies.md): Generated policy names and Python signatures. - [CLI commands](https://aqvenstudio.com/llms/reference/cli.md): Generated command registry from the AQVEN Python package. - [Common limits and constraints](https://aqvenstudio.com/llms/reference/common.md): Generated field reference from the AQVEN Python package. - [Datasets](https://aqvenstudio.com/llms/reference/datasets.md): Generated field reference from the AQVEN Python package. - [Diagnostics and error codes](https://aqvenstudio.com/llms/reference/diagnostics.md): Generated diagnostic-code index from the AQVEN Python package. - [Environment variables](https://aqvenstudio.com/llms/reference/environment.md): Generated provider key-variable index from the installed AQVEN packages. - [Error codes](https://aqvenstudio.com/llms/reference/error-codes.md): Generated index of run error codes, API error codes and check diagnostics from the AQVEN Python package. - [Experiments](https://aqvenstudio.com/llms/reference/experiments.md): Generated field reference from the AQVEN Python package. - [Fields and bindings](https://aqvenstudio.com/llms/reference/fields.md): Generated field reference from the AQVEN Python package. - [Findings](https://aqvenstudio.com/llms/reference/findings.md): Generated field reference from the AQVEN Python package. - [Flow specification](https://aqvenstudio.com/llms/reference/flows.md): Generated field reference from the AQVEN Python package. - [Reference](https://aqvenstudio.com/llms/reference/index.md): Generated field-by-field reference for every YAML kind, CLI command, and diagnostic code. - [Inference specification](https://aqvenstudio.com/llms/reference/inference.md): Generated field reference from the AQVEN Python package. - [MCP servers](https://aqvenstudio.com/llms/reference/mcp.md): Generated field reference from the AQVEN Python package. - [Media and dynamic values](https://aqvenstudio.com/llms/reference/media.md): Generated field reference from the AQVEN Python package. - [Node specifications](https://aqvenstudio.com/llms/reference/nodes.md): Generated field reference from the AQVEN Python package. - [HTTP API / OpenAPI](https://aqvenstudio.com/llms/reference/openapi.md): Generated endpoint index from Studio's OpenAPI document. - [Policies and limits](https://aqvenstudio.com/llms/reference/policies.md): Generated field reference from the AQVEN Python package. - [Project MCP tool reference](https://aqvenstudio.com/llms/reference/project-mcp-tools.md): Generated operation index from AQVEN's project MCP registrations. - [Project configuration](https://aqvenstudio.com/llms/reference/project.md): Generated field reference from the AQVEN Python package. - [Rendered prompts](https://aqvenstudio.com/llms/reference/prompts.md): Generated field reference from the AQVEN Python package. - [Provider catalog](https://aqvenstudio.com/llms/reference/provider-catalog.md): Generated catalog of model providers in the installed Python package. - [Python API](https://aqvenstudio.com/llms/reference/python-api.md): Generated signatures of the public AQVEN Python package. - [Statuses and verdicts](https://aqvenstudio.com/llms/reference/status-and-verdicts.md): Generated index of series statuses, pause reasons, verdicts, attempt outcomes and run statuses. - [Tool specification](https://aqvenstudio.com/llms/reference/tools.md): Generated field reference from the AQVEN Python package. - [Type specifications](https://aqvenstudio.com/llms/reference/types.md): Generated field reference from the AQVEN Python package. ## Optional - [Full documentation](https://aqvenstudio.com/llms-full.txt): Every documentation page above in one Markdown file.