sift-tools 0.1.0__py3-none-any.whl

sift/__init__.py

@@ -0,0 +1,206 @@
+"""SIFT — Search · Inspect · Filter · Trigger.
+
+Hierarchical, search-first tool discovery for LLM agents. Give the model 3
+meta-tools instead of a 30k-token catalogue; it discovers the rest by navigating.
+
+Quickstart::
+
+    from sift import Sift
+
+    sift = Sift()
+
+    @sift.tool("google_workspace.gmail.read",
+               description="Read emails from the inbox",
+               params={"q": "string:o:is:unread:search query", "m": "number:o:10:max"},
+               returns=["id", "subject", "from", "snippet", "date"])
+    def gmail_read(q="is:unread", m=10):
+        return {"id": "1", "subject": "Hi", "from": "a@b.c", "snippet": "...",
+                "date": "2026-06-30", "body": "filtered out"}
+
+    sift.build_index()
+
+    sift.search_tools("read my last email")      # discovery
+    sift.get_tool_schema("google_workspace.gmail.read")  # TOON schema
+    sift.execute_tool("google_workspace.gmail.read", {"m": 1})  # run + filter
+
+    # Plug into any stack:
+    sift.openai_tools()       # function-calling specs
+    sift.langchain_tools()    # LangChain BaseTool list
+    sift.serve_mcp()          # expose as an MCP server
+"""
+from __future__ import annotations
+
+import json
+from typing import Callable
+
+from .gateway import Gateway, SearchResult
+from .metatools import META_TOOL_NAMES, SYSTEM_PROMPT, tool_specs
+from .registry import Registry, ToolDef
+
+__all__ = ["Sift", "Registry", "ToolDef", "SearchResult", "SYSTEM_PROMPT", "tool_specs"]
+__version__ = "0.1.0"
+
+
+class Sift:
+    """The public facade: register tools, build the index, expose meta-tools."""
+
+    def __init__(self, *, registry: Registry | None = None, embedder=None,
+                 model_name: str | None = None, retrieval: str = "hybrid",
+                 reranker=None, min_score: float = 0.0) -> None:
+        self.registry = registry or Registry()
+        self._embedder = embedder
+        self._model_name = model_name
+        self._retrieval = retrieval
+        self._reranker = reranker
+        self._min_score = min_score
+        self._gateway: Gateway | None = None
+
+    # ----------------------------------------------------------- registration
+    def tool(self, path: str, *, description: str, params: dict | None = None,
+             returns: list[str] | None = None, risk: bool = False,
+             transform: Callable | None = None) -> Callable:
+        """Decorator: register a function as a tool at ``path``."""
+        def deco(fn: Callable[..., dict]) -> Callable[..., dict]:
+            self.registry.add(ToolDef(path, description, params or {}, returns or [], risk, fn, transform))
+            return fn
+        return deco
+
+    def add_tool(self, path: str, fn: Callable[..., dict], *, description: str,
+                 params: dict | None = None, returns: list[str] | None = None,
+                 risk: bool = False, transform: Callable | None = None) -> "Sift":
+        self.registry.add(ToolDef(path, description, params or {}, returns or [], risk, fn, transform))
+        return self
+
+    def describe(self, node_path: str, description: str) -> "Sift":
+        self.registry.describe(node_path, description)
+        return self
+
+    def set_response(self, path: str, *, returns: list[str] | None = None,
+                     transform: Callable | None = None) -> "Sift":
+        """Trim what a tool returns to the model — a field whitelist and/or a
+        reshaping transform. Works on imported (MCP/OpenAPI) tools too."""
+        self.registry.set_response(path, returns=returns, transform=transform)
+        return self
+
+    def scope(self, *, allow: list[str] | None = None, deny: list[str] | None = None,
+              allow_risky: bool = True):
+        """A scoped view that only sees/runs tools matching the allow/deny globs
+        (an `allowedTools` per model/session). Reuses the built index.
+        ``allow_risky=False`` additionally blocks every tool flagged ``risk``."""
+        from .scope import SiftScope
+        return SiftScope(self, allow=allow, deny=deny, allow_risky=allow_risky)
+
+    # ----------------------------------------------------------------- index
+    def build_index(self) -> "Sift":
+        if self._embedder is None and self._retrieval != "bm25":
+            from .embeddings import FastEmbedder
+            self._embedder = FastEmbedder(self._model_name)
+        self._gateway = Gateway(self.registry, self._embedder, retrieval=self._retrieval,
+                                reranker=self._reranker, min_score=self._min_score)
+        self._gateway.build_index()
+        return self
+
+    @property
+    def gateway(self) -> Gateway:
+        if self._gateway is None:
+            raise RuntimeError("call build_index() before using the gateway")
+        return self._gateway
+
+    # ------------------------------------------------------------ meta-tools
+    def search_tools(self, q: str, top_k: int = 5) -> list[SearchResult]:
+        return self.gateway.search_tools(q, top_k)
+
+    def get_tool_schema(self, path: str) -> str:
+        return self.gateway.get_tool_schema(path)
+
+    def execute_tool(self, path: str, params: dict | None = None) -> dict:
+        return self.gateway.execute_tool(path, params)
+
+    def dispatch(self, name: str, arguments: dict | str) -> str:
+        """Run a meta-tool call by name; returns a string (TOON or JSON).
+
+        Handy as the single entry point when wiring SIFT into an LLM loop.
+        Handles the 3 meta-tools plus ``run_code`` (code mode).
+        """
+        args = json.loads(arguments) if isinstance(arguments, str) else dict(arguments or {})
+        try:
+            if name == "search_tools":
+                # compact TOON with schema inline — lets the model execute directly
+                return self.gateway.search_compact(args["q"], int(args.get("top_k", 3)))
+            if name == "run_code":
+                return self.run_code(args["code"])
+            if name == "get_tool_schema":
+                return self.get_tool_schema(args.get("path", ""))
+            if name == "execute_tool":
+                res = self.execute_tool(args["path"], args.get("params") or {})
+                return json.dumps(res, ensure_ascii=False, default=str)
+            return json.dumps({"error": f"unknown meta-tool {name!r}"})
+        except Exception as exc:  # surfaced back to the model as a tool result
+            return json.dumps({"error": str(exc)}, ensure_ascii=False)
+
+    # --------------------------------------------------------------- adapters
+    def openai_tools(self) -> list[dict]:
+        """OpenAI/OpenRouter function-calling specs for the 3 meta-tools."""
+        return tool_specs()
+
+    @property
+    def system_prompt(self) -> str:
+        return SYSTEM_PROMPT
+
+    # --- code mode (orchestrate many tools in one turn) ---
+    def code_tools(self) -> list[dict]:
+        from .codemode import code_tool_specs
+        return code_tool_specs()
+
+    @property
+    def code_system_prompt(self) -> str:
+        from .codemode import CODE_SYSTEM_PROMPT
+        return CODE_SYSTEM_PROMPT
+
+    def run_code(self, code: str) -> str:
+        from .codemode import run_code
+        return run_code(self, code)
+
+    @property
+    def meta_tool_names(self) -> tuple[str, ...]:
+        return META_TOOL_NAMES
+
+    def langchain_tools(self) -> list:
+        from .adapters.langchain import langchain_tools
+        return langchain_tools(self)
+
+    def anthropic_tools(self) -> list[dict]:
+        """The 3 meta-tools in the native Anthropic (Messages API) tool format."""
+        from .adapters.anthropic import anthropic_tools
+        return anthropic_tools(self)
+
+    # --- for models without native tool calling (prompted / constrained) ---
+    def tool_call_schema(self) -> dict:
+        """JSON Schema for a prompted step — feed to a structured-output decoder."""
+        from .constrain import tool_call_json_schema
+        return tool_call_json_schema()
+
+    def json_gbnf(self) -> str:
+        """GBNF grammar (llama.cpp) constraining output to valid JSON."""
+        from .constrain import json_gbnf
+        return json_gbnf()
+
+    def mcp_server(self, name: str = "sift"):
+        from .adapters.mcp_server import build_mcp_server
+        return build_mcp_server(self, name=name)
+
+    def serve_http(self, *, host: str = "127.0.0.1", port: int = 8000, scope=None) -> None:
+        """Run an OpenAPI HTTP server exposing the 3 meta-tools (OpenWebUI tool
+        server, REST clients). Requires the ``server`` extra."""
+        from .http_server import serve_http
+        serve_http(self, host=host, port=port, scope=scope)
+
+    def serve_mcp(self, name: str = "sift", transport: str = "stdio") -> None:
+        """Run SIFT as an MCP server exposing the 3 meta-tools.
+
+        transport: "stdio" (default; Claude Desktop, local clients) or "sse" /
+        "streamable-http" (remote clients, OpenWebUI). HTTP host/port are taken
+        from the MCP server settings / env.
+        """
+        server = self.mcp_server(name)
+        server.run() if transport == "stdio" else server.run(transport=transport)

