toolnexus 0.1.1__tar.gz

toolnexus-0.1.1/.gitignore

@@ -0,0 +1,28 @@
+# JS
+node_modules/
+js/dist/
+*.tsbuildinfo
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+
+# Go
+golang/bin/
+
+# OS / editor
+.DS_Store
+*.log
+.env
+
+# compiled Go binaries (examples / CLI built in-place)
+golang/agent
+golang/openrouter
+golang/toolnexus
+golang/cmd/toolnexus/toolnexus

toolnexus-0.1.1/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: toolnexus
+Version: 0.1.1
+Summary: Provider-agnostic toolkit: dynamic MCP servers + agent skills for any LLM.
+Author-email: Muthukumaran Navaneethakrishnan <muthuishere@gmail.com>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# toolnexus (Python)
+
+Provider-agnostic toolkit that gives **any LLM** the two dynamic capabilities
+opencode has:
+
+1. **Dynamic MCP servers** — read an MCP config file, connect to every server
+   (local stdio + remote streamable-HTTP), and expose each server tool as a
+   uniform `Tool`.
+2. **Dynamic agent skills** — read a skills folder (`**/SKILL.md`) and expose a
+   single `skill` tool that loads a skill's instructions + resources on demand
+   (progressive disclosure).
+
+Built on the official MCP Python SDK (the `mcp` package). This is the Python
+sibling of the `js/` reference implementation; the contract is shared
+(`../SPEC.md`).
+
+## Install
+
+```bash
+uv venv
+uv pip install -e .
+```
+
+(Or with stdlib venv: `python -m venv .venv && .venv/bin/pip install -e .`.)
+
+## Quickstart
+
+The MCP SDK is async, so the toolkit is async. Manage its lifetime with
+`async with`:
+
+```python
+import asyncio
+from toolnexus import create_toolkit
+
+
+async def main():
+    async with await create_toolkit(
+        mcp_config="../examples/mcp.json",
+        skills_dir="../examples/skills",
+    ) as tk:
+        print(tk.mcp_status())                       # {"everything": "connected", ...}
+        print([t.name for t in tk.tools()])          # mcp tools + "skill"
+        print(tk.skills_prompt())                    # ## Available Skills ...
+
+        tools = tk.to_openai()                        # or to_anthropic() / to_gemini()
+
+        # ... call your LLM with `tools` + skills_prompt() as system text ...
+        # model returns a tool_call { name, arguments }
+
+        res = await tk.execute(name, arguments)       # routes to the right tool
+        print(res.output)                             # feed back to the model
+
+
+asyncio.run(main())
+```
+
+`create_toolkit(...)` is an async factory. The returned `Toolkit` is also an
+async context manager; if you do not use `async with`, call `await tk.close()`
+yourself to disconnect every MCP client.
+
+## API
+
+| Python                       | JS / SPEC equivalent |
+|------------------------------|----------------------|
+| `await create_toolkit(...)`  | `createToolkit(...)` |
+| `tk.tools()`                 | `tk.tools()`         |
+| `tk.get(name)`               | `tk.get(name)`       |
+| `await tk.execute(name, args, ctx=None)` | `tk.execute(...)` |
+| `tk.skills_prompt()`         | `tk.skillsPrompt()`  |
+| `tk.mcp_status()`            | `tk.mcpStatus()`     |
+| `tk.to_openai()` / `to_anthropic()` / `to_gemini()` | `toOpenAI()` etc. |
+| `await tk.close()`           | `tk.close()`         |
+
+A uniform `Tool` has `name`, `description`, `input_schema`, `source`
+(`"mcp" | "skill" | "custom"`), and an async `execute(args, ctx=None)` returning
+a `ToolResult(output, is_error, metadata)`.
+
+## Examples
+
+- `examples/basic.py` — connect to the `everything` MCP server, list tools,
+  print the skills catalog, and load the `hello-world` skill (progressive
+  disclosure). Requires `npx` on PATH (for `@modelcontextprotocol/server-everything`).
+- `examples/openrouter_test.py` — a real OpenRouter tool-calling round trip.
+  Reads `OPENROUTER_API_KEY` from the environment (never hardcode it).

