Skip to content

Getting started

Requirements

  • Python 3.12+ (3.13 also tested)
  • Git (for setup_hooks.py and the pre-commit gate)
  • Make (optional, for convenience targets) — Windows users can call the python commands directly

Install

# 1. Clone
git clone https://github.com/claudinoinsights/mult-agentes.git
cd mult-agentes

# 2. Virtualenv
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# 3. Install with all extras
pip install -e ".[dev,test,docs]"

# 4. Wire the pre-commit gate
python scripts/setup_hooks.py
pre-commit install                  # optional, also installs the pre-commit framework hooks

Verify

make audit       # all 5 audits + drift detection (should report CLEAN)
make test        # pytest unit + smoke (46 tests)
make smoke       # end-to-end smoke only (13 modules)
make typecheck   # mypy (strict on src.pipeline + src.privacy)
make lint        # ruff check + format-check

If everything is green, your tree is healthy. Any make target above must pass before sending a PR.

First pipeline run

from datetime import datetime, timedelta, timezone
from src.pipeline import (
    AgentRef, BudgetTracker, Capsule, Constraints, ExpectedOutput,
    LockManager, PipelineOrchestrator, TaskSpec, VerificationAgent,
)

deadline = (datetime.now(timezone.utc) + timedelta(hours=2)).isoformat()

capsule = Capsule.new(
    from_agent=AgentRef(id="cortex", layer=1),
    to_agent=AgentRef(id="code-writer", layer=5),
    task=TaskSpec(
        story_id="STORY-001",
        description="Implement a sum(a, b) function with tests.",
        intent_class="build_feature",
        acceptance_criteria=[
            "function returns a+b",
            "tests cover positives, negatives, zero",
            "type hints present",
            "module exports the function",
            "passes lint",
        ],
    ),
    constraints=Constraints(
        budget_tokens=50_000,
        budget_dollars=2.0,
        deadline=deadline,
    ),
    expected_output=ExpectedOutput(type="code"),
    metadata={"project_profile": "startup"},
)

orch = PipelineOrchestrator(
    budget=BudgetTracker(
        capsule_id=capsule.capsule_id,
        limit_tokens=50_000,
        limit_dollars=2.0,
    ),
    locks=LockManager(),
    verifier=VerificationAgent(),
)

result = orch.run(capsule)
print(f"success={result.success}  cycles_used={result.cycles_used}")
for p in result.phases:
    print(f"  {p.phase.name:18s}  success={p.success}  reason={p.halt_reason}")

You'll see all 7 phases execute against the mock executor. To wire a real LLM, inject an executor callable into orch.run().

Next steps