loopengt 0.1.0__py3-none-any.whl

loopengt/core/runtime/executor.py

@@ -0,0 +1,463 @@
+"""Main loop executor — the core orchestration engine.
+
+Implements the **supervisor orchestration pattern**: reads a ``LoopSpec``,
+initialises agent and step states, and drives steps to completion by
+selecting the next agent/tool at each turn.
+
+Patterns supported:
+  - Sequential — steps execute in declaration order.
+  - Supervisor-Worker — a supervisor agent decides which worker to invoke.
+  - Parallel Fan-out — independent steps execute concurrently.
+  - Handoff — agents pass context to the next agent directly.
+  - Evaluator-Optimizer — an evaluator agent reviews, an optimizer refines.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import anyio
+import structlog
+
+from loopengt.core.models.loop_spec import LoopPattern, LoopSpec, StepSpec
+from loopengt.core.models.policy import RetryPolicy
+from loopengt.core.models.state import (
+    AgentState,
+    LoopState,
+    RunStatus,
+    StepResult,
+    StepState,
+    StepStatus,
+)
+
+logger = structlog.get_logger(__name__)
+
+
+class ExecutionError(Exception):
+    """Raised when a loop execution cannot proceed."""
+
+
+class LoopExecutor:
+    """Async-first loop executor.
+
+    Usage::
+
+        executor = LoopExecutor(spec)
+        final_state = await executor.execute()
+    """
+
+    def __init__(self, spec: LoopSpec) -> None:
+        self._spec = spec
+        self._state = self._init_state()
+        self._log = logger.bind(loop=spec.name)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def execute(self) -> LoopState:
+        """Run the loop to completion and return the final state."""
+        self._log.info("loop.start", pattern=self._spec.pattern)
+        self._state.mark_running()
+
+        try:
+            if self._spec.pattern == LoopPattern.SEQUENTIAL:
+                await self._run_sequential()
+            elif self._spec.pattern == LoopPattern.SUPERVISOR_WORKER:
+                await self._run_supervisor_worker()
+            elif self._spec.pattern == LoopPattern.PARALLEL_FAN_OUT:
+                await self._run_parallel_fan_out()
+            elif self._spec.pattern == LoopPattern.HANDOFF:
+                await self._run_handoff()
+            elif self._spec.pattern == LoopPattern.EVALUATOR_OPTIMIZER:
+                await self._run_evaluator_optimizer()
+            else:
+                # CUSTOM or unknown — fall back to sequential
+                self._log.warning(
+                    "loop.unknown_pattern",
+                    pattern=self._spec.pattern,
+                    fallback="sequential",
+                )
+                await self._run_sequential()
+
+            self._state.mark_completed()
+            self._log.info("loop.completed", run_id=self._state.run_id)
+
+        except ExecutionError as exc:
+            self._state.mark_failed(str(exc))
+            self._log.error("loop.failed", error=str(exc))
+        except Exception as exc:  # noqa: BLE001
+            self._state.mark_failed(f"Unexpected error: {exc}")
+            self._log.error("loop.unexpected_error", error=str(exc))
+
+        return self._state
+
+    async def resume(self, checkpoint_id: str | None = None) -> LoopState:
+        """Resume a paused or failed loop from a checkpoint.
+
+        If *checkpoint_id* is ``None``, resumes from the last checkpoint.
+        """
+        self._log.info("loop.resume", checkpoint_id=checkpoint_id)
+        # For now, re-run from the current step index
+        self._state.status = RunStatus.RUNNING
+        try:
+            await self._run_sequential(start_index=self._state.current_step_index)
+            self._state.mark_completed()
+        except ExecutionError as exc:
+            self._state.mark_failed(str(exc))
+        return self._state
+
+    # ------------------------------------------------------------------
+    # Pattern implementations
+    # ------------------------------------------------------------------
+
+    async def _run_sequential(self, *, start_index: int = 0) -> None:
+        """Execute steps in declaration order."""
+        steps = self._spec.steps[start_index:]
+        for i, step in enumerate(steps, start=start_index):
+            if self._should_stop():
+                self._log.info("loop.stop_condition_met", turn=self._state.turn)
+                break
+            self._state.current_step_index = i
+            await self._execute_step(step)
+
+    async def _run_supervisor_worker(self) -> None:
+        """Supervisor decides which worker step to run next."""
+        # The first agent acts as the supervisor
+        supervisor_step = self._spec.steps[0]
+        worker_steps = self._spec.steps[1:]
+
+        while not self._should_stop():
+            # Run supervisor to decide next action
+            result = await self._execute_step(supervisor_step)
+            if result is None:
+                break
+
+            # Determine which worker to invoke from supervisor output
+            next_worker = self._select_worker(result, worker_steps)
+            if next_worker is None:
+                self._log.info("supervisor.no_more_workers")
+                break
+
+            await self._execute_step(next_worker)
+
+    async def _run_parallel_fan_out(self) -> None:
+        """Execute independent steps concurrently using the StepScheduler."""
+        from loopengt.core.runtime.scheduler import StepScheduler
+        scheduler = StepScheduler(self._spec, self._state)
+        
+        async def _execute_single_step(step: StepSpec) -> None:
+            if not self._should_stop():
+                await self._execute_step(step)
+                
+        await scheduler.run_parallel(
+            _execute_single_step,
+            max_concurrency=self._spec.policy.max_concurrency,
+        )
+
+    async def _run_handoff(self) -> None:
+        """Steps hand off context to the next step in sequence using HandoffManager."""
+        from loopengt.core.runtime.handoff import HandoffManager
+        manager = HandoffManager([agent.name for agent in self._spec.agents])
+        
+        handoff_ctx = None
+        for i, step in enumerate(self._spec.steps):
+            if self._should_stop():
+                break
+            self._state.current_step_index = i
+            
+            # Inject handoff context into state context if available
+            if handoff_ctx:
+                self._state.context["_handoff"] = handoff_ctx.model_dump()
+                
+            result = await self._execute_step(step)
+            
+            # Create handoff payload for the next agent
+            if result is not None and i + 1 < len(self._spec.steps):
+                next_step = self._spec.steps[i + 1]
+                handoff_ctx = manager.create_handoff(
+                    from_agent=step.agent,
+                    to_agent=next_step.agent,
+                    payload={"output": result} if isinstance(result, dict) else {"output": result}
+                )
+                manager.complete_handoff(handoff_ctx)
+
+    async def _run_evaluator_optimizer(self) -> None:
+        """Alternate between an evaluator and an optimizer agent."""
+        if len(self._spec.steps) < 2:
+            raise ExecutionError(
+                "evaluator_optimizer pattern requires at least 2 steps"
+            )
+
+        evaluator_step = self._spec.steps[0]
+        optimizer_step = self._spec.steps[1]
+
+        while not self._should_stop():
+            # Evaluate
+            eval_result = await self._execute_step(evaluator_step)
+            if eval_result is None:
+                break
+
+            # Check if quality is sufficient
+            if self._quality_met(eval_result):
+                self._log.info("evaluator_optimizer.quality_met")
+                break
+
+            # Optimize
+            self._state.context["_evaluation"] = eval_result
+            await self._execute_step(optimizer_step)
+
+    # ------------------------------------------------------------------
+    # Step execution
+    # ------------------------------------------------------------------
+
+    async def _execute_step(self, step: StepSpec) -> Any:
+        """Execute a single step with retry logic."""
+        step_state = self._state.step_states[step.name]
+        retry_policy = self._spec.policy.retry
+        agent = self._spec.get_agent(step.agent)
+
+        if agent is None:
+            step_state.mark_failed(f"Agent not found: {step.agent}")
+            if self._spec.policy.fail_fast:
+                raise ExecutionError(f"Agent not found: {step.agent}")
+            return None
+
+        agent_state = self._state.agent_states.get(step.agent)
+        self._state.increment_turn()
+
+        max_attempts = retry_policy.max_retries + 1 if step.allow_retry else 1
+
+        for attempt in range(max_attempts):
+            step_state.mark_running()
+            self._log.info(
+                "step.start",
+                step=step.name,
+                agent=step.agent,
+                attempt=attempt + 1,
+            )
+
+            start_time = time.monotonic()
+
+            try:
+                # Build the prompt from template + context
+                prompt = self._render_prompt(step)
+
+                # Execute the agent (stub — calls the agent's LLM or function)
+                output = await self._invoke_agent(step, prompt)
+
+                duration = time.monotonic() - start_time
+                result = StepResult(
+                    output=output,
+                    duration_seconds=duration,
+                )
+
+                step_state.mark_completed(result)
+                if agent_state:
+                    agent_state.record_invocation()
+                    agent_state.last_output = output
+
+                self._state.add_to_history(step.name, output)
+                self._log.info(
+                    "step.completed",
+                    step=step.name,
+                    duration=f"{duration:.2f}s",
+                )
+
+                return output
+
+            except Exception as exc:  # noqa: BLE001
+                duration = time.monotonic() - start_time
+                self._log.warning(
+                    "step.error",
+                    step=step.name,
+                    attempt=attempt + 1,
+                    error=str(exc),
+                )
+
+                if agent_state:
+                    agent_state.record_invocation(error=True)
+
+                if attempt < max_attempts - 1:
+                    step_state.mark_retrying()
+                    delay = retry_policy.compute_delay(attempt)
+                    self._log.info("step.retry", delay=delay)
+                    await anyio.sleep(delay)
+                else:
+                    step_state.mark_failed(str(exc))
+                    if self._spec.policy.fail_fast:
+                        raise ExecutionError(
+                            f"Step '{step.name}' failed after "
+                            f"{max_attempts} attempts: {exc}"
+                        ) from exc
+
+        return None
+
+    async def _invoke_agent(self, step: StepSpec, prompt: str) -> Any:
+        """Invoke an agent for a step.
+
+        Uses the openai client (if available) to call the configured
+        LLM provider. Falls back to a stub if the dependency is missing.
+        """
+        agent = self._spec.get_agent(step.agent)
+        agent_name = agent.name if agent else step.agent
+
+        try:
+            import os
+            from openai import AsyncOpenAI
+        except ImportError:
+            self._log.warning("openai_not_installed", fallback="stub")
+            return {
+                "agent": agent_name,
+                "step": step.name,
+                "prompt_length": len(prompt),
+                "response": f"[stub] {agent_name} completed step '{step.name}' (install loopengt[llm] for real execution)",
+                "status": "ok",
+            }
+
+        provider_env = os.environ.get("LOOPENGT_LLM_PROVIDER", "openai").lower()
+        provider = agent.config.provider.lower() if agent and agent.config.provider else provider_env
+
+        if provider == "huggingface":
+            api_key = os.environ.get("HF_TOKEN")
+            base_url = "https://api-inference.huggingface.co/v1/"
+        else:
+            api_key = os.environ.get("OPENAI_API_KEY")
+            base_url = None
+
+        if not api_key:
+            raise ExecutionError(f"API key missing for provider '{provider}'. Please set OPENAI_API_KEY or HF_TOKEN.")
+
+        client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+
+        model = agent.config.model if agent else "gpt-4o"
+        system_prompt = agent.system_prompt if agent else "You are a helpful assistant."
+        temperature = agent.config.temperature if agent else 0.7
+        max_tokens = agent.config.max_tokens if agent else None
+
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": prompt},
+            ],
+            "temperature": temperature,
+        }
+        if max_tokens is not None:
+            kwargs["max_tokens"] = max_tokens
+
+        try:
+            response = await client.chat.completions.create(**kwargs)
+            content = response.choices[0].message.content
+            return {
+                "agent": agent_name,
+                "step": step.name,
+                "prompt_length": len(prompt),
+                "response": content,
+                "status": "ok",
+            }
+        except Exception as e:
+            raise ExecutionError(f"LLM request failed: {e}") from e
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _init_state(self) -> LoopState:
+        """Build the initial LoopState from the spec."""
+        state = LoopState(loop_name=self._spec.name)
+        state.context = dict(self._spec.context)
+
+        # Initialise step states
+        for step in self._spec.steps:
+            state.step_states[step.name] = StepState(step_name=step.name)
+
+        # Initialise agent states
+        for agent in self._spec.agents:
+            state.agent_states[agent.name] = AgentState(agent_name=agent.name)
+
+        return state
+
+    def _render_prompt(self, step: StepSpec) -> str:
+        """Render a step's prompt template against the current context."""
+        template = step.prompt_template or step.description
+        try:
+            return template.format(**self._state.context)
+        except KeyError:
+            # Template has placeholders not yet in context — return raw
+            return template
+
+    def _should_stop(self) -> bool:
+        """Evaluate stop conditions."""
+        # Check turn limit
+        if self._state.turn >= self._spec.policy.max_turns:
+            return True
+
+        # Check explicit stop conditions
+        for cond in self._spec.stop_conditions:
+            if cond.condition_type.value == "max_turns":
+                if isinstance(cond.value, int) and self._state.turn >= cond.value:
+                    return True
+
+        return False
+
+    def _select_worker(
+        self, supervisor_output: Any, workers: list[StepSpec]
+    ) -> StepSpec | None:
+        """Select the next worker step based on supervisor output."""
+        import json
+        if isinstance(supervisor_output, str):
+            try:
+                # Naive JSON extraction (strip markdown blocks if any)
+                content = supervisor_output.strip()
+                if content.startswith("```json"):
+                    content = content[7:-3].strip()
+                supervisor_output = json.loads(content)
+            except json.JSONDecodeError:
+                pass
+
+        if isinstance(supervisor_output, dict):
+            next_name = supervisor_output.get("next_step") or supervisor_output.get(
+                "next_worker"
+            )
+            if next_name:
+                for w in workers:
+                    if w.name == next_name:
+                        return w
+
+        # Default: pick the first unexecuted worker
+        for w in workers:
+            step_state = self._state.step_states.get(w.name)
+            if step_state and step_state.status == StepStatus.PENDING:
+                return w
+
+        return None
+
+    def _quality_met(self, eval_result: Any) -> bool:
+        """Check if the evaluator's result indicates sufficient quality."""
+        import json
+        if isinstance(eval_result, str):
+            try:
+                content = eval_result.strip()
+                if content.startswith("```json"):
+                    content = content[7:-3].strip()
+                eval_result = json.loads(content)
+            except json.JSONDecodeError:
+                pass
+
+        if isinstance(eval_result, dict):
+            score = eval_result.get("score") or eval_result.get("quality")
+            if isinstance(score, (int, float, str)):
+                try:
+                    score = float(score)
+                    # Check against quality_threshold stop conditions
+                    for cond in self._spec.stop_conditions:
+                        if cond.condition_type.value == "quality_threshold":
+                            threshold = float(cond.value) if cond.value else 0.8
+                            return score >= threshold
+                    return score >= 0.8  # default threshold
+                except ValueError:
+                    pass
+            return bool(eval_result.get("passed") or eval_result.get("approved"))
+        return False

