adaptive-memory-multi-model-router 2.16.0 → 2.16.2

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,25 @@
+"""
+A3M Router MCP Server
+
+MCP (Model Context Protocol) server for A3M Router.
+Provides intelligent LLM routing and ensemble execution as MCP tools.
+"""
+
+__version__ = "1.0.0"
+
+# Try to import MCP components
+HAS_MCP = False
+SERVER_NAME = "a3m-router"
+
+try:
+    from mcp.server.lowlevel import Server
+    from mcp import Tool
+    HAS_MCP = True
+except ImportError:
+    pass
+
+# Import main if available
+try:
+    from .server import main
+except ImportError:
+    main = None

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,205 @@
+"""
+A3M Router MCP Server - MCP Protocol Server for A3M Router
+
+MCP 2.0.0 compatible server that provides A3M Router functionality
+as MCP tools for AI agents.
+"""
+
+import os
+import asyncio
+import json
+from typing import Optional, List, Any
+
+try:
+    from mcp.server.lowlevel import Server
+    from mcp import Tool, ListToolsResult
+    from mcp.types import CallToolResult, TextContent
+    from mcp.server.stdio import stdio_server
+    HAS_MCP = True
+except ImportError:
+    HAS_MCP = False
+    print("WARNING: mcp package not installed. Run: pip install mcp", flush=True)
+
+# A3M Router client
+try:
+    import a3m
+    A3MRouter = a3m.A3MRouter
+except ImportError:
+    A3MRouter = None
+
+
+SERVER_NAME = "a3m-router"
+SERVER_VERSION = "1.0.0"
+
+_router: Optional["A3MRouter"] = None
+
+
+def get_router() -> "A3MRouter":
+    """Get or create A3MRouter instance."""
+    global _router
+    if _router is None:
+        base_url = os.environ.get("A3M_BASE_URL", "http://localhost:8787")
+        api_key = os.environ.get("A3M_API_KEY", "")
+        _router = A3MRouter(base_url=base_url, api_key=api_key)
+    return _router
+
+
+# Tool definitions
+TOOLS = [
+    Tool(
+        name="a3m_route",
+        title="Route Query",
+        description="Route a query to the optimal LLM provider using A3M's adaptive routing. Returns model selection, tier, estimated cost, and reasoning.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "The user query to route (e.g. 'Write Python code to sort a list')",
+                },
+                "provider": {
+                    "type": "string",
+                    "description": "Optional: Force a specific provider (e.g. 'groq', 'google')",
+                },
+            },
+            "required": ["query"],
+        },
+    ),
+    Tool(
+        name="a3m_chat",
+        title="Chat with A3M",
+        description="Send a chat message through A3M Router's adaptive routing.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "The user query",
+                },
+            },
+            "required": ["query"],
+        },
+    ),
+    Tool(
+        name="a3m_cost_report",
+        title="Cost Report",
+        description="Get cost analytics across all providers.",
+        inputSchema={
+            "type": "object",
+            "properties": {},
+        },
+    ),
+    Tool(
+        name="a3m_models",
+        title="List Models",
+        description="List all available models with cost/latency info.",
+        inputSchema={
+            "type": "object",
+            "properties": {},
+        },
+    ),
+]
+
+
+class A3MServer:
+    """A3M Router MCP Server with tool handlers."""
+
+    def __init__(self):
+        pass
+
+    async def handle_list_tools(self, request_context=None) -> ListToolsResult:
+        """Handle tools/list request."""
+        return ListToolsResult(
+            tools=[
+                {
+                    "name": t.name,
+                    "description": t.description,
+                    "inputSchema": t.inputSchema,
+                }
+                for t in TOOLS
+            ]
+        )
+
+    async def handle_call_tool(self, request_context, name: str, arguments: dict) -> CallToolResult:
+        """Handle tools/call request."""
+        try:
+            if name == "a3m_route":
+                router = get_router()
+                query = arguments.get("query")
+                provider = arguments.get("provider")
+
+                result = router.route(query, provider=provider)
+                return CallToolResult(
+                    content=[TextContent(type="text", text=json.dumps(result, indent=2))]
+                )
+
+            elif name == "a3m_chat":
+                router = get_router()
+                query = arguments.get("query")
+
+                result = router.chat(query)
+                return CallToolResult(
+                    content=[TextContent(type="text", text=str(result))]
+                )
+
+            elif name == "a3m_cost_report":
+                router = get_router()
+                report = router.cost_report()
+                return CallToolResult(
+                    content=[TextContent(type="text", text=json.dumps(report, indent=2))]
+                )
+
+            elif name == "a3m_models":
+                router = get_router()
+                models = router.models()
+                return CallToolResult(
+                    content=[TextContent(type="text", text=json.dumps(models, indent=2))]
+                )
+
+            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,
+            )
+
+
+if HAS_MCP:
+    # Create server with handlers
+    a3m_server = A3MServer()
+
+    server = Server(
+        SERVER_NAME,
+        version=SERVER_VERSION,
+        on_list_tools=a3m_server.handle_list_tools,
+        on_call_tool=a3m_server.handle_call_tool,
+    )
+
+
+async def main():
+    """Main entry point for MCP server."""
+    if not HAS_MCP:
+        print("ERROR: mcp package not installed", flush=True)
+        return
+
+    print(f"Starting {SERVER_NAME} MCP Server v{SERVER_VERSION}", flush=True)
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options(),
+        )
+
+
+if __name__ == "__main__":
+    if HAS_MCP:
+        asyncio.run(main())
+    else:
+        print("ERROR: mcp package required", flush=True)
+        print("Run: pip install mcp", flush=True)

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,77 @@
 [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.16.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"
+Homepage = "https://github.com/Das-rebel/a3m-router#a3m-router"
+Documentation = "https://github.com/Das-rebel/a3m-router#readme"
+Repository = "https://github.com/Das-rebel/a3m-router"
+Changelog = "https://github.com/Das-rebel/a3m-router/releases"
+"NPM Package" = "https://www.npmjs.com/package/adaptive-memory-multi-model-router"
+"PyPI Package" = "https://pypi.org/project/a3m-router/"
+"GitHub Stars" = "https://github.com/Das-rebel/a3m-router/stargazers"
+
+[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()

package/scripts/submit-sitemap.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+#
+# A3M Router — Sitemap Submission Script
+# Submits sitemap to Google, Bing, and IndexNow for faster indexing
+#
+set -e
+
+SITEMAP_URL="${SITEMAP_URL:-https://a3m-router.com/sitemap.xml}"
+INDEXNOW_KEY="${INDEXNOW_KEY:-}"
+
+echo "=== A3M Router Sitemap Submission ==="
+echo "Sitemap: $SITEMAP_URL"
+echo ""
+
+# ─── Google ───────────────────────────────────────────
+echo "[1/3] Submitting to Google..."
+GOOGLE_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+  "https://www.google.com/ping?sitemap=$SITEMAP_URL")
+if [ "$GOOGLE_STATUS" = "200" ]; then
+  echo "  ✅ Google: OK (HTTP $GOOGLE_STATUS)"
+else
+  echo "  ⚠️  Google: HTTP $GOOGLE_STATUS"
+fi
+
+# ─── Bing ─────────────────────────────────────────────
+echo "[2/3] Submitting to Bing..."
+BING_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+  "https://www.bing.com/ping?sitemap=$SITEMAP_URL")
+if [ "$BING_STATUS" = "200" ]; then
+  echo "  ✅ Bing: OK (HTTP $BING_STATUS)"
+else
+  echo "  ⚠️  Bing: HTTP $BING_STATUS"
+fi
+
+# ─── IndexNow ─────────────────────────────────────────
+echo "[3/3] Submitting to IndexNow..."
+if [ -z "$INDEXNOW_KEY" ]; then
+  echo "  ⚠️  Skipped: INDEXNOW_KEY env var not set"
+  echo "  To enable IndexNow: export INDEXNOW_KEY=your_key_from_indexnow.org"
+else
+  # Get the sitemap URLs and submit each to IndexNow
+  curl -s "$SITEMAP_URL" | grep -oP '(?<=<loc>)[^<]+' | while read -r url; do
+    RESPONSE=$(curl -s -w "%{http_code}" -o /dev/null -X POST \
+      "https://indexnow.org/ping" \
+      -H "Content-Type: text/plain" \
+      -d "url=$url&key=$INDEXNOW_KEY")
+    echo "  IndexNow: $url → HTTP $RESPONSE"
+  done
+fi
+
+echo ""
+echo "=== Done ==="

package/src/__types__/registry.d.ts

@@ -0,0 +1,14 @@
+declare module '@my-org/a3m-router/src/providers/registry' {
+  const PROVIDERS: Map<string, any>;
+  const registry: Map<string, any>;
+  export function registerProvider(name: string, config: any): void;
+  export function getProvider(name: string): any;
+  export function listProviders(): Array<[string, any]>;
+  export interface ProviderRegistry {
+    registerProvider: (name: string, config: any) => void;
+    getProvider: (name: string) => any;
+    listProviders: () => Array<[string, any]>;
+  }
+  const registryInstance: ProviderRegistry;
+  export default registryInstance;
+}