docs: clarify adaptive load balancing weight calculation and cross-node coordination

[Pratham-Mishra04]

Summary

Updates the adaptive load balancing documentation to more accurately describe how the scoring algorithm works, removing references to fixed percentage weights and the momentum term that no longer reflect the current implementation.

Changes

• Replaced the fixed-weight scoring table (Error 50%, Latency 20%, Utilization 5%, Momentum additive) with a priority-ordered description (primary, secondary, tuning) that matches the actual behavior
• Removed the explicit scoring formulas that referenced the old weighted sum and momentum bias, replacing them with a prose description of the health-aware scoring logic
• Clarified that recovering routes are scored differently from healthy routes — they are evaluated on latency and recovery progress rather than stale error history
• Updated the Mermaid flowchart to remove the Momentum input node and reflect the revised scoring labels
• Revised the "Cross-Node Synchronization" feature description to clarify that nodes share circuit-breaker signals for fleet-wide backoff, rather than just syncing weights via gossip
• Updated the self-healing tip to describe penalty decay rather than a specific 90%/30-second figure
• Reworded the smart key selection description to emphasize proportional probabilistic distribution with continuous re-probing of lower-weight routes

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Review the rendered documentation to confirm the scoring table, flowchart, and prose descriptions are internally consistent and no longer reference the removed momentum term or fixed percentage weights.

Breaking changes

• Yes
• No

Related issues

Security considerations

None.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adaptive Load Balancing documentation is updated across two docs pages to describe health-aware scoring, operator configuration controls, provider-selection wording, and revised scope/next-step guidance.

Changes

Adaptive Load Balancing Documentation Rewrite

Layer / File(s)	Summary
Health-aware scoring narrative docs/enterprise/adaptive-load-balancing.mdx	Key Features, the weight calculation section, and Key Capabilities are rewritten to describe Error Penalty, Latency Score, and Utilization instead of the prior momentum-based model.
Configuration section docs/enterprise/adaptive-load-balancing.mdx	Adds runtime configuration switches, live propagation notes, API and config.json examples, and a PUT full-replacement warning.
Scope and next steps docs/enterprise/adaptive-load-balancing.mdx	Updates scope/limitations bullets and replaces procedural next steps with direct documentation links.
Provider selection flow docs/providers/provider-routing.mdx	Updates the Level 1 direction section, score label, and request-flow example to match the revised provider-selection language.
Route scoring and exploration docs/providers/provider-routing.mdx	Reworks Level 2 scoring, smart exploration, and dashboard note content to describe the 5-second recompute cycle and health-aware scoring.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main documentation updates to weight calculation and cross-node coordination.
Description check	✅ Passed	The description matches the template well with summary, changes, type, affected areas, testing, breaking changes, issues, security, and checklist.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 06-25-docs_lb_doc_updates

---

_{Comment @coderabbitai help to get the list of available commands.}

[Pratham-Mishra04]

• docs: add conflicting credentials troubleshooting and clarify MCP auth mode credential exclusivity #4910
• docs: clarify adaptive load balancing weight calculation and cross-node coordination #4744 👈 (View in Graphite)
• docs: update benchmarking docs for new CLI flags, mocker/hitter tools, and revised result schema #4909
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
docs/enterprise/adaptive-load-balancing.mdx	Rewrites the adaptive load balancing page with updated scoring, configuration, and limitations guidance.
docs/providers/provider-routing.mdx	Updates provider-routing language to align with the revised adaptive load balancing behavior.
docs/media/ui-load-balancing-dashboard.png	Adds a dashboard screenshot for the refreshed docs.
docs/media/ui-load-balancing-metrics.png	Adds a metrics screenshot for the refreshed docs.
docs/media/ui-load-balancing-settings.png	Adds a settings screenshot for the refreshed docs.
docs/media/ui-load-balancing.png	Removes the older combined load balancing screenshot.