loopengt/core/runtime/handoff.py

@@ -0,0 +1,139 @@
+"""Agent-to-agent handoff logic."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+import structlog
+from pydantic import BaseModel, ConfigDict, Field
+
+logger = structlog.get_logger(__name__)
+
+
+class HandoffProtocol(StrEnum):
+    """How context is transferred between agents."""
+
+    DIRECT = "direct"
+    VIA_SUPERVISOR = "via_supervisor"
+    BROADCAST = "broadcast"
+
+
+class HandoffContext(BaseModel):
+    """Context payload passed between agents during a handoff."""
+
+    model_config = ConfigDict(frozen=True)
+
+    from_agent: str = Field(..., description="Agent handing off")
+    to_agent: str = Field(..., description="Agent receiving")
+    protocol: HandoffProtocol = Field(
+        default=HandoffProtocol.DIRECT, description="Handoff protocol"
+    )
+    payload: dict[str, Any] = Field(
+        default_factory=dict, description="Data being transferred"
+    )
+    instructions: str = Field(
+        default="", description="Instructions for the receiving agent"
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Handoff metadata"
+    )
+
+
+class HandoffManager:
+    """Manages agent-to-agent handoff within a loop execution.
+
+    Tracks handoff history and validates agent transitions.
+
+    Usage::
+
+        manager = HandoffManager(allowed_agents=["planner", "executor", "reviewer"])
+        ctx = manager.create_handoff(
+            from_agent="planner",
+            to_agent="executor",
+            payload={"plan": plan_output},
+        )
+        # Deliver ctx to the receiving agent
+        manager.complete_handoff(ctx)
+    """
+
+    def __init__(self, allowed_agents: list[str] | None = None) -> None:
+        self._allowed = set(allowed_agents) if allowed_agents else None
+        self._history: list[HandoffContext] = []
+        self._log = logger.bind(component="handoff")
+
+    def create_handoff(
+        self,
+        from_agent: str,
+        to_agent: str,
+        payload: dict[str, Any] | None = None,
+        instructions: str = "",
+        protocol: HandoffProtocol = HandoffProtocol.DIRECT,
+    ) -> HandoffContext:
+        """Create a new handoff context.
+
+        Raises
+        ------
+        ValueError
+            If either agent is not in the allowed set.
+        """
+        if self._allowed:
+            for name in (from_agent, to_agent):
+                if name not in self._allowed:
+                    raise ValueError(
+                        f"Agent '{name}' not in allowed set: {self._allowed}"
+                    )
+
+        ctx = HandoffContext(
+            from_agent=from_agent,
+            to_agent=to_agent,
+            protocol=protocol,
+            payload=payload or {},
+            instructions=instructions,
+        )
+
+        self._log.info(
+            "handoff.created",
+            from_agent=from_agent,
+            to_agent=to_agent,
+            protocol=protocol,
+        )
+        return ctx
+
+    def complete_handoff(self, ctx: HandoffContext) -> None:
+        """Record a completed handoff."""
+        self._history.append(ctx)
+        self._log.info(
+            "handoff.completed",
+            from_agent=ctx.from_agent,
+            to_agent=ctx.to_agent,
+        )
+
+    def broadcast(
+        self,
+        from_agent: str,
+        targets: list[str],
+        payload: dict[str, Any] | None = None,
+        instructions: str = "",
+    ) -> list[HandoffContext]:
+        """Create handoff contexts for a broadcast to multiple agents."""
+        contexts = []
+        for target in targets:
+            ctx = self.create_handoff(
+                from_agent=from_agent,
+                to_agent=target,
+                payload=payload,
+                instructions=instructions,
+                protocol=HandoffProtocol.BROADCAST,
+            )
+            contexts.append(ctx)
+        return contexts
+
+    @property
+    def history(self) -> list[HandoffContext]:
+        """Return the handoff history (read-only copy)."""
+        return list(self._history)
+
+    def last_handoff(self) -> HandoffContext | None:
+        """Return the most recent handoff, or None."""
+        return self._history[-1] if self._history else None