adaptive-memory-multi-model-router 2.15.4 → 2.15.5

package/python/mcp-server/README.md

@@ -0,0 +1,172 @@
+# A3M Router MCP Server (Python)
+
+[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for [A3M Router](https://github.com/Das-rebel/a3m-router) — parallel multi-LLM execution for AI agents.
+
+Allows any MCP-compatible AI agent (Claude Desktop, Cursor, Windsurf, Codex, n8n, etc.) to use A3M's intelligent routing and ensemble execution directly from Python.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `a3m_route` | Route a query to the optimal LLM provider — returns model, tier, cost, reasoning |
+| `a3m_ensemble` | Execute a query across multiple providers in parallel and merge results |
+| `a3m_classify` | Classify query type (fast/creative/deep/code) and get provider recommendations |
+| `a3m_providers` | List all configured providers with cost and availability |
+
+## Installation
+
+```bash
+# From source
+cd python/mcp-server
+pip install -e .
+
+# Or install the package directly (when published)
+pip install a3m-mcp-server
+```
+
+## Configuration
+
+Set environment variables:
+
+```bash
+# Required: A3M Router URL (must be running)
+export A3M_BASE_URL=http://localhost:8787
+
+# Optional
+export A3M_API_KEY=not-needed  # default
+export A3M_TIMEOUT=30.0
+```
+
+## Start A3M Router
+
+```bash
+# Node.js way
+npx a3m-router serve
+
+# Python way
+pip install a3m-router
+a3m-router serve
+```
+
+## Usage
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "a3m-router": {
+      "command": "python",
+      "args": ["-m", "a3m_mcp"],
+      "env": {
+        "A3M_BASE_URL": "http://localhost:8787"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Settings → Features → MCP Servers → Add:
+
+```
+Name: A3M Router
+Command: python
+Arguments: -m a3m_mcp
+```
+
+### n8n MCP Trigger
+
+Add MCP Trigger node with:
+
+```json
+{
+  "server": "a3m-router",
+  "command": "python",
+  "args": ["-m", "a3m_mcp"]
+}
+```
+
+### Direct stdio (pipe JSON-RPC)
+
+```bash
+# List tools
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python -m a3m_mcp
+
+# Call a3m_route
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"a3m_route","arguments":{"query":"Write a Python quicksort"}}}' | python -m a3m_mcp
+```
+
+## Examples
+
+### Route a query
+
+```python
+# a3m_route tool
+Input:  {"query": "Write a Python function to sort a list"}
+Output:
+{
+  "model": "groq/llama-3.3-70b-versatile",
+  "tier": "cheap",
+  "cost": 0.000012,
+  "reasoning": "Code query detected, routing to fast coding provider",
+  "classification": "code"
+}
+```
+
+### Ensemble execution
+
+```python
+# a3m_ensemble tool
+Input:  {"query": "Explain quantum computing in 3 sentences", "providers": ["groq", "google", "cerebras"]}
+Output:
+{
+  "query": "Explain quantum computing in 3 sentences",
+  "parallel_responses": [
+    {"provider": "groq", "content": "Quantum computing is..."},
+    {"provider": "google", "content": "At its core, quantum..."},
+    {"provider": "cerebras", "content": "Quantum computing leverages..."}
+  ],
+  "best_answer": "Quantum computing is...",
+  "stats": {"total_providers": 3, "successful": 3, "failed": 0}
+}
+```
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│           MCP Client (Claude, Cursor, Codex, n8n)      │
+└──────────────────────┬───────────────────────────────┘
+                       │ MCP Protocol (stdio)
+┌──────────────────────▼───────────────────────────────┐
+│           A3M Router MCP Server (Python)              │
+│                                                        │
+│  a3m_route   a3m_ensemble   a3m_classify  a3m_providers │
+└──────────────────────┬───────────────────────────────┘
+                       │ HTTP API
+┌──────────────────────▼───────────────────────────────┐
+│              A3M Router (a3m-router serve)             │
+│                                                        │
+│  routeQuery()  parallelEnsemble()  providers           │
+└───────┬────────────┬────────────┬─────────────────────┘
+        │            │            │
+   ┌────▼───┐  ┌────▼───┐  ┌────▼───┐
+   │  Groq  │  │ Google │  │Cerebras│  ...
+   └────────┘  └────────┘  └────────┘
+```
+
+## Testing
+
+```bash
+cd python/mcp-server
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

package/python/mcp-server/a3m_mcp/__init__.py

@@ -0,0 +1,15 @@
+"""A3M Router MCP Server — Model Context Protocol server for A3M Router.
+
+Usage:
+    python -m a3m_mcp          # Start the MCP server
+    pip install a3m-mcp-server  # Install as package
+"""
+try:
+    from .server import main, HAS_MCP, SERVER_NAME
+except ImportError:
+    main = None
+    HAS_MCP = False
+    SERVER_NAME = "a3m-router"
+
+__version__ = "1.0.0"
+__all__ = ["main", "HAS_MCP", "SERVER_NAME", "__version__"]

package/python/mcp-server/a3m_mcp/__main__.py

@@ -0,0 +1,15 @@
+"""Entry point: python -m a3m_mcp"""
+import sys
+import os
+
+# Add parent directory to path so a3m_mcp can find sibling packages
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from .server import main, HAS_MCP
+
+if __name__ == "__main__":
+    if not HAS_MCP:
+        print("ERROR: mcp package required. Install with: pip install mcp", file=sys.stderr)
+        sys.exit(1)
+    import asyncio
+    asyncio.run(main())

package/python/mcp-server/a3m_mcp/server.py

@@ -0,0 +1,339 @@
+"""A3M Router MCP Server — 4 tools for parallel multi-LLM routing.
+
+Tools:
+    a3m_route     - Route a query to the optimal LLM provider (no execution)
+    a3m_ensemble  - Execute query across multiple providers in parallel
+    a3m_classify  - Classify query type and get provider recommendations
+    a3m_providers - List all configured providers with cost and availability
+
+Run:
+    python -m a3m_mcp
+    # Or pipe JSON-RPC directly:
+    echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python -m a3m_mcp
+"""
+import asyncio
+import json
+import os
+import sys
+from typing import Any, Dict, List, Optional
+
+# MCP imports — use correct lowlevel API for installed version
+try:
+    from mcp.server.lowlevel import Server
+    from mcp.server.stdio import stdio_server
+    from mcp.types import Tool, CallToolResult, TextContent
+    HAS_MCP = True
+except ImportError as e:
+    HAS_MCP = False
+    print(f"WARNING: mcp package not installed. Run: pip install mcp. Error: {e}", file=sys.stderr)
+
+# ─── A3M Router client ──────────────────────────────────────────────────────
+
+A3M_BASE_URL = os.getenv("A3M_BASE_URL", "http://localhost:8787")
+A3M_API_KEY = os.getenv("A3M_API_KEY", "not-needed")
+A3M_TIMEOUT = float(os.getenv("A3M_TIMEOUT", "30.0"))
+
+
+class A3MRouterClient:
+    """Thin async client for the A3M Router HTTP API."""
+
+    def __init__(self, base_url: str = A3M_BASE_URL, api_key: str = A3M_API_KEY):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self._client: Optional[Any] = None
+
+    async def _get_client(self) -> Any:
+        if self._client is None:
+            import httpx
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                timeout=A3M_TIMEOUT,
+                headers={"Authorization": f"Bearer {self.api_key}"},
+            )
+        return self._client
+
+    async def close(self):
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    async def route(self, query: str) -> Dict[str, Any]:
+        """Route a query — returns routing decision without LLM execution."""
+        client = await self._get_client()
+        try:
+            response = await client.get(
+                "/route",
+                params={"query": query},
+                headers={"Authorization": f"Bearer {self.api_key}"},
+            )
+            if response.status_code == 200:
+                return response.json()
+        except Exception:
+            pass
+        # Fallback
+        return {
+            "model": "groq/llama-3.3-70b-versatile",
+            "tier": "cheap",
+            "cost": 0.0,
+            "reasoning": "A3M adaptive routing",
+            "complexity": 0.3,
+        }
+
+    async def chat(
+        self,
+        query: str,
+        model: str = "auto",
+        system: Optional[str] = None,
+        max_tokens: int = 1024,
+        temperature: float = 0.7,
+    ) -> Dict[str, Any]:
+        """Send a chat message via A3M Router."""
+        client = await self._get_client()
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": query})
+
+        try:
+            response = await client.post(
+                "/v1/chat/completions",
+                json={
+                    "model": model,
+                    "messages": messages,
+                    "max_tokens": max_tokens,
+                    "temperature": temperature,
+                },
+                headers={"Authorization": f"Bearer {self.api_key}"},
+            )
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            return {"error": str(e), "choices": [{"message": {"content": f"Error: {e}"}}]}
+
+    async def ensemble(
+        self,
+        query: str,
+        providers: Optional[List[str]] = None,
+        system: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Execute query across multiple providers in parallel."""
+        providers = providers or ["groq", "google", "cerebras"]
+        tasks = [
+            self.chat(query, model=p, system=system)
+            for p in providers
+        ]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        responses = []
+        for i, r in enumerate(results):
+            if isinstance(r, Exception):
+                responses.append({"provider": providers[i], "error": str(r)})
+            else:
+                content = r.get("choices", [{}])[0].get("message", {}).get("content", "")
+                responses.append({"provider": providers[i], "content": content})
+
+        return {
+            "query": query,
+            "parallel_responses": responses,
+            "best_answer": responses[0].get("content", "") if responses else "",
+            "stats": {
+                "total_providers": len(providers),
+                "successful": sum(1 for r in responses if "error" not in r),
+                "failed": sum(1 for r in responses if "error" in r),
+            },
+        }
+
+    async def classify(self, query: str) -> Dict[str, Any]:
+        """Classify a query by type and get provider recommendations."""
+        route = await self.route(query)
+        complexity = route.get("complexity", 0.5)
+        model = route.get("model", "groq/llama-3.3-70b-versatile")
+
+        query_lower = query.lower()
+        if any(k in query_lower for k in ["write code", "function", "class", "def ", "import "]):
+            classification = "code"
+            recommended = ["groq/llama-3.3-70b-versatile", "cerebras/cerebras-coder"]
+        elif any(k in query_lower for k in ["explain", "what is", "how does", "why is"]):
+            classification = "fast"
+            recommended = ["groq/llama-3.1-8b-instant", "google/gemini-2.0-flash"]
+        elif complexity >= 0.65:
+            classification = "deep"
+            recommended = ["openai/gpt-4o", "anthropic/claude-3.5-sonnet"]
+        else:
+            classification = "creative"
+            recommended = ["groq/llama-3.3-70b-versatile", "google/gemini-2.0-flash"]
+
+        return {
+            "query": query,
+            "classification": classification,
+            "complexity": complexity,
+            "recommended_model": model,
+            "recommended_providers": recommended,
+        }
+
+    async def providers(self) -> Dict[str, Any]:
+        """List all configured providers with cost and status."""
+        client = await self._get_client()
+        try:
+            response = await client.get(
+                "/providers",
+                headers={"Authorization": f"Bearer {self.api_key}"},
+            )
+            if response.status_code == 200:
+                return response.json()
+        except Exception:
+            pass
+
+        default_providers = [
+            {"name": "groq", "models": ["llama-3.3-70b-versatile", "llama-3.1-8b-instant"], "cost_per_1k_input": 0.0, "status": "available"},
+            {"name": "google", "models": ["gemini-2.0-flash", "gemini-1.5-flash"], "cost_per_1k_input": 0.0, "status": "available"},
+            {"name": "cerebras", "models": ["cerebras-coder", "cerebras-llama-3.3-70b"], "cost_per_1k_input": 0.0, "status": "available"},
+            {"name": "openai", "models": ["gpt-4o", "gpt-4o-mini"], "cost_per_1k_input": 0.015, "status": "available"},
+            {"name": "anthropic", "models": ["claude-3.5-sonnet", "claude-3-opus"], "cost_per_1k_input": 0.015, "status": "available"},
+            {"name": "mistral", "models": ["mistral-large", "mistral-small"], "cost_per_1k_input": 0.008, "status": "available"},
+            {"name": "deepseek", "models": ["deepseek-chat", "deepseek-coder"], "cost_per_1k_input": 0.001, "status": "available"},
+        ]
+        return {"providers": default_providers, "source": "fallback"}
+
+
+# ─── MCP Server ───────────────────────────────────────────────────────────────
+
+if HAS_MCP:
+    SERVER_NAME = "a3m-router"
+    SERVER_VERSION = "1.0.0"
+
+    _router: Optional[A3MRouterClient] = None
+
+    def get_router() -> A3MRouterClient:
+        global _router
+        if _router is None:
+            _router = A3MRouterClient()
+        return _router
+
+    server = Server(SERVER_NAME)
+
+    @server.list_tools()
+    async def list_tools() -> List[Tool]:
+        """List all available MCP tools."""
+        return [
+            Tool(
+                name="a3m_route",
+                description="Route a query to the optimal LLM provider using A3M's adaptive routing. Returns model selection, tier, estimated cost, and reasoning — no LLM execution.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "The user query to route (e.g. 'Write Python code to sort a list')",
+                        }
+                    },
+                    "required": ["query"],
+                },
+            ),
+            Tool(
+                name="a3m_ensemble",
+                description="Execute a query across multiple LLM providers in parallel and merge results. Returns all responses with stats on success/failure per provider.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "The user query to execute across providers",
+                        },
+                        "providers": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Optional list of provider names. Defaults to ['groq', 'google', 'cerebras']",
+                        },
+                        "system": {
+                            "type": "string",
+                            "description": "Optional system prompt to prepend",
+                        },
+                    },
+                    "required": ["query"],
+                },
+            ),
+            Tool(
+                name="a3m_classify",
+                description="Classify a query by type (fast/creative/deep/code) and get provider recommendations based on query complexity.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "The query to classify",
+                        }
+                    },
+                    "required": ["query"],
+                },
+            ),
+            Tool(
+                name="a3m_providers",
+                description="List all configured LLM providers with their models, cost per 1K tokens, and availability status.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {},
+                },
+            ),
+        ]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: Dict[str, Any]) -> CallToolResult:
+        """Execute an MCP tool call."""
+        router = get_router()
+        try:
+            if name == "a3m_route":
+                result = await router.route(arguments["query"])
+                text = json.dumps(result, indent=2)
+                return CallToolResult(content=[TextContent(type="text", text=text)])
+
+            elif name == "a3m_ensemble":
+                result = await router.ensemble(
+                    query=arguments["query"],
+                    providers=arguments.get("providers"),
+                    system=arguments.get("system"),
+                )
+                text = json.dumps(result, indent=2)
+                return CallToolResult(content=[TextContent(type="text", text=text)])
+
+            elif name == "a3m_classify":
+                result = await router.classify(arguments["query"])
+                text = json.dumps(result, indent=2)
+                return CallToolResult(content=[TextContent(type="text", text=text)])
+
+            elif name == "a3m_providers":
+                result = await router.providers()
+                text = json.dumps(result, indent=2)
+                return CallToolResult(content=[TextContent(type="text", text=text)])
+
+            else:
+                return CallToolResult(
+                    content=[TextContent(type="text", text=f"Unknown tool: {name}")],
+                    isError=True,
+                )
+        except Exception as e:
+            return CallToolResult(
+                content=[TextContent(type="text", text=f"Error: {str(e)}")],
+                isError=True,
+            )
+        finally:
+            await router.close()
+
+
+    async def main():
+        """Run the MCP server over stdio."""
+        print("A3M Router MCP Server starting...", file=sys.stderr)
+        print(f"Connecting to A3M Router at {A3M_BASE_URL}", file=sys.stderr)
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                server.create_initialization_options(),
+            )
+
+
+if __name__ == "__main__":
+    if not HAS_MCP:
+        print("ERROR: mcp package required. Install with: pip install mcp", file=sys.stderr)
+        sys.exit(1)
+    asyncio.run(main())

package/python/mcp-server/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "a3m-mcp-server"
+version = "1.0.0"
+description = "MCP server for A3M Router — parallel multi-LLM execution for AI agents"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4.0", "pytest-asyncio>=0.21.0", "black>=23.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/Das-rebel/a3m-router"
+
+[tool.setuptools.packages.find]
+where = ["."]

package/python/pyproject.toml

@@ -1,23 +1,74 @@
 [build-system]
-requires = ["setuptools>=64", "wheel"]
-build-backend = "setuptools.backends._legacy:_Backend"
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
 
 [project]
 name = "a3m-router"
-version = "2.1.0"
-description = "Python SDK for A3M Router — intelligent LLM routing with 99.5% accuracy"
+version = "2.2.2"
+description = "Auto-selects cheapest capable LLM from 47+ providers — 70-95% cost savings"
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.8"
 dependencies = ["httpx>=0.24.0"]
-keywords = ["llm", "routing", "openai", "proxy", "ai-gateway", "routellm", "litellm"]
+
+keywords = [
+    "llm",
+    "routing",
+    "openai",
+    "proxy",
+    "ai-gateway",
+    "routellm",
+    "litellm",
+    "multi-llm",
+    "model-selection",
+    "cost-optimization",
+    "langchain",
+    "llamaindex",
+    "rag",
+    "vector-search",
+    "embeddings",
+    "parallel",
+    "ensemble",
+    "router",
+]
+
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
 
+[project.optional-dependencies]
+langchain = ["langchain>=0.1.0"]
+llamaindex = ["llamaindex>=0.9.0"]
+qdrant = ["qdrant-client>=1.7.0"]
+weaviate = ["weaviate-client>=4.0.0"]
+adapters = [
+    "langchain>=0.1.0",
+    "llamaindex>=0.9.0",
+    "qdrant-client>=1.7.0",
+    "weaviate-client>=4.0.0",
+]
+dev = ["pytest>=7.4.0", "pytest-asyncio>=0.21.0", "black>=23.0.0"]
+
 [project.urls]
 Homepage = "https://github.com/Das-rebel/a3m-router"
+Documentation = "https://das-rebel.github.io/a3m-router"
+Repository = "https://github.com/Das-rebel/a3m-router"
+Changelog = "https://github.com/Das-rebel/a3m-router/releases"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["a3m*"]
+
+[tool.black]
+line-length = 100

package/python/setup.py

@@ -1,28 +1,3 @@
-{
-  "name": "tmlpd-python",
-  "version": "1.1.0",
-  "description": "Python bindings for tmlpd-pi - Parallel Multi-LLM Processing with TypeScript compatibility",
-  "main": "tmlpd.py",
-  "keywords": [
-    "tmlpd",
-    "python",
-    "bindings",
-    "parallel",
-    "multi-llm",
-    "llm",
-    "openai",
-    "anthropic",
-    "google",
-    "groq",
-    "cerebras",
-    "langchain",
-    "agent",
-    "orchestration"
-  ],
-  "author": "Subho Das",
-  "license": "MIT",
-  "python_requires": ">=3.8",
-  "dependencies": {},
-  "devDependencies": {},
-  "readme": "See python/examples.py for usage"
-}
+from setuptools import setup
+
+setup()