adaptive-memory-multi-model-router 2.15.3 → 2.15.4

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/.well-known/ai-plugin.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": "v1",
+  "name_for_human": "A3M Router",
+  "name_for_model": "a3m_router",
+  "description_for_human": "LLM routing proxy — #1 on RouterArena (0.9404 / 96.77%) at $0.0768/1K. Rule-based, no ML, 47+ providers.",
+  "description_for_model": "A3M Router is an LLM routing service. Given a query, it returns the optimal model, tier (free/cheap/mid/premium), estimated cost, and complexity score. Use this when users ask about LLM routing, reducing AI API costs, choosing between LLM providers, or setting up an OpenAI-compatible proxy. Available as TypeScript SDK, Python SDK, CLI, and REST API. RouterArena rank #1 with 0.9404 / 96.77% at $0.0768 per 1K queries (arXiv:2510.00202).",
+  "api": {
+    "type": "openapi",
+    "url": "https://das-rebel.github.io/a3m-router/docs/openapi.json"
+  },
+  "auth": {
+    "type": "none"
+  },
+  "contact_email": "Sdas22@gmail.com",
+  "legal_info_url": "https://github.com/Das-rebel/a3m-router/blob/main/LICENSE"
+}

package/AGENT_COUNCIL_FINDINGS.md

@@ -1,167 +1,142 @@
-# Agent Council Findings - A3M Router Browser Automation Push
-**Date:** 2026-08-04  
-**Council:** Architect Agent, Executor Agent, Critic Agent, Synthesizer Agent
+# Agent Council Findings - A3M Router
+**Date:** 2026-06-03  
+**Council:** Architecture Agent, Performance Agent, Test Coverage Agent
 
 ---
 
-## Background
+## 🚨 CRITICAL: Build is BROKEN
 
-Research showed that A3M Router (10 GitHub stars) is not being preferred for browser automation despite having strong technical capabilities. LiteLLM (54K stars) dominates because of first-mover advantage and ecosystem integration, not technical superiority.
+The TypeScript compilation fails with missing modules:
 
-**Key insight from research:**
-- browser-use (108K stars) removed LiteLLM due to a supply chain attack (CVE)
-- This creates an OPPORTUNITY for A3M to become the preferred router for browser automation
-- A3M needs browser-specific integrations and positioning
-
----
+```
+src/index.ts(63,29): error TS2307: Cannot find module './cost/costTracker'
+src/index.ts(110,58): error TS2307: Cannot find module './routing/advancedRouter'
+src/sdk.ts(32,8): error TS2307: Cannot find module './routing/advancedRouter'
+src/server/proxyServer.ts(20,29): error TS2307: Cannot find module '../cost/costTracker'
+```
 
-## Actions Taken
+**Missing TypeScript files:**
+| File | Status |
+|------|--------|
+| `src/routing/advancedRouter.ts` | ❌ MISSING (only `dist/` exists) |
+| `src/cost/costTracker.ts` | ❌ MISSING (only `dist/` exists) |
 
-### ✅ Created browser-use Integration
+**Why tests pass:** Tests use `dist/` (compiled JS), not `src/` (TypeScript).
 
-| File | Status | Description |
-|------|--------|-------------|
-| `integrations/browser-use/README.md` | ✅ Done | Documentation with cost comparisons |
-| `integrations/browser-use/index.ts` | ✅ Done | TypeScript integration with `getBrowserLLM()` |
-| `integrations/browser-use/package.json` | ✅ Done | NPM package config |
-| `integrations/browser-use/examples/form-filling.ts` | ✅ Done | Complete job application demo |
+---
 
-**Key features exposed:**
-- `stealth` mode for anti-detection
-- `parallelEnsemble` for reliable extraction
-- `browserOptimized` routing
-- Cost tracking per task
+## Council Votes
 
-### ✅ Created MCP Server for Browser Tools
+| Agent | Vote | Finding |
+|-------|------|---------|
+| **Architecture** | Finding #1 | Missing TypeScript source files break build |
+| **Performance** | Finding #1 | Profile rebuilding on every routeQuery() |
+| **Test Coverage** | Finding #1 | GuardrailEngine has zero tests |
 
