YAML schemas#
swarm uses YAML for declarative configuration in three places:
- Pipelines — pipeline templates under
config/pipelines/*.yaml - Agent definitions — per-agent operational rules under
config/agent_rules/*.yaml - Permission policies — operator-authored rules under
config/permission_policies*.yaml
Why YAML#
- Declarative > imperative for configuration
- Reviewable in PRs
- No code to execute — safer to accept from operators
- Machine-readable — can be edited by UI, not just humans
- Versionable —
git blameshows who changed what and when
Schema enforcement#
All schemas are validated via Pydantic at load time. Bad YAML → startup error with a clear message pointing at the offending file + line.
File organisation#
ml_team/config/
├── agent_defs.py # Python dataclasses (for performance + type-safety)
├── agent_rules/ # YAML — per-agent operational rules
│ ├── ml_director.yaml
│ ├── data_profiler.yaml
│ └── ... (40 files)
├── pipelines/ # YAML — pipeline templates
│ ├── fast_prototype.yaml
│ ├── default_ml_pipeline.yaml
│ └── parallel_research.yaml
├── permission_policies.yaml # operator-authored rules (empty default)
├── permission_policies_hipaa.yaml # compliance-profile policy bundles
├── permission_policies_rbi.yaml
└── algorithm_registry.yaml # 18 curated algorithm templates
Agent definitions live in Python (agent_defs.py) because they include type-checked tool lists. Agent rules live in YAML because they're meant to be operator-editable.
Schema evolution#
- Breaking schema changes only at major version bumps
- Deprecated fields marked in docs + logged at load time for ≥6 months before removal
- Migrate your YAMLs using: