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

package/README.md

@@ -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 }
 ```
 
-Works with Python, Node, LangChain, LlamaIndex. Any OpenAI-compatible client.
+### Python
+
+```bash
+pip install a3m-router
+```
+
+```python
+from a3m import A3MRouter
+
+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
+```
 
-### Library mode
+### OpenAI-Compatible Proxy
 
-```javascript
-const { createA3MRouter } = require('adaptive-memory-multi-model-router');
-const router = createA3MRouter();
+```bash
+npx a3m-router serve
+# Now point any OpenAI SDK at http://localhost:8787/v1
+```
 
-const result = await router.route("Explain quantum computing briefly");
-console.log(result.response, result.provider, result.cost);
+```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"}]}'
 ```
 
 ---

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;