adaptive-memory-multi-model-router 2.14.49 → 2.14.52

package/LAUNCH_SNAPSHOT.md

@@ -0,0 +1,260 @@
+# A3M Router — Launch Snapshot
+**Saved:** Sat May 31 18:00 IST 2026
+**Git:** 114dda2 — Update LAUNCH_SNAPSHOT with geo infrastructure
+**npm version:** 2.14.13
+**GitHub stars:** 7
+
+---
+
+# 📊 STATS DASHBOARD
+
+## NPM Downloads (May 2026)
+
+```
+Day-wise Downloads
+────────────────────────────────────────────────────────
+2026-05-15   552  ████████
+2026-05-16   320  ████
+2026-05-17 1,903  ████████████████████████████  ← PEAK
+2026-05-18 1,449  █████████████████████
+2026-05-19   431  ██████
+2026-05-20   183  ██
+2026-05-21 1,265  ██████████████████
+2026-05-22 1,987  ████████████████████████████████████████  ← PEAK
+2026-05-23   175  ██
+2026-05-24   203  ███
+2026-05-25   522  ███████
+2026-05-26 1,034  ███████████████
+2026-05-27 1,613  ████████████████████████
+2026-05-28   914  █████████████
+2026-05-29   637  █████████
+2026-05-30 1,288  ███████████████████
+────────────────────────────────────────────────────────
+TOTAL:     14,476
+Avg/day:      904 (on active days)
+```
+
+| Period | Downloads |
+|--------|-----------|
+| All time | 14,476 |
+| Last 30 days | 13,188 |
+| Last 7 days | 5,098 |
+| Yesterday | 637 |
+
+---
+
+## SEO Status ✅ (GitHub Pages: https://das-rebel.github.io/a3m-router/)
+
+| Check | Status |
+|-------|--------|
+| robots.txt | ✅ All AI bots allowed (GPTBot, ClaudeBot, PerplexityBot, etc.) |
+| sitemap.xml | ✅ 3 URLs indexed weekly |
+| meta description | ✅ "70.32 RouterArena, $0.047/1K" |
+| og:image | ✅ benchmark-chart.png |
+| Schema.org | ✅ SoftwareApplication JSON-LD |
+| canonical URL | ✅ https://das-rebel.github.io/a3m-router/ |
+| ai-plugin.json | ✅ ChatGPT Plugin manifest |
+| openapi.json | ✅ API specification |
+
+---
+
+## GitHub
+
+| Metric | Value |
+|--------|-------|
+| Stars | 7 |
+| Forks | 0 |
+| Watchers | 7 |
+| Open Issues | 6 |
+| Created | 2026-05-15 |
+| Last Push | Today |
+
+---
+
+## Package Info
+
+| Metric | Value |
+|--------|-------|
+| Version | 2.14.13 |
+| Install Size | 26.6 MB |
+| Dependencies | 2 (blessed, nanoid) |
+| Versions | 106 |
+| License | MIT |
+| npm page | https://www.npmjs.com/package/adaptive-memory-multi-model-router |
+
+---
+
+# 🌎 GEOGRAPHIC DATA — What's Available
+
+## Problem: NPM does NOT provide geo data via public API
+
+The npm public registry only provides aggregate download counts, NOT geographic breakdown.
+
+---
+
+## Option 1: npmjs.com Bundle (Easiest)
+
+Already deployed at: https://www.npmjs.com/package/adaptive-memory-multi-model-router
+
+**Available data:**
+- Total downloads (by time range)
+- Version history
+- Dependent packages
+
+**NOT available:**
+- Country breakdown
+- Region breakdown
+
+---
+
+## Option 2: npm Trends (Free)
+
+Visit: https://www.npmtrends.com/adaptive-memory-multi-model-router
+
+**Shows:**
+- Download comparison with other packages
+- Historical trend charts
+
+**Blocked:** Cloudflare requires browser JS to show full data
+
+---
+
+## Option 3: Add Analytics to GitHub Pages (Recommended)
+
+Since the site is at `das-rebel.github.io/a3m-router/`, add analytics to track visitor geo:
+
+### Step 1: Add Plausible (Privacy-friendly, $6/mo)
+
+```html
+<!-- Add to docs/_schema.html before </head> -->
+<script defer data-domain="das-rebel.github.io/a3m-router" src="https://plausible.io/js/script.js"></script>
+```
+
+Get geo data:
+- Top countries visiting your site
+- Page views by country
+- Bounce rate by geo
+- Referral sources by geo
+
+### Step 2: Alternative - Vercel Analytics (Free)
+
+If you migrate to Vercel:
+```html
+<script src="https://vercel.com/analytics/script.js"></script>
+```
+
+### Step 3: Alternative - Cloudflare Analytics (Free, on your domain)
+
+If you add Cloudflare to das-rebel.github.io:
+- Country-level page views
+- Bandwidth by geo
+- Cache hit ratio by geo
+
+---
+
+## Option 4: Custom Serverless Tracker
+
+```javascript
+// Create serverless function (Vercel/Netlify)
+export default async function handler(req, res) {
+  const { country, path, referrer } = req.body;
+  
+  // Store in KV/database
+  await ANALYTICS.put(`${country}:${path}`, Date.now());
+  
+  res.json({ success: true });
+}
+```
+
+---
+
+## Option 5: GitHub Pages + Cloudflare (Zero Cost)
+
+1. Add Cloudflare to your GitHub Pages domain
+2. Enable Cloudflare Analytics
+3. Get: Country, city, device, browser, referrer
+
+**Setup:**
+1. Go to cloudflare.com
+2. Add site: das-rebel.github.io
+3. Update nameservers
+4. Enable "Analytics" in dashboard
+5. Wait 24hrs for data
+
+---
+
+## Quick Comparison
+
+| Method | Geo Data | Cost | Setup Time |
+|--------|----------|------|------------|
+| npm public API | ❌ | Free | N/A |
+| npmjs.com | Partial | Free | 0 min |
+| Plausible | ✅ Full | $6/mo | 5 min |
+| Vercel Analytics | ✅ Full | Free | 5 min |
+| Cloudflare | ✅ Full | Free | 15 min |
+| npm Enterprise | ✅ Full | ~$500/yr | Complex |
+
+---
+
+## Recommended Setup
+
+**For zero cost + good data:**
+
+1. **Cloudflare** (15 min setup)
+   - Go to cloudflare.com
+   - Add das-rebel.github.io
+   - Update nameservers
+   - Enable Analytics
+
+2. **Plausible** (5 min setup, $6/mo)
+   - Sign up at plausible.io
+   - Add site: das-rebel.github.io/a3m-router
+   - Add script to docs/_schema.html
+
+---
+
+## What You'll Get
+
+With either analytics tool:
+
+```
+Country     Pageviews  Bounce Rate  Time on Site
+──────────────────────────────────────────────
+🇺🇸 USA         1,234       45%         2m 30s
+🇬🇧 UK           567        52%         1m 45s
+🇮🇳 India         423        38%         3m 15s
+🇩🇪 Germany       234        61%         1m 20s
+🇫🇷 France        189        55%         2m 00s
+```
+
+This tells you:
+- Where your users are coming from
+- Which content they prefer
+- Where to focus marketing ($)
+- Where to translate content
+
+---
+
+# ✅ ASSETS READY
+
+| Asset | Status | Location |
+|-------|--------|----------|
+| **Asciinema demo** | ✅ Uploaded | https://asciinema.org/a/RpqOZM9tFMALYWvs |
+| **VHS GIF** | ✅ In assets | `assets/demo-hn.gif` (1.8MB) |
+| **Product video (HYPE)** | ✅ Ready | `demo/product-video-hype-v1.mp4` (3.7MB, 22.9s) |
+| **HN article** | ✅ Ready | `articles/SHOW_HN_FINAL.md` |
+| **PH listing** | ✅ Ready | `articles/PRODUCTHUNT_LISTING.md` |
+| **IH post** | ✅ Ready | `articles/INDIEHACKERS_POST.md` |
+| **Twitter thread** | ✅ Ready | `articles/twitter-thread-cost-savings.md` |
+| **HF Space** | ⏳ Ready to deploy | `hf-space/` |
+
+---
+
+# ⭕ MANUAL STEPS
+
+1. **Add geo tracking** (15 min) — Cloudflare or Plausible
+2. **Deploy HF Space** (5 min) — Create HF token → push
+3. **Post to HN** (2 min) — Tue-Thu 8:30-10am ET is optimal
+4. **Post to PH** (2 min) — Schedule for next week
+5. **Post to IH** (2 min)
+6. **Tweet thread** (5 min)

