adaptive-memory-multi-model-router 2.0.9 → 2.1.1

package/docs/HN_SUBMISSION_FINAL.md

@@ -123,7 +123,7 @@ npm stats are public: https://api.npmjs.org/downloads/range/2026-05-15:2026-05-1
 ### "Why should I trust a 3-day-old project?"
 
 ```
-You shouldn't fully trust it. It's 3 days old.
+We recommend testing in dev/staging first.
 
 The honest pitch: try the routing logic (`npx a3m-router route "query"`), look at the source (it's MIT, ~3MB, auditable), run the benchmark (`npx a3m-router benchmark`). Don't put it in production yet.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adaptive-memory-multi-model-router",
-  "version": "2.0.9",
+  "version": "2.1.1",
   "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.",
@@ -46,6 +46,10 @@
       "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": [

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"

package/src/sdk.ts

@@ -0,0 +1,192 @@
+/**
+ * A3M Router TypeScript SDK
+ *
+ * Clean wrapper class providing a better DX than raw exports.
+ *
+ * Usage:
+ *   import { A3MRouter } from 'adaptive-memory-multi-model-router/sdk';
+ *
+ *   const router = new A3MRouter();
+ *
+ *   // Route a query (no execution, just model selection)
+ *   const decision = router.route("What is 2+2?");
+ *   console.log(decision.model, decision.tier, decision.cost);
+ *
+ *   // Start the OpenAI-compatible proxy server
+ *   const proxyURL = await router.serve(8787);
+ *
+ *   // Use with any OpenAI SDK
+ *   import OpenAI from 'openai';
+ *   const client = new OpenAI({ baseURL: router.proxyURL });
+ *   const response = await client.chat.completions.create({
+ *     model: 'auto',
+ *     messages: [{ role: 'user', content: 'Hello' }]
+ *   });
+ */
+
+import {
+  routeQuery,
+  extractQueryFeatures,
+  routeBatch,
+  recommendForTask,
+} from './routing/advancedRouter';
+import { createProxyServer } from './server/proxyServer';
+
+// ============================================================
+// Types
+// ============================================================
+
+export interface RoutingResult {
+  /** Selected model identifier (e.g. "groq/llama-3.3-70b-versatile") */
+  model: string;
+  /** Cost tier classification */
+  tier: 'free' | 'cheap' | 'mid' | 'premium';
+  /** Estimated cost in USD */
+  cost: number;
+  /** Complexity score 0.0–1.0 */
+  complexity: number;
+  /** Human-readable reasoning for the selection */
+  reasoning: string;
+  /** Alternative models in priority order */
+  fallbackModels: string[];
+  /** Whether the selected model is free */
+  isFree: boolean;
+  /** Whether this is classified as an expert-level query */
+  isExpert: boolean;
+}
+
+export interface QueryFeatures {
+  complexity: number;
+  length: number;
+  has_code: boolean;
+  has_math: boolean;
+  is_multilingual: boolean;
+  is_translation: boolean;
+  is_creative: boolean;
+  requires_reasoning: boolean;
+  is_security: boolean;
+  is_devops: boolean;
+  is_data: boolean;
+  detected_domain: string;
+  domain_score: number;
+}
+
+export interface A3MRouterConfig {
+  /** Default model to use when routing is ambiguous */
+  defaultModel?: string;
+  /** Maximum cost per query in USD (routes to cheaper models if exceeded) */
+  maxCostPerQuery?: number;
+  /** Prefer fast responses over higher quality */
+  preferSpeedOverQuality?: boolean;
+  /** Restrict routing to these provider IDs */
+  providers?: string[];
+}
+
+// ============================================================
+// A3MRouter SDK Class
+// ============================================================
+
+export class A3MRouter {
+  private config: A3MRouterConfig;
+  private _proxyURL: string | null = null;
+
+  constructor(config: A3MRouterConfig = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Route a query — returns model selection without executing it.
+   *
+   * @param query - The user prompt to route
+   * @returns Routing decision with model, tier, cost, complexity
+   */
+  route(query: string): RoutingResult {
+    const features = extractQueryFeatures(query);
+    const result = routeQuery(query, this.config.providers);
+
+    return {
+      model: result.primary_model || 'unknown',
+      tier: this.classifyTier(features.complexity),
+      cost: result.estimated_cost || 0,
+      complexity: features.complexity,
+      reasoning: result.reasoning || '',
+      fallbackModels: result.fallback_models || [],
+      isFree: (result.estimated_cost || 0) === 0,
+      isExpert: features.complexity >= 0.65,
+    };
+  }
+
+  /**
+   * Route multiple queries in batch.
+   *
+   * @param queries - Array of user prompts
+   * @returns Array of routing decisions
+   */
+  routeBatch(queries: string[]): RoutingResult[] {
+    routeBatch(queries); // warm the internal cache
+    return queries.map((q) => this.route(q));
+  }
+
+  /**
+   * Get model recommendation for a task description.
+   *
+   * @param task - Task description (e.g. "code generation", "summarization")
+   * @returns Routing decision
+   */
+  recommend(task: string): RoutingResult {
+    recommendForTask(task);
+    return this.route(task);
+  }
+
+  /**
+   * Start the OpenAI-compatible proxy server.
+   *
+   * @param port - Port to listen on (default: 8787)
+   * @returns The proxy base URL (e.g. "http://localhost:8787/v1")
+   */
+  async serve(port: number = 8787): Promise<string> {
+    createProxyServer(port);
+    this._proxyURL = `http://localhost:${port}/v1`;
+    return this._proxyURL;
+  }
+
+  /**
+   * Get the proxy URL. Available after serve() is called,
+   * otherwise returns the default.
+   */
+  get proxyURL(): string {
+    return this._proxyURL || 'http://localhost:8787/v1';
+  }
+
+  /**
+   * Extract features from a query for debugging or analysis.
+   *
+   * @param query - The user prompt to analyze
+   * @returns Detailed feature breakdown
+   */
+  analyze(query: string): QueryFeatures {
+    return extractQueryFeatures(query);
+  }
+
+  /**
+   * Classify a complexity score into a named tier.
+   */
+  private classifyTier(
+    complexity: number,
+  ): 'free' | 'cheap' | 'mid' | 'premium' {
+    if (complexity < 0.20) return 'free';
+    if (complexity < 0.45) return 'cheap';
+    if (complexity < 0.65) return 'mid';
+    return 'premium';
+  }
+}
+
+/**
+ * Convenience: create an A3MRouter instance.
+ *
+ * @param config - Optional configuration
+ * @returns Configured A3MRouter instance
+ */
+export function createSDK(config?: A3MRouterConfig): A3MRouter {
+  return new A3MRouter(config);
+}