adaptive-memory-multi-model-router 2.1.0 → 2.2.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "adaptive-memory-multi-model-router",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "shortName": "A3M Router",
   "displayName": "A3M Router - Adaptive Memory Multi-Model Router",
-  "description": "99.5% ±1 tier routing accuracy, zero ML. Exceeds RouteLLM BERT. Drop-in OpenAI proxy, 40 providers, domain-aware. 245% growth in 3 days.",
+  "description": "LLM router & AI gateway with OpenAI-compatible proxy. 99.5% routing accuracy, 40 providers (Groq, Cerebras, Ollama, DeepSeek, Mistral). Semantic cache, guardrails, cost optimization. Drop-in for LangChain, Vercel AI SDK.",
   "main": "dist/index.js",
   "bin": {
     "a3m-router": "dist/cli.js",
@@ -46,38 +46,78 @@
       "import": "./dist/analytics/costAnalytics.js",
       "require": "./dist/analytics/costAnalytics.js",
       "types": "./dist/analytics/costAnalytics.d.ts"
+    },
+    "./sdk": {
+      "import": "./dist/sdk.js",
+      "require": "./dist/sdk.js"
     }
   },
   "keywords": [
-    "llm-router",
-    "llm-routing",
-    "llm-gateway",
-    "openai-proxy",
-    "cost-optimization",
+    "ai",
+    "ai-agent",
+    "ai-cost-optimization",
     "ai-gateway",
-    "routellm-alternative",
-    "litellm-alternative",
-    "portkey-alternative",
-    "semantic-cache",
-    "guardrails",
-    "multi-provider",
-    "openai-compatible",
-    "llm-proxy",
-    "llm-orchestration",
-    "groq",
-    "cerebras",
-    "mistral",
-    "deepseek",
+    "ai-guardrails",
+    "ai-load-balancer",
+    "ai-proxy",
+    "ai-router",
+    "ai-sdk",
     "anthropic",
+    "anthropic-proxy",
     "benchmark",
-    "routing-accuracy",
-    "lightweight",
-    "no-gpu",
+    "cerebras",
+    "cerebras-proxy",
+    "chatbot",
+    "chatgpt",
+    "claude",
+    "claude-proxy",
+    "cost-optimization",
+    "deepseek",
+    "deepseek-proxy",
+    "domain-routing",
+    "gpt",
+    "groq",
+    "groq-proxy",
+    "guardrails",
+    "helicone",
     "keyword-routing",
-    "ai",
+    "langchain",
+    "language-model",
+    "lightweight",
+    "litellm-alternative",
     "llm",
+    "llm-gateway",
+    "llm-load-balancer",
+    "llm-manager",
+    "llm-orchestration",
+    "llm-proxy",
+    "llm-router",
+    "llm-routing",
+    "mistral",
+    "mistral-proxy",
+    "model-router",
+    "model-routing",
+    "multi-llm",
+    "multi-provider",
     "nlp",
-    "language-model"
+    "no-gpu",
+    "ollama",
+    "ollama-proxy",
+    "openai",
+    "openai-api",
+    "openai-compatible",
+    "openai-proxy",
+    "openai-sdk",
+    "openrouter",
+    "portkey-alternative",
+    "provider-fallback",
+    "query-routing",
+    "routellm-alternative",
+    "routing-accuracy",
+    "semantic-cache",
+    "smart-routing",
+    "token-counter",
+    "vercel-ai"
   ],
   "author": "Das-rebel <subho@example.com>",
   "license": "MIT",

package/python/README.md