sift/adapters/__init__.py

@@ -0,0 +1 @@
+"""Framework adapters: expose SIFT's 3 meta-tools to OpenAI, LangChain and MCP."""

sift/adapters/anthropic.py

@@ -0,0 +1,70 @@
+"""Native Anthropic (Messages API) adapter.
+
+Anthropic's tool format differs from OpenAI's: tools use ``input_schema`` (not a
+``function`` wrapper), the system prompt is a separate argument, and tool calls
+come back as ``tool_use`` content blocks answered with ``tool_result`` blocks.
+This adapter bridges that so SIFT works with the native ``anthropic`` SDK.
+
+    import anthropic
+    from sift.adapters.anthropic import run_agent
+    run_agent(sift, anthropic.Anthropic(), "claude-haiku-4.5", "what's my last email?")
+
+Requires the ``anthropic`` extra:  pip install "sift-tools[anthropic]"
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def anthropic_tools(sift) -> list[dict]:
+    """The 3 meta-tools in Anthropic's tool format."""
+    out = []
+    for spec in sift.openai_tools():
+        fn = spec["function"]
+        out.append({
+            "name": fn["name"],
+            "description": fn["description"],
+            "input_schema": fn["parameters"],
+        })
+    return out
+
+
+def _text_of(content: Any) -> str:
+    parts = []
+    for block in content:
+        if getattr(block, "type", None) == "text":
+            parts.append(block.text)
+    return "".join(parts)
+
+
+def run_agent(sift, client: Any, model: str, message: str, *,
+              max_tokens: int = 1024, max_steps: int = 12, verbose: bool = False,
+              extra: dict | None = None) -> str:
+    """Drive a tool-use loop against the native Anthropic Messages API.
+
+    ``client`` is duck-typed: it just needs ``messages.create(...)``.
+    """
+    tools = anthropic_tools(sift)
+    messages: list[dict] = [{"role": "user", "content": message}]
+
+    for _ in range(max_steps):
+        resp = client.messages.create(
+            model=model, system=sift.system_prompt, tools=tools,
+            max_tokens=max_tokens, messages=messages, **(extra or {}))
+
+        messages.append({"role": "assistant", "content": resp.content})
+
+        if getattr(resp, "stop_reason", None) != "tool_use":
+            return _text_of(resp.content)
+
+        results = []
+        for block in resp.content:
+            if getattr(block, "type", None) != "tool_use":
+                continue
+            out = sift.dispatch(block.name, block.input)
+            if verbose:
+                print(f"  ↳ {block.name}({block.input}) = {out[:160]}")
+            results.append({"type": "tool_result", "tool_use_id": block.id, "content": out})
+        messages.append({"role": "user", "content": results})
+
+    raise RuntimeError(f"reached max_steps={max_steps} without a final answer")

