Skip to content

Contributor docs#

You're here to read code, extend code, or ship changes back. Start here.

Prerequisites: read Concepts first — understand the mental model before diving into implementation.

  • Per-subsystem docs

    Every folder under ml_team/ has an IMPLEMENTATION_README.md (engineering memory) + LEARNING_README.md (conceptual model). 5,400+ lines total. The authoritative contributor surface.

  • How to add a test

    Conventions, singleton reset patterns, matrix tests, regression gate.

  • Release process

    Tag → build → publish → announce.

Project map#

swarm/
├── ml_team/
│   ├── core/          engine: agent runtime, permissions, hooks, cron, batch
│   ├── api/           FastAPI layer + routers (17 of them)
│   ├── backends/      native / LangGraph orchestrators
│   ├── tools/         38 leaf tools (training / eval / compliance / deploy)
│   ├── config/        agent_defs.py, pipeline YAMLs, 40 rule files
│   ├── dashboard/     Next.js 16 UI
│   └── tests/         30+ test files + bench + e2e
├── docs/              this site
├── .project/          strategy + research + decisions (ADRs)
├── deploy/            Helm, Compose, Terraform
├── examples/          plugin examples
└── CHANGELOG.md

Where to start#

If you want to… Read this first
Fix a bug in the agent loop core IMPL — agent_runner.py section
Add a new tool How-to: Write a custom tool
Extend the plugin loader core IMPL — plugin_loader section
Add a REST endpoint api IMPL
Build a new dashboard page dashboard IMPL
Add a compliance profile tools IMPL — audit_pdf + fairness sections
Write a regression test How to add a test
Understand why X was built the way it was .project/decisions.md — ADR log

Contributing workflow#

See CONTRIBUTING.md for the full guide. Short version:

  1. Fork + branch (fix/description, feat/description)
  2. Write tests
  3. ruff format . + run regression gate (.venv/bin/pytest ml_team/tests)
  4. Commit with DCO sign-off: git commit -s -m "fix(scope): what broke"
  5. PR against master

CI runs the full test suite + doc-drift check on every PR.

Decision log#

Every non-trivial architectural choice has an ADR at .project/decisions.md. Read the relevant ADR before proposing a redesign — we've usually already considered + rejected the alternative.

Strategic decisions (open-source model, pricing, compliance roadmap) live under .project/strategy/. Research notes at .project/research/.