dehydrator 0.2.0__py3-none-any.whl

dehydrator/__init__.py

@@ -0,0 +1,16 @@
+"""Dehydrator — Client-side BM25 tool search for LLM APIs."""
+
+from dehydrator._client import AsyncDehydratedClient, DehydratedClient
+from dehydrator._index import ToolIndex
+from dehydrator._openai_client import (
+    AsyncOpenAIDehydratedClient,
+    OpenAIDehydratedClient,
+)
+
+__all__ = [
+    "AsyncDehydratedClient",
+    "AsyncOpenAIDehydratedClient",
+    "DehydratedClient",
+    "OpenAIDehydratedClient",
+    "ToolIndex",
+]

dehydrator/_adapter.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Protocol
+
+from dehydrator._index import ToolIndex
+from dehydrator._search_tool import SEARCH_TOOL_DEFINITION, SEARCH_TOOL_NAME
+from dehydrator._types import (
+    ToolParam,
+    get_tool_description,
+    get_tool_name,
+    get_tool_schema,
+)
+
+
+def _format_search_result(matched_tools: list[ToolParam]) -> str:
+    """Format matched tools into a human-readable result."""
+    if not matched_tools:
+        return "No matching tools found. Try a different search query."
+    lines = ["Found the following tools:\n"]
+    for tool in matched_tools:
+        desc = get_tool_description(tool)
+        lines.append(f"- **{get_tool_name(tool)}**: {desc}")
+    lines.append("\nThese tools are now available for you to use.")
+    return "\n".join(lines)
+
+
+class ProviderAdapter(Protocol):
+    """Protocol for provider-specific response handling."""
+
+    def build_tools(
+        self,
+        index: ToolIndex,
+        always_available: list[ToolParam],
+        discovered: set[str],
+    ) -> list[ToolParam]: ...
+
+    def has_search_call(self, response: Any) -> bool: ...
+
+    def has_non_search_tool_call(self, response: Any) -> bool: ...
+
+    def process_search_calls(
+        self,
+        response: Any,
+        index: ToolIndex,
+        discovered: set[str],
+    ) -> list[dict[str, Any]]: ...
+
+    def append_search_round(
+        self,
+        messages: list[dict[str, Any]],
+        response: Any,
+        search_results: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]: ...
+
+    def call_api(self, client: Any, **kwargs: Any) -> Any: ...
+
+    async def acall_api(self, client: Any, **kwargs: Any) -> Any: ...
+
+
+class AnthropicAdapter:
+    """Adapter for the Anthropic Messages API."""
+
+    def build_tools(
+        self,
+        index: ToolIndex,
+        always_available: list[ToolParam],
+        discovered: set[str],
+    ) -> list[ToolParam]:
+        tools: list[ToolParam] = [SEARCH_TOOL_DEFINITION]
+        tools.extend(always_available)
+        tools.extend(index.get_tools(sorted(discovered)))
+        return tools
+
+    def has_search_call(self, response: Any) -> bool:
+        return any(
+            block.type == "tool_use" and block.name == SEARCH_TOOL_NAME
+            for block in response.content
+        )
+
+    def has_non_search_tool_call(self, response: Any) -> bool:
+        return any(
+            block.type == "tool_use" and block.name != SEARCH_TOOL_NAME
+            for block in response.content
+        )
+
+    def process_search_calls(
+        self,
+        response: Any,
+        index: ToolIndex,
+        discovered: set[str],
+    ) -> list[dict[str, Any]]:
+        results: list[dict[str, Any]] = []
+        for block in response.content:
+            if block.type == "tool_use" and block.name == SEARCH_TOOL_NAME:
+                query = str(block.input.get("query", ""))
+                matched_names = index.search(query)
+                discovered.update(matched_names)
+                matched_tools = index.get_tools(matched_names)
+                results.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": block.id,
+                        "content": _format_search_result(matched_tools),
+                    }
+                )
+        return results
+
+    def append_search_round(
+        self,
+        messages: list[dict[str, Any]],
+        response: Any,
+        search_results: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        messages = list(messages)
+        messages.append(
+            {
+                "role": "assistant",
+                "content": _response_content_to_params(response),
+            }
+        )
+        messages.append(
+            {
+                "role": "user",
+                "content": search_results,
+            }
+        )
+        return messages
+
+    def call_api(self, client: Any, **kwargs: Any) -> Any:
+        return client.messages.create(**kwargs)
+
+    async def acall_api(self, client: Any, **kwargs: Any) -> Any:
+        return await client.messages.create(**kwargs)
+
+
+def _response_content_to_params(
+    response: Any,
+) -> list[dict[str, Any]]:
+    """Convert Anthropic response content blocks to message param format."""
+    blocks: list[dict[str, Any]] = []
+    for block in response.content:
+        if block.type == "text":
+            blocks.append({"type": "text", "text": block.text})
+        elif block.type == "tool_use":
+            blocks.append(
+                {
+                    "type": "tool_use",
+                    "id": block.id,
+                    "name": block.name,
+                    "input": block.input,
+                }
+            )
+        elif block.type == "thinking":
+            blocks.append(
+                {
+                    "type": "thinking",
+                    "thinking": block.thinking,
+                    "signature": block.signature,
+                }
+            )
+        elif block.type == "redacted_thinking":
+            blocks.append(
+                {
+                    "type": "redacted_thinking",
+                    "data": block.data,
+                }
+            )
+    return blocks
+
+
+class OpenAIAdapter:
+    """Adapter for OpenAI-compatible APIs."""
+
+    def _to_openai_tool(self, tool: ToolParam) -> ToolParam:
+        """Convert an Anthropic/MCP tool dict to OpenAI function format."""
+        return {
+            "type": "function",
+            "function": {
+                "name": get_tool_name(tool),
+                "description": get_tool_description(tool),
+                "parameters": get_tool_schema(tool),
+            },
+        }
+
+    def build_tools(
+        self,
+        index: ToolIndex,
+        always_available: list[ToolParam],
+        discovered: set[str],
+    ) -> list[ToolParam]:
+        raw: list[ToolParam] = [SEARCH_TOOL_DEFINITION]
+        raw.extend(always_available)
+        raw.extend(index.get_tools(sorted(discovered)))
+        return [self._to_openai_tool(t) for t in raw]
+
+    def has_search_call(self, response: Any) -> bool:
+        tool_calls = _get_openai_tool_calls(response)
+        return any(tc.function.name == SEARCH_TOOL_NAME for tc in tool_calls)
+
+    def has_non_search_tool_call(self, response: Any) -> bool:
+        tool_calls = _get_openai_tool_calls(response)
+        return any(tc.function.name != SEARCH_TOOL_NAME for tc in tool_calls)
+
+    def process_search_calls(
+        self,
+        response: Any,
+        index: ToolIndex,
+        discovered: set[str],
+    ) -> list[dict[str, Any]]:
+        results: list[dict[str, Any]] = []
+        for tc in _get_openai_tool_calls(response):
+            if tc.function.name == SEARCH_TOOL_NAME:
+                raw_args = tc.function.arguments
+                args = json.loads(raw_args) if isinstance(raw_args, str) else raw_args
+                query = str(args.get("query", ""))
+                matched_names = index.search(query)
+                discovered.update(matched_names)
+                matched_tools = index.get_tools(matched_names)
+                results.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": tc.id,
+                        "content": _format_search_result(matched_tools),
+                    }
+                )
+        return results
+
+    def append_search_round(
+        self,
+        messages: list[dict[str, Any]],
+        response: Any,
+        search_results: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        messages = list(messages)
+        message = response.choices[0].message
+        assistant_msg: dict[str, Any] = {
+            "role": "assistant",
+            "content": message.content or "",
+        }
+        if message.tool_calls:
+            assistant_msg["tool_calls"] = [
+                {
+                    "id": tc.id,
+                    "type": "function",
+                    "function": {
+                        "name": tc.function.name,
+                        "arguments": tc.function.arguments,
+                    },
+                }
+                for tc in message.tool_calls
+            ]
+        messages.append(assistant_msg)
+        messages.extend(search_results)
+        return messages
+
+    def call_api(self, client: Any, **kwargs: Any) -> Any:
+        return client.chat.completions.create(**kwargs)
+
+    async def acall_api(self, client: Any, **kwargs: Any) -> Any:
+        return await client.chat.completions.create(**kwargs)
+
+
+def _get_openai_tool_calls(response: Any) -> list[Any]:
+    """Extract tool_calls from an OpenAI-compatible response."""
+    message = response.choices[0].message
+    return message.tool_calls or []

dehydrator/_client.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+import anthropic
+
+from dehydrator._adapter import AnthropicAdapter
+from dehydrator._index import ToolIndex
+from dehydrator._interceptor import async_send, send
+from dehydrator._search_tool import SEARCH_TOOL_NAME
+from dehydrator._types import ToolParam, get_tool_name
+
+
+class _Messages:
+    """Namespace that mimics ``client.messages`` for sync usage."""
+
+    def __init__(self, parent: DehydratedClient) -> None:
+        self._parent = parent
+
+    def create(self, **kwargs: Any) -> anthropic.types.Message:
+        if kwargs.get("stream"):
+            raise NotImplementedError(
+                "Streaming is not yet supported by DehydratedClient. "
+                "Pass stream=False or omit it."
+            )
+        # Strip tools from kwargs — we manage them
+        kwargs.pop("tools", None)
+        return cast(
+            anthropic.types.Message,
+            send(
+                client=self._parent._client,
+                adapter=AnthropicAdapter(),
+                index=self._parent._index,
+                always_available=self._parent._always_available,
+                discovered=self._parent._discovered,
+                max_search_rounds=self._parent._max_search_rounds,
+                **kwargs,
+            ),
+        )
+
+
+class _AsyncMessages:
+    """Namespace that mimics ``client.messages`` for async usage."""
+
+    def __init__(self, parent: AsyncDehydratedClient) -> None:
+        self._parent = parent
+
+    async def create(self, **kwargs: Any) -> anthropic.types.Message:
+        if kwargs.get("stream"):
+            raise NotImplementedError(
+                "Streaming is not yet supported by AsyncDehydratedClient. "
+                "Pass stream=False or omit it."
+            )
+        kwargs.pop("tools", None)
+        return cast(
+            anthropic.types.Message,
+            await async_send(
+                client=self._parent._client,
+                adapter=AnthropicAdapter(),
+                index=self._parent._index,
+                always_available=self._parent._always_available,
+                discovered=self._parent._discovered,
+                max_search_rounds=self._parent._max_search_rounds,
+                **kwargs,
+            ),
+        )
+
+
+class DehydratedClient:
+    """Wraps an ``anthropic.Anthropic`` client with transparent BM25 tool search.
+
+    Instead of sending all tools in every request, only a search tool and
+    ``always_available`` tools are sent. When Claude calls the search tool,
+    BM25 is run locally and matching tools are added to the next request.
+
+    Usage::
+
+        client = DehydratedClient(
+            anthropic.Anthropic(),
+            tools=all_my_tools,
+            top_k=5,
+        )
+        response = client.messages.create(
+            model="claude-sonnet-4-6",
+            max_tokens=1024,
+            messages=[{"role": "user", "content": "Send an email"}],
+        )
+    """
+
+    def __init__(
+        self,
+        client: anthropic.Anthropic,
+        tools: list[ToolParam],
+        *,
+        top_k: int = 5,
+        always_available: list[str] | None = None,
+        max_search_rounds: int = 3,
+    ) -> None:
+        self._validate_tool_names(tools)
+        self._client = client
+        all_tools, self._always_available = self._split_tools(
+            tools, always_available or []
+        )
+        if not all_tools:
+            raise ValueError("No searchable tools provided.")
+        self._index = ToolIndex(all_tools, top_k=top_k)
+        self._discovered: set[str] = set()
+        self._max_search_rounds = max_search_rounds
+        self.messages = _Messages(self)
+
+    @property
+    def inner(self) -> anthropic.Anthropic:
+        """The underlying Anthropic client."""
+        return self._client
+
+    def reset_discoveries(self) -> None:
+        """Clear discovered tools. Call this when starting a new conversation."""
+        self._discovered.clear()
+
+    @staticmethod
+    def _validate_tool_names(tools: list[ToolParam]) -> None:
+        for tool in tools:
+            if get_tool_name(tool) == SEARCH_TOOL_NAME:
+                raise ValueError(
+                    f"Tool name {SEARCH_TOOL_NAME!r} is reserved by Dehydrator. "
+                    "Please rename your tool."
+                )
+
+    @staticmethod
+    def _split_tools(
+        tools: list[ToolParam], always_names: list[str]
+    ) -> tuple[list[ToolParam], list[ToolParam]]:
+        always_set = set(always_names)
+        always: list[ToolParam] = []
+        searchable: list[ToolParam] = []
+        for tool in tools:
+            if get_tool_name(tool) in always_set:
+                always.append(tool)
+            else:
+                searchable.append(tool)
+        return searchable, always
+
+
+class AsyncDehydratedClient:
+    """Async version of :class:`DehydratedClient`.
+
+    Wraps an ``anthropic.AsyncAnthropic`` client.
+    """
+
+    def __init__(
+        self,
+        client: anthropic.AsyncAnthropic,
+        tools: list[ToolParam],
+        *,
+        top_k: int = 5,
+        always_available: list[str] | None = None,
+        max_search_rounds: int = 3,
+    ) -> None:
+        DehydratedClient._validate_tool_names(tools)
+        self._client = client
+        all_tools, self._always_available = DehydratedClient._split_tools(
+            tools, always_available or []
+        )
+        if not all_tools:
+            raise ValueError("No searchable tools provided.")
+        self._index = ToolIndex(all_tools, top_k=top_k)
+        self._discovered: set[str] = set()
+        self._max_search_rounds = max_search_rounds
+        self.messages = _AsyncMessages(self)
+
+    @property
+    def inner(self) -> anthropic.AsyncAnthropic:
+        """The underlying async Anthropic client."""
+        return self._client
+
+    def reset_discoveries(self) -> None:
+        """Clear discovered tools. Call this when starting a new conversation."""
+        self._discovered.clear()

dehydrator/_index.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Any
+
+from rank_bm25 import BM25L
+
+from dehydrator._tokenizer import tokenize_query, tokenize_tool
+from dehydrator._types import ToolParam, get_tool_name, mcp_tool_to_dict
+
+
+class ToolIndex:
+    """BM25 search index over tool definitions."""
+
+    def __init__(self, tools: list[ToolParam], *, top_k: int = 5) -> None:
+        if not tools:
+            raise ValueError("tools must not be empty")
+        self._tools_by_name: dict[str, ToolParam] = {}
+        corpus: list[list[str]] = []
+        names: list[str] = []
+        for tool in tools:
+            name = get_tool_name(tool)
+            if name in self._tools_by_name:
+                raise ValueError(f"Duplicate tool name: {name!r}")
+            self._tools_by_name[name] = tool
+            names.append(name)
+            corpus.append(tokenize_tool(tool))
+        self._names = names
+        self._bm25 = BM25L(corpus)
+        self._top_k = top_k
+
+    @classmethod
+    def from_mcp(cls, tools: list[Any], *, top_k: int = 5) -> ToolIndex:
+        """Create a ToolIndex from a list of ``mcp.types.Tool`` objects."""
+        return cls([mcp_tool_to_dict(t) for t in tools], top_k=top_k)
+
+    @property
+    def tool_names(self) -> list[str]:
+        """All indexed tool names."""
+        return list(self._names)
+
+    def search(self, query: str) -> list[str]:
+        """Return up to *top_k* tool names ranked by BM25 relevance.
+
+        Only tools with a positive score are returned.
+        """
+        tokens = tokenize_query(query)
+        if not tokens:
+            return []
+        scores = self._bm25.get_scores(tokens)
+        scored = [
+            (name, float(score))
+            for name, score in zip(self._names, scores)
+            if score > 0
+        ]
+        scored.sort(key=lambda x: x[1], reverse=True)
+        return [name for name, _ in scored[: self._top_k]]
+
+    def get_tools(self, names: list[str]) -> list[ToolParam]:
+        """Return full tool definitions for the given names.
+
+        Unknown names are silently skipped.
+        """
+        return [self._tools_by_name[n] for n in names if n in self._tools_by_name]
+
+    def get_tool(self, name: str) -> ToolParam | None:
+        """Return a single tool definition by name, or None."""
+        return self._tools_by_name.get(name)

dehydrator/_interceptor.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Any
+
+from dehydrator._adapter import ProviderAdapter
+from dehydrator._index import ToolIndex
+from dehydrator._types import ToolParam
+
+
+def send(
+    client: Any,
+    adapter: ProviderAdapter,
+    index: ToolIndex,
+    always_available: list[ToolParam],
+    discovered: set[str],
+    max_search_rounds: int,
+    **kwargs: Any,
+) -> Any:
+    """Synchronous send with search interception."""
+    response: Any = None
+    for _ in range(max_search_rounds):
+        tools = adapter.build_tools(index, always_available, discovered)
+        kwargs["tools"] = tools
+        response = adapter.call_api(client, **kwargs)
+
+        if not adapter.has_search_call(response):
+            return response
+
+        if adapter.has_non_search_tool_call(response):
+            adapter.process_search_calls(response, index, discovered)
+            return response
+
+        search_results = adapter.process_search_calls(response, index, discovered)
+
+        messages = list(kwargs.get("messages", []))
+        kwargs["messages"] = adapter.append_search_round(
+            messages, response, search_results
+        )
+
+    assert response is not None
+    return response
+
+
+async def async_send(
+    client: Any,
+    adapter: ProviderAdapter,
+    index: ToolIndex,
+    always_available: list[ToolParam],
+    discovered: set[str],
+    max_search_rounds: int,
+    **kwargs: Any,
+) -> Any:
+    """Asynchronous send with search interception."""
+    response: Any = None
+    for _ in range(max_search_rounds):
+        tools = adapter.build_tools(index, always_available, discovered)
+        kwargs["tools"] = tools
+        response = await adapter.acall_api(client, **kwargs)
+
+        if not adapter.has_search_call(response):
+            return response
+
+        if adapter.has_non_search_tool_call(response):
+            adapter.process_search_calls(response, index, discovered)
+            return response
+
+        search_results = adapter.process_search_calls(response, index, discovered)
+
+        messages = list(kwargs.get("messages", []))
+        kwargs["messages"] = adapter.append_search_round(
+            messages, response, search_results
+        )
+
+    assert response is not None
+    return response

dehydrator/_openai_client.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from typing import Any
+
+from dehydrator._adapter import OpenAIAdapter
+from dehydrator._index import ToolIndex
+from dehydrator._interceptor import async_send, send
+from dehydrator._search_tool import SEARCH_TOOL_NAME
+from dehydrator._types import ToolParam, get_tool_name
+
+
+class _ChatCompletions:
+    """Namespace that mimics ``client.chat.completions`` for sync usage."""
+
+    def __init__(self, parent: OpenAIDehydratedClient) -> None:
+        self._parent = parent
+
+    def create(self, **kwargs: Any) -> Any:
+        if kwargs.get("stream"):
+            raise NotImplementedError(
+                "Streaming is not yet supported by OpenAIDehydratedClient. "
+                "Pass stream=False or omit it."
+            )
+        kwargs.pop("tools", None)
+        return send(
+            client=self._parent._client,
+            adapter=OpenAIAdapter(),
+            index=self._parent._index,
+            always_available=self._parent._always_available,
+            discovered=self._parent._discovered,
+            max_search_rounds=self._parent._max_search_rounds,
+            **kwargs,
+        )
+
+
+class _AsyncChatCompletions:
+    """Namespace that mimics ``client.chat.completions`` for async usage."""
+
+    def __init__(self, parent: AsyncOpenAIDehydratedClient) -> None:
+        self._parent = parent
+
+    async def create(self, **kwargs: Any) -> Any:
+        if kwargs.get("stream"):
+            raise NotImplementedError(
+                "Streaming is not yet supported by AsyncOpenAIDehydratedClient. "
+                "Pass stream=False or omit it."
+            )
+        kwargs.pop("tools", None)
+        return await async_send(
+            client=self._parent._client,
+            adapter=OpenAIAdapter(),
+            index=self._parent._index,
+            always_available=self._parent._always_available,
+            discovered=self._parent._discovered,
+            max_search_rounds=self._parent._max_search_rounds,
+            **kwargs,
+        )
+
+
+class _Chat:
+    """Namespace that mimics ``client.chat``."""
+
+    def __init__(self, completions: _ChatCompletions | _AsyncChatCompletions) -> None:
+        self.completions = completions
+
+
+class OpenAIDehydratedClient:
+    """Wraps any OpenAI-compatible client with transparent BM25 tool search.
+
+    Works with ``openai.OpenAI``, Groq, OpenRouter, Chutes, and any other
+    client that implements ``client.chat.completions.create()``.
+
+    Usage::
+
+        from openai import OpenAI
+        client = OpenAIDehydratedClient(
+            OpenAI(),
+            tools=all_my_tools,
+            top_k=5,
+        )
+        response = client.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "Send an email"}],
+        )
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        tools: list[ToolParam],
+        *,
+        top_k: int = 5,
+        always_available: list[str] | None = None,
+        max_search_rounds: int = 3,
+    ) -> None:
+        self._validate_tool_names(tools)
+        self._client = client
+        all_tools, self._always_available = self._split_tools(
+            tools, always_available or []
+        )
+        if not all_tools:
+            raise ValueError("No searchable tools provided.")
+        self._index = ToolIndex(all_tools, top_k=top_k)
+        self._discovered: set[str] = set()
+        self._max_search_rounds = max_search_rounds
+        self.chat = _Chat(_ChatCompletions(self))
+
+    @property
+    def inner(self) -> Any:
+        """The underlying OpenAI-compatible client."""
+        return self._client
+
+    def reset_discoveries(self) -> None:
+        """Clear discovered tools. Call this when starting a new conversation."""
+        self._discovered.clear()
+
+    @staticmethod
+    def _validate_tool_names(tools: list[ToolParam]) -> None:
+        for tool in tools:
+            if get_tool_name(tool) == SEARCH_TOOL_NAME:
+                raise ValueError(
+                    f"Tool name {SEARCH_TOOL_NAME!r} is reserved by Dehydrator. "
+                    "Please rename your tool."
+                )
+
+    @staticmethod
+    def _split_tools(
+        tools: list[ToolParam], always_names: list[str]
+    ) -> tuple[list[ToolParam], list[ToolParam]]:
+        always_set = set(always_names)
+        always: list[ToolParam] = []
+        searchable: list[ToolParam] = []
+        for tool in tools:
+            if get_tool_name(tool) in always_set:
+                always.append(tool)
+            else:
+                searchable.append(tool)
+        return searchable, always
+
+
+class AsyncOpenAIDehydratedClient:
+    """Async version of :class:`OpenAIDehydratedClient`.
+
+    Wraps any async OpenAI-compatible client.
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        tools: list[ToolParam],
+        *,
+        top_k: int = 5,
+        always_available: list[str] | None = None,
+        max_search_rounds: int = 3,
+    ) -> None:
+        OpenAIDehydratedClient._validate_tool_names(tools)
+        self._client = client
+        all_tools, self._always_available = OpenAIDehydratedClient._split_tools(
+            tools, always_available or []
+        )
+        if not all_tools:
+            raise ValueError("No searchable tools provided.")
+        self._index = ToolIndex(all_tools, top_k=top_k)
+        self._discovered: set[str] = set()
+        self._max_search_rounds = max_search_rounds
+        self.chat = _Chat(_AsyncChatCompletions(self))
+
+    @property
+    def inner(self) -> Any:
+        """The underlying async OpenAI-compatible client."""
+        return self._client
+
+    def reset_discoveries(self) -> None:
+        """Clear discovered tools. Call this when starting a new conversation."""
+        self._discovered.clear()