toolnexus-0.1.1/README.md

@@ -0,0 +1,84 @@
+# toolnexus (Python)
+
+Provider-agnostic toolkit that gives **any LLM** the two dynamic capabilities
+opencode has:
+
+1. **Dynamic MCP servers** — read an MCP config file, connect to every server
+   (local stdio + remote streamable-HTTP), and expose each server tool as a
+   uniform `Tool`.
+2. **Dynamic agent skills** — read a skills folder (`**/SKILL.md`) and expose a
+   single `skill` tool that loads a skill's instructions + resources on demand
+   (progressive disclosure).
+
+Built on the official MCP Python SDK (the `mcp` package). This is the Python
+sibling of the `js/` reference implementation; the contract is shared
+(`../SPEC.md`).
+
+## Install
+
+```bash
+uv venv
+uv pip install -e .
+```
+
+(Or with stdlib venv: `python -m venv .venv && .venv/bin/pip install -e .`.)
+
+## Quickstart
+
+The MCP SDK is async, so the toolkit is async. Manage its lifetime with
+`async with`:
+
+```python
+import asyncio
+from toolnexus import create_toolkit
+
+
+async def main():
+    async with await create_toolkit(
+        mcp_config="../examples/mcp.json",
+        skills_dir="../examples/skills",
+    ) as tk:
+        print(tk.mcp_status())                       # {"everything": "connected", ...}
+        print([t.name for t in tk.tools()])          # mcp tools + "skill"
+        print(tk.skills_prompt())                    # ## Available Skills ...
+
+        tools = tk.to_openai()                        # or to_anthropic() / to_gemini()
+
+        # ... call your LLM with `tools` + skills_prompt() as system text ...
+        # model returns a tool_call { name, arguments }
+
+        res = await tk.execute(name, arguments)       # routes to the right tool
+        print(res.output)                             # feed back to the model
+
+
+asyncio.run(main())
+```
+
+`create_toolkit(...)` is an async factory. The returned `Toolkit` is also an
+async context manager; if you do not use `async with`, call `await tk.close()`
+yourself to disconnect every MCP client.
+
+## API
+
+| Python                       | JS / SPEC equivalent |
+|------------------------------|----------------------|
+| `await create_toolkit(...)`  | `createToolkit(...)` |
+| `tk.tools()`                 | `tk.tools()`         |
+| `tk.get(name)`               | `tk.get(name)`       |
+| `await tk.execute(name, args, ctx=None)` | `tk.execute(...)` |
+| `tk.skills_prompt()`         | `tk.skillsPrompt()`  |
+| `tk.mcp_status()`            | `tk.mcpStatus()`     |
+| `tk.to_openai()` / `to_anthropic()` / `to_gemini()` | `toOpenAI()` etc. |
+| `await tk.close()`           | `tk.close()`         |
+
+A uniform `Tool` has `name`, `description`, `input_schema`, `source`
+(`"mcp" | "skill" | "custom"`), and an async `execute(args, ctx=None)` returning
+a `ToolResult(output, is_error, metadata)`.
+
+## Examples
+
+- `examples/basic.py` — connect to the `everything` MCP server, list tools,
+  print the skills catalog, and load the `hello-world` skill (progressive
+  disclosure). Requires `npx` on PATH (for `@modelcontextprotocol/server-everything`).
+- `examples/openrouter_test.py` — a real OpenRouter tool-calling round trip.
+  Reads `OPENROUTER_API_KEY` from the environment (never hardcode it).

toolnexus-0.1.1/examples/advanced.py

