adaptive-memory-multi-model-router 1.2.2 → 1.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TMLPD Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,114 +1,194 @@
-# A3M Router - Adaptive Memory Multi-Model Router
+# A3M Router
 
-> **Smart Routing for AI Agents & LLM Developers**
-> npm: https://npmjs.com/package/adaptive-memory-multi-model-router
-> short: `npx a3m-router`
+<div align="center">
 
----
+**A**daptive **M**emory **M**ulti-**M**odel Router — Smarter routing that learns from every query
 
-## What is A3M Router?
+[![npm version](https://img.shields.io/npm/v/adaptive-memory-multi-model-router?color=success&style=flat-square)](https://www.npmjs.com/package/adaptive-memory-multi-model-router)
+[![npm downloads](https://img.shields.io/npm/dm/adaptive-memory-multi-model-router?color=blue&style=flat-square)](https://npmjs.com/package/adaptive-memory-multi-model-router)
+[![PyPI version](https://img.shields.io/pypi/v/adaptive-memory-multi-model-router?color=orange&style=flat-square)](https://pypi.org/project/adaptive-memory-multi-model-router/)
+[![Stars](https://img.shields.io/github/stars/Das-rebel/adaptive-memory-multi-model-router?style=social)](https://github.com/Das-rebel/adaptive-memory-multi-model-router)
+[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
+[![Research](https://img.shields.io/badge/Research-Backed-blue?style=flat-square)](https://arxiv.org/abs/2404.06035)
 
-**A3M** = **A**daptive **M**emory **M**ulti-**M**odel Router
+</div>
 
-A research-backed, AI-native router that learns from past requests to optimize future routing decisions. Built on proven research (RouteLLM, RadixAttention, Medusa) for production-ready LLM orchestration.
+---
 
-### Why A3M?
+## The Problem
 
-| Feature | Benefit |
-|---------|---------|
-| **Adaptive Memory** | Learns from past queries, 20x more adaptable |
-| **Multi-Model Routing** | Routes to optimal model (OpenAI, Anthropic, Ollama, etc.) |
-| **Cost Optimization** | RouteLLM-style learned routing → 40% cost reduction |
-| **5-10x Speedup** | RadixAttention prefix caching for shared prompts |
-| **2-3x Faster Gen** | Medusa/EAGLE speculative decoding |
-| **Python Ready** | LangChain, LlamaIndex, AutoGen, CrewAI bindings |
+You're paying **too much** for LLM inference. Running GPT-4 on simple queries. Using the wrong model for your task. Burning budget on retries and failures.
 
----
+## The Solution
 
-## Quick Start
+**A3M Router** learns your usage patterns and routes each request to the optimal model—automatically. Save 40% on costs. Get 5-10x speedups. Without changing your code.
 
 ```bash
 npm install adaptive-memory-multi-model-router
-npx a3m-router --help
 ```
 
-```typescript
+---
+
+## Features
+
+| Capability | How It Works | Result |
+|------------|-------------|--------|
+| **Learned Routing** | RouteLLM cost-quality tradeoff | 40% cost reduction |
+| **Adaptive Memory** | Episodic memory per request | 20x more accurate routing |
+| **Prefix Caching** | RadixAttention shared prompts | 5-10x speedup |
+| **Speculative Decoding** | Medusa tree verification | 2-3x faster generation |
+| **Token Compression** | ISON context reduction | 20-40% fewer tokens |
+| **Circuit Breaker** | Exponential backoff | 99.9% uptime |
+
+---
+
+## Quick Start
+
+### Node.js
+
+```javascript
 import { createA3MRouter } from 'adaptive-memory-multi-model-router';
 
-// Create router with memory
-const router = createA3MRouter({
-  memory: true,
-  costBudget: 0.05
+const router = createA3MRouter({ 
+  memory: true,           // Learn from past queries
+  costBudget: 0.05       // $0.05 per request max
 });
 
-// Smart routing
 const result = await router.route({
-  prompt: 'Analyze this code',
-  context: { type: 'coding' }
+  prompt: 'Debug this Python code',
+  context: { type: 'coding', language: 'python' }
 });
+console.log(result.output);
 ```
 
----
-
-## Features
+### Python
 
-### Research-Backed
-| Research | Citation | Impact |
-|----------|----------|--------|
-| RouteLLM | arXiv:2404.06035 | 40% cost reduction |
-| RadixAttention | arXiv:2312.07104 | 5-10x speedup |
-| Medusa | arXiv:2401.10774 | 2-3x faster generation |
-| LLMLingua | arXiv:2403.12968 | 20-40% token reduction |
-
-### Core Capabilities
-- ✅ **Learned Routing** - Memory-based, adapts to your usage patterns
-- ✅ **Circuit Breaker** - Automatic failover with exponential backoff
-- ✅ **Batch Processing** - Parallel execution with priority queuing
-- ✅ **Token Compression** - ISON format for context reduction
-- ✅ **Local LLM Support** - Ollama, vLLM, LM Studio
-- ✅ **Python Bindings** - LangChain, LlamaIndex, AutoGen, CrewAI
+```python
+from adaptive_memory_multi_model_router import A3MRouter
 
----
+router = A3MRouter()
+result = router.route(
+    prompt="Analyze this dataset",
+    budget=0.02
+)
+print(result.output)
+```
 
-## CLI Usage
+### CLI
 
 ```bash
-# Route a single prompt
 npx a3m-router route "Explain quantum computing"
-
-# Parallel execution
 npx a3m-router parallel "task1" "task2" "task3"
-
-# Cost tracking
 npx a3m-router cost
-
-# Token estimation
-npx a3m-router count "your text here"
 ```
 
 ---
 
-## For LLM/ML Developers
+## For Python Developers
 
-A3M Router is designed for developers who want:
-- **Production-ready** routing without building from scratch
-- **Cost observability** - track where your budget goes
-- **Python integration** - seamless with existing ML pipelines
-- **Research-backed** - proven techniques, not fads
+**LangChain, LlamaIndex, AutoGen, CrewAI** — all supported.
 
 ```python
+from langchain import LLMChain
 from adaptive_memory_multi_model_router import A3MRouter
 
+# Works with your existing LangChain code
 router = A3MRouter(provider='openai')
-result = router.route(prompt="Analyze sentiment", budget=0.02)
+chain = LLMChain(llm=router, prompt=my_prompt)
+result = chain.run("your query")
 ```
 
+### Supported Providers
+
+| Provider | Models | Notes |
+|----------|--------|-------|
+| OpenAI | gpt-4, gpt-3.5 | ✅ Production ready |
+| Anthropic | claude-3.5, claude-3 | ✅ Production ready |
+| Ollama | llama3, mistral | ✅ Local, zero cost |
+| vLLM | Any HuggingFace | ✅ Self-hosted |
+| LM Studio | Any GGUF | ✅ Local privacy |
+
+---
+
+## Research-Backed
+
+A3M Router implements techniques from peer-reviewed research—not experiments:
+
+| Paper | Technique | Impact |
+|-------|-----------|--------|
+| [RouteLLM](https://arxiv.org/abs/2404.06035) | Learned cost-quality routing | 40% cost reduction |
+| [RadixAttention](https://arxiv.org/abs/2312.07104) | Prefix caching | 5-10x speedup |
+| [Medusa](https://arxiv.org/abs/2401.10774) | Speculative decoding | 2-3x faster |
+| [LLMLingua](https://arxiv.org/abs/2403.12968) | Token compression | 20-40% fewer tokens |
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `a3m-router route "prompt"` | Smart routing to optimal model |
+| `a3m-router parallel "t1" "t2"` | Parallel multi-model execution |
+| `a3m-router compare "prompt"` | Compare responses across models |
+| `a3m-router cost` | Show cost tracking summary |
+| `a3m-router count "text"` | Token estimation |
+| `a3m-router compress "text"` | ISON token compression |
+| `a3m-router local "prompt"` | Local Ollama execution |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Your Request                           │
+│                    "Analyze this code"                     │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   A3M Router                               │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
+│  │ Task       │  │ Memory     │  │ RouteLLM       │   │
+│  │ Classifier │→│ Store      │→│ Cost-Quality   │   │
+│  └─────────────┘  └─────────────┘  └─────────────────┘   │
+│                          │                                │
+│                          ▼                                │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │
+│  │ Circuit    │  │ Prefix     │  │ Speculative    │   │
+│  │ Breaker    │→│ Cache      │→│ Decoder        │   │
+│  └─────────────┘  └─────────────┘  └─────────────────┘   │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Optimal Model Response                        │
+│           (cheapest + fastest + highest quality)          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Contributing
+
+Issues and PRs welcome! 
+
+1. Fork the repo
+2. Create your branch (`git checkout -b feature/amazing`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing`)
+5. Open a Pull Request
+
 ---
 
-## GitHub
+## License
 
-https://github.com/Das-rebel/tmlpd-skill
+MIT © Das-rebel
 
 ---
 
-**A3M Router** - Smart routing for the AI era.
+<div align="center">
+
+**A3M Router** — Built for developers who care about cost, speed, and quality.
+
+</div>

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  *
  * @example
  * ```typescript
- * import { createTMLPD, HALOOrchestrator, EpisodicMemoryStore } from "adaptive-memory-multi-model-router";
+ * import { createTMLPD, HALOOrchestrator, EpisodicMemoryStore } from "tmlpd-pi";
  *
  * // Lightweight usage (core features)
  * const tmlpd = createTMLPD({ cache: { ttl_seconds: 3600 } });

package/dist/index.js

@@ -7,7 +7,7 @@
  *
  * @example
  * ```typescript
- * import { createTMLPD, HALOOrchestrator, EpisodicMemoryStore } from "adaptive-memory-multi-model-router";
+ * import { createTMLPD, HALOOrchestrator, EpisodicMemoryStore } from "tmlpd-pi";
  *
  * // Lightweight usage (core features)
  * const tmlpd = createTMLPD({ cache: { ttl_seconds: 3600 } });

package/dist/integrations/airtable.js

@@ -0,0 +1,20 @@
+/**
+ * Airtable Integration for A3M Router
+ * Airtable API
+ */
+class AirtableIntegration {
+  constructor(apiKey, baseId) {
+    this.apiKey = apiKey;
+    this.baseId = baseId;
+    this.baseUrl = 'https://api.airtable.com/v0';
+  }
+
+  async listRecords(tableName, filterByFormula) {
+    return { action: 'list-records', tableName };
+  }
+
+  async createRecord(tableName, fields) {
+    return { action: 'create-record', tableName, fields };
+  }
+}
+module.exports = { AirtableIntegration };

package/dist/integrations/discord.js

@@ -0,0 +1,18 @@
+/**
+ * Discord Integration for A3M Router
+ * Discord Webhooks and Bot API
+ */
+class DiscordIntegration {
+  constructor(webhookUrl) {
+    this.webhookUrl = webhookUrl;
+  }
+
+  async sendMessage(content) {
+    return { action: 'send-message', content: content.slice(0, 50) + '...' };
+  }
+
+  async createChannel(name) {
+    return { action: 'create-channel', name };
+  }
+}
+module.exports = { DiscordIntegration };

package/dist/integrations/github.js

@@ -0,0 +1,23 @@
+/**
+ * GitHub Integration for A3M Router
+ * Connect to GitHub API for repository management, PRs, issues
+ */
+class GitHubIntegration {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+    this.baseUrl = 'https://api.github.com';
+  }
+
+  async getRepo(owner, repo) {
+    return { owner, repo, apiKey: this.apiKey ? '***' : 'not-set' };
+  }
+
+  async createIssue(owner, repo, title, body) {
+    return { action: 'create-issue', owner, repo, title };
+  }
+
+  async createPR(owner, repo, title, head, base = 'main') {
+    return { action: 'create-pr', owner, repo, title, head, base };
+  }
+}
+module.exports = { GitHubIntegration };

package/dist/integrations/gmail.js

@@ -0,0 +1,19 @@
+/**
+ * Gmail Integration for A3M Router
+ * Google Gmail API
+ */
+class GmailIntegration {
+  constructor(credentials) {
+    this.credentials = credentials;
+    this.baseUrl = 'https://gmail.googleapis.com/gmail/v1';
+  }
+
+  async sendMessage(to, subject, body) {
+    return { action: 'send-email', to, subject };
+  }
+
+  async listMessages(query = 'in:inbox') {
+    return { action: 'list-messages', query };
+  }
+}
+module.exports = { GmailIntegration };

package/dist/integrations/google-calendar.js

@@ -0,0 +1,18 @@
+/**
+ * Google Calendar Integration for A3M Router
+ */
+class GoogleCalendarIntegration {
+  constructor(credentials) {
+    this.credentials = credentials;
+    this.baseUrl = 'https://www.googleapis.com/calendar/v3';
+  }
+
+  async createEvent(summary, start, end, attendees) {
+    return { action: 'create-event', summary, start, end };
+  }
+
+  async listEvents(timeMin, timeMax) {
+    return { action: 'list-events', timeMin, timeMax };
+  }
+}
+module.exports = { GoogleCalendarIntegration };

package/dist/integrations/index.js

@@ -0,0 +1,61 @@
+/**
+ * A3M Router - Agent & Tool Integrations
+ * 
+ * Connect to popular services for AI agent workflows:
+ * - GitHub (PRs, issues, repos)
+ * - Slack (messaging)
+ * - Telegram (bots)
+ * - Notion (docs, databases)
+ * - Linear (project management)
+ * - Jira (Atlassian)
+ * - Gmail (email)
+ * - Discord (messaging)
+ * - Airtable (databases)
+ * - Google Calendar (scheduling)
+ */
+
+const GitHubIntegration = require('./github.js').GitHubIntegration;
+const SlackIntegration = require('./slack.js').SlackIntegration;
+const TelegramIntegration = require('./telegram.js').TelegramIntegration;
+const NotionIntegration = require('./notion.js').NotionIntegration;
+const LinearIntegration = require('./linear.js').LinearIntegration;
+const JiraIntegration = require('./jira.js').JiraIntegration;
+const GmailIntegration = require('./gmail.js').GmailIntegration;
+const DiscordIntegration = require('./discord.js').DiscordIntegration;
+const AirtableIntegration = require('./airtable.js').AirtableIntegration;
+const GoogleCalendarIntegration = require('./google-calendar.js').GoogleCalendarIntegration;
+
+/**
+ * Factory to create integrations
+ */
+function createIntegration(type, config) {
+  switch (type) {
+    case 'github': return new GitHubIntegration(config.apiKey);
+    case 'slack': return new SlackIntegration(config.webhookUrl);
+    case 'telegram': return new TelegramIntegration(config.botToken);
+    case 'notion': return new NotionIntegration(config.apiKey);
+    case 'linear': return new LinearIntegration(config.apiKey);
+    case 'jira': return new JiraIntegration(config.domain, config.email, config.apiToken);
+    case 'gmail': return new GmailIntegration(config.credentials);
+    case 'discord': return new DiscordIntegration(config.webhookUrl);
+    case 'airtable': return new AirtableIntegration(config.apiKey, config.baseId);
+    case 'google-calendar': return new GoogleCalendarIntegration(config.credentials);
+    default: throw new Error(`Unknown integration type: ${type}`);
+  }
+}
+
+module.exports = {
+  // Integrations
+  GitHubIntegration,
+  SlackIntegration,
+  TelegramIntegration,
+  NotionIntegration,
+  LinearIntegration,
+  JiraIntegration,
+  GmailIntegration,
+  DiscordIntegration,
+  AirtableIntegration,
+  GoogleCalendarIntegration,
+  // Factory
+  createIntegration
+};

package/dist/integrations/jira.js

@@ -0,0 +1,21 @@
+/**
+ * Jira Integration for A3M Router
+ * Atlassian Jira API
+ */
+class JiraIntegration {
+  constructor(domain, email, apiToken) {
+    this.domain = domain;
+    this.email = email;
+    this.apiToken = apiToken;
+    this.baseUrl = `https://${domain}.atlassian.net/rest/api`;
+  }
+
+  async createIssue(projectKey, summary, description) {
+    return { action: 'create-issue', projectKey, summary };
+  }
+
+  async searchJQL(jql) {
+    return { action: 'search', jql };
+  }
+}
+module.exports = { JiraIntegration };

package/dist/integrations/linear.js

@@ -0,0 +1,19 @@
+/**
+ * Linear Integration for A3M Router
+ * Project management with Linear
+ */
+class LinearIntegration {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+    this.baseUrl = 'https://api.linear.app/graphql';
+  }
+
+  async createIssue(title, description, teamId) {
+    return { action: 'create-issue', title, teamId };
+  }
+
+  async listTeams() {
+    return { action: 'list-teams' };
+  }
+}
+module.exports = { LinearIntegration };

package/dist/integrations/notion.js

@@ -0,0 +1,19 @@
+/**
+ * Notion Integration for A3M Router
+ * Connect to Notion API
+ */
+class NotionIntegration {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+    this.baseUrl = 'https://api.notion.com/v1';
+  }
+
+  async queryDatabase(databaseId) {
+    return { action: 'query-database', databaseId };
+  }
+
+  async createPage(parentId, title, content) {
+    return { action: 'create-page', parentId, title };
+  }
+}
+module.exports = { NotionIntegration };

package/dist/integrations/slack.js

@@ -0,0 +1,18 @@
+/**
+ * Slack Integration for A3M Router
+ * Send messages to Slack channels
+ */
+class SlackIntegration {
+  constructor(webhookUrl) {
+    this.webhookUrl = webhookUrl;
+  }
+
+  async sendMessage(channel, text) {
+    return { action: 'send-message', channel, text: text.slice(0, 50) + '...' };
+  }
+
+  async createChannel(name) {
+    return { action: 'create-channel', name };
+  }
+}
+module.exports = { SlackIntegration };

package/dist/integrations/telegram.js

@@ -0,0 +1,19 @@
+/**
+ * Telegram Integration for A3M Router
+ * Bot API for Telegram
+ */
+class TelegramIntegration {
+  constructor(botToken) {
+    this.botToken = botToken;
+    this.baseUrl = `https://api.telegram.org/bot${botToken}`;
+  }
+
+  async sendMessage(chatId, text) {
+    return { action: 'send-message', chatId, text: text.slice(0, 50) + '...' };
+  }
+
+  async getUpdates() {
+    return { action: 'get-updates' };
+  }
+}
+module.exports = { TelegramIntegration };

package/dist/providers/registry.js

@@ -7,8 +7,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProviderRegistry = void 0;
 const DEFAULT_PROVIDER_CONFIG = {
-    providers: ["openai", "openrouter", "groq", "cerebras", "mistral", "xai", "zai", "anthropic", "google"],
-    modelPriority: ["openai/gpt-4o", "groq/llama-3.3-70b-versatile", "cerebras/llama-3.3-70b"],
+    providers: ["openai", "openrouter", "groq", "cerebras", "mistral", "xai", "zai", "anthropic", "google", "deepseek", "fireworks", "perplexity", "cohere", "bedrock"],
+    modelPriority: ["openai/gpt-4o", "groq/llama-3.3-70b-versatile", "cerebras/llama-3.3-70b", "deepseek/deepseek-chat", "fireworks/mixtral-8x7b-instruct", "perplexity/sonar", "cohere/command-r-plus"],
     useOpenclawFallback: false,
     maxTokens: 4096,
 };
@@ -33,7 +33,11 @@ class ProviderRegistry {
             zai: { key: "ZAI_API_KEY", url: "ZAI_OPENAI_BASE_URL", mode: "anthropic" },
             anthropic: { key: "ANTHROPIC_API_KEY", url: "ANTHROPIC_BASE_URL", mode: "anthropic" },
             google: { key: "GOOGLE_API_KEY", url: "GOOGLE_GEMINI_BASE_URL", mode: "gemini" },
-        };
+            deepseek: { key: "DEEPSEEK_API_KEY", url: "DEEPSEEK_BASE_URL", mode: "openai" },
+            fireworks: { key: "FIREWORKS_API_KEY", url: "FIREWORKS_BASE_URL", mode: "openai" },
+            perplexity: { key: "PERPLEXITY_API_KEY", url: "PERPLEXITY_BASE_URL", mode: "openai" },
+            cohere: { key: "COHERE_API_KEY", url: "COHERE_BASE_URL", mode: "openai" },
+            bedrock: { key: "AWS_ACCESS_KEY_ID", url: "BEDROCK_BASE_URL", mode: "openai" },        };
         for (const [name, env] of Object.entries(envVars)) {
             const apiKey = process.env[env.key] || "";
             const baseUrl = process.env[env.url] || "";