semantic routing #5: added semantic classifier for complexity router + handlers changes

[Madhuvod]

Summary

Adds semantic complexity routing to the Governance plugin. Instead of relying solely on lexical keyword matching, requests can now be classified by embedding the latest user message and finding its nearest labelled exemplar in a VectorStore. This enables more accurate tier assignment for requests that don't contain explicit keywords but are semantically similar to known simple, medium, or complex prompts.

Changes

• SemanticClassifier: New component that manages asynchronous exemplar warmup, generation lifecycle (fingerprinted namespaces), and nearest-neighbour classification via a VectorStore. Supports embedded (private Chromem), auto (prefer configured store), and external (require configured store) modes.
• Default exemplars: 50 curated phrases per tier (coding, general knowledge, math/reasoning, writing) are bundled as defaultSimpleExemplars, defaultMediumExemplars, and defaultComplexExemplars. These are merged with the existing lexical keyword lists so both classifiers share one phrase list.
• Batch embedding support: generateEmbeddings sends multi-input requests during warmup and falls back to single-input calls when a provider signals ErrBatchEmbeddingsUnsupported. Response index reordering is handled explicitly.
• Semantic validation: When semantic routing is enabled, phrase lists are validated for cross-tier duplicates (case/whitespace normalized) and bounded by MaxComplexitySemanticPhrases (500) and MaxComplexitySemanticPhraseCharacters (2000).
• Routing integration: applyRoutingRules attempts semantic classification first; on success it records MechanismSemantic and the cosine similarity score. On failure or unavailability it falls back to lexical or skips based on the configured fallback field.
• ComplexityVectorStoreSetter interface: Allows the HTTP server to wire Bifrost's configured shared VectorStore into the Governance plugin at bootstrap and on plugin reload.
• New HTTP endpoint: GET /api/governance/complexity-analyzer-status returns the non-persisted semantic classifier readiness (disabled, warming, ready, failed) so UI clients can distinguish a saved config from a ready one.
• PUT /api/governance/complexity-analyzer-config validation: Runtime dependency checks (e.g. external VectorStore availability) now run before the config is persisted.
• Context keys and log types updated: BifrostContextKeyGovernanceComplexityMechanism now documents "semantic" as a valid value; BifrostContextKeyGovernanceComplexityScore description updated to reflect cosine similarity.
• UI types and API client: SemanticConfig, SemanticStatusInfo, and useGetComplexitySemanticStatusQuery added. The complexity router form schema preserves the semantic block on save. Keyword list labels updated to "tier phrases" to reflect dual lexical/semantic use.
• MergeComplexityAnalyzerConfig fix: Both merge paths now normalize before validating, ensuring semantic phrase validation sees the same canonical form that will be stored.

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

# Core/Transports
go test ./plugins/governance/complexity/...
go test ./plugins/governance/...
go test ./framework/configstore/...
go test ./transports/bifrost-http/handlers/...

# UI
cd ui
pnpm i
pnpm build

To exercise semantic routing end-to-end:

1. Configure a Governance routing rule with a complexity_tier condition.
2. Add a semantic block to the complexity analyzer config pointing at an OpenAI-compatible embedding model.
3. Send a chat request whose last user message is semantically close to one tier's exemplars.
4. Confirm complexity_mechanism: "semantic" and the matched tier appear in the routing engine logs.
5. Remove the embedding executor (or set fallback: "lexical") and confirm the request falls back to lexical classification with complexity_mechanism: "lexical".

Breaking changes

• Yes
• No

Security considerations

• Exemplar phrases and embeddings are never surfaced through the semantic status endpoint or routing logs; only tier labels and similarity scores are recorded.
• Raw embedding vectors are not logged or included in any API response.
• The external VectorStore mode is fail-closed: if no configured store is present, the config is rejected at save time rather than silently degrading.
• Warmup cancellation ensures a superseded generation cannot write vectors into a namespace owned by a newer configuration.

Checklist

• I added/updated tests where appropriate
• I verified builds succeed (Go and UI)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c40a1be7-cf67-4bc9-9d9d-8a126c5903f4