sift/adapters/langchain.py

@@ -0,0 +1,31 @@
+"""LangChain adapter — exposes the 3 meta-tools as LangChain ``StructuredTool``s.
+
+    from sift import Sift
+    sift = Sift(); ...; sift.build_index()
+    tools = sift.langchain_tools()           # plug into any LangChain agent
+
+Requires the ``langchain`` extra:  pip install "sift-tools[langchain]"
+"""
+from __future__ import annotations
+
+
+def langchain_tools(sift) -> list:
+    from langchain_core.tools import StructuredTool
+
+    def search_tools(q: str) -> str:
+        """Discover tools by natural language; returns candidate paths with scores."""
+        return sift.dispatch("search_tools", {"q": q})
+
+    def get_tool_schema(path: str) -> str:
+        """Compact (TOON) schema of a hierarchy level. Empty path lists categories."""
+        return sift.dispatch("get_tool_schema", {"path": path})
+
+    def execute_tool(path: str, params: dict | None = None) -> str:
+        """Execute a function (full path category.service.function) and return the filtered result."""
+        return sift.dispatch("execute_tool", {"path": path, "params": params or {}})
+
+    return [
+        StructuredTool.from_function(search_tools, name="search_tools"),
+        StructuredTool.from_function(get_tool_schema, name="get_tool_schema"),
+        StructuredTool.from_function(execute_tool, name="execute_tool"),
+    ]

