docs for complexity router and openapi reference

[Madhuvod]

Summary

Adds documentation and OpenAPI spec coverage for the Complexity Router feature, which automatically classifies incoming LLM requests into four tiers (SIMPLE, MEDIUM, COMPLEX, REASONING) and exposes a complexity_tier CEL variable for use in routing rules. This allows requests to be steered to appropriately-sized models based on prompt content with no application-side changes.

Changes

• Added docs/features/governance/complexity-router.mdx — full reference page covering the scoring algorithm (five weighted dimensions, system prompt contribution, conversation context blending, output complexity floor, reasoning override), tier classification boundaries, configuration via UI/API/config.json, CEL routing examples, observability, and troubleshooting guidance.
• Registered the new page in docs/docs.json under the Governance section.
• Added cross-reference callouts in routing.mdx, routing-rules.mdx, and provider-routing.mdx pointing to the Complexity Router page and describing the complexity_tier variable.
• Added GET /api/governance/complexity-analyzer-config, PUT /api/governance/complexity-analyzer-config, and POST /api/governance/complexity-analyzer-config/reset endpoints to the OpenAPI spec (both openapi.json and openapi.yaml), with ComplexityAnalyzerConfig, ComplexityTierBoundaries, and ComplexityKeywordConfig schemas.
• Added a ConfigStoreUnavailable (503) reusable response component to the OpenAPI spec.
• Corrected the API path reference in ui/lib/types/complexityRouter.ts from /api/governance/complexity to /governance/complexity-analyzer-config.
• Added supporting architecture and UI screenshot assets under docs/media/.

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

1. Navigate to the docs site and confirm the Complexity Router page appears under the Governance section in the sidebar.
2. Verify all internal links (Routing Rules, Virtual Keys, Budget & Limits, Provider Routing) resolve correctly.
3. Confirm the OpenAPI spec renders the three new /api/governance/complexity-analyzer-config endpoints with correct request/response schemas.
4. Validate the complexity_tier CEL variable examples in routing-rules.mdx are consistent with the behavior described in the Complexity Router page.

Breaking changes

• Yes
• No

Related issues

N/A

Security considerations

No new auth surfaces or secrets handling introduced. The API endpoints follow the same governance authentication patterns as existing endpoints.

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

Summary by CodeRabbit

• New Features

  • Introduced Complexity Router feature to classify requests into four tiers (SIMPLE, MEDIUM, COMPLEX, REASONING) for dynamic request routing.
  • Added REST API endpoints to retrieve, update, and reset complexity analyzer configuration at runtime.

• Documentation

  • Added comprehensive guide for Complexity Router feature and configuration options.
  • Updated routing documentation to reference Complexity Router and explain the complexity_tier routing variable.
  • Clarified static vs. dynamic routing capabilities.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a Complexity Router docs page and navigation entry; defines complexity_tier CEL usage; adds OpenAPI schemas and management endpoints (GET, PUT, POST/reset) for the analyzer config; updates routing/provider docs; and small UI/configstore doc comment tweaks.

Changes

Complexity Router Feature

Layer / File(s)	Summary
Navigation and page frontmatter docs/docs.json, docs/features/governance/complexity-router.mdx	Added the feature page to site navigation and the page frontmatter/intro describing automatic request tier classification.
Core Complexity Router docs docs/features/governance/complexity-router.mdx	Full feature documentation covering scoring pipeline, tier mapping, configuration (UI/API/config.json), CEL routing examples, observability, troubleshooting, supported request types, and next steps.
OpenAPI schema definitions docs/openapi/schemas/management/governance.yaml	Added ComplexityTierBoundaries, ComplexityKeywordConfig, and ComplexityAnalyzerConfig schemas describing thresholds and keyword lists.
OpenAPI paths, operations, and response component docs/openapi/paths/management/governance.yaml, docs/openapi/openapi.json, docs/openapi/openapi.yaml	Added management endpoints for complexity-analyzer-config (GET, PUT, POST /reset) with request/response schemas and error responses, and a reusable ConfigStoreUnavailable response mapping to BifrostError.
Routing docs and provider docs integration docs/features/governance/routing.mdx, docs/providers/routing-rules.mdx, docs/providers/provider-routing.mdx	Clarified static governance routing scope, added Complexity Routing docs describing the complexity_tier CEL variable, examples, unknown/fallback behavior, troubleshooting note, and cross-links to the new feature page.
ConfigStore doc and UI comment tweaks framework/configstore/store.go, ui/lib/types/complexityRouter.ts	Added a doc comment for GetComplexityAnalyzerConfig and updated a UI type comment to reference /governance/complexity-analyzer-config.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• akshaydeo
• danpiths

