Getting started¶

Install¶

git clone <repo> bfev && cd bfev
uv venv && uv pip install -e ".[dev]"

Verify:

bfev --version
pytest -q          # should report 16 passed

Configure $BFEV_HOME¶

bfev stores all client data outside the repo by default, under ~/bfev/. That keeps confidential client emissions data out of any git history.

export BFEV_HOME=~/bfev          # or wherever you keep client work

Optionally drop a bfev.toml at the root of a project:

[paths]
home      = "${HOME}/bfev"
resources = "${BFEV_HOME}/resources"
clients   = "${BFEV_HOME}/clients"

[defaults]
scenario                  = "v0"
locale                    = "fr-FR"
uncertainty_tolerance_pct = 0.5

Bootstrap a client¶

bfev init porteo-btp
$EDITOR ~/bfev/clients/porteo-btp/client.yaml

This creates the layout:

~/bfev/clients/porteo-btp/
  client.yaml          # ground truth — fill this in
  collection/
  activity-data-v0/
  calculations-v0/
  deliverables-v0/
  runs.jsonl           # append-only run log
  lockfile.yaml        # bfev version + factor pinning

Run the pipeline¶

Pipeline stages are agents, run through Claude Code via the bfev plugin. The CLI does not invoke Claude itself. After each stage completes, the agent writes a record to runs.jsonl and the orchestrator can audit cross-stage consistency mechanically:

bfev log porteo-btp -n 20
bfev audit porteo-btp

bfev audit returns exit code 0 if all checks pass, 1 otherwise. Useful in CI.

Where to next¶

Architecture — the orchestrator + 4 sub-agents design.
Contracts — exact I/O of each agent.
Testing — golden runs, contract tests, the meta-test workflow.
Packaging — how to share bfev with colleagues.