Skip to main content

AQVEN

Discover what your AI workflow needs to work reliably. 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 · GitHub

AQVEN Studio showing a multi-step AI workflow on one canvas

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, OpenCode, Codex or any MCP client) works on the same files through AQVEN's MCP server, and runs experiments whose verdicts AQVEN computes.

AQVEN is in alpha: expect changes between releases.

What it's for

  • 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.

Install

You need uv. AQVEN runs on Python 3.14, and uv fetches it for you. Studio ships inside the package: no Node.js toolchain, nothing to build.

uv tool install aqven
aqven new my_project --template minimal --provider openrouter
cd my_project
uv run aqven check my_project
errors: 0, warnings: 0

aqven new writes the project, installs its environment 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. aqven check needs no API key and no network.

Work with your coding agent

Start Claude Code in the project, approve the aqven server, and hand it a task. It builds the flow, explores on working cases and confirms once on held-out cases; you read the first traces and make the decisions. Open Studio next to it with uv run aqven dev my_project.

For OpenCode, Codex, Cursor or another MCP client, see How to set up a coding agent outside Studio.

Commands

Command What it does
aqven new creates a project from a template, installs its environment and generates its models
aqven check checks the project and simulates every flow without network or tokens
aqven run runs a flow locally and prints run events as they happen
aqven dev starts the project server and opens Studio in the browser
aqven serve the project server without a browser: Studio API, engine and MCP
aqven mcp MCP over stdio, for a coding agent outside Studio

Built on

Pydantic AI calls the models, DBOS checkpoints every run on SQLite, the official MCP Python SDK serves and consumes MCP, and FastAPI serves Studio and the API. Runs locally.

FAQ

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 below.

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 in Studio's chat. In your own terminal: Claude Code, OpenCode and Codex from the files aqven new writes into the project, 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.

License

AQVEN is source-available, not open source, under the AQVEN License 1.0.0, based on PolyForm Shield 1.0.0. Use it for any purpose, including in production and in commercial products you build with it. 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. Full terms: LICENSE.

Copyright Kirill Burkhanov.

Metadata

Release files for aqven 0.0.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aqven 0.0.6
File Size Uploaded Provenance Actions
aqven-0.0.6.tar.gz 2.1 MB Without provenance Details for aqven-0.0.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aqven 0.0.6
File Interpreter ABI Platform Actions
aqven-0.0.6-py3-none-any.whl Python 3 none any Details for aqven-0.0.6-py3-none-any.whl

Total release size: 4.8 MB

Release files / aqven-0.0.6.tar.gz

Download URL aqven-0.0.6.tar.gz
Size 2.1 MB
Tags Source
SHA-256 checksum
How to use checksums
7055000d4928d9920e3620afe3fc5251dc180ad88d651f9c317cca8d50c6e970
BLAKE2b-256 checksum
How to use checksums
c46b31ce8daac2652caa8717e507ffca60f0eb4d48e17672e1e2d8458d29bf07
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / aqven-0.0.6-py3-none-any.whl

Download URL aqven-0.0.6-py3-none-any.whl
Size 2.7 MB
Tags Python 3
SHA-256 checksum
How to use checksums
8bd0a96c47e2f47e13afe866aa760855153fde99318c25d9ed7d6fe9c009a4e9
BLAKE2b-256 checksum
How to use checksums
8e913d019dd5122662a649ec5a6f29185d8e4802b7cb13a7c55111feb41d3412
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for aqven 0.0.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page