"I hop through docs and YAML with cheer,
I tuck new tiers where routes appear,
SIMPLE to REASONING, CEL knows the way,
Endpoints and schemas now join the play,
A rabbit's note: docs blossom today."

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: documentation and OpenAPI reference updates for the Complexity Router feature, which aligns with the substantial additions to docs and OpenAPI specs.
Description check	✅ Passed	The description follows the template structure with all major sections completed: Summary, Changes, Type of change, Affected areas, How to test, Breaking changes, Related issues, Security considerations, and Checklist. All critical information is present and well-documented.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 05-24-docs_for_complexity_router_and_openapi_reference

---

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

[Madhuvod]

• feat(helm): add complexity analyzer config values support #3948
• docs for complexity router and openapi reference #3716 👈 (View in Graphite)
• feat(ui): add complexity router config UI and CEL support #3715
• complexity router : add complexity analyzer config DB and API changes #3712
• feat: complexity router : adds complexity_tier CEL routing #3711
• feat: enforce routing allowlist in core and propagate VK provider constraints via context key #3936 : 1 other dependent PR (#4014 )
• docs: document PreRequestHook routing phase, per-request vs per-attempt semantics, and updated plugin sequencing #3935
• refactor: move model-catalog provider resolution into a modelcatalogresolver PreRequestHook plugin #3934
• refactor: migrate governance routing from HTTPTransportPreHook to PreRequestHook #3933
• feat: add PreRequestHook to LLMPlugin interface as a once-per-request routing phase before PreLLMHook #3932
• dev

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

[greptile-apps]

Confidence Score: 5/5

Safe to merge; all doc content and API paths cross-check against the live handler and schema implementations, and the one code change (comment fix) is purely cosmetic.

The changes are documentation and OpenAPI spec additions. API paths, schema field names, tier boundaries, and fallback behaviour in the docs all match what the Go handlers and config schema actually implement. The only non-doc touch is a comment correction in a TypeScript types file, which is correct given how the UI base URL is constructed.

ui/public/images/prisma_airs.png — appears to be an accidentally included image not referenced anywhere in the UI.

Important Files Changed

Filename	Overview
docs/features/governance/complexity-router.mdx	New full-reference page for Complexity Router; algorithm description, tier table, config tabs, routing examples, observability, and troubleshooting all align with actual handler and schema implementations reviewed.
docs/openapi/schemas/management/governance.yaml	Adds ComplexityTierBoundaries, ComplexityKeywordConfig, and ComplexityAnalyzerConfig schemas; field names and types match the Go AnalyzerConfig struct.
docs/openapi/paths/management/governance.yaml	Adds GET/PUT complexity and POST complexity-reset path definitions; request/response schemas, 400/500/503 responses, and operationIds all match actual handler routes.
docs/openapi/openapi.json	Adds three new endpoints and ConfigStoreUnavailable component; ComplexityAnalyzerConfig schema is inlined four times rather than added to components/schemas and referenced, unlike the pattern used elsewhere in this file (e.g. BifrostError).
ui/lib/types/complexityRouter.ts	Fixes comment path from /api/governance/complexity to /governance/complexity-analyzer-config, which is correct given getApiBaseUrl() already prepends /api.
framework/configstore/store.go	Adds doc comment for GetComplexityAnalyzerConfig; no functional changes.
docs/providers/routing-rules.mdx	Adds complexity_tier CEL variable documentation with accurate fallback behaviour and cross-link to the new complexity-router page.
ui/public/images/prisma_airs.png	Binary image file added to ui/public/images/ but not referenced anywhere in UI code; appears to be an accidental inclusion.

