toolbox-gateway 0.1.0__tar.gz

toolbox_gateway-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# ── Python ─────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+*.db
+.idea/
+.vscode/
+
+# ── JavaScript ─────────────────────────────────────────────────────────
+node_modules/
+dist/
+*.d.ts
+*.js.map
+*.tsbuildinfo
+.next/
+coverage/
+.yalc/
+yalc.lock
+
+# ── OS / Editor ────────────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+*~

toolbox_gateway-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: toolbox-gateway
+Version: 0.1.0
+Summary: Single-tool gateway pattern for LLM agents — discover, inspect, and execute tools on demand
+Author: Jason McNeal
+License-Expression: MIT
+Keywords: agent,ai,llm,mcp,token-optimization,tools
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == 'langchain'
+Requires-Dist: pydantic>=2.0; extra == 'langchain'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# toolbox-gateway
+
+Python implementation of the single-tool gateway pattern for LLM agents.
+
+See the [top-level README](../../README.md) for full documentation.
+
+Install: `pip install toolbox-gateway`
+Import: `from toolbox import Toolbox, Tool`

toolbox_gateway-0.1.0/README.md

@@ -0,0 +1,8 @@
+# toolbox-gateway
+
+Python implementation of the single-tool gateway pattern for LLM agents.
+
+See the [top-level README](../../README.md) for full documentation.
+
+Install: `pip install toolbox-gateway`
+Import: `from toolbox import Toolbox, Tool`

