adaptive-memory-multi-model-router 2.14.48 → 2.14.51

package/.dockerignore

@@ -0,0 +1,82 @@
+# =============================================================================
+# A3M Router — .dockerignore
+# Excludes unnecessary files from Docker build context for smaller images
+# =============================================================================
+
+# Dependencies (installed inside container)
+node_modules/
+
+# Git
+.git/
+.gitattributes
+.gitignore
+.github/
+
+# Build output (built inside container)
+dist/
+
+# Documentation (not needed at runtime)
+docs/
+docs-site/
+_*.md
+CONTRIBUTING.md
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+SECURITY.md
+LAUNCH*.md
+MANIFESTO.md
+LANDING.md
+POPULARITY_BOOSTERS.md
+SUBMISSIONS.md
+
+# Research / articles
+articles/
+awesome-ai-gateways/
+Awesome-LLM/
+awesome-selfhosted/
+qna/
+llms-full.txt
+llms.txt
+
+# Demos / playground
+demo/
+playground/
+demo*.tape
+demo*.sh
+demo.html
+index.html
+
+# Tests
+test/
+test*
+pytest.ini
+__pycache__/
+*.py[cod]
+.pytest_cache/
+
+# Scripts / tooling
+scripts/
+eval/
+integrations/
+mcp-server/
+tmlpd-pi-extension/
+openclaw-alexa-bridge/
+python/
+skill/
+hf-space/
+
+# Config & secrets (use container env vars)
+.env
+.env.example
+tsconfig.json
+tsconfig.build.json
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs / temp
+*.log
+*.tsbuildinfo
+*.bak
+coverage/

package/.env.example

