feat: add universal agent tool wrapper, test suite and real-world e2e tool calling example

Author: AlgorithmicMind

README.md

@@ -156,6 +156,17 @@ python -m codeshield run script.py --llm        # try Gemini self-healing if con
 python -m codeshield run script.py --no-llm     # force local fallback
 ```
 
+## 🤖 Agent Tool Integration (LangChain, CrewAI, Gemini)
+
+```python
+from codeshield import create_code_execution_tool
+
+# Pasa la tool directamente a tu agente
+tools = [create_code_execution_tool()]
+```
+
+`create_code_execution_tool()` returns a ready-to-register `execute_python_code(code: str) -> str` function. It runs the provided Python in a self-healing sandbox and returns either the stdout or a structured error report with `error_type` and `stderr`.
+
 ---
 
 ## Examples

examples/04_agent_tool_dropin.py

@@ -0,0 +1,51 @@
+"""Example 4: real-world agentic function calling with CodeShield + Gemini."""
+
+from __future__ import annotations
+
+import os
+
+from dotenv import load_dotenv
+from google import genai
+from google.genai import types
+
+from codeshield import create_code_execution_tool
+
+
+def main() -> None:
+    load_dotenv()
+
+    api_key = os.environ.get("GEMINI_API_KEY")
+    model = os.environ.get("GEMINI_MODEL", "gemini-3.7-flash")
+    if not api_key:
+        print("GEMINI_API_KEY not set. Set it in .env to run this example.")
+        return
+
+    execute_python_code = create_code_execution_tool()
+
+    client = genai.Client(api_key=api_key)
+
+    prompt = (
+        "Calculate the cumulative return and the annualized Sharpe Ratio "
+        "(assuming a risk-free rate of 0.02) for this daily return series:\n"
+        "[0.012, -0.005, 0.008, 0.015, -0.002, 0.021, -0.010, 0.018]\n\n"
+        "Use only the Python standard library (math, statistics). "
+        "Do not use numpy, pandas or any third-party package. "
+        "Print the cumulative return and the annualized Sharpe ratio clearly."
+    )
+
+    response = client.models.generate_content(
+        model=model,
+        contents=prompt,
+        config=types.GenerateContentConfig(
+            tools=[execute_python_code],
+            temperature=0.2,
+            automatic_function_calling=types.AutomaticFunctionCallingConfig(),
+        ),
+    )
+
+    print("\n--- Final response ---")
+    print(response.text)
+
+
+if __name__ == "__main__":
+    main()

src/codeshield/__init__.py

@@ -7,5 +7,11 @@
 
 from codeshield.loop import SelfHealingEngine
 from codeshield.schemas import CodeExecutionRequest, ExecutionResult
+from codeshield.tools import create_code_execution_tool
 
-__all__ = ["SelfHealingEngine", "CodeExecutionRequest", "ExecutionResult"]
+__all__ = [
+    "SelfHealingEngine",
+    "CodeExecutionRequest",
+    "ExecutionResult",
+    "create_code_execution_tool",
+]

src/codeshield/tools.py

@@ -0,0 +1,76 @@
+"""Universal agent tool wrapper for CodeShield.
+
+The function returned by ``create_code_execution_tool`` can be registered as a
+tool in any agent framework (LangChain, CrewAI, Google Gen AI, etc.). It runs
+the provided Python source inside a self-healing sandbox and returns either the
+stdout or a structured error report.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from codeshield.environment import SandboxError
+from codeshield.loop import SelfHealingEngine, SelfHealingError
+from codeshield.runner import SubprocessRunnerError
+
+
+def create_code_execution_tool(
+    engine: SelfHealingEngine | None = None,
+) -> Callable[[str], str]:
+    """Return a drop-in ``execute_python_code(code: str) -> str`` tool.
+
+    Args:
+        engine: Optional ``SelfHealingEngine`` instance. When ``None``, a fresh
+            engine is created for each tool call.
+
+    Returns:
+        A callable ready to be registered as an agent tool.
+    """
+
+    def execute_python_code(code: str) -> str:
+        """Execute Python code in an isolated, self-healing sandbox.
+
+        Use this tool to run numerical, statistical or data-processing
+        computations that cannot be done directly in the conversation.
+
+        Args:
+            code: A valid Python script as a string.
+
+        Returns:
+            The stdout of the script if execution succeeds, or a structured
+            error report if it fails after all self-healing attempts.
+        """
+        _engine = engine or SelfHealingEngine()
+        with _engine:
+            try:
+                result, diagnosis = _engine.run(code)
+            except SelfHealingError as exc:
+                return f"error_type: SelfHealingError\nmessage: {exc}"
+            except (SandboxError, SubprocessRunnerError) as exc:
+                return f"error_type: {type(exc).__name__}\nmessage: {exc}"
+
+        if (
+            result.exit_code == 0
+            and not result.silent_failure_detected
+            and not result.timed_out
+        ):
+            return result.stdout.strip()
+
+        report: list[str] = ["The Python script did not execute successfully."]
+        if diagnosis is not None:
+            report.append(f"error_type: {diagnosis.error_type}")
+            if diagnosis.root_cause_line is not None:
+                report.append(f"root_cause_line: {diagnosis.root_cause_line}")
+            if diagnosis.message:
+                report.append(f"message: {diagnosis.message}")
+        if result.stderr.strip():
+            report.append(f"stderr: {result.stderr.strip()}")
+        if result.timed_out:
+            report.append("timed_out: true")
+        if result.silent_failure_detected:
+            report.append("silent_failure_detected: true")
+
+        return "\n".join(report)
+
+    return execute_python_code

tests/test_tools.py

@@ -0,0 +1,37 @@
+"""Unit tests for the CodeShield agent tool wrapper."""
+
+from __future__ import annotations
+
+from codeshield import create_code_execution_tool
+from codeshield.loop import SelfHealingEngine
+
+
+def test_tool_returns_stdout_on_success() -> None:
+    """A clean execution returns the stripped stdout."""
+    engine = SelfHealingEngine(use_llm=False)
+    tool = create_code_execution_tool(engine)
+
+    result = tool("print('hello from tool')")
+
+    assert result == "hello from tool"
+
+
+def test_tool_reports_controlled_failure() -> None:
+    """An unresolved import error surfaces a structured error report."""
+    engine = SelfHealingEngine(use_llm=False)
+    tool = create_code_execution_tool(engine)
+
+    result = tool("import not_a_real_module_xyz_123")
+
+    assert "error_type" in result
+    assert "ModuleNotFoundError" in result
+    assert "stderr" in result
+
+
+def test_tool_without_engine_uses_default() -> None:
+    """Calling the tool without an explicit engine still works."""
+    tool = create_code_execution_tool()
+
+    result = tool("print(2 + 2)")
+
+    assert result == "4"