toolbox_gateway-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "toolbox-gateway"
+version = "0.1.0"
+description = "Single-tool gateway pattern for LLM agents — discover, inspect, and execute tools on demand"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Jason McNeal" },
+]
+keywords = ["llm", "ai", "agent", "tools", "mcp", "token-optimization"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+redis = ["redis>=5.0"]
+langchain = ["langchain-core>=0.1", "pydantic>=2.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff>=0.4"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/toolbox"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

toolbox_gateway-0.1.0/src/toolbox/__init__.py

@@ -0,0 +1,20 @@
+"""Toolbox — a single-tool gateway pattern for LLM agents."""
+
+__version__ = "0.1.0"
+
+from .core import Toolbox, Tool
+from .hints import HintStore, Hint, MemoryHintStore
+from .backends.sqlite_store import SQLiteHintStore
+
+__all__ = [
+    "Toolbox",
+    "Tool",
+    "HintStore",
+    "Hint",
+    "MemoryHintStore",
+    "SQLiteHintStore",
+]
+
+# Opt-in: schema formatting utilities
+# Usage: from toolbox.schema import schema_to_csv, schema_to_markdown, data_to_csv
+# Requires: pip install toolbox-gateway[schema] (future: may add dependencies)

toolbox_gateway-0.1.0/src/toolbox/adapters/__init__.py

@@ -0,0 +1 @@
+""

toolbox_gateway-0.1.0/src/toolbox/adapters/langchain.py

@@ -0,0 +1,98 @@
+"""LangChain adapter for Toolbox.
+
+Converts the toolbox into a single LangChain BaseTool instance.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from ..core import Toolbox
+
+
+class LangChainAdapter:
+    """Adapt Toolbox as a single LangChain tool.
+
+    Requires langchain-core to be installed.
+
+    Usage::
+
+        adapter = LangChainAdapter(toolbox)
+        tool = adapter.as_tool()
+
+        # Use in a LangChain agent
+        agent = create_react_agent(llm, [tool], prompt)
+    """
+
+    def __init__(self, toolbox: Toolbox) -> None:
+        self.toolbox = toolbox
+
+    def as_tool(self) -> Any:
+        """Return a LangChain BaseTool wrapping the toolbox.
+
+        Raises ImportError if langchain-core is not installed.
+        """
+        try:
+            from langchain_core.tools import StructuredTool
+        except ImportError as e:
+            raise ImportError(
+                "langchain-core is required for the LangChain adapter. "
+                "Install it with: pip install langchain-core"
+            ) from e
+
+        def _run(command: str, **kwargs: Any) -> str:
+            result = self.toolbox.handle(command=command, **kwargs)
+            return json.dumps(result.to_dict(), default=str)
+
+        async def _arun(command: str, **kwargs: Any) -> str:
+            # Synchronous fallback — async execute is not yet supported
+            return _run(command, **kwargs)
+
+        defn = self.toolbox.get_tool_definition()
+        params = defn["parameters"]
+
+        return StructuredTool.from_function(
+            func=_run,
+            coroutine=_arun,
+            name=defn["name"],
+            description=defn["description"],
+            args_schema=_build_pydantic_schema(params),
+        )
+
+
+def _build_pydantic_schema(json_schema: dict[str, Any]) -> Any:
+    """Convert a JSON Schema to a Pydantic model for LangChain."""
+    try:
+        from pydantic import BaseModel, Field, create_model
+    except ImportError:
+        raise ImportError("pydantic is required for the LangChain adapter")
+
+    properties = json_schema.get("properties", {})
+    required = set(json_schema.get("required", []))
+
+    fields: dict[str, Any] = {}
+    for name, prop in properties.items():
+        field_type = _json_type_to_python(prop)
+        is_required = name in required
+
+        if is_required:
+            fields[name] = (field_type, Field(description=prop.get("description", "")))
+        else:
+            fields[name] = (Optional[field_type], Field(default=None, description=prop.get("description", "")))
+
+    return create_model("ToolboxInput", **fields)
+
+
+def _json_type_to_python(prop: dict[str, Any]) -> type:
+    """Map JSON Schema types to Python types."""
+    type_map = {
+        "string": str,
+        "integer": int,
+        "number": float,
+        "boolean": bool,
+        "array": list,
+        "object": dict,
+    }
+    json_type = prop.get("type", "string")
+    return type_map.get(json_type, str)

toolbox_gateway-0.1.0/src/toolbox/adapters/openai.py

@@ -0,0 +1,63 @@
+"""OpenAI function calling adapter for Toolbox.
+
+Converts the toolbox into a single OpenAI function definition and
+provides a handler for tool call responses.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..core import Toolbox, ToolboxCommand
+
+
+class OpenAIAdapter:
+    """Adapt Toolbox for OpenAI's function calling API.
+
+    Usage::
+
+        adapter = OpenAIAdapter(toolbox)
+
+        # Get the function definition for your API call
+        functions = [adapter.get_function_schema()]
+
+        # When OpenAI returns a tool call, handle it:
+        result = adapter.handle_tool_call(tool_call)
+    """
+
+    def __init__(self, toolbox: Toolbox) -> None:
+        self.toolbox = toolbox
+
+    def get_function_schema(self) -> dict[str, Any]:
+        """Return the OpenAI function calling schema for toolbox."""
+        defn = self.toolbox.get_tool_definition()
+        return {
+            "type": "function",
+            "function": {
+                "name": defn["name"],
+                "description": defn["description"],
+                "parameters": defn["parameters"],
+            },
+        }
+
+    def handle_tool_call(self, tool_call: dict[str, Any]) -> dict[str, Any]:
+        """Handle an OpenAI tool call response.
+
+        Args:
+            tool_call: The tool call object from OpenAI's response,
+                       with 'function' containing 'arguments' as a JSON string.
+
+        Returns:
+            A dict suitable for sending back as a tool message.
+        """
+        arguments = json.loads(tool_call["function"]["arguments"])
+        command = arguments.get("command", "")
+        result = self.toolbox.handle(command=command, **arguments)
+
+        return {
+            "tool_call_id": tool_call.get("id", ""),
+            "role": "tool",
+            "name": "toolbox",
+            "content": json.dumps(result.to_dict()),
+        }

toolbox_gateway-0.1.0/src/toolbox/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Toolbox backends — persistent hint storage."""
+
+from .sqlite_store import SQLiteHintStore
+
+__all__ = ["SQLiteHintStore"]

toolbox_gateway-0.1.0/src/toolbox/backends/redis_store.py

@@ -0,0 +1,131 @@
+"""Redis hint store — production-grade persistent hints with TTL."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Optional
+
+from ..hints import Hint, HintStore
+
+
+class RedisHintStore:
+    """Redis-backed hint store for production use.
+
+    Hints are stored with a configurable TTL (default 30 days).
+    Uses SCAN for key discovery to avoid blocking Redis.
+
+    Requires the ``redis`` package: pip install redis
+
+    Usage::
+
+        import redis
+        client = redis.Redis(host="localhost", port=6379, db=0)
+        store = RedisHintStore(client)
+    """
+
+    KEY_PREFIX = "tool-hints"
+    DEFAULT_TTL_SECONDS = 30 * 24 * 60 * 60  # 30 days
+
+    def __init__(self, client: Any, ttl_seconds: int = DEFAULT_TTL_SECONDS) -> None:
+        self._redis = client
+        self._ttl = ttl_seconds
+
+    # ── Key helpers ────────────────────────────────────────────────
+
+    def _id_key(self, hint_id: str) -> str:
+        return f"{self.KEY_PREFIX}:id:{hint_id}"
+
+    def _index_key(self, category: str, key: str) -> str:
+        return f"{self.KEY_PREFIX}:index:{category}:{key}"
+
+    # ── Interface ──────────────────────────────────────────────────
+
+    def read(self, *, category: str | None = None, key: str | None = None) -> list[Hint]:
+        all_hints = self._get_all_hints()
+        if category:
+            all_hints = [h for h in all_hints if h.category == category]
+        if key:
+            all_hints = [h for h in all_hints if h.key == key]
+        return all_hints
+
+    def get_by_id(self, hint_id: str) -> Optional[Hint]:
+        data = self._redis.get(self._id_key(hint_id))
+        if data:
+            return Hint(**json.loads(data))
+        return None
+
+    def create(self, *, category: str, key: str, hint: str) -> Hint:
+        # Idempotent: check for existing hint with same category+key
+        existing_id = self._redis.get(self._index_key(category, key))
+        if existing_id:
+            existing_data = self._redis.get(self._id_key(existing_id.decode() if isinstance(existing_id, bytes) else existing_id))
+            if existing_data:
+                return Hint(**json.loads(existing_data))
+
+        from uuid import uuid4
+        now = datetime.now(timezone.utc).isoformat()
+        hint_obj = Hint(id=str(uuid4()), category=category, key=key, hint=hint, created_at=now, updated_at=now)
+
+        id_key = self._id_key(hint_obj.id)
+        idx_key = self._index_key(category, key)
+
+        self._redis.setex(id_key, self._ttl, json.dumps({
+            "id": hint_obj.id, "category": hint_obj.category,
+            "key": hint_obj.key, "hint": hint_obj.hint,
+            "created_at": hint_obj.created_at, "updated_at": hint_obj.updated_at,
+        }))
+        self._redis.setex(idx_key, self._ttl, hint_obj.id)
+
+        return hint_obj
+
+    def update(self, *, hint_id: str, hint: str) -> Optional[Hint]:
+        data = self._redis.get(self._id_key(hint_id))
+        if not data:
+            return None
+
+        existing = Hint(**json.loads(data))
+        updated = Hint(
+            id=existing.id, category=existing.category, key=existing.key,
+            hint=hint, created_at=existing.created_at,
+            updated_at=datetime.now(timezone.utc).isoformat(),
+        )
+
+        id_key = self._id_key(updated.id)
+        self._redis.setex(id_key, self._ttl, json.dumps({
+            "id": updated.id, "category": updated.category,
+            "key": updated.key, "hint": updated.hint,
+            "created_at": updated.created_at, "updated_at": updated.updated_at,
+        }))
+
+        return updated
+
+    def delete(self, *, hint_id: str) -> bool:
+        data = self._redis.get(self._id_key(hint_id))
+        if not data:
+            return False
+
+        existing = Hint(**json.loads(data))
+        self._redis.delete(self._id_key(hint_id))
+        self._redis.delete(self._index_key(existing.category, existing.key))
+        return True
+
+    # ── Internals ──────────────────────────────────────────────────
+
+    def _get_all_hints(self) -> list[Hint]:
+        """Use SCAN to discover all hint keys without blocking."""
+        hints: list[Hint] = []
+        pattern = f"{self.KEY_PREFIX}:id:*"
+        cursor = 0
+
+        while True:
+            cursor, keys = self._redis.scan(cursor, match=pattern, count=100)
+            for key in keys:
+                key_str = key.decode() if isinstance(key, bytes) else key
+                data = self._redis.get(key_str)
+                if data:
+                    hints.append(Hint(**json.loads(data)))
+            if cursor == 0:
+                break
+
+        return hints

toolbox_gateway-0.1.0/src/toolbox/backends/sqlite_store.py

@@ -0,0 +1,133 @@
+"""SQLite hint store — lightweight persistent hints with no external deps."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from ..hints import Hint, HintStore
+
+
+DEFAULT_DB_PATH = ".toolbox/hints.db"
+
+
+class SQLiteHintStore:
+    """SQLite-backed hint store for production use.
+
+    Zero external dependencies — uses Python's built-in sqlite3 module.
+    Persists hints across restarts with no infrastructure requirements.
+
+    Usage::
+
+        store = SQLiteHintStore()                          # .toolbox/hints.db
+        store = SQLiteHintStore(path="data/my_hints.db")   # custom path
+    """
+
+    def __init__(self, path: str = DEFAULT_DB_PATH) -> None:
+        self._path = path
+        self._ensure_db()
+
+    def _ensure_db(self) -> None:
+        """Create the database and table if they don't exist."""
+        Path(self._path).parent.mkdir(parents=True, exist_ok=True)
+        with self._connect() as conn:
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS hints (
+                    id TEXT PRIMARY KEY,
+                    category TEXT NOT NULL,
+                    key TEXT NOT NULL,
+                    hint TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                )
+            """)
+            conn.execute("""
+                CREATE UNIQUE INDEX IF NOT EXISTS idx_hints_category_key
+                ON hints (category, key)
+            """)
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._path)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    @staticmethod
+    def _row_to_hint(row: sqlite3.Row) -> Hint:
+        return Hint(
+            id=row["id"],
+            category=row["category"],
+            key=row["key"],
+            hint=row["hint"],
+            created_at=row["created_at"],
+            updated_at=row["updated_at"],
+        )
+
+    # ── Interface ──────────────────────────────────────────────────
+
+    def read(self, *, category: str | None = None, key: str | None = None) -> list[Hint]:
+        with self._connect() as conn:
+            query = "SELECT * FROM hints"
+            conditions: list[str] = []
+            params: list[str] = []
+
+            if category:
+                conditions.append("category = ?")
+                params.append(category)
+            if key:
+                conditions.append("key = ?")
+                params.append(key)
+
+            if conditions:
+                query += " WHERE " + " AND ".join(conditions)
+
+            rows = conn.execute(query, params).fetchall()
+            return [self._row_to_hint(row) for row in rows]
+
+    def get_by_id(self, hint_id: str) -> Optional[Hint]:
+        with self._connect() as conn:
+            row = conn.execute("SELECT * FROM hints WHERE id = ?", (hint_id,)).fetchone()
+            return self._row_to_hint(row) if row else None
+
+    def create(self, *, category: str, key: str, hint: str) -> Hint:
+        from uuid import uuid4
+
+        with self._connect() as conn:
+            # Check for existing (idempotent)
+            existing = conn.execute(
+                "SELECT * FROM hints WHERE category = ? AND key = ?",
+                (category, key),
+            ).fetchone()
+
+            if existing:
+                return self._row_to_hint(existing)
+
+            now = datetime.now(timezone.utc).isoformat()
+            hint_obj = Hint(id=str(uuid4()), category=category, key=key, hint=hint, created_at=now, updated_at=now)
+
+            conn.execute(
+                "INSERT INTO hints (id, category, key, hint, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)",
+                (hint_obj.id, hint_obj.category, hint_obj.key, hint_obj.hint, hint_obj.created_at, hint_obj.updated_at),
+            )
+
+            return hint_obj
+
+    def update(self, *, hint_id: str, hint: str) -> Optional[Hint]:
+        now = datetime.now(timezone.utc).isoformat()
+        with self._connect() as conn:
+            cursor = conn.execute(
+                "UPDATE hints SET hint = ?, updated_at = ? WHERE id = ?",
+                (hint, now, hint_id),
+            )
+            if cursor.rowcount == 0:
+                return None
+
+            row = conn.execute("SELECT * FROM hints WHERE id = ?", (hint_id,)).fetchone()
+            return self._row_to_hint(row) if row else None
+
+    def delete(self, *, hint_id: str) -> bool:
+        with self._connect() as conn:
+            cursor = conn.execute("DELETE FROM hints WHERE id = ?", (hint_id,))
+            return cursor.rowcount > 0