@@ -0,0 +1,102 @@
+# A3M Router Python SDK
+
+Python SDK for the A3M Router — an intelligent LLM routing proxy that selects the best model for each query based on complexity, cost, and capability.
+
+## Install
+
+```bash
+pip install a3m-router
+```
+
+Requires Python 3.8+. Only dependency: `httpx`.
+
+## Quick Start
+
+### Async Client (recommended)
+
+```python
+import asyncio
+from a3m import A3MRouter
+
+async def main():
+    async with A3MRouter() as router:
+        # Chat with automatic model routing
+        response = await router.chat("What is 2+2?")
+        print(response["choices"][0]["message"]["content"])
+
+        # Check routing decision without executing
+        decision = await router.route("Write a Python web scraper")
+        print(decision)  # RoutingDecision(model=groq/llama-3.3-70b, tier=cheap, cost=$0.000000, complexity=0.35)
+
+        # Stream a response
+        async for token in router.stream_chat("Tell me a joke"):
+            print(token, end="", flush=True)
+
+        # List available models
+        models = await router.models()
+
+        # Get cost analytics
+        report = await router.cost_report()
+        print(f"Total requests: {report.total_requests}")
+        print(f"Savings: {report.savings_percentage:.1f}%")
+
+asyncio.run(main())
+```
+
+### Sync Client
+
+```python
+from a3m.sync_client import A3MRouterSync
+
+with A3MRouterSync() as router:
+    response = router.chat("What is 2+2?")
+    print(response["choices"][0]["message"]["content"])
+
+    decision = router.route("Explain quantum computing")
+    print(f"Routed to {decision.model} (tier={decision.tier}, cost=${decision.cost:.6f})")
+```
+
+### With OpenAI SDK
+
+The router is OpenAI-compatible, so you can use the standard OpenAI SDK:
+
+```python
+from openai import AsyncOpenAI
+
+client = AsyncOpenAI(base_url="http://localhost:8787/v1", api_key="not-needed")
+response = await client.chat.completions.create(
+    model="auto",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+```
+
+## API Reference
+
+### A3MRouter (async)
+
+| Method | Description |
+|--------|-------------|
+| `chat(message, model="auto", max_tokens=100, temperature=0.7, system=None)` | Send a chat message with automatic routing |
+| `route(query)` | Get routing decision without executing |
+| `route_batch(queries)` | Route multiple queries |
+| `stream_chat(message, model="auto", max_tokens=100)` | Stream response tokens |
+| `models()` | List available models |
+| `health()` | Check router health |
+| `cost_report()` | Get cost analytics |
+
+### RoutingDecision
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `model` | str | Selected model name |
+| `tier` | str | Cost tier (free/cheap/mid/premium) |
+| `cost` | float | Estimated cost per request |
+| `complexity` | float | Query complexity score (0-1) |
+| `reasoning` | str | Why this model was chosen |
+| `fallback_models` | list | Alternative models if primary fails |
+| `is_free` | bool | Property — True if cost is $0 |
+| `is_expert` | bool | Property — True if complexity >= 0.65 |
+
+## License
+
+MIT

package/python/a3m/__init__.py

@@ -0,0 +1,6 @@
+"""A3M Router Python SDK"""
+from .client import A3MRouter
+from .models import RoutingDecision, CostReport
+
+__version__ = "2.1.0"
+__all__ = ["A3MRouter", "RoutingDecision", "CostReport"]

package/python/a3m/client.py

