adaptive-memory-multi-model-router 2.16.3 → 2.16.4

package/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for all files
+* @Das-rebel

package/.github/FUNDING.yml

@@ -1,2 +1,8 @@
-# These are supported funding model platforms
 github: Das-rebel
+patreon: # Replace with a Patreon username
+ko_fi: # Replace with a Ko-fi username
+tidelift: npm/adaptive-memory-multi-model-router
+community_bridge: # Replace with Community Bridge project slug e.g. lightning
+liberapay: # Replace with Liberapay username
+open_collective: # Replace with Open Collective username
+custom: ["https://opencollective.com/a3m-router"]

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,56 @@
+---
+name: 🐛 Bug Report
+about: Something isn't working as expected
+title: "[Bug] "
+labels: bug
+assignees: ''
+---
+
+## Description
+
+A clear description of the bug. What did you expect vs what actually happened?
+
+## Steps to Reproduce
+
+1. Go to '...'
+2. Run `...`
+3. See error
+
+```bash
+# Paste relevant command output
+npx a3m-router route "..."
+node test.js
+```
+
+## Expected Behavior
+
+What should happen.
+
+## Actual Behavior
+
+What actually happens — include error messages, stack traces.
+
+## Environment
+
+- **OS**: (e.g., macOS 14, Ubuntu 24.04)
+- **Node.js version**: (e.g., 22.x)
+- **a3m-router version**: (e.g., 2.16.3 — run `npm show adaptive-memory-multi-model-router version`)
+- **Provider**: (which provider were you routing to?)
+
+## Relevant Logs
+
+```log
+# paste relevant log output here
+```
+
+## Additional Context
+
+Anything else that might help diagnose the issue.
+
+## Changelog Entry
+
+One-liner for the changelog (if this bug fix is worth noting):
+
+```
+- fix: short description
+```

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,41 @@
+---
+name: ✨ Feature Request
+about: Suggest a new capability
+title: "[Feature] "
+labels: enhancement
+assignees: ''
+---
+
+## Problem or Opportunity
+
+Describe the problem you're trying to solve, or the gap in the current capability.
+
+## Proposed Solution
+
+Describe your proposed solution. Include code sketches if relevant.
+
+```typescript
+// How the API might look
+const result = router.route({
+  model: "auto",
+  // new option described here
+})
+```
+
+## Alternatives Considered
+
+What other approaches did you consider and why did you reject them?
+
+## Additional Context
+
+- Related discussions, issues, or PRs
+- Would this break backward compatibility?
+- Any dependencies or provider requirements?
+
+## Changelog Entry
+
+One-liner for the changelog:
+
+```
+- feat: short description
+```

package/.github/workflows/pages.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: '.'
+          path: 'docs'
           
       - name: Deploy to GitHub Pages
         id: deployment

package/CHANGELOG.md

@@ -2,17 +2,24 @@
 
 ## [Unreleased]
 
+## [2.16.3] — 2026-09-19
+
 ### Added
