From 89025c12f123bc0c1f94a587d6db92e33ece7cb1 Mon Sep 17 00:00:00 2001 From: Diego Rodrigues de Sa e Souza <8016841+diegosouzapw@users.noreply.github.com> Date: Fri, 17 Jul 2026 16:46:24 -0300 Subject: [PATCH] docs(readme): animate pool + combo ASCII blocks as SMIL SVG diagrams (#7626) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(readme): animate pool + combo blocks as SMIL SVG diagrams Replace the two remaining ASCII blocks in the README with hand-authored animated SVGs (16s loops, SMIL only โ€” play inside GitHub's sandbox, DESIGN_SYSTEM.md palette), following the tier-cascade.svg pattern: - pool-fair-share.svg โ€” key pool "team-codex" fair-share quota: weights 50/30/20, generous mode lending idle shares, 50% threshold crossing, strict mode holding each key to its cap (verbatim README copy). - combo-always-on.svg โ€” combo "always-on" priority strategy: 4 fallback layers with coral hand-off on failure and an uptime bar that never drops (zero downtime). Both blocks keep their full flow text in the img alt. Registered in docs/diagrams/README.md (hand-authored table). * docs(changelog): add fragment for #7626 (pool + combo SVG diagrams) --- README.md | 18 +- .../maintenance/7626-readme-pool-combo-svg.md | 1 + docs/diagrams/README.md | 2 + docs/diagrams/combo-always-on.svg | 230 ++++++++++++++++++ docs/diagrams/pool-fair-share.svg | 204 ++++++++++++++++ 5 files changed, 439 insertions(+), 16 deletions(-) create mode 100644 changelog.d/maintenance/7626-readme-pool-combo-svg.md create mode 100644 docs/diagrams/combo-always-on.svg create mode 100644 docs/diagrams/pool-fair-share.svg diff --git a/README.md b/README.md index 528ca049d7..450865fcf3 100644 --- a/README.md +++ b/README.md @@ -255,14 +255,7 @@ All **18** strategies โ€” mix & match per combo step: | ๐Ÿšฆ **Policy** | `hard` (block over share) ยท `soft` (deprioritize) ยท `burst` (use idle headroom) | | ๐Ÿงฑ **Cap** | absolute ceiling per key, independent of mode | -``` -Pool "team-codex" ยท 1 Codex Pro account ยท 3 keys ยท 5-hour window - โ”œโ”€ alice weight 50 โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ โ‰ค 50% of the shared 5h quota - โ”œโ”€ bob weight 30 โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ โ‰ค 30% - โ””โ”€ ci-bot weight 20 โ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ โ‰ค 20% -Generous mode (<50% pool used) โ†’ idle shares are lent out -Strict mode (โ‰ฅ50% pool used) โ†’ each key held to its fair share -``` +OmniRoute key pool 'team-codex': one Codex Pro account shared by 3 keys over a 5-hour window. alice weight 50 (up to 50% of the shared 5h quota), bob weight 30, ci-bot weight 20. In generous mode (under 50% pool used) idle shares are lent out; once the pool crosses 50% strict mode holds each key to its fair share. Enforced in the hot path **before** the request leaves OmniRoute, with per-(key, model) caps + session stickiness for prompt-cache integrity (now with a per-combo / global disable toggle). ๐Ÿ“– [Quota Sharing Engine](docs/routing/QUOTA_SHARE.md) @@ -276,14 +269,7 @@ Strict mode (โ‰ฅ50% pool used) โ†’ each key held to its fair share | ๐Ÿ’ค **Connection cooldown** | one account / key | Skips a rate-limited key while other keys keep serving | | ๐ŸŽฏ **Model lockout** | provider + model | Quarantines just one quota-limited model, not the whole connection | -``` -Combo: "always-on" Strategy: priority - 1. cc/claude-opus-4-7 โ† subscription (use it fully) - 2. cx/gpt-5.5 โ† second subscription - 3. glm/glm-5.1 โ† cheap backup ($0.5/1M) - 4. kr/claude-sonnet-4.5 โ† FREE, unlimited (never fails) -Result: 4 layers of fallback = zero downtime -``` +OmniRoute combo 'always-on' with priority strategy: requests go to 1. cc/claude-opus-4-7 (subscription, use it fully); on failure fall through to 2. cx/gpt-5.5 (second subscription), then 3. glm/glm-5.1 (cheap backup at $0.5/1M), then 4. kr/claude-sonnet-4.5 (free, unlimited, never fails). Result: 4 layers of fallback = zero downtime. ๐Ÿ“– [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) ยท [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md) diff --git a/changelog.d/maintenance/7626-readme-pool-combo-svg.md b/changelog.d/maintenance/7626-readme-pool-combo-svg.md new file mode 100644 index 0000000000..14ebdc8f25 --- /dev/null +++ b/changelog.d/maintenance/7626-readme-pool-combo-svg.md @@ -0,0 +1 @@ +- **README animated diagrams** (`docs/diagrams/pool-fair-share.svg`, `docs/diagrams/combo-always-on.svg`): the last two ASCII blocks in the root README โ€” the `"team-codex"` key-pool fair-share example and the `"always-on"` priority combo โ€” are now hand-authored SMIL SVG animations (16s loops, DESIGN_SYSTEM.md palette, GitHub ``-sandbox safe), completing the set started by tier-cascade.svg (#7615). Full block copy preserved verbatim in the `img` alt text; both registered in `docs/diagrams/README.md`. diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md index 2de1805fe3..18543d6959 100644 --- a/docs/diagrams/README.md +++ b/docs/diagrams/README.md @@ -30,6 +30,8 @@ inside GitHub's `` sandbox: | File | Used in | Notes | | ---------------------------------------- | ---------------- | ---------------------------------------------------------------------------- | | [tier-cascade.svg](./tier-cascade.svg) | README.md (root) | Animated 4-tier auto-fallback cascade (16s loop, 4 acts). Edit the SVG directly โ€” there is no `.mmd` source. | +| [pool-fair-share.svg](./pool-fair-share.svg) | README.md (root) | Animated key-pool fair-share quota (generous โ†’ strict, 16s loop). Edit the SVG directly โ€” there is no `.mmd` source. | +| [combo-always-on.svg](./combo-always-on.svg) | README.md (root) | Animated priority-combo fallback (4 layers, 16s loop). Edit the SVG directly โ€” there is no `.mmd` source. | ## How to update diff --git a/docs/diagrams/combo-always-on.svg b/docs/diagrams/combo-always-on.svg new file mode 100644 index 0000000000..0278375d73 --- /dev/null +++ b/docs/diagrams/combo-always-on.svg @@ -0,0 +1,230 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + COMBO + "always-on" + Strategy: priority + try 1 first · fall through + on failure + + + REQUESTS + + + + + + + + + + + + + + + + + + + 1 + cc/claude-opus-4-7 + subscription · use it fully + + + + + + + + + + + + 2 + cx/gpt-5.5 + second subscription + + + + + + + + + + + + 3 + glm/glm-5.1 + cheap backup · $0.5/1M + + + + + + + + + + + + 4 + kr/claude-sonnet-4.5 + FREE · unlimited · never fails + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + fails → next + + fails → next + + fails → next + + + UPTIME + + + + + + + + + ALWAYS ON + + Result: 4 layers of fallback = zero downtime + diff --git a/docs/diagrams/pool-fair-share.svg b/docs/diagrams/pool-fair-share.svg new file mode 100644 index 0000000000..85e2d1ca16 --- /dev/null +++ b/docs/diagrams/pool-fair-share.svg @@ -0,0 +1,204 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Pool "team-codex" + 1 Codex Pro account ยท 3 keys ยท 5-hour window + + + POOL USED + + + + + + + + + + + 50% + 0 + 100% + + + + + + + + + GENEROUS ยท <50% USED + + + + + + + + STRICT ยท ≥50% USED + + + + + + + + + + alice + weight 50 + bob + weight 30 + ci-bot + weight 20 + + + + + + + + + + + + + + + + + + + + + + + + + + ≤ 50% of the shared 5h quota + ≤ 30% + ≤ 20% + + + + + + + + + + + + + + + + + + + + + + lent + + + + + + + + + + + + + + + + + + + + + + + + + idle + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ✕ + + + + + + + + + Generous mode (<50% pool used) → idle shares are lent out + + + + + Strict mode (≥50% pool used) → each key held to its fair share + Enforced in the hot path — before the request leaves OmniRoute ยท per-(key, model) caps ยท session stickiness +