@@ -0,0 +1,157 @@
+"""Verify parallel tool calling (many calls in one turn) and chained tool calling
+(a later call depends on an earlier result, across turns). Mirrors
+js/examples/advanced.ts.
+
+Run from a venv where the package is installed (`uv pip install -e .`):
+    python examples/advanced.py                          # skips live section, exits 0
+    OPENROUTER_API_KEY=... python examples/advanced.py   # runs the live checks
+
+The API key is read from the environment and is NEVER printed.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from typing import Any
+
+from toolnexus import create_client, create_toolkit, define_tool, http_tool
+
+
+def _max_parallel(messages: list[dict[str, Any]]) -> int:
+    """Largest number of tool calls the model emitted in a single assistant turn."""
+    m = 0
+    for msg in messages:
+        if msg.get("role") == "assistant" and isinstance(msg.get("tool_calls"), list):
+            m = max(m, len(msg["tool_calls"]))
+    return m
+
+
+def _tool_turns(messages: list[dict[str, Any]]) -> int:
+    """Number of assistant turns that issued tool calls (chain depth)."""
+    return sum(
+        1
+        for m in messages
+        if m.get("role") == "assistant"
+        and isinstance(m.get("tool_calls"), list)
+        and len(m["tool_calls"])
+    )
+
+
+async def main() -> None:
+    tk = await create_toolkit({})
+
+    # a native (annotation) tool
+    def add(a: float, b: float) -> str:
+        """Add two numbers and return the sum."""
+        return str(a + b)
+
+    tk.register(define_tool(add, name="add"))
+
+    # an HTTP tool (public test API, no auth)
+    tk.register(
+        http_tool(
+            name="get_post",
+            description="Fetch a placeholder blog post by id.",
+            method="GET",
+            url="https://jsonplaceholder.typicode.com/posts/{id}",
+            input_schema={
+                "type": "object",
+                "properties": {"id": {"type": "number"}},
+                "required": ["id"],
+                "additionalProperties": False,
+            },
+        )
+    )
+
+    # opaque: the model CANNOT guess this value, so it must call it first and wait
+    def todays_post_id() -> str:
+        """Returns the server-chosen blog post id to read today. Cannot be guessed; you must call it."""
+        return "3"
+
+    tk.register(define_tool(todays_post_id, name="todays_post_id"))
+
+    key = os.environ.get("OPENROUTER_API_KEY")
+    if not key:
+        print("no OPENROUTER_API_KEY — skipping")
+        await tk.close()
+        return
+
+    agent = create_client(
+        base_url="https://openrouter.ai/api/v1",
+        style="openai",
+        model=os.environ.get("OPENROUTER_MODEL", "openai/gpt-4o-mini"),
+        api_key=key,
+        system_prompt="You are a precise agent. Prefer issuing independent tool calls together in one step.",
+    )
+
+    # ---- A) PARALLEL: two independent adds, ideally in one turn ----
+    a = await agent.run(
+        "In a single step, call the add tool twice: add 2 and 3, and add 100 and 200. Then report both sums.",
+        tk,
+    )
+    print(
+        "A) parallel — tool calls:",
+        [f"{c['name']}({json.dumps(c['args'])})={c['output']}" for c in a.tool_calls],
+    )
+    print(
+        "A) max calls in one turn:",
+        _max_parallel(a.messages),
+        "| answer:",
+        a.text.replace("\n", " ")[:60],
+    )
+    print(
+        "A) usage:",
+        a.usage,
+        "| tool_call_count:",
+        a.tool_call_count,
+        "| turns:",
+        a.turns,
+        "| model:",
+        a.model,
+    )
+    print("A) first tool result metadata:", a.tool_calls[0]["metadata"] if a.tool_calls else None)
+
+    # ---- B) CHAIN: second call depends on an OPAQUE first result (forces a 2nd turn) ----
+    b = await agent.run(
+        "Call todays_post_id to find which post to read, then use get_post to fetch that exact id and tell me its title.",
+        tk,
+    )
+    print(
+        "\nB) chain — tool calls:",
+        [f"{c['name']}({json.dumps(c['args'])})" for c in b.tool_calls],
+    )
+    print("B) tool-calling turns (chain depth):", _tool_turns(b.messages))
+    print("B) answer:", b.text.replace("\n", " ")[:100])
+
+    await tk.close()
+
+    # ---- assertions ----
+    parallel_ok = _max_parallel(a.messages) >= 2
+    called_add = sum(1 for c in a.tool_calls if c["name"] == "add") >= 2
+    # true chain: todays_post_id THEN get_post(id=3) across ≥2 turns (id=3 is unguessable)
+    chain_ok = (
+        _tool_turns(b.messages) >= 2
+        and any(c["name"] == "todays_post_id" for c in b.tool_calls)
+        and any(
+            c["name"] == "get_post" and int(c["args"].get("id", 0)) == 3
+            for c in b.tool_calls
+        )
+    )
+    print(
+        f"\nparallel: {'✅ multiple calls in one turn' if parallel_ok else '⚠️ model serialized'}"
+        f" | ran {sum(1 for c in a.tool_calls if c['name'] == 'add')} adds"
+    )
+    print(
+        f"chain:    {'✅ get_post(id=3) used the opaque result across turns' if chain_ok else '❌ chain not observed'}"
+    )
+    if not called_add or not parallel_ok or not chain_ok:
+        raise SystemExit(
+            "❌ expected ≥2 parallel adds AND a real cross-turn chain "
+            "(todays_post_id → get_post(id=3))"
+        )
+    print("\n✅ parallel + chained tool calling verified")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

toolnexus-0.1.1/examples/agent.py

@@ -0,0 +1,81 @@
+"""Full agent example: MCP tools + skills + a native tool + an HTTP tool, driven
+by the unified client host loop. Mirrors js/examples/agent.ts.
+
+Run from a venv where the package is installed (`uv pip install -e .`):
+    python examples/agent.py                     # tools list only, exits cleanly
+    OPENROUTER_API_KEY=... python examples/agent.py   # runs the live loop
+
+Requires `npx` on PATH for the @modelcontextprotocol/server-everything stdio
+server. The API key is read from the environment and never printed.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+
+from toolnexus import create_client, create_toolkit, define_tool, http_tool
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_EXAMPLES = os.path.normpath(os.path.join(_HERE, "..", "..", "examples"))
+
+
+async def main() -> None:
+    tk = await create_toolkit(
+        mcp_config=os.path.join(_EXAMPLES, "mcp.json"),
+        skills_dir=os.path.join(_EXAMPLES, "skills"),
+    )
+
+    # a native (annotation) tool
+    def add(a: float, b: float) -> str:
+        """Add two numbers and return the sum."""
+        return str(a + b)
+
+    tk.register(define_tool(add, name="add"))
+
+    # an HTTP tool (public test API, no auth)
+    tk.register(
+        http_tool(
+            name="get_post",
+            description="Fetch a placeholder blog post by id from jsonplaceholder.",
+            method="GET",
+            url="https://jsonplaceholder.typicode.com/posts/{id}",
+            input_schema={
+                "type": "object",
+                "properties": {"id": {"type": "number", "description": "post id 1-100"}},
+                "required": ["id"],
+                "additionalProperties": False,
+            },
+        )
+    )
+
+    print("Tools:", [f"{t.name} ({t.source})" for t in tk.tools()])
+
+    key = os.environ.get("OPENROUTER_API_KEY")
+    if not key:
+        print("\n(no OPENROUTER_API_KEY — skipping live loop)")
+        await tk.close()
+        return
+
+    agent = create_client(
+        base_url="https://openrouter.ai/api/v1",
+        style="openai",
+        model=os.environ.get("OPENROUTER_MODEL", "openai/gpt-4o-mini"),
+        api_key=key,
+        system_prompt="You are a precise agent. Use tools to compute and fetch facts.",
+    )
+
+    res = await agent.run(
+        "What is 21 + 21? Use the add tool. Then fetch post id 1 and tell me its title.",
+        tk,
+    )
+    print("\nTool calls:", [c["name"] for c in res.tool_calls])
+    print("\nFINAL:\n" + res.text)
+
+    await tk.close()
+    if "42" not in res.text:
+        raise SystemExit("expected 42 in answer")
+    print("\nPython agent loop (native + http + mcp + skills) OK")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

