toolproxy 0.1.0__py3-none-any.whl

toolproxy/llm_client.py

@@ -0,0 +1,409 @@
+"""
+LLM client abstraction layer for toolproxy.
+
+Provides a common interface (LLMClient) over different backends:
+- OpenRouterClient  (OpenRouter via OpenAI-compatible API)
+- OpenAIClient      (Direct OpenAI or OpenAI-compatible endpoint)
+- OllamaClient      (Local Ollama server)
+- MockClient        (For testing without real API keys)
+
+Factory function:
+    get_client(model, **kwargs) -> LLMClient
+"""
+from __future__ import annotations
+
+import json
+import os
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .config import model_supports_native_tools
+from .exceptions import ModelError
+from .schemas import Message, ToolCall
+
+
+# ---------------------------------------------------------------------------
+# Provider-agnostic response
+# ---------------------------------------------------------------------------
+
+class ModelResponse:
+    """
+    Provider-agnostic response from an LLM.
+
+    raw_text        — the plain-text content of the response (may be empty if
+                      the model produced only tool calls).
+    tool_calls      — list of native ToolCall objects (empty if none).
+    raw             — the full provider response dict, for debugging.
+    """
+
+    def __init__(
+        self,
+        raw_text: str = "",
+        tool_calls: Optional[List[ToolCall]] = None,
+        raw: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.raw_text = raw_text
+        self.tool_calls: List[ToolCall] = tool_calls or []
+        self.raw = raw or {}
+
+    @property
+    def has_tool_calls(self) -> bool:
+        return bool(self.tool_calls)
+
+
+# ---------------------------------------------------------------------------
+# Abstract base
+# ---------------------------------------------------------------------------
+
+class LLMClient(ABC):
+    """Abstract interface all LLM clients must implement."""
+
+    @abstractmethod
+    def generate(
+        self,
+        messages: List[Message],
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> ModelResponse:
+        """
+        Send *messages* to the model and return a ModelResponse.
+
+        If *tools* is provided and the backend supports native tools, pass
+        them to the provider; otherwise ignore.
+        """
+
+    @abstractmethod
+    def supports_native_tools(self) -> bool:
+        """Return True if this client/model supports native tool calling."""
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _messages_to_openai(messages: List[Message]) -> List[Dict[str, Any]]:
+    """Convert internal Message objects to OpenAI chat format."""
+    result = []
+    for msg in messages:
+        d: Dict[str, Any] = {"role": msg.role, "content": msg.content}
+        if msg.role == "tool":
+            d["tool_call_id"] = msg.tool_call_id or "unknown"
+            d["name"] = msg.tool_name or "unknown"
+        result.append(d)
+    return result
+
+
+def _parse_native_tool_calls(raw_calls: List[Dict[str, Any]]) -> List[ToolCall]:
+    """Parse OpenAI-format tool_calls into internal ToolCall objects."""
+    parsed = []
+    for c in raw_calls:
+        fn = c.get("function", {})
+        try:
+            args = json.loads(fn.get("arguments", "{}"))
+        except json.JSONDecodeError:
+            args = {}
+        parsed.append(
+            ToolCall(
+                tool_name=fn.get("name", ""),
+                arguments=args,
+                call_id=c.get("id"),
+            )
+        )
+    return parsed
+
+
+# ---------------------------------------------------------------------------
+# OpenRouter client  (uses OpenAI-compatible REST API)
+# ---------------------------------------------------------------------------
+
+class OpenRouterClient(LLMClient):
+    """
+    Client for the OpenRouter API.
+
+    Reads OPENROUTER_API_KEY from the environment unless *api_key* is given.
+    Native tool support is determined by the MODEL_TOOL_SUPPORT map (see config).
+    """
+
+    BASE_URL = "https://openrouter.ai/api/v1"
+
+    def __init__(
+        self,
+        model: str,
+        api_key: Optional[str] = None,
+        native_tools: Optional[bool] = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self.model = model
+        self._api_key = api_key or os.environ.get("OPENROUTER_API_KEY", "")
+        self._native_tools = (
+            native_tools
+            if native_tools is not None
+            else model_supports_native_tools(model)
+        )
+        self._timeout = timeout
+
+    def supports_native_tools(self) -> bool:
+        return self._native_tools
+
+    def generate(
+        self,
+        messages: List[Message],
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> ModelResponse:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "HTTP-Referer": "https://github.com/universal-agent",
+            "X-Title": "universal-agent",
+        }
+        body: Dict[str, Any] = {
+            "model": self.model,
+            "messages": _messages_to_openai(messages),
+        }
+        if tools and self._native_tools:
+            body["tools"] = tools
+            body["tool_choice"] = "auto"
+
+        try:
+            resp = httpx.post(
+                f"{self.BASE_URL}/chat/completions",
+                headers=headers,
+                json=body,
+                timeout=self._timeout,
+            )
+            resp.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise ModelError(f"HTTP {exc.response.status_code}: {exc.response.text}") from exc
+        except httpx.RequestError as exc:
+            raise ModelError(f"Request failed: {exc}") from exc
+
+        data = resp.json()
+        return self._parse_response(data)
+
+    def _parse_response(self, data: Dict[str, Any]) -> ModelResponse:
+        choices = data.get("choices", [])
+        if not choices:
+            raise ModelError("No choices in model response.")
+        msg = choices[0].get("message", {})
+        raw_text = msg.get("content") or ""
+        native_calls = msg.get("tool_calls") or []
+        tool_calls = _parse_native_tool_calls(native_calls) if native_calls else []
+        return ModelResponse(raw_text=raw_text, tool_calls=tool_calls, raw=data)
+
+
+# ---------------------------------------------------------------------------
+# OpenAI client  (direct OpenAI or any OpenAI-compatible endpoint)
+# ---------------------------------------------------------------------------
+
+class OpenAIClient(LLMClient):
+    """
+    Client for OpenAI or any OpenAI-compatible endpoint (e.g., Together, Anyscale).
+    """
+
+    DEFAULT_BASE_URL = "https://api.openai.com/v1"
+
+    def __init__(
+        self,
+        model: str,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        native_tools: Optional[bool] = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self.model = model
+        self._api_key = api_key or os.environ.get("OPENAI_API_KEY", "")
+        self._base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self._native_tools = (
+            native_tools
+            if native_tools is not None
+            else model_supports_native_tools(model)
+        )
+        self._timeout = timeout
+
+    def supports_native_tools(self) -> bool:
+        return self._native_tools
+
+    def generate(
+        self,
+        messages: List[Message],
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> ModelResponse:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+        body: Dict[str, Any] = {
+            "model": self.model,
+            "messages": _messages_to_openai(messages),
+        }
+        if tools and self._native_tools:
+            body["tools"] = tools
+            body["tool_choice"] = "auto"
+
+        try:
+            resp = httpx.post(
+                f"{self._base_url}/chat/completions",
+                headers=headers,
+                json=body,
+                timeout=self._timeout,
+            )
+            resp.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise ModelError(f"HTTP {exc.response.status_code}: {exc.response.text}") from exc
+        except httpx.RequestError as exc:
+            raise ModelError(f"Request failed: {exc}") from exc
+
+        data = resp.json()
+        choices = data.get("choices", [])
+        if not choices:
+            raise ModelError("No choices in model response.")
+        msg = choices[0].get("message", {})
+        raw_text = msg.get("content") or ""
+        native_calls = msg.get("tool_calls") or []
+        tool_calls = _parse_native_tool_calls(native_calls) if native_calls else []
+        return ModelResponse(raw_text=raw_text, tool_calls=tool_calls, raw=data)
+
+
+# ---------------------------------------------------------------------------
+# Ollama client  (local HTTP server, tool support = False by default)
+# ---------------------------------------------------------------------------
+
+class OllamaClient(LLMClient):
+    """
+    Client for a local Ollama server.
+
+    Default base URL: http://localhost:11434
+    Tool calling: disabled by default (emulated mode).
+    """
+
+    DEFAULT_BASE_URL = "http://localhost:11434"
+
+    def __init__(
+        self,
+        model: str,
+        base_url: Optional[str] = None,
+        native_tools: bool = False,
+        timeout: float = 120.0,
+    ) -> None:
+        self.model = model
+        self._base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self._native_tools = native_tools
+        self._timeout = timeout
+
+    def supports_native_tools(self) -> bool:
+        return self._native_tools
+
+    def generate(
+        self,
+        messages: List[Message],
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> ModelResponse:
+        body: Dict[str, Any] = {
+            "model": self.model,
+            "messages": _messages_to_openai(messages),
+            "stream": False,
+        }
+        if tools and self._native_tools:
+            body["tools"] = tools
+
+        try:
+            resp = httpx.post(
+                f"{self._base_url}/api/chat",
+                json=body,
+                timeout=self._timeout,
+            )
+            resp.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise ModelError(f"HTTP {exc.response.status_code}: {exc.response.text}") from exc
+        except httpx.RequestError as exc:
+            raise ModelError(f"Request failed: {exc}") from exc
+
+        data = resp.json()
+        msg = data.get("message", {})
+        raw_text = msg.get("content") or ""
+        return ModelResponse(raw_text=raw_text, raw=data)
+
+
+# ---------------------------------------------------------------------------
+# Mock client  (for testing / demos without real API)
+# ---------------------------------------------------------------------------
+
+class MockClient(LLMClient):
+    """
+    A mock LLM client for unit tests.
+
+    Provide a list of pre-programmed responses; each call pops the next one.
+    Responses can be raw text strings or ModelResponse objects.
+    """
+
+    def __init__(
+        self,
+        responses: Optional[List[Any]] = None,
+        native_tools: bool = False,
+    ) -> None:
+        self._responses: List[Any] = list(responses or [])
+        self._native_tools = native_tools
+        self.call_count = 0
+        self.call_history: List[List[Message]] = []
+
+    def supports_native_tools(self) -> bool:
+        return self._native_tools
+
+    def generate(
+        self,
+        messages: List[Message],
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> ModelResponse:
+        self.call_history.append(messages)
+        self.call_count += 1
+        if not self._responses:
+            return ModelResponse(raw_text='{"type": "final", "content": "No more responses."}')
+        resp = self._responses.pop(0)
+        if isinstance(resp, ModelResponse):
+            return resp
+        return ModelResponse(raw_text=str(resp))
+
+
+# ---------------------------------------------------------------------------
+# Client factory
+# ---------------------------------------------------------------------------
+
+def get_client(
+    model: str,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    native_tools: Optional[bool] = None,
+) -> LLMClient:
+    """
+    Create and return the appropriate LLMClient for *model*.
+
+    Model routing:
+    - Starts with "openrouter/"  → OpenRouterClient (strips prefix)
+    - Starts with "ollama/"      → OllamaClient (strips prefix)
+    - Starts with "mock/"        → MockClient (for testing)
+    - Everything else            → OpenAIClient
+    """
+    if model.startswith("openrouter/"):
+        actual_model = model[len("openrouter/"):]
+        return OpenRouterClient(
+            model=actual_model,
+            api_key=api_key,
+            native_tools=native_tools,
+        )
+    if model.startswith("ollama/"):
+        actual_model = model[len("ollama/"):]
+        return OllamaClient(
+            model=actual_model,
+            base_url=base_url,
+            native_tools=native_tools or False,
+        )
+    if model.startswith("mock/"):
+        return MockClient(native_tools=native_tools or False)
+    # Default: OpenAI-compatible
+    return OpenAIClient(
+        model=model,
+        api_key=api_key,
+        base_url=base_url,
+        native_tools=native_tools,
+    )

toolproxy/loop.py

@@ -0,0 +1,180 @@
+"""
+Loop controller for toolproxy.
+
+Orchestrates the full agent execution cycle:
+  1. Inject system + user messages.
+  2. Ask the Planner what to do (tool call or final answer).
+  3. Execute tools via the Executor.
+  4. Append results to the conversation and loop.
+  5. Return AgentResponse (with optional trace).
+"""
+from __future__ import annotations
+
+from typing import Callable, List, Optional, Union
+
+from .exceptions import MaxStepsExceededError
+from .executor import Executor
+from .planner import Planner
+from .schemas import (
+    Action,
+    AgentResponse,
+    AgentTrace,
+    Message,
+    ToolCall,
+    ToolResult,
+    TraceEntry,
+)
+
+
+# ---------------------------------------------------------------------------
+# Callback type aliases
+# ---------------------------------------------------------------------------
+OnToolCallCb = Callable[[int, ToolCall], None]
+OnToolResultCb = Callable[[int, ToolResult], None]
+OnModelOutputCb = Callable[[int, str], None]
+
+
+class LoopController:
+    """
+    Runs the main agent loop until a final answer or max_steps is reached.
+
+    Callbacks (all optional):
+    - on_tool_call(step, tool_call)
+    - on_tool_result(step, tool_result)
+    - on_model_output(step, raw_text)
+    """
+
+    def __init__(
+        self,
+        planner: Planner,
+        executor: Executor,
+        max_steps: int = 10,
+        return_trace: bool = False,
+    ) -> None:
+        self._planner = planner
+        self._executor = executor
+        self._max_steps = max_steps
+        self._return_trace = return_trace
+
+    # ------------------------------------------------------------------
+    # Main run method
+    # ------------------------------------------------------------------
+
+    def run(
+        self,
+        messages: List[Message],
+        on_tool_call: Optional[OnToolCallCb] = None,
+        on_tool_result: Optional[OnToolResultCb] = None,
+        on_model_output: Optional[OnModelOutputCb] = None,
+    ) -> AgentResponse:
+        """
+        Execute the agent loop and return the final AgentResponse.
+
+        Parameters
+        ----------
+        messages:
+            Initial conversation (system + user messages).
+        on_tool_call / on_tool_result / on_model_output:
+            Optional streaming callbacks fired at each step.
+        """
+        conversation: List[Message] = list(messages)
+        trace = AgentTrace() if self._return_trace else None
+        steps_taken = 0
+
+        for step in range(1, self._max_steps + 1):
+            steps_taken = step
+
+            # Ask the planner
+            plan_result: Union[List[ToolCall], Action] = self._planner.plan(conversation)
+
+            # ----------------------------------------------------------
+            # Handle result
+            # ----------------------------------------------------------
+            if isinstance(plan_result, list):
+                # Native mode: list of tool calls
+                tool_calls = plan_result
+                if not tool_calls:
+                    # Unexpected: no calls and no final answer — treat as done
+                    return AgentResponse(
+                        content="(No response from model)",
+                        trace=trace,
+                        steps_taken=steps_taken,
+                    )
+
+                for tc in tool_calls:
+                    if on_tool_call:
+                        on_tool_call(step, tc)
+
+                    result = self._executor.execute(tc)
+
+                    if on_tool_result:
+                        on_tool_result(step, result)
+
+                    if trace is not None:
+                        trace.steps.append(
+                            TraceEntry(step=step, tool_call=tc, tool_result=result)
+                        )
+
+                    # Append tool result to conversation
+                    conversation.append(
+                        Message(
+                            role="tool",
+                            content=result.as_message_content(),
+                            tool_name=result.tool_name,
+                            tool_call_id=result.call_id,
+                        )
+                    )
+
+            elif isinstance(plan_result, Action):
+                action = plan_result
+
+                if on_model_output:
+                    on_model_output(step, action.content or "")
+
+                if action.type == "final":
+                    if trace is not None:
+                        trace.steps.append(
+                            TraceEntry(step=step, model_output=action.content)
+                        )
+                    return AgentResponse(
+                        content=action.content or "",
+                        trace=trace,
+                        steps_taken=steps_taken,
+                    )
+
+                # Emulated tool call
+                if action.tool is None:
+                    # Shouldn't happen (planner validates), but guard anyway
+                    raise ValueError("Action type='tool_call' has no tool field.")
+
+                tc = action.tool
+                if on_tool_call:
+                    on_tool_call(step, tc)
+
+                result = self._executor.execute(tc)
+
+                if on_tool_result:
+                    on_tool_result(step, result)
+
+                if trace is not None:
+                    trace.steps.append(
+                        TraceEntry(step=step, tool_call=tc, tool_result=result)
+                    )
+
+                # Append tool result to conversation as an assistant + user pair
+                # so emulated mode can follow the result
+                conversation.append(
+                    Message(
+                        role="assistant",
+                        content=f"[Calling tool: {tc.tool_name}]",
+                    )
+                )
+                conversation.append(
+                    Message(
+                        role="user",
+                        content=result.as_message_content(),
+                    )
+                )
+
+        # Max steps exceeded
+        raise MaxStepsExceededError(self._max_steps)