Skip to content

Commit f2c9199

Browse files
Das-rebelDas-rebel
committed
chore: clean up repo usability
README: rewrite with TOC, architecture diagram, prominent Jev feature section, tighter quick-start CONTRIBUTING: full project structure, test commands, PR checklist, provider/engine addition guide CHANGELOG: add v2.16.3 entry (Jev System One, CI fixes, lazy import) FUNDING.yml: GitHub Sponsors + Open Collective CODEOWNERS: default to Das-rebel .github/ISSUE_TEMPLATE: bug report + feature request templates .archive root: move 30+ outdated campaign/launch/research files to archive/ - archive/launch/ (8 files) - archive/research/ (5 files) - archive/campaign/ (5 files) - archive/submissions/ (6 files) - archive/ (7 files)
1 parent a7aadbb commit f2c9199

37 files changed

Lines changed: 376 additions & 243 deletions

‎.github/CODEOWNERS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Default owner for all files
2+
* @Das-rebel

‎.github/FUNDING.yml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,8 @@
1-
# These are supported funding model platforms
21
github: Das-rebel
2+
patreon: # Replace with a Patreon username
3+
ko_fi: # Replace with a Ko-fi username
4+
tidelift: npm/adaptive-memory-multi-model-router
5+
community_bridge: # Replace with Community Bridge project slug e.g. lightning
6+
liberapay: # Replace with Liberapay username
7+
open_collective: # Replace with Open Collective username
8+
custom: ["https://opencollective.com/a3m-router"]

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
name: 🐛 Bug Report
3+
about: Something isn't working as expected
4+
title: "[Bug] "
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
## Description
10+
11+
A clear description of the bug. What did you expect vs what actually happened?
12+
13+
## Steps to Reproduce
14+
15+
1. Go to '...'
16+
2. Run `...`
17+
3. See error
18+
19+
```bash
20+
# Paste relevant command output
21+
npx a3m-router route "..."
22+
node test.js
23+
```
24+
25+
## Expected Behavior
26+
27+
What should happen.
28+
29+
## Actual Behavior
30+
31+
What actually happens — include error messages, stack traces.
32+
33+
## Environment
34+
35+
- **OS**: (e.g., macOS 14, Ubuntu 24.04)
36+
- **Node.js version**: (e.g., 22.x)
37+
- **a3m-router version**: (e.g., 2.16.3 — run `npm show adaptive-memory-multi-model-router version`)
38+
- **Provider**: (which provider were you routing to?)
39+
40+
## Relevant Logs
41+
42+
```log
43+
# paste relevant log output here
44+
```
45+
46+
## Additional Context
47+
48+
Anything else that might help diagnose the issue.
49+
50+
## Changelog Entry
51+
52+
One-liner for the changelog (if this bug fix is worth noting):
53+
54+
```
55+
- fix: short description
56+
```

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
name: ✨ Feature Request
3+
about: Suggest a new capability
4+
title: "[Feature] "
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
## Problem or Opportunity
10+
11+
Describe the problem you're trying to solve, or the gap in the current capability.
12+
13+
## Proposed Solution
14+
15+
Describe your proposed solution. Include code sketches if relevant.
16+
17+
```typescript
18+
// How the API might look
19+
const result = router.route({
20+
model: "auto",
21+
// new option described here
22+
})
23+
```
24+
25+
## Alternatives Considered
26+
27+
What other approaches did you consider and why did you reject them?
28+
29+
## Additional Context
30+
31+
- Related discussions, issues, or PRs
32+
- Would this break backward compatibility?
33+
- Any dependencies or provider requirements?
34+
35+
## Changelog Entry
36+
37+
One-liner for the changelog:
38+
39+
```
40+
- feat: short description
41+
```

‎CHANGELOG.md‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,24 @@
22

33
## [Unreleased]
44

5+
## [2.16.3] — 2026-09-19
6+
57
### Added
6-
- Docker + docker-compose deployment
7-
- MCP server for AI agent integration
8-
- LangChain LLM integration with A3M Router
9-
- Gradio demo on HuggingFace Space
10-
- GitHub Pages documentation site
11-
- CI/CD badges and community health files
12-
- Posting directory with 30+ platforms for A3M discovery
8+
- **`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)
9+
- `npm run jev:distill` + `npm run jev:train` pipeline — distills training data and trains the Jev decision head from real traffic
10+
- Remote Jev backend support via `A3M_JEV_URL` env var (openjev-sglang or api.typesafe.ai)
11+
- imprint Jev head (Python/numpy, ~0.5ms/decision) — gates cascade compression, cross-compatible weights with a3m-router
12+
13+
### Fixed
14+
- CI `npm ci` failure: restored `package-lock.json` (deleted by git add -A in da2ae95)
15+
- CI MODULE_NOT_FOUND: force-tracked `dist/routing/jev/` (was gitignored but needed for CI's node test.js against committed dist)
16+
- Lazy guarded import in modelMapper.ts — graceful fallback when jev weights unavailable
17+
- Repo About description: removed circular "DEPRECATED → adaptive-memory-multi-model-router" (repo redirects to itself)
1318

1419
### Changed
15-
- Cleanup removed 4 unused deps, fixed 0 vulns, deduplicated
20+
- `dist/` Jev files now properly tracked for CI compatibility
21+
- README restructured: TOC, architecture diagram, prominent Jev feature section, cleaner quick-start flow
22+
- CONTRIBUTING.md rewritten with real project structure, test commands, PR checklist
1623

1724
## [2.16.0] — 2026-08-12
1825

‎CONTRIBUTING.md‎

Lines changed: 109 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Contributing to A3M Router
22

3-
Thanks for helping build the fastest-growing open-source LLM router! 🚀
3+
Thanks for helping build the open-source LLM router! 🚀
44

55
## Quick Setup
66

@@ -11,40 +11,124 @@ npm install
1111
npm run build
1212
```
1313