dehydrator/_search_tool.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dehydrator._types import ToolParam
+
+SEARCH_TOOL_NAME = "tool_search"
+
+_SEARCH_DESCRIPTION = (
+    "Search for available tools by describing what you want to do. "
+    "Use this before attempting to call a tool you haven't discovered yet. "
+    "Returns the names and descriptions of matching tools which will then "
+    "become available for you to use."
+)
+
+_SCHEMA: ToolParam = {
+    "type": "object",
+    "properties": {
+        "query": {
+            "type": "string",
+            "description": (
+                "A natural language description of the action you want to "
+                "perform. Be specific — e.g. 'send an email' or "
+                "'get weather forecast'."
+            ),
+        },
+    },
+    "required": ["query"],
+}
+
+SEARCH_TOOL_DEFINITION: ToolParam = {
+    "name": SEARCH_TOOL_NAME,
+    "description": _SEARCH_DESCRIPTION,
+    "input_schema": _SCHEMA,
+}
+
+
+def search_tool_for_openai() -> ToolParam:
+    """Return the search tool definition in OpenAI function-calling format."""
+    return {
+        "type": "function",
+        "function": {
+            "name": SEARCH_TOOL_NAME,
+            "description": _SEARCH_DESCRIPTION,
+            "parameters": _SCHEMA,
+        },
+    }

