threadplane-client-tools 0.0.1__tar.gz

threadplane_client_tools-0.0.1/.gitignore

@@ -0,0 +1,64 @@
+# Worktrees
+.worktrees/
+.superpowers/
+.claude/worktrees/
+
+# Node
+node_modules/
+dist/
+.next/
+deploy/
+
+# Nx
+.nx/cache/
+.nx/workspace-data
+tmp/
+apps/website/test-results/
+# Demo media is hosted on Vercel Blob, not committed (see DemoShowcase.tsx /
+# apps/website/scripts/upload-demo-media.md). Keep these binaries out of git.
+apps/website/public/demo/
+cockpit/**/angular/test-results/
+/test-results/
+
+# Marketing channel dry-run simulation outputs (ephemeral; see "simulatedAt")
+marketing/channels/marketing/cowork/outbox/dry-runs/
+
+# Env
+.env
+.env.local
+
+# OS
+.DS_Store
+
+.angular
+
+# Next.js
+.next
+out
+.vercel
+
+# Whitepaper signup data
+apps/website/data/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+
+# LangGraph local runtime
+.langgraph_api/
+
+# Local LangGraph deployment deps
+deployments/*/deps/
+# ...but ag-ui-dev commits generated deps/ (Docker build copies them in)
+!deployments/ag-ui-dev/deps/
+!deployments/ag-ui-dev/deps/**
+
+# Generated license public key (produced by libs/licensing/scripts/generate-public-key.mjs)
+libs/licensing/src/lib/license-public-key.generated.ts
+
+# superpowers brainstorming output
+.superpowers/
+# TypeScript incremental build caches (any project)
+*.tsbuildinfo

threadplane_client_tools-0.0.1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: threadplane-client-tools
+Version: 0.0.1
+Summary: LangGraph middleware for binding client-declared tool stubs and routing client tool calls to END so the browser executes them.
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langgraph>=0.3.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# threadplane-client-tools
+
+LangGraph middleware for binding client-declared tool stubs and routing
+client tool calls to `END` so the browser executes them.
+
+## How it works
+
+When a browser client sends a tool catalog (`{name, description, parameters}`
+dicts) along with a run request, the graph can expose those tools to the LLM
+and route their calls back to the browser instead of executing them
+server-side. The browser then executes the call and re-runs the graph with a
+`ToolMessage` carrying the result.
+
+The catalog is read from `state["tools"]`, falling back to
+`state["client_tools"]` if `tools` is absent.
+
+## Installation
+
+```bash
+pip install threadplane-client-tools
+```
+
+## Usage
+
+```python
+from langgraph.graph import END, StateGraph
+from threadplane.client_tools import bind_client_tools, route_after_agent
+
+# Server-side tools your graph owns
+SERVER_TOOLS = [search_tool, calculator_tool]
+base_llm = ChatOpenAI(model="gpt-4o")
+
+def agent_node(state):
+    # bind_client_tools must be called per-run inside the node because
+    # the client catalog arrives in state and may differ between runs.
+    llm = bind_client_tools(base_llm, SERVER_TOOLS, state)
+    response = llm.invoke(state["messages"])
+    return {"messages": [response]}
+
+def router(state):
+    # Returns "tools" for server tool calls, "__end__" otherwise.
+    # Map "__end__" to LangGraph's END in add_conditional_edges.
+    return route_after_agent(state, [t.name for t in SERVER_TOOLS])
+
+graph = StateGraph(...)
+graph.add_node("agent", agent_node)
+graph.add_node("tools", ToolNode(SERVER_TOOLS))
+graph.add_conditional_edges("agent", router, {"tools": "tools", "__end__": END})
+```
+
+### What happens with a client tool call
+
+1. The LLM emits a tool call whose name matches a client-declared tool.
+2. `route_after_agent` returns `"__end__"` — the graph run ends.
+3. The browser receives the partial output, executes the tool locally, and
+   re-runs the graph with a `ToolMessage` containing the result.
+4. The LLM continues from there as if it had called a server tool.
+
+### Lower-level helpers
+
+```python
+from threadplane.client_tools import (
+    client_tool_specs,   # → list of OpenAI function-tool dicts
+    client_tool_names,   # → set[str] of client tool names
+    has_client_tool_call,  # → bool
+    has_server_tool_call,  # → bool
+    last_message,          # → last message from state["messages"]
+)
+```
+
+## Development
+
+```bash
+uv venv
+uv pip install -e '.[test]'
+uv run pytest -q
+```

threadplane_client_tools-0.0.1/README.md

@@ -0,0 +1,77 @@
+# threadplane-client-tools
+
+LangGraph middleware for binding client-declared tool stubs and routing
+client tool calls to `END` so the browser executes them.
+
+## How it works
+
+When a browser client sends a tool catalog (`{name, description, parameters}`
+dicts) along with a run request, the graph can expose those tools to the LLM
+and route their calls back to the browser instead of executing them
+server-side. The browser then executes the call and re-runs the graph with a
+`ToolMessage` carrying the result.
+
+The catalog is read from `state["tools"]`, falling back to
+`state["client_tools"]` if `tools` is absent.
+
+## Installation
+
+```bash
+pip install threadplane-client-tools
+```
+
+## Usage
+
+```python
+from langgraph.graph import END, StateGraph
+from threadplane.client_tools import bind_client_tools, route_after_agent
+
+# Server-side tools your graph owns
+SERVER_TOOLS = [search_tool, calculator_tool]
+base_llm = ChatOpenAI(model="gpt-4o")
+
+def agent_node(state):
+    # bind_client_tools must be called per-run inside the node because
+    # the client catalog arrives in state and may differ between runs.
+    llm = bind_client_tools(base_llm, SERVER_TOOLS, state)
+    response = llm.invoke(state["messages"])
+    return {"messages": [response]}
+
+def router(state):
+    # Returns "tools" for server tool calls, "__end__" otherwise.
+    # Map "__end__" to LangGraph's END in add_conditional_edges.
+    return route_after_agent(state, [t.name for t in SERVER_TOOLS])
+
+graph = StateGraph(...)
+graph.add_node("agent", agent_node)
+graph.add_node("tools", ToolNode(SERVER_TOOLS))
+graph.add_conditional_edges("agent", router, {"tools": "tools", "__end__": END})
+```
+
+### What happens with a client tool call
+
+1. The LLM emits a tool call whose name matches a client-declared tool.
+2. `route_after_agent` returns `"__end__"` — the graph run ends.
+3. The browser receives the partial output, executes the tool locally, and
+   re-runs the graph with a `ToolMessage` containing the result.
+4. The LLM continues from there as if it had called a server tool.
+
+### Lower-level helpers
+
+```python
+from threadplane.client_tools import (
+    client_tool_specs,   # → list of OpenAI function-tool dicts
+    client_tool_names,   # → set[str] of client tool names
+    has_client_tool_call,  # → bool
+    has_server_tool_call,  # → bool
+    last_message,          # → last message from state["messages"]
+)
+```
+
+## Development
+
+```bash
+uv venv
+uv pip install -e '.[test]'
+uv run pytest -q
+```

threadplane_client_tools-0.0.1/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "threadplane-client-tools"
+version = "0.0.1"
+description = "LangGraph middleware for binding client-declared tool stubs and routing client tool calls to END so the browser executes them."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "langchain-core>=0.3.0",
+    "langgraph>=0.3.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/threadplane"]

threadplane_client_tools-0.0.1/src/threadplane/client_tools/__init__.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: MIT
+"""threadplane-client-tools — LangGraph middleware for client-declared tools."""
+
+from threadplane.client_tools.middleware import (
+    bind_client_tools,
+    client_tool_names,
+    client_tool_specs,
+    has_client_tool_call,
+    has_server_tool_call,
+    last_message,
+    route_after_agent,
+)
+
+__all__ = [
+    "bind_client_tools",
+    "client_tool_names",
+    "client_tool_specs",
+    "has_client_tool_call",
+    "has_server_tool_call",
+    "last_message",
+    "route_after_agent",
+]

threadplane_client_tools-0.0.1/src/threadplane/client_tools/middleware.py

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: MIT
+"""client-tools middleware: bind client-declared tool stubs and route their
+calls to END so the browser executes them and re-runs with a ToolMessage."""
+from __future__ import annotations
+from typing import Any, Iterable
+
+
+def _catalog(state: dict) -> list[dict]:
+    raw = state.get("tools")
+    if not raw:
+        raw = state.get("client_tools")
+    return [t for t in (raw or []) if isinstance(t, dict) and t.get("name")]
+
+
+def client_tool_specs(state: dict) -> list[dict]:
+    """The client catalog as OpenAI function-tool dicts for ``llm.bind_tools``.
+
+    Each entry in ``state["tools"]`` (or ``state["client_tools"]`` as a
+    fallback) is converted to the explicit
+    ``{"type": "function", "function": {...}}`` form that is accepted by
+    ``ChatOpenAI(...).bind_tools([...])`` regardless of LangChain version.
+    """
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": t["name"],
+                "description": t.get("description", ""),
+                "parameters": t.get("parameters", {}) or {},
+            },
+        }
+        for t in _catalog(state)
+    ]
+
+
+def client_tool_names(state: dict) -> set[str]:
+    """Return the set of tool names declared by the client in this run."""
+    return {t["name"] for t in _catalog(state)}
+
+
+def _tool_calls(message: Any) -> list:
+    tc = (
+        message.get("tool_calls")
+        if isinstance(message, dict)
+        else getattr(message, "tool_calls", None)
+    )
+    return list(tc or [])
+
+
+def _call_name(call: Any) -> str | None:
+    if isinstance(call, dict):
+        return call.get("name") or (call.get("function") or {}).get("name")
+    return getattr(call, "name", None)
+
+
+def last_message(state: dict) -> Any:
+    """Return the last message from ``state["messages"]``, or None."""
+    msgs = state.get("messages") or []
+    return msgs[-1] if msgs else None
+
+
+def has_client_tool_call(state: dict) -> bool:
+    """True if the last message calls at least one tool that is a client tool."""
+    names = client_tool_names(state)
+    return any(_call_name(c) in names for c in _tool_calls(last_message(state)))
+
+
+def has_server_tool_call(state: dict, server_tool_names: Iterable[str]) -> bool:
+    """True if the last message calls at least one server (non-client) tool.
+
+    A call is treated as a server call when its name appears in
+    ``server_tool_names`` OR when its name is not a known client tool name
+    (unknown tools are assumed to be server-side).
+    """
+    server = set(server_tool_names)
+    client = client_tool_names(state)
+    for c in _tool_calls(last_message(state)):
+        n = _call_name(c)
+        if n in server or (n is not None and n not in client):
+            return True
+    return False
+
+
+def bind_client_tools(llm: Any, server_tools: list, state: dict) -> Any:
+    """Bind server tools + the client catalog stubs onto ``llm``.
+
+    Call this *inside* the agent node (per-run) because the client catalog
+    arrives in state and may differ between runs.
+
+    Example::
+
+        def agent_node(state):
+            bound = bind_client_tools(base_llm, SERVER_TOOLS, state)
+            response = bound.invoke(state["messages"])
+            return {"messages": [response]}
+    """
+    return llm.bind_tools([*server_tools, *client_tool_specs(state)])
+
+
+def route_after_agent(
+    state: dict,
+    server_tool_names: Iterable[str],
+    *,
+    tools_node: str = "tools",
+    end: str = "__end__",
+) -> str:
+    """Routing helper to call from a LangGraph conditional edge.
+
+    Returns:
+        ``tools_node`` when the last message contains a server tool call
+        (so LangGraph dispatches to the server-side ToolNode).
+        ``end`` when the last message contains only client tool calls
+        (the browser executes the call; map ``end`` to LangGraph's ``END``).
+        ``end`` when the last message has no tool calls at all.
+
+    Note: this helper is LangGraph-free — it returns plain strings so callers
+    can map the return value to ``END`` themselves::
+
+        from langgraph.graph import END
+        graph.add_conditional_edges(
+            "agent",
+            lambda s: route_after_agent(s, ["search"]),
+            {"tools": "tools", "__end__": END},
+        )
+    """
+    if has_server_tool_call(state, server_tool_names):
+        return tools_node
+    return end