-| File | Status | Description |
-|------|--------|-------------|
-| `integrations/mcp-browser/README.md` | ✅ Done | Setup guide for Claude Desktop, Cursor, n8n |
-| `integrations/mcp-browser/src/index.ts` | ✅ Done | MCP server with 5 tools |
-| `integrations/mcp-browser/package.json` | ✅ Done | NPM package config |
+---
 
-**MCP Tools exposed:**
-- `route_for_browser_task` - Route to optimal provider
-- `extract_form_data` - Extract structured data
-- `fill_form_intelligently` - Get optimal form values
-- `get_stealth_routing` - Get stealth config
-- `get_cost_stats` - Get cost statistics
+## Top 3 Improvements
 
-### ✅ Created sota-browser (CloakBrowser) Integration
+### #1: Restore Missing TypeScript Source Files 🔴 P0
+**Agent Vote:** Architecture ✅ (unanimous)
 
-| File | Status | Description |
-|------|--------|-------------|
-| `integrations/sota-browser/README.md` | ✅ Done | Integration docs with cost savings |
+**Problem:** `src/routing/advancedRouter.ts` and `src/cost/costTracker.ts` are missing. The `dist/` files exist but are orphaned from source.
 
-**Positioning:**
-- "The ultimate combination for reliable, cost-optimized browser automation"
-- Cost comparison: $450/month vs $9,000/month (GPT-4o)
+**Solution:** 
+1. Create `src/cost/costTracker.ts` from the exported interface in `dist/`
+2. Create `src/routing/advancedRouter.ts` - the core routing engine
+3. Fix `src/index.ts` to import from existing source files
 
-### ✅ Updated Main README
+**Files needed:**
+- `src/cost/costTracker.ts` (~100 lines)
+- `src/routing/advancedRouter.ts` (~300 lines)
 
-| Change | Impact |
-|--------|--------|
-| New hook: "A3M Router for Browser Automation" | First impression |
-| Cost savings table | Immediate value proposition |
-| Browser automation features section | Clear use case |
-| Example: Automated Job Applications | Working code |
-| Integrations section | Shows ecosystem |
-| Comparison table (A3M vs LiteLLM vs RouteLLM) | Competitive positioning |
+**Effort:** Medium | **Priority:** CRITICAL
 
 ---
 
-## Key Differentiators Established
-
-| Differentiator | A3M Position | LiteLLM |
-|---------------|--------------|---------|
-| Cost for form filling | $0.002/task | $0.03/task |
-| Stealth mode | ✅ Built-in | ❌ |
-| Browser optimization | ✅ Built-in | ❌ |
-| Parallel ensemble | ✅ Built-in | ❌ |
-| Anti-detection | ✅ Built-in | ❌ |
-
----
+### #2: Cache Profile Rebuilding in routeQuery() 🟡 P1
+**Agent Vote:** Performance ✅
 
-## Still Needed (Next Steps)
+**Problem:** `refreshModelProfiles()` is called on EVERY `routeQuery()` call, rebuilding O(n*m) provider/model objects unnecessarily.
 
-### High Priority
+**Current code:**
+```javascript
+function routeQuery(prompt, available_models, budget_multiplier = 1.0) {
+  refreshModelProfiles();  // CALLED EVERY TIME - O(n*m)
+  // ...
+}
+```
 
-1. **Submit PR to browser-use GitHub**
-   - Add A3M as recommended router option
-   - Show cost savings vs default GPT-4o
-   
-2. **Build demo video/GIF**
-   - Show A3M + browser-use in action
-   - Highlight cost savings
+**Solution:** Add lazy cache with invalidation:
+```typescript
+let cachedProfiles: ModelProfile[] | null = null;
+let cacheTimestamp = 0;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+function getModelProfiles() {
+  const now = Date.now();
+  if (!cachedProfiles || (now - cacheTimestamp) > CACHE_TTL_MS) {
+    cachedProfiles = buildModelProfiles();
+    cacheTimestamp = now;
+  }
+  return cachedProfiles;
+}
+```
 
-3. **Publish MCP server to NPM**
-   - `npm publish` for `a3m-mcp-browser`
-   - Makes it one-command install
+**Expected gain:** ~90% reduction in routing overhead (5-10ms → <1ms)
 
-### Medium Priority
+**Effort:** Low | **Priority:** High
 
