semantic router #2: semantic routing config

[kohlivrinda]

Summary

Adds a semantic configuration block to the complexity analyzer that enables embedding-based tier classification. When present, the classifier generates embeddings for incoming requests and compares them against per-tier exemplar utterances (derived from the shared keyword lists) to determine complexity, falling back to lexical classification (or no classification) when the embedding call is unavailable or exceeds its timeout.

Changes

• Introduced ComplexitySemanticConfig with fields for provider, embedding model, vector dimension, timeout, fallback behavior, budget tracking, and vector store selection.
• Timeout supports both duration strings ("100ms") and millisecond numbers in JSON, with custom MarshalJSON/UnmarshalJSON to ensure round-trip fidelity.
• Added SemanticSettings to ComplexityAnalyzerConfigHashes. Scalar settings and the shared keyword lists are hashed independently so edits to one do not register as changes to the other.
• GenerateComplexityAnalyzerConfigHashes now populates SemanticSettings when a semantic section is present.
• MergeComplexityAnalyzerConfig and MergeComplexityAnalyzerConfigByHashes handle the semantic section: a missing file section leaves DB state untouched, and hash changes replace the semantic block wholesale.
• Added EmbeddingFingerprint to ComplexityAnalyzerConfig (persisted as _embedding_fingerprint) so warmup can detect when stored exemplar embeddings need to be recomputed.
• UpdateComplexityAnalyzerConfig preserves the stored EmbeddingFingerprint when the caller does not supply one, preventing UI writes from wiping it.
• Added a startup validation step (validateComplexitySemanticVectorStore) that fails fast when vector_store is set to "external" but no vector store is configured.
• Exported SemanticConfig type alias from the complexity plugin package.
• Extended config.schema.json with the complexity_semantic_config definition, including enum constraints on fallback and vector_store, and a dual-type (string/number) schema for timeout.
• ComplexityAnalyzerConfigHashes.Empty() and Equal() now use struct comparison instead of field-by-field checks.

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

go test ./framework/configstore/... ./transports/schema_test/... ./plugins/governance/complexity/...

Key scenarios covered by the new tests:

• TestComplexitySemanticConfigTimeoutDecoding — verifies duration strings, millisecond numbers, absent/null values, and rejection of negative or unparseable values.
• TestComplexitySemanticConfigTimeoutMarshalRoundTrip — confirms JSON encode → decode preserves the timeout.
• TestComplexitySemanticConfigNormalizedDefaults — checks that defaults (100 ms timeout, lexical fallback, embedded vector store) are applied.
• TestComplexitySemanticConfigValidation — exercises all invalid-field paths.
• TestGenerateComplexityAnalyzerConfigHashesSemantic — asserts that keyword edits do not move the semantic settings hash and vice versa.
• TestMergeComplexityAnalyzerConfigByHashesSemantic — covers first-time addition, unchanged-hash preservation, hash-triggered replacement, and file-without-semantic preservation.
• TestRDBConfigStore_ComplexityAnalyzerConfigSemanticPersistence — integration test confirming round-trip persistence and fingerprint preservation across UI-style writes.
• TestSchemaComplexitySemanticConfig — JSON Schema validation for valid and invalid semantic blocks.

New config fields (governance.complexity_analyzer_config.semantic):

Field	Type	Default	Description
provider	string	required	Embedding provider
embedding_model	string	required	Model name
dimension	integer ≥ 2	required	Vector dimension
timeout	string or number	"100ms"	Per-request timeout
fallback	"lexical" | "none"	"lexical"	Behavior when semantic is unavailable
count_toward_budgets	boolean	false	Record embedding cost against budgets
vector_store	"auto" | "embedded" | "external"	"embedded"	Exemplar embedding store

Breaking changes

• Yes
• No

Security considerations

Embedding calls are made against the configured provider using existing credential plumbing. The count_toward_budgets flag is record-only and never enforced, so there is no risk of classification embeddings triggering budget blocks.

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