_{Reviews (22): Last reviewed commit: "docs for complexity router and openapi r..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

docs/openapi/schemas/management/governance.yaml (1)

1318-1341: 💤 Low value

Document that ordering constraint is runtime-validated, not schema-enforced.

The description states "All values must satisfy 0 < simple_medium < medium_complex < complex_reasoning < 1", but JSON Schema cannot enforce cross-field ordering (only per-field bounds via exclusiveMinimum/exclusiveMaximum). The ordering constraint must be validated by the API handler at runtime and will produce a 400 BadRequest on violation.

Consider adding a note in the description that ordering validation happens at the API layer (as documented in the PUT operation at line 1090), so clients understand that schema-valid payloads may still be rejected.

📝 Suggested clarification

 ComplexityTierBoundaries:
   type: object
-  description: Score thresholds for complexity tier classification. All values must satisfy 0 < simple_medium < medium_complex < complex_reasoning < 1.
+  description: |
+    Score thresholds for complexity tier classification. All values must satisfy 
+    0 < simple_medium < medium_complex < complex_reasoning < 1. 
+    Note: Cross-field ordering is validated at runtime by the API; the schema enforces only per-field bounds.
   additionalProperties: false

🤖 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/openapi/schemas/management/governance.yaml` around lines 1318 - 1341,
Update the ComplexityTierBoundaries schema description to explicitly state that
cross-field ordering (0 < simple_medium < medium_complex < complex_reasoning <
1) is NOT enforced by the JSON Schema and is validated at the API layer
(runtime) — violations will result in a 400 BadRequest; reference the PUT
operation's runtime validation behavior and ensure the description mentions
clients may pass schema-valid payloads that are still rejected if ordering is
invalid.

🤖 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/openapi/openapi.json`:
- Around line 40364-40391: The OpenAPI schema's tier_boundaries (properties
simple_medium, medium_complex, complex_reasoning) notes a required ordering (0 <
simple_medium < medium_complex < complex_reasoning < 1) that JSON Schema cannot
enforce at runtime; add validation in the request handling code that inspects
tier_boundaries and verifies simple_medium < medium_complex < complex_reasoning
(and each is between 0 and 1), and if the check fails return a 400 response with
a clear error message indicating which boundary comparison failed (e.g.,
"simple_medium must be less than medium_complex").
- Around line 48995-49003: The new response component ConfigStoreUnavailable is
defined but unused; update the three complexity-analyzer-config endpoints (the
GET, PUT, and POST operations that currently inline identical 503 responses) to
reference the component instead of duplicating the schema by replacing their
inline 503 response bodies with "$ref":
"`#/components/responses/ConfigStoreUnavailable`"; alternatively, if the component
is not needed, remove the ConfigStoreUnavailable component declaration to avoid
dead OpenAPI definitions. Ensure the change is applied to the operations named
for complexity-analyzer-config (GET complexity-analyzer-config, PUT
complexity-analyzer-config, POST complexity-analyzer-config) so they all
consistently reference the shared response component.

---

Nitpick comments:
In `@docs/openapi/schemas/management/governance.yaml`:
- Around line 1318-1341: Update the ComplexityTierBoundaries schema description
to explicitly state that cross-field ordering (0 < simple_medium <
medium_complex < complex_reasoning < 1) is NOT enforced by the JSON Schema and
is validated at the API layer (runtime) — violations will result in a 400
BadRequest; reference the PUT operation's runtime validation behavior and ensure
the description mentions clients may pass schema-valid payloads that are still
rejected if ordering is invalid.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1e90ca74-44a5-482c-b6f8-655b6bbede83

📥 Commits

Reviewing files that changed from the base of the PR and between 032bc77 and 96b8aad.

⛔ Files ignored due to path filters (6)

• docs/media/architecture-complexity-router.png is excluded by !**/*.png
• docs/media/complexity-logic-architecture.png is excluded by !**/*.png
• docs/media/ui-complexity-router-config.png is excluded by !**/*.png
• docs/media/ui-complexity-router-keywords.png is excluded by !**/*.png
• docs/media/ui-routing-logs-complexity.png is excluded by !**/*.png
• docs/media/ui-routing-rule-complexity.png is excluded by !**/*.png

📒 Files selected for processing (10)

• docs/docs.json
• docs/features/governance/complexity-router.mdx
• docs/features/governance/routing.mdx
• docs/openapi/openapi.json
• docs/openapi/openapi.yaml
• docs/openapi/paths/management/governance.yaml
• docs/openapi/schemas/management/governance.yaml
• docs/providers/provider-routing.mdx
• docs/providers/routing-rules.mdx
• ui/lib/types/complexityRouter.ts

✅ Files skipped from review due to trivial changes (2)

• docs/providers/provider-routing.mdx
• ui/lib/types/complexityRouter.ts

[akshaydeo]

Merge activity

• Jun 10, 1:30 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jun 10, 1:37 PM UTC: Graphite rebased this pull request as part of a merge.
• Jun 10, 1:38 PM UTC: @akshaydeo merged this pull request with Graphite.

The base branch was changed.