toolnexus-0.1.1/examples/basic.py

@@ -0,0 +1,42 @@
+"""Minimal end-to-end example. Mirrors js/examples/basic.ts.
+
+Run from a venv where the package is installed (`uv pip install -e .`):
+    python examples/basic.py
+
+Uses the shared sample fixtures in ../../examples/. Requires `npx` on PATH for
+the `@modelcontextprotocol/server-everything` stdio server.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+
+from toolnexus import create_toolkit
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_EXAMPLES = os.path.normpath(os.path.join(_HERE, "..", "..", "examples"))
+
+
+async def main() -> None:
+    tk = await create_toolkit(
+        mcp_config=os.path.join(_EXAMPLES, "mcp.json"),
+        skills_dir=os.path.join(_EXAMPLES, "skills"),
+    )
+
+    print("MCP status:", tk.mcp_status())
+    print("Tools:", [f"{t.name} ({t.source})" for t in tk.tools()])
+    print("\nSystem-prompt skill catalog:\n" + tk.skills_prompt())
+
+    print("\nOpenAI tool schema (first 2):")
+    print(json.dumps(tk.to_openai()[:2], indent=2))
+
+    # Load a skill (progressive disclosure) — works with no MCP servers running.
+    res = await tk.execute("skill", {"name": "hello-world"})
+    print("\nskill(hello-world) ->\n" + res.output)
+
+    await tk.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

toolnexus-0.1.1/examples/hooks.py

@@ -0,0 +1,127 @@
+"""Lifecycle hooks: before_llm / after_llm / before_tool / after_tool — observe,
+mutate, and short-circuit. Mirrors js/examples/hooks.ts.
+
+Run from a venv where the package is installed (`uv pip install -e .`):
+    python examples/hooks.py                       # import + setup only (no key)
+    OPENROUTER_API_KEY=... python examples/hooks.py   # runs the live loop
+
+The API key is read from the environment and is NEVER printed.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+
+from toolnexus import ToolResult, create_client, create_toolkit, define_tool, http_tool
+
+
+async def main() -> None:
+    tk = await create_toolkit()
+
+    def add(a: float, b: float) -> str:
+        """Add two numbers and return the sum."""
+        return str(a + b)
+
+    tk.register(
+        define_tool(add, name="add"),
+        http_tool(
+            name="get_post",
+            description="Fetch a placeholder blog post by id.",
+            method="GET",
+            url="https://jsonplaceholder.typicode.com/posts/{id}",
+            input_schema={
+                "type": "object",
+                "properties": {"id": {"type": "number", "description": "post id 1-100"}},
+                "required": ["id"],
+                "additionalProperties": False,
+            },
+        ),
+    )
+
+    # Spy on whether get_post's real execute ever runs (it must NOT — we deny it
+    # in a before_tool hook before it can reach the network).
+    real = tk.get("get_post")
+    assert real is not None
+    http_hits = {"n": 0}
+    orig = real.execute
+
+    async def spy(args, ctx=None):
+        http_hits["n"] += 1
+        return await orig(args, ctx)
+
+    real.execute = spy  # type: ignore[assignment]
+
+    counts = {"before_llm": 0, "after_llm": 0, "before_tool": 0, "after_tool": 0, "denied": 0}
+
+    # Hooks as a plain dict of snake_case callables (sync here; async is also fine).
+    def before_llm(ev):
+        counts["before_llm"] += 1
+        print(f"  [before_llm] turn {ev['turn']}")
+
+    def after_llm(ev):
+        counts["after_llm"] += 1
+        print(f"  [after_llm] turn {ev['turn']} usage {ev['response'].get('usage')}")
+
+    def before_tool(ev):
+        counts["before_tool"] += 1
+        print(f"  [before_tool] {ev['name']}({json.dumps(ev['args'])})")
+        if ev["name"] == "get_post":
+            counts["denied"] += 1
+            # SHORT-CIRCUIT: deny the tool. The model never sees real data and the
+            # real http execute never runs.
+            return {"result": ToolResult(output="DENIED: get_post is blocked by policy", is_error=True)}
+
+    def after_tool(ev):
+        counts["after_tool"] += 1
+        print(f"  [after_tool] {ev['name']} -> {ev['result'].output[:40]}")
+
+    hooks = {
+        "before_llm": before_llm,
+        "after_llm": after_llm,
+        "before_tool": before_tool,
+        "after_tool": after_tool,
+    }
+
+    key = os.environ.get("OPENROUTER_API_KEY")
+    if not key:
+        print("(no OPENROUTER_API_KEY — import + setup OK, skipping live loop)")
+        await tk.close()
+        return
+
+    agent = create_client(
+        base_url="https://openrouter.ai/api/v1",
+        style="openai",
+        model=os.environ.get("OPENROUTER_MODEL", "openai/gpt-4o-mini"),
+        api_key=key,
+        system_prompt="You are an agent. Use tools when asked.",
+        hooks=hooks,
+    )
+
+    out = await agent.run(
+        "Add 2 and 3 with the add tool, then fetch post id 1 with get_post.", tk
+    )
+    await tk.close()
+
+    print("\nFINAL:", out.text.replace("\n", " ")[:100])
+    print(
+        "hook counts:", counts,
+        "| http actually hit:", http_hits["n"],
+        "| usage:", out.usage,
+    )
+
+    ok = (
+        counts["before_llm"] >= 1
+        and counts["after_llm"] >= 1
+        and counts["before_tool"] >= 2
+        and counts["after_tool"] >= 1
+        and counts["denied"] >= 1
+        and http_hits["n"] == 0  # deny short-circuited the real http execute
+    )
+    if not ok:
+        raise SystemExit("hooks did not all fire / short-circuit failed")
+    print("\nall four hooks fired; before_tool short-circuited get_post (0 real http hits)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

toolnexus-0.1.1/examples/memory.py

@@ -0,0 +1,51 @@
+"""Conversation memory: a Conversation retains history across send() calls.
+
+Mirrors js/examples/memory.ts. Reads OPENROUTER_API_KEY from the environment
+(never hardcoded, never printed); skips the live call if it is unset.
+
+Run from a venv where the package is installed:
+    OPENROUTER_API_KEY=... python examples/memory.py
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+
+from toolnexus import create_client, create_toolkit
+
+
+async def main() -> None:
+    tk = await create_toolkit()
+
+    key = os.environ.get("OPENROUTER_API_KEY")
+    if not key:
+        print("no OPENROUTER_API_KEY — skipping (imports OK)")
+        await tk.close()
+        return
+
+    agent = create_client(
+        base_url="https://openrouter.ai/api/v1",
+        style="openai",
+        model=os.environ.get("OPENROUTER_MODEL", "openai/gpt-4o-mini"),
+        api_key=key,
+    )
+
+    convo = agent.conversation(tk)
+
+    a = await convo.send("My name is Muthu and my favorite number is 7. Reply with just 'noted'.")
+    print("turn 1:", a.text.replace("\n", " ")[:60], "| messages:", len(convo.messages))
+
+    b = await convo.send("What is my name and favorite number?")
+    print("turn 2:", b.text.replace("\n", " ")[:80], "| messages:", len(convo.messages))
+
+    await tk.close()
+    remembered = bool(re.search(r"muthu", b.text, re.I)) and bool(re.search(r"7|seven", b.text, re.I))
+    if not remembered:
+        print("FAILED conversation did not retain memory across turns")
+        raise SystemExit(1)
+    print("\nOK conversation memory verified — turn 2 recalled facts from turn 1")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())