[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: 2e87a6fc-c151-47b4-8bfa-1ac6a9b4ba71

📥 Commits

Reviewing files that changed from the base of the PR and between c8f0037 and 7f4e855.

📒 Files selected for processing (9)

• framework/configstore/clientconfig.go
• framework/configstore/complexityconfig.go
• framework/configstore/complexityconfig_test.go
• framework/configstore/rdb.go
• plugins/governance/complexity/config.go
• transports/bifrost-http/lib/config.go
• transports/bifrost-http/lib/config_test.go
• transports/config.schema.json
• transports/schema_test/config_schema_test.go

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

• transports/config.schema.json
• plugins/governance/complexity/config.go
• framework/configstore/clientconfig.go
• transports/schema_test/config_schema_test.go
• transports/bifrost-http/lib/config.go
• transports/bifrost-http/lib/config_test.go
• framework/configstore/complexityconfig_test.go
• framework/configstore/rdb.go
• framework/configstore/complexityconfig.go

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added optional embedding-based complexity classification with configurable providers, models, timeouts, fallbacks, budget tracking, and vector-store modes.
  • Standardized complexity keyword tiers to simple, medium, and complex while preserving legacy configuration compatibility.
  • Added configuration schema support and validation for semantic complexity settings.

• Bug Fixes

  • Improved startup handling for unavailable external vector stores.
  • Improved atomic configuration updates and preservation of existing settings during partial updates.

• Tests

  • Expanded coverage for validation, persistence, merging, timeout parsing, concurrency, and vector-store behavior.

Walkthrough

Adds semantic complexity configuration with timeout handling, validation, schema support, hashing, persistence, merge behavior, and startup checks for external vector stores.

Changes

Semantic complexity configuration

Layer / File(s)	Summary
Semantic configuration contracts framework/configstore/complexityconfig.go, plugins/governance/complexity/config.go, transports/config.schema.json, transports/schema_test/config_schema_test.go, framework/configstore/complexityconfig_test.go	Adds semantic configuration types, timeout handling, defaults, validation, schema support, canonical keyword compatibility, and validation tests.
Configstore semantic state framework/configstore/clientconfig.go, framework/configstore/complexityconfig.go, framework/configstore/complexityconfig_test.go	Carries semantic settings, hashes, and embedding fingerprints through normalization, merging, encoding, decoding, and hash generation.
Transactional configuration persistence framework/configstore/rdb.go, framework/configstore/complexityconfig_test.go	Preserves omitted hashes and embedding fingerprints during transactional updates and tests concurrent carry-over behavior.
Startup vector-store validation transports/bifrost-http/lib/config.go, transports/bifrost-http/lib/config_test.go	Validates external vector-store requirements during configuration loading and tests explicit file settings, database-derived settings, configured stores, and non-external modes.

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

Mergeability Score: ⚪ Minimal · up to 7f4e8

The change adds semantic routing configuration with focused persistence, validation, schema, and timeout handling tests; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant LoadConfig
  participant GovernanceConfig
  participant validateComplexitySemanticVectorStore
  participant VectorStore
  LoadConfig->>GovernanceConfig: load governance configuration
  GovernanceConfig->>validateComplexitySemanticVectorStore: validate semantic vector-store mode
  validateComplexitySemanticVectorStore->>VectorStore: check external vector-store initialization
  VectorStore-->>validateComplexitySemanticVectorStore: return configured or missing state
  validateComplexitySemanticVectorStore-->>LoadConfig: return validation result

Loading

Possibly related PRs

• maximhq/bifrost#5602: Adds the canonical keyword configuration and hashing/merge behavior extended by this change.
• maximhq/bifrost#5628: Adds the Chromem vector-store support used by semantic vector-store validation.
• maximhq/bifrost#5656: Implements embedding execution that consumes the semantic configuration.

Suggested reviewers: akshaydeo, impoiler, madhuvod

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.14% 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 the semantic routing configuration change, which matches the primary purpose of the pull request.
Description check	✅ Passed	The description is complete and covers the feature, design changes, testing, affected areas, breaking changes, and security considerations.

✨ 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-29-semantic_routing_config

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[kohlivrinda]

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
• semantic router #3: embedding executor #5656
• semantic router #2: semantic routing config #5655 👈 (View in Graphite)
• 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]

Actionable comments posted: 1

🤖 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 `@transports/config.schema.json`:
- Around line 3518-3544: The provider enum in the complexity classification
configuration is narrower than the providers accepted by
ComplexitySemanticConfig.Validate and custom provider names. Remove the
hardcoded enum from the provider property while retaining type string and
minLength 1, so all non-empty runtime-supported and custom provider values pass
schema validation.

🪄 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: 2aea0e26-0767-46b6-8056-7b7db176f435

📥 Commits

Reviewing files that changed from the base of the PR and between 25e7b2a and 65d0768.

📒 Files selected for processing (8)

• framework/configstore/clientconfig.go
• framework/configstore/complexityconfig.go
• framework/configstore/complexityconfig_test.go
• framework/configstore/rdb.go
• plugins/governance/complexity/config.go
• transports/bifrost-http/lib/config.go
• transports/config.schema.json
• transports/schema_test/config_schema_test.go

[coderabbitai]

Caution

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

⚠️ Outside diff range comments (1)

framework/configstore/rdb.go (1)

5360-5398: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Make the read-modify-write for ConfigHashes/EmbeddingFingerprint atomic.

