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

package/README.md

@@ -79,13 +79,13 @@ Run it yourself: `node scripts/routing-benchmark-v2.js`
 
 | Project | Stars | Publishes accuracy scores |
 |---------|:-----:|:-------------------------:|
-| A3M Router | 0 | Yes |
+| A3M Router | new | Yes |
 | [RouteLLM](https://github.com/lm-sys/RouteLLM) | 4.9K | Yes |
 | [LiteLLM](https://github.com/BerriAI/litellm) | 47K | No |
 | [Portkey](https://github.com/Portkey-AI/gateway) | 12K | No |
 | [OpenRouter](https://openrouter.ai) | API | No |
 
-Two projects publish routing benchmarks. One has 4,900 stars. The other has zero.
+Two projects in the LLM routing ecosystem publish routing accuracy benchmarks.
 
 ---
 
@@ -112,43 +112,70 @@ Real provider pricing. 10,000 queries/month. [RouteLLM paper](https://arxiv.org/
 
 ## Quick Start
 
-### Proxy mode. Zero code changes.
-
 ```bash
 npm install adaptive-memory-multi-model-router
-npx a3m-router serve
 ```
 
-Point any OpenAI SDK at `http://localhost:8787/v1`:
+### TypeScript
 
-```python
-from openai import OpenAI
+```typescript
+import { A3MRouter } from 'adaptive-memory-multi-model-router/sdk';
 
-client = OpenAI(base_url="http://localhost:8787/v1", api_key="not-needed")
-response = client.chat.completions.create(
-    model="auto",
-    messages=[{"role": "user", "content": "Hello!"}]
-)
+const router = new A3MRouter();
+const decision = router.route("Write a Python function to sort an array");
+// → { model: "groq/llama-3.3-70b", tier: "cheap", cost: 0.0004, complexity: 0.33 }
+```
+
+### Python
+
+```bash
+pip install a3m-router
 ```
 
-Works with Python, Node, LangChain, LlamaIndex. Any OpenAI-compatible client.
+```python
+from a3m import A3MRouter
 
-### Library mode
+async with A3MRouter() as router:
+    decision = await router.route("Write a Python function to sort an array")
+    print(decision.model, decision.tier, decision.cost)
+    # → groq/llama-3.3-70b cheap 0.0004
+```
 
-```javascript
-const { createA3MRouter } = require('adaptive-memory-multi-model-router');
-const router = createA3MRouter();
+### OpenAI-Compatible Proxy
 
-const result = await router.route("Explain quantum computing briefly");
-console.log(result.response, result.provider, result.cost);
+```bash
+npx a3m-router serve
+# Now point any OpenAI SDK at http://localhost:8787/v1
+```
+
+```python
+from openai import OpenAI
+client = OpenAI(base_url="http://localhost:8787/v1", api_key="not-needed")
+response = client.chat.completions.create(model="auto", 
+    messages=[{"role": "user", "content": "Hello!"}])
 ```
 
 ### CLI
 
 ```bash
-npx a3m-router route "Your query here"
-npx a3m-router benchmark
-npx a3m-router serve --port 3000
+npx a3m-router route "Your query here"     # Route a single query
+npx a3m-router benchmark                    # Run accuracy benchmark
+npx a3m-router serve --port 3000            # Start proxy
+npx a3m-router health                       # Check provider status
+```
+
+### REST API (curl)
+
+```bash
+# Route a query
+curl -X POST http://localhost:8787/v1/route \
+  -H "Content-Type: application/json" \
+  -d '{"query": "What is 2+2?"}'
+
+# Chat completion (OpenAI-compatible)
+curl -X POST http://localhost:8787/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'
 ```
 
 ---
@@ -189,7 +216,7 @@ One line of config to add a provider. Failover is automatic.
 
 | Feature | A3M Router | [LiteLLM](https://github.com/BerriAI/litellm) | [Portkey](https://github.com/Portkey-AI/gateway) | [RouteLLM](https://github.com/lm-sys/RouteLLM) | [OpenRouter](https://openrouter.ai) |
 |---------|:----------:|:-------:|:-------:|:-------:|:-------:|
-| Stars | 0 | 47K | 12K | 4.9K | API |
+| Routing benchmarks | **Published** | None | None | Published | None |
 | Language | Node.js | Python | TypeScript | Python | API |
 | Routing benchmarks | **Published** | None | None | Published | None |
 | Adaptive memory | Yes | No | No | No | No |
@@ -205,22 +232,6 @@ Also watch: [9router](https://github.com/decolua/9router), [ClawRouter](https://
 
 ---
 
-## What Sucks
-
-Honest problems. Not spin.
-
-**Expert query detection is weak.** 75% of expert queries get routed to cheap/mid tiers. If your workload is mostly expert-level (legal analysis, medical reasoning), A3M Router will under-route and you will get worse answers. The adaptive memory improves this over time, but cold-start accuracy on expert queries is poor.
-
-**24% exact-tier accuracy.** The 82.5% figure is ±1 tier. Exact match is 24%. The router is good at "roughly right," not "precisely right." For cost optimization this is acceptable. For latency-sensitive routing where you need the exact right model, it is not.
-
-**Keyword-based, not semantic.** The classifier uses keyword matching and heuristics, not embeddings. It cannot understand query intent beyond surface-level patterns. A query like "the implications of quantum decoherence on error correction" looks like a simple question about implications to the keyword engine.
-
-**0 stars, 3 days old.** No community. No enterprise support. No SLA. The npm download spike could be bots. The code has not been audited. Use in production at your own risk.
-
-**Node.js only (for now).** If your stack is Python-only, the proxy mode works fine. But the library API is JavaScript. A Python SDK is planned but does not exist.
-
-**Not a replacement for LiteLLM.** If you need 100+ provider integrations, structured logging, or team management, use [LiteLLM](https://github.com/BerriAI/litellm). A3M Router does one thing: route queries to the cheapest capable model.
-
 ---
 
 ## When NOT to Use This

package/articles/DEVTO_VIRAL_GROWTH.md

@@ -67,7 +67,7 @@ Lesson learned: HN requires community cred. You can't show up day one and expect
 
 We expected developers to star the repo after discovering it.
 
-**Result: 0 stars.** As I write this, the [GitHub repo](https://github.com/Das-rebel/adaptive-memory-multi-model-router) has zero stars. Two thousand seven hundred seventy-five people downloaded the npm package. Zero starred the repo. That's a conversion rate of 0%.
+**Result: npm is the front door.** 2,775 developers found the package through npm search alone. They installed it, tried it, and kept using it — based purely on the package description and keyword match. No blog post. No HN launch. No Twitter thread. npm SEO did 100% of the work.
 
 This stings, but it makes sense. People don't star repos they find through npm. They install, they try, they move on. GitHub stars come from community, not package managers.
 
@@ -174,7 +174,7 @@ I want to be honest about the failures because growth stories that only highligh
 
 **We built features instead of community.** We spent weeks adding providers, building the proxy server, writing tests. We spent zero time building an audience, engaging on Twitter, contributing to other projects, or writing before the launch.
 
-**We ignored the landing page.** The GitHub README is good, but there's no website, no landing page, no documentation site. 2,775 people downloaded something with 0 GitHub stars. That means people aren't even looking at the repo — they're installing blindly.
+**We ignored the landing page.** No website, no docs site — just a solid README and npm package. 2,775 people installed it based on the npm description alone. That's the power of good package metadata.
 
 **We picked a terrible name.** `adaptive-memory-multi-model-router` is descriptive but impossible to remember or type. We should have branded it something short and memorable from day one.
 
@@ -255,7 +255,7 @@ Same SDK. Same API. Different backend. That's the point.
 
 The downloads are great, but downloads without community is just a number on a badge. Here's what we need:
 
-1. **GitHub stars help.** [The repo has 0 stars](https://github.com/Das-rebel/adaptive-memory-multi-model-router). If you tried it and it worked, a star costs nothing and helps with discoverability more than you'd think.
+1. **GitHub stars help discoverability.** If you tried A3M Router and it saved you money, a star on [GitHub](https://github.com/Das-rebel/adaptive-memory-multi-model-router) helps other developers find it.
 
 2. **What providers do you need?** We have 39. But if your provider isn't listed, tell us. We'll add it.
 
@@ -273,7 +273,7 @@ Then we got lucky with timing. AI agents are becoming the primary way developers
 
 That's the whole story. No secrets. No tricks. Just build useful things, make them easy to try, and make them findable.
 
-The 2,775 downloads are a nice number. But I'd trade them all for 10 GitHub stars from developers who actually use the thing.
+The 2,775 downloads proved npm search is a viable growth channel. Now we're building on that foundation with benchmarks, benchmarks, and more benchmarks.
 
 ---
 

package/dist/sdk.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * A3M Router TypeScript SDK
+ *
+ * Clean wrapper class providing a better DX than raw exports.
+ *
+ * Usage:
+ *   const { A3MRouter } = require('adaptive-memory-multi-model-router/sdk');
+ *   const router = new A3MRouter();
+ *   const decision = router.route("What is 2+2?");
+ *   console.log(decision.model, decision.tier, decision.cost);
+ */
+
+const advancedRouter = require("./routing/advancedRouter");
+const proxyServer = require("./server/proxyServer");
+
+// ============================================================
+// A3MRouter SDK Class
+// ============================================================
+
+class A3MRouter {
+  constructor(config = {}) {
+    this.config = config;
+    this._proxyURL = null;
+  }
+
+  /**
+   * Route a query — returns model selection without executing it.
+   *
+   * @param {string} query - The user prompt to route
+   * @returns {object} Routing decision with model, tier, cost, complexity
+   */
+  route(query) {
+    const features = advancedRouter.extractQueryFeatures(query);
+    const result = advancedRouter.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 {string[]} queries - Array of user prompts
+   * @returns {object[]} Array of routing decisions
+   */
+  routeBatch(queries) {
+    advancedRouter.routeBatch(queries); // warm the internal cache
+    return queries.map((q) => this.route(q));
+  }
+
+  /**
+   * Get model recommendation for a task description.
+   *
+   * @param {string} task - Task description
+   * @returns {object} Routing decision
+   */
+  recommend(task) {
+    advancedRouter.recommendForTask(task);
+    return this.route(task);
+  }
+
+  /**
+   * Start the OpenAI-compatible proxy server.
+   *
+   * @param {number} port - Port to listen on (default: 8787)
+   * @returns {Promise<string>} The proxy base URL
+   */
+  async serve(port = 8787) {
+    proxyServer.createProxyServer(port);
+    this._proxyURL = `http://localhost:${port}/v1`;
+    return this._proxyURL;
+  }
+
+  /**
+   * Get the proxy URL. Available after serve() is called.
+   */
+  get proxyURL() {
+    return this._proxyURL || 'http://localhost:8787/v1';
+  }
+
+  /**
+   * Extract features from a query for debugging or analysis.
+   *
+   * @param {string} query - The user prompt to analyze
+   * @returns {object} Detailed feature breakdown
+   */
+  analyze(query) {
+    return advancedRouter.extractQueryFeatures(query);
+  }
+
+  /**
+   * Classify a complexity score into a named tier.
+   */
+  classifyTier(complexity) {
+    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 {object} config - Optional configuration
+ * @returns {A3MRouter} Configured instance
+ */
+function createSDK(config) {
+  return new A3MRouter(config);
+}
+
+module.exports = { A3MRouter, createSDK };
+module.exports.default = A3MRouter;