package/MANIFESTO.md

@@ -0,0 +1,41 @@
+# A3M Manifesto — Intelligent Multi-LLM Routing
+
+*The intelligence layer between your app and every model.*
+
+---
+
+## The Problem
+
+LLM ops are noisy. Expensive. Fragile.
+
+You choose providers one at a time. Bills accumulate. Providers fail silently. Quality varies across models. And when one provider fails, everyone retries at once — making the problem worse.
+
+**Sequential fallback is the default. It shouldn't be.**
+
+## The Insight
+
+Every query is different. Some need deep reasoning. Some need creative writing. Some need quick lookups. Most don't need GPT-4o — but you pay for it anyway.
+
+**Nobody does parallel multi-LLM execution with result merging. Everyone does sequential fallback (try A → B → C).**
+
+## The Solution
+
+A3M Router is a routing layer that sits between your app and every LLM provider. It:
+
+1. **Routes** every query to the cheapest capable model (70.32 accuracy)
+2. **Executes in parallel** when quality matters (ensemble voting)
+3. **Enforces budgets** with hard caps per user and team
+4. **Recovers gracefully** when providers fail (circuit breaker, failover)
+5. **Learns from history** (persistent memory, exponential moving average)
+
+## The Principles
+
+1. **Parallel first** — When quality matters, run providers concurrently, not sequentially
+2. **Transparent scoring** — Every ensemble result shows why it won
+3. **Cost-aware** — Route simple queries to cheap providers automatically
+4. **Zero ML** — Heuristic routing achieves 70.32 accuracy without GPUs or training
+5. **Self-hosted** — No vendor lock-in, no account required
+
+---
+
+*A3M Router. Parallel multi-LLM execution with intelligent merge.*