📥 Commits

Reviewing files that changed from the base of the PR and between e809390 and 15d7581.

📒 Files selected for processing (20)

• core/schemas/bifrost.go
• framework/configstore/complexityconfig.go
• framework/configstore/complexityconfig_test.go
• plugins/governance/complexity/config.go
• plugins/governance/complexity/exemplars.go
• plugins/governance/complexity/exemplars_test.go
• plugins/governance/complexity/semanticclassifier.go
• plugins/governance/complexity/semanticclassifier_test.go
• plugins/governance/embedding.go
• plugins/governance/embedding_test.go
• plugins/governance/main.go
• plugins/governance/prerequesthookcomplexity_test.go
• plugins/governance/utils.go
• transports/bifrost-http/handlers/governance.go
• transports/bifrost-http/handlers/governance_test.go
• transports/bifrost-http/server/server.go
• ui/app/workspace/complexity-router/page.tsx
• ui/lib/store/apis/governanceApi.ts
• ui/lib/types/complexityRouter.ts
• ui/lib/types/logs.ts

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

• plugins/governance/embedding_test.go
• ui/lib/store/apis/governanceApi.ts
• ui/lib/types/logs.ts
• plugins/governance/utils.go
• ui/app/workspace/complexity-router/page.tsx
• plugins/governance/complexity/config.go
• plugins/governance/prerequesthookcomplexity_test.go
• framework/configstore/complexityconfig_test.go
• plugins/governance/complexity/exemplars_test.go
• ui/lib/types/complexityRouter.ts
• transports/bifrost-http/handlers/governance.go
• plugins/governance/complexity/exemplars.go
• framework/configstore/complexityconfig.go
• plugins/governance/complexity/semanticclassifier_test.go
• plugins/governance/embedding.go
• transports/bifrost-http/handlers/governance_test.go
• plugins/governance/main.go
• plugins/governance/complexity/semanticclassifier.go

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added embedding-based semantic complexity routing across SIMPLE, MEDIUM, and COMPLEX tiers.
  • Added configurable providers, models, vector stores, timeouts, fallback behavior, and budget tracking.
  • Added readiness reporting, routing metadata, matched exemplars, API support, and UI configuration.
  • Added balanced built-in semantic examples and a status endpoint for monitoring routing readiness.

• Bug Fixes

  • Added validation for duplicate, ambiguous, and oversized semantic phrases.
  • Improved embedding batching, response validation, ordering, and fallback handling.
  • Prevented invalid external semantic-store configurations from being saved.
  • Limited matched exemplar length in routing logs.

Walkthrough

Adds semantic complexity routing with configurable exemplars, embedding-backed classification, vector-store warmup, lexical fallback, runtime status APIs, configuration validation, and frontend support.

Changes

Semantic routing

Layer / File(s)	Summary
Semantic configuration and exemplars framework/configstore/..., plugins/governance/complexity/config.go, plugins/governance/complexity/exemplars.go	Adds phrase validation, normalized merging, tier exemplars, and combined lexical-semantic defaults.
Semantic classifier lifecycle and warmup plugins/governance/complexity/semanticclassifier.go, plugins/governance/complexity/semanticclassifier_test.go	Adds readiness states, classification, asynchronous warmup, generation switching, vector-store modes, batching, and lifecycle handling.
Embedding integration and governance routing plugins/governance/embedding.go, plugins/governance/main.go, plugins/governance/prerequesthookcomplexity_test.go, plugins/governance/utils.go, core/schemas/bifrost.go, ui/lib/types/logs.ts	Adds batch embedding and vector-store wiring. Governance uses semantic classification before lexical fallback and bounds matched exemplars in logs.
Runtime validation and status APIs transports/bifrost-http/handlers/governance.go, transports/bifrost-http/server/server.go, transports/bifrost-http/handlers/governance_test.go	Adds runtime validation, readiness reporting, server callbacks, vector-store injection, and HTTP tests.
UI semantic configuration and status query ui/lib/types/complexityRouter.ts, ui/lib/store/apis/governanceApi.ts, ui/app/workspace/complexity-router/page.tsx	Adds semantic configuration and status types, mechanism labels, form validation, and a status query hook.

