feat(tools): add YAML tool registry and sample echo tool

Author: HalukProductions

TASKS.md

@@ -13,14 +13,14 @@ Starter kit for building test-first, easily deployable AI agents.
 - [x] Flesh out `README.md` with badges, quick-start guide, and differentiators
 - [x] Add GitHub Actions release workflow to publish to PyPI & NPM on version tags
 - [x] Bump working version to `0.1.0.dev0` (Python) and `0.1.0-dev` (NPM)
+- [x] YAML tool registry with auto-import & CLI stub generation
 
 ## In Progress Tasks
 
-- [ ] Implement core ReAct-style agent loop (`mini_agent_harness.core.loop`) **(initial echo LLM completed; full tool loop pending)**
+- [ ] Implement core ReAct-style agent loop (`mini_agent_harness.core.loop`) — partial (tool registry wired, reasoning loop pending)
 
 ## Future Tasks
 
-- [ ] YAML tool registry with auto-import & CLI stub generation
 - [ ] `mini-agent serve` FastAPI server with streaming SSE endpoint
 - [ ] React webapp (`webapp/`) with shadcn/ui chat + playground
 - [ ] Testing harness Phase 1: DeepEval metrics and Guardrails schema checks

agents/quickstart.yaml

@@ -1,3 +1,4 @@
 name: Quickstart Agent
 description: "A minimal agent spec for the Mini Agent Harness demo."
-tools: []
+tools:
+  - tools/echo.yaml

mini_agent_harness/core/__init__.py

@@ -8,6 +8,7 @@
 from dataclasses import dataclass
 
 from .llm import get_default_llm, LLM
+from ..tools import load_tools_from_manifest
 
 
 @dataclass
@@ -31,6 +32,7 @@ class Agent:
     def __init__(self, manifest: dict, llm: LLM | None = None):
         self.manifest = manifest
         self.llm: LLM = llm or get_default_llm()
+        self.tools = load_tools_from_manifest(manifest)
 
     def run(self, input_text: str) -> AgentResult:
         """Execute the agent for a single user prompt.
@@ -40,5 +42,13 @@ def run(self, input_text: str) -> AgentResult:
         and tool execution steps.
         """
 
+        # Naive tool invocation: if the prompt starts with "<tool>: " call it
+        if ":" in input_text:
+            tool_name, _, arg = input_text.partition(":")
+            tool_name = tool_name.strip()
+            if tool_name in self.tools:
+                result = self.tools[tool_name](arg.strip())
+                return AgentResult(response_text=str(result))
+
         output = self.llm.generate(input_text)
         return AgentResult(response_text=output) 

mini_agent_harness/tools/__init__.py

@@ -0,0 +1,77 @@
+"""Dynamic tool registry.
+
+Tools are defined by YAML spec files and backed by Python callables.
+Each tool spec looks like:
+
+```yaml
+name: echo
+description: Echo the user input
+python: mini_agent_harness.tools.echo:echo_tool
+```
+
+At runtime we import the callable and expose it via `load_tools`.
+"""
+from __future__ import annotations
+
+import importlib
+import inspect
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Dict, Iterable, List
+
+import yaml
+
+
+@dataclass
+class ToolSpec:
+    name: str
+    description: str
+    python: str  # module:path e.g. path.to.mod:function_name
+    func: Callable | None = None  # populated after import
+
+    def import_func(self) -> Callable:
+        if self.func is not None:
+            return self.func
+        module_path, _, attr = self.python.partition(":")
+        if not module_path or not attr:
+            raise ValueError(f"Invalid python path in tool spec: {self.python}")
+        module = importlib.import_module(module_path)
+        func: Callable = getattr(module, attr)
+        if not callable(func):
+            raise TypeError(f"Tool target {self.python} is not callable")
+        # Basic signature check: first param should be str or none
+        sig = inspect.signature(func)
+        if len(sig.parameters) == 0:
+            raise TypeError("Tool callable must accept at least one argument (input string)")
+        self.func = func
+        return func
+
+
+def _load_tool_yaml(path: Path) -> ToolSpec:
+    data = yaml.safe_load(path.read_text())
+    return ToolSpec(**data)
+
+
+def discover_tools(tool_paths: Iterable[str | Path]) -> Dict[str, ToolSpec]:
+    """Load multiple tool YAMLs into a registry keyed by tool name."""
+    registry: Dict[str, ToolSpec] = {}
+    for p in tool_paths:
+        spec = _load_tool_yaml(Path(p))
+        if spec.name in registry:
+            raise ValueError(f"Duplicate tool name {spec.name}")
+        registry[spec.name] = spec
+    return registry
+
+
+def load_tools_from_manifest(manifest: dict) -> Dict[str, Callable]:
+    """Given the agent manifest dict, import and return callable tools."""
+    tools_field: List[str] = manifest.get("tools", [])
+    registry = discover_tools(tools_field)
+    return {name: spec.import_func() for name, spec in registry.items()}
+
+
+__all__ = [
+    "ToolSpec",
+    "discover_tools",
+    "load_tools_from_manifest",
+] 

mini_agent_harness/tools/echo.py

@@ -0,0 +1,5 @@
+"""Sample tool that echoes the input."""
+
+def echo_tool(text: str) -> str:
+    """Return the text unchanged (demo tool)."""
+    return text 

tests/test_quickstart.py

@@ -5,5 +5,11 @@
 
 
 def test_quickstart_echo():
+    # direct llm path
     result = quickstart_agent.run("Hello")
-    assert "[ECHO]" in result.response_text 
+    assert "[ECHO]" in result.response_text
+
+
+def test_tool_invocation():
+    result = quickstart_agent.run("echo: hi there")
+    assert result.response_text == "hi there" 

tools/echo.yaml

@@ -0,0 +1,3 @@
+name: echo
+description: Echo the input string back.
+python: mini_agent_harness.tools.echo:echo_tool