hypermind 0.11.0__py3-none-any.whl

hypermind/responders/tools.py

@@ -0,0 +1,444 @@
+"""Tool-using responders — let LLMs ground claims in retrieved evidence.
+
+A :class:`ToolCallingResponder` wraps an OpenAI-compatible chat model
+that supports function-calling. When the model emits tool calls, the
+router invokes the registered Python callables, feeds the results back
+as ``role=tool`` messages, and re-asks for the final JSON answer.
+
+Built-in tools (importable from this module):
+  * :func:`web_search` — tiny stub web-search that callers replace with
+    a real search engine in production. The default implementation
+    returns a "no results" stub so the panel still degrades gracefully.
+  * :func:`retrieve_document` — caller-supplied document store lookup.
+  * :func:`query_knowledge_base` — caller-supplied vector-DB lookup.
+
+The default tool implementations are deliberately *stubs* — the SDK
+never ships an opinionated retrieval backend. Operators wire their own
+``Tool`` objects and pass them via ``tools=[...]``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from hypermind.responders.base import (
+    LLMResponderError,
+    ResponderResult,
+    confidence_to_uncertainty,
+)
+from hypermind.responders.structured import (
+    STRUCTURED_PROMPT_SUFFIX,
+    StructuredResponse,
+    TokenUsage,
+    parse_structured_response,
+)
+
+# ---------------------------------------------------------------------------
+# Tool dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Tool:
+    """One callable tool exposed to the LLM.
+
+    ``handler`` receives a JSON dict (the LLM-supplied arguments) and
+    must return a string (the tool result). Async or sync callables
+    both supported — async wins if both are present.
+    """
+
+    name: str
+    description: str
+    parameters_schema: dict[str, Any]
+    handler: Callable[[dict[str, Any]], Awaitable[str] | str]
+
+
+# ---------------------------------------------------------------------------
+# Built-in stub tools — operators replace these in production
+# ---------------------------------------------------------------------------
+
+
+async def _stub_web_search(args: dict[str, Any]) -> str:
+    """Default ``web_search`` stub: returns a 'no results' message.
+
+    Production deployments override by passing a real handler:
+
+    >>> from duckduckgo_search import AsyncDDGS
+    >>> async def real_search(args): ...
+    """
+    query = args.get("query", "")
+    return json.dumps(
+        {
+            "query": query,
+            "results": [],
+            "note": "no real web_search backend configured; results unavailable",
+        }
+    )
+
+
+def web_search(handler: Callable[[dict[str, Any]], Awaitable[str] | str] | None = None) -> Tool:
+    """Build a ``web_search`` tool with the given handler (or stub)."""
+    return Tool(
+        name="web_search",
+        description="Search the public web for recent information about a topic.",
+        parameters_schema={
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Search query."},
+                "max_results": {"type": "integer", "default": 5},
+            },
+            "required": ["query"],
+        },
+        handler=handler or _stub_web_search,
+    )
+
+
+async def _stub_retrieve_document(args: dict[str, Any]) -> str:
+    doc_id = args.get("doc_id", "")
+    return json.dumps(
+        {
+            "doc_id": doc_id,
+            "found": False,
+            "note": "no document store configured",
+        }
+    )
+
+
+def retrieve_document(
+    handler: Callable[[dict[str, Any]], Awaitable[str] | str] | None = None,
+) -> Tool:
+    return Tool(
+        name="retrieve_document",
+        description="Retrieve a document by ID from the configured store.",
+        parameters_schema={
+            "type": "object",
+            "properties": {
+                "doc_id": {"type": "string", "description": "Stable document identifier."},
+            },
+            "required": ["doc_id"],
+        },
+        handler=handler or _stub_retrieve_document,
+    )
+
+
+async def _stub_query_knowledge_base(args: dict[str, Any]) -> str:
+    query = args.get("query", "")
+    return json.dumps(
+        {
+            "query": query,
+            "matches": [],
+            "note": "no knowledge_base backend configured",
+        }
+    )
+
+
+def query_knowledge_base(
+    handler: Callable[[dict[str, Any]], Awaitable[str] | str] | None = None,
+) -> Tool:
+    return Tool(
+        name="query_knowledge_base",
+        description="Vector-search the configured knowledge base for relevant facts.",
+        parameters_schema={
+            "type": "object",
+            "properties": {
+                "query": {"type": "string"},
+                "top_k": {"type": "integer", "default": 5},
+            },
+            "required": ["query"],
+        },
+        handler=handler or _stub_query_knowledge_base,
+    )
+
+
+# ---------------------------------------------------------------------------
+# ToolCallingResponder
+# ---------------------------------------------------------------------------
+
+_DEFAULT_TOOL_SYSTEM = """You are a domain analyst on a federated intelligence panel.
+
+You have access to tools (web_search, retrieve_document, query_knowledge_base)
+that you may call BEFORE forming your final answer. Use a tool only if
+your reasoning genuinely depends on information you don't already know;
+do not invoke tools merely to be thorough — they cost time and money.
+
+After you have all the information you need, respond with a single json
+object containing your final answer. Do not call any further tools after
+producing the json answer."""
+
+
+_MAX_TOOL_ROUNDS = 4
+
+
+class ToolCallingResponder:
+    """OpenAI-compatible function-calling responder.
+
+    Compatible with any chat model whose SDK exposes ``tools=[...]`` and
+    returns ``message.tool_calls``. Used in production with OpenAI,
+    Anthropic (via OpenAI-compatible adapter), or OpenRouter.
+
+    Each call may run multiple rounds: the LLM emits tool calls, we
+    execute them and feed results back, then ask for the final JSON
+    answer. ``max_tool_rounds`` caps this loop so a misbehaving model
+    can't burn unlimited tokens.
+
+    Costs (token usage and tool-call counts) are emitted to the
+    recorder if one is attached.
+    """
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        model: str = "gpt-4o-mini",
+        tools: list[Tool] | None = None,
+        system_prompt: str = _DEFAULT_TOOL_SYSTEM,
+        effective_n: float = 10.0,
+        timeout_s: float = 60.0,
+        temperature: float = 0.4,
+        max_tool_rounds: int = _MAX_TOOL_ROUNDS,
+        cost_tracker: Any = None,
+        recorder: Any = None,
+    ) -> None:
+        self.client = client
+        self.model = model
+        self.tools: list[Tool] = list(tools or [])
+        self.system_prompt = system_prompt
+        self.effective_n = effective_n
+        self.timeout_s = timeout_s
+        self.temperature = temperature
+        self.max_tool_rounds = max(1, int(max_tool_rounds))
+        self.cost_tracker = cost_tracker
+        self.recorder = recorder
+        self.last_tool_calls: list[dict[str, Any]] = []
+        self.last_structured: StructuredResponse | None = None
+
+    # ----- tool dispatch -------------------------------------------------
+
+    def _tool_specs(self) -> list[dict[str, Any]]:
+        """OpenAI-style tools array."""
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": t.name,
+                    "description": t.description,
+                    "parameters": t.parameters_schema,
+                },
+            }
+            for t in self.tools
+        ]
+
+    async def _execute_tool(self, name: str, arguments_json: str) -> str:
+        tool = next((t for t in self.tools if t.name == name), None)
+        if tool is None:
+            return json.dumps({"error": f"unknown tool {name!r}"})
+        try:
+            args = json.loads(arguments_json) if arguments_json else {}
+        except json.JSONDecodeError as exc:
+            return json.dumps({"error": f"invalid tool args: {exc}"})
+
+        try:
+            handler_result = tool.handler(args)
+            if hasattr(handler_result, "__await__"):
+                handler_result = await handler_result  # type: ignore[assignment]
+            return str(handler_result)
+        except (asyncio.CancelledError, KeyboardInterrupt):
+            raise
+        except Exception as exc:
+            return json.dumps(
+                {
+                    "error": f"{type(exc).__name__}: {exc}",
+                    "tool": name,
+                }
+            )
+
+    def _emit(self, event_type: str, fields: dict[str, Any]) -> None:
+        if self.recorder is None:
+            return
+        try:
+            self.recorder.emit(event_type=event_type, severity="info", fields=fields)
+        except Exception:
+            pass
+
+    def _accumulate_token_usage(
+        self,
+        accum: TokenUsage | None,
+        usage_obj: Any,
+        agent_kid: bytes,
+    ) -> TokenUsage | None:
+        if usage_obj is None:
+            return accum
+        prompt_t = int(getattr(usage_obj, "prompt_tokens", 0) or 0)
+        completion_t = int(getattr(usage_obj, "completion_tokens", 0) or 0)
+        if self.cost_tracker is not None:
+            try:
+                this_call = self.cost_tracker.record(
+                    model=self.model,
+                    prompt_tokens=prompt_t,
+                    completion_tokens=completion_t,
+                    agent_kid=agent_kid,
+                )
+            except Exception:
+                this_call = TokenUsage(
+                    model=self.model,
+                    prompt_tokens=prompt_t,
+                    completion_tokens=completion_t,
+                    cost_usd=None,
+                )
+        else:
+            this_call = TokenUsage(
+                model=self.model,
+                prompt_tokens=prompt_t,
+                completion_tokens=completion_t,
+                cost_usd=None,
+            )
+        if accum is None:
+            return this_call
+        return TokenUsage(
+            model=self.model,
+            prompt_tokens=accum.prompt_tokens + this_call.prompt_tokens,
+            completion_tokens=accum.completion_tokens + this_call.completion_tokens,
+            cost_usd=(accum.cost_usd or 0) + (this_call.cost_usd or 0)
+            if accum.cost_usd is not None or this_call.cost_usd is not None
+            else None,
+        )
+
+    # ----- main loop -----------------------------------------------------
+
+    async def __call__(self, agent_kid: bytes, query: str) -> ResponderResult:
+        system = self.system_prompt
+        if "sub_claims" not in system:
+            system = system + STRUCTURED_PROMPT_SUFFIX
+
+        # Some chat APIs require literal "json" in the messages when
+        # response_format=json_object — not used in the tool loop, but the
+        # final-answer round may use it. We always inject the hint.
+        user_content = (
+            f"{query}\n\n"
+            "Use tools if needed; otherwise respond with the final "
+            'json object: {"confidence": <0..1>, "reasoning": "..."}'
+        )
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user_content},
+        ]
+
+        token_usage: TokenUsage | None = None
+        tool_calls_made: list[dict[str, Any]] = []
+
+        for round_idx in range(self.max_tool_rounds + 1):
+            try:
+                kwargs: dict[str, Any] = {
+                    "model": self.model,
+                    "messages": messages,
+                    "temperature": self.temperature,
+                    "timeout": self.timeout_s,
+                }
+                # Only offer tools if we still have rounds to use them.
+                if round_idx < self.max_tool_rounds and self.tools:
+                    kwargs["tools"] = self._tool_specs()
+                    kwargs["tool_choice"] = "auto"
+                # Force JSON only on the final-answer round
+                if round_idx == self.max_tool_rounds or not self.tools:
+                    kwargs["response_format"] = {"type": "json_object"}
+                resp = await self.client.chat.completions.create(**kwargs)
+            except Exception as exc:
+                raise LLMResponderError(f"OpenAI call failed: {exc}") from exc
+
+            token_usage = self._accumulate_token_usage(
+                token_usage,
+                getattr(resp, "usage", None),
+                agent_kid,
+            )
+
+            choice = resp.choices[0]
+            msg = choice.message
+            tool_calls = getattr(msg, "tool_calls", None) or []
+
+            if not tool_calls:
+                # Final answer turn
+                content = msg.content or "{}"
+                try:
+                    structured = parse_structured_response(
+                        content,
+                        agent_kid=agent_kid,
+                        token_usage=token_usage,
+                    )
+                except ValueError as exc:
+                    raise LLMResponderError(
+                        f"Tool responder produced no parseable answer: {exc}"
+                    ) from exc
+
+                self.last_structured = structured
+                self.last_tool_calls = tool_calls_made
+                unc = confidence_to_uncertainty(
+                    structured.confidence,
+                    effective_n=self.effective_n,
+                )
+                return unc, structured
+
+            # Execute every tool call; append results as role=tool messages
+            messages.append(
+                {
+                    "role": "assistant",
+                    "content": msg.content,
+                    "tool_calls": [
+                        {
+                            "id": tc.id,
+                            "type": "function",
+                            "function": {
+                                "name": tc.function.name,
+                                "arguments": tc.function.arguments,
+                            },
+                        }
+                        for tc in tool_calls
+                    ],
+                }
+            )
+
+            for tc in tool_calls:
+                tool_name = tc.function.name
+                args_json = tc.function.arguments
+                tool_result = await self._execute_tool(tool_name, args_json)
+                tool_calls_made.append(
+                    {
+                        "round": round_idx,
+                        "tool": tool_name,
+                        "args_json": args_json,
+                        "result_truncated": tool_result[:500],
+                    }
+                )
+                self._emit(
+                    "tool_call",
+                    {
+                        "tool": tool_name,
+                        "round": round_idx,
+                        "agent_kid": agent_kid.hex(),
+                    },
+                )
+                messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": tc.id,
+                        "content": tool_result,
+                    }
+                )
+
+        # Exhausted rounds without a final answer
+        raise LLMResponderError(
+            f"ToolCallingResponder exceeded {self.max_tool_rounds} tool rounds "
+            "without producing a final JSON answer"
+        )
+
+
+__all__ = [
+    "Tool",
+    "ToolCallingResponder",
+    "query_knowledge_base",
+    "retrieve_document",
+    "web_search",
+]