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 +