dehydrator/_tokenizer.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from dehydrator._types import get_tool_description, get_tool_name, get_tool_schema
+
+
+def tokenize_tool(tool: dict[str, Any]) -> list[str]:
+    """Extract searchable tokens from a tool definition.
+
+    Pulls text from the tool name, description, and input schema
+    (property names, descriptions, enum values) and returns a flat
+    list of lowercase tokens.  Accepts both Anthropic (``input_schema``)
+    and MCP (``inputSchema``) key conventions.
+    """
+    tokens: list[str] = []
+
+    name = get_tool_name(tool)
+    tokens.extend(_split_identifier(name))
+
+    description = get_tool_description(tool)
+    tokens.extend(_tokenize_text(description))
+
+    schema = get_tool_schema(tool)
+    _walk_schema(schema, tokens)
+
+    return tokens
+
+
+def tokenize_query(query: str) -> list[str]:
+    """Tokenize a free-text search query."""
+    return _tokenize_text(query)
+
+
+def _split_identifier(name: str) -> list[str]:
+    """Split a snake_case or camelCase identifier into lowercase tokens."""
+    # First split on underscores/hyphens
+    parts = re.split(r"[_\-]+", name)
+    tokens: list[str] = []
+    for part in parts:
+        # Then split camelCase: insert boundary before uppercase letters
+        sub = re.sub(r"([a-z])([A-Z])", r"\1 \2", part)
+        for word in sub.split():
+            lower = word.lower()
+            if lower:
+                tokens.append(lower)
+    return tokens
+
+
+def _tokenize_text(text: str) -> list[str]:
+    """Lowercase and split text on non-alphanumeric characters."""
+    return [w for w in re.split(r"[^a-zA-Z0-9]+", text.lower()) if w]
+
+
+def _walk_schema(schema: dict[str, Any], tokens: list[str]) -> None:
+    """Recursively extract tokens from a JSON Schema object."""
+    properties: dict[str, Any] = schema.get("properties", {})
+    for prop_name, prop_schema in properties.items():
+        tokens.extend(_split_identifier(prop_name))
+        if "description" in prop_schema:
+            tokens.extend(_tokenize_text(prop_schema["description"]))
+        if "enum" in prop_schema:
+            for val in prop_schema["enum"]:
+                if isinstance(val, str):
+                    tokens.extend(_tokenize_text(val))
+        # Recurse into nested objects
+        if prop_schema.get("type") == "object":
+            _walk_schema(prop_schema, tokens)
+        # Recurse into array items
+        items = prop_schema.get("items")
+        if isinstance(items, dict) and items.get("type") == "object":
+            _walk_schema(items, tokens)

