feat(ui): show models under each tier in routing benchmark chart

[tin-berri]

Summary

Shows each complexity tier's configured model(s) in the "Routing by tier" chart legend, labels the donut's center number, and clarifies the baseline spend wording.

Changes

TierTurnsChart.tsx (new)

• Donut chart showing turns distributed across complexity tiers, only rendered when a single auto-router is selected
• Center label reads "N total turns" instead of a bare number
• Custom legend lists each tier's assigned models below the tier name and percentage
• Quality routers show tier name and percentage only, since they share one model pool instead of pinning models per tier
• Deployment lookup matches on both router name and router type, so two routers sharing a name but different types never borrow each other's config

AutoRouterBenchmarks helpers

• Added viewGroup() to narrow a view to the single-router case, the only one with tier identity
• Widened BenchmarkView.stats to explicitly include AutoRouterBenchmarkGroup

AutoRouterBenchmarksTab.tsx

• Changed the label "Estimated spend at highest-cost model" to "highest-tier model", since the baseline compares against the most capable tier rather than a single highest-priced model

User Flow

Before: an admin on the Auto-Router usage tab, with a specific router selected, sees only tier names and turn percentages, with no indication of which models each tier routes to, and the donut's center just shows a bare number

1. They open http://localhost:4000/ui/cost-optimization/, click the Auto-Router tab, and pick a router from the dropdown
2. The "Routing by tier" legend lists each tier and its share of turns, but nothing about which models that tier uses
3. The donut's center shows a plain number like "6,916" with no unit

After: the same admin sees the models behind each tier and a labeled total

1. Same navigation as above
2. Each legend entry now shows the tier's assigned model(s) beneath its name, e.g. "Fast & Cheap 57%" followed by "claude-3-haiku-fake"
3. The donut's center reads "6,916 total turns"

Relevant issues

Linear ticket

Resolves LIT-5302

Screenshots / Proof of Fix

Backend data, live proxy on localhost:4000, seeded with 340 complexity-router sessions and 180 quality-router sessions, commit 7224c68:

curl -s "http://localhost:4000/auto_router/benchmarks?start_date=2026-07-09&end_date=2026-08-08" \
  -H "Authorization: Bearer sk-1234" | python3 -m json.tool

{
  "totals": { "sessions": 520, "turns": 9616, "saved_spend": 1036.17, "baseline_spend": 1258.24 },
  "groups": [
    { "router_name": "claude-auto", "router_type": "complexity", "sessions": 340, "turns": 6916 }
  ]
}

UI: http://localhost:4000/ui/cost-optimization/, Auto-Router tab, claude-auto selected. The legend shows Fast & Cheap 57% / claude-3-haiku-fake, Balanced 30% / claude-3-sonnet-fake, High Quality 12% / claude-3-opus-fake, Deep Reasoning 2% / claude-3-opus-fake, claude-3-5-sonnet-fake, and the donut center reads "6,916 total turns". The hero card reads "Estimated spend at highest-tier model".

Type

New Feature

Changes

Covered above.

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

---

Note

Low Risk
Dashboard-only analytics and copy changes; deployment config is read for display with type-safe matching and no auth or billing logic changes.

Overview
Adds a Routing by tier donut on the Auto-Router usage tab when a single router is selected. Slices use admin tier labels and benchmark tier_turns keys (SIMPLE/MEDIUM/…); the legend lists configured models for complexity tiers, with deployment lookup matched on router name and type. Quality routers show tier share only; aggregate “all routers” and empty tier data hide the chart. The donut center is labeled “N total turns”.

The savings hero card is simplified to two columns: spend breakdown moves under total savings, avg saved per session is emphasized with “across N sessions”, and baseline copy changes from highest-cost to highest-tier model. Benchmark helpers add viewGroup() and widen BenchmarkView.stats for per-router tier data.

API/schema docs for tier_turns now document uppercase complexity tier keys. Tests wrap cost-optimization views in QueryClientProvider and mock useAutoRouters for the new chart.