_{Reviews (5): Last reviewed commit: "docs: lb doc updates" | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/enterprise/adaptive-load-balancing.mdx`:
- Around line 83-98: The adaptive load-balancing docs are now using the new
three-signal, recovery-aware scoring model, but the related provider-routing
guide still describes the older momentum-based scoring and fixed recovery
example. Update the provider-routing section that documents route scoring and
recovery behavior so it matches the same terminology and logic as the updated
adaptive-load-balancing page, keeping the guidance for the scoring flow and
examples in sync across both docs.
- Around line 99-121: The Mermaid diagram in the adaptive load balancing docs
only shows a single health-aware scoring path from Error Rate, Latency, and
Utilization, but the surrounding text also describes a recovering-route branch
driven by recovery progress. Update the `flowchart LR` diagram to include the
health-state/recovery-progress path alongside the existing `Inputs`, `Scoring`,
and `Output` nodes, or revise the prose so the `Health-aware Scoring` section
matches the simpler model shown in the diagram.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7278ff8e-39b6-4af9-bb5b-39a3d2b837ac

📥 Commits

Reviewing files that changed from the base of the PR and between 62e5fbe and 58cadb8.

📒 Files selected for processing (1)

• docs/enterprise/adaptive-load-balancing.mdx

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/providers/provider-routing.mdx (1)

1155-1164: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Stale fixed-value claim left in "Fast Recovery" row.

The Fast Recovery row still states "90% penalty reduction in 30 seconds after issues resolve"-style fixed figures, but this PR intentionally removed that kind of hard-coded value elsewhere on the same page — the Tip right above (lines 1118-1122) now describes penalties as decaying "fast" without a specific percentage/time, and the upstream enterprise doc frames recovery timings as pre-tuned rather than a fixed number. Leaving this row unchanged creates an inconsistency within the same page.

✏️ Suggested fix

-| **Fast Recovery**          | 90% penalty reduction in 30 seconds after issues resolve            |
+| **Fast Recovery**          | Penalties decay quickly once issues resolve, restoring full traffic within seconds |

Based on path instructions ("Check docs for parity with code, config.schema.json, and provider behavior") and the PR objective of removing fixed 90%/30-second values.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/providers/provider-routing.mdx` around lines 1155 - 1164, The “Fast
Recovery” entry in the key features table still contains stale fixed recovery
numbers that conflict with the rest of the page and the PR’s removal of
hard-coded 90%/30-second claims. Update the table row in provider-routing.mdx so
the description for “Fast Recovery” matches the new generic wording used nearby
(as in the Tip above) and remove any specific percentage/time values. Keep the
wording aligned with the page’s broader recovery behavior and the
provider-routing documentation.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@docs/providers/provider-routing.mdx`:
- Around line 1155-1164: The “Fast Recovery” entry in the key features table
still contains stale fixed recovery numbers that conflict with the rest of the
page and the PR’s removal of hard-coded 90%/30-second claims. Update the table
row in provider-routing.mdx so the description for “Fast Recovery” matches the
new generic wording used nearby (as in the Tip above) and remove any specific
percentage/time values. Keep the wording aligned with the page’s broader
recovery behavior and the provider-routing documentation.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 963b9e97-d0f6-4e0c-bd76-b8f9b24d08a8

📥 Commits

Reviewing files that changed from the base of the PR and between 835aee3 and 1495fa4.

⛔ Files ignored due to path filters (4)

• docs/media/ui-load-balancing-dashboard.png is excluded by !**/*.png
• docs/media/ui-load-balancing-metrics.png is excluded by !**/*.png
• docs/media/ui-load-balancing-settings.png is excluded by !**/*.png
• docs/media/ui-load-balancing.png is excluded by !**/*.png

📒 Files selected for processing (2)

• docs/enterprise/adaptive-load-balancing.mdx
• docs/providers/provider-routing.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/enterprise/adaptive-load-balancing.mdx

[akshaydeo]

Merge activity

• Jul 4, 4:52 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jul 4, 4:54 PM UTC: @akshaydeo merged this pull request with Graphite.

The base branch was changed.