dehydrator/_types.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any
+
+ToolParam = dict[str, Any]
+"""A tool definition dict (Anthropic or MCP format)."""
+
+
+def get_tool_name(tool: Any) -> str:
+    """Extract tool name from a dict or mcp.types.Tool object."""
+    if isinstance(tool, dict):
+        return str(tool["name"])
+    return str(tool.name)
+
+
+def get_tool_description(tool: Any) -> str:
+    """Extract tool description from a dict or mcp.types.Tool object."""
+    if isinstance(tool, dict):
+        return str(tool.get("description", ""))
+    return str(tool.description or "")
+
+
+def get_tool_schema(tool: Any) -> dict[str, Any]:
+    """Extract input schema from a dict or mcp.types.Tool object.
+
+    Checks ``inputSchema`` (MCP camelCase) then ``input_schema``
+    (Anthropic snake_case).
+    """
+    if isinstance(tool, dict):
+        schema: Any = tool.get("inputSchema") or tool.get("input_schema")
+        if isinstance(schema, dict):
+            return schema
+        return {}
+    # mcp.types.Tool has .inputSchema
+    schema = getattr(tool, "inputSchema", None)
+    if schema is None:
+        return {}
+    if isinstance(schema, dict):
+        return schema
+    # Pydantic model — convert to dict
+    return schema.model_dump()  # type: ignore[no-any-return]
+
+
+def mcp_tool_to_dict(tool: Any) -> ToolParam:
+    """Convert an mcp.types.Tool object to an Anthropic-format dict."""
+    return {
+        "name": get_tool_name(tool),
+        "description": get_tool_description(tool),
+        "input_schema": get_tool_schema(tool),
+    }