Estimated code review effort: 4 (Complex) | ~60–90 minutes

Mergeability Score: ⚪ Minimal · up to 15d75

This PR adds semantic complexity routing and related configuration, API, and UI support; no actionable merge-blocking risk remains based on the supplied evidence.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant GovernanceHandler
  participant BifrostHTTPServer
  participant GovernancePlugin
  participant SemanticClassifier
  participant VectorStore
  Client->>GovernanceHandler: Update semantic analyzer configuration
  GovernanceHandler->>BifrostHTTPServer: Validate normalized configuration
  BifrostHTTPServer->>GovernancePlugin: ValidateComplexityAnalyzerConfig
  GovernancePlugin->>SemanticClassifier: ValidateConfig
  alt Configuration valid
    GovernanceHandler->>GovernancePlugin: Persist and apply configuration
    GovernancePlugin->>SemanticClassifier: Configure
    SemanticClassifier->>VectorStore: Warm exemplar generation
  else Configuration invalid
    GovernanceHandler-->>Client: Return HTTP 400
  end
  Client->>GovernanceHandler: Get semantic status
  GovernanceHandler->>BifrostHTTPServer: Request runtime status
  BifrostHTTPServer->>GovernancePlugin: ComplexitySemanticStatus
  GovernancePlugin->>SemanticClassifier: Status
  SemanticClassifier-->>Client: Return readiness state and progress

Loading

Possibly related PRs

• maximhq/bifrost#5602: Extends the same complexity configuration and merge-validation logic with semantic exemplars.
• maximhq/bifrost#5628: Provides vector-store infrastructure used by semantic classification.
• maximhq/bifrost#5656: Provides embedding executor wiring used by semantic routing.

Suggested reviewers: akshaydeo, danpiths, kohlivrinda

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 51.61% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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 identifies semantic routing and the new classifier, which are the primary changes.
Description check	✅ Passed	The description covers the purpose, major changes, affected areas, testing steps, breaking changes, security, and test updates; some template sections are omitted.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 07-30-semantic_routing_5_added_semantic_classifier_for_complexity_router_handlers_changes

---

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

[Madhuvod]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• semantic router: incremental embedding + embed usage accounting #5896 : 2 dependent PRs (#5901 , #5924 )
• semantic router ui revamp #5865
• move complexity exemplars to configstore with backfill migration #5842
• feat(complexity): harness-aware complexity input extraction for cc and codex #5810
• server: export ObserveWarmupRoutingEmbedding for enterprise #5791
• weaviate + redis adapter fixes #5790
• semantic routing ui #5743
• semantic router: dimension probe + message history window #5748
• semantic cache: min similarity + fallback logging #5742
• smenatic router: budgeting+telemetry management #5686
• semantic routing #5: added semantic classifier for complexity router + handlers changes #5680 👈 (View in Graphite)
• semantic router #3: embedding executor #5656
• semantic router #2: semantic routing config #5655
• semantic router #1: add chromem backend #5628
• complexity : reducing keyword lists from 4 -> 3 lists #5602
• helm and docs changes #5530
• update complexity boundaries #5529
• expose tier/mechanism on every surface #5499
• structured logging #5497
• complexity tier merge #5494
• dev

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

[coderabbitai]

🧹 Nitpick comments (1)

ui/lib/store/apis/governanceApi.ts (1)

860-865: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Semantic status is asynchronous — plan for refresh at the consumer.

The endpoint has no tag and no polling, so a component rendering warmup state will hold a stale warming/failed value until remount. Either give it a ComplexityAnalyzerConfig-adjacent tag or set pollingInterval where the hook is used.

