feat: complete V1 with unit tests, integration tests, and pyproject.toml

- 82 tests passing: 7 unit test suites + 1 integration test suite
- Budget, escalation, degrader, finalizer, optimizer, audit core modules tested
- API integration tests using httpx AsyncClient + ASGITransport
- pyproject.toml with ruff, mypy, and pytest configuration
- Fix .github/workflow -> .github/workflows (GitHub Actions requires plural)
- Fix audit singleton isolation in degrader tests via @patch
- Extract _make_state() helper in finalizer tests
- Targeted mypy overrides instead of blanket ignore_missing_imports

Author: nikunjkumar05

.github/workflow/deploy.yml .github/workflows/deploy.yml.github/workflow/deploy.yml renamed to .github/workflows/deploy.yml

@@ -0,0 +1,27 @@
+[project]
+name = "multi-agent"
+version = "0.1.0"
+description = "Budget-aware multi-agent task executor with BAMAS-adapted cost-tier optimizer"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["langchain_*", "langgraph.*", "langsmith.*", "redis.*", "aiosqlite.*", "orjson.*", "scipy.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["ignore::DeprecationWarning"]
+addopts = "--ignore=tests/stress_test.py"

pyproject.toml

@@ -0,0 +1,53 @@
+import pytest
+from httpx import AsyncClient, ASGITransport
+from api.main import app
+
+
+@pytest.mark.anyio
+async def test_health():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        r = await client.get("/health")
+        assert r.status_code == 200
+        assert r.json()["status"] == "ok"
+
+
+@pytest.mark.anyio
+async def test_execute_returns_task_id():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        r = await client.post("/execute", json={"task": "What is 2+2?", "budget_usd": 0.05})
+        assert r.status_code == 200
+        data = r.json()
+        assert "task_id" in data
+        assert data["status"] == "pending"
+
+
+@pytest.mark.anyio
+async def test_get_task_not_found():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        r = await client.get("/tasks/nonexistent-id")
+        assert r.status_code == 404
+
+
+@pytest.mark.anyio
+async def test_get_audit_not_found():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        r = await client.get("/audit/nonexistent-id")
+        assert r.status_code == 404
+
+
+@pytest.mark.anyio
+async def test_execute_with_topology_override():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        r = await client.post("/execute", json={
+            "task": "Write a function",
+            "budget_usd": 0.10,
+            "topology": "pipeline",
+        })
+        assert r.status_code == 200
+        data = r.json()
+        assert "task_id" in data

tests/fixtures/__init__.py

@@ -0,0 +1,73 @@
+import pytest
+from core.audit import AuditTrail, get_audit_trail
+
+
+class TestAuditTrail:
+    def test_record_and_get(self):
+        audit = AuditTrail()
+        audit.record("task-1", "test_event", {"key": "value"})
+        events = audit.get_task_audit("task-1")
+        assert len(events) == 1
+        assert events[0]["event_type"] == "test_event"
+        assert events[0]["detail"]["key"] == "value"
+        assert events[0]["task_id"] == "task-1"
+
+    def test_get_empty_for_unknown_task(self):
+        audit = AuditTrail()
+        assert audit.get_task_audit("nonexistent") == []
+
+    def test_record_topology_decision(self):
+        audit = AuditTrail()
+        audit.record_topology_decision(
+            task_id="t1",
+            topology="pipeline",
+            model_tiers={"planner": "standard"},
+            budget=80.0,
+            rationale="code task",
+            alternatives=[],
+        )
+        events = audit.get_task_audit("t1")
+        assert len(events) == 1
+        assert events[0]["event_type"] == "topology_decision"
+        assert events[0]["detail"]["topology"] == "pipeline"
+
+    def test_record_budget_band(self):
+        audit = AuditTrail()
+        audit.record_budget_band("t2", "tier_downgrade", 25.0, "Downgrading tiers")
+        events = audit.get_task_audit("t2")
+        assert events[0]["event_type"] == "budget_band_crossed"
+        assert events[0]["detail"]["band"] == "tier_downgrade"
+
+    def test_record_degradation(self):
+        audit = AuditTrail()
+        audit.record_degradation("t3", "ensemble", "fanout", "budget low")
+        events = audit.get_task_audit("t3")
+        assert events[0]["event_type"] == "structural_degradation"
+        assert events[0]["detail"]["from_topology"] == "ensemble"
+        assert events[0]["detail"]["to_topology"] == "fanout"
+
+    def test_multiple_tasks_isolated(self):
+        audit = AuditTrail()
+        audit.record("t1", "event_a", {})
+        audit.record("t2", "event_b", {})
+        assert len(audit.get_task_audit("t1")) == 1
+        assert len(audit.get_task_audit("t2")) == 1
+
+    def test_to_json(self):
+        audit = AuditTrail()
+        audit.record("t1", "event", {"key": "val"})
+        json_str = audit.to_json("t1")
+        assert "event" in json_str
+        assert "key" in json_str
+
+    def test_timestamp_present(self):
+        audit = AuditTrail()
+        audit.record("t1", "event", {})
+        assert "timestamp" in audit.get_task_audit("t1")[0]
+
+
+class TestGetAuditTrailSingleton:
+    def test_returns_same_instance(self):
+        a = get_audit_trail()
+        b = get_audit_trail()
+        assert a is b

tests/integration/test_api.py

@@ -0,0 +1,124 @@
+import pytest
+from core.budget import BudgetTracker, BudgetBand
+
+
+class TestBudgetBands:
+    def test_healthy_band_below_70(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.5)
+        assert bt.spent_pct == 50.0
+        assert bt.get_band() == BudgetBand.HEALTHY
+
+    def test_tier_downgrade_band_70_to_90(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.8)
+        assert bt.get_band() == BudgetBand.TIER_DOWNGRADE
+
+    def test_structural_degrade_band_90_to_100(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.95)
+        assert bt.get_band() == BudgetBand.STRUCTURAL_DEGRADE
+
+    def test_critical_band_at_100(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=1.0)
+        assert bt.get_band() == BudgetBand.CRITICAL
+
+    def test_critical_band_over_100(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=1.5)
+        assert bt.get_band() == BudgetBand.CRITICAL
+
+
+class TestCanAffordTier:
+    def test_healthy_affords_all(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.0)
+        assert bt.can_afford_tier("cheap") is True
+        assert bt.can_afford_tier("standard") is True
+        assert bt.can_afford_tier("frontier") is True
+
+    def test_tier_downgrade_no_frontier(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.8)
+        assert bt.can_afford_tier("cheap") is True
+        assert bt.can_afford_tier("standard") is True
+        assert bt.can_afford_tier("frontier") is False
+
+    def test_structural_degrade_only_cheap(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.95)
+        assert bt.can_afford_tier("cheap") is True
+        assert bt.can_afford_tier("standard") is False
+        assert bt.can_afford_tier("frontier") is False
+
+    def test_critical_affords_nothing(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=1.0)
+        assert bt.can_afford_tier("cheap") is False
+        assert bt.can_afford_tier("standard") is False
+        assert bt.can_afford_tier("frontier") is False
+
+
+class TestGetAllowedTiers:
+    def test_healthy_all_tiers(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.0)
+        assert bt.get_allowed_tiers() == ["cheap", "standard", "frontier"]
+
+    def test_tier_downgrade_two_tiers(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.8)
+        assert bt.get_allowed_tiers() == ["cheap", "standard"]
+
+    def test_structural_degrade_one_tier(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.95)
+        assert bt.get_allowed_tiers() == ["cheap"]
+
+    def test_critical_one_tier(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=1.0)
+        assert bt.get_allowed_tiers() == ["cheap"]
+
+
+class TestShouldSkipJudge:
+    def test_healthy_no_skip(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.0)
+        assert bt.should_skip_judge() is False
+
+    def test_tier_downgrade_no_skip(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.8)
+        assert bt.should_skip_judge() is False
+
+    def test_structural_degrade_skip(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.95)
+        assert bt.should_skip_judge() is True
+
+    def test_critical_skip(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=1.0)
+        assert bt.should_skip_judge() is True
+
+
+class TestRecordUsage:
+    def test_record_usage_increments(self):
+        bt = BudgetTracker(max_cost_usd=1.0)
+        bt.record_usage(tokens=100, cost=0.05)
+        assert bt.consumed_tokens == 100
+        assert bt.consumed_cost == 0.05
+
+    def test_record_usage_accumulates(self):
+        bt = BudgetTracker(max_cost_usd=1.0)
+        bt.record_usage(tokens=100, cost=0.05)
+        bt.record_usage(tokens=200, cost=0.10)
+        assert bt.consumed_tokens == 300
+        assert bt.consumed_cost == pytest.approx(0.15)
+
+
+class TestGetDegradedTopology:
+    def test_ensemble_to_fanout(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.0)
+        assert bt.get_degraded_topology("ensemble") == "fanout"
+
+    def test_fanout_to_supervisor(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.0)
+        assert bt.get_degraded_topology("fanout") == "supervisor"
+
+    def test_supervisor_to_pipeline(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.0)
+        assert bt.get_degraded_topology("supervisor") == "pipeline"
+
+    def test_pipeline_to_single(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.0)
+        assert bt.get_degraded_topology("pipeline") == "single"
+
+    def test_single_stays_single(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.0)
+        assert bt.get_degraded_topology("single") == "single"

tests/unit/test_audit.py

@@ -0,0 +1,79 @@
+import pytest
+from unittest.mock import patch
+from core.degrader import degrade_topology, TOPOLOGY_DEGRADATION_CHAIN
+from core.budget import BudgetTracker, BudgetBand
+from core.audit import AuditTrail
+
+
+def _fresh_audit() -> AuditTrail:
+    return AuditTrail()
+
+
+class TestDegradeTopology:
+    def test_healthy_band_returns_same(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.0)
+        result = degrade_topology(bt, "ensemble", "task-1")
+        assert result == "ensemble"
+
+    def test_tier_downgrade_returns_same(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.8)
+        result = degrade_topology(bt, "supervisor", "task-2")
+        assert result == "supervisor"
+
+    def test_structural_degrade_ensemble_to_fanout(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.95)
+        result = degrade_topology(bt, "ensemble", "task-3")
+        assert result == "fanout"
+
+    def test_structural_degrade_fanout_to_supervisor(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.95)
+        result = degrade_topology(bt, "fanout", "task-4")
+        assert result == "supervisor"
+
+    def test_structural_degrade_supervisor_to_pipeline(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.95)
+        result = degrade_topology(bt, "supervisor", "task-5")
+        assert result == "pipeline"
+
+    def test_structural_degrade_pipeline_to_single(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.95)
+        result = degrade_topology(bt, "pipeline", "task-6")
+        assert result == "single"
+
+    def test_structural_degrade_single_stays_single(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.95)
+        result = degrade_topology(bt, "single", "task-7")
+        assert result == "single"
+
+    def test_structural_degrade_unknown_to_single(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.95)
+        result = degrade_topology(bt, "unknown_topology", "task-8")
+        assert result == "single"
+
+    def test_critical_band_returns_single(self):
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=1.0)
+        result = degrade_topology(bt, "ensemble", "task-9")
+        assert result == "single"
+
+    def test_degradation_chain_order(self):
+        assert TOPOLOGY_DEGRADATION_CHAIN == ["ensemble", "fanout", "supervisor", "pipeline", "single"]
+
+    @patch("core.degrader.get_audit_trail")
+    def test_audit_records_on_structural_degrade(self, mock_get_audit):
+        audit = _fresh_audit()
+        mock_get_audit.return_value = audit
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=0.95)
+        degrade_topology(bt, "ensemble", "task-audit-1")
+        events = audit.get_task_audit("task-audit-1")
+        event_types = [e["event_type"] for e in events]
+        assert "budget_band_crossed" in event_types
+        assert "structural_degradation" in event_types
+
+    @patch("core.degrader.get_audit_trail")
+    def test_audit_records_on_critical(self, mock_get_audit):
+        audit = _fresh_audit()
+        mock_get_audit.return_value = audit
+        bt = BudgetTracker(max_cost_usd=1.0, consumed_cost=1.0)
+        degrade_topology(bt, "ensemble", "task-audit-2")
+        events = audit.get_task_audit("task-audit-2")
+        assert any(e["event_type"] == "budget_band_crossed" for e in events)