^{Reviewed by Cursor Bugbot for commit cef0aaa. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

The PR adds a tier-routing donut chart for individually selected auto-routers and displays configured complexity-tier models. It also labels total tiered turns, updates baseline-spend wording, and aligns benchmark tier documentation and generated API types

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains

No blocking failure remains

Important Files Changed

Filename	Overview
ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/TierTurnsChart.tsx	Adds the tier-turn donut, labels, model legend, and deployment matching by router name and type-specific configuration
ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/TierTurnsChart.test.tsx	Covers tier labels, model lists, router-type separation, totals, and chart visibility conditions
ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/AutoRouterBenchmarksTab.tsx	Loads auto-router deployments, mounts the tier chart, and reorganizes benchmark summary metrics
ui/litellm-dashboard/src/app/(dashboard)/cost-optimization/_components/autoRouterBenchmarks.ts	Widens benchmark views to retain single-router group identity and adds a narrowing helper
litellm/types/management_endpoints/auto_router_endpoints.py	Corrects the documented complexity-tier key casing
ui/litellm-dashboard/src/lib/http/schema.d.ts	Updates generated benchmark schema documentation to match uppercase complexity-tier keys

_{Reviews (4): Last reviewed commit: "test(ui): drop prohibited explanatory co..." | Re-trigger Greptile}

[greptile-apps]

New source comments violate policy

These explanatory blocks add source-code comments despite the repository's explicit no-new-comments convention, creating prose that must be maintained alongside the implementation. The same pattern also occurs around lines 50–55 and in AutoRouterBenchmarksTab.tsx.

Context Used: CLAUDE.md (source)

[tin-berri]

Greptile fix applied: Deployment lookup now validates router type matches (complexity, quality, adaptive, or auto_router) to prevent same-named routers of different types from sharing each other's configuration.

Test added: ignores a same-named deployment of a different router type

Amended and re-pushed.

[tin-berri]

@greptileai can you reply here with a score and why that score?

[tin-berri]

bugbot run

[tin-berri]

@greptileai please re-score at the current commit

[greptile-apps]

Score: 4/5

Why 4/5:

Strengths:

• Test coverage is comprehensive — 11 cases in TierTurnsChart.test.tsx covering quality routers, JSON-stringified configs, empty tiers, cross-type name collisions, and the all-routers/no-tiers null paths.
• The deployment lookup (deploymentFor) correctly discriminates by both router_name and the presence of the type-specific config key, so a quality router sharing a name with a complexity router can never "borrow" its config.
• tierLabelsFor correctly falls back to undefined for quality routers (since complexity_router_config won't exist on a quality deployment that passed through deploymentFor).
• viewGroup() is a clean discriminated-union narrower; widening BenchmarkView.stats to explicitly include AutoRouterBenchmarkGroup makes intent clear even though it was already structurally compatible.
• The wording fix ("highest-cost" → "highest-tier") is more accurate.

Minor deductions:

1. Total turns is no longer visible in the all-routers view. The HeroCard refactor removes the standalone "Total sessions / Total turns" cells. Sessions is still surfaced as "across N sessions", but total turns is only shown in the donut — which renders null for the all-routers view since viewGroup returns null. An admin on the aggregate view loses that figure entirely. Small UX regression worth noting.

2. Math.max(slices.length, 1) in the colors slice is dead code — the component already returns null when entries.length === 0, so slices.length can never be 0 at that point. Harmless but slightly noisy.

Otherwise clean, well-scoped, and the architecture is solid.

[cursor]

Tier legend order is unstable

Medium Severity

tier_turns is rendered via Object.entries with no sort, so slice and legend order follow whatever key order the API returns. Complexity tiers have a fixed severity ladder (SIMPLE → MEDIUM → COMPLEX → REASONING), and the sequential color ramp assumes that order. Unsorted keys scramble the ladder and make darker/lighter colors meaningless.

 

^{Reviewed by Cursor Bugbot for commit 7224c68. Configure here.}

[tin-berri]

Both findings addressed in 6ab29314d4.

1. Total turns no longer visible in the all-routers view — correct, and it was a regression from my own HeroCard refactor, not an intentional trade. The savings-per-session tile now names both denominators:

across 94 sessions and 3,073 turns

This puts the figure back on every view including the aggregate, and reads better than the standalone tile it replaced since the turns count is now attached to the number it qualifies. Test updated to assert the full string (AutoRouterBenchmarksTab.test.tsx, "pairs the savings with the session and turn counts it was earned over").

2. Math.max(slices.length, 1) is dead code — agreed, the entries.length === 0 early return at line 90 makes slices.length unreachable at 0. Simplified to SEQUENTIAL_COLOR_RAMP.slice(0, slices.length).

104/104 dashboard tests pass; tsc --noEmit and eslint clean on the touched files.

@greptileai please re-review.

[tin-berri]

@greptileai can you reply here with a score and why that score?

[tin-berri]

bugbot run

[greptile-apps]

Score: 4.5 / 5

The implementation is clean, well-tested, and low-risk. Here's the breakdown:

What's good (pushing it to 4.5)

• deploymentFor correctly discriminates on both router_name and router-type config key, so two routers sharing a name can't borrow each other's tier config. The test for type-isolation ("ignores a same-named deployment of a different router type") confirms this.
• asRecord + safeParse cleanly handle configs stored as JSON strings without throwing.
• viewGroup uses "router_name" in view.stats as a structural discriminant — correct since AutoRouterBenchmarkGroup is the only type that adds those fields.
• Tests are thorough: canonical fallback, JSON-string configs, empty model lists, quality-router no-models path, all-routers sentinel, and the type-isolation case are all covered.
• The API doc-string fix ('simple' → 'SIMPLE') aligns documentation to what the backend actually emits, preventing client-side key mismatches.

Minor deductions

1. Rounding can silently missum to ≠ 100%. Each slice uses Math.round((100 * slice.turns) / total) independently. With three roughly equal tiers you'll display e.g. 33% + 33% + 33% = 99% even though the donut sums correctly. A "largest-remainder" rounding strategy would fix this, but it's cosmetic-only.

2. idx % colors.length is a no-op. Since colors = SEQUENTIAL_COLOR_RAMP.slice(0, slices.length), idx is already in-bounds and the modulo never changes the result. No bug, just a tiny readability noise.

3. Removing the standalone "Total sessions" and "Total turns" tiles reduces quick-scan information density; the data survives in the prose "across N sessions and N turns" but at lower visual weight. Whether that's a regression is a product call, not a correctness one.

None of these are blockers. The PR is a net improvement and safe to merge.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 6ab2931. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing feat/tier-models-in-legend (cef0aaa) with litellm_internal_staging (79d412e)¹}

Footnotes

1. No successful run was found on litellm_internal_staging (c4656d8) during the generation of this report, so 79d412e was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[tin-berri]

@greptileai can you review

[tin-berri]

bugbot run

[tin-berri]

@greptileai can you reply here with score and why

[tin-berri]

bugbot run

[greptile-apps]

Score: 8/10

Why:

Strengths:

• Clean, well-structured component with good separation of concerns (tierLabelsFor, tierModelsFor, deploymentFor helpers)
• Solid test coverage — 10 focused cases covering quality vs complexity router distinction, JSON string config, same-name/different-type disambiguation, and empty edge cases
• ChartColor type correctly accepts hex strings (#${string}), so TIER_DONUT_COLORS is type-safe
• viewGroup is a clean narrowing pattern that avoids casting throughout the component

Concerns:

1. Tier key case change may break existing data. The docs + schema comment change simple/medium/complex/reasoning → SIMPLE/MEDIUM/COMPLEX/REASONING. If any existing sessions recorded lowercase keys before this change, isComplexityTier will return false for them (since TIER_KEYS presumably contains uppercase values), and those turns will show as raw strings with no model lookup. This is a silent data display regression, not a crash — but worth verifying the backend has always emitted uppercase, or that there's no old data with lowercase keys.

2. "Total turns" disappears in the all-routers view. The hero card redesign removes the "Total turns" tile entirely. In the all-routers aggregate view, the donut chart is hidden (correctly), so there's now no place in the UI that shows total turns for the aggregate. "Avg turns per session" remains, but not the raw total.

3. Color cycling for quality routers with many numeric tiers. TIER_DONUT_COLORS has 4 entries; a quality router with 5+ numeric tiers will repeat colors. Minor cosmetic issue but potentially confusing.

The first concern is the most material — everything else is cosmetic or low risk. The PR is otherwise well-executed for a purely presentational change.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit cef0aaa. Configure here.}