Butterflow

Quickstart

Get from zero to your first passing flow in five minutes.

Install

pip install -e ".[dev]"
# or with uv:
uv pip install -e ".[dev]"

Verify the CLI is available:

butterflow --help

Write your first spec

Create evals/hello.py:

from butterflow import expect, flow

with flow("say hello", subset="smoke") as f:
    f.intent("The assistant greets the user.")
    f.input("Hello!")
    f.expect(expect.agent("router").selects("greeter"))
    f.expect(expect.final_response().contains("Hello"))

Discover and dry-run

butterflow ingest evals/
butterflow run evals/ --dry-run

Or try the bundled examples:

butterflow ingest examples/
butterflow run examples/ --dry-run

Build a plan

butterflow plan examples/ --show-cache-clusters

Generate docs

butterflow docs examples/

Next steps