UpdateComplexityAnalyzerConfig reads the existing row, merges missing fields, then writes it back — a separate DB round-trip without clause.Locking. Concurrent writers such as an API payload/runtime request and file merge can each read stale data and overwrite the other’s field; use a row lock around the read and update, ensuring callers consistently run in a shared transaction.

🤖 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 `@framework/configstore/rdb.go` around lines 5360 - 5398, Make
UpdateComplexityAnalyzerConfig perform the read-modify-write for ConfigHashes
and EmbeddingFingerprint within a shared transaction: when either field is
missing, begin or reuse a transaction, lock the existing configuration row with
the appropriate clause.Locking, merge the missing values, and execute the update
through that same transaction. Preserve validation and encoding behavior, and
ensure the transaction commits on success or rolls back on failure.

🤖 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 `@framework/configstore/rdb.go`:
- Around line 5360-5398: Make UpdateComplexityAnalyzerConfig perform the
read-modify-write for ConfigHashes and EmbeddingFingerprint within a shared
transaction: when either field is missing, begin or reuse a transaction, lock
the existing configuration row with the appropriate clause.Locking, merge the
missing values, and execute the update through that same transaction. Preserve
validation and encoding behavior, and ensure the transaction commits on success
or rolls back on failure.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: f820afb1-d22f-406f-8d93-8b628d393300

📥 Commits

Reviewing files that changed from the base of the PR and between 00825bc and aa0217c.

📒 Files selected for processing (8)

• framework/configstore/clientconfig.go
• framework/configstore/complexityconfig.go
• framework/configstore/complexityconfig_test.go
• framework/configstore/rdb.go
• plugins/governance/complexity/config.go
• transports/bifrost-http/lib/config.go
• transports/config.schema.json
• transports/schema_test/config_schema_test.go

[coderabbitai]

🧹 Nitpick comments (2)

framework/configstore/complexityconfig.go (1)

441-448: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Redundant normalized() calls on already-normalized values.

mergeComplexitySemanticConfig receives normalizedBase.Semantic / normalizedFile.Semantic (both produced by Normalized()), and line 491 re-normalizes normalizedFile.Semantic again. Harmless because normalized() is idempotent, but it does an extra allocation and slightly obscures the invariant. Consider dropping the inner calls, or keeping them and documenting that they exist purely for defensive copying.

Also applies to: 486-494

🤖 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 `@framework/configstore/complexityconfig.go` around lines 441 - 448, The merge
path redundantly normalizes semantic configurations that are already normalized
by Normalized(). Update mergeComplexitySemanticConfig and its callers around
normalizedBase.Semantic and normalizedFile.Semantic to reuse the normalized
values directly, preserving the nil-file behavior and avoiding extra
allocations.

framework/configstore/rdb.go (1)

3065-3092: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Duplicated relation closure across the two preload helpers.

preloadCustomerRelations now redefines the same prefix closure that preloadCustomerRelationsWithoutVirtualKeys already has, only to build one relation name. Inlining it (prefix + "VirtualKeys" guarded on empty prefix, or a small package-level helper) would remove the copy.

🤖 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 `@framework/configstore/rdb.go` around lines 3065 - 3092, Remove the duplicated
relation closure from preloadCustomerRelations and construct the VirtualKeys
preload path using the existing prefix behavior directly or a shared
package-level helper. Keep preloadCustomerRelationsWithoutVirtualKeys unchanged
and preserve correct relation names for both empty and non-empty prefixes.

🤖 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 `@framework/configstore/complexityconfig.go`:
- Around line 441-448: The merge path redundantly normalizes semantic
configurations that are already normalized by Normalized(). Update
mergeComplexitySemanticConfig and its callers around normalizedBase.Semantic and
normalizedFile.Semantic to reuse the normalized values directly, preserving the
nil-file behavior and avoiding extra allocations.

In `@framework/configstore/rdb.go`:
- Around line 3065-3092: Remove the duplicated relation closure from
preloadCustomerRelations and construct the VirtualKeys preload path using the
existing prefix behavior directly or a shared package-level helper. Keep
preloadCustomerRelationsWithoutVirtualKeys unchanged and preserve correct
relation names for both empty and non-empty prefixes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e37c887c-6d59-4ec7-bd29-f2aefd50e739

📥 Commits

Reviewing files that changed from the base of the PR and between aa0217c and d2438a7.

📒 Files selected for processing (8)

• framework/configstore/clientconfig.go
• framework/configstore/complexityconfig.go
• framework/configstore/complexityconfig_test.go
• framework/configstore/rdb.go
• plugins/governance/complexity/config.go
• transports/bifrost-http/lib/config.go
• transports/config.schema.json
• transports/schema_test/config_schema_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.

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