dehydrator-0.2.0.dist-info/METADATA

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: dehydrator
+Version: 0.2.0
+Summary: Client-side BM25 tool search for LLM APIs — Anthropic, OpenAI-compatible, and MCP
+Project-URL: Homepage, https://github.com/arrmlet/dehydrator
+Project-URL: Repository, https://github.com/arrmlet/dehydrator
+Project-URL: Issues, https://github.com/arrmlet/dehydrator/issues
+Author-email: arrmlet <trubavolodymyr@gmail.com>
+License-Expression: MIT
+Keywords: anthropic,bm25,context-window,lazy-loading,llm,mcp,openai,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: mcp>=1.26.0
+Requires-Dist: rank-bm25>=0.2.2
+Description-Content-Type: text/markdown
+
+# Dehydrator
+
+Client-side BM25 tool search for LLM APIs. Use thousands of tools without bloating the context window.
+
+Works with **Anthropic**, **OpenAI**, and any **OpenAI-compatible** provider (Groq, OpenRouter, Chutes, etc.). Accepts tools from **MCP servers** natively.
+
+## The problem
+
+LLM APIs require you to send all tool definitions in every request. With 100+ tools, this wastes tokens and degrades tool selection. Anthropic offers a server-side `tool_search_tool_bm25`, but it's not available on all platforms (e.g. Bedrock) and doesn't work with ZDR. Dehydrator gives you the same capability client-side, so it works everywhere — with any provider.
+
+## How it works
+
+Dehydrator wraps your LLM client and replaces the full tool list with a single `tool_search` tool. When the model needs a tool, it searches by description. Dehydrator intercepts the call, runs BM25 locally, and re-calls the API with only the matched tools injected.
+
+```
+User request
+    │
+    ▼
+┌─────────────────────────────┐
+│  API call #1                │
+│  tools = [tool_search]      │
+│                             │
+│  Model responds:            │
+│  tool_search("send email")  │
+└─────────────┬───────────────┘
+              │  intercepted by Dehydrator
+              ▼
+┌─────────────────────────────┐
+│  BM25 search (local)        │
+│  → matches: send_email,     │
+│     send_slack_message       │
+└─────────────┬───────────────┘
+              │
+              ▼
+┌─────────────────────────────┐
+│  API call #2                │
+│  tools = [tool_search,      │
+│           send_email,        │
+│           send_slack_message]│
+│                             │
+│  Model responds:            │
+│  send_email({...})          │
+└─────────────────────────────┘
+              │
+              ▼
+        Returned to you
+```
+
+Only the tools the model actually needs are ever sent. Discovered tools persist across turns within a conversation.
+
+## Installation
+
+```bash
+pip install dehydrator
+```
+
+## Quick start
+
+### Anthropic
+
+```python
+import anthropic
+from dehydrator import DehydratedClient
+
+client = DehydratedClient(
+    anthropic.Anthropic(),
+    tools=tools,
+    top_k=5,
+)
+
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
+)
+```
+
+The response is a standard `anthropic.types.Message`.
+
+### OpenAI-compatible (OpenAI, Groq, OpenRouter, Chutes, etc.)
+
+```python
+from openai import OpenAI
+from dehydrator import OpenAIDehydratedClient
+
+client = OpenAIDehydratedClient(
+    OpenAI(),
+    tools=tools,
+    top_k=5,
+)
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
+)
+```
+
+Works with any client that implements `client.chat.completions.create()`. No `openai` import required — fully duck-typed.
+
+### MCP tools
+
+Tools from MCP servers use `inputSchema` (camelCase) instead of `input_schema`. Dehydrator accepts both formats automatically:
+
+```python
+# MCP format tools work directly
+tools = [
+    {"name": "get_weather", "description": "...", "inputSchema": {...}},
+]
+client = DehydratedClient(anthropic.Anthropic(), tools=tools)
+
+# Or use mcp.types.Tool objects with ToolIndex.from_mcp()
+from dehydrator import ToolIndex
+
+tools = await session.list_tools()  # returns list[mcp.types.Tool]
+index = ToolIndex.from_mcp(tools, top_k=5)
+```
+
+## API
+
+### `DehydratedClient(client, tools, *, top_k=5, always_available=None, max_search_rounds=3)`
+
+Wraps an `anthropic.Anthropic` client.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `client` | `anthropic.Anthropic` | An Anthropic SDK client instance |
+| `tools` | `list[dict]` | Tool definitions (Anthropic or MCP format) |
+| `top_k` | `int` | Max tools returned per search (default: 5) |
+| `always_available` | `list[str]` | Tool names to include in every request, bypassing search |
+| `max_search_rounds` | `int` | Max search iterations per `create()` call (default: 3) |
+
+#### Methods
+
+- **`client.messages.create(**kwargs)`** — Same signature as the Anthropic SDK. The `tools` kwarg is ignored (Dehydrator manages tools). Returns `anthropic.types.Message`.
+- **`client.reset_discoveries()`** — Clears discovered tools. Call this when starting a new conversation.
+- **`client.inner`** — Access the underlying `anthropic.Anthropic` client.
+
+### `AsyncDehydratedClient`
+
+Same API as `DehydratedClient`, but wraps `anthropic.AsyncAnthropic` and `create()` is async.
+
+### `OpenAIDehydratedClient(client, tools, *, top_k=5, always_available=None, max_search_rounds=3)`
+
+Wraps any OpenAI-compatible client.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `client` | any | Any client with `client.chat.completions.create()` |
+| `tools` | `list[dict]` | Tool definitions (Anthropic or MCP format — converted to OpenAI format automatically) |
+| `top_k` | `int` | Max tools returned per search (default: 5) |
+| `always_available` | `list[str]` | Tool names to include in every request, bypassing search |
+| `max_search_rounds` | `int` | Max search iterations per `create()` call (default: 3) |
+
+#### Methods
+
+- **`client.chat.completions.create(**kwargs)`** — Same signature as the OpenAI SDK. The `tools` kwarg is ignored. Returns the provider's response object.
+- **`client.reset_discoveries()`** — Clears discovered tools.
+- **`client.inner`** — Access the underlying client.
+
+### `AsyncOpenAIDehydratedClient`
+
+Same API as `OpenAIDehydratedClient`, but `create()` is async.
+
+### `ToolIndex`
+
+The BM25 index is also available standalone if you want to use it directly.
+
+```python
+from dehydrator import ToolIndex
+
+index = ToolIndex(tools, top_k=5)
+matched_names = index.search("weather forecast")
+matched_tools = index.get_tools(matched_names)
+
+# From MCP Tool objects
+index = ToolIndex.from_mcp(mcp_tools, top_k=5)
+```
+
+## Always-available tools
+
+Some tools should always be in context (e.g. a `help` tool). Pass their names to `always_available`:
+
+```python
+client = DehydratedClient(
+    anthropic.Anthropic(),
+    tools=tools,
+    always_available=["help", "get_current_user"],
+)
+```
+
+These tools are sent in every request without requiring a search.
+
+## Multi-turn conversations
+
+Discovered tools persist across calls to `create()`. If the model found `send_email` in turn 1, it's still available in turn 2 without re-searching.
+
+Call `client.reset_discoveries()` when starting a new conversation:
+
+```python
+# Turn 1: model discovers send_email
+response = client.messages.create(...)
+
+# Turn 2: send_email is still available
+response = client.messages.create(...)
+
+# New conversation
+client.reset_discoveries()
+```
+
+## Benchmarks
+
+Benchmarked against **139 real tool definitions** from 6 popular MCP servers (Chrome DevTools, GitHub, Playwright, Filesystem, Git, Notion).
+
+### Token savings
+
+Sending all tools in every request is expensive. Dehydrator replaces them with a single `tool_search` tool and only injects the tools the model actually needs:
+
+| Tools | top_k=3 | top_k=5 | top_k=10 | Baseline |
+|------:|--------:|--------:|---------:|---------:|
+| 50 | 274 tokens (94%) | 349 tokens (93%) | 678 tokens (86%) | 4,864 |
+| 100 | 274 tokens (97%) | 349 tokens (96%) | 678 tokens (92%) | 8,954 |
+| 200 | 274 tokens (98%) | 349 tokens (98%) | 678 tokens (96%) | 18,159 |
+
+With 200 tools and `top_k=5`, you go from **18,159 → 349 tokens** per request — a **98% reduction**.
+
+### Search quality
+
+BM25 finds the right tools reliably across all 6 MCP servers:
+
+| Metric | k=3 | k=5 | k=10 |
+|--------|----:|----:|-----:|
+| Precision@k | 51.1% | 32.7% | 17.3% |
+| Recall@k | 88.6% | 95.3% | 98.3% |
+| **MRR** | | **95.8%** | |
+
+30/30 test queries found at least one correct tool in the top 10. The right tool is ranked #1 or #2 in almost every case.
+
+### Run the benchmarks
+
+```bash
+uv run python benchmarks/search_quality.py       # local, no API key
+uv run python benchmarks/token_savings_openai.py  # local, uses tiktoken
+```
+
+## Limitations
+
+- **No streaming** — `stream=True` raises `NotImplementedError`. Planned for a future release.
+- **Reserved tool name** — You cannot have a tool named `tool_search`. Dehydrator will raise `ValueError` if you do.
+
+## Development
+
+```bash
+git clone https://github.com/Arrmlet/dehydrator.git
+cd dehydrator
+uv sync
+
+uv run pytest           # tests
+uv run ruff check src/  # lint
+uv run mypy src/        # type check
+```
+
+## License
+
+MIT