🤖 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 `@ui/lib/store/apis/governanceApi.ts` around lines 860 - 865, Update the
getComplexitySemanticStatus query usage so consumers refresh asynchronous
warming or failed states without requiring a remount. Prefer adding a
pollingInterval where the generated getComplexitySemanticStatus hook is used, or
add a tag adjacent to ComplexityAnalyzerConfig and invalidate it when status
changes; preserve the existing endpoint request behavior.

🤖 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.

Nitpick comments:
In `@ui/lib/store/apis/governanceApi.ts`:
- Around line 860-865: Update the getComplexitySemanticStatus query usage so
consumers refresh asynchronous warming or failed states without requiring a
remount. Prefer adding a pollingInterval where the generated
getComplexitySemanticStatus hook is used, or add a tag adjacent to
ComplexityAnalyzerConfig and invalidate it when status changes; preserve the
existing endpoint request behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ef346c26-f999-4206-90b6-3457af91fe9b

📥 Commits

Reviewing files that changed from the base of the PR and between 383a002 and fad421f.

📒 Files selected for processing (19)

• core/schemas/bifrost.go
• framework/configstore/complexityconfig.go
• framework/configstore/complexityconfig_test.go
• plugins/governance/complexity/config.go
• plugins/governance/complexity/exemplars.go
• plugins/governance/complexity/exemplars_test.go
• plugins/governance/complexity/semanticclassifier.go
• plugins/governance/complexity/semanticclassifier_test.go
• plugins/governance/embedding.go
• plugins/governance/embedding_test.go
• plugins/governance/main.go
• plugins/governance/prerequesthookcomplexity_test.go
• transports/bifrost-http/handlers/governance.go
• transports/bifrost-http/handlers/governance_test.go
• transports/bifrost-http/server/server.go
• ui/app/workspace/complexity-router/page.tsx
• ui/lib/store/apis/governanceApi.ts
• ui/lib/types/complexityRouter.ts
• ui/lib/types/logs.ts

[coderabbitai]

Actionable comments posted: 1

Caution

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

⚠️ Outside diff range comments (1)

ui/app/workspace/complexity-router/page.tsx (1)

379-385: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Attach the dependency to the field being validated, not the source field.

The validation on medium_complex depends on the value of simple_medium. Line 380 checks value <= simple_medium when key === "medium_complex". When simple_medium changes, medium_complex must revalidate.

The current code sets deps on the simple_medium registration, not on medium_complex. React Hook Form requires deps to be attached to the field that depends on other fields. Set deps on medium_complex to declare its dependency on simple_medium:

Proposed fix

-								deps: key === "simple_medium" ? ["tier_boundaries.medium_complex"] : undefined,
+								deps: key === "medium_complex" ? ["tier_boundaries.simple_medium"] : undefined,

This change ensures medium_complex revalidates when simple_medium changes, preventing stale validity states between edits.

🤖 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 `@ui/app/workspace/complexity-router/page.tsx` around lines 379 - 385, Update
the validation registration around the `key === "medium_complex"` branch so
`deps` is assigned to the `medium_complex` field and references `simple_medium`.
Remove the current dependency assignment from the `simple_medium` registration
while preserving the existing validation logic.

🤖 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 `@ui/app/workspace/complexity-router/page.tsx`:
- Around line 102-114: Update the semantic schema’s timeout field in the visible
semantic object to validate a numeric millisecond wire value instead of a
string. Keep the field optional and preserve the validation behavior of the
other semantic properties so saved configurations continue through handleSubmit
when lexical fields are edited.

---

Outside diff comments:
In `@ui/app/workspace/complexity-router/page.tsx`:
- Around line 379-385: Update the validation registration around the `key ===
"medium_complex"` branch so `deps` is assigned to the `medium_complex` field and
references `simple_medium`. Remove the current dependency assignment from the
`simple_medium` registration while preserving the existing validation logic.

🪄 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: 676152c0-0ec0-4009-8552-ced677cf4e38

📥 Commits

Reviewing files that changed from the base of the PR and between 3747cee and e755887.

📒 Files selected for processing (19)

