toolproxy 0.1.0__py3-none-any.whl

toolproxy/__init__.py

@@ -0,0 +1,90 @@
+"""
+toolproxy — Universal Tool-Calling Wrapper for Non-Tool-Native LLMs.
+
+Public API:
+    UniversalAgent  — main agent class
+    tool            — decorator to mark callables as tools
+    ToolRegistry    — registry for managing tools
+    AgentResponse   — returned by UniversalAgent.run()
+    AgentTrace      — full debug trace
+    Message         — conversation message
+    ToolCall        — a single tool invocation
+    ToolResult      — outcome of a tool execution
+    Action          — emulated-mode structured output
+
+Exceptions:
+    UniversalAgentError
+    ToolNotFoundError
+    ToolExecutionError
+    MaxStepsExceededError
+    SchemaValidationError
+    ModelError
+    ExecutionPolicyError
+"""
+from .agent import UniversalAgent
+from .config import AgentConfig, ExecutionPolicy
+from .exceptions import (
+    ExecutionPolicyError,
+    MaxStepsExceededError,
+    ModelError,
+    SchemaValidationError,
+    ToolExecutionError,
+    ToolNotFoundError,
+    UniversalAgentError,
+)
+from .llm_client import (
+    LLMClient,
+    MockClient,
+    ModelResponse,
+    OllamaClient,
+    OpenAIClient,
+    OpenRouterClient,
+    get_client,
+)
+from .schemas import (
+    Action,
+    AgentResponse,
+    AgentTrace,
+    Message,
+    ToolCall,
+    ToolResult,
+    TraceEntry,
+)
+from .tools import ToolDefinition, ToolRegistry, tool
+
+__all__ = [
+    # Main API
+    "UniversalAgent",
+    "tool",
+    "ToolRegistry",
+    "ToolDefinition",
+    # Config
+    "AgentConfig",
+    "ExecutionPolicy",
+    # Schemas
+    "Action",
+    "AgentResponse",
+    "AgentTrace",
+    "Message",
+    "ToolCall",
+    "ToolResult",
+    "TraceEntry",
+    # Clients
+    "LLMClient",
+    "ModelResponse",
+    "OpenRouterClient",
+    "OpenAIClient",
+    "OllamaClient",
+    "MockClient",
+    "get_client",
+    # Exceptions
+    "UniversalAgentError",
+    "ToolNotFoundError",
+    "ToolExecutionError",
+    "MaxStepsExceededError",
+    "SchemaValidationError",
+    "ModelError",
+    "ExecutionPolicyError",
+]
+
+__version__ = "0.1.0"

toolproxy/agent.py