sift/adapters/mcp_server.py

@@ -0,0 +1,35 @@
+"""MCP server adapter — expose SIFT as a Model Context Protocol server.
+
+Any MCP client (Claude Desktop, IDEs, etc.) then sees just the 3 meta-tools and
+discovers your whole catalogue through them.
+
+    from sift import Sift
+    sift = Sift(); ...; sift.build_index()
+    sift.serve_mcp()                 # runs a stdio MCP server
+
+Requires the ``mcp`` extra:  pip install "sift-tools[mcp]"
+"""
+from __future__ import annotations
+
+
+def build_mcp_server(sift, name: str = "sift"):
+    from mcp.server.fastmcp import FastMCP
+
+    server = FastMCP(name)
+
+    @server.tool()
+    def search_tools(q: str) -> str:
+        """Discover tools by natural language; returns candidate paths with scores."""
+        return sift.dispatch("search_tools", {"q": q})
+
+    @server.tool()
+    def get_tool_schema(path: str) -> str:
+        """Compact (TOON) schema of a hierarchy level. Empty path lists categories."""
+        return sift.dispatch("get_tool_schema", {"path": path})
+
+    @server.tool()
+    def execute_tool(path: str, params: dict | None = None) -> str:
+        """Execute a function (full path category.service.function); returns the filtered result."""
+        return sift.dispatch("execute_tool", {"path": path, "params": params or {}})
+
+    return server

sift/adapters/openai.py