• core/schemas/bifrost.go
• framework/configstore/complexityconfig.go
• framework/configstore/complexityconfig_test.go
• plugins/governance/complexity/config.go
• plugins/governance/complexity/exemplars.go
• plugins/governance/complexity/exemplars_test.go
• plugins/governance/complexity/semanticclassifier.go
• plugins/governance/complexity/semanticclassifier_test.go
• plugins/governance/embedding.go
• plugins/governance/embedding_test.go
• plugins/governance/main.go
• plugins/governance/prerequesthookcomplexity_test.go
• transports/bifrost-http/handlers/governance.go
• transports/bifrost-http/handlers/governance_test.go
• transports/bifrost-http/server/server.go
• ui/app/workspace/complexity-router/page.tsx
• ui/lib/store/apis/governanceApi.ts
• ui/lib/types/complexityRouter.ts
• ui/lib/types/logs.ts

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

• ui/lib/types/logs.ts
• plugins/governance/embedding_test.go
• plugins/governance/prerequesthookcomplexity_test.go
• plugins/governance/complexity/config.go
• ui/lib/store/apis/governanceApi.ts
• framework/configstore/complexityconfig_test.go
• plugins/governance/complexity/exemplars_test.go
• framework/configstore/complexityconfig.go
• transports/bifrost-http/handlers/governance_test.go
• transports/bifrost-http/server/server.go
• plugins/governance/complexity/exemplars.go
• transports/bifrost-http/handlers/governance.go
• plugins/governance/embedding.go
• plugins/governance/main.go
• plugins/governance/complexity/semanticclassifier_test.go
• plugins/governance/complexity/semanticclassifier.go
• ui/lib/types/complexityRouter.ts

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

plugins/governance/complexity/semanticclassifier.go (1)

538-539: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Remove the always-true wrapper condition.

dimension is assigned 0 on Line 538, so the if dimension == 0 test on Line 539 is always true. The inner test on Line 569 carries the real meaning. Delete the outer condition and dedent the block to make the probe logic readable.

🤖 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 `@plugins/governance/complexity/semanticclassifier.go` around lines 538 - 539,
Remove the redundant outer dimension == 0 condition around the probe logic,
since dimension is initialized to zero immediately beforehand. Dedent the
enclosed block while preserving the inner test near line 569 and its existing
behavior.

🤖 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 `@plugins/governance/complexity/semanticclassifier.go`:
- Around line 290-302: Add a closed state protected by c.mu and set it in Close
before releasing the lock, then update resetForCurrentConfigLocked and
requestWarmupLocked to return immediately when the classifier is closed. Ensure
post-Close Configure, SetConfiguredStore, and SetEmbeddingFunc calls cannot
restart warmup or reuse the closed ownedStore.
- Around line 556-580: Update the batch embedding handling in the
dimension-detection flow to reject a zero-length vector immediately after
receiving the batch result, before assigning dimension or advancing pending.
Return the existing dimension-detection error with the relevant exemplar
context, ensuring malformed empty probe vectors cannot reach the pending[0]
warmup probe in runWarmupWorker.

---

Nitpick comments:
In `@plugins/governance/complexity/semanticclassifier.go`:
- Around line 538-539: Remove the redundant outer dimension == 0 condition
around the probe logic, since dimension is initialized to zero immediately
beforehand. Dedent the enclosed block while preserving the inner test near line
569 and its existing behavior.

🪄 Autofix

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: f1b69934-f781-4551-ba9a-58bd77d255b3

📥 Commits

Reviewing files that changed from the base of the PR and between 2e66e15 and 1936bfc.

📒 Files selected for processing (6)

• core/schemas/bifrost.go
• framework/configstore/complexityconfig.go
• framework/configstore/complexityconfig_test.go
• plugins/governance/complexity/semanticclassifier.go
• plugins/governance/complexity/semanticclassifier_test.go
• ui/app/workspace/complexity-router/page.tsx

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

• ui/app/workspace/complexity-router/page.tsx
• framework/configstore/complexityconfig.go
• framework/configstore/complexityconfig_test.go

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.