apsimo 1.3.0__py3-none-any.whl

apsimo/reasoning/loop.py

@@ -0,0 +1,373 @@
+"""ReasoningLoop — orchestrates model calls and tool execution.
+
+This is the core of Colony's reasoning capability. It replaces the
+tightly-coupled reasoning loop in ``run_agent.py`` with a clean,
+host-agnostic interface that can be driven via the ``/v1/host/reasoning/turn``
+HTTP endpoint.
+
+The loop works like this:
+
+1. Receive messages + optional system prompt from the host
+2. Call the LLM via LLMRouter
+3. If the LLM returns tool calls, execute them and append results
+4. Repeat until the LLM responds without tool calls (or budget exhausted)
+5. Return the final response + any pending tool calls
+
+Key differences from run_agent.py:
+
+- No session persistence (hosts manage their own sessions)
+- No streaming callbacks (hosts handle streaming themselves)
+- No display/print logic (hosts handle display)
+- No memory auto-recall (that's the context engine's job)
+- Tool execution is delegated to ToolExecutor (pluggable)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from apsimo.reasoning.executor import ToolExecutor, ToolRegistryError
+from apsimo.reasoning.tool_policy import ToolActorPolicy
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ReasoningConfig:
+    """Tunable parameters for the reasoning loop."""
+
+    max_iterations: int = 10
+    tool_delay_seconds: float = 0.0  # Delay between tool call batches
+    force_tier: str | None = None  # Force a specific LLM tier
+
+
+@dataclass
+class ReasoningResult:
+    """Result of a single reasoning turn."""
+
+    status: str  # "completed" | "needs_tool" | "error"
+    message: dict[str, Any] | None = None  # HostMessage-shaped
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    usage: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+    model_provenance: dict[str, Any] = field(default_factory=dict)
+
+
+def _messages_to_dicts(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Normalise messages for LiteLLM consumption.
+
+    Ensures every message has at least ``role`` and ``content`` keys.
+    Strips None content, replacing with empty string.
+    """
+    result = []
+    for m in messages:
+        d = dict(m)
+        if d.get("content") is None:
+            d["content"] = ""
+        result.append(d)
+    return result
+
+
+class ReasoningLoop:
+    """Orchestrate model calls and tool execution for a reasoning turn.
+
+    Parameters
+    ----------
+    model :
+        An object with an ``async complete(messages, *, tools, force_tier, context)``
+        method — typically an :class:`~apsimo.router.router.LLMRouter`.
+    tools :
+        A :class:`ToolExecutor` that can dispatch tool calls.
+    config :
+        Optional tuning parameters.
+    """
+
+    def __init__(
+        self,
+        model: Any,
+        tools: ToolExecutor | None = None,
+        config: ReasoningConfig | None = None,
+    ) -> None:
+        self._model = model
+        self._tools = tools or ToolExecutor()
+        self._config = config or ReasoningConfig()
+
+    async def run_turn(
+        self,
+        *,
+        session_id: str,
+        messages: list[dict[str, Any]],
+        available_tools: list[str] | None = None,
+        model_override: str | None = None,
+        system_prompt: str | None = None,
+        context: dict[str, Any] | None = None,
+        actor_policy: ToolActorPolicy | None = None,
+    ) -> ReasoningResult:
+        """Run a single reasoning turn with tool iteration.
+
+        This is the main entry point called by the host router.
+
+        Parameters
+        ----------
+        session_id :
+            Identifier for the reasoning session (for logging / tracing).
+        messages :
+            OpenAI-format message list (role + content).
+        available_tools :
+            Tool names the host has made available.
+        model_override :
+            If set, passed as ``force_tier`` hint to the LLMRouter.
+        system_prompt :
+            Optional system prompt prepended to messages.
+        context :
+            Optional routing hints for the LLMRouter.
+
+        Returns
+        -------
+        ReasoningResult
+            The final response, or a needs_tool signal if the budget
+            ran out mid-iteration.
+        """
+        turn_id = str(uuid.uuid4())[:8]
+        log_prefix = f"[reasoning:{turn_id}]"
+
+        # Build the working message list
+        working = []
+        if system_prompt:
+            working.append({"role": "system", "content": system_prompt})
+        working.extend(_messages_to_dicts(messages))
+
+        # Build tool definitions for the LLM call
+        try:
+            tool_defs = self._tools.get_definitions(available_tools)
+        except ToolRegistryError as exc:
+            logger.error(
+                "%s tool registry failed closed: %s: %s",
+                log_prefix,
+                exc.code,
+                exc,
+            )
+            return ReasoningResult(
+                status="error",
+                error=f"{exc.code}: {exc}",
+            )
+        allowed_tool_names = (
+            None if available_tools is None else frozenset(available_tools)
+        )
+
+        iterations = 0
+        last_usage: dict[str, Any] = {}
+        cumulative_usage: dict[str, int] = {
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "total_tokens": 0,
+        }
+        model_provenance: dict[str, Any] = {}
+
+        while iterations < self._config.max_iterations:
+            iterations += 1
+            logger.debug(
+                "%s iteration %d/%d — %d messages, %d tools",
+                log_prefix,
+                iterations,
+                self._config.max_iterations,
+                len(working),
+                len(tool_defs),
+            )
+
+            # Call the LLM
+            try:
+                tier_hint = model_override or self._config.force_tier
+                if isinstance(tier_hint, str):
+                    from apsimo.router.tiers import ModelTier
+                    try:
+                        tier_hint = ModelTier(tier_hint)
+                    except ValueError:
+                        tier_hint = None
+                response = await self._model.complete(
+                    working,
+                    tools=tool_defs if tool_defs else None,
+                    force_tier=tier_hint,
+                    context=context or {},
+                )
+            except Exception as exc:
+                logger.error("%s LLM call failed: %s", log_prefix, exc)
+                return ReasoningResult(
+                    status="error",
+                    error=f"LLM call failed: {exc}",
+                    model_provenance=model_provenance,
+                )
+
+            # Accumulate usage
+            used = getattr(response, 'tier_used', None)
+            model_provenance = {'model_role': getattr(response, 'function_role', '') or getattr(used, 'value', str(used or 'unknown')),
+                'model_id': getattr(response, 'model_id', 'unknown'),
+                'model_revision': getattr(response, 'model_revision', 'unknown'),
+                'config_revision': getattr(response, 'config_revision', '') or 'unknown',
+                'basis': 'last_successful_model_response'}
+            last_usage = dict(response.usage)
+            for k in cumulative_usage:
+                cumulative_usage[k] += last_usage.get(k, 0)
+
+            # Extract the assistant's response
+            raw = response.raw
+            assistant_content = response.content or ""
+            tool_calls_raw = self._extract_tool_calls(raw)
+
+            if not tool_calls_raw:
+                # No tool calls — the LLM is done
+                return ReasoningResult(
+                    status="completed",
+                    message={
+                        "role": "assistant",
+                        "content": assistant_content,
+                    },
+                    usage=cumulative_usage,
+                    model_provenance=model_provenance,
+                )
+
+            # Tool calls — execute them
+            logger.debug(
+                "%s LLM requested %d tool calls",
+                log_prefix,
+                len(tool_calls_raw),
+            )
+
+            # Add assistant message with tool calls to working history
+            working.append(self._build_assistant_message(raw, assistant_content, tool_calls_raw))
+
+            # Execute tool calls
+            tool_delay = self._config.tool_delay_seconds
+            if tool_delay > 0:
+                await asyncio.sleep(tool_delay)
+
+            try:
+                tool_results = await self._tools.execute_batch(
+                    tool_calls_raw,
+                    session_id=session_id,
+                    allowed_tools=allowed_tool_names,
+                    actor_policy=actor_policy,
+                )
+            except Exception as exc:
+                logger.error("%s tool execution failed: %s", log_prefix, exc)
+                # Return what we have — the host can decide what to do
+                return ReasoningResult(
+                    status="error",
+                    message={
+                        "role": "assistant",
+                        "content": assistant_content or f"Tool execution error: {exc}",
+                    },
+                    tool_calls=tool_calls_raw,
+                    usage=cumulative_usage,
+                    error=f"Tool execution failed: {exc}",
+                    model_provenance=model_provenance,
+                )
+
+            # Append tool results to working history
+            for result in tool_results:
+                working.append({
+                    "role": "tool",
+                    "tool_call_id": result["tool_call_id"],
+                    "content": result["content"],
+                })
+
+        # Budget exhausted — return needs_tool with pending calls
+        logger.warning(
+            "%s budget exhausted after %d iterations",
+            log_prefix,
+            iterations,
+        )
+        return ReasoningResult(
+            status="needs_tool",
+            message={
+                "role": "assistant",
+                "content": assistant_content,
+            },
+            tool_calls=tool_calls_raw,
+            usage=cumulative_usage,
+            model_provenance=model_provenance,
+        )
+
+    @staticmethod
+    def _extract_tool_calls(raw_response: Any) -> list[dict[str, Any]]:
+        """Extract tool calls from a LiteLLM response object.
+
+        Returns a list of dicts with keys: id, name, arguments.
+        """
+        if raw_response is None:
+            return []
+
+        # LiteLLM / OpenAI response format
+        choices = getattr(raw_response, "choices", None)
+        if not choices:
+            return []
+
+        message = getattr(choices[0], "message", None)
+        if message is None:
+            return []
+
+        raw_calls = getattr(message, "tool_calls", None)
+        if not raw_calls:
+            return []
+
+        result = []
+        for tc in raw_calls:
+            tc_id = getattr(tc, "id", None) or str(uuid.uuid4())
+            func = getattr(tc, "function", None)
+            if func is None:
+                continue
+            name = getattr(func, "name", "unknown")
+            try:
+                arguments = json.loads(getattr(func, "arguments", "{}"))
+            except (json.JSONDecodeError, TypeError):
+                arguments = {}
+
+            result.append({
+                "id": tc_id,
+                "name": name,
+                "arguments": arguments,
+            })
+
+        return result
+
+    @staticmethod
+    def _build_assistant_message(
+        raw_response: Any,
+        content: str,
+        tool_calls: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Build an assistant message dict that includes tool calls.
+
+        This preserves the tool call structure in the conversation
+        history so the LLM can see its own prior tool calls.
+        """
+        msg: dict[str, Any] = {"role": "assistant"}
+
+        if content:
+            msg["content"] = content
+        else:
+            msg["content"] = None
+
+        if tool_calls:
+            msg["tool_calls"] = [
+                {
+                    "id": tc["id"],
+                    "type": "function",
+                    "function": {
+                        "name": tc["name"],
+                        "arguments": (
+                            tc["arguments"]
+                            if isinstance(tc["arguments"], str)
+                            else json.dumps(tc["arguments"])
+                        ),
+                    },
+                }
+                for tc in tool_calls
+            ]
+
+        return msg

apsimo/reasoning/native_tools/__init__.py

@@ -0,0 +1,16 @@
+"""Native tool handlers for Colony's reasoning loop.
+
+These tools run inside Colony without requiring a host harness roundtrip.
+"""
+
+from apsimo.reasoning.native_tools.calculate import CalculateTool
+from apsimo.reasoning.native_tools.web_search import WebSearchTool
+from apsimo.reasoning.native_tools.file_ops import ReadFileTool, WriteFileTool, ListDirectoryTool
+
+__all__ = [
+    "CalculateTool",
+    "WebSearchTool",
+    "ReadFileTool",
+    "WriteFileTool",
+    "ListDirectoryTool",
+]

apsimo/reasoning/native_tools/calculate.py

@@ -0,0 +1,141 @@
+"""Safe math evaluation tool — no eval(), no exec()."""
+
+from __future__ import annotations
+
+import ast
+import logging
+import operator
+from typing import Any, Dict
+
+logger = logging.getLogger(__name__)
+
+ALLOWED_NAMES = {
+    "abs": abs, "round": round, "min": min, "max": max,
+    "sum": sum, "len": len, "int": int, "float": float,
+    "pow": pow, "divmod": divmod, "sorted": sorted,
+    "True": True, "False": False, "None": None,
+}
+
+BIN_OPS = {
+    ast.Add: operator.add, ast.Sub: operator.sub,
+    ast.Mult: operator.mul, ast.Div: operator.truediv,
+    ast.Mod: operator.mod, ast.Pow: operator.pow,
+    ast.FloorDiv: operator.floordiv,
+}
+
+COMPARE_OPS = {
+    ast.Eq: operator.eq, ast.NotEq: operator.ne,
+    ast.Lt: operator.lt, ast.LtE: operator.le,
+    ast.Gt: operator.gt, ast.GtE: operator.ge,
+}
+
+UNARY_OPS = {
+    ast.USub: operator.neg,
+    ast.UAdd: operator.pos,
+    ast.Not: operator.not_,
+}
+
+
+class CalculateTool:
+    """Safe math expression evaluator using AST parsing.
+
+    No eval(), no exec(). Only numeric operations allowed.
+    """
+
+    @property
+    def name(self) -> str:
+        return "calculate"
+
+    @property
+    def schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "expression": {
+                    "type": "string",
+                    "description": "Math expression to evaluate (e.g., '2 + 2', 'abs(-5) * 3')",
+                },
+            },
+            "required": ["expression"],
+        }
+
+    async def execute(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        expression = args.get("expression", "")
+        if not expression:
+            return {"error": True, "message": "No expression provided"}
+
+        try:
+            tree = ast.parse(expression, mode="eval")
+            result = self._eval_node(tree.body)
+            return {"result": result, "expression": expression}
+        except (ValueError, TypeError, SyntaxError, ZeroDivisionError) as e:
+            return {"error": True, "message": str(e), "expression": expression}
+        except Exception as e:
+            return {"error": True, "message": f"Cannot evaluate: {e}", "expression": expression}
+
+    def _eval_node(self, node: ast.AST) -> Any:
+        # Constants (numbers, strings)
+        if isinstance(node, ast.Constant):
+            return node.value
+
+        # Names (functions, constants)
+        if isinstance(node, ast.Name):
+            if node.id in ALLOWED_NAMES:
+                return ALLOWED_NAMES[node.id]
+            raise ValueError(f"Name not allowed: {node.id}")
+
+        # Binary operations
+        if isinstance(node, ast.BinOp):
+            left = self._eval_node(node.left)
+            right = self._eval_node(node.right)
+            op_type = type(node.op)
+            if op_type in BIN_OPS:
+                return BIN_OPS[op_type](left, right)
+            raise ValueError(f"Binary operation not allowed: {op_type.__name__}")
+
+        # Unary operations
+        if isinstance(node, ast.UnaryOp):
+            operand = self._eval_node(node.operand)
+            op_type = type(node.op)
+            if op_type in UNARY_OPS:
+                return UNARY_OPS[op_type](operand)
+            raise ValueError(f"Unary operation not allowed: {op_type.__name__}")
+
+        # Comparisons
+        if isinstance(node, ast.Compare):
+            left = self._eval_node(node.left)
+            for op, comparator in zip(node.ops, node.comparators):
+                right = self._eval_node(comparator)
+                op_type = type(op)
+                if op_type in COMPARE_OPS:
+                    if not COMPARE_OPS[op_type](left, right):
+                        return False
+                    left = right
+                else:
+                    raise ValueError(f"Comparison not allowed: {op_type.__name__}")
+            return True
+
+        # Function calls (abs, round, min, max, etc.)
+        if isinstance(node, ast.Call):
+            func = self._eval_node(node.func)
+            call_args = [self._eval_node(a) for a in node.args]
+            # Reject keyword arguments for safety
+            if node.keywords:
+                raise ValueError("Keyword arguments not allowed")
+            return func(*call_args)
+
+        # Subscripts (list[0])
+        if isinstance(node, ast.Subscript):
+            value = self._eval_node(node.value)
+            slice_val = self._eval_node(node.slice) if isinstance(node.slice, ast.AST) else node.slice
+            return value[slice_val]
+
+        # Lists
+        if isinstance(node, ast.List):
+            return [self._eval_node(e) for e in node.elts]
+
+        # Tuples
+        if isinstance(node, ast.Tuple):
+            return tuple(self._eval_node(e) for e in node.elts)
+
+        raise ValueError(f"Operation not allowed: {type(node).__name__}")

apsimo/reasoning/native_tools/file_ops.py

@@ -0,0 +1,150 @@
+"""Sandboxed file operation tools."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class ReadFileTool:
+    """Read files from a sandboxed directory."""
+
+    def __init__(self, sandbox_dir: str = ""):
+        self._sandbox = Path(sandbox_dir).resolve() if sandbox_dir else None
+
+    @property
+    def name(self) -> str:
+        return "read_file"
+
+    @property
+    def schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "File path relative to sandbox"},
+            },
+            "required": ["path"],
+        }
+
+    async def execute(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        if not self._sandbox:
+            return {"error": True, "message": "File sandbox not configured"}
+
+        path = args.get("path", "")
+        try:
+            resolved = self._resolve_safe(path)
+            if not resolved.exists():
+                return {"error": True, "message": f"File not found: {path}"}
+            if resolved.is_dir():
+                return {"error": True, "message": f"Path is a directory: {path}"}
+            content = resolved.read_text(errors="replace")
+            return {"content": content, "path": str(resolved.relative_to(self._sandbox)), "size": len(content)}
+        except ValueError as e:
+            return {"error": True, "message": str(e)}
+
+    def _resolve_safe(self, path: str) -> Path:
+        """Resolve path within sandbox — reject path traversal."""
+        if not self._sandbox:
+            raise ValueError("Sandbox not configured")
+        resolved = (self._sandbox / path).resolve()
+        if not str(resolved).startswith(str(self._sandbox)):
+            raise ValueError("Path traversal detected")
+        return resolved
+
+
+class WriteFileTool:
+    """Write files to a sandboxed directory."""
+
+    def __init__(self, sandbox_dir: str = ""):
+        self._sandbox = Path(sandbox_dir).resolve() if sandbox_dir else None
+
+    @property
+    def name(self) -> str:
+        return "write_file"
+
+    @property
+    def schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "File path relative to sandbox"},
+                "content": {"type": "string", "description": "Content to write"},
+            },
+            "required": ["path", "content"],
+        }
+
+    async def execute(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        if not self._sandbox:
+            return {"error": True, "message": "File sandbox not configured"}
+
+        path = args.get("path", "")
+        content = args.get("content", "")
+        try:
+            resolved = self._resolve_safe(path)
+            resolved.parent.mkdir(parents=True, exist_ok=True)
+            resolved.write_text(content)
+            return {"path": str(resolved.relative_to(self._sandbox)), "size": len(content), "written": True}
+        except ValueError as e:
+            return {"error": True, "message": str(e)}
+
+    def _resolve_safe(self, path: str) -> Path:
+        if not self._sandbox:
+            raise ValueError("Sandbox not configured")
+        resolved = (self._sandbox / path).resolve()
+        if not str(resolved).startswith(str(self._sandbox)):
+            raise ValueError("Path traversal detected")
+        return resolved
+
+
+class ListDirectoryTool:
+    """List files in a sandboxed directory."""
+
+    def __init__(self, sandbox_dir: str = ""):
+        self._sandbox = Path(sandbox_dir).resolve() if sandbox_dir else None
+
+    @property
+    def name(self) -> str:
+        return "list_directory"
+
+    @property
+    def schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Directory path relative to sandbox (default: root)", "default": ""},
+            },
+        }
+
+    async def execute(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        if not self._sandbox:
+            return {"error": True, "message": "File sandbox not configured"}
+
+        path = args.get("path", "")
+        try:
+            resolved = self._resolve_safe(path)
+            if not resolved.exists():
+                return {"error": True, "message": f"Directory not found: {path}"}
+            if not resolved.is_dir():
+                return {"error": True, "message": f"Not a directory: {path}"}
+
+            entries = []
+            for p in sorted(resolved.iterdir()):
+                entries.append({
+                    "name": p.name,
+                    "type": "directory" if p.is_dir() else "file",
+                    "size": p.stat().st_size if p.is_file() else None,
+                })
+            return {"path": path or "/", "entries": entries, "count": len(entries)}
+        except ValueError as e:
+            return {"error": True, "message": str(e)}
+
+    def _resolve_safe(self, path: str) -> Path:
+        if not self._sandbox:
+            raise ValueError("Sandbox not configured")
+        resolved = (self._sandbox / path).resolve() if path else self._sandbox
+        if not str(resolved).startswith(str(self._sandbox)):
+            raise ValueError("Path traversal detected")
+        return resolved