@@ -0,0 +1,190 @@
+"""A3M Router Python SDK — Async client"""
+import json
+import httpx
+from typing import Optional, List, Dict, Any, AsyncIterator
+from .models import RoutingDecision, CostReport
+
+
+class A3MRouter:
+    """Python client for A3M Router.
+
+    Usage:
+        # Auto-start proxy: pip install a3m-router, then:
+        router = A3MRouter(base_url="http://localhost:8787")
+
+        # Route a query (returns OpenAI-compatible response)
+        response = await router.chat("What is 2+2?")
+
+        # Get routing decision only (no LLM call)
+        decision = await router.route("What is 2+2?")
+        print(decision.model, decision.tier, decision.cost)
+
+        # Use with OpenAI SDK
+        from openai import AsyncOpenAI
+        client = AsyncOpenAI(base_url="http://localhost:8787/v1", api_key="not-needed")
+        response = await client.chat.completions.create(
+            model="auto",
+            messages=[{"role": "user", "content": "Hello"}]
+        )
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8787",
+        timeout: float = 30.0,
+        api_key: str = "not-needed",
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+
+    async def chat(
+        self,
+        message: str,
+        model: str = "auto",
+        max_tokens: int = 100,
+        temperature: float = 0.7,
+        system: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Send a chat message and get a routed response.
+
+        Args:
+            message: User message
+            model: Model to use (default "auto" for intelligent routing)
+            max_tokens: Max response tokens
+            temperature: Response temperature
+            system: Optional system prompt
+
+        Returns:
+            OpenAI-compatible response dict
+        """
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": message})
+
+        response = await self._client.post(
+            "/v1/chat/completions",
+            json={
+                "model": model,
+                "messages": messages,
+                "max_tokens": max_tokens,
+                "temperature": temperature,
+            },
+        )
+        response.raise_for_status()
+        return response.json()
+
+    async def route(self, query: str) -> RoutingDecision:
+        """Get routing decision for a query without executing it.
+
+        Args:
+            query: The query to analyze
+
+        Returns:
+            RoutingDecision with model, tier, cost, reasoning
+        """
+        response = await self._client.post(
+            "/v1/route",
+            json={"query": query},
+        )
+        response.raise_for_status()
+        data = response.json()
+        return RoutingDecision(
+            model=data.get("model", "unknown"),
+            tier=data.get("tier", "unknown"),
+            cost=data.get("cost", 0),
+            complexity=data.get("complexity", 0),
+            reasoning=data.get("reasoning", ""),
+            fallback_models=data.get("fallback_models", []),
+        )
+
+    async def route_batch(self, queries: List[str]) -> List[RoutingDecision]:
+        """Route multiple queries in batch.
+
+        Args:
+            queries: List of queries to route
+
+        Returns:
+            List of RoutingDecision objects
+        """
+        decisions = []
+        for q in queries:
+            d = await self.route(q)
+            decisions.append(d)
+        return decisions
+
+    async def models(self) -> List[Dict[str, Any]]:
+        """List available models and their metadata."""
+        response = await self._client.get("/v1/models")
+        response.raise_for_status()
+        return response.json().get("data", [])
+
+    async def health(self) -> Dict[str, Any]:
+        """Check router health and provider availability."""
+        response = await self._client.get("/health")
+        response.raise_for_status()
+        return response.json()
+
+    async def cost_report(self) -> CostReport:
+        """Get cost analytics and savings report."""
+        response = await self._client.get("/dashboard")
+        response.raise_for_status()
+        data = response.json()
+        return CostReport(
+            total_requests=data.get("total_requests", 0),
+            total_cost=data.get("total_cost", 0),
+            savings_vs_premium=data.get("savings_vs_premium", 0),
+            by_provider=data.get("by_provider", {}),
+        )
+
+    async def stream_chat(
+        self,
+        message: str,
+        model: str = "auto",
+        max_tokens: int = 100,
+    ) -> AsyncIterator[str]:
+        """Stream a chat response token by token.
+
+        Args:
+            message: User message
+            model: Model to use
+            max_tokens: Max response tokens
+
+        Yields:
+            Response tokens as they arrive
+        """
+        async with self._client.stream(
+            "POST",
+            "/v1/chat/completions",
+            json={
+                "model": model,
+                "messages": [{"role": "user", "content": message}],
+                "max_tokens": max_tokens,
+                "stream": True,
+            },
+        ) as response:
+            response.raise_for_status()
+            async for line in response.aiter_lines():
+                if line.startswith("data: "):
+                    data = line[6:]
+                    if data == "[DONE]":
+                        break
+                    chunk = json.loads(data)
+                    content = chunk.get("choices", [{}])[0].get("delta", {}).get("content", "")
+                    if content:
+                        yield content
+
+    async def close(self):
+        """Close the HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()

package/python/a3m/models.py

@@ -0,0 +1,40 @@
+"""Data models for A3M Router Python SDK"""
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional
+
+
+@dataclass
+class RoutingDecision:
+    """Result of a routing decision."""
+    model: str
+    tier: str
+    cost: float
+    complexity: float = 0.0
+    reasoning: str = ""
+    fallback_models: List[str] = field(default_factory=list)
+
+    @property
+    def is_free(self) -> bool:
+        return self.cost == 0
+
+    @property
+    def is_expert(self) -> bool:
+        return self.complexity >= 0.65
+
+    def __str__(self) -> str:
+        return f"RoutingDecision(model={self.model}, tier={self.tier}, cost=${self.cost:.6f}, complexity={self.complexity:.2f})"
+
+
+@dataclass
+class CostReport:
+    """Cost analytics report."""
+    total_requests: int = 0
+    total_cost: float = 0.0
+    savings_vs_premium: float = 0.0
+    by_provider: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def savings_percentage(self) -> float:
+        if self.total_cost + self.savings_vs_premium == 0:
+            return 0
+        return self.savings_vs_premium / (self.total_cost + self.savings_vs_premium) * 100

package/python/a3m/sync_client.py

@@ -0,0 +1,61 @@
+"""A3M Router Python SDK — Synchronous client"""
+import httpx
+from typing import Optional, List, Dict, Any
+from .models import RoutingDecision, CostReport
+
+
+class A3MRouterSync:
+    """Synchronous Python client for A3M Router.
+
+    Usage:
+        router = A3MRouterSync()
+        response = router.chat("What is 2+2?")
+        decision = router.route("Write a Python function")
+        print(decision.model, decision.cost)
+    """
+
+    def __init__(self, base_url: str = "http://localhost:8787", timeout: float = 30.0):
+        self._client = httpx.Client(base_url=base_url.rstrip("/"), timeout=timeout)
+
+    def chat(self, message: str, model: str = "auto", max_tokens: int = 100, **kwargs) -> Dict[str, Any]:
+        messages = [{"role": "user", "content": message}]
+        if kwargs.get("system"):
+            messages.insert(0, {"role": "system", "content": kwargs["system"]})
+        response = self._client.post("/v1/chat/completions", json={
+            "model": model, "messages": messages,
+            "max_tokens": max_tokens, "temperature": kwargs.get("temperature", 0.7),
+        })
+        response.raise_for_status()
+        return response.json()
+
+    def route(self, query: str) -> RoutingDecision:
+        response = self._client.post("/v1/route", json={"query": query})
+        response.raise_for_status()
+        data = response.json()
+        return RoutingDecision(
+            model=data.get("model", "unknown"), tier=data.get("tier", "unknown"),
+            cost=data.get("cost", 0), complexity=data.get("complexity", 0),
+            reasoning=data.get("reasoning", ""), fallback_models=data.get("fallback_models", []),
+        )
+
+    def route_batch(self, queries: List[str]) -> List[RoutingDecision]:
+        return [self.route(q) for q in queries]
+
+    def models(self) -> List[Dict[str, Any]]:
+        response = self._client.get("/v1/models")
+        response.raise_for_status()
+        return response.json().get("data", [])
+
+    def health(self) -> Dict[str, Any]:
+        response = self._client.get("/health")
+        response.raise_for_status()
+        return response.json()
+
+    def close(self):
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

package/python/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.backends._legacy:_Backend"
+
+[project]
+name = "a3m-router"
+version = "2.1.0"
+description = "Python SDK for A3M Router — intelligent LLM routing with 99.5% accuracy"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+dependencies = ["httpx>=0.24.0"]
+keywords = ["llm", "routing", "openai", "proxy", "ai-gateway", "routellm", "litellm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/Das-rebel/adaptive-memory-multi-model-router"