-- Docker + docker-compose deployment
-- MCP server for AI agent integration
-- LangChain LLM integration with A3M Router
-- Gradio demo on HuggingFace Space
-- GitHub Pages documentation site
-- CI/CD badges and community health files
-- Posting directory with 30+ platforms for A3M discovery
+- **`model="jev-auto"`** — System One single-pass routing head: option-attention engine in pure TypeScript, zero extra dependencies, ~2ms warm latency, 97.8% agreement with heuristic router, calibrated per-choice probabilities, dynamic option sets for unseen providers, confidence guard (p<0.22 auto-fallback)
+- `npm run jev:distill` + `npm run jev:train` pipeline — distills training data and trains the Jev decision head from real traffic
+- Remote Jev backend support via `A3M_JEV_URL` env var (openjev-sglang or api.typesafe.ai)
+- imprint Jev head (Python/numpy, ~0.5ms/decision) — gates cascade compression, cross-compatible weights with a3m-router
+
+### Fixed
+- CI `npm ci` failure: restored `package-lock.json` (deleted by git add -A in da2ae95)
+- CI MODULE_NOT_FOUND: force-tracked `dist/routing/jev/` (was gitignored but needed for CI's node test.js against committed dist)
+- Lazy guarded import in modelMapper.ts — graceful fallback when jev weights unavailable
+- Repo About description: removed circular "DEPRECATED → adaptive-memory-multi-model-router" (repo redirects to itself)
 
 ### Changed
-- Cleanup removed 4 unused deps, fixed 0 vulns, deduplicated
+- `dist/` Jev files now properly tracked for CI compatibility
+- README restructured: TOC, architecture diagram, prominent Jev feature section, cleaner quick-start flow
+- CONTRIBUTING.md rewritten with real project structure, test commands, PR checklist
 
 ## [2.16.0] — 2026-08-12
 

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to A3M Router
 
-Thanks for helping build the fastest-growing open-source LLM router! 🚀
+Thanks for helping build the open-source LLM router! 🚀
 
 ## Quick Setup
 
@@ -11,40 +11,124 @@ npm install
 npm run build
 ```
 
+## Running Tests
+
+```bash
+# All tests
+npm test                    # or: npx vitest run tests/
+
+# Routing engine tests
+npx vitest run tests/routing/
+
+# Jev engine tests
+npx vitest run tests/routing/jev.test.ts
+
+# Provider tests
+node test/provider-test.js
+
+# Quick smoke test
+node test.js
+```
+
 ## Project Structure
 
 ```
 src/
-├── providers/     # 47+ LLM provider configurations
-├── routing/       # UCB1 + MCTS routing engine
-├── cache/         # Semantic deduplication cache
-├── proxy/         # OpenAI-compatible proxy server
-└── tui/           # Terminal UI overlay
+├── routing/
+│   ├── advancedRouter.ts    # Main heuristic router (System 2)
+│   ├── jev/                 # Jev System One decision head
+│   │   ├── jevRouter.ts     # Entry point
+│   │   ├── optionAttention.ts # Single-pass option-attention math
+│   │   ├── weights/          # Trained weights (git-tracked dist/)
+│   │   └── types.ts
+│   └── routeQuery.ts        # Provider scoring + selection
+├── providers/
+│   └── providerConfig.ts   # 80+ provider configs + tier definitions
+├── server/
+│   ├── modelMapper.ts      # model="auto" / model="jev-auto" dispatcher
+│   └── proxyServer.ts      # OpenAI-compatible proxy server
+├── cache/
+│   └── semanticCache.ts    # Embedding-based deduplication
+└── cli.ts                  # CLI entry point
+
+tests/
+├── routing/jev.test.ts      # Jev engine unit tests
+├── routing/advancedRouter.test.ts
+└── integration/
 ```
 
-## Development
+## Adding a New Provider
 
-```bash
-npm run build      # Compile TypeScript
-npm test           # Run tests
-node dist/tui/dashboard.js  # Launch TUI
-```
+1. Add the provider config to `src/providers/providerConfig.ts`:
+   ```typescript
+   export const MY_PROVIDER: Provider = {
+     name: "my-provider",
+     apiKeyEnvVar: "MY_PROVIDER_API_KEY",
+     endpoint: "https://api.my-provider.ai/v1",
+     supports: ["chat", "Completions"],
+     tier: "cheap",  // free | cheap | mid | premium
+     region: "us-east",
+   };
+   ```
+
+2. Add to the provider registry:
+   ```typescript
+   export const PROVIDERS: Record<string, Provider> = {
+     // ...existing
+     "my-provider": MY_PROVIDER,
+   };
+   ```
+
+3. Run tests:
+   ```bash
+   node test/provider-test.js   # basic connectivity
+   npx a3m-router providers list  # verify it appears
+   ```
+
+## Adding a Routing Engine (e.g., a new Jev variant)
+
+1. Create `src/routing/myEngine/`
+2. Implement the engine interface:
+   ```typescript
+   export interface RouteResult {
+     primary_model: string;     // "provider/model-name"
+     confidence: number;        // 0–1
+    备选?: string;            // fallback provider/model
+   }
+   export function routeQuery(prompt: string): RouteResult { ... }
+   ```
+3. Wire it into `src/server/modelMapper.ts` under the new model name
+4. Add tests in `tests/routing/myEngine.test.ts`
+5. Document in this README under "Two Routing Modes"
 
-## PR Guidelines
+## Code Style
+
+- **TypeScript strict mode** — no `any`, full type coverage
+- **ES2022** target, CommonJS output
+- 2-space indent, single quotes
+- Run `npx tsc --noEmit` before committing
+
+## Commit Conventions
+
+```
+feat(provider): add Cloudflare Workers AI support
+fix(jev): guard against empty option set
+chore: bump vitest to 3.x
+docs: rewrite Quick Start section
+```
 
-- Keep the package under 20KB (no ML deps)
-- Add provider configs in `src/providers/`
-- Route logic in `src/routing/`
-- TUI changes in `src/tui/`
-- Update CHANGELOG.md
+## Pull Request Checklist
 
-## Adding a Provider
+- [ ] `npm run build` passes locally
+- [ ] `npx vitest run tests/` — all tests green
+- [ ] `node test.js` — smoke test passes
+- [ ] New provider/engine has tests
+- [ ] README updated if adding new features
 
-1. Add config in `src/providers/providerConfig.ts`
-2. Set tier: `free` / `cheap` / `mid` / `premium`
-3. Add to `PROVIDER_TIERS` map
-4. PR with latency benchmarks
+---
 
-## Questions?
+## Getting Help
 
-Open an issue or reach out on [GitHub Discussions](https://github.com/Das-rebel/a3m-router/discussions).
+- 💬 [GitHub Discussions](https://github.com/Das-rebel/a3m-router/discussions)
+- 🐛 [Issue Tracker](https://github.com/Das-rebel/a3m-router/issues)
+- 📖 [docs/](docs/) for architecture and API reference