maestro-loop 0.1.0__py3-none-any.whl

maestro_loop/__init__.py

@@ -0,0 +1,8 @@
+"""Auto-Loop controller for autonomous multi-agent execution."""
+
+from __future__ import annotations
+
+from .controller import AutoLoop, LoopResult
+from .states import LoopState
+
+__all__ = ["AutoLoop", "LoopResult", "LoopState"]

maestro_loop/controller.py

@@ -0,0 +1,584 @@
+"""AutoLoop controller: LLM-driven orchestration for autonomous execution."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+from pydantic_ai import Agent
+from rich.console import Console
+
+from maestro.resilience import async_retry, is_retryable_error  # type: ignore[import-untyped]
+from maestro.streaming import AgentStreamLogger  # type: ignore[import-untyped]
+from maestro_agents.animation import ThinkingAnimation
+from maestro_agents.base import MaestroAgent
+from maestro_agents.contract_validator import validate_contracts
+from maestro_ssot.hub import SSOTHub
+from maestro_ssot.models import ReqStatus
+
+from .retry import RetryBudget
+from .scheduler import LLMScheduler
+from .states import ControllerAction, LoopState
+
+if TYPE_CHECKING:
+    from maestro_harness.harness import Harness
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+class LoopResult(BaseModel):
+    """Result of a complete AutoLoop run."""
+
+    state: LoopState
+    requirement: str
+    iterations: int
+    message: str
+
+
+class LLMController:
+    """LLM-based controller that decides the next action in the loop.
+
+    In test mode (model="test"), falls back to deterministic rule-based
+    decisions so that CI tests pass without requiring a real LLM.
+    """
+
+    def __init__(self, model: str | object, agents: list[MaestroAgent]) -> None:
+        self._is_test = str(model) == "test"
+        if not self._is_test:
+            self._agent = Agent(
+                model,  # type: ignore[arg-type]
+                output_type=ControllerAction,
+                system_prompt=self._system_prompt(),
+            )
+        self._agents = agents
+
+    async def decide(
+        self, prompt: str, timeout: float = 60.0
+    ) -> ControllerAction:
+        """Ask the LLM (or test fallback) to decide the next action.
+
+        Retries transient failures (rate limits, timeouts) with exponential
+        backoff.  Non-retryable errors fail fast.
+        """
+        if self._is_test:
+            return self._test_decide(prompt)
+
+        async def _call() -> ControllerAction:
+            import asyncio
+            coro = self._agent.run(prompt)
+            result = await asyncio.wait_for(coro, timeout=timeout)
+            return result.output
+
+        try:
+            action: ControllerAction = await async_retry(
+                _call,
+                max_retries=2,
+                base_delay=2.0,
+                retryable=(Exception,),
+            )
+            return action
+        except Exception as exc:
+            if is_retryable_error(exc):
+                logger.warning("Controller LLM call failed after retries: %s", exc)
+            else:
+                logger.warning("Controller LLM call failed (non-retryable): %s", exc)
+            # Fail-safe: assume nothing to do
+            return ControllerAction(
+                action="DONE",
+                reasoning=f"Controller failed: {exc}",
+            )
+
+    def _test_decide(self, prompt: str) -> ControllerAction:
+        """Deterministic decision logic for TestModel environments.
+
+        Parses the controller prompt heuristically to infer state and
+        returns the same action a real LLM would choose for the test tasks.
+        """
+        has_pending = "Pending tasks" in prompt
+        has_in_progress = "In-progress tasks" in prompt
+        has_done = "Completed tasks" in prompt
+        is_first = "Iteration: 1 " in prompt
+        all_done = (
+            "Pending:     0" in prompt
+            and "In Progress: 0" in prompt
+            and "Blocked:     0" in prompt
+            and has_done
+        )
+
+        if is_first:
+            return ControllerAction(action="DECOMPOSE", reasoning="Test: first iteration")
+        if has_in_progress:
+            return ControllerAction(action="EXECUTE", reasoning="Test: execute in-progress")
+        if has_pending:
+            return ControllerAction(action="ASSIGN", reasoning="Test: assign pending")
+        if all_done:
+            return ControllerAction(action="DONE", reasoning="Test: all tasks done")
+        if has_done:
+            return ControllerAction(action="VERIFY", reasoning="Test: verify completed")
+        return ControllerAction(action="DONE", reasoning="Test: nothing to do")
+
+    @staticmethod
+    def _system_prompt() -> str:
+        return (
+            "You are the Controller of a multi-agent software engineering system. "
+            "You observe the current state of tasks and decide the single next action. "
+            "Your decision must be one of: DECOMPOSE, ASSIGN, EXECUTE, VERIFY, "
+            "COMMIT, or DONE. Return your decision as structured JSON."
+        )
+
+
+class AutoLoop:
+    """LLM-driven execution loop. The Controller decides each step dynamically.
+
+    Unlike the previous deterministic state machine (PLAN→ASSIGN→EXEC→VALID→...),
+    the Controller observes the full SSOT state and chooses the next action.
+    This allows the loop to skip unnecessary steps (e.g., ANSWER a greeting
+    directly without decomposition) or repeat steps when needed.
+    """
+
+    def __init__(
+        self,
+        hub: SSOTHub,
+        harness: Harness,
+        agents: list[MaestroAgent],
+        max_retries: int = 3,
+        max_iterations: int = 20,
+        model_map: dict[str, Any] | None = None,
+        scheduler_model: str | object = "test",
+        timeout_seconds: float = 600.0,
+    ) -> None:
+        self.hub = hub
+        self.harness = harness
+        self.agents = agents
+        self.scheduler = LLMScheduler(scheduler_model, agents)
+        self.controller = LLMController(scheduler_model, agents)
+        self._test_mode = str(scheduler_model) == "test"
+        self.retry_budget = RetryBudget(max_retries)
+        self.max_iterations = max_iterations
+        self.timeout_seconds = timeout_seconds
+        self.model_map = model_map or {}
+        self.iterations = 0
+        self._history: list[ControllerAction] = []
+        self._planning_agent = self._get_agent_by_role("planner")
+        self._review_agent = self._get_agent_by_role("review")
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def run(self, requirement: str) -> LoopResult:
+        """Execute the autonomous loop until DONE or FAIL."""
+        import asyncio
+
+        self.hub.initialize(requirement)
+        self.iterations = 0
+        self.retry_budget.reset()
+        self._history.clear()
+        start_time = asyncio.get_event_loop().time()
+
+        while True:
+            elapsed = asyncio.get_event_loop().time() - start_time
+            if elapsed > self.timeout_seconds:
+                return LoopResult(
+                    state=LoopState.FAIL,
+                    requirement=requirement,
+                    iterations=self.iterations,
+                    message=f"Global timeout ({self.timeout_seconds}s) exceeded.",
+                )
+            self.iterations += 1
+            if self.iterations > self.max_iterations:
+                return LoopResult(
+                    state=LoopState.FAIL,
+                    requirement=requirement,
+                    iterations=self.iterations,
+                    message=f"Max iterations ({self.max_iterations}) exceeded.",
+                )
+
+            # Shortcut: if all non-root requirements are DONE, finish immediately
+            all_reqs = self.hub.list_all_requirements()
+            non_root = [r for r in all_reqs if r.parent_id is not None]
+            if non_root and all(r.status == ReqStatus.DONE for r in non_root):
+                return LoopResult(
+                    state=LoopState.DONE,
+                    requirement=requirement,
+                    iterations=self.iterations,
+                    message="All requirements completed.",
+                )
+
+            prompt = self._build_controller_prompt(requirement)
+            ctrl_anim = ThinkingAnimation(
+                "[bold blue]controller[/] deciding",
+                console=console,
+            )
+            ctrl_anim.start()
+            action = await self.controller.decide(prompt)
+            ctrl_anim.stop()
+            console.print(f"[dim]→ {action.action}: {action.reasoning}[/]")
+            self._history.append(action)
+
+            logger.info(
+                "Iteration %d: action=%s reason=%s",
+                self.iterations,
+                action.action,
+                action.reasoning,
+            )
+
+            match action.action:
+                case "DECOMPOSE":
+                    had_pending = await self._do_plan()
+                    if not had_pending:
+                        logger.info("Planner produced no sub-tasks (likely trivial)")
+
+                case "ASSIGN":
+                    await self._do_assign()
+
+                case "EXECUTE":
+                    await self._do_exec()
+
+                case "VERIFY":
+                    ok, reasons = await self._do_valid()
+                    if not ok:
+                        logger.info("Validation failed: %s", reasons)
+                        self._rollback()
+                        if self.retry_budget.exhausted:
+                            return LoopResult(
+                                state=LoopState.FAIL,
+                                requirement=requirement,
+                                iterations=self.iterations,
+                                message=(
+                                    f"Validation failed after {self.retry_budget.max_retries} "
+                                    f"retries: {reasons}"
+                                ),
+                            )
+                        self.retry_budget.consume()
+
+                case "COMMIT":
+                    self._do_commit()
+
+                case "DONE":
+                    all_reqs = self.hub.list_all_requirements()
+                    non_root = [r for r in all_reqs if r.parent_id is not None]
+                    if not non_root or all(r.status == ReqStatus.DONE for r in non_root):
+                        return LoopResult(
+                            state=LoopState.DONE,
+                            requirement=requirement,
+                            iterations=self.iterations,
+                            message="All requirements completed.",
+                        )
+                    logger.warning("Controller chose DONE but tasks remain pending")
+
+                case _:
+                    return LoopResult(
+                        state=LoopState.FAIL,
+                        requirement=requirement,
+                        iterations=self.iterations,
+                        message=f"Unknown controller action: {action.action}",
+                    )
+
+    # ------------------------------------------------------------------
+    # Action handlers (do the work, do NOT set state — Controller decides next step)
+    # ------------------------------------------------------------------
+
+    async def _do_plan(self) -> bool:
+        """Invoke PlanningAgent to decompose the current requirement tree.
+
+        Returns True if at least one PENDING requirement was created.
+        """
+        if self._planning_agent is not None:
+            all_reqs = self.hub.list_all_requirements()
+            root = next((r for r in all_reqs if r.parent_id is None), None)
+            root_id = root.id if root else "unknown"
+            existing = [r for r in all_reqs if r.parent_id is not None]
+            agent_list = ", ".join(f"{a.role}({a.agent_id})" for a in self.agents)
+
+            prompt = (
+                f"Decompose the requirement into actionable sub-tasks.\n\n"
+                f"Root requirement ID (use this as parent_id for ALL sub-tasks): {root_id}\n"
+                f"Available agents in the team: {agent_list}\n"
+            )
+            if existing:
+                prompt += (
+                    f"Existing sub-requirements ({len(existing)}): "
+                    f"do NOT create duplicates.\n"
+                )
+            prompt += (
+                "Use the SSOT tools to add requirements and register contracts. "
+                "Remember: every sub-task MUST have a parent_id."
+            )
+            try:
+                sl = AgentStreamLogger()
+                result = await sl.run(
+                    self._planning_agent,
+                    prompt,
+                    model=self._model_for("planner"),
+                )
+                if not result.success:
+                    logger.warning("PlanningAgent error: %s", result.error)
+            except Exception as exc:
+                logger.warning("PlanningAgent exception: %s", exc)
+
+        all_reqs = self.hub.list_all_requirements()
+        return any(r.status == ReqStatus.PENDING for r in all_reqs)
+
+    async def _do_assign(self) -> bool:
+        """Claim pending requirements for the best-matching agents.
+
+        Returns True if at least one task was assigned.
+        """
+        pending = self.hub.list_pending()
+        assigned_any = False
+
+        for task in pending:
+            # Skip root requirement (parent_id is None) — only sub-tasks get assigned
+            if task.parent_id is None:
+                continue
+            if task.dependencies:
+                deps_done = all(
+                    (d := self.hub.get_requirement(dep_id)) is not None
+                    and d.status == ReqStatus.DONE
+                    for dep_id in task.dependencies
+                )
+                if not deps_done:
+                    continue
+
+            agent = await self.scheduler.select_best_agent(task, self.agents)
+            if agent is None:
+                continue
+            # Planner should only decompose, not execute sub-tasks
+            if agent.role == "planner":
+                continue
+
+            try:
+                self.hub.claim_requirement(task.id, agent.agent_id)
+                assigned_any = True
+            except ValueError as exc:
+                logger.debug("Could not claim %s: %s", task.id, exc)
+
+        return assigned_any
+
+    async def _do_exec(self) -> None:
+        """Run each claimed agent to implement its requirement."""
+        in_progress = self.hub.list_in_progress()
+
+        for task in in_progress:
+            agent = self._get_agent_by_id(task.assignee)
+            if agent is None:
+                logger.warning(
+                    "Agent %s not found, unclaiming %s for reassignment",
+                    task.assignee,
+                    task.id,
+                )
+                self.hub.update_requirement_status(
+                    task.id, ReqStatus.PENDING, task.assignee or "system"
+                )
+                continue
+
+            prompt = (
+                f"Requirement ID: {task.id}\n"
+                f"Implement this requirement: {task.description}\n\n"
+                "Use the SSOT tools to read contracts, write code via the harness, "
+                "and update the requirement status to DONE when complete. "
+                f"Call ssot_update_requirement_status with node_id='{task.id}' and status='DONE'."
+            )
+            try:
+                sl = AgentStreamLogger()
+                result = await sl.run(
+                    agent,
+                    prompt,
+                    model=self._model_for(agent.role),
+                )
+                console.print(f"[dim]Agent {agent.agent_id} output: {result.output[:200]}[/]")
+                if not result.success:
+                    logger.warning("Agent %s error: %s", agent.agent_id, result.error)
+            except Exception as exc:
+                logger.warning("Agent %s exception: %s", agent.agent_id, exc)
+
+    async def _do_valid(self) -> tuple[bool, list[str]]:
+        """Validate contracts, run tests, and invoke ReviewAgent.
+
+        Returns (all_passed, list_of_failure_reasons).
+        """
+        reasons: list[str] = []
+
+        contract_result = validate_contracts(self.hub)
+        if not contract_result.valid:
+            for v in contract_result.violations:
+                reasons.append(f"Contract violation: {v.message}")
+
+        if self._review_agent is not None:
+            try:
+                sl = AgentStreamLogger()
+                review_result = await sl.run(
+                    self._review_agent,
+                    "Review the latest code changes and contracts for quality issues.",
+                    model=self._model_for("review"),
+                )
+                if not review_result.success:
+                    reasons.append(f"Review failed: {review_result.error}")
+            except Exception as exc:
+                reasons.append(f"Review exception: {exc}")
+
+        if not self._run_tests():
+            reasons.append("Tests failed")
+
+        return len(reasons) == 0, reasons
+
+    def _do_commit(self) -> None:
+        """Tag a clean SSOT snapshot and clear the harness rollback point."""
+        self.hub.create_snapshot(f"Iteration {self.iterations} commit")
+        if hasattr(self.harness, "clear_snapshot"):
+            self.harness.clear_snapshot()
+        self.retry_budget.reset()
+
+    # ------------------------------------------------------------------
+    # Controller prompt builder
+    # ------------------------------------------------------------------
+
+    def _build_controller_prompt(self, requirement: str) -> str:
+        """Build a rich state snapshot for the LLM Controller."""
+        all_reqs = self.hub.list_all_requirements()
+
+        pending = [r for r in all_reqs if r.status == ReqStatus.PENDING]
+        in_progress = [r for r in all_reqs if r.status == ReqStatus.IN_PROGRESS]
+        done = [r for r in all_reqs if r.status == ReqStatus.DONE]
+        blocked = [r for r in all_reqs if r.status == ReqStatus.BLOCKED]
+
+        lines = [
+            f"Original requirement: {requirement}",
+            "",
+            f"Iteration: {self.iterations} / {self.max_iterations}",
+            f"Retry budget remaining: {self.retry_budget.remaining}",
+            "",
+            "## Current Task State",
+            f"  Pending:     {len(pending)}",
+            f"  In Progress: {len(in_progress)}",
+            f"  Done:        {len(done)}",
+            f"  Blocked:     {len(blocked)}",
+            "",
+        ]
+
+        if pending:
+            lines.append("### Pending tasks")
+            for r in pending:
+                deps = (
+                    f" (depends on: {', '.join(r.dependencies)})"
+                    if r.dependencies
+                    else ""
+                )
+                lines.append(f"  - [{r.id[:8]}] {r.description}{deps}")
+            lines.append("")
+
+        if in_progress:
+            lines.append("### In-progress tasks")
+            for r in in_progress:
+                lines.append(
+                    f"  - [{r.id[:8]}] {r.description} (assigned to {r.assignee})"
+                )
+            lines.append("")
+
+        if done:
+            lines.append("### Completed tasks")
+            for r in done:
+                lines.append(f"  - [{r.id[:8]}] {r.description}")
+            lines.append("")
+
+        if self._history:
+            lines.append("### Recent actions")
+            for h in self._history[-5:]:
+                lines.append(f"  - {h.action}: {h.reasoning}")
+            lines.append("")
+
+        lines.append("### Available agents")
+        for a in self.agents:
+            lines.append(f"  - {a.role} ({a.agent_id})")
+        lines.append("")
+
+        lines.extend(
+            [
+                "## Instruction",
+                "You are the Controller. Based on the current state, choose the next action.",
+                "",
+                "Available actions:",
+                "  DECOMPOSE — Use the planner to break requirements into sub-tasks.",
+                "  ASSIGN    — Assign pending tasks to suitable agents.",
+                "  EXECUTE   — Run claimed agents on their in-progress tasks.",
+                "  VERIFY    — Validate contracts, tests, and code quality.",
+                "  COMMIT    — Save a snapshot of the current successful state.",
+                "  DONE      — All work is complete. Finish the loop.",
+                "",
+                "Guidelines:",
+                "- If there are pending tasks that need decomposition, choose DECOMPOSE."
+                "- If there are pending tasks ready to work on, choose ASSIGN.",
+                "- If there are in-progress tasks, choose EXECUTE.",
+                "- After execution, choose VERIFY to validate.",
+                "- If validation passes, choose COMMIT then DONE.",
+                "- If retry budget is 0 and problems remain, choose DONE anyway.",
+            ]
+        )
+
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _model_for(self, role: str) -> Any | None:
+        """Return the model override for a given role, if any."""
+        return self.model_map.get(role)
+
+    def _get_agent_by_role(self, role: str) -> MaestroAgent | None:
+        for agent in self.agents:
+            if agent.role == role:
+                return agent
+        return None
+
+    def _get_agent_by_id(self, agent_id: str | None) -> MaestroAgent | None:
+        if agent_id is None:
+            return None
+        for agent in self.agents:
+            if agent.agent_id == agent_id:
+                return agent
+        return None
+
+    def _rollback(self) -> None:
+        """Rollback code changes via harness and reset SSOT task statuses."""
+        if hasattr(self.harness, "rollback"):
+            self.harness.rollback()
+
+        from contextlib import suppress
+
+        for task in self.hub.list_in_progress():
+            with suppress(ValueError):
+                self.hub.update_requirement_status(
+                    task.id, ReqStatus.PENDING, task.assignee or "system"
+                )
+
+    def _run_tests(self) -> bool:
+        """Run test commands through the harness if a test agent is configured.
+
+        Returns True if tests pass or no test agent exists.
+        """
+        test_agent = self._get_agent_by_role("test")
+        if test_agent is None:
+            return True
+
+        policy = self.harness.get_agent_policy(test_agent.agent_id)
+        if policy is None:
+            return True
+
+        allowed = policy.commands.allow
+        if any("pytest" in cmd for cmd in allowed):
+            from maestro_harness.validator import Action
+
+            action = Action(
+                agent_id=test_agent.agent_id,
+                action_type="COMMAND",
+                target=".",
+                command="pytest",
+            )
+            result = self.harness.execute_action(test_agent.agent_id, action)
+            return result.exit_code == 0
+
+        return True

maestro_loop/retry.py

@@ -0,0 +1,36 @@
+"""Retry budget manager for the Auto-Loop controller."""
+
+from __future__ import annotations
+
+
+class RetryBudget:
+    """Tracks global retry attempts across planning epochs.
+
+    The loop is allowed ``max_retries`` full-cycle retries before
+    declaring failure and escalating to a human supervisor.
+    """
+
+    def __init__(self, max_retries: int = 3) -> None:
+        self.max_retries = max_retries
+        self._attempts = 0
+
+    def consume(self) -> bool:
+        """Consume one retry attempt. Returns True if budget remains."""
+        if self._attempts >= self.max_retries:
+            return False
+        self._attempts += 1
+        return True
+
+    @property
+    def exhausted(self) -> bool:
+        """True when no retries remain."""
+        return self._attempts >= self.max_retries
+
+    @property
+    def remaining(self) -> int:
+        """Number of retries still available."""
+        return max(0, self.max_retries - self._attempts)
+
+    def reset(self) -> None:
+        """Reset budget (used when a clean COMMIT succeeds)."""
+        self._attempts = 0

maestro_loop/scheduler.py

@@ -0,0 +1,98 @@
+"""LLM-powered agent-task scheduler for the Auto-Loop controller."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+from pydantic_ai import Agent
+
+from maestro_agents.base import MaestroAgent
+from maestro_ssot.models import RequirementNode
+
+
+class ScheduleDecision(BaseModel):
+    """Structured output from the scheduling LLM."""
+
+    selected_role: str = Field(description="Role of the best agent for this task")
+    reason: str = Field(description="Why this agent is the best fit")
+    confidence: float = Field(ge=0.0, le=1.0, description="Confidence score (0-1)")
+
+
+class LLMScheduler:
+    """LLM-based scheduler that selects the best agent for a task.
+
+    Uses a lightweight PydanticAI agent with structured output to evaluate
+    task descriptions semantically and pick the most suitable role.
+    """
+
+    def __init__(self, model: str | object, agents: list[MaestroAgent]) -> None:
+        self._agent = Agent(
+            model,  # type: ignore[arg-type]
+            output_type=ScheduleDecision,
+            system_prompt=self._system_prompt(),
+        )
+        self._agents = agents
+
+    async def select_best_agent(
+        self, task: RequirementNode, agents: list[MaestroAgent]
+    ) -> MaestroAgent | None:
+        """Return the agent whose role best matches the task description."""
+        if not agents:
+            return None
+
+        prompt = self._build_prompt(task, agents)
+        result = await self._agent.run(prompt)
+        decision: ScheduleDecision = result.output
+
+        for agent in agents:
+            if agent.role == decision.selected_role:
+                return agent
+
+        # Fallback: if LLM returns an unknown role, pick first non-planner/review
+        for agent in agents:
+            if agent.role not in ("planner", "review"):
+                return agent
+
+        return None
+
+    @staticmethod
+    def _system_prompt() -> str:
+        return (
+            "You are a task scheduler for a multi-agent software engineering team. "
+            "Your job is to read a task description and pick exactly one agent role "
+            "that is best suited to execute it. Return your decision as structured JSON."
+        )
+
+    @staticmethod
+    def _build_prompt(task: RequirementNode, agents: list[MaestroAgent]) -> str:
+        lines = [
+            "## Task",
+            f"Description: {task.description}",
+        ]
+        if task.acceptance_criteria:
+            lines.append("Acceptance criteria:")
+            for ac in task.acceptance_criteria:
+                lines.append(f"  - {ac}")
+
+        lines.extend(["", "## Available Agents"])
+        for agent in agents:
+            lines.append(f"- role: {agent.role}")
+            # Try to show a short excerpt of the system prompt if available
+            prompt_excerpt = ""
+            if hasattr(agent, "system_prompt"):
+                sp = agent.system_prompt()
+                if sp:
+                    prompt_excerpt = sp[:120].replace("\n", " ")
+            if prompt_excerpt:
+                lines.append(f"  prompt: {prompt_excerpt}...")
+
+        lines.extend(
+            [
+                "",
+                "## Instruction",
+                "Pick the single best agent role for this task.",
+                "Consider the full semantic meaning, not just keyword matching.",
+                "If a task involves both API logic and UI (e.g. 'login page with JWT'), "
+                "favor the agent that owns the core business logic.",
+            ]
+        )
+        return "\n".join(lines)