@@ -0,0 +1,56 @@
+"""OpenAI / OpenRouter (function-calling) adapter.
+
+``sift.openai_tools()`` already returns the tool specs. This module adds a small
+driver that runs a full agent loop against any OpenAI-compatible client (the
+official ``openai`` SDK, OpenRouter via the same SDK, Azure, etc.). The client is
+duck-typed: it just needs ``client.chat.completions.create(...)``.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def run_agent(sift, client: Any, model: str, message: str, *,
+              max_steps: int = 12, verbose: bool = False,
+              extra_body: dict | None = None) -> str:
+    """Drive a tool-calling loop until the model returns a final answer.
+
+    ``extra_body`` is forwarded to ``chat.completions.create`` — use it for
+    provider extras like prompt caching or ``{"reasoning": {"effort": "low"}}``
+    to keep tool-routing turns cheap.
+    """
+    messages: list[dict] = [
+        {"role": "system", "content": sift.system_prompt},
+        {"role": "user", "content": message},
+    ]
+    tools = sift.openai_tools()
+
+    for _ in range(max_steps):
+        resp = client.chat.completions.create(
+            model=model, messages=messages, tools=tools, extra_body=extra_body or {})
+        msg = resp.choices[0].message
+
+        assistant: dict = {"role": "assistant", "content": msg.content or ""}
+        if getattr(msg, "tool_calls", None):
+            assistant["tool_calls"] = [
+                {"id": tc.id, "type": "function",
+                 "function": {"name": tc.function.name, "arguments": tc.function.arguments}}
+                for tc in msg.tool_calls
+            ]
+        messages.append(assistant)
+
+        if not getattr(msg, "tool_calls", None):
+            return msg.content or ""
+
+        for tc in msg.tool_calls:
+            result = sift.dispatch(tc.function.name, tc.function.arguments)
+            if verbose:
+                print(f"  ↳ {tc.function.name}({tc.function.arguments}) = {result[:200]}")
+            messages.append({
+                "role": "tool",
+                "tool_call_id": tc.id,
+                "name": tc.function.name,
+                "content": result,
+            })
+
+    raise RuntimeError(f"reached max_steps={max_steps} without a final answer")

sift/adapters/prompted.py

@@ -0,0 +1,109 @@
+"""Prompted (text-based) tool calling — for models WITHOUT native function calling.
+
+The core ``sift.dispatch(name, args)`` is format-agnostic, so any text model can
+drive SIFT if we (a) tell it a JSON protocol in the prompt and (b) parse its plain
+text back. This adapter does both, looping search -> execute -> answer.
+
+``generate`` is the only thing you supply: a callable ``generate(prompt: str) ->
+str``. That wraps ANYTHING — a HuggingFace pipeline, llama.cpp, Ollama /generate,
+a base model — so SIFT reaches models the native adapters can't.
+
+For weak models, pair this with constrained decoding (see ``sift.constrain``) and
+prefer :func:`single_decision`.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Callable
+
+PROMPTED_SYSTEM = """You solve the user's task using tools, by emitting JSON.
+
+You have 3 tools:
+- search_tools     args: {"q": "<what you need>"}   -> returns matching tool paths WITH their schema
+- get_tool_schema  args: {"path": "<'' | category | category.service>"}  -> browse (rarely needed)
+- execute_tool     args: {"path": "<category.service.function>", "params": {...}}  -> run a tool
+
+PROTOCOL — every reply MUST be exactly ONE JSON object and nothing else:
+  to use a tool:        {"tool": "<name>", "args": {...}}
+  to answer the user:   {"answer": "<your reply>"}
+
+Always start with search_tools, then execute_tool with a full path from the results,
+then give {"answer": ...}. Tool results are provided back to you as JSON."""
+
+
+def _extract_json(text: str) -> dict | None:
+    """Best-effort: pull the first JSON object out of a model's text reply."""
+    text = text.strip()
+    fenced = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.S)
+    if fenced:
+        try:
+            return json.loads(fenced.group(1))
+        except json.JSONDecodeError:
+            pass
+    start = text.find("{")
+    while start != -1:
+        depth = 0
+        for i in range(start, len(text)):
+            if text[i] == "{":
+                depth += 1
+            elif text[i] == "}":
+                depth -= 1
+                if depth == 0:
+                    try:
+                        return json.loads(text[start:i + 1])
+                    except json.JSONDecodeError:
+                        break
+        start = text.find("{", start + 1)
+    return None
+
+
+def run_agent(sift, generate: Callable[[str], str], message: str, *,
+              max_steps: int = 10, verbose: bool = False) -> str:
+    """Drive a text model through the tool loop. ``generate(prompt)->str``."""
+    transcript = f"{PROMPTED_SYSTEM}\n\nUser: {message}\n"
+
+    for _ in range(max_steps):
+        reply = generate(transcript + "Assistant:")
+        obj = _extract_json(reply)
+
+        if obj is None:
+            transcript += (f"Assistant: {reply.strip()[:200]}\n"
+                           'System: Invalid. Reply with ONE JSON object: '
+                           '{"tool": ...} or {"answer": ...}.\n')
+            continue
+
+        if "answer" in obj:
+            return str(obj["answer"])
+
+        if "tool" in obj:
+            result = sift.dispatch(obj["tool"], obj.get("args") or {})
+            if verbose:
+                print(f"  ↳ {obj['tool']}({obj.get('args')}) = {result[:160]}")
+            transcript += (f'Assistant: {json.dumps(obj, ensure_ascii=False)}\n'
+                           f"Tool result: {result}\n")
+            continue
+
+        transcript += ('System: JSON must contain "tool" or "answer".\n')
+
+    raise RuntimeError(f"reached max_steps={max_steps} without an answer")
+
+
+def single_decision(sift, generate: Callable[[str], str], query: str, *,
+                    top_k: int = 3) -> dict:
+    """One-shot path for very weak models: search server-side, then ask the model
+    for a SINGLE decision (which tool + args). Returns {path, args, result}."""
+    candidates = sift.gateway.search_compact(query, top_k)
+    prompt = (
+        f"{candidates}\n\n"
+        f"User wants: {query}\n"
+        'Reply with ONLY JSON: {"path": "<one path above>", "args": {<parameters>}}'
+    )
+    obj = _extract_json(generate(prompt)) or {}
+    path = obj.get("path")
+    args = obj.get("args") or {}
+    try:
+        result = sift.execute_tool(path, args) if path else {"error": "no path chosen"}
+    except Exception as exc:
+        result = {"error": str(exc)}
+    return {"path": path, "args": args, "result": result}