adaptive-memory-multi-model-router 2.13.18 → 2.13.20

package/docs/styles.css

@@ -0,0 +1,682 @@
+/* ===== A3M Router — Global Styles ===== */
+/* Dark theme, professional, minimal */
+
+:root {
+  --bg-primary: #0d1117;
+  --bg-secondary: #161b22;
+  --bg-tertiary: #1c2128;
+  --border: #30363d;
+  --border-light: #21262d;
+  --text-primary: #e6edf3;
+  --text-secondary: #8b949e;
+  --text-muted: #6e7681;
+  --accent-blue: #58a6ff;
+  --accent-green: #3fb950;
+  --accent-orange: #f0c000;
+  --accent-purple: #bc8cff;
+  --accent-red: #f85149;
+  --header-bg: rgba(13, 17, 23, 0.85);
+  --card-hover: #1c2128;
+
+  --font-mono: 'SF Mono', 'Fira Code', 'Cascadia Code', 'JetBrains Mono', 'Consolas', monospace;
+  --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Roboto, sans-serif;
+
+  --max-width: 960px;
+  --radius: 12px;
+  --radius-sm: 8px;
+}
+
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  font-family: var(--font-sans);
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* ===== Links ===== */
+a {
+  color: var(--accent-blue);
+  text-decoration: none;
+  transition: color 0.15s ease;
+}
+a:hover {
+  color: #79c0ff;
+  text-decoration: underline;
+}
+
+/* ===== Header / Nav ===== */
+.site-header {
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  background: var(--header-bg);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  border-bottom: 1px solid var(--border);
+}
+
+.nav-container {
+  max-width: var(--max-width);
+  margin: 0 auto;
+  padding: 0 20px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: 56px;
+}
+
+.nav-brand {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 700;
+  font-size: 18px;
+  color: var(--text-primary);
+}
+.nav-brand:hover {
+  text-decoration: none;
+  color: var(--text-primary);
+}
+.nav-brand-icon {
+  font-size: 22px;
+}
+
+.nav-links {
+  display: flex;
+  align-items: center;
+  gap: 24px;
+  list-style: none;
+}
+
+.nav-links a {
+  color: var(--text-secondary);
+  font-size: 14px;
+  font-weight: 500;
+  transition: color 0.15s ease;
+}
+.nav-links a:hover {
+  color: var(--text-primary);
+  text-decoration: none;
+}
+.nav-links a.active {
+  color: var(--accent-blue);
+}
+
+.nav-github-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 14px;
+  border: 1px solid var(--border);
+  border-radius: 20px;
+  font-size: 13px;
+  color: var(--text-secondary);
+  background: var(--bg-secondary);
+  transition: all 0.15s ease;
+}
+.nav-github-btn:hover {
+  border-color: var(--text-muted);
+  color: var(--text-primary);
+  text-decoration: none;
+}
+
+/* Mobile nav toggle */
+.nav-toggle {
+  display: none;
+  background: none;
+  border: none;
+  color: var(--text-secondary);
+  font-size: 24px;
+  cursor: pointer;
+  padding: 4px;
+}
+
+@media (max-width: 640px) {
+  .nav-links {
+    display: none;
+    position: absolute;
+    top: 56px;
+    left: 0;
+    right: 0;
+    background: var(--bg-primary);
+    border-bottom: 1px solid var(--border);
+    padding: 16px 20px;
+    flex-direction: column;
+    gap: 12px;
+    align-items: flex-start;
+  }
+  .nav-links.open {
+    display: flex;
+  }
+  .nav-toggle {
+    display: block;
+  }
+  .nav-github-btn {
+    display: none;
+  }
+}
+
+/* ===== Main Content ===== */
+.container {
+  max-width: var(--max-width);
+  margin: 0 auto;
+  padding: 0 20px;
+}
+
+.page {
+  padding: 48px 0 80px;
+}
+
+/* Headings */
+h1 {
+  font-size: 48px;
+  font-weight: 800;
+  letter-spacing: -1.5px;
+  line-height: 1.15;
+  color: var(--text-primary);
+  margin-bottom: 16px;
+}
+h2 {
+  font-size: 28px;
+  font-weight: 700;
+  letter-spacing: -0.5px;
+  color: var(--text-primary);
+  margin: 40px 0 16px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--border-light);
+}
+h3 {
+  font-size: 20px;
+  font-weight: 600;
+  color: var(--text-primary);
+  margin: 32px 0 12px;
+}
+h4 {
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--text-primary);
+  margin: 24px 0 8px;
+}
+
+p {
+  color: var(--text-secondary);
+  margin-bottom: 16px;
+  font-size: 16px;
+}
+
+strong {
+  color: var(--text-primary);
+}
+
+/* ===== Hero ===== */
+.hero {
+  text-align: center;
+  padding: 80px 0 40px;
+}
+
+.hero h1 {
+  font-size: 56px;
+  margin-bottom: 16px;
+}
+
+.hero .tagline {
+  font-size: 20px;
+  color: var(--text-secondary);
+  margin-bottom: 32px;
+  max-width: 600px;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+/* ===== Badges / Tags ===== */
+.badges {
+  display: flex;
+  gap: 10px;
+  flex-wrap: wrap;
+  justify-content: center;
+  margin-bottom: 40px;
+}
+
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  background: rgba(56, 139, 253, 0.12);
+  border: 1px solid rgba(56, 139, 253, 0.3);
+  color: var(--accent-blue);
+  padding: 5px 14px;
+  border-radius: 20px;
+  font-size: 13px;
+  font-weight: 500;
+}
+.badge.green {
+  background: rgba(63, 185, 80, 0.12);
+  border-color: rgba(63, 185, 80, 0.3);
+  color: var(--accent-green);
+}
+.badge.orange {
+  background: rgba(240, 192, 0, 0.12);
+  border-color: rgba(240, 192, 0, 0.3);
+  color: var(--accent-orange);
+}
+.badge.purple {
+  background: rgba(188, 140, 255, 0.12);
+  border-color: rgba(188, 140, 255, 0.3);
+  color: var(--accent-purple);
+}
+
+/* ===== Buttons ===== */
+.btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 12px 24px;
+  border-radius: var(--radius-sm);
+  font-size: 15px;
+  font-weight: 600;
+  transition: all 0.15s ease;
+  cursor: pointer;
+  border: none;
+}
+.btn:hover {
+  text-decoration: none;
+}
+
+.btn-primary {
+  background: #238636;
+  color: #fff;
+}
+.btn-primary:hover {
+  background: #2ea043;
+  color: #fff;
+}
+
+.btn-secondary {
+  background: var(--bg-secondary);
+  color: var(--text-primary);
+  border: 1px solid var(--border);
+}
+.btn-secondary:hover {
+  background: var(--card-hover);
+  border-color: var(--text-muted);
+  color: var(--text-primary);
+}
+
+.btn-ghost {
+  background: transparent;
+  color: var(--accent-blue);
+  border: 1px solid rgba(56, 139, 253, 0.3);
+}
+.btn-ghost:hover {
+  background: rgba(56, 139, 253, 0.1);
+  color: var(--accent-blue);
+}
+
+.cta-buttons {
+  display: flex;
+  gap: 12px;
+  justify-content: center;
+  flex-wrap: wrap;
+  margin-bottom: 48px;
+}
+
+/* ===== Cards ===== */
+.card {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 24px 28px;
+  margin-bottom: 20px;
+  transition: border-color 0.15s ease;
+}
+.card:hover {
+  border-color: #3d444d;
+}
+.card h3 {
+  margin-top: 0;
+  margin-bottom: 12px;
+  font-size: 18px;
+}
+.card p {
+  margin-bottom: 0;
+  font-size: 14px;
+}
+
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 16px;
+  margin: 24px 0;
+}
+
+.card-icon {
+  font-size: 28px;
+  margin-bottom: 12px;
+  display: inline-block;
+}
+
+/* ===== Code blocks ===== */
+code, pre {
+  font-family: var(--font-mono);
+}
+
+pre {
+  background: #0d1117;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 16px 20px;
+  overflow-x: auto;
+  font-size: 13px;
+  line-height: 1.5;
+  margin: 16px 0;
+  color: #e6edf3;
+}
+
+code:not(pre code) {
+  background: rgba(56, 139, 253, 0.1);
+  color: var(--accent-blue);
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-size: 13px;
+}
+
+/* Syntax highlighting */
+.hljs-keyword { color: #ff7b72; }
+.hljs-string { color: #a5d6ff; }
+.hljs-comment { color: #6e7681; font-style: italic; }
+.hljs-function { color: #d2a8ff; }
+.hljs-number { color: #79c0ff; }
+.hljs-built_in { color: #ffa657; }
+.hljs-title { color: #d2a8ff; }
+.hljs-params { color: #e6edf3; }
+.hljs-literal { color: #79c0ff; }
+.hljs-type { color: #ffa657; }
+
+/* ===== Tables ===== */
+.table-wrapper {
+  overflow-x: auto;
+  margin: 16px 0;
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 14px;
+}
+
+th, td {
+  padding: 10px 14px;
+  text-align: left;
+  border-bottom: 1px solid var(--border-light);
+}
+
+th {
+  font-weight: 600;
+  color: var(--text-primary);
+  background: var(--bg-tertiary);
+  white-space: nowrap;
+}
+
+td {
+  color: var(--text-secondary);
+}
+
+tr:hover td {
+  background: rgba(56, 139, 253, 0.04);
+}
+
+/* ===== Stats ===== */
+.stats-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+  gap: 20px;
+  margin: 32px 0;
+}
+
+.stat-card {
+  text-align: center;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 24px 16px;
+}
+
+.stat-value {
+  font-size: 32px;
+  font-weight: 800;
+  color: var(--text-primary);
+  line-height: 1.1;
+  letter-spacing: -1px;
+}
+
+.stat-label {
+  font-size: 13px;
+  color: var(--text-muted);
+  margin-top: 6px;
+}
+
+/* ===== Comparison tables ===== */
+.comparison-table {
+  width: 100%;
+  font-size: 13px;
+}
+.comparison-table th, .comparison-table td {
+  padding: 10px 12px;
+}
+.comparison-table .check { color: var(--accent-green); }
+.comparison-table .cross { color: var(--text-muted); }
+
+/* ===== Image / Chart ===== */
+.chart-container {
+  margin: 32px 0;
+  text-align: center;
+}
+.chart-container img {
+  max-width: 100%;
+  height: auto;
+  border-radius: var(--radius);
+  border: 1px solid var(--border);
+}
+.chart-caption {
+  font-size: 13px;
+  color: var(--text-muted);
+  margin-top: 8px;
+}
+
+/* ===== Callout boxes ===== */
+.callout {
+  padding: 16px 20px;
+  border-radius: var(--radius-sm);
+  margin: 16px 0;
+  border-left: 4px solid;
+  font-size: 14px;
+}
+.callout-info {
+  background: rgba(56, 139, 253, 0.08);
+  border-color: var(--accent-blue);
+  color: var(--accent-blue);
+}
+.callout-success {
+  background: rgba(63, 185, 80, 0.08);
+  border-color: var(--accent-green);
+  color: var(--accent-green);
+}
+.callout-warning {
+  background: rgba(240, 192, 0, 0.08);
+  border-color: var(--accent-orange);
+  color: var(--accent-orange);
+}
+
+/* ===== Tabs (benchmark page) ===== */
+.tabs {
+  display: flex;
+  gap: 4px;
+  margin: 24px 0 0;
+  border-bottom: 1px solid var(--border);
+}
+.tab-btn {
+  padding: 10px 20px;
+  background: transparent;
+  border: none;
+  color: var(--text-muted);
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  border-bottom: 2px solid transparent;
+  transition: all 0.15s ease;
+}
+.tab-btn:hover {
+  color: var(--text-primary);
+}
+.tab-btn.active {
+  color: var(--accent-blue);
+  border-bottom-color: var(--accent-blue);
+}
+.tab-content {
+  display: none;
+  padding: 24px 0;
+}
+.tab-content.active {
+  display: block;
+}
+
+/* ===== Timeline ===== */
+.timeline {
+  position: relative;
+  margin: 24px 0;
+  padding-left: 28px;
+}
+.timeline::before {
+  content: '';
+  position: absolute;
+  left: 8px;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background: var(--border);
+}
+.timeline-item {
+  position: relative;
+  margin-bottom: 24px;
+}
+.timeline-item::before {
+  content: '';
+  position: absolute;
+  left: -24px;
+  top: 6px;
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+  background: var(--accent-blue);
+  border: 2px solid var(--bg-primary);
+}
+.timeline-item h4 {
+  margin: 0 0 4px;
+}
+.timeline-item p {
+  margin: 0;
+  font-size: 14px;
+}
+
+/* ===== Footer ===== */
+.site-footer {
+  border-top: 1px solid var(--border);
+  padding: 32px 0;
+  margin-top: 48px;
+  text-align: center;
+}
+
+.footer-content {
+  max-width: var(--max-width);
+  margin: 0 auto;
+  padding: 0 20px;
+}
+
+.footer-links {
+  display: flex;
+  gap: 20px;
+  justify-content: center;
+  flex-wrap: wrap;
+  margin-bottom: 12px;
+}
+
+.footer-links a {
+  font-size: 14px;
+  color: var(--text-muted);
+}
+
+.footer-copyright {
+  font-size: 13px;
+  color: var(--text-muted);
+}
+
+/* ===== TOC ===== */
+.toc {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 16px 20px;
+  margin: 24px 0;
+}
+.toc h4 {
+  margin: 0 0 8px;
+  font-size: 14px;
+  color: var(--text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+.toc ul {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+.toc li {
+  margin-bottom: 4px;
+}
+.toc a {
+  font-size: 14px;
+}
+
+/* ===== Responsive ===== */
+@media (max-width: 768px) {
+  h1 { font-size: 36px; }
+  .hero h1 { font-size: 36px; }
+  h2 { font-size: 24px; }
+  .hero { padding: 48px 0 24px; }
+  .page { padding: 32px 0 48px; }
+  .stats-grid { grid-template-columns: repeat(2, 1fr); }
+  pre { font-size: 12px; padding: 12px 14px; }
+  .card-grid { grid-template-columns: 1fr; }
+}
+
+@media (max-width: 480px) {
+  h1 { font-size: 28px; }
+  .hero h1 { font-size: 28px; }
+  .hero .tagline { font-size: 16px; }
+  .stats-grid { grid-template-columns: repeat(2, 1fr); }
+  .stat-value { font-size: 24px; }
+  .badges { gap: 6px; }
+  .badge { font-size: 12px; padding: 4px 10px; }
+  .cta-buttons { flex-direction: column; align-items: center; }
+  .cta-buttons .btn { width: 100%; justify-content: center; }
+}
+
+/* ===== Print ===== */
+@media print {
+  .site-header { display: none; }
+  .site-footer { display: none; }
+  body { background: #fff; color: #000; }
+  pre { background: #f6f8fa; border: 1px solid #d0d7de; }
+}

package/examples/README.md

@@ -0,0 +1,61 @@
+# A3M Router Usage Examples
+
+Practical examples showing how to use the **Adaptive Memory Multi-Model Router** in real-world scenarios.
+
+## Prerequisites
+
+```bash
+npm install adaptive-memory-multi-model-router
+```
+
+Set at least one API key in your environment:
+
+```bash
+export OPENAI_API_KEY=sk-...
+export GROQ_API_KEY=gsk_...
+export ANTHROPIC_API_KEY=sk-ant-...
+export GEMINI_API_KEY=...
+```
+
+## Examples
+
+| #  | File                     | Description                                                                 |
+|----|--------------------------|-----------------------------------------------------------------------------|
+| 1  | `basic-route.js`         | Route a query to the best provider. Shows the routing decision with model, cost, confidence, and reasoning. |
+| 2  | `ensemble.js`            | Query multiple providers in parallel and merge results. A3M's signature capability. |
+| 3  | `classify-then-route.js` | Classify a query's domain first (code, math, creative, etc.), then route to the optimal provider for that domain. |
+| 4  | `chat-loop.js`           | Interactive terminal chat loop with auto-routing, cost tracking, and guardrails. |
+| 5  | `cost-compare.js`        | Compare estimated costs across providers for the same prompt. Find the cheapest and fastest routes. |
+| 6  | `a3m-sdk.js`             | Use the TypeScript SDK class — `route()`, `analyze()`, `recommend()`, batch routing, and the proxy server. |
+
+## Running Examples
+
+```bash
+# Route a query (dry-run — no API call)
+node examples/basic-route.js
+
+# Ensemble across multiple providers
+node examples/ensemble.js
+
+# Classify then route
+node examples/classify-then-route.js
+
+# Interactive chat loop
+node examples/chat-loop.js
+
+# Cost comparison
+node examples/cost-compare.js
+
+# SDK showcase
+node examples/a3m-sdk.js
+```
+
+## What Makes A3M Unique
+
+- **Parallel ensemble voting** — query multiple LLMs and compare results (no other router does this)
+- **RouteLLM-style routing** — learned cost-quality tradeoff based on arXiv:2404.06035
+- **47+ providers** — free, cheap, mid, premium, enterprise tiers
+- **Semantic cache** — returns cached responses for semantically similar queries
+- **Budget enforcement** — hard caps per API key with monthly reset
+- **Guardrails** — prompt injection detection, PII redaction, content filtering
+- **LangChain adapter** — drop-in replacement for ChatOpenAI