` combos, **Fusion** (model panel + judge), task-aware routing, per-request model / mode / USD-budget overrides. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **🗜️ Pluggable compression** — 12 composable engines + Compression Studios: LLMLingua-2, two-tier Ultra, omniglyph, per-step fidelity gate, GCF v3.2, drag-reorder editor. → [Compression](docs/compression/COMPRESSION_ENGINES.md)
@@ -642,11 +642,11 @@ of your shell history. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md)
-## 🌐 349 AI Providers — 90+ Free
+## 🌐 350 AI Providers — 154 Catalog-Marked Free
-> The most complete catalog of any open-source router: **350 providers**, **90+ with a free tier**, **56 free forever**.
+> **350 registered providers** across the canonical chat, media, search, local, cloud-agent and system collections, including **154 carrying `hasFree: true` discovery metadata**. The chat model registry covers **268 providers / 2,566 distinct provider-model pairs / 1,312 raw model IDs**; the separate free-budget catalog has **455 per-model rows**, **40 recurring pools** and **56 recurring/keyless free-forever providers**. These are different denominators by design; definitions and pool-deduped calculations live in the [Provider Reference](docs/reference/PROVIDER_REFERENCE.md) and [Free Tiers](docs/reference/FREE_TIERS.md).
@@ -679,7 +679,7 @@ of your shell history. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md)
-…and 220+ more — every icon resolves live from the dashboard's provider catalog. 📖 [Provider Reference](docs/reference/PROVIDER_REFERENCE.md)
+…and 330+ more — every icon resolves live from the dashboard's provider catalog. 📖 [Provider Reference](docs/reference/PROVIDER_REFERENCE.md)
-📖 [Authorization](docs/architecture/AUTHZ_GUIDE.md) · [Guardrails](docs/security/GUARDRAILS.md) · [Compliance](docs/security/COMPLIANCE.md)
@@ -810,7 +810,7 @@ Tokens are scoped `read` / `write` / `admin`; process-spawning routes stay loopb
-
+
-
Dados de cobertura social em 2026-08-17 · YT: 741 | TT: 137 | IG: 124 · Frescor (dias): YT 0 · TT 14 · IG 15
+
Snapshot do painel em 2026-08-24 · Catálogo bruto: YT 809 | TT 137 | IG 124 · Frescor (dias): YT 1 | TT 21 | IG 22
@@ -1114,52 +1115,52 @@ same process on one port, so there is no separate CLI-only package today.
🎬 #1 — Instagram nick_saraev — 1,628,910 views
+ nick_saraev — 3,042,474 views
+
+
+
+ 🎬 #2 — Instagram theopenstack — 692,419 views
+
+
+
+ 🎬 #3 — TikTok milesreevesai — 620,400 views
🎬 #2 — YouTube Vaibhav Sisinty — 373,084 views
+ 🎬 #4 — YouTube Vaibhav Sisinty — 391,109 views
-
-
+ 🎬 #3 — YouTube Shorts Nick Automates — 207,714 views
-
-
-
- 🎬 #4 — TikTok milesreevesai — 620,400 views
-
-
-
- 🎬 #5 — YouTube Valency Labs — 135,974 views
+ 🎬 #5 — Instagram buildwithai.club — 347,652 views
Stealth wreq-js — JA3 / JA4 TLS fingerprint impersonation, 3-level proxy Resilience Circuit breaker, exponential backoff, anti-thundering-herd, auto-combo self-healing Logging pino — structured JSON logs with request context Testing Node.js test runner + Vitest — 25,000+ test cases across 3,300+ files (unit, integration, E2E, security, ecosystem) Testing Node.js test runner + Vitest — 39,000+ static test declarations across 5,100+ tracked test files (unit, integration, E2E, security, ecosystem) Platforms Desktop (Electron) · Android (Termux) · PWA (any browser) CI/CD GitHub Actions — auto npm publish + Docker Hub on release Links Website · npm · Docker Hub Compression Rules Format JSON rule-pack schemas for Caveman and RTK filters Compression Language Packs Language detection and Caveman rule-pack authoring Resilience Guide Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing Auto-Combo Engine 14-factor scoring, mode packs, self-healing Auto-Combo Engine 15-factor scoring, mode packs, self-healing Proxy Guide 3-level proxy system, 1proxy marketplace, registry CRUD Free Tiers 90+ free providers consolidated directory (42 documented token pools / 495 models) Free Tiers Consolidated directory: 40 documented recurring pools / 455 cataloged free-tier entries Features Gallery Visual dashboard tour with screenshots Codebase Documentation Beginner-friendly codebase walkthrough Document Description API Reference All endpoints with examples OpenAPI Spec OpenAPI 3.0 specification MCP Server 109 MCP tools, IDE configs, Python/TS/Go clients MCP Server 110 MCP tools, IDE configs, Python/TS/Go clients MCP Server Guide MCP installation, transports, and tool reference A2A Server JSON-RPC 2.0 protocol, skills, streaming, task mgmt A2A Server Guide A2A agent card, tasks, skills, and streaming Security Policy Vulnerability reporting and security practices i18n Guide 43-language support, translation workflow, RTL Release Checklist Pre-release validation steps Coverage Plan Test coverage strategy and 25,000+ test suite Coverage Plan Test coverage strategy for 39,000+ static test declarations across 5,100+ tracked test files
+ Rank Contributor Merged PRs ~Changed lines 1 backryun 190 227,977 2 oyi77 180 407,678 3 rdself 145 80,663 4 JxnLexn 128 387,049 5 KooshaPari 101 125,747 6 herjarsa 88 230,872 7 RaviTharuma 79 55,106 8 maxmad64bis 69 394,715 9 artickc 59 33,260 10 HouMinXi 51 47,334 10 chirag127 51 5,153 12 xz-dev 50 245,976 13 hartmark 47 52,185 14 rqzbeh 39 143,181 15 dhaern 34 19,559 16 Dingding-leo 33 1,986 17 NomenAK 32 13,854 18 MumuTW 30 16,953 19 benzntech 29 11,641 20 pacocartones 24 9,331 20 Prudhvivuda 24 6,312
+
+Frozen at live release/v3.8.50 tip dafb4ae808, with merges through 2026-08-24 05:26:03 UTC. The paginated GitHub GraphQL census contains 5,911 merged PRs: 2,707 by the repository owner, 179 by Dependabot, and 3,025 external PRs from 535 distinct contributors . “Changed lines” is GitHub additions + deletions and includes generated files, lockfiles, catalogs, translations and documentation; it is churn, not authored LOC. Ties at the cutoff are retained.
+
+### GitHub-attributed commits
+
-
-
-
- oyi77
- 🥇 213 commits • +114K lines Analytics engine, SQL aggregations,
-
-
-
- R.D. & Randi
- 🥈 108 commits • +38K lines Endpoints page, tunnel integrations,
-
-
-
- Chris Staley
- 🥉 70 commits • +1.8K lines SSE stream hardening, Responses API,
-
-
-
- zenobit
- 🏅 62 commits • +22K lines CI/CD pipeline, i18n for 33 languages,
-
-
-
- Jan Leon
- 🏅 58 commits • +22K lines Reasoning-effort routing, proxy controls,
-
-
backryun
🏅 53 commits • +70K lines Provider catalog curation — Perplexity, Kimi,
+ 🥇 220 GitHub-attributed commits
-
- Chirag Singhal
+
+ Paijo
🏅 46 commits • +4.8K lines Error sanitization, MITM prefill fix,
+ 🥈 219 GitHub-attributed commits
-
- kfiramar
+
+ Randi
🏅 38 commits • +1.7K lines Codex websocket + passthrough, auth/onboarding,
+ 🥉 108 GitHub-attributed commits
-
- Benson K B
+
+ Ravi Tharuma
🏅 28 commits • +9.2K lines Electron desktop app, auto-updater,
+ 🏅 81 GitHub-attributed commits
-
- Hernan J. Ardila
+
+ Chris
🏅 25 commits • +174K lines Zero-latency combos, vision-bridge auto-routing,
+ 🏅 70 GitHub-attributed commits
+
+
+
+ Markus Hartung
+ 🏅 69 GitHub-attributed commits · tied #6
+
+
+
+
+
+ Dizzle
+ 🏅 69 GitHub-attributed commits · tied #6
+
+
+
+ Jan Leon
+ 🏅 64 GitHub-attributed commits
+
+
+
+ zenobit
+ 🏅 62 GitHub-attributed commits
+
+
+
+ Bob.Hou
+ 🏅 51 GitHub-attributed commits · tied #10
+
+
+
+ Xiangzhe
+ 🏅 51 GitHub-attributed commits · tied #10
+Rechecked at 2026-08-24 06:14:31 UTC: GitHub-attributed commits reported by the repository Contributors API for the release/v3.8.50 default branch. The API returned 525 identities (415 users, 2 bots, 108 anonymous); this table excludes the maintainer, bots and anonymous identities and retains competition ties. It is distinct from both the merged-PR ranking above and the 639-person Git-metadata census below.
+
> 🙏 These contributors' features, bug fixes, and infrastructure improvements are a **core part** of what makes OmniRoute reliable and feature-rich. Every pull request, every test case, and every i18n translation file matters. Open source is built by people like them.
@@ -1405,25 +1436,48 @@ A heartfelt thank-you to the people who fund OmniRoute out of their own pocket
… and others who prefer to stay private 💛
+Public GitHub Sponsors revalidated on 2026-08-24. GitHub's activeOnly status determines the active labels above; previously disclosed public one-time supporters remain thanked, and private sponsors remain anonymous.
+
💖 Become a sponsor →
-## 👥 320+ Contributors
+## 👥 600+ Contributors
-[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
+[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
+
+Audited on 2026-08-24 at frozen base ac02c5b42f and rechecked at live release/v3.8.50 tip dafb4ae808: 639 normalized human Git identities — 407 appear as commit authors (including the maintainer) and 232 only in explicit Co-authored-by trailers. The census normalizes GitHub noreply handles, excludes 26 bot/agent/service/placeholder identities, and does not merge ordinary email addresses merely because their display names match.
### How to Contribute
@@ -1453,7 +1509,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
```bash
# Create a release — npm publish happens automatically
-gh release create v3.8.2 --title "v3.8.2" --generate-notes
+VERSION=x.y.z
+gh release create "v${VERSION}" --title "v${VERSION}" --generate-notes
```
Project ⭐ How it inspired OmniRoute 9router 22.7k The original project this fork is built on — extended here with multi-modal APIs and a full TypeScript rewrite. CLIProxyAPI 43.6k The Go implementation that inspired this JavaScript / TypeScript port. LiteLLM 54.0k The AI gateway whose public pricing dataset feeds our cost-tracking sync and whose provider-normalization model informed our routing. 9router 26,161 The original project this fork is built on — extended here with multi-modal APIs and a full TypeScript rewrite. CLIProxyAPI 48,497 The Go implementation that inspired this JavaScript / TypeScript port. LiteLLM 57,100 The AI gateway whose public pricing dataset feeds our cost-tracking sync and whose provider-normalization model informed our routing. codex-chatgpt-web 1,410 MIT source adapted into the vendored ChatGPT Web → Codex Responses bridge, including browser-session, response-framing, usage and web-search adapters. free-claude-code 48,112 Patterns ported into stream recovery, no-thinking aliases, fallback web search, sliding-window limits, log redaction and hardened launcher flows. composer-api 322 Cursor Composer tool-choice, output-constraint and tool-commit patterns adapted into the native Cursor executor. codex-multi-auth 457 Fresh-login and refresh-token rotation patterns ported into Codex OAuth reauthentication. opencode-anthropic-auth 510 Claude Code-compatible transform defaults and billing-header behavior generalized into OmniRoute's config-driven bridge. grok2api-merged 2 Its Grok model mappings, fake-TypeError Statsig generator, request and device defaults, and NDJSON response processor were materially adapted into OmniRoute's Grok Web executor. TQZHR/grok2api 705 The principal transitive code source behind grok2api-merged; its model, header, payload, Statsig and processor implementations are preserved in the Grok Web lineage. chenyme/grok2api 7,520 The underlying MIT source for Grok payload and device defaults, the Statsig generator, and the result.response processor carried through TQZHR and grok2api-merged. grok2api-pro 27 A transitive source credited by grok2api-merged for its proxy-pool layer; OmniRoute preserves that lineage notice but does not claim a proxy-pool port in its bounded Grok Web executor. GrokProxy 50 Its cookie-authenticated Grok proxy and result.response.token streaming pattern informed OmniRoute's Grok Web transport. GrokBridge 5 The original Grok Web implementation consulted its HTTP/browser upstream design; its direct HTTP path derives from GrokProxy, so no independent code port is claimed. grok-web-api 14 Its Rust ChatOptions and response-envelope schemas informed OmniRoute's TypeScript Grok request and streaming-response types.
### 🗜️ Context & token compression — engines
Project ⭐ How it inspired OmniRoute Caveman 90.8k The viral "why use many token when few token do trick" project — its caveman-speak philosophy powers our standard compression mode and 30+ filler/condensation rules. RTK – Rust Token Killer 71.8k High-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline. headroom 60.1k Reversible context-compression (SmartCrusher) — inspired our headroom engine and the ccr retrieve-marker pattern. LLMLingua 6.5k Prompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open llmlingua engine. llmlingua-2-js 30 The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine. Troglodita 26 PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar. ponytail 86.0k The viral "lazy senior dev" YAGNI-coder skill — inspired our less-code Output Style: smallest-working-change steering that cuts _generated_ code (the output-axis sibling to Caveman's terse prose). Caveman 100,538 The viral "why use many token when few token do trick" project — its caveman-speak philosophy powers our standard compression mode and 30+ filler/condensation rules. RTK – Rust Token Killer 77,185 High-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline. headroom 67,310 Reversible context-compression (SmartCrusher) — inspired our headroom engine and the ccr retrieve-marker pattern. LLMLingua 6,598 Prompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open llmlingua engine. llmlingua-2-js 31 The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine. Troglodita 40 PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar. ponytail 108,957 The viral "lazy senior dev" YAGNI-coder skill — inspired our less-code Output Style: smallest-working-change steering that cuts _generated_ code (the output-axis sibling to Caveman's terse prose). i-have-adhd 23,526 Its action-first, ADHD-friendly response style was adapted into OmniRoute's concise output style across five languages.
### 🧩 Compact formats, token research & code-aware tooling
Project ⭐ How it inspired OmniRoute TOON 24.9k Token-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage. GCF – Graph Compact Format 22 First inspired our tabular compaction stage; now its zero-dependency, lossless generic-profile encoder is vendored directly as the Headroom codec (MIT, SPDX-marked), with later numeric-domain and count-mismatch correctness fixes. token-optimizer-mcp 444 Brotli/SQLite cache + per-session context-delta — inspired our session-dedup engine. token-savior 1.1k Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction. token-saver 117 Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip. token-optimizer 1.7k "Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking. TokenMizer 16 A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design. TOON 25,233 Token-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage. GCF – Graph Compact Format 41 Its compact graph format and generic-profile design informed OmniRoute's tabular compaction and Headroom codec format. gcf-typescript 4 The MIT TypeScript implementation directly vendored and extended as the Headroom generic-profile codec. token-optimizer-mcp 494 Brotli/SQLite cache + per-session context-delta — inspired our session-dedup engine. token-savior 1,122 Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction. token-saver 138 Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip. token-optimizer 1,951 "Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking. TokenMizer 28 A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design. OmniCompress 3 Rust columnar-JSON + content-addressed retrieve + cross-message dedup — validated our headroom/ccr/session-dedup engine design and the cache-stable "compressed form is position-independent" invariant. mcp-compressor 98 MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction. RepoMapper 187 Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration. mcp-compressor 113 MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction. RepoMapper 197 Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration. quiet-shell-mcp 4 Declarative shell-output reduction over MCP — validated our declarative bash-output compaction. ts-morph 6.1k TypeScript Compiler API toolkit — inspired our parser-based comment removal that preserves string, template and regex literals. ts-morph 6,162 TypeScript Compiler API toolkit — inspired our parser-based comment removal that preserves string, template and regex literals.
### 🧠 Memory & RAG
Project ⭐ How it inspired OmniRoute Mem0 61.2k Universal memory layer — its proxy-as-write/read-boundary model shaped our memory architecture. Letta (MemGPT) 23.9k Stateful agents with tiered memory — inspired our Context Control & Recovery (CCR) tiered model. WFGY 1.8k The ProblemMap taxonomy of 16 recurring RAG/LLM failure modes — the shared vocabulary in our troubleshooting guide. Mem0 63,902 Universal memory layer — its proxy-as-write/read-boundary model shaped our memory architecture. Letta (MemGPT) 24,382 Stateful agents with tiered memory — inspired our Context Control & Recovery (CCR) tiered model. WFGY 1,781 The ProblemMap taxonomy of 16 recurring RAG/LLM failure modes — the shared vocabulary in our troubleshooting guide.
### 🛰️ Traffic inspection, MITM & transparent proxy
Project ⭐ How it inspired OmniRoute llm-interceptor 49 MITM interception/analysis of coding-assistant ↔ LLM traffic — our Traffic Inspector ports its SSE merge, conversation normalization, host passthrough and secret masking (MIT). ProxyBridge 5.5k Transparent per-process proxy routing — inspired our crash-safe MITM teardown, socket idle-timeouts, /proc process attribution and TPROXY capture. llm-interceptor 66 MITM interception/analysis of coding-assistant ↔ LLM traffic — our Traffic Inspector ports its SSE merge, conversation normalization, host passthrough and secret masking. The upstream's complete license text is still under provenance review. ProxyBridge 5,995 Transparent per-process proxy routing — inspired our crash-safe MITM teardown, socket idle-timeouts, /proc process attribution and TPROXY capture.
### 📚 Model data, observability & UI
Project ⭐ How it inspired OmniRoute models.dev 6.0k Open database of AI model specs, pricing and capabilities — synced natively into our model catalog. React Flow / xyflow 37.7k The node-based graph library powering our real-time Compression Studio and Combo/Routing Studio. LangGraph 37.6k LangGraph Studio's live workflow-graph visualization inspired our Studios' real-time cascade view. Langfuse 31.4k Its trace → span → generation observability model shaped our Compression Studio waterfall. Kiali 3.6k Istio service-mesh observability — inspired our circuit-breaker badges and error-edge visuals in the Routing/Combo Studio. lobe-icons 2.2k AI/LLM brand logos that render the provider icons across our dashboard. models.dev 6,555 Open database of AI model specs, pricing and capabilities — synced natively into our model catalog. React Flow / xyflow 38,108 The node-based graph library powering our real-time Compression Studio and Combo/Routing Studio. LangGraph 40,314 LangGraph Studio's live workflow-graph visualization inspired our Studios' real-time cascade view. Langfuse 33,592 Its trace → span → generation observability model shaped our Compression Studio waterfall. Kiali 3,631 Istio service-mesh observability — inspired our circuit-breaker badges and error-edge visuals in the Routing/Combo Studio. lobe-icons 2,428 AI/LLM brand logos that render the provider icons across our dashboard. flag-icons 12,354 Provides the MIT-licensed SVG flags used by the README language selector.
### 🛡️ Security
Project ⭐ How it inspired OmniRoute awesome-secure-defaults 710 A curated list of secure-by-default libraries that guides our security choices (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink). awesome-secure-defaults 721 A curated list of secure-by-default libraries that guides our security choices (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink).
### 🧭 Complementary tools
Project ⭐ How it inspired OmniRoute ClawRouter 6,564 Inspired request deduplication, emergency zero-cost fallback, pluggable Auto-Combo strategies and multilingual intent classification. Antigravity-Manager 30,652 Its account-aware model remapping, executable-path validation and plan-label behavior informed OmniRoute's Antigravity runtime. vscode-antigravity-cockpit 4,817 Its compact quota-reset countdown format inspired the corresponding provider-limit display in OmniRoute. AionUi 32,230 Its ACP integrations inspired OmniRoute's automatic detection of installed CLI agents. CodexBar 20,507 Identified the Grok Build quota surface; OmniRoute then verified and corrected the live wire format independently.
## 📄 License
@@ -1589,7 +1666,7 @@ MIT License - see [LICENSE](LICENSE) for details.
**[⬆ Back to top](#-omniroute)** · Built with ❤️ for the open-source AI community.
-OmniRoute v3.8.49 · Node ≥22.22.2 · MIT License · omniroute.online
+OmniRoute v3.8.50 · Node ≥22.22.2 · MIT License · omniroute.online
diff --git a/changelog.d/maintenance/11356-readme-live-metrics.md b/changelog.d/maintenance/11356-readme-live-metrics.md
new file mode 100644
index 0000000000..3d06965062
--- /dev/null
+++ b/changelog.d/maintenance/11356-readme-live-metrics.md
@@ -0,0 +1,5 @@
+- **docs(readme):** reconcile live v3.8.50 provider, free-tier, CLI, routing, test,
+ community, sponsor, acknowledgment, and SVG metrics with their audited source
+ denominators, including a deduplicated OmniRoute-in-Action snapshot and distinct
+ contributor rankings for merged pull requests, GitHub-attributed commits, and Git history
+ ([#11356](https://github.com/diegosouzapw/OmniRoute/pull/11356)).
diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md
index 7b6fd18f9a..ccd553555c 100644
--- a/docs/diagrams/README.md
+++ b/docs/diagrams/README.md
@@ -16,7 +16,7 @@ Mermaid sources (`.mmd`) and exported SVGs for OmniRoute v3.8.0 architecture flo
| [auto-combo-12factor.mmd](./auto-combo-12factor.mmd) | [SVG](./exported/auto-combo-12factor.svg) | docs/routing/AUTO-COMBO.md |
| [resilience-3layers.mmd](./resilience-3layers.mmd) | [SVG](./exported/resilience-3layers.svg) | docs/architecture/RESILIENCE_GUIDE.md, CLAUDE.md |
| [i18n-flow.mmd](./i18n-flow.mmd) | [SVG](./exported/i18n-flow.svg) | docs/guides/I18N.md |
-| [mcp-tools-107.mmd](./mcp-tools-107.mmd) | [SVG](./exported/mcp-tools-107.svg) | docs/frameworks/MCP-SERVER.md |
+| [mcp-tools-107.mmd](./mcp-tools-107.mmd) | [SVG](./exported/mcp-tools-107.svg) | docs/frameworks/MCP-SERVER.md |
| [cloud-agent-flow.mmd](./cloud-agent-flow.mmd) | [SVG](./exported/cloud-agent-flow.svg) | docs/frameworks/CLOUD_AGENT.md |
| [authz-pipeline.mmd](./authz-pipeline.mmd) | [SVG](./exported/authz-pipeline.svg) | docs/architecture/AUTHZ_GUIDE.md |
| [db-schema-overview.mmd](./db-schema-overview.mmd) | [SVG](./exported/db-schema-overview.svg) | docs/architecture/CODEBASE_DOCUMENTATION.md |
@@ -34,11 +34,11 @@ inside GitHub's `
+
Compact animated terminal cycling three real OmniRoute CLI commands with a typewriter effect and a scrolling subcommand ticker; the first frame shows the completed providers-list screen.
omniroute — 80+ commands
-omniroute providers list OmniRoute Providers 1f3a9c2e anthropic Claude Max 20x active 8c2d5b1a codex Codex Pro (team) active f4e0a97b glm GLM Coding Plan active 03bd6e5f kimi Kimi K2 free active … 334 more providers
+omniroute — 85 top-level commands
+omniroute providers list OmniRoute Providers 1f3a9c2e anthropic Claude Max 20x active 8c2d5b1a codex Codex Pro (team) active f4e0a97b glm GLM Coding Plan active 03bd6e5f kimi Kimi K2 free active … 346 more providers
$
omniroute providers list active active active active active active active active
$
@@ -32,11 +32,11 @@
healthy Uptime: 4d 12h 33m● 24 closed ◒ 1 half-open ○ 0 open healthy Uptime: 4d 12h 33m● 24 closed ◒ 1 half-open ○ 0 open
providers · oauth · keys · combo · nodes · models · cache · compression · cost · usage · quota · health · resilience · telemetry · logs · audit · mcp · a2a · cloud · memory · skills · eval · doctor · repl · tunnel · backup · sync · webhooks · policy · pricing · translator · simulate …providers · oauth · keys · combo · nodes · models · cache · compression · cost · usage · quota · health · resilience · telemetry · logs · audit · mcp · a2a · cloud · memory · skills · eval · doctor · repl · tunnel · backup · sync · webhooks · policy · pricing · translator · simulate …
\ No newline at end of file
+
diff --git a/docs/diagrams/comparison-table.svg b/docs/diagrams/comparison-table.svg
index 24018c7fed..fbbef865f5 100644
--- a/docs/diagrams/comparison-table.svg
+++ b/docs/diagrams/comparison-table.svg
@@ -23,7 +23,7 @@
Providers
- 338
+ 350
40+
400+*
~5
@@ -57,7 +57,7 @@
Built-in MCP server (own tools)
- 109
+ 110
13-factor scoring weights (sum = 1.0)
resetWindowAffinity (0.00)
Eligible candidates
Compute composite score
Dispatch sequentially
OmniRoute Auto-Combo 15-factor scoring Flow from an incoming request through eligible candidates, the 15 weighted scoring factors, descending score sort, top-N selection, and sequential dispatch.
15-factor scoring weights (sum = 1.0)
specificityMatch (0.0476)
sessionAvailability (0.0476)
resetWindowAffinity (0.0000)
connectionDensity (0.0476)
Eligible candidates
Compute composite score
Dispatch sequentially
+
+ Pool-deduplicated chart of the 20 recurring free-token pools with positive published budgets, plus signup credits and uncapped providers shown separately.
~1.51B
FREE TOKENS / MONTH · STEADY
up to ~2.13B in your first month — signup credits
- documented free tiers · 40 provider pools · 495 models · one endpoint
+ documented free tiers · 40 recurring pools · 455 catalog entries · one endpoint
counted once ✓
15 providers ToS-flagged — we flag it · you decide WHERE IT COMES FROM · 19 COUNTABLE FREE POOLS
+
+ WHERE IT COMES FROM · 20 QUANTIFIED RECURRING POOLS
-
- each segment = one free pool · widths floored so every provider shows · honest numbers below
+ each segment = one recurring pool · widths floored so every pool shows · audited pool budgets below
-
+
- Mistral Large 3 1.00B
- GPT-4o mini 150M
- Gemini 2.5 Flash 60M
- GLM 4.7 30M
- Llama 3.3 70B 30M
- Grok-3 24M
- DeepSeek V4 Pro 20M
- GPT-4.1 18M
- Llama 4 Scout 15M
- GPT-4o 7M
- MiniMax-M2.7 6M
- Arcee Trinity Large Prev 5M
- Auto Free 4M
- Auto 1M
- Command A Reasoning 800K
- ERNIE 4.5 VL 424B 500K
- morph-v3-large 400K
- Llama 3.1 8B 200K
- Claude Sonnet 4.5 25K
+ Mistral 1.00B
+ LLM7 150M
+ Nara 150M
+ Gemini 60M
+ Cerebras 30M
+ Cloudflare AI 30M
+ API Airforce 24M
+ Ollama Cloud 20M
+ Groq 15M
+ Bluesminds 7.2M
+ SambaNova 6M
+ Arcee 4.8M
+ Navy 4.5M
+ BazaarLink 3.6M
+ OpenRouter 1.2M
+ Cohere 800K
+ HuggingChat 500K
+ Morph 400K
+ Hugging Face 200K
+ Kiro 25K
diff --git a/docs/diagrams/promise-pillars.svg b/docs/diagrams/promise-pillars.svg
index f0d30f74a3..232065d928 100644
--- a/docs/diagrams/promise-pillars.svg
+++ b/docs/diagrams/promise-pillars.svg
@@ -1,4 +1,4 @@
-
+
Animated promise card: six pillar tiles fade in in reading order, then a soft colored border highlight sweeps from tile to tile in a continuous cycle.
@@ -40,7 +40,7 @@
Never hit limits
Auto-fallback across 350 providers in
milliseconds. Quota out? The next provider
- takes over — zero downtime.
+ takes over while a healthy target remains.
Every tool works
- 33 coding agents — Claude Code, Codex,
+ 35 CLI/agent integrations — Claude Code, Codex,
Cursor, Cline, Copilot, Antigravity —
through one config.
@@ -127,7 +127,7 @@
Production-grade
Circuit breakers, TLS stealth, MCP (110
tools), A2A, memory, guardrails, evals —
- 25,000+ tests.
+ 39,000+ static test declarations.
diff --git a/docs/diagrams/readme-hero.svg b/docs/diagrams/readme-hero.svg
index e3faa34758..52e4d168db 100644
--- a/docs/diagrams/readme-hero.svg
+++ b/docs/diagrams/readme-hero.svg
@@ -66,7 +66,7 @@
338
+ 350
AI PROVIDERS
90+
diff --git a/docs/diagrams/resilience-layers.svg b/docs/diagrams/resilience-layers.svg
index 022e35f365..369277e0fb 100644
--- a/docs/diagrams/resilience-layers.svg
+++ b/docs/diagrams/resilience-layers.svg
@@ -17,6 +17,6 @@
The right layer for the right failure — never kill more than what actually broke .
PROVIDER CONNECTION / KEY MODEL LAYER 1 · SCOPE: WHOLE PROVIDER Provider circuit breaker isolate a provider failing upstream — reroute now, auto-probe to recover trips only on 408 · 500 · 502 · 503 · 504 threshold — oauth 3× · api-key 5× · local 2× reset — 60s · 30s · 15s → HALF-OPEN probe lazy recovery — reads refresh expired state router provider A fails ×15 provider B ← next CLOSED OPEN HALF-OPEN LAYER 2 · SCOPE: ONE KEY / ACCOUNT Connection cooldown skip one rate-limited key while the other keys keep serving the provider base cooldown — oauth 5s · api-key 3s repeat fails — backoff ×2 (anti-herd guard) 429 honors Retry-After / reset headers success → clearAccountError() resets all provider · 3 keys key-1 429 key-2 key-3 cooling ×2ⁿ LAYER 3 · SCOPE: ONE MODEL Model lockout quarantine a single model — never kill the whole connection for one 429 scope — provider + connection + model per-model 429 · local 404 · mode denials locked model ≠ dead key other models keep serving instantly key-1 model-a model-b model-c LAYER 1 · SCOPE: WHOLE PROVIDER Provider circuit breaker isolate a provider failing upstream — reroute now, auto-probe to recover trips only on 408 · 500 · 502 · 503 · 504 threshold — oauth 10× · api-key 15× · local 2× reset — 60s · 30s · 15s → HALF-OPEN probe lazy recovery — reads refresh expired state router provider A fails ×15 provider B ← next CLOSED OPEN HALF-OPEN LAYER 2 · SCOPE: ONE KEY / ACCOUNT Connection cooldown skip one rate-limited key while the other keys keep serving the provider base cooldown — oauth 5s · api-key 3s repeat fails — backoff ×2 (anti-herd guard) 429 honors Retry-After / reset headers success → clearAccountError() resets all provider · 3 keys key-1 429 key-2 key-3 cooling ×2ⁿ LAYER 3 · SCOPE: ONE MODEL Model lockout quarantine a single model — never kill the whole connection for one 429 scope — provider + connection + model per-model 429 · local 404 · mode denials locked model ≠ dead key other models keep serving instantly key-1 model-a model-b model-c which failure trips what → 5xx / 408 : breaker · key 429 / 401 : cooldown · one-model 429 / 404 : lockout · banned / expired / credits : terminal (operator)
\ No newline at end of file
diff --git a/docs/diagrams/strategies-grid.svg b/docs/diagrams/strategies-grid.svg
index d518f85d06..1706f36e7e 100644
--- a/docs/diagrams/strategies-grid.svg
+++ b/docs/diagrams/strategies-grid.svg
@@ -95,7 +95,7 @@
auto
72 91 64 55 live 13-factor scoring
+live 15-factor scoring
fusion
diff --git a/docs/getting-started/FREE-TIERS-GUIDE.md b/docs/getting-started/FREE-TIERS-GUIDE.md
index 6fd9dcc35b..400343affe 100644
--- a/docs/getting-started/FREE-TIERS-GUIDE.md
+++ b/docs/getting-started/FREE-TIERS-GUIDE.md
@@ -1,6 +1,6 @@
# Free Tiers Guide: Understand and Combine Free AI Access
-> **TL;DR**: OmniRoute registers 329 providers, with **155 catalog entries marked free/no-auth**. The stricter audited budget currently covers **43 recurring pools / 522 model budget entries**. Connect several suitable providers for broader fallback capacity; every quota, approval rule, privacy policy, and paid-overage condition still applies.
+> **TL;DR**: OmniRoute registers 350 provider IDs, with **154 provider-catalog entries marked `hasFree`**. The stricter audited free-model catalog covers **40 recurring pool keys / 455 entries** (448 active + 7 discontinued). Connect several suitable providers for broader fallback capacity; every quota, approval rule, privacy policy, and paid-overage condition still applies.
---
@@ -21,38 +21,38 @@ OmniRoute **aggregates** these free tiers into one endpoint. Instead of signing
These providers have a recurring, keyless, or uncapped free-access path in the audited catalog. “Uncapped” means no published token cap; rate, concurrency, account, regional, and policy limits can still apply:
-| Provider | Models | Quota | How to Connect |
-|----------|--------|-------|----------------|
-| **Kiro AI** | Claude Sonnet 4.5, Haiku 4.5, DeepSeek V3.2, and others | Audited catalog estimates a 25K-token shared monthly pool | OAuth/account flow; ToS flagged `avoid` in the catalog |
-| **OpenCode Free** | Current `*-free` model set in the provider registry | Keyless; no published token cap | No provider credential; ToS flagged `avoid` |
-| **Pollinations** | Current keyless model set; some former models are discontinued or key-required | Keyless; no published token cap | No provider credential for the keyless models |
-| **Logfare** | kimi-k3, deepseek-v4-pro, glm-5.2, gpt-5.6-luna, minimax-m3, and more | Free API key (no rate limits, no card); **every request is logged** for research (opt out at logfare.ai/consent) | Instant key at logfare.ai/register; ToS/privacy at logfare.ai/tos and logfare.ai/privacy |
-| **Cloudflare AI** | Workers AI catalog | Audited pool estimates ~30M tokens/month from published usage units | Cloudflare account and API credentials |
-| **Gemini** | Gemini Flash family | Audited pool estimates ~60M tokens/month | Google AI Studio API key; rate limits apply |
-| **Groq** | Llama, GPT-OSS, and Qwen models | Audited pool estimates ~15M tokens/month | Groq API key; rate limits apply |
-| **Cerebras** | GLM 4.7 and GPT-OSS 120B | Audited pool estimates ~30M tokens/month | Cerebras API key; rate limits apply |
+| Provider | Models | Quota | How to Connect |
+| ----------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **Kiro AI** | Claude Sonnet 4.5, Haiku 4.5, DeepSeek V3.2, and others | Audited catalog estimates a 25K-token shared monthly pool | OAuth/account flow; ToS flagged `avoid` in the catalog |
+| **OpenCode Free** | Current `*-free` model set in the provider registry | Keyless; no published token cap | No provider credential; ToS flagged `avoid` |
+| **Pollinations** | Current keyless model set; some former models are discontinued or key-required | Keyless; no published token cap | No provider credential for the keyless models |
+| **Logfare** | kimi-k3, deepseek-v4-pro, glm-5.2, gpt-5.6-luna, minimax-m3, and more | Free API key (no rate limits, no card); **every request is logged** for research (opt out at logfare.ai/consent) | Instant key at logfare.ai/register; ToS/privacy at logfare.ai/tos and logfare.ai/privacy |
+| **Cloudflare AI** | Workers AI catalog | Audited pool estimates ~30M tokens/month from published usage units | Cloudflare account and API credentials |
+| **Gemini** | Gemini Flash family | Audited pool estimates ~60M tokens/month | Google AI Studio API key; rate limits apply |
+| **Groq** | Llama, GPT-OSS, and Qwen models | Audited pool estimates ~15M tokens/month | Groq API key; rate limits apply |
+| **Cerebras** | GLM 4.7 and GPT-OSS 120B | Audited pool estimates ~30M tokens/month | Cerebras API key; rate limits apply |
### Signup Grants and Provider-Specific Credits
These providers give you **free credits** when you sign up:
-| Provider | Free Credits | Models | How to Get |
-|----------|-------------|--------|------------|
-| **DeepSeek** | 5M free tokens | DeepSeek V4 | Sign up at platform.deepseek.com |
-| **LongCat** | 10M-token one-time grant | LongCat 2.0 | API key + KYC; pay-as-you-go after the grant |
-| **Together** | $25 signup credit represented as ~25M tokens in the budget model | Provider catalog | Sign up and verify current terms |
+| Provider | Free Credits | Models | How to Get |
+| ------------- | ------------------------------------------------------------------ | ------------------------- | --------------------------------------------------------- |
+| **DeepSeek** | 5M free tokens | DeepSeek V4 | Sign up at platform.deepseek.com |
+| **LongCat** | 10M-token one-time grant | LongCat 2.0 | API key + KYC; pay-as-you-go after the grant |
+| **Together** | $25 signup credit represented as ~25M tokens in the budget model | Provider catalog | Sign up and verify current terms |
| **Vertex AI** | $300 signup credit represented as ~300M tokens in the budget model | Gemini and partner models | Google Cloud account; billing and eligibility rules apply |
### Other Limited Access
These providers have **free tiers** with specific limits:
-| Provider | Free Limit | Models | Best For |
-|----------|-----------|--------|----------|
-| **GitHub Models** | Audited shared pool estimates ~18M tokens/month | Broad model evaluation |
-| **Hugging Face** | Small recurring monthly pool | Experiments and model variety |
-| **OpenRouter free models** | Shared request-limited pool; optional one-time top-up increases the recurring allowance | Broad fallback catalog |
-| **AI Horde** | Keyless community capacity; availability varies | Opportunistic distributed inference |
+| Provider | Free Limit | Models | Best For |
+| -------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------- | -------- |
+| **GitHub Models** | Audited shared pool estimates ~18M tokens/month | Broad model evaluation |
+| **Hugging Face** | Small recurring monthly pool | Experiments and model variety |
+| **OpenRouter free models** | Shared request-limited pool; optional one-time top-up increases the recurring allowance | Broad fallback catalog |
+| **AI Horde** | Keyless community capacity; availability varies | Opportunistic distributed inference |
---
@@ -70,6 +70,7 @@ Connect several providers to reduce dependence on any single quota:
4. **LongCat** — one-time signup grant (requires KYC)
Then use `model: "auto"` and OmniRoute will:
+
- Try the highest-ranked eligible connection first
- If its quota or health check fails → try the next configured provider
- If the keyless provider is unavailable → continue through the remaining targets
@@ -135,6 +136,7 @@ If one free provider is busy or down, OmniRoute automatically tries the next one
### 2. Smart Routing
OmniRoute picks the **best free provider** for each request based on:
+
- Speed — Which provider is fastest right now?
- Quality — Which provider is best for this task?
- Capacity — Which provider has quota remaining?
@@ -157,13 +159,13 @@ provider's quota or access policy.
The live, pool-deduplicated catalog currently reports:
-| Metric | Current audited value | Interpretation |
-| --- | ---: | --- |
-| Recurring quantified grant | **~1.53B tokens/month** | Shared pools counted once; excludes uncapped providers from the sum |
-| First month with signup grants | **~2.15B tokens** | Recurring total plus one-time and recurring credits |
-| Quantified inventory | **43 pools / 522 model budget entries** | Budget-model coverage, not the full 329-provider catalog |
-| Recurring/keyless/uncapped providers represented | **58** | Provider presence in recurring forms of the audited budget catalog |
-| Free/no-auth discovery entries | **155** | Broader provider metadata; not all have a quantifiable recurring quota |
+| Metric | Current audited value | Interpretation |
+| ---------------------------------------------------- | -----------------------------------------------: | ----------------------------------------------------------------------------------------- |
+| Recurring quantified grant | **~1.51B tokens/month** | Shared pools counted once; excludes uncapped providers from the sum |
+| First month with signup grants | **~2.13B tokens** | Recurring total plus one-time and recurring credits |
+| Audited free-model inventory | **40 recurring pool keys / 455 catalog entries** | 448 active + 7 discontinued; distinct from the 350-provider catalog |
+| Recurring/keyless free-forever providers represented | **56** | Unique providers across recurring daily/monthly/credit/uncapped and keyless catalog types |
+| Provider catalog entries marked `hasFree` | **154 / 350** | Broader provider metadata; not all have a quantifiable recurring quota |
These values are computed from `open-sse/config/freeModelCatalog.ts`; see the
[Free Tiers Reference](../reference/FREE_TIERS.md) for pool deduplication, ToS flags,
diff --git a/docs/routing/AUTO-COMBO.md b/docs/routing/AUTO-COMBO.md
index bad9aa43dd..eacd1a700b 100644
--- a/docs/routing/AUTO-COMBO.md
+++ b/docs/routing/AUTO-COMBO.md
@@ -183,30 +183,31 @@ See [#7992](https://github.com/diegosouzapw/OmniRoute/issues/7992) and [#7111](h
## How It Works (Persisted Auto-Combos)
-The Auto-Combo Engine dynamically selects the best provider/model for each request using a **14-factor scoring function** (defined in `open-sse/services/autoCombo/scoring.ts` → `DEFAULT_WEIGHTS`). Weights form a normalized distribution (custom weights are renormalized by `normalizeScoringWeights()`).
+The Auto-Combo Engine dynamically selects the best provider/model for each request using a **15-factor scoring function** (defined in `open-sse/services/autoCombo/scoring.ts` → `DEFAULT_WEIGHTS`). The default weights sum to `1.0`; custom weights are renormalized by `normalizeScoringWeights()`.
-
+
-> Source: [diagrams/auto-combo-12factor.mmd](../diagrams/auto-combo-12factor.mmd) (regenerate via `npm run docs:render-diagrams`). The filename predates the current factor set; the diagram shows 13 of the 14 factors (missing `sessionAvailability`).
+> Source: [diagrams/auto-combo-12factor.mmd](../diagrams/auto-combo-12factor.mmd) (regenerate via `npm run docs:render-diagrams`). The filename is historical; the source and rendered diagram show all 15 factors declared in `DEFAULT_WEIGHTS`.
| Factor | Default Weight | Description |
| :-------------------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `health` | 0.20 | Health score from circuit breaker (CLOSED=1.0, HALF_OPEN=0.5, OPEN=0.0) |
-| `quota` | 0.15 | Remaining quota / rate-limit headroom [0..1] |
-| `costInv` | 0.15 | Inverse **blended** cost (60% input + 40% output token price, normalized) — cheaper = higher score |
-| `latencyInv` | 0.12 | Inverse p95 latency normalized to pool — faster = higher score |
-| `taskFit` | 0.08 | Task-type fitness (coding, review, planning, analysis, debugging, docs) |
-| `stability` | 0.05 | Variance-based stability (low latency stdDev / error rate) |
-| `tierPriority` | 0.05 | Account-tier priority — Ultra=1.0, Pro=0.67, Standard=0.33, Free=0.0 |
-| `tierAffinity` | 0.05 | Affinity between the candidate's tier and the manifest-recommended tier |
-| `specificityMatch` | 0.05 | Match between request specificity (manifest hint) and model tier |
-| `contextAffinity` | 0.05 | Affinity between the request's context-window need and the model's context window |
-| `sessionAvailability` | 0.05 | OAuth session availability of the candidate connection for this session (`getOAuthSessionAvailability()`; non-OAuth connections score 1.0) |
-| `connectionDensity` | 0.05 | Spreads load across connections of the same provider (anti-concentration) |
+| `quota` | 0.1429 | Remaining quota / rate-limit headroom [0..1] |
+| `health` | 0.1605 | Health score from circuit breaker (CLOSED=1.0, HALF_OPEN=0.5, OPEN=0.0) |
+| `costInv` | 0.1429 | Inverse **blended** cost (60% input + 40% output token price, normalized) — cheaper = higher score |
+| `latencyInv` | 0.1143 | Inverse p95 latency normalized to pool — faster = higher score |
+| `taskFit` | 0.0762 | Task-type fitness (coding, review, planning, analysis, debugging, docs) |
+| `stability` | 0.0476 | Variance-based stability (low latency stdDev / error rate) |
+| `tierPriority` | 0.0476 | Account-tier priority — Ultra=1.0, Pro=0.67, Standard=0.33, Free=0.0 |
+| `tierAffinity` | 0.0476 | Affinity between the candidate's tier and the manifest-recommended tier |
+| `specificityMatch` | 0.0476 | Match between request specificity (manifest hint) and model tier |
+| `contextAffinity` | 0.0476 | Affinity between the request's context-window need and the model's context window |
+| `sessionAvailability` | 0.0476 | OAuth session availability of the candidate connection for this session (`getOAuthSessionAvailability()`; non-OAuth connections score 1.0) |
+| `connectionDensity` | 0.0476 | Spreads load across connections of the same provider (anti-concentration) |
| `cacheAffinity` | 0.00 | Rendezvous-hash affinity toward the connection likeliest to already hold this request's prompt-cache prefix (`open-sse/services/combo/promptCacheAffinity.ts`); disabled by default (#8008) |
| `resetWindowAffinity` | 0.00 | Bias toward connections whose quota reset window is favorable (disabled by default) |
+| `quality` | 0.03 | Feedback-driven output-quality signal from the routing-event quality tracker; candidates without observations receive a neutral 0.5 |
-**Sum:** `0.20 + 0.15 + 0.15 + 0.12 + 0.08 + 0.05 + 0.05 + 0.05 + 0.05 + 0.05 + 0.05 + 0.05 + 0.00 + 0.00 = 1.05` as literally declared in `DEFAULT_WEIGHTS`; user-configured weights are renormalized into a distribution by `normalizeScoringWeights()` before scoring.
+**Sum:** `0.1429 + 0.1605 + 0.1429 + 0.1143 + 0.0762 + (7 × 0.0476) + 0.00 + 0.00 + 0.03 = 1.0` as declared in `DEFAULT_WEIGHTS`; user-configured weights are renormalized into a distribution by `normalizeScoringWeights()` before scoring.
## Mode Packs
@@ -677,8 +678,8 @@ Including the bare `auto` (default) plus the 6 `AutoVariant` values declared in
## How tiers fit Auto-Combo
-The 14-factor scoring function (`open-sse/services/autoCombo/scoring.ts`) treats tier
-membership as two signals: `tierPriority` (0.05) and `tierAffinity` (0.05). See the
+The 15-factor scoring function (`open-sse/services/autoCombo/scoring.ts`) treats tier
+membership as two signals: `tierPriority` (0.0476) and `tierAffinity` (0.0476). See the
canonical [scoring factor table](#how-it-works-persisted-auto-combos) above for the full
`DEFAULT_WEIGHTS` set — the per-pack overrides (ship-fast/cost-saver/quality-first/
offline-friendly) are listed in the "Weight profiles per pack" table.
diff --git a/docs/screenshots/free-tier-budget-card.svg b/docs/screenshots/free-tier-budget-card.svg
index 4a861867d6..42bf89d20c 100644
--- a/docs/screenshots/free-tier-budget-card.svg
+++ b/docs/screenshots/free-tier-budget-card.svg
@@ -1,77 +1,80 @@
-
+
Static dashboard preview of recurring token pools, first-month signup grants, and uncapped but rate-limited free-access providers.
OmniRoute · /dashboard/free-tiers · preview mockup
Monthly free-token budget
-43 provider pools · 522 model entries · one endpoint
+40 recurring pools · 455 catalog entries · one endpoint
Steady / month
-~1.53B
+~1.51B
First month (+ signup credits)
-~2.15B
+~2.13B
ToS-flagged (you decide)
15 providers
Each segment = one of 19 quantified recurring pools · 43 total pools / 522 entries in the audited catalog.
+Each segment = one of 20 quantified recurring pools · 40 pools / 455 entries in the audited catalog.
Mistral Large 3 1.00B
+Mistral 1.00B
GPT-4o mini 150M
+LLM7 150M
Gemini 2.5 Flash 60M
+Nara 150M
GLM 4.7 30M
+Gemini 60M
Llama 3.3 70B 30M
+Cerebras 30M
Grok-3 24M
+Cloudflare AI 30M
DeepSeek V4 Pro 20M
+API Airforce 24M
GPT-4.1 18M
+Ollama Cloud 20M
Llama 4 Scout 15M
+Groq 15M
GPT-4o 7M
+Bluesminds 7.2M
MiniMax-M2.7 6M
+SambaNova 6M
Arcee Trinity Large Prev 5M
+Arcee 4.8M
Auto Free 4M
+Navy 4.5M
Auto 1M
+BazaarLink 3.6M
Command A Reasoning 800K
+OpenRouter 1.2M
ERNIE 4.5 VL 424B 500K
+Cohere 800K
morph-v3-large 400K
+HuggingChat 500K
Llama 3.1 8B 200K
+Morph 400K
Claude Sonnet 4.5 25K
+Hugging Face 200K
+Kiro 25K
+ First month: one-time signup credits (~626M)
nscale 5M
Pool-deduped, honest counting — no inflated rate-limit ceilings. Some terms suggest personal-use only; we flag them so you decide.
-+ 13 recurring uncapped* providers (rate/concurrency-limited) · OpenRouter $10 → +24M/mo.
++ 14 recurring uncapped* providers (rate/concurrency-limited) · OpenRouter $10 → +24M/mo.
diff --git a/scripts/docs/render-diagrams.mjs b/scripts/docs/render-diagrams.mjs
index 01cd7c7377..148013adb8 100644
--- a/scripts/docs/render-diagrams.mjs
+++ b/scripts/docs/render-diagrams.mjs
@@ -18,11 +18,13 @@
* gate on it.
*/
import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { tmpdir } from "node:os";
+import { ensureSvgAccessibility, validateSvgFile } from "./validate-svg.mjs";
+
const __dirname = dirname(fileURLToPath(import.meta.url));
const repoRoot = resolve(__dirname, "..", "..");
const srcDir = resolve(repoRoot, "docs", "diagrams");
@@ -75,6 +77,31 @@ for (const src of sources) {
if (result.status !== 0) {
console.error(` [FAIL] ${src} (exit ${result.status})`);
failures += 1;
+ continue;
+ }
+
+ const source = readFileSync(input, "utf8");
+ const title = source.match(/^%%\s*svg-title:\s*(.+)$/im)?.[1]?.trim();
+ const description = source.match(/^%%\s*svg-description:\s*(.+)$/im)?.[1]?.trim();
+ if (title && description) {
+ const svg = readFileSync(output, "utf8");
+ writeFileSync(
+ output,
+ ensureSvgAccessibility(svg, {
+ title,
+ description,
+ idBase: src.replace(/\.mmd$/, ""),
+ })
+ );
+ } else if (title || description) {
+ console.warn(` [WARN] ${src}: svg-title and svg-description must be provided together`);
+ }
+
+ const validation = validateSvgFile(output);
+ for (const warning of validation.warnings) console.warn(` [WARN] ${src}: ${warning}`);
+ if (validation.errors.length > 0) {
+ for (const error of validation.errors) console.error(` [FAIL] ${src}: ${error}`);
+ failures += 1;
}
}
diff --git a/scripts/docs/validate-svg.mjs b/scripts/docs/validate-svg.mjs
new file mode 100644
index 0000000000..b3c65b07f6
--- /dev/null
+++ b/scripts/docs/validate-svg.mjs
@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { XMLParser, XMLValidator } from "fast-xml-parser";
+
+const parser = new XMLParser({
+ ignoreAttributes: false,
+ attributeNamePrefix: "@_",
+ preserveOrder: true,
+});
+
+function collectIds(value, ids) {
+ if (Array.isArray(value)) {
+ for (const entry of value) collectIds(entry, ids);
+ return;
+ }
+ if (!value || typeof value !== "object") return;
+
+ const attributes = value[":@"];
+ if (attributes && typeof attributes === "object" && typeof attributes["@_id"] === "string") {
+ ids.push(attributes["@_id"]);
+ }
+ for (const entry of Object.values(value)) collectIds(entry, ids);
+}
+
+function escapeXml(value) {
+ return value
+ .replaceAll("&", "&")
+ .replaceAll("<", "<")
+ .replaceAll(">", ">")
+ .replaceAll('"', """)
+ .replaceAll("'", "'");
+}
+
+function replaceRootAttribute(openingTag, name, value) {
+ const attribute = new RegExp(`\\s${name}=(?:"[^"]*"|'[^']*')`, "i");
+ const withoutExisting = openingTag.replace(attribute, "");
+ return withoutExisting.replace(/>$/, ` ${name}="${escapeXml(value)}">`);
+}
+
+function escapeRegExp(value) {
+ return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function ensureSvgAccessibility(svg, { title, description, idBase }) {
+ const xmlResult = XMLValidator.validate(svg);
+ if (xmlResult !== true) throw new Error(`invalid XML: ${xmlResult.err.msg}`);
+
+ const titleId = `${idBase}-title`;
+ const descriptionId = `${idBase}-desc`;
+ const priorTitle = new RegExp(
+ `]*\\bid=["']${escapeRegExp(titleId)}["'][^>]*>[\\s\\S]*?<\\/title>`,
+ "i"
+ );
+ const priorDescription = new RegExp(
+ `]*\\bid=["']${escapeRegExp(descriptionId)}["'][^>]*>[\\s\\S]*?<\\/desc>`,
+ "i"
+ );
+ const withoutPriorAccessibleName = svg.replace(priorTitle, "").replace(priorDescription, "");
+ const match = withoutPriorAccessibleName.match(/]*>/i);
+ if (!match) throw new Error("document root is not an SVG element");
+
+ let openingTag = replaceRootAttribute(match[0], "role", "img");
+ openingTag = replaceRootAttribute(openingTag, "aria-labelledby", `${titleId} ${descriptionId}`);
+ const accessibleName =
+ `${escapeXml(title)} ` +
+ `${escapeXml(description)} `;
+
+ return withoutPriorAccessibleName.replace(match[0], `${openingTag}${accessibleName}`);
+}
+
+export function validateSvgText(svg) {
+ const xmlResult = XMLValidator.validate(svg);
+ if (xmlResult !== true) {
+ return { errors: [`invalid XML: ${xmlResult.err.msg}`], warnings: [] };
+ }
+
+ const document = parser.parse(svg);
+ const ids = [];
+ collectIds(document, ids);
+ const duplicates = [...new Set(ids.filter((id, index) => ids.indexOf(id) !== index))].sort();
+
+ const openingTag = svg.match(/]*>/i)?.[0] ?? "";
+ const warnings = [];
+ if (!/\srole=["']img["']/i.test(openingTag)) warnings.push('root role is not "img"');
+ const hasAccessibleName =
+ /\saria-(?:label|labelledby)=["'][^"']+["']/i.test(openingTag) ||
+ /]*>[^<]+<\/title>/i.test(svg);
+ if (!hasAccessibleName) {
+ warnings.push("missing accessible name (title, aria-label, or aria-labelledby)");
+ }
+ if (!/]*>[^<]+<\/desc>/i.test(svg)) warnings.push("missing desc element");
+ if (/ 0 ? [`duplicate IDs: ${duplicates.join(", ")}`] : [],
+ warnings,
+ };
+}
+
+export function validateSvgFile(file) {
+ return validateSvgText(readFileSync(file, "utf8"));
+}
+
+function isDirectExecution() {
+ if (!process.argv[1]) return false;
+ return fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+}
+
+if (isDirectExecution()) {
+ const args = process.argv.slice(2);
+ let fixAccessibility = false;
+ let title;
+ let description;
+ const files = [];
+ for (let index = 0; index < args.length; index += 1) {
+ const arg = args[index];
+ if (arg === "--fix-a11y") {
+ fixAccessibility = true;
+ } else if (arg === "--title") {
+ title = args[++index];
+ } else if (arg === "--description") {
+ description = args[++index];
+ } else {
+ files.push(arg);
+ }
+ }
+ if (files.length === 0) {
+ console.error(
+ "Usage: node scripts/docs/validate-svg.mjs [--fix-a11y --title TEXT --description TEXT] [...]"
+ );
+ process.exit(2);
+ }
+
+ if (fixAccessibility && (!title || !description)) {
+ console.error("--fix-a11y requires both --title and --description");
+ process.exit(2);
+ }
+
+ let failures = 0;
+ for (const file of files) {
+ if (fixAccessibility) {
+ const idBase = path.basename(file, path.extname(file));
+ const updated = ensureSvgAccessibility(readFileSync(file, "utf8"), {
+ title,
+ description,
+ idBase,
+ });
+ writeFileSync(file, updated);
+ }
+ const result = validateSvgFile(file);
+ for (const warning of result.warnings) console.warn(`WARN ${file}: ${warning}`);
+ if (result.errors.length === 0) {
+ console.log(`PASS ${file}`);
+ continue;
+ }
+ failures += 1;
+ for (const error of result.errors) console.error(`FAIL ${file}: ${error}`);
+ }
+ if (failures > 0) process.exit(1);
+}
diff --git a/tests/unit/docs-validate-svg.test.ts b/tests/unit/docs-validate-svg.test.ts
new file mode 100644
index 0000000000..a53ff75afd
--- /dev/null
+++ b/tests/unit/docs-validate-svg.test.ts
@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const validator = path.resolve(here, "../../scripts/docs/validate-svg.mjs");
+
+test("SVG validator ignores Mermaid data-id attributes when checking duplicate IDs", () => {
+ const fixtureDir = mkdtempSync(path.join(tmpdir(), "omniroute-svg-validator-"));
+ const fixture = path.join(fixtureDir, "mermaid.svg");
+ writeFileSync(
+ fixture,
+ '' +
+ "Fixture diagram. " +
+ ' "
+ );
+
+ try {
+ const result = spawnSync(process.execPath, [validator, fixture], { encoding: "utf8" });
+ assert.equal(result.status, 0, `${result.stdout}${result.stderr}`);
+ assert.match(result.stdout, /PASS/);
+ assert.doesNotMatch(`${result.stdout}${result.stderr}`, /WARN/);
+ } finally {
+ rmSync(fixtureDir, { recursive: true, force: true });
+ }
+});
+
+test("SVG validator rejects duplicate XML id attributes", () => {
+ const fixtureDir = mkdtempSync(path.join(tmpdir(), "omniroute-svg-validator-"));
+ const fixture = path.join(fixtureDir, "duplicate.svg");
+ writeFileSync(
+ fixture,
+ '' +
+ ' "
+ );
+
+ try {
+ const result = spawnSync(process.execPath, [validator, fixture], { encoding: "utf8" });
+ assert.equal(result.status, 1, `${result.stdout}${result.stderr}`);
+ assert.match(result.stderr, /duplicate IDs: edge-a/);
+ } finally {
+ rmSync(fixtureDir, { recursive: true, force: true });
+ }
+});
+
+test("SVG validator adds explicit accessible naming when requested for a generated diagram", () => {
+ const fixtureDir = mkdtempSync(path.join(tmpdir(), "omniroute-svg-validator-"));
+ const fixture = path.join(fixtureDir, "auto-combo.svg");
+ writeFileSync(
+ fixture,
+ 'Auto-Combo scoring<\/title>/);
+ assert.match(
+ updated,
+ /<desc id="auto-combo-desc">How OmniRoute scores eligible routing targets with 15 factors\.<\/desc>/
+ );
+ assert.equal([...updated.matchAll(/id="auto-combo-title"/g)].length, 1);
+ assert.equal([...updated.matchAll(/id="auto-combo-desc"/g)].length, 1);
+ } finally {
+ rmSync(fixtureDir, { recursive: true, force: true });
+ }
+});
+
+
+
-> A **combo** is a chain of models OmniRoute routes across **automatically**. Quota runs out, a provider fails, or costs spike — the combo silently slides to the next model. **This is what makes OmniRoute unbreakable.** 🛡️
+> A **combo** is a chain of models OmniRoute routes across **automatically**. If quota runs out, a provider fails, or costs spike, the combo can move to the next eligible healthy model. 🛡️
### ⚡ Zero-config — just use `auto`
@@ -429,7 +429,7 @@ All **19** strategies — mix & match per combo step:
+
+
+
+
+ 
+
+ 
- 