dehydrator-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+dehydrator/__init__.py,sha256=hSp8Jp-wzuQsYxFiVR7spYvfaVzmaBlQoOnpLYOtNFw,429
+dehydrator/_adapter.py,sha256=ukBmiJnEXitD-RmR6ugaBi1xLDPVzyEjJxokHAxKfjM,8685
+dehydrator/_client.py,sha256=Z_5RGau_0GrOWvb-9zz2en0sF4XLvAdVIeUrJNG6lNQ,5937
+dehydrator/_index.py,sha256=CBPObCBbZdumqnY6QzfPqtlY4ecBB8LFx1JotosR6O0,2326
+dehydrator/_interceptor.py,sha256=O_3AtT30v4X-dgZOt2emGO7_LcsOPX-L7qTY6GIrQQU,2242
+dehydrator/_openai_client.py,sha256=DRy5scqku5UV-Ch13Gmh3ojI3maStR6A0MPZq6cPQoM,5753
+dehydrator/_search_tool.py,sha256=8xBvIqWihdt3X1IOWAdXrgB4IQqi2BzQnPFx0GVUOOo,1255
+dehydrator/_tokenizer.py,sha256=ZMbhmESdlC5vWp8fKKPC40dch9Lbj--_DuwTCroDCuk,2550
+dehydrator/_types.py,sha256=VoBfSdXbfgTX1pdl2ddREOw0eQ4eAu84g-b2DBvYbV0,1540
+dehydrator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dehydrator-0.2.0.dist-info/METADATA,sha256=b59KQulJiibSBidZbDX1AeM-s_MAN0RT1E5lAVi7Ays,9978
+dehydrator-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+dehydrator-0.2.0.dist-info/RECORD,,

dehydrator-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any