semantic cache: min similarity + fallback logging

[kohlivrinda]

Summary

Briefly explain the purpose of this PR and the problem it solves.

Changes

• What was changed and why
• Any notable design decisions or trade-offs

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

Describe the steps to validate this change. Include commands and expected outcomes.

# Core/Transports
go version
go test ./...

# UI
cd ui
pnpm i || npm i
pnpm test || npm test
pnpm build || npm run build

If adding new configs or environment variables, document them here.

Screenshots/Recordings

If UI changes, add before/after screenshots or short clips.

Breaking changes

• Yes
• No

If yes, describe impact and migration instructions.

Related issues

Link related issues and discussions. Example: Closes #123

Security considerations

Note any security implications (auth, secrets, PII, sandboxing, etc.).

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

[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 👈 (View in Graphite)
• 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
• 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]

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: 5b484c5f-dcbe-4f5d-9403-4d84acbf548e

📥 Commits

Reviewing files that changed from the base of the PR and between 7fb8358 and cca0807.

📒 Files selected for processing (10)

• framework/configstore/complexityconfig.go
• framework/configstore/complexityconfig_test.go
• plugins/governance/complexity/semanticclassifier.go
• plugins/governance/complexity/semanticclassifier_test.go
• plugins/governance/main.go
• plugins/governance/prerequesthookcomplexity_test.go
• plugins/governance/utils.go
• transports/config.schema.json
• ui/app/workspace/complexity-router/page.tsx
• ui/lib/types/complexityRouter.ts

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

• ui/lib/types/complexityRouter.ts
• plugins/governance/utils.go
• ui/app/workspace/complexity-router/page.tsx
• framework/configstore/complexityconfig_test.go
• plugins/governance/complexity/semanticclassifier_test.go
• plugins/governance/main.go
• framework/configstore/complexityconfig.go
• transports/config.schema.json
• plugins/governance/prerequesthookcomplexity_test.go
• plugins/governance/complexity/semanticclassifier.go

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added an optional minimum similarity threshold for semantic complexity classification.
  • Classification results now include similarity scores, thresholds, and acceptance status.
  • Below-threshold matches use the configured fallback classifier.
  • Routing logs may include matched exemplars for clearer diagnostics.
  • Documented backend-specific similarity scales and fallback behavior.

• Bug Fixes

  • Added validation for thresholds from 0 inclusive to below 1.
  • Improved logging for unavailable classifiers, timeouts, and rejected matches.
  • Preserved diagnostic details for near-threshold matches.
  • Timeout logs now include the configured duration.

Walkthrough

The change adds a configurable [0, 1) minimum similarity threshold. Classification retains near matches, reports acceptance details, and distinguishes unavailable, rejected, and timed-out results in fallback routing logs.

Changes

Semantic similarity threshold

Layer / File(s)	Summary
Configuration contract and validation framework/configstore/complexityconfig.go, framework/configstore/complexityconfig_test.go, transports/config.schema.json, ui/lib/types/complexityRouter.ts, ui/app/workspace/complexity-router/page.tsx	Adds MinSimilarity serialization, normalization, validation, schema support, UI typing, and boundary-value tests.
Application-level semantic acceptance plugins/governance/complexity/semanticclassifier.go, plugins/governance/complexity/semanticclassifier_test.go	Queries nonnegative similarity matches and reports the score, configured threshold, and acceptance status. Tests cover borderline scores and deterministic embeddings.
Fallback routing and diagnostics plugins/governance/main.go, plugins/governance/utils.go, plugins/governance/prerequesthookcomplexity_test.go	Distinguishes semantic rejection, unavailability, and timeout conditions. Routing logs include threshold metrics, timeout duration, or truncated exemplars. The regression test verifies lexical fallback routing.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Mergeability Score: ⚪ Minimal · up to cca08

The current changes introduce no evidenced merge-blocking risk, so the PR is merge-ready after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant RoutingEngine
  participant SemanticClassifier
  participant EmbeddingBackend
  participant FallbackClassifier
  participant RoutingLog

  RoutingEngine->>SemanticClassifier: classify request
  SemanticClassifier->>EmbeddingBackend: query nearest nonnegative-similarity exemplar
  EmbeddingBackend-->>SemanticClassifier: return tier and similarity score
  SemanticClassifier-->>RoutingEngine: return acceptance or timeout result
  alt rejected or timed out
    RoutingEngine->>FallbackClassifier: apply fallback classifier
    RoutingEngine->>RoutingLog: record rejection or timeout diagnostic
  else accepted
    RoutingEngine->>RoutingLog: record matched exemplar
  end

Loading

Possibly related PRs

• maximhq/bifrost#5655: Introduces the semantic routing configuration extended by this change.
• maximhq/bifrost#5680: Shares changes to the semantic classifier and complexity routing flow.
• maximhq/bifrost#5743: Modifies the same semantic routing configuration and fallback behavior.

Suggested reviewers: akshaydeo, impoiler, madhuvod

🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR implements semantic similarity thresholds and fallback logging, but linked issue #123 requires File API support for providers.	Link the issue that covers semantic classification changes, or add the required File API support described in issue #123.
Out of Scope Changes check	⚠️ Warning	All reviewed changes are unrelated to the linked File API Support objective in issue #123.	Update the linked issue to match this PR's semantic classification scope, or remove the unrelated changes.
Description check	⚠️ Warning	The description contains only unfilled template text and omits the PR purpose, changes, testing steps, affected areas, and other required details.	Replace the placeholder text with implementation details, selected change and area types, test commands and results, breaking-change status, security notes, and checklist items.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.
Title check	✅ Passed	The title clearly summarizes the main changes: adding a semantic similarity threshold and improving fallback logging.

✨ 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 07-31-semantic_cache_min_similarity_fallback_logging

---

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

[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 `@plugins/governance/main.go`:
- Around line 753-771: Preserve the rejected semanticResult state through the
fallback decision instead of treating it as unavailable when Fallback() is none.
Update the fallback-disabled handling near the semantic classification branch to
emit a message identifying the rejected result and its below-MinSimilarity
score, while retaining the existing unavailable message only for cases where
classification truly did not produce a result.

🪄 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: e1837271-32b1-4b84-897e-8873ae059635

📥 Commits

Reviewing files that changed from the base of the PR and between 28e1a04 and 0f9b878.

📒 Files selected for processing (6)

• framework/configstore/complexityconfig.go
• framework/configstore/complexityconfig_test.go
• plugins/governance/complexity/semanticclassifier.go
• plugins/governance/complexity/semanticclassifier_test.go
• plugins/governance/main.go
• transports/config.schema.json

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

Caution

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

⚠️ Outside diff range comments (2)

framework/configstore/complexityconfig.go (1)

222-237: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Serialize Timeout as milliseconds.

Line 222 writes a duration string such as "100ms". Config JSON duration fields must use milliseconds. Emit float64(c.Timeout) / float64(time.Millisecond) as the JSON value. Keep the current dual-format decoder so existing stored strings remain readable.

As per coding guidelines, “Config duration fields serialized as JSON must use milliseconds even when represented as time.Duration in Go.”

Proposed fix

 func (c ComplexitySemanticConfig) MarshalJSON() ([]byte, error) {
 	type alias ComplexitySemanticConfig
-	var timeout string
+	var timeout float64
 	if c.Timeout != 0 {
-		timeout = c.Timeout.String()
+		timeout = float64(c.Timeout) / float64(time.Millisecond)
 	}
 	return json.Marshal(struct {
-		Timeout string `json:"timeout,omitempty"`
+		Timeout float64 `json:"timeout,omitempty"`
 		alias
 	}{

🤖 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 222 - 237, Update
ComplexitySemanticConfig.MarshalJSON to serialize Timeout as a numeric
millisecond value using the time.Duration-to-milliseconds conversion, rather
than a duration string. Preserve the existing omitempty behavior for zero
Timeout and leave the dual-format decoder unchanged so previously stored strings
remain readable.

Source: Coding guidelines

ui/lib/types/complexityRouter.ts (1)

19-30: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Preserve semantic.fallback when saving the form.

The resolver strips fallback before updateConfig(values), so saving a config with "none" restores the backend default "lexical".

• Add fallback?: "lexical" | "none" to SemanticConfig.
• Add fallback: z.enum(["lexical", "none"]).optional() to the semantic schema.

🤖 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/types/complexityRouter.ts` around lines 19 - 30, Preserve the semantic
fallback value when saving by adding optional fallback support to SemanticConfig
in ui/lib/types/complexityRouter.ts and to the semantic validation schema in
ui/app/workspace/complexity-router/page.tsx (anchor lines 19-30; sibling lines
106-115), restricting values to "lexical" or "none" so the resolver passes it
through to updateConfig(values).

🤖 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/complexityconfig.go`:
- Around line 222-237: Update ComplexitySemanticConfig.MarshalJSON to serialize
Timeout as a numeric millisecond value using the time.Duration-to-milliseconds
conversion, rather than a duration string. Preserve the existing omitempty
behavior for zero Timeout and leave the dual-format decoder unchanged so
previously stored strings remain readable.

In `@ui/lib/types/complexityRouter.ts`:
- Around line 19-30: Preserve the semantic fallback value when saving by adding
optional fallback support to SemanticConfig in ui/lib/types/complexityRouter.ts
and to the semantic validation schema in
ui/app/workspace/complexity-router/page.tsx (anchor lines 19-30; sibling lines
106-115), restricting values to "lexical" or "none" so the resolver passes it
through to updateConfig(values).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 111ddd87-fbb1-47d4-959f-8846e1ea2a56

📥 Commits

Reviewing files that changed from the base of the PR and between 5fba23f and c0f5bdd.

📒 Files selected for processing (6)

• 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
• ui/lib/types/complexityRouter.ts

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

• plugins/governance/complexity/semanticclassifier_test.go
• framework/configstore/complexityconfig_test.go
• plugins/governance/complexity/semanticclassifier.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.