algo-cli-runtime 0.14.0__py3-none-any.whl

algo_cli/reasoning/react.py

@@ -0,0 +1,246 @@
+"""ReAct+ Enhanced Reasoning-Action Loop.
+
+Interleaves structured Thought, Action, and Observation steps with:
+- Typed action parsing (tool calls, sub-questions, assertions)
+- Observation summarization to prevent context bloat
+- Automatic thought-chain compaction for long episodes
+- Loop detection with strategy broadening
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from ..chat_protocol import get_attr
+
+
+@dataclass
+class ReactStep:
+    """One step in a ReAct episode."""
+    thought: str
+    action: str
+    action_input: dict[str, Any] | str
+    observation: str
+    timestamp: float = field(default_factory=time.time)
+
+    def to_message(self) -> dict[str, Any]:
+        return {
+            "role": "assistant",
+            "content": f"Thought: {self.thought}\nAction: {self.action}\nAction Input: {self._format_input()}",
+        }
+
+    def observation_message(self) -> dict[str, Any]:
+        return {
+            "role": "user",
+            "content": f"Observation: {self.observation}",
+        }
+
+    def _format_input(self) -> str:
+        if isinstance(self.action_input, dict):
+            return json.dumps(self.action_input)
+        return str(self.action_input)
+
+
+THOUGHT_RE = re.compile(r"Thought:\s*(.+?)(?=\nAction:|$)", re.DOTALL)
+ACTION_RE = re.compile(r"Action:\s*(.+?)(?=\nAction Input:|$)", re.DOTALL)
+ACTION_INPUT_RE = re.compile(r"Action Input:\s*(.+?)$", re.DOTALL)
+
+
+def parse_react_output(text: str) -> tuple[str, str, dict[str, Any] | str]:
+    """Parse a ReAct-formatted response into (thought, action, action_input)."""
+    thought_m = THOUGHT_RE.search(text)
+    action_m = ACTION_RE.search(text)
+    input_m = ACTION_INPUT_RE.search(text)
+
+    thought = thought_m.group(1).strip() if thought_m else ""
+    action = action_m.group(1).strip() if action_m else ""
+    raw_input = input_m.group(1).strip() if input_m else ""
+
+    # Try parsing action input as JSON; fall back to string
+    action_input: dict[str, Any] | str = raw_input
+    if raw_input:
+        try:
+            parsed = json.loads(raw_input)
+            if isinstance(parsed, dict):
+                action_input = parsed
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+    return thought, action, action_input
+
+
+def compact_observations(steps: list[ReactStep], max_chars: int = 4000) -> str:
+    """Compact a ReAct episode into a summary for context injection."""
+    if not steps:
+        return ""
+    lines: list[str] = []
+    total = 0
+    for i, step in enumerate(steps):
+        entry = f"[{i+1}] Thought: {step.thought[:200]}\n    Action: {step.action} -> Obs: {step.observation[:300]}"
+        if total + len(entry) > max_chars:
+            remaining = len(steps) - i
+            lines.append(f"... ({remaining} earlier steps compacted)")
+            break
+        lines.append(entry)
+        total += len(entry)
+    return "\n".join(lines)
+
+
+@dataclass
+class ReactLoop:
+    """Stateful ReAct+ loop for agent harness integration."""
+    max_steps: int = 10
+    observation_limit: int = 2000
+    loop_detection_window: int = 3
+
+    steps: list[ReactStep] = field(default_factory=list)
+    _action_history: list[str] = field(default_factory=list)
+
+    def detect_loop(self) -> bool:
+        """Detect if the last N actions are identical (stuck loop)."""
+        if len(self._action_history) < self.loop_detection_window:
+            return False
+        window = self._action_history[-self.loop_detection_window:]
+        return len(set(window)) == 1
+
+    def add_step(self, step: ReactStep) -> None:
+        self.steps.append(step)
+        self._action_history.append(f"{step.action}:{str(step.action_input)[:80]}")
+
+    def truncate_observation(self, obs: str) -> str:
+        if len(obs) > self.observation_limit:
+            return obs[:self.observation_limit - 20] + "\n...[truncated]"
+        return obs
+
+    def build_context(self, task: str, system: str) -> list[dict[str, Any]]:
+        """Build the message list for the next LLM call."""
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": task},
+        ]
+        for step in self.steps:
+            messages.append(step.to_message())
+            messages.append(step.observation_message())
+        # Final prompt to continue reasoning
+        messages.append({
+            "role": "user",
+            "content": "Continue with your next Thought and Action. If you have enough information to answer, respond with just the final answer.",
+        })
+        return messages
+
+
+def run_react_loop(
+    *,
+    task: str,
+    client: Any,
+    model: str,
+    tools: list[Any] | None = None,
+    system: str = "You are a reasoning agent. Use the ReAct format:\nThought: <your reasoning>\nAction: <tool name or 'finish'>\nAction Input: <JSON args or final answer>",
+    max_steps: int = 10,
+    tool_map: dict[str, Callable] | None = None,
+    observation_limit: int = 2000,
+) -> list[ReactStep]:
+    """Run a complete ReAct+ episode.
+
+    Args:
+        task: The task to solve.
+        client: Ollama client instance.
+        model: Model name.
+        tools: Optional list of tool functions for the model.
+        system: System prompt (ReAct format instructions).
+        max_steps: Maximum reasoning steps.
+        tool_map: Optional mapping of action names to callables for executing actions.
+        observation_limit: Max chars per observation.
+
+    Returns:
+        List of ReactStep records.
+    """
+    loop = ReactLoop(max_steps=max_steps, observation_limit=observation_limit)
+    kwargs: dict[str, Any] = {
+        "model": model,
+        "messages": loop.build_context(task, system),
+        "stream": False,
+    }
+    if tools:
+        kwargs["tools"] = tools
+
+    for _ in range(max_steps):
+        try:
+            response = client.chat(**kwargs)
+        except Exception as exc:
+            loop.add_step(ReactStep(
+                thought="(LLM call failed)",
+                action="error",
+                action_input={},
+                observation=str(exc),
+            ))
+            break
+
+        content = get_attr(get_attr(response, "message", {}), "content", "")
+        tool_calls = get_attr(get_attr(response, "message", {}), "tool_calls", None)
+
+        # If the model used structured tool calls, execute them
+        if tool_calls:
+            from ..tool_runtime import normalize_tool_call
+            for call in tool_calls:
+                name, args = normalize_tool_call(call)
+                thought = f"(model called tool: {name})"
+                obs = ""
+                if tool_map and name in tool_map:
+                    try:
+                        obs = str(tool_map[name](**args))
+                    except Exception as exc:
+                        obs = f"Tool error: {exc}"
+                step = ReactStep(thought=thought, action=name, action_input=args, observation=loop.truncate_observation(obs))
+                loop.add_step(step)
+            # Rebuild context and continue
+            kwargs["messages"] = loop.build_context(task, system)
+            continue
+
+        # Parse ReAct-formatted text
+        thought, action, action_input = parse_react_output(content)
+
+        if not action or action.lower() == "finish":
+            # Task complete or final answer
+            loop.add_step(ReactStep(
+                thought=thought,
+                action="finish",
+                action_input=action_input if isinstance(action_input, str) else json.dumps(action_input),
+                observation="Task complete.",
+            ))
+            break
+
+        # Execute action if tool_map provided
+        obs = ""
+        if tool_map:
+            fn = tool_map.get(action)
+            if fn:
+                try:
+                    args = action_input if isinstance(action_input, dict) else {"query": str(action_input)}
+                    obs = str(fn(**args))
+                except Exception as exc:
+                    obs = f"Tool error: {exc}"
+            else:
+                obs = f"Unknown action: {action}"
+
+        step = ReactStep(
+            thought=thought,
+            action=action,
+            action_input=action_input,
+            observation=loop.truncate_observation(obs),
+        )
+        loop.add_step(step)
+
+        # Loop detection
+        if loop.detect_loop():
+            step.observation += "\n[Loop detected: same action repeated. Try a different approach.]"
+            break
+
+        # Rebuild context
+        kwargs["messages"] = loop.build_context(task, system)
+
+    return loop.steps

algo_cli/reasoning/reflexion.py

@@ -0,0 +1,225 @@
+"""Reflexion+ Verbal Self-Critique with Episodic Memory.
+
+Extends the base reflex module with:
+- Verbal self-evaluation after each attempt
+- Episodic memory of past critiques for cross-attempt learning
+- Retry with critique-guided modifications
+- Convergence detection (when critiques stop surfacing new issues)
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..chat_protocol import get_attr
+
+
+@dataclass
+class ReflexionEpisode:
+    """One attempt in a Reflexion loop."""
+    attempt: int
+    task: str
+    output: str
+    critique: str
+    score: float  # 0.0-1.0 self-assessment
+    improved: bool  # did this attempt improve over the previous?
+    timestamp: float = field(default_factory=time.time)
+
+    def critique_message(self) -> dict[str, Any]:
+        return {
+            "role": "user",
+            "content": (
+                f"## Self-Critique for Attempt {self.attempt}\n"
+                f"Score: {self.score:.2f}/1.0\n"
+                f"{self.critique}\n\n"
+                "Revise your approach to address these issues. Do not repeat the same mistakes."
+            ),
+        }
+
+
+CRITIQUE_PROMPT = """You are evaluating your own work. Be specific and constructive.
+
+Rate your output on a scale of 0.0 to 1.0:
+- 1.0: Fully correct, complete, no issues
+- 0.7: Mostly correct with minor gaps
+- 0.4: Partially correct with significant issues
+- 0.0: Fundamentally wrong or missing
+
+For each issue found:
+1. State the specific problem
+2. Explain why it is a problem
+3. Suggest a concrete fix
+
+Format your response as JSON:
+{"score": <float>, "critique": "<specific issues and fixes>"}
+"""
+
+CONVERGENCE_THRESHOLD = 0.05  # Score improvement below this = converged
+
+
+@dataclass
+class ReflexionLoop:
+    """Stateful Reflexion loop for agent harness integration."""
+    max_attempts: int = 3
+    convergence_threshold: float = CONVERGENCE_THRESHOLD
+
+    episodes: list[ReflexionEpisode] = field(default_factory=list)
+    best_output: str = ""
+    best_score: float = 0.0
+
+    def is_converged(self) -> bool:
+        """Check if recent episodes show diminishing returns."""
+        if len(self.episodes) < 2:
+            return False
+        recent = self.episodes[-2:]
+        improvement = abs(recent[1].score - recent[0].score)
+        return improvement < self.convergence_threshold and recent[1].score >= recent[0].score
+
+    def add_episode(self, episode: ReflexionEpisode) -> None:
+        """Record an episode and update the best-so-far result.
+
+        ``improved`` describes progress over the immediately preceding attempt,
+        not whether the episode established a new all-time best.  Keeping those
+        concepts separate matters after a regression followed by a partial
+        recovery (for example, scores of 0.8, 0.5, then 0.7).
+        """
+        previous = self.episodes[-1] if self.episodes else None
+        episode.improved = previous is not None and episode.score > previous.score
+        self.episodes.append(episode)
+        if len(self.episodes) == 1 or episode.score > self.best_score:
+            self.best_score = episode.score
+            self.best_output = episode.output
+
+    def build_memory_context(self) -> str:
+        """Build the episodic memory injection for the next attempt."""
+        if not self.episodes:
+            return ""
+        lines = ["## Previous Attempts and Self-Critiques"]
+        for ep in self.episodes:
+            lines.append(f"### Attempt {ep.attempt} (score: {ep.score:.2f})")
+            lines.append(f"Critique: {ep.critique[:500]}")
+        lines.append("\nLearn from these critiques. Avoid repeating the same errors.")
+        return "\n".join(lines)
+
+    def build_messages(self, task: str, system: str) -> list[dict[str, Any]]:
+        """Build messages for the next attempt, including episodic memory."""
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": system},
+        ]
+        memory = self.build_memory_context()
+        if memory:
+            messages.append({"role": "user", "content": memory})
+        messages.append({"role": "user", "content": task})
+        return messages
+
+
+def _parse_critique(response_text: str) -> tuple[float, str]:
+    """Parse a critique response into (score, critique_text)."""
+    text = response_text.strip()
+    # Try JSON parse
+    try:
+        data = json.loads(text)
+        score = float(data.get("score", 0.5))
+        critique = str(data.get("critique", ""))
+        return max(0.0, min(1.0, score)), critique
+    except (json.JSONDecodeError, ValueError, TypeError):
+        pass
+    # Try extracting score from text
+    score_m = None
+    for pattern in [r'"score"\s*:\s*([0-9.]+)', r'score:\s*([0-9.]+)', r'([0-9.]+)\s*/\s*1\.0']:
+        import re
+        m = re.search(pattern, text)
+        if m:
+            score_m = m
+            break
+    score = float(score_m.group(1)) if score_m else 0.5
+    return max(0.0, min(1.0, score)), text[:1000]
+
+
+def run_reflexion_loop(
+    *,
+    task: str,
+    client: Any,
+    model: str,
+    critique_model: str | None = None,
+    system: str = "You are a capable reasoning agent. Produce your best work on the given task.",
+    max_attempts: int = 3,
+    tools: list[Any] | None = None,
+    score_threshold: float = 0.8,
+) -> list[ReflexionEpisode]:
+    """Run a Reflexion+ loop: attempt -> self-critique -> retry.
+
+    Args:
+        task: The task to solve.
+        client: Ollama client instance.
+        model: Model for task attempts.
+        critique_model: Optional separate model for self-critique (defaults to model).
+        system: System prompt.
+        max_attempts: Maximum reflexion attempts.
+        tools: Optional tools for the model.
+        score_threshold: Stop early if score exceeds this.
+
+    Returns:
+        List of ReflexionEpisode records.
+    """
+    critique_model = critique_model or model
+    loop = ReflexionLoop(max_attempts=max_attempts)
+
+    for attempt in range(1, max_attempts + 1):
+        # 1. Attempt the task
+        messages = loop.build_messages(task, system)
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "stream": False,
+        }
+        if tools:
+            kwargs["tools"] = tools
+
+        try:
+            response = client.chat(**kwargs)
+            output = get_attr(get_attr(response, "message", {}), "content", "")
+        except Exception as exc:
+            output = f"Error during attempt {attempt}: {exc}"
+
+        # 2. Self-critique
+        critique_messages = [
+            {"role": "system", "content": CRITIQUE_PROMPT},
+            {"role": "user", "content": f"## Task\n{task}\n\n## Your Output\n{output}\n\nEvaluate your output above."},
+        ]
+        try:
+            critique_response = client.chat(
+                model=critique_model,
+                messages=critique_messages,
+                stream=False,
+                format="json",
+            )
+            critique_text = get_attr(get_attr(critique_response, "message", {}), "content", "")
+            score, critique = _parse_critique(critique_text)
+        except Exception:
+            score = 0.5
+            critique = "(critique generation failed)"
+
+        episode = ReflexionEpisode(
+            attempt=attempt,
+            task=task,
+            output=output,
+            critique=critique,
+            score=score,
+            # add_episode derives the value from the previous episode.  Supply
+            # the neutral value here so construction cannot fail before that
+            # comparison is made.
+            improved=False,
+        )
+        loop.add_episode(episode)
+
+        # 3. Check termination
+        if score >= score_threshold:
+            break
+        if loop.is_converged() and attempt >= 2:
+            break
+
+    return loop.episodes