14+
## Running Tests
15+
16+
```bash
17+
# All tests
18+
npm test # or: npx vitest run tests/
19+
20+
# Routing engine tests
21+
npx vitest run tests/routing/
22+
23+
# Jev engine tests
24+
npx vitest run tests/routing/jev.test.ts
25+
26+
# Provider tests
27+
node test/provider-test.js
28+
29+
# Quick smoke test
30+
node test.js
31+
```
32+
1433
## Project Structure
1534

1635
```
1736
src/
18-
├── providers/ # 47+ LLM provider configurations
19-
├── routing/ # UCB1 + MCTS routing engine
20-
├── cache/ # Semantic deduplication cache
21-
├── proxy/ # OpenAI-compatible proxy server
22-
└── tui/ # Terminal UI overlay
37+
├── routing/
38+
│ ├── advancedRouter.ts # Main heuristic router (System 2)
39+
│ ├── jev/ # Jev System One decision head
40+
│ │ ├── jevRouter.ts # Entry point
41+
│ │ ├── optionAttention.ts # Single-pass option-attention math
42+
│ │ ├── weights/ # Trained weights (git-tracked dist/)
43+
│ │ └── types.ts
44+
│ └── routeQuery.ts # Provider scoring + selection
45+
├── providers/
46+
│ └── providerConfig.ts # 80+ provider configs + tier definitions
47+
├── server/
48+
│ ├── modelMapper.ts # model="auto" / model="jev-auto" dispatcher
49+
│ └── proxyServer.ts # OpenAI-compatible proxy server
50+
├── cache/
51+
│ └── semanticCache.ts # Embedding-based deduplication
52+
└── cli.ts # CLI entry point
53+
54+
tests/
55+
├── routing/jev.test.ts # Jev engine unit tests
56+
├── routing/advancedRouter.test.ts
57+
└── integration/
2358
```
2459

25-
## Development
60+
## Adding a New Provider
2661

27-
```bash
28-
npm run build # Compile TypeScript
29-
npm test # Run tests
30-
node dist/tui/dashboard.js # Launch TUI
31-
```
62+
1. Add the provider config to `src/providers/providerConfig.ts`:
63+
```typescript
64+
export const MY_PROVIDER: Provider = {
65+
name: "my-provider",
66+
apiKeyEnvVar: "MY_PROVIDER_API_KEY",
67+
endpoint: "https://api.my-provider.ai/v1",
68+
supports: ["chat", "Completions"],
69+
tier: "cheap", // free | cheap | mid | premium
70+
region: "us-east",
71+
};
72+
```
73+
74+
2. Add to the provider registry:
75+
```typescript
76+
export const PROVIDERS: Record<string, Provider> = {
77+
// ...existing
78+
"my-provider": MY_PROVIDER,
79+
};
80+
```
81+
82+
3. Run tests:
83+
```bash
84+
node test/provider-test.js # basic connectivity
85+
npx a3m-router providers list # verify it appears
86+
```
87+
88+
## Adding a Routing Engine (e.g., a new Jev variant)
89+
90+
1. Create `src/routing/myEngine/`
91+
2. Implement the engine interface:
92+
```typescript
93+
export interface RouteResult {
94+
primary_model: string; // "provider/model-name"
95+
confidence: number; // 0–1
96+
备选?: string; // fallback provider/model
97+
}
98+
export function routeQuery(prompt: string): RouteResult { ... }
99+
```
100+
3. Wire it into `src/server/modelMapper.ts` under the new model name
101+
4. Add tests in `tests/routing/myEngine.test.ts`
102+
5. Document in this README under "Two Routing Modes"
32103

33-
## PR Guidelines
104+
## Code Style
105+
106+
- **TypeScript strict mode** — no `any`, full type coverage
107+
- **ES2022** target, CommonJS output
108+
- 2-space indent, single quotes
109+
- Run `npx tsc --noEmit` before committing
110+
111+
## Commit Conventions
112+
113+
```
114+
feat(provider): add Cloudflare Workers AI support
115+
fix(jev): guard against empty option set
116+
chore: bump vitest to 3.x
117+
docs: rewrite Quick Start section
118+
```
34119

35-
- Keep the package under 20KB (no ML deps)
36-
- Add provider configs in `src/providers/`
37-
- Route logic in `src/routing/`
38-
- TUI changes in `src/tui/`
39-
- Update CHANGELOG.md
120+
## Pull Request Checklist
40121

41-
## Adding a Provider
122+
- [ ] `npm run build` passes locally
123+
- [ ] `npx vitest run tests/` — all tests green
124+
- [ ] `node test.js` — smoke test passes
125+
- [ ] New provider/engine has tests
126+
- [ ] README updated if adding new features
42127

43-
1. Add config in `src/providers/providerConfig.ts`
44-
2. Set tier: `free` / `cheap` / `mid` / `premium`
45-
3. Add to `PROVIDER_TIERS` map
46-
4. PR with latency benchmarks
128+
---
47129

48-
## Questions?
130+
## Getting Help
49131

50-
Open an issue or reach out on [GitHub Discussions](https://github.com/Das-rebel/a3m-router/discussions).
132+
- 💬 [GitHub Discussions](https://github.com/Das-rebel/a3m-router/discussions)
133+
- 🐛 [Issue Tracker](https://github.com/Das-rebel/a3m-router/issues)
134+
- 📖 [docs/](docs/) for architecture and API reference

0 commit comments

Comments
 (0)