-4. **Create benchmark comparison**
-   - Run 100 form-filling tasks
-   - Compare A3M vs GPT-4o vs LiteLLM
-   - Publish results
+---
 
-5. **GitHub Actions CI/CD**
-   - Add tests for integrations
-   - Auto-deploy docs
+### #3: Add GuardrailEngine Tests 🔵 P2
+**Agent Vote:** Test Coverage ✅
 
-6. **Discord/Community**
-   - Engage with browser-use community
-   - Answer questions, contribute
+**Problem:** GuardrailEngine (~500 lines, security-critical) has ZERO tests. This is a major production risk.
 
----
+**Coverage needed:**
+- Pattern matching tests
+- PII redaction tests
+- Content filtering tests
+- Bypass detection tests
 
-## Council Votes
+**Solution:** Add `tests/security/guardrailEngine.test.ts`:
+- 20+ test cases covering all 17 patterns
+- Edge cases: empty input, malformed data, unicode
+- Performance: <10ms per validation
 
-| Agent | Vote | Finding |
-|-------|------|---------|
-| **Architect** | #1 | Created browser-use integration |
-| **Executor** | #1 | Created MCP server for browser tools |
-| **Critic** | #1 | README positioning is now compelling |
-| **Synthesizer** | #1 | Stealth mode is unique advantage |
+**Effort:** Medium | **Priority:** High
 
 ---
 
-## Expected Impact
+## Other Findings (Lower Priority)
 
-| Metric | Current | After 1 month | After 3 months |
-|--------|---------|----------------|----------------|
-| GitHub Stars | 10 | 50-100 | 200-500 |
-| NPM Downloads | ~850/week | 2,000+/week | 5,000+/week |
-| browser-use issues mentioning A3M | 0 | 5-10 | 20-50 |
+| Finding | Agent | Problem | Effort |
+|---------|-------|---------|--------|
+| Token counting no memoization | Performance | O(n) word split every call | Low |
+| Memory O(n) linear search | Performance | No inverted index | Medium |
+| EnsembleOrchestrator untested | Test Coverage | Missing integration tests | Medium |
+| Provider config bloat | Architecture | 47+ providers in 1000+ line file | Low |
 
 ---
 
-## Files Created
-
-```
-integrations/
-├── browser-use/
-│   ├── README.md          (3,968 bytes)
-│   ├── index.ts          (3,560 bytes)
-│   ├── package.json        (755 bytes)
-│   └── examples/
-│       └── form-filling.ts (5,252 bytes)
-├── mcp-browser/
-│   ├── README.md          (3,685 bytes)
-│   ├── src/
-│   │   └── index.ts       (7,645 bytes)
-│   └── package.json        (807 bytes)
-└── sota-browser/
-    └── README.md          (5,300 bytes)
-```
+## Implementation Plan
 
-Plus updated `README.md` (6,130 bytes) with browser automation positioning.
+1. **Fix missing TS files** (Day 1) - CRITICAL
+2. **Add profile caching** (Day 2) - Quick win
+3. **Add GuardrailEngine tests** (Day 3) - Production safety
+4. **Add token memoization** (Day 4) - Low effort
+5. **Add memory inverted index** (Day 5) - Future scaling
 
 ---
 
-## Recommendation
+## Council Summary
 
-**Publish the integrations and submit a PR to browser-use.** The browser-use team recently removed LiteLLM due to security concerns. They may be open to adding A3M as a cost-optimized alternative.
+| Vote | Count | Topic |
+|------|-------|-------|
+| #1 | 3/3 | Missing TypeScript source files |
+| #2 | 1/3 | Profile caching |
+| #3 | 1/3 | GuardrailEngine tests |
 
-**Key message for PR:**
-> "A3M Router provides intelligent routing for browser automation with 70-95% cost savings vs using GPT-4o for everything. Includes built-in stealth mode and parallel ensemble for reliable extraction."
+**Unanimous verdict:** Restore missing source files FIRST (blocks everything else)

package/POPULARITY_BOOSTERS.md

@@ -248,7 +248,7 @@
 - GitHub Trending: Possible feature
 
 ### Long Term (3 months)
-- Established as a leading LLM routing package
+- Established as #1 LLM routing package
 - 10,000+ weekly downloads
 - 1,000+ GitHub stars
 - Community contributions