toolproxy 0.1.0__tar.gz → 0.2.0__tar.gz

{toolproxy-0.1.0 → toolproxy-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toolproxy
-Version: 0.1.0
+Version: 0.2.0
 Summary: Universal tool-calling wrapper for non-tool-native LLMs — emulates function calling via structured JSON planning
 Project-URL: Homepage, https://github.com/yourusername/toolproxy
 Project-URL: Repository, https://github.com/yourusername/toolproxy

{toolproxy-0.1.0 → toolproxy-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "toolproxy"
-version = "0.1.0"
+version = "0.2.0"
 description = "Universal tool-calling wrapper for non-tool-native LLMs — emulates function calling via structured JSON planning"
 readme = "README.md"
 requires-python = ">=3.10"

{toolproxy-0.1.0 → toolproxy-0.2.0}/src/toolproxy/__init__.py

@@ -5,12 +5,16 @@ Public API:
     UniversalAgent  — main agent class
     tool            — decorator to mark callables as tools
     ToolRegistry    — registry for managing tools
-    AgentResponse   — returned by UniversalAgent.run()
+    AgentResponse   — returned by UniversalAgent.run() / arun()
     AgentTrace      — full debug trace
     Message         — conversation message
     ToolCall        — a single tool invocation
     ToolResult      — outcome of a tool execution
     Action          — emulated-mode structured output
+    StreamChunk     — (v0.2) streaming event from agent.stream()
+
+Utilities:
+    probe_tool_support — (v0.2) async helper to detect native tool support
 
 Exceptions:
     UniversalAgentError
@@ -22,7 +26,7 @@ Exceptions:
     ExecutionPolicyError
 """
 from .agent import UniversalAgent
-from .config import AgentConfig, ExecutionPolicy
+from .config import AgentConfig, ExecutionPolicy, probe_tool_support
 from .exceptions import (
     ExecutionPolicyError,
     MaxStepsExceededError,
@@ -46,6 +50,7 @@ from .schemas import (
     AgentResponse,
     AgentTrace,
     Message,
+    StreamChunk,
     ToolCall,
     ToolResult,
     TraceEntry,
@@ -61,11 +66,13 @@ __all__ = [
     # Config
     "AgentConfig",
     "ExecutionPolicy",
+    "probe_tool_support",
     # Schemas
     "Action",
     "AgentResponse",
     "AgentTrace",
     "Message",
+    "StreamChunk",
     "ToolCall",
     "ToolResult",
     "TraceEntry",
@@ -87,4 +94,4 @@ __all__ = [
     "ExecutionPolicyError",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{toolproxy-0.1.0 → toolproxy-0.2.0}/src/toolproxy/agent.py

@@ -15,9 +15,21 @@ Usage::
         tools=[get_weather],
     )
 
+    # Synchronous (unchanged API)
     result = agent.run("What is the weather in Chennai?")
     print(result.content)
 
+    # Async (new in v0.2)
+    result = await agent.arun("What is the weather in Chennai?")
+    print(result.content)
+
+    # Streaming (new in v0.2)
+    async for chunk in agent.stream("What is the weather in Chennai?"):
+        if chunk.done:
+            print()
+        else:
+            print(chunk.delta, end="", flush=True)
+
     # With trace
     result = agent.run("...", return_trace=True)
     for call in result.trace.tool_calls:
@@ -26,14 +38,14 @@ Usage::
 from __future__ import annotations
 
 import os
-from typing import Any, Callable, List, Literal, Optional, Union
+from typing import Any, AsyncIterator, 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 .schemas import AgentResponse, Message, StreamChunk
 from .tools import ToolRegistry
 
 
@@ -118,7 +130,7 @@ class UniversalAgent:
         )
 
     # ------------------------------------------------------------------
-    # Main API
+    # Synchronous API (backwards-compatible)
     # ------------------------------------------------------------------
 
     def run(
@@ -158,6 +170,82 @@ class UniversalAgent:
             on_model_output=on_model_output,
         )
 
+    # ------------------------------------------------------------------
+    # Async API (new in v0.2)
+    # ------------------------------------------------------------------
+
+    async def arun(
+        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:
+        """
+        Async version of ``run``.
+
+        Uses non-blocking I/O throughout and dispatches multiple tool calls
+        in parallel via asyncio.gather when the model requests them.
+
+        Parameters
+        ----------
+        prompt_or_messages :
+            Either a plain string or a list of Message objects.
+        return_trace :
+            If True, the response includes a full execution trace.
+        on_tool_call / on_tool_result / on_model_output :
+            Optional callbacks (called synchronously mid-loop).
+        """
+        if isinstance(prompt_or_messages, str):
+            messages: List[Message] = [Message(role="user", content=prompt_or_messages)]
+        else:
+            messages = list(prompt_or_messages)
+
+        self._loop._return_trace = return_trace
+
+        return await self._loop.arun(
+            messages=messages,
+            on_tool_call=on_tool_call,
+            on_tool_result=on_tool_result,
+            on_model_output=on_model_output,
+        )
+
+    # ------------------------------------------------------------------
+    # Streaming API (new in v0.2)
+    # ------------------------------------------------------------------
+
+    def stream(
+        self,
+        prompt_or_messages: Union[str, List[Message]],
+    ) -> AsyncIterator[StreamChunk]:
+        """
+        Stream the agent's execution as an async iterator of StreamChunk events.
+
+        Usage::
+
+            async for chunk in agent.stream("What's the weather in Chennai?"):
+                if chunk.done:
+                    print()  # newline after streaming
+                elif chunk.tool_call:
+                    print(f"\\n[calling {chunk.tool_call.tool_name}]")
+                elif chunk.tool_result:
+                    print(f"\\n[result: {chunk.tool_result.output}]")
+                else:
+                    print(chunk.delta, end="", flush=True)
+
+        Yields
+        ------
+        StreamChunk
+            One chunk per event: text token, tool call, tool result, or done.
+        """
+        if isinstance(prompt_or_messages, str):
+            messages: List[Message] = [Message(role="user", content=prompt_or_messages)]
+        else:
+            messages = list(prompt_or_messages)
+
+        return self._loop.stream(messages)
+
     # ------------------------------------------------------------------
     # Convenience properties
     # ------------------------------------------------------------------

toolproxy-0.2.0/src/toolproxy/config.py

@@ -0,0 +1,201 @@
+"""
+Configuration for toolproxy.
+
+Includes AgentConfig, ExecutionPolicy, the MODEL_TOOL_SUPPORT capability map,
+and an async ``probe_tool_support()`` helper that can dynamically detect
+whether a model/endpoint truly supports native tool calling.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, Literal, Optional
+
+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,
+    "gemini-2": 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
+
+
+# ---------------------------------------------------------------------------
+# Dynamic capability probe
+# ---------------------------------------------------------------------------
+
+# Simple JSON cache stored alongside the package data (or the user's home dir)
+_CACHE_PATH = Path(os.environ.get("TOOLPROXY_CACHE_DIR", Path.home() / ".toolproxy")) / "capability_cache.json"
+_CACHE_TTL_SECONDS = 86_400  # 24 hours
+
+
+def _load_cache() -> Dict[str, Any]:
+    """Load the capability cache from disk, returning {} on any error."""
+    try:
+        if _CACHE_PATH.exists():
+            return json.loads(_CACHE_PATH.read_text())
+    except Exception:
+        pass
+    return {}
+
+
+def _save_cache(cache: Dict[str, Any]) -> None:
+    """Persist *cache* to disk, silently ignoring write errors."""
+    try:
+        _CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+        _CACHE_PATH.write_text(json.dumps(cache, indent=2))
+    except Exception:
+        pass
+
+
+async def probe_tool_support(
+    client: Any,  # LLMClient — circular import avoided via Any
+    cache_key: Optional[str] = None,
+    force: bool = False,
+) -> bool:
+    """
+    Dynamically probe whether *client*'s model supports native tool calling.
+
+    Strategy
+    --------
+    1. Check the in-memory / on-disk cache (TTL: 24 h) unless ``force=True``.
+    2. Send a minimal tool-schema test request (a dummy ``ping`` tool).
+    3. If the response contains tool_calls → native mode supported.
+    4. If the response is plain text or the provider returns an error
+       indicating unsupported features → emulated mode.
+    5. Cache and return the result.
+
+    Parameters
+    ----------
+    client:
+        Any LLMClient instance.
+    cache_key:
+        Optional cache key string (defaults to ``client.model``).
+    force:
+        If True, bypass the cache and always probe live.
+    """
+    from .schemas import Message  # local import to avoid circular
+
+    key = cache_key or getattr(client, "model", "unknown")
+    now = time.time()
+
+    if not force:
+        cache = _load_cache()
+        entry = cache.get(key)
+        if entry and (now - entry.get("ts", 0)) < _CACHE_TTL_SECONDS:
+            return bool(entry["supported"])
+
+    # Minimal probe: ask model to call a trivial "ping" tool
+    _PING_TOOL = [
+        {
+            "type": "function",
+            "function": {
+                "name": "ping",
+                "description": "A diagnostic ping.",
+                "parameters": {"type": "object", "properties": {}, "required": []},
+            },
+        }
+    ]
+    probe_messages = [
+        Message(role="user", content="ping"),
+    ]
+
+    supported = False
+    try:
+        response = await client.agenerate(probe_messages, tools=_PING_TOOL)
+        supported = response.has_tool_calls
+    except Exception:
+        # Any error → assume no native tool support (safe default)
+        supported = False
+
+    # Persist to cache
+    cache = _load_cache()
+    cache[key] = {"supported": supported, "ts": now}
+    _save_cache(cache)
+
+    return supported
+
+
+# ---------------------------------------------------------------------------
+# 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-0.1.0 → toolproxy-0.2.0}/src/toolproxy/executor.py

@@ -2,9 +2,14 @@
 Executor module for toolproxy.
 
 Validates tool arguments and executes tool callables with policy enforcement.
+
+Supports both synchronous execution (execute / execute_many) and async
+parallel execution (aexecute / aexecute_many) via asyncio.gather.
 """
 from __future__ import annotations
 
+import asyncio
+import inspect
 from typing import Any, Callable, List, Optional
 
 from pydantic import ValidationError
@@ -24,6 +29,10 @@ class Executor:
     - 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.
+
+    Both sync and async execution are supported:
+    - ``execute`` / ``execute_many``          — synchronous
+    - ``aexecute`` / ``aexecute_many``        — async, with parallel dispatch
     """
 
     def __init__(
@@ -49,7 +58,7 @@ class Executor:
         self._confirm_callback = confirm_callback
 
     # ------------------------------------------------------------------
-    # Public interface
+    # Sync public interface
     # ------------------------------------------------------------------
 
     def execute(self, tool_call: ToolCall) -> ToolResult:
@@ -78,9 +87,14 @@ class Executor:
                 error=f"Argument validation failed: {exc}",
             )
 
-        # 4. Execute the callable
+        # 4. Execute the callable (handles both sync and async tools)
         try:
-            output = defn.callable(**validated_args.model_dump())
+            raw_output = defn.callable(**validated_args.model_dump())
+            # If the tool is an async function, run it in the event loop
+            if inspect.isawaitable(raw_output):
+                loop = asyncio.get_event_loop()
+                raw_output = loop.run_until_complete(raw_output)
+            output = str(raw_output)
         except Exception as exc:
             return ToolResult(
                 tool_name=tool_call.tool_name,
@@ -91,13 +105,74 @@ class Executor:
         return ToolResult(
             tool_name=tool_call.tool_name,
             call_id=tool_call.call_id,
-            output=str(output),
+            output=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]
 
+    # ------------------------------------------------------------------
+    # Async public interface
+    # ------------------------------------------------------------------
+
+    async def aexecute(self, tool_call: ToolCall) -> ToolResult:
+        """
+        Async version of ``execute``.
+
+        Natively handles ``async def`` tools (awaited directly) and
+        sync tools (run in a thread pool via ``asyncio.to_thread``).
+        """
+        # 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 (async-aware)
+        try:
+            kwargs = validated_args.model_dump()
+            if inspect.iscoroutinefunction(defn.callable):
+                raw_output = await defn.callable(**kwargs)
+            else:
+                raw_output = await asyncio.to_thread(defn.callable, **kwargs)
+            output = str(raw_output)
+        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=output,
+        )
+
+    async def aexecute_many(self, tool_calls: List[ToolCall]) -> List[ToolResult]:
+        """
+        Execute *tool_calls* in parallel using ``asyncio.gather``.
+
+        All tool calls in the list are dispatched concurrently and results
+        are returned in the same order as the input list.
+        """
+        tasks = [self.aexecute(tc) for tc in tool_calls]
+        return list(await asyncio.gather(*tasks))
+
     # ------------------------------------------------------------------
     # Policy enforcement
     # ------------------------------------------------------------------