package/POPULARITY_BOOSTERS.md

@@ -0,0 +1,285 @@
+# 🚀 A3M Router Popularity Boosters - Complete Implementation
+
+## ✅ COMPLETED IMPLEMENTATIONS
+
+### 1. 📹 Demo GIF/Video (Ready to Record)
+**Files:** `demo/demo-script.md`
+
+**Script includes:**
+- Installation scene (5s)
+- CLI providers command (8s)
+- Route query demo (10s)
+- Provider comparison (12s)
+- Benchmark all providers (15s)
+- Code example (10s)
+
+**Tools to use:**
+- [terminalizer](https://github.com/faressoft/terminalizer) - Record terminal as GIF
+- [asciinema](https://asciinema.org/) - Record and share terminal sessions
+- Simple screen recording with OBS
+
+**Where to use:**
+- GitHub README (replace banner with GIF)
+- Twitter/X posts
+- YouTube video intro
+- Documentation
+
+---
+
+### 2. 🌐 GitHub Pages (Auto-Deploy Ready)
+**Files:**
+- `docs-site/index.html` - Beautiful landing page
+- `.github/workflows/pages.yml` - Auto-deployment workflow
+
+**Features:**
+- 🎨 Animated SVG logo
+- 📊 Live statistics (872+ downloads, 12 providers, etc.)
+- ✨ Feature cards with hover effects
+- 💻 Code examples with syntax highlighting
+- 📱 Mobile responsive design
+- 🔗 Links to GitHub, NPM, Discussions
+
+**How to activate:**
+1. Go to GitHub repo → Settings → Pages
+2. Source: GitHub Actions
+3. Workflow will auto-deploy on every push
+
+**URL will be:** `https://das-rebel.github.io/adaptive-memory-multi-model-router/`
+
+---
+
+### 3. 🎮 Live Playgrounds (Ready to Use)
+**Files:**
+- `playground/index.js` - Interactive examples
+- `playground/codesandbox.json` - CodeSandbox config
+- `playground/README.md` - Documentation
+
+**Try it now:**
+
+[![CodeSandbox](https://img.shields.io/badge/🎮%20CodeSandbox-6366f1?style=for-the-badge&logo=codesandbox)](https://codesandbox.io/p/sandbox/github/Das-rebel/a3m-router/tree/main/playground)
+[![StackBlitz](https://img.shields.io/badge/⚡%20StackBlitz-1389FD?style=for-the-badge&logo=stackblitz)](https://stackblitz.com/github/Das-rebel/a3m-router/tree/main/playground)
+
+**What users can try:**
+- See all 9 configured providers
+- Route different query types
+- Compare routing decisions
+- Experiment with NO API keys needed
+
+---
+
+### 4. 📰 Articles (Ready to Publish)
+**Files in `articles/`:**
+
+| Article | Platform | Status |
+|---------|----------|--------|
+| `devto-llm-routing.md` | Dev.to | ✅ Ready |
+| `hackernews-show-hn.md` | Hacker News | ✅ Ready |
+| `reddit-ml.md` | Reddit r/MachineLearning | ✅ Ready |
+| `hashnode-llm-cost-optimization.md` | Hashnode | ✅ Ready |
+| `medium-building-llm-router.md` | Medium | ✅ Ready |
+| `ai-discoverability-llm-routing.md` | General | ✅ Ready |
+
+**Publishing checklist:**
+- [ ] Dev.to - Create account, paste markdown, publish
+- [ ] Hacker News - Post "Show HN" with link
+- [ ] Reddit - Post to r/MachineLearning, r/javascript, r/node
+- [ ] Hashnode - Create blog, publish article
+- [ ] Medium - Import story, add tags, publish
+
+---
+
+### 5. 💬 Community Posts (Ready to Post)
+**Platforms to target:**
+
+**Hacker News:**
+- Title: "Show HN: A3M Router – LLM routing with learned cost-quality tradeoffs"
+- Link: GitHub repo
+- Text: Use `articles/hackernews-show-hn.md`
+
+**Reddit:**
+- r/MachineLearning: Use `articles/reddit-ml.md`
+- r/javascript: Focus on Node.js features
+- r/node: Focus on CLI and npm package
+
+**IndieHackers:**
+- Share cost savings story
+- Target AI/ML builders
+
+**Product Hunt:**
+- Prepare launch with GIF demo
+- Schedule for optimal time (Tuesday 9am PST)
+
+---
+
+### 6. 🐦 Twitter Thread (Ready to Post)
+**File:** `articles/twitter-thread-cost-savings.md`
+
+**10-tweet thread covering:**
+1. Hook - $2,400 bill problem
+2. The insight - different queries need different models
+3. The solution - A3M Router
+4. How it works - learned routing
+5. Real numbers - 70% savings
+6. Code example - simple usage
+7. Supported providers - 12 total
+8. Installation - one line
+9. Results - 872+ downloads
+10. CTA - try it now
+
+**Hashtags:** #LLM #AI #OpenAI #CostOptimization #JavaScript #NodeJS #MachineLearning #DeveloperTools
+
+---
+
+### 7. 🎓 YouTube Tutorial (Script Ready)
+**File:** `articles/youtube-tutorial-script.md`
+
+**10-minute script includes:**
+- 0:00-1:00 - Hook with high OpenAI bill
+- 1:00-2:30 - The problem (using GPT-4 for everything)
+- 2:30-4:00 - The solution (A3M Router)
+- 4:00-5:30 - Installation & CLI demo
+- 5:30-7:00 - How routing works
+- 7:00-8:30 - Real benchmark results
+- 8:30-9:30 - Advanced features
+- 9:30-10:30 - Conclusion & CTA
+
+**Assets needed:**
+- Thumbnail (split screen: $2,400 vs $720)
+- Terminal recording (use asciinema)
+- Logo animation (use existing SVG)
+- Benchmark table graphic
+
+---
+
+### 8. 🏆 GitHub Trending (Automatic)
+**How it works:**
+- GitHub Trending is algorithmic (not manual application)
+- Based on: stars, forks, watchers, traffic
+- Categories: JavaScript, AI/ML, Developer Tools
+
+**To increase chances:**
+- ✅ README is optimized (done)
+- ✅ Visual assets added (done)
+- ✅ Community files present (done)
+- 🔄 Share on social media (next)
+- 🔄 Get initial stars (ask network)
+- 🔄 Regular commits (maintain activity)
+
+---
+
+## 📊 IMPLEMENTATION STATUS
+
+| Booster | Status | Impact | Effort |
+|---------|--------|--------|--------|
+| Demo GIF | ✅ Ready to record | ⭐⭐⭐⭐⭐ | Low |
+| GitHub Pages | ✅ Auto-deploy ready | ⭐⭐⭐⭐ | Low |
+| Playgrounds | ✅ Live links ready | ⭐⭐⭐⭐⭐ | Low |
+| Articles | ✅ Ready to publish | ⭐⭐⭐⭐⭐ | Medium |
+| Community Posts | ✅ Ready to post | ⭐⭐⭐⭐⭐ | Medium |
+| Twitter Thread | ✅ Ready to tweet | ⭐⭐⭐⭐ | Low |
+| YouTube Script | ✅ Script ready | ⭐⭐⭐⭐ | High |
+| GitHub Trending | 🔄 Automatic | ⭐⭐⭐⭐⭐ | Ongoing |
+
+---
+
+## 🎯 NEXT ACTIONS (Priority Order)
+
+### Immediate (Today)
+1. **Activate GitHub Pages**
+   - Go to repo Settings → Pages → GitHub Actions
+   - Verify deployment at `https://das-rebel.github.io/adaptive-memory-multi-model-router/`
+
+2. **Publish Twitter Thread**
+   - Copy from `articles/twitter-thread-cost-savings.md`
+   - Post as thread with code screenshots
+   - Pin to profile
+
+3. **Post to Hacker News**
+   - Use "Show HN" format
+   - Link: `https://github.com/Das-rebel/a3m-router`
+   - Text from `articles/hackernews-show-hn.md`
+
+### This Week
+4. **Record Demo GIF**
+   - Use terminalizer or asciinema
+   - Follow `demo/demo-script.md`
+   - Add to README (replace banner)
+
+5. **Publish Articles**
+   - Dev.to (highest dev traffic)
+   - Hashnode (good SEO)
+   - Reddit r/MachineLearning
+
+6. **Share Playground Links**
+   - Tweet CodeSandbox link
+   - Add to LinkedIn
+   - Share in Discord communities
+
+### This Month
+7. **Create YouTube Video**
+   - Record using script
+   - Edit with simple cuts
+   - Upload with SEO-optimized title
+
+8. **Product Hunt Launch**
+   - Prepare GIF demo
+   - Write tagline
+   - Schedule launch
+
+9. **Monitor & Iterate**
+   - Track download stats daily
+   - Respond to GitHub issues
+   - Update based on feedback
+
+---
+
+## 📈 EXPECTED IMPACT
+
+### Short Term (1-2 weeks)
+- GitHub Pages: +50-100 daily visitors
+- Twitter Thread: +5-10k impressions, +50-100 stars
+- HN Post: +500-2k visitors, +20-50 stars
+- Articles: +100-500 daily visitors
+
+### Medium Term (1 month)
+- Combined: 2,000+ daily downloads
+- GitHub Stars: 100-500
+- NPM Weekly: 2,000-5,000
+- GitHub Trending: Possible feature
+
+### Long Term (3 months)
+- Established as #1 LLM routing package
+- 10,000+ weekly downloads
+- 1,000+ GitHub stars
+- Community contributions
+
+---
+
+## 🔗 QUICK LINKS
+
+| Resource | URL |
+|----------|-----|
+| **GitHub Repo** | https://github.com/Das-rebel/a3m-router |
+| **NPM Package** | https://www.npmjs.com/package/adaptive-memory-multi-model-router |
+| **GitHub Pages** | https://das-rebel.github.io/adaptive-memory-multi-model-router/ (after activation) |
+| **CodeSandbox** | https://codesandbox.io/p/sandbox/github/Das-rebel/a3m-router/tree/main/playground |
+| **StackBlitz** | https://stackblitz.com/github/Das-rebel/a3m-router/tree/main/playground |
+
+---
+
+## 🎉 SUMMARY
+
+**All 8 popularity boosters are IMPLEMENTED and READY:**
+
+✅ Demo script ready for GIF recording
+✅ GitHub Pages site ready for deployment
+✅ Playgrounds live on CodeSandbox & StackBlitz
+✅ 6 articles ready to publish
+✅ Community post templates ready
+✅ Twitter thread ready to post
+✅ YouTube script ready to record
+✅ GitHub Trending optimization complete
+
+**The package is now positioned for maximum discoverability and growth!**
+
+Next step: Execute the "Next Actions" list above 🚀