Maida

Don't let broken agent changes merge.

_{A real run, caught. The agent returned a normal answer -- and looped search_kb five times to get there.}

Your agent still returns the right answer -- but now it calls 3x the tools. A retry loop that wasn't there last week. A new tool the baseline has never seen. Output evals pass. Review sees a green diff. It ships.

Maida is the pre-merge behavioral regression gate for AI agents. It compares agent execution traces against checked-in baselines and blocks PRs when structural behavior regresses.

🔒 No cloud or account required. No usage collection by default. Traces stay on your machine or CI runner. Optional usage counts require explicit consent and a configured collector; no collector is configured by default.

Start with one useful check

This checkout targets v0.6.0, supporting Python 3.12–3.14. Use the explicit version pin below; see the changelog for changes and migration from 0.5.x.

uv tool install "maida-ai==0.6.0"
maida demo --regression

Expect a FAIL verdict and a PR-comment preview: the simulated agent still answers, but loops and calls an unexpected tool. The demo command exits 0 after successfully showing the failing gate; an actual failed gate exits 1. No clone, API keys, or account are needed for this rehearsal.

Protect one coding-agent task →

Start with a one-minute task in your repository, such as finding its test command, and get a report on that actual execution. Allow 10–15 minutes for capture setup and the first check. Review a small baseline and policy when that result is useful; deliberate failure, repair, and CI come next. This is a setup target, not a measured activation claim.

Building a Python tool-calling agent? Use the secondary Python walkthrough, including installation into the project environment.

What the gate checks

Maida compares the observed execution against your checked-in policy and baseline: tool use, loops, stop conditions, structural counts, and configured cost or latency limits. It does not establish answer correctness or behavior outside the captured evidence. Keep your correctness tests alongside it.

Read the verdict: PASS, FAIL, or INCONCLUSIVE. Exit 0 includes INCONCLUSIVE; consumers must not treat process success as approval.

Investigate a failed check

Use maida view to inspect the local timeline and maida diff --baseline .maida/baselines/agent.json to understand the structural change. Repair an unintended regression; review the evidence and reason before accepting an intentional baseline change.

Add the PR gate

After the local pass → deliberate failure → repair loop works, follow the Action setup and protection requirements. Use the init reference for your installed version. The workflow needs a real entrypoint, dependencies, a reviewed baseline, and an immutable Action pin.

A generated workflow is setup, not evidence of merge enforcement. Verify required checks on the actual PR head, trusted base policy, workflow protection, and the fresh result after acceptance before relying on that boundary.

🔌 Integrations

Maida is framework-agnostic at its core -- the SDK works with any Python code. Adapters are optional and import-to-enable; the core package works without any of them installed.

Systems that write native traces directly can check them with maida validate-trace before handing them to the gate -- no SDK required.

Langfuse tells you what happened; Maida tells you whether it changed.

📚 Documentation

Full documentation lives at maida.ai/docs.

Step-by-step notebooks live in maida-ai/maida-tutorials -- all runnable without API keys.

🔒 Privacy and local-first guarantees

Redaction is on by default: values for keys matching api_key, token, authorization, cookie, secret, and password are scrubbed before anything is written to disk, and large fields are truncated.

Runs are plain files you can inspect or delete:

~/.maida/runs/<trace_id>/
├── meta.json     # run metadata (status, counts, timing)
└── spans.jsonl   # append-only OpenTelemetry span records

No prompt, response, tool payload, secret, or environment variable leaves your machine or CI runner unless you explicitly configure it. Set MAIDA_DATA_DIR to move storage elsewhere.

📖 Configuration reference

🧪 Development

git clone https://github.com/maida-ai/maida.git
cd maida
uv venv && uv sync && uv pip install -e .
uv run pytest

python -m venv .venv && source .venv/bin/activate
pip install -e .
pytest

Contributions welcome -- see CONTRIBUTING.md and SECURITY.md.

📄 License

Apache License 2.0. See LICENSE.