toolproxy 0.1.0__tar.gz

toolproxy-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+Universal Tool

toolproxy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 toolproxy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

toolproxy-0.1.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: toolproxy
+Version: 0.1.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
+Project-URL: Bug Tracker, https://github.com/yourusername/toolproxy/issues
+Author: toolproxy contributors
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,function-calling,llm,ollama,openrouter,pydantic,structured-output,tool-calling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Requires-Dist: openai>=1.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-mock>=3.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# toolproxy
+
+[![PyPI version](https://badge.fury.io/py/toolproxy.svg)](https://pypi.org/project/toolproxy/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/toolproxy.svg)](https://pypi.org/project/toolproxy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Universal Tool-Calling Wrapper for Non-Tool-Native LLMs**
+
+A provider-agnostic Python library that adds reliable tool/function calling to *any* LLM — even models that have no native tool-calling API.
+
+---
+
+## Problem
+
+Many LLM providers (OpenRouter, Ollama, local LLMs) expose models that don't support function calling. This library solves that by:
+
+- **Detecting** whether the model supports native tool calling.
+- **Using** native tool calls when available (OpenAI format).
+- **Falling back** to a structured JSON planning protocol when not.
+
+The developer always uses the same API regardless of the underlying model.
+
+---
+
+## Installation
+
+```bash
+pip install toolproxy
+```
+
+Or from source:
+
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+```python
+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 today?")
+print(result.content)
+```
+
+The same code works whether the model supports native tools or not.
+
+---
+
+## How It Works
+
+```
+Developer
+    │
+    ▼
+UniversalAgent.run(prompt)
+    │
+    ├─ Planner (auto-detects native vs emulated mode)
+    │       │
+    │       ├── Native mode  → provider tool calls (OpenAI format)
+    │       └── Emulated mode → structured JSON Action schema
+    │
+    ├─ Executor (validates args, runs tool, captures errors)
+    │
+    └─ LoopController (repeats until final answer or max_steps)
+```
+
+---
+
+## Model Prefixes
+
+| Prefix | Backend |
+|---|---|
+| `openrouter/...` | OpenRouter API |
+| `ollama/...` | Local Ollama server |
+| `mock/...` | MockClient (for testing, no API key needed) |
+| *(no prefix)* | OpenAI / any OpenAI-compatible endpoint |
+
+---
+
+## Advanced Options
+
+```python
+from toolproxy import UniversalAgent, tool
+from toolproxy.config import ExecutionPolicy
+
+agent = UniversalAgent(
+    model="openrouter/your-model",
+    tools=[get_weather],
+    mode="auto",               # "auto" | "native_only" | "emulated_only"
+    max_steps=10,
+    execution_policy=ExecutionPolicy(
+        mode="allow_only",
+        allowed_tools=["get_weather"],
+    ),
+)
+
+result = agent.run("...", return_trace=True)
+print(result.content)
+for call in result.trace.tool_calls:
+    print(call.tool_name, call.arguments)
+```
+
+### Callbacks (streaming-style)
+
+```python
+result = agent.run(
+    "...",
+    on_tool_call=lambda step, tc: print(f"Calling: {tc.tool_name}"),
+    on_tool_result=lambda step, tr: print(f"Result: {tr.output}"),
+    on_model_output=lambda step, text: print(f"Model: {text}"),
+)
+```
+
+---
+
+## Emulated Mode Protocol
+
+When the model does not support native tools, the agent injects a system prompt instructing the model to output one of two JSON formats:
+
+```json
+// Tool call
+{"type": "tool_call", "tool": {"tool_name": "get_weather", "arguments": {"city": "Chennai"}}}
+
+// Final answer
+{"type": "final", "content": "The weather is sunny."}
+```
+
+Malformed responses are retried up to `parse_retries` times (default: 3) with an error explanation.
+
+---
+
+## Project Structure
+
+```
+src/toolproxy/
+  __init__.py      # Public API re-exports
+  agent.py         # UniversalAgent class
+  llm_client.py    # LLMClient + adapters
+  tools.py         # @tool decorator + ToolRegistry
+  schemas.py       # Pydantic schemas
+  planner.py       # Planner logic
+  executor.py      # Tool execution + policies
+  loop.py          # Loop controller
+  exceptions.py    # Custom exceptions
+  config.py        # Configuration + capability map
+examples/
+  basic_chat.py
+  openrouter_tools.py
+  local_ollama.py
+tests/
+  test_agent_basic.py
+  test_emulated_mode.py
+  test_native_mode.py
+  test_error_handling.py
+  test_tool_registry.py
+```
+
+---
+
+## Publishing to PyPI
+
+```bash
+# 1. Install build tools
+pip install build twine
+
+# 2. Build wheel + sdist
+python -m build
+
+# 3. Check the distribution
+twine check dist/*
+
+# 4. Upload to PyPI (you will be prompted for credentials)
+twine upload dist/*
+
+# Or upload to TestPyPI first
+twine upload --repository testpypi dist/*
+```
+
+---
+
+## Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `OPENROUTER_API_KEY` | API key for OpenRouter |
+| `OPENAI_API_KEY` | API key for OpenAI |
+| `OLLAMA_BASE_URL` | Ollama server URL (default: `http://localhost:11434`) |
+| `OLLAMA_MODEL` | Ollama model name (default: `llama3`) |

toolproxy-0.1.0/README.md

@@ -0,0 +1,209 @@
+# toolproxy
+
+[![PyPI version](https://badge.fury.io/py/toolproxy.svg)](https://pypi.org/project/toolproxy/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/toolproxy.svg)](https://pypi.org/project/toolproxy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Universal Tool-Calling Wrapper for Non-Tool-Native LLMs**
+
+A provider-agnostic Python library that adds reliable tool/function calling to *any* LLM — even models that have no native tool-calling API.
+
+---
+
+## Problem
+
+Many LLM providers (OpenRouter, Ollama, local LLMs) expose models that don't support function calling. This library solves that by:
+
+- **Detecting** whether the model supports native tool calling.
+- **Using** native tool calls when available (OpenAI format).
+- **Falling back** to a structured JSON planning protocol when not.
+
+The developer always uses the same API regardless of the underlying model.
+
+---
+
+## Installation
+
+```bash
+pip install toolproxy
+```
+
+Or from source:
+
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+```python
+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 today?")
+print(result.content)
+```
+
+The same code works whether the model supports native tools or not.
+
+---
+
+## How It Works
+
+```
+Developer
+    │
+    ▼
+UniversalAgent.run(prompt)
+    │
+    ├─ Planner (auto-detects native vs emulated mode)
+    │       │
+    │       ├── Native mode  → provider tool calls (OpenAI format)
+    │       └── Emulated mode → structured JSON Action schema
+    │
+    ├─ Executor (validates args, runs tool, captures errors)
+    │
+    └─ LoopController (repeats until final answer or max_steps)
+```
+
+---
+
+## Model Prefixes
+
+| Prefix | Backend |
+|---|---|
+| `openrouter/...` | OpenRouter API |
+| `ollama/...` | Local Ollama server |
+| `mock/...` | MockClient (for testing, no API key needed) |
+| *(no prefix)* | OpenAI / any OpenAI-compatible endpoint |
+
+---
+
+## Advanced Options
+
+```python
+from toolproxy import UniversalAgent, tool
+from toolproxy.config import ExecutionPolicy
+
+agent = UniversalAgent(
+    model="openrouter/your-model",
+    tools=[get_weather],
+    mode="auto",               # "auto" | "native_only" | "emulated_only"
+    max_steps=10,
+    execution_policy=ExecutionPolicy(
+        mode="allow_only",
+        allowed_tools=["get_weather"],
+    ),
+)
+
+result = agent.run("...", return_trace=True)
+print(result.content)
+for call in result.trace.tool_calls:
+    print(call.tool_name, call.arguments)
+```
+
+### Callbacks (streaming-style)
+
+```python
+result = agent.run(
+    "...",
+    on_tool_call=lambda step, tc: print(f"Calling: {tc.tool_name}"),
+    on_tool_result=lambda step, tr: print(f"Result: {tr.output}"),
+    on_model_output=lambda step, text: print(f"Model: {text}"),
+)
+```
+
+---
+
+## Emulated Mode Protocol
+
+When the model does not support native tools, the agent injects a system prompt instructing the model to output one of two JSON formats:
+
+```json
+// Tool call
+{"type": "tool_call", "tool": {"tool_name": "get_weather", "arguments": {"city": "Chennai"}}}
+
+// Final answer
+{"type": "final", "content": "The weather is sunny."}
+```
+
+Malformed responses are retried up to `parse_retries` times (default: 3) with an error explanation.
+
+---
+
+## Project Structure
+
+```
+src/toolproxy/
+  __init__.py      # Public API re-exports
+  agent.py         # UniversalAgent class
+  llm_client.py    # LLMClient + adapters
+  tools.py         # @tool decorator + ToolRegistry
+  schemas.py       # Pydantic schemas
+  planner.py       # Planner logic
+  executor.py      # Tool execution + policies
+  loop.py          # Loop controller
+  exceptions.py    # Custom exceptions
+  config.py        # Configuration + capability map
+examples/
+  basic_chat.py
+  openrouter_tools.py
+  local_ollama.py
+tests/
+  test_agent_basic.py
+  test_emulated_mode.py
+  test_native_mode.py
+  test_error_handling.py
+  test_tool_registry.py
+```
+
+---
+
+## Publishing to PyPI
+
+```bash
+# 1. Install build tools
+pip install build twine
+
+# 2. Build wheel + sdist
+python -m build
+
+# 3. Check the distribution
+twine check dist/*
+
+# 4. Upload to PyPI (you will be prompted for credentials)
+twine upload dist/*
+
+# Or upload to TestPyPI first
+twine upload --repository testpypi dist/*
+```
+
+---
+
+## Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `OPENROUTER_API_KEY` | API key for OpenRouter |
+| `OPENAI_API_KEY` | API key for OpenAI |
+| `OLLAMA_BASE_URL` | Ollama server URL (default: `http://localhost:11434`) |
+| `OLLAMA_MODEL` | Ollama model name (default: `llama3`) |

toolproxy-0.1.0/examples/basic_chat.py

@@ -0,0 +1,93 @@
+"""
+Basic chat example — demonstrates the @tool decorator and UniversalAgent.run().
+
+Runs without a real API key using MockClient responses so you can see the flow.
+To use with a real model, set OPENROUTER_API_KEY and change the model string.
+"""
+import os
+import sys
+
+# Allow running from repo root
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from toolproxy import UniversalAgent, tool
+from toolproxy.llm_client import MockClient, ModelResponse
+from toolproxy.schemas import ToolCall
+
+
+# ---------------------------------------------------------------------------
+# Define tools
+# ---------------------------------------------------------------------------
+
+@tool
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    # In a real app this would call a weather API
+    weather_data = {
+        "Chennai": "Sunny, 34°C, humidity 72%",
+        "Mumbai": "Partly cloudy, 31°C, humidity 85%",
+        "Delhi": "Hazy, 38°C, humidity 45%",
+    }
+    return weather_data.get(city, f"Weather data not available for {city}")
+
+
+@tool
+def convert_currency(amount: float, from_currency: str, to_currency: str) -> str:
+    """Convert an amount from one currency to another."""
+    # Simplified fixed rates for demo
+    rates = {"USD": 1.0, "INR": 83.5, "EUR": 0.92, "GBP": 0.79}
+    if from_currency not in rates or to_currency not in rates:
+        return f"Currency not supported. Supported: {', '.join(rates)}"
+    converted = amount / rates[from_currency] * rates[to_currency]
+    return f"{amount} {from_currency} = {converted:.2f} {to_currency}"
+
+
+# ---------------------------------------------------------------------------
+# Mock responses simulating: tool call → final answer
+# ---------------------------------------------------------------------------
+
+MOCK_RESPONSES = [
+    # Step 1: model calls get_weather
+    ModelResponse(
+        raw_text='{"type": "tool_call", "tool": {"tool_name": "get_weather", "arguments": {"city": "Chennai"}}}',
+        tool_calls=[],
+    ),
+    # Step 2: model gives final answer after seeing result
+    ModelResponse(
+        raw_text='{"type": "final", "content": "The weather in Chennai is Sunny, 34°C with 72% humidity. Have a great day!"}',
+        tool_calls=[],
+    ),
+]
+
+
+def run_demo():
+    mock_client = MockClient(responses=MOCK_RESPONSES, native_tools=False)
+
+    agent = UniversalAgent(
+        model="mock/demo",
+        tools=[get_weather, convert_currency],
+        client=mock_client,
+        mode="emulated_only",
+    )
+
+    print("=== Universal Agent — Basic Chat Demo ===\n")
+    print(f"Agent: {agent}\n")
+
+    result = agent.run(
+        "What is the weather in Chennai today?",
+        return_trace=True,
+        on_tool_call=lambda step, tc: print(f"[Step {step}] Calling tool: {tc.tool_name}({tc.arguments})"),
+        on_tool_result=lambda step, tr: print(f"[Step {step}] Tool result: {tr.output or tr.error}"),
+    )
+
+    print(f"\n[OK] Final Answer: {result.content}")
+    print(f"Steps taken: {result.steps_taken}")
+    if result.trace:
+        print(f"\nTrace summary:")
+        for entry in result.trace.steps:
+            if entry.tool_call:
+                print(f"  - Called: {entry.tool_call.tool_name}")
+
+
+if __name__ == "__main__":
+    run_demo()

toolproxy-0.1.0/examples/local_ollama.py

@@ -0,0 +1,83 @@
+"""
+Local Ollama example — runs toolproxy against a local Ollama server.
+
+Requires: Ollama installed and running locally.
+Usage:
+    ollama pull llama3
+    python examples/local_ollama.py
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from toolproxy import UniversalAgent, tool
+from toolproxy.llm_client import OllamaClient
+
+
+@tool
+def list_files(directory: str) -> str:
+    """List files in a local directory."""
+    import os as _os
+    try:
+        entries = _os.listdir(directory)
+        if not entries:
+            return f"Directory '{directory}' is empty."
+        return "\n".join(entries[:20])  # limit output
+    except FileNotFoundError:
+        return f"Directory '{directory}' not found."
+    except PermissionError:
+        return f"Permission denied for '{directory}'."
+
+
+@tool
+def read_file(path: str, max_lines: int = 50) -> str:
+    """Read the contents of a file (up to max_lines lines)."""
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as f:
+            lines = []
+            for i, line in enumerate(f):
+                if i >= max_lines:
+                    lines.append(f"... (truncated at {max_lines} lines)")
+                    break
+                lines.append(line.rstrip())
+        return "\n".join(lines) if lines else "(empty file)"
+    except FileNotFoundError:
+        return f"File '{path}' not found."
+    except PermissionError:
+        return f"Permission denied for '{path}'."
+
+
+def main():
+    model = os.environ.get("OLLAMA_MODEL", "llama3")
+    base_url = os.environ.get("OLLAMA_BASE_URL", "http://localhost:11434")
+
+    print(f"=== Local Ollama Demo ===")
+    print(f"Model: {model} @ {base_url}")
+    print("Mode: emulated (Ollama default)\n")
+
+    client = OllamaClient(model=model, base_url=base_url, native_tools=False)
+
+    agent = UniversalAgent(
+        model=f"ollama/{model}",
+        tools=[list_files, read_file],
+        mode="emulated_only",
+        client=client,
+    )
+
+    prompt = "List the files in the current directory."
+    print(f"Prompt: {prompt}\n")
+
+    result = agent.run(
+        prompt,
+        return_trace=True,
+        on_tool_call=lambda s, tc: print(f"[Step {s}] → {tc.tool_name}({tc.arguments})"),
+        on_tool_result=lambda s, tr: print(f"[Step {s}] ← {(tr.output or tr.error)[:200]}"),
+    )
+
+    print(f"\n✅ Answer: {result.content}")
+    print(f"Steps: {result.steps_taken}")
+
+
+if __name__ == "__main__":
+    main()