@@ -0,0 +1,184 @@
+"""
+UniversalAgent — the main developer-facing API for toolproxy.
+
+Usage::
+
+    from toolproxy import UniversalAgent, tool
+
+    @tool
+    def get_weather(city: str) -> str:
+        \"\"\"Get the current weather for a city.\"\"\"
+        return f"Sunny, 25°C in {city}"
+
+    agent = UniversalAgent(
+        model="openrouter/mistralai/mistral-7b-instruct",
+        tools=[get_weather],
+    )
+
+    result = agent.run("What is the weather in Chennai?")
+    print(result.content)
+
+    # With trace
+    result = agent.run("...", return_trace=True)
+    for call in result.trace.tool_calls:
+        print(call.tool_name, call.arguments)
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Callable, List, Literal, Optional, Union
+
+from .config import AgentConfig, ExecutionPolicy
+from .executor import Executor
+from .llm_client import LLMClient, get_client
+from .loop import LoopController
+from .planner import Planner
+from .schemas import AgentResponse, Message
+from .tools import ToolRegistry
+
+
+class UniversalAgent:
+    """
+    Universal tool-calling wrapper that works with any LLM provider.
+
+    Automatically detects whether the underlying model supports native tool
+    calling and falls back to structured-output emulation when it does not.
+
+    Parameters
+    ----------
+    model : str
+        Model identifier. Prefix with:
+        - ``openrouter/`` for OpenRouter models.
+        - ``ollama/`` for local Ollama models.
+        - ``mock/`` for unit tests.
+        - No prefix for direct OpenAI-compatible endpoints.
+    tools : list
+        List of @tool-decorated callables to register.
+    mode : "auto" | "native_only" | "emulated_only"
+        Override capability detection. Defaults to "auto".
+    max_steps : int
+        Maximum loop iterations before raising MaxStepsExceededError.
+    api_key : str, optional
+        API key. Falls back to OPENROUTER_API_KEY / OPENAI_API_KEY env vars.
+    base_url : str, optional
+        Override the provider base URL.
+    execution_policy : ExecutionPolicy, optional
+        Controls which tools may be called.
+    client : LLMClient, optional
+        Inject a pre-built LLMClient (useful for testing).
+    """
+
+    def __init__(
+        self,
+        model: str,
+        tools: Optional[List[Any]] = None,
+        mode: Literal["auto", "native_only", "emulated_only"] = "auto",
+        max_steps: int = 10,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        execution_policy: Optional[ExecutionPolicy] = None,
+        client: Optional[LLMClient] = None,
+    ) -> None:
+        self._config = AgentConfig(
+            model=model,
+            api_key=api_key,
+            base_url=base_url,
+            mode=mode,
+            max_steps=max_steps,
+            execution_policy=execution_policy or ExecutionPolicy(),
+        )
+
+        # Build or use provided LLM client
+        self._client: LLMClient = client or get_client(
+            model=model,
+            api_key=api_key,
+            base_url=base_url,
+        )
+
+        # Build tool registry
+        self._registry = ToolRegistry()
+        for t in (tools or []):
+            self._registry.register(t)
+
+        # Build planner, executor, loop controller
+        self._planner = Planner(
+            client=self._client,
+            registry=self._registry,
+            mode=mode,
+            parse_retries=self._config.parse_retries,
+        )
+        self._executor = Executor(
+            registry=self._registry,
+            policy=execution_policy,
+        )
+        self._loop = LoopController(
+            planner=self._planner,
+            executor=self._executor,
+            max_steps=max_steps,
+        )
+
+    # ------------------------------------------------------------------
+    # Main API
+    # ------------------------------------------------------------------
+
+    def run(
+        self,
+        prompt_or_messages: Union[str, List[Message]],
+        return_trace: bool = False,
+        on_tool_call: Optional[Callable] = None,
+        on_tool_result: Optional[Callable] = None,
+        on_model_output: Optional[Callable] = None,
+    ) -> AgentResponse:
+        """
+        Run the agent on *prompt_or_messages* and return an AgentResponse.
+
+        Parameters
+        ----------
+        prompt_or_messages :
+            Either a plain string (treated as a user message) or a list of
+            Message objects representing an existing conversation.
+        return_trace :
+            If True, the returned AgentResponse will include a full trace
+            of all tool calls and results.
+        on_tool_call / on_tool_result / on_model_output :
+            Optional streaming callbacks.
+        """
+        if isinstance(prompt_or_messages, str):
+            messages: List[Message] = [Message(role="user", content=prompt_or_messages)]
+        else:
+            messages = list(prompt_or_messages)
+
+        # Update loop controller with current return_trace setting
+        self._loop._return_trace = return_trace
+
+        return self._loop.run(
+            messages=messages,
+            on_tool_call=on_tool_call,
+            on_tool_result=on_tool_result,
+            on_model_output=on_model_output,
+        )
+
+    # ------------------------------------------------------------------
+    # Convenience properties
+    # ------------------------------------------------------------------
+
+    @property
+    def model(self) -> str:
+        return self._config.model
+
+    @property
+    def uses_native_tools(self) -> bool:
+        """True if the planner is running in native tool-calling mode."""
+        return self._planner.use_native
+
+    @property
+    def registry(self) -> ToolRegistry:
+        """Access the internal ToolRegistry (read-only by convention)."""
+        return self._registry
+
+    def __repr__(self) -> str:
+        mode_str = "native" if self.uses_native_tools else "emulated"
+        return (
+            f"UniversalAgent(model={self.model!r}, "
+            f"tools={len(self._registry)}, mode={mode_str})"
+        )

toolproxy/config.py

@@ -0,0 +1,98 @@
+"""
+Configuration for toolproxy.
+
+Includes AgentConfig and the MODEL_TOOL_SUPPORT capability map.
+"""
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+# ---------------------------------------------------------------------------
+# Execution policy constants
+# ---------------------------------------------------------------------------
+POLICY_ALLOW_ALL = "allow_all"
+POLICY_ALLOW_ONLY = "allow_only"
+POLICY_CONFIRM_BEFORE = "confirm_before"
+
+# ---------------------------------------------------------------------------
+# Known model → native tool-calling support map
+# Models not listed here default to False (emulated mode).
+# Keys use lowercase and may include partial prefixes.
+# ---------------------------------------------------------------------------
+MODEL_TOOL_SUPPORT: dict[str, bool] = {
+    # OpenAI
+    "gpt-4o": True,
+    "gpt-4o-mini": True,
+    "gpt-4-turbo": True,
+    "gpt-4": True,
+    "gpt-3.5-turbo": True,
+    # Anthropic (via OpenRouter or direct)
+    "claude-3-5-sonnet": True,
+    "claude-3-5-haiku": True,
+    "claude-3-opus": True,
+    "claude-3-sonnet": True,
+    "claude-3-haiku": True,
+    # Google (via OpenRouter)
+    "gemini-pro": True,
+    "gemini-1.5-pro": True,
+    "gemini-1.5-flash": True,
+    # Meta / Llama (typically no native tool calling through OpenRouter free tier)
+    "llama-3": False,
+    "llama-2": False,
+    "mistral": False,
+    "mixtral": False,
+    # Qwen / DeepSeek free tier
+    "deepseek": False,
+    "qwen": False,
+}
+
+
+def model_supports_native_tools(model: str) -> bool:
+    """
+    Check whether *model* supports native tool/function calling.
+
+    Performs a case-insensitive substring search against MODEL_TOOL_SUPPORT.
+    Returns False for unknown models (safe default → emulated mode).
+    """
+    lower = model.lower()
+    for key, supported in MODEL_TOOL_SUPPORT.items():
+        if key in lower:
+            return supported
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Agent configuration
+# ---------------------------------------------------------------------------
+
+class ExecutionPolicy(BaseModel):
+    """Defines what tools the executor is allowed to run."""
+
+    mode: Literal["allow_all", "allow_only", "confirm_before"] = "allow_all"
+    allowed_tools: list[str] = Field(default_factory=list)
+    confirm_tools: list[str] = Field(default_factory=list)
+
+
+class AgentConfig(BaseModel):
+    """Full configuration for a UniversalAgent instance."""
+
+    model: str
+    api_key: str | None = None
+    base_url: str | None = None
+
+    # Capability override
+    mode: Literal["auto", "native_only", "emulated_only"] = "auto"
+
+    # Loop settings
+    max_steps: int = Field(default=10, ge=1)
+
+    # Execution policy
+    execution_policy: ExecutionPolicy = Field(default_factory=ExecutionPolicy)
+
+    # Tracing
+    return_trace: bool = False
+
+    # Retry attempts for schema parsing in emulated mode
+    parse_retries: int = Field(default=3, ge=1)

toolproxy/exceptions.py

@@ -0,0 +1,58 @@
+"""
+Custom exceptions for toolproxy.
+"""
+
+
+class UniversalAgentError(Exception):
+    """Base exception for all toolproxy errors."""
+
+
+class ToolNotFoundError(UniversalAgentError):
+    """Raised when a requested tool is not in the registry."""
+
+    def __init__(self, tool_name: str) -> None:
+        super().__init__(f"Tool '{tool_name}' not found in registry.")
+        self.tool_name = tool_name
+
+
+class ToolExecutionError(UniversalAgentError):
+    """Raised when a tool callable raises an exception during execution."""
+
+    def __init__(self, tool_name: str, cause: Exception) -> None:
+        super().__init__(f"Tool '{tool_name}' raised an error: {cause}")
+        self.tool_name = tool_name
+        self.cause = cause
+
+
+class MaxStepsExceededError(UniversalAgentError):
+    """Raised when the agent loop exceeds max_steps without a final answer."""
+
+    def __init__(self, max_steps: int) -> None:
+        super().__init__(
+            f"Agent did not produce a final answer within {max_steps} step(s)."
+        )
+        self.max_steps = max_steps
+
+
+class SchemaValidationError(UniversalAgentError):
+    """Raised when the model's output cannot be validated against the Action schema."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(f"Schema validation failed: {message}")
+
+
+class ModelError(UniversalAgentError):
+    """Raised when the underlying LLM returns an error or unexpected response."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(f"Model error: {message}")
+
+
+class ExecutionPolicyError(UniversalAgentError):
+    """Raised when a tool is blocked by the execution policy."""
+
+    def __init__(self, tool_name: str) -> None:
+        super().__init__(
+            f"Tool '{tool_name}' is blocked by the current execution policy."
+        )
+        self.tool_name = tool_name

toolproxy/executor.py

@@ -0,0 +1,123 @@
+"""
+Executor module for toolproxy.
+
+Validates tool arguments and executes tool callables with policy enforcement.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, List, Optional
+
+from pydantic import ValidationError
+
+from .config import ExecutionPolicy, POLICY_ALLOW_ALL, POLICY_ALLOW_ONLY, POLICY_CONFIRM_BEFORE
+from .exceptions import ExecutionPolicyError, ToolExecutionError, ToolNotFoundError
+from .schemas import ToolCall, ToolResult
+from .tools import ToolRegistry
+
+
+class Executor:
+    """
+    Executes ToolCall objects against the registry, with policy enforcement.
+
+    Execution policies:
+    - allow_all          — any tool may be called.
+    - allow_only([...])  — only tools in the allow-list may be called.
+    - confirm_before([...]) — prompt user for confirmation before listed tools;
+                              in non-interactive mode these are blocked.
+    """
+
+    def __init__(
+        self,
+        registry: ToolRegistry,
+        policy: Optional[ExecutionPolicy] = None,
+        confirm_callback: Optional[Callable[[str, dict], bool]] = None,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        registry:
+            The ToolRegistry to look up tools from.
+        policy:
+            Execution policy (defaults to allow_all).
+        confirm_callback:
+            Called for confirm_before tools. Receives (tool_name, arguments).
+            Should return True to allow, False to block.
+            If None, confirm_before tools are blocked (safe default).
+        """
+        self._registry = registry
+        self._policy = policy or ExecutionPolicy()
+        self._confirm_callback = confirm_callback
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def execute(self, tool_call: ToolCall) -> ToolResult:
+        """
+        Validate and execute *tool_call*.
+
+        Returns a ToolResult (success or error); never raises on tool errors.
+        Raises ExecutionPolicyError / ToolNotFoundError before execution.
+        """
+        # 1. Check policy
+        self._check_policy(tool_call.tool_name, tool_call.arguments)
+
+        # 2. Look up tool
+        try:
+            defn = self._registry.get(tool_call.tool_name)
+        except ToolNotFoundError:
+            raise
+
+        # 3. Validate arguments
+        try:
+            validated_args = defn.args_schema.model_validate(tool_call.arguments)
+        except ValidationError as exc:
+            return ToolResult(
+                tool_name=tool_call.tool_name,
+                call_id=tool_call.call_id,
+                error=f"Argument validation failed: {exc}",
+            )
+
+        # 4. Execute the callable
+        try:
+            output = defn.callable(**validated_args.model_dump())
+        except Exception as exc:
+            return ToolResult(
+                tool_name=tool_call.tool_name,
+                call_id=tool_call.call_id,
+                error=f"Tool raised exception: {type(exc).__name__}: {exc}",
+            )
+
+        return ToolResult(
+            tool_name=tool_call.tool_name,
+            call_id=tool_call.call_id,
+            output=str(output),
+        )
+
+    def execute_many(self, tool_calls: List[ToolCall]) -> List[ToolResult]:
+        """Execute a list of tool calls sequentially, collecting all results."""
+        return [self.execute(tc) for tc in tool_calls]
+
+    # ------------------------------------------------------------------
+    # Policy enforcement
+    # ------------------------------------------------------------------
+
+    def _check_policy(self, tool_name: str, arguments: dict) -> None:
+        mode = self._policy.mode
+
+        if mode == POLICY_ALLOW_ALL:
+            return
+
+        if mode == POLICY_ALLOW_ONLY:
+            if tool_name not in self._policy.allowed_tools:
+                raise ExecutionPolicyError(tool_name)
+            return
+
+        if mode == POLICY_CONFIRM_BEFORE:
+            if tool_name in self._policy.confirm_tools:
+                if self._confirm_callback is None:
+                    raise ExecutionPolicyError(tool_name)
+                allowed = self._confirm_callback(tool_name, arguments)
+                if not allowed:
+                    raise ExecutionPolicyError(tool_name)
+            return