maestro_loop/states.py

@@ -0,0 +1,48 @@
+"""LoopState enumeration and Controller action model for the Auto-Loop."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class LoopState(StrEnum):
+    """Deterministic states of the autonomous execution loop."""
+
+    PLAN = "PLAN"
+    ASSIGN = "ASSIGN"
+    EXEC = "EXEC"
+    VALID = "VALID"
+    COMMIT = "COMMIT"
+    CHECK = "CHECK"
+    DONE = "DONE"
+    FAIL = "FAIL"
+
+
+TERMINAL_STATES = {LoopState.DONE, LoopState.FAIL}
+
+
+class ControllerAction(BaseModel):
+    """Structured output from the LLM Controller.
+
+    The Controller observes the current SSOT state and decides the next
+    action, rather than following a hard-coded state machine transition.
+    """
+
+    action: Literal["DECOMPOSE", "ASSIGN", "EXECUTE", "VERIFY", "COMMIT", "DONE"] = Field(
+        description="The next action to take in the execution loop"
+    )
+    target_requirement_id: str | None = Field(
+        default=None,
+        description="ID of the requirement to target (for ASSIGN / EXECUTE)",
+    )
+    agent_role: str | None = Field(
+        default=None,
+        description="Role of the agent to use (for ASSIGN / EXECUTE)",
+    )
+
+    reasoning: str = Field(
+        description="Why this action was chosen"
+    )

maestro_loop-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: maestro-loop
+Version: 0.1.0
+Summary: Auto-Loop Controller: deterministic state machine for autonomous execution
+Requires-Python: >=3.12
+Requires-Dist: maestro-agents
+Requires-Dist: maestro-harness
+Requires-Dist: maestro-ssot
+Requires-Dist: pydantic-ai>=0.5
+Requires-Dist: pydantic>=2.10

maestro_loop-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+maestro_loop/__init__.py,sha256=yIqDkpGjng1NQTR5mDzf9mjg11f2zFaGnJTfqhVyaUA,228
+maestro_loop/controller.py,sha256=C6hnaSrsphfq6K41T-FlOe1PDbxFmjQtN53cR53nXbg,22884
+maestro_loop/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+maestro_loop/retry.py,sha256=Ix9SdHMMBApR0_rapl-71t05Puizij6LGuiLIeBm5ag,1070
+maestro_loop/scheduler.py,sha256=4EizHaUKXL5xFGXaoTgHj8JdgR7RIArkPTnELzfzL5s,3536
+maestro_loop/states.py,sha256=967kdRnZbOydabx__TKH2vtxXbtF24X8HAoCRtYM6p8,1285
+maestro_loop-0.1.0.dist-info/METADATA,sha256=loMnlj_Vp6YkyRC2Bm9Z2k0zF2boJN5K0LDB3elK8qY,315
+maestro_loop-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+maestro_loop-0.1.0.dist-info/RECORD,,

maestro_loop-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any