@@ -0,0 +1,303 @@
+# =============================================================================
+# A3M Router - Adaptive Memory Multi-Model Router
+# Environment Configuration Template
+# =============================================================================
+#
+# Copy this file to .env and fill in your API keys.
+# At least one provider key is required for the router to function.
+# Providers without keys are automatically skipped at runtime.
+#
+# Usage:
+#   cp .env.example .env
+#   # Edit .env with your keys
+#   a3m-router start
+#
+# =============================================================================
+
+# =============================================================================
+# SECTION 1: PRIMARY PROVIDERS (Frontier / Most Commonly Used)
+# =============================================================================
+
+# OpenAI — GPT-4o, GPT-4o-mini, o1, o3, etc.
+# https://platform.openai.com/api-keys
+OPENAI_API_KEY=sk-...
+
+# Anthropic — Claude Sonnet 4, Opus, Haiku
+# https://console.anthropic.com/
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Google / Gemini — Gemini 2.5 Flash/Pro, Gemma
+# https://aistudio.google.com/apikey
+GOOGLE_API_KEY=...
+
+# xAI — Grok-3, Grok-3-mini, Grok-2
+# https://console.x.ai
+XAI_API_KEY=...
+
+# =============================================================================
+# SECTION 2: FAST INFERENCE PROVIDERS (Cheap / Low-Latency)
+# =============================================================================
+
+# Groq — LPU-powered inference, very fast
+# https://console.groq.com/keys
+GROQ_API_KEY=gsk_...
+
+# Cerebras — Wafer-scale inference, ultra-fast
+# https://cloud.cerebras.ai/
+CEREBRAS_API_KEY=...
+
+# DeepInfra — Serverless inference, many open models
+# https://deepinfra.com/dash/api_keys
+DEEPINFRA_API_KEY=...
+
+# Together AI — Hosted open-source models
+# https://api.together.ai/settings/api-keys
+TOGETHER_API_KEY=...
+
+# Fireworks AI — Fast inference for open models
+# https://fireworks.ai/api-keys
+FIREWORKS_API_KEY=...
+
+# Novita AI — Low-cost LLM inference
+# https://novita.ai/settings
+NOVITA_API_KEY=...
+
+# SambaNova — Fast open-model inference
+# https://cloud.sambanova.ai/
+SAMBANOVA_API_KEY=...
+
+# Anyscale — Endpoints for open models
+# https://console.anyscale.com/
+ANYSCALE_API_KEY=...
+
+# =============================================================================
+# SECTION 3: MID-TIER / SPECIALTY PROVIDERS
+# =============================================================================
+
+# DeepSeek — DeepSeek-V3, DeepSeek-R1
+# https://platform.deepseek.com/api_keys
+DEEPSEEK_API_KEY=...
+
+# Mistral AI — Mistral Large, Small, Codestral, Ministral
+# https://console.mistral.ai/api-keys
+MISTRAL_API_KEY=...
+
+# Perplexity — Sonar models with online search
+# https://www.perplexity.ai/settings/api
+PERPLEXITY_API_KEY=...
+
+# Cohere — Command R+, Command A, embeddings
+# https://dashboard.cohere.com/api-keys
+COHERE_API_KEY=...
+
+# AI21 Labs — Jamba 1.5 models
+# https://studio.ai21.com/account/api-keys
+AI21_API_KEY=...
+
+# Replicate — Cloud for open-source models
+# https://replicate.com/account/api-tokens
+REPLICATE_API_KEY=...
+
+# Hugging Face — Inference API, Inference Endpoints
+# https://huggingface.co/settings/tokens
+HUGGINGFACE_API_KEY=hf_...
+# or use HF_API_TOKEN
+HF_API_TOKEN=hf_...
+
+# Writer — Palmyra models, full-stack AI platform
+# https://dev.writer.com/
+WRITER_API_KEY=...
+
+# OctoAI — Fast inference for open and custom models
+# https://octo.ai/
+OCTOAI_API_KEY=...
+
+# =============================================================================
+# SECTION 4: AI AGGREGATORS & ROUTERS
+# =============================================================================
+
+# OpenRouter — Aggregator with 200+ models, passthrough pricing
+# https://openrouter.ai/keys
+OPENROUTER_API_KEY=...
+
+# AI/ML API — Single API for 200+ models
+# https://aimlapi.com/
+AIMLAPI_KEY=...
+
+# =============================================================================
+# SECTION 5: ENTERPRISE CLOUD PROVIDERS
+# =============================================================================
+
+# Azure OpenAI — GPT models via Azure
+# https://portal.azure.com/
+AZURE_OPENAI_API_KEY=...
+# Also requires your Azure endpoint
+AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
+
+# AWS Bedrock — Claude, Llama, Mistral via AWS
+# https://console.aws.amazon.com/bedrock/
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+# Optional: set default region
+AWS_REGION=us-east-1
+
+# Google Vertex AI — Gemini, Claude via GCP
+# https://console.cloud.google.com/vertex-ai
+# Path to service account JSON key file
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
+
+# IBM watsonx — Granite, Llama, Mistral on IBM Cloud
+# https://cloud.ibm.com/watsonx
+WATSONX_API_KEY=...
+WATSONX_PROJECT_ID=...
+WATSONX_URL=https://us-south.ml.cloud.ibm.com
+
+# Cloudflare Workers AI — Serverless AI inference
+# https://dash.cloudflare.com/profile/api-tokens
+CLOUDFLARE_API_TOKEN=...
+CLOUDFLARE_ACCOUNT_ID=...
+
+# =============================================================================
+# SECTION 6: NVIDIA PLATFORMS
+# =============================================================================
+
+# NVIDIA NIM / API Catalog — Free tier for many open models
+# https://build.nvidia.com/
+NVIDIA_API_KEY=nvapi-...
+
+# NVIDIA AI Foundation — Endpoints for NeMo, Llama, etc.
+# Also uses NVIDIA_API_KEY above
+
+# =============================================================================
+# SECTION 7: CHINESE / ASIAN PROVIDERS
+# =============================================================================
+
+# Zhipu AI (GLM) — GLM-4 series
+# https://open.bigmodel.cn/usercenter/apikeys
+ZHIPU_API_KEY=...
+
+# Alibaba Qwen (DashScope) — Qwen-Max, Qwen-Plus, Qwen-Turbo
+# https://dashscope.console.aliyun.com/
+DASHSCOPE_API_KEY=...
+
+# Moonshot AI (Kimi) — Long-context models (128K)
+# https://platform.moonshot.cn/
+MOONSHOT_API_KEY=...
+
+# 01.AI (Yi) — Yi-Lightning, Yi-Large, Yi-Medium
+# https://platform.lingyiwanwu.com/
+YI_API_KEY=...
+
+# Baichuan AI — Baichuan4, Baichuan3-Turbo
+# https://platform.baichuan-ai.com/
+BAICHUAN_API_KEY=...
+
+# MiniMax — MiniMax-Text-01, abab models
+# https://platform.minimax.chat/
+MINIMAX_API_KEY=...
+
+# StepFun (Step) — Step-1, Step-2 models
+# https://platform.stepfun.com/
+STEPFUN_API_KEY=...
+
+# ByteDance (Doubao) — Doubao-pro, Doubao-lite
+# https://console.volcengine.com/ark
+ARK_API_KEY=...
+
+# Tencent (Hunyuan) — Hunyuan large models
+# https://console.cloud.tencent.com/hunyuan
+TENCENT_API_KEY=...
+
+# Baidu (ERNIE) — ERNIE 4.0, ERNIE-Bot
+# https://console.bce.baidu.com/qianfan/
+BAIDU_API_KEY=...
+BAIDU_SECRET_KEY=...
+
+# =============================================================================
+# SECTION 8: EUROPEAN & PRIVACY-FOCUSED PROVIDERS
+# =============================================================================
+
+# Aleph Alpha — Luminous models (GDPR-compliant)
+# https://www.aleph-alpha.com/
+ALEPH_ALPHA_API_KEY=...
+
+# Deepset — Haystack Cloud, model endpoints
+# https://cloud.deepset.ai/
+DEEPSET_API_KEY=...
+
+# Lepton AI — Fast, affordable inference
+# https://lepton.ai/
+LEPTON_API_KEY=...
+
+# Mistral AI (also listed above, European-based)
+# MISTRAL_API_KEY=...
+
+# =============================================================================
+# SECTION 9: EMBEDDINGS & SPECIALTY PROVIDERS
+# =============================================================================
+
+# Jina AI — Embeddings, Reranker, Reader API
+# https://jina.ai/
+JINA_API_KEY=...
+
+# Voyage AI — Specialized embedding models
+# https://www.voyageai.com/
+VOYAGE_API_KEY=...
+
+# Cohere (also listed above — embeddings + generation)
+# COHERE_API_KEY=...
+
+# Deepgram — Speech-to-text, text-to-speech, LLM (Nova-2)
+# https://console.deepgram.com/
+DEEPGRAM_API_KEY=...
+
+# =============================================================================
+# SECTION 10: ADDITIONAL / EMERGING PROVIDERS
+# =============================================================================
+
+# GooseAI — API for open models (deprecated but still supported)
+GOOSEAI_API_KEY=...
+
+# aiXcoder — Code-specialized LLM API
+AIXCODER_API_KEY=...
+
+# Infinity — Embedding serving (self-hosted)
+INFINITY_API_KEY=...
+
+# Laminar — LLM observability + routing
+LAMINAR_API_KEY=...
+
+# Fireworks (also listed above)
+# FIREWORKS_API_KEY=...
+
+# CommandCode — Coding agent API
+COMMANDCODE_API_KEY=...
+
+# =============================================================================
+# SECTION 11: LOCAL / SELF-HOSTED (No API keys needed)
+# =============================================================================
+#
+# These run locally and require no environment variables:
+#
+# Ollama           — http://127.0.0.1:11434      (no key)
+# LM Studio        — http://127.0.0.1:1234       (no key)
+# vLLM (local)     — http://127.0.0.1:8000       (no key)
+# LocalAI          — http://127.0.0.1:8080       (no key)
+# llama.cpp server — http://127.0.0.1:8080       (no key)
+# Text Generation Inference (TGI) — http://127.0.0.1:8080 (no key)
+#
+# =============================================================================
+
+# =============================================================================
+# SECTION 12: SERVER CONFIGURATION
+# =============================================================================
+
+# Port and host for the A3M Router proxy server
+PORT=3000
+HOST=0.0.0.0
+
+# Optional: API key required to access the router itself
+# A3M_API_KEY=router-secret-key
+
+# Logging level: debug | info | warn | error
+LOG_LEVEL=info

package/.github/DISCUSSIONS_WELCOME.md

@@ -0,0 +1,27 @@
+# Welcome to A3M Router Discussions!
+
+## 🎯 What is A3M Router?
+A3M Router is an open-source LLM router that runs queries across **47+ providers in parallel**, scores responses by confidence, and returns the best result. No sequential fallback. No vendor lock-in.
+
+## 💬 Discussion Categories
+- **Show and Tell** — Share what you've built with A3M Router
+- **Q&A** — Ask questions about usage, configuration, deployment
+- **Ideas** — Feature requests and suggestions
+- **Announcements** — Release notes and updates
+
+## 🔗 Quick Links
+- [GitHub](https://github.com/Das-rebel/a3m-router)
+- [npm](https://www.npmjs.com/package/adaptive-memory-multi-model-router)
+- [Documentation](https://github.com/Das-rebel/a3m-router#readme)
+- [Benchmark Results](https://github.com/Das-rebel/a3m-router/blob/main/docs/BENCHMARK.md)
+
+## 🚀 Getting Started
+```bash
+npx a3m-router "What is the meaning of life?"
+```
+
+Or install globally:
+```bash
+npm install -g adaptive-memory-multi-model-router
+a3m "Explain quantum computing in simple terms"
+```

package/.github/DISCUSSION_TEMPLATE.yml

@@ -0,0 +1,5 @@
+labels:
+  - show-and-tell
+  - q-a
+  - ideas
+  - announcements

package/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+# These are supported funding model platforms
+github: Das-rebel

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,94 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior to help us improve A3M Router
+title: "[Bug] "
+labels: bug, needs-triage
+assignees: ""
+---
+
+## Description
+
+A clear and concise description of the bug.
+
+## Reproduction Steps
+
+Steps to reproduce the behavior:
+
+```bash
+# 1. Set up (if applicable)
+export PROVIDER_API_KEY=sk-...
+
+# 2. Run
+npx a3m-router route "Your query here"
+```
+
+If using the SDK, provide a minimal code snippet:
+
+```typescript
+import { A3MRouter } from "adaptive-memory-multi-model-router";
+
+const router = new A3MRouter({ /* your config */ });
+const result = await router.route("Your query");
+```
+
+## Expected Behavior
+
+What did you expect to happen?
+
+## Actual Behavior
+
+What actually happened? Include error messages, stack traces, or unexpected output.
+
+```
+Paste error output or logs here
+```
+
+## A3M Router Version
+
+- Package: `adaptive-memory-multi-model-router@<version>` (run `npm list adaptive-memory-multi-model-router`)
+- CLI version (if applicable): `npx a3m-router --version`
+
+## Environment
+
+- **OS:** macOS / Linux / Windows
+- **Node.js version:** (run `node --version`)
+- **npm version:** (run `npm --version`)
+- **Python version (if using Python SDK):** (run `python --version`)
+
+## Providers Used
+
+Which provider(s) were involved? (e.g., Groq, OpenAI, Anthropic, NVIDIA, DeepSeek, custom)
+
+## Configuration
+
+Attach or describe relevant config (redact API keys):
+
+```json
+{
+  "providers": { ... },
+  "routing": { ... },
+  "budgets": { ... }
+}
+```
+
+## Logs
+
+If you ran with `DEBUG=*` or `LOG_LEVEL=debug`, include relevant log lines:
+
+```
+[DEBUG] Routing query...
+[ERROR] Provider groq returned 503
+```
+
+## Additional Context
+
+- Does this happen consistently or intermittently?
+- Does it affect all providers or a specific one?
+- Did it work in a previous version? If so, which version?
+- Any recent changes to your setup?
+
+## Checklist
+
+- [ ] I have searched existing issues for duplicates
+- [ ] I have redacted all API keys and secrets from the above
+- [ ] I can reliably reproduce this bug

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,17 @@
+blank_issues_enabled: false
+contact_links:
+  - name: "\U0001F4D6 Documentation & Quick Start"
+    url: https://github.com/Das-rebel/a3m-router#readme
+    about: Check the README for setup, SDK usage, API reference, and configuration examples
+  - name: "\U0001F4AC Discussions & Community"
+    url: https://github.com/Das-rebel/a3m-router/discussions
+    about: Ask questions, share ideas, show what you've built, and get help from the community
+  - name: "\U0001F680 NPM Package"
+    url: https://www.npmjs.com/package/adaptive-memory-multi-model-router
+    about: View package details, version history, and download statistics
+  - name: "\U0001F4DC Changelog"
+    url: https://github.com/Das-rebel/a3m-router/blob/main/CHANGELOG.md
+    about: See what's changed in recent releases
+  - name: "\U0001F6A8 Security"
+    url: https://github.com/Das-rebel/a3m-router/security/policy
+    about: Report security vulnerabilities privately

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,71 @@
+---
+name: Feature Request
+about: Suggest an idea or enhancement for A3M Router
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem Statement
+
+A clear description of the problem you're trying to solve. What gap or pain point does this feature address?
+
+**Example:** "Currently, A3M Router doesn't support routing based on response language. When I send multilingual queries, I want them routed to providers that perform best in that language."
+
+## Proposed Solution
+
+Describe the feature you'd like to see. Be as specific as possible about behavior, configuration, and API.
+
+```typescript
+// If applicable, sketch the API you envision
+const router = new A3MRouter({
+  languageRouting: {
+    enabled: true,
+    defaultProvider: "openai",
+    languageOverrides: {
+      ja: "anthropic",
+      zh: "deepseek",
+    },
+  },
+});
+```
+
+## Use Case
+
+Describe the real-world scenario that would benefit from this feature.
+
+- Who is the target user? (e.g., solo developer, enterprise team, researcher)
+- What workflow does it enable or simplify?
+- How frequently would this be used?
+
+## Alternatives Considered
+
+List any workarounds or alternative approaches you've explored:
+
+1. Manual provider selection per query
+2. Custom wrapper script
+3. Forking and modifying the router
+4. Using a different tool altogether
+
+Explain why these are insufficient.
+
+## Priority
+
+How important is this to you?
+
+- [ ] **Blocking** — Cannot proceed without this feature
+- [ ] **High** — Important for my workflow
+- [ ] **Medium** — Nice to have
+- [ ] **Low** — Interesting idea, not urgent
+
+## Would You Implement It?
+
+- [ ] **Yes** — I can submit a PR (with guidance)
+- [ ] **Maybe** — Willing to help test or provide requirements
+- [ ] **No** — Just suggesting
+
+## Additional Context
+
+- Links to related discussions, issues, or external references
+- Screenshots or mockups (if applicable)
+- Any constraints or requirements (e.g., must work offline, must not increase bundle size)

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,71 @@
+## Description
+
+Please include a summary of the change and which issue it fixes. Explain the motivation and context — what problem does this solve and why is this the right approach?
+
+Fixes # (issue)
+
+## Type of Change
+
+Check all that apply:
+
+- [ ] 🐛 **Bug fix** (non-breaking change that fixes an issue)
+- [ ] ✨ **New feature** (non-breaking change that adds functionality)
+- [ ] 💥 **Breaking change** (fix or feature that would break existing functionality)
+- [ ] 📚 **Documentation** (README, API docs, inline comments, or examples)
+- [ ] 🎨 **Style** (formatting, code style — no logic change)
+- [ ] ⚡ **Performance** (improves speed, memory, or latency without behavior change)
+- [ ] 🔒 **Security** (fixes a vulnerability or improves security posture)
+- [ ] ♻️ **Refactor** (code change that neither fixes a bug nor adds a feature)
+- [ ] 🧪 **Tests** (adds or updates tests, not production code)
+
+## Testing
+
+Describe the tests you ran to verify your changes:
+
+- [ ] All existing tests pass (`npm test`)
+- [ ] Added new tests for the changes
+- [ ] Tested manually (describe the commands or SDK calls used)
+- [ ] Tested with real provider API calls (if applicable)
+
+```bash
+# Provide commands to reproduce your testing
+node test/some-test.js
+npx a3m-router route "Test query"
+```
+
+## Checklist
+
+- [ ] My code follows the project's coding style and conventions
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented complex logic, especially in hard-to-understand areas
+- [ ] I have updated the documentation (README, API docs, JSDoc comments) if needed
+- [ ] My changes produce no new warnings (no `console.log` left behind, no TypeScript errors)
+- [ ] I have added tests that prove my fix is effective or my feature works
+- [ ] New and existing unit tests pass locally
+- [ ] Any dependent changes are merged and published in downstream modules
+- [ ] I have checked that my changes are backward-compatible (or documented breaking changes)
+
+## Screenshots (if applicable)
+
+If the change affects the terminal UI, dashboard, or any visual output, include screenshots:
+
+| Before | After |
+|--------|-------|
+| _screenshot_ | _screenshot_ |
+
+## Additional Context
+
+- Related issues or PRs
+- Performance impact (latency, memory, bundle size)
+- Configuration changes required
+- Migration guide (if breaking change)
+
+## Changelog Entry
+
+Suggest a one-line changelog entry for this change:
+
+```
+- {type}: {short description} ({issue/PR link})
+```
+
+Example: `- feat: add language-based routing override (#42)`

package/.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"