feat(core): minimal ReAct loop with tool invocation

Author: HalukProductions

mini_agent_harness/core/__init__.py

@@ -9,6 +9,7 @@
 
 from .llm import get_default_llm, LLM
 from ..tools import load_tools_from_manifest
+from .loop import ReActLoop
 
 
 @dataclass
@@ -42,7 +43,11 @@ def run(self, input_text: str) -> AgentResult:
         and tool execution steps.
         """
 
-        # Naive tool invocation: if the prompt starts with "<tool>: " call it
+        if self.manifest.get("mode") == "react":
+            loop = ReActLoop(self.llm, self.tools)
+            return AgentResult(response_text=loop.run(input_text))
+
+        # Simple prefix tool call mode
         if ":" in input_text:
             tool_name, _, arg = input_text.partition(":")
             tool_name = tool_name.strip()

mini_agent_harness/core/loop.py

@@ -0,0 +1,64 @@
+"""Minimal ReAct-style reasoning loop.
+
+This is *not* a full implementation – it is intentionally lightweight so that
+unit tests can stub the LLM responses. The protocol is:
+
+1. Build a transcript containing a list of tools and the user input.
+2. Ask the LLM for a response.
+3. If the response starts with `ACTION:` and `ARG:` we call that tool,
+   append an `OBSERVATION:` line, and loop.
+4. If the response starts with `FINAL:` we stop and return the remaining text.
+5. After `max_iters` fall back to returning the last model output.
+"""
+from __future__ import annotations
+
+from typing import Callable, Dict
+
+from .llm import LLM
+
+
+class ReActLoop:
+    """Lightweight ReAct executor."""
+
+    def __init__(self, llm: LLM, tools: Dict[str, Callable], max_iters: int = 3):
+        self.llm = llm
+        self.tools = tools
+        self.max_iters = max_iters
+
+    def run(self, user_input: str) -> str:
+        transcript = [f"Tools: {', '.join(self.tools)}", f"User: {user_input}"]
+
+        for _ in range(self.max_iters):
+            prompt = "\n".join(transcript + ["Assistant:"])
+            model_response = self.llm.generate(prompt)
+
+            if model_response.startswith("FINAL:"):
+                return model_response[len("FINAL:") :].strip()
+
+            if model_response.startswith("ACTION:"):
+                # Parse lines
+                lines = model_response.splitlines()
+                try:
+                    action = lines[0].split(":", 1)[1].strip()
+                    arg_line = next(l for l in lines[1:] if l.startswith("ARG:"))
+                    arg = arg_line.split(":", 1)[1].strip()
+                except Exception:  # pragma: no cover
+                    # If parsing fails, treat whole response as final.
+                    return model_response
+
+                if action not in self.tools:
+                    observation = f"ERROR: unknown tool {action}"
+                else:
+                    try:
+                        observation = str(self.tools[action](arg))
+                    except Exception as exc:  # pragma: no cover
+                        observation = f"ERROR: tool raised {exc}"
+
+                transcript.extend([model_response, f"OBSERVATION: {observation}"])
+                continue
+
+            # Fallback: treat model response as final answer
+            return model_response.strip()
+
+        # Reached iteration cap
+        return "ERROR: max iterations reached" 

tests/test_react_loop.py

@@ -0,0 +1,26 @@
+from mini_agent_harness.core import Agent, AgentResult
+from mini_agent_harness.testing import agent_fixture
+
+class MockLLM:
+    """Returns scripted responses for each call."""
+
+    def __init__(self):
+        self.calls = 0
+
+    def generate(self, prompt: str) -> str:  # noqa: D401
+        self.calls += 1
+        if self.calls == 1:
+            return "ACTION: echo\nARG: hello"
+        return "FINAL: done"
+
+
+def test_react_loop_invokes_tool():
+    manifest = {
+        "name": "react-agent",
+        "description": "demo",
+        "mode": "react",
+        "tools": ["tools/echo.yaml"],
+    }
+    agent = Agent(manifest, llm=MockLLM())
+    result: AgentResult = agent.run("ignored user input")
+    assert result.response_text == "done"