semantic router #3: embedding executor

[kohlivrinda]

Summary

Wires the bifrost embedding client into the governance plugin so it can call out to an embedding provider for semantic complexity classification. Previously the governance plugin had no way to generate embeddings; this adds the executor interface, the embedding call logic, and the server-side wiring at both bootstrap and plugin reload time.

Changes

• Added EmbeddingRequestExecutor type and EmbeddingExecutorSetter interface to the governance plugin, mirroring the pattern already used by the semantic cache plugin.
• Implemented SetEmbeddingRequestExecutor, embeddingExecutor, CanClassifySemantically, and generateEmbedding on GovernancePlugin. The executor is stored atomically to allow safe concurrent access during plugin reloads and request classification.
• generateEmbedding handles all embedding response encodings (string JSON, float64 array, 2D float64 array, int8, int32) by normalising them to []float32 for uniform cosine similarity comparison.
• The embedding context is derived with a hard timeout from SemanticConfig.Timeout (defaulting to configstore.DefaultComplexitySemanticTimeout), skips the plugin pipeline to prevent recursion, and clears caller routing state so the internal request behaves like a fresh external embeddings call.
• Added embeddingRequestExecutor atomic.Pointer[EmbeddingRequestExecutor] field to GovernancePlugin.
• The HTTP server now wires the executor to any governance plugin implementing EmbeddingExecutorSetter during both Bootstrap and ReloadPlugin, consistent with how the semantic cache plugin is handled.

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 ./plugins/governance/...
go test ./transports/bifrost-http/...

Key test scenarios covered:

• TestGenerateEmbeddingDecodesAllEncodings — verifies all five embedding wire formats are correctly normalised to []float32.
• TestGenerateEmbeddingRequestShape — asserts the outbound request carries the correct provider, model, input text, skip-pipeline flag, and a bounded deadline.
• TestGenerateEmbeddingTimeoutCancelsCall — confirms a slow provider is cancelled within the configured timeout window.
• TestGenerateEmbeddingGuards — covers nil executor, nil semantic config, empty response, and executor teardown.
• TestCanClassifySemantically — validates the readiness gate across all partial-configuration combinations.

Breaking changes

• Yes
• No

Related issues

Prerequisite for semantic complexity classification (task #5 — exemplar warmup).

Security considerations

The internal embedding request explicitly clears caller key-routing and body-transport state and skips the plugin pipeline, preventing the governance plugin from inadvertently inheriting or leaking caller credentials or routing context into the embedding call.

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: 9d9d5697-8e73-43a2-9d2a-cf5c8d2a7d3e

📥 Commits

Reviewing files that changed from the base of the PR and between a7329f0 and ae27dad.

📒 Files selected for processing (5)

• core/utils.go
• plugins/governance/embedding.go
• plugins/governance/embedding_test.go
• plugins/governance/main.go
• transports/bifrost-http/server/server.go

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

• plugins/governance/main.go

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added semantic complexity classification using governance-side embeddings.
  • Supports multiple embedding payload formats and normalizes them for similarity scoring.
  • Automatically wires the governance embedding capability during server bootstrap and plugin reloads.
• Bug Fixes
  • Improved internal request handling to prevent recursive plugin pipeline execution during embedding calls.
  • Added bounded semantic-timeout cancellation and stricter validation for missing configuration, unset executors, or empty embedding responses.
• Tests
  • Added tests for decoding all supported formats, request shape, token usage extraction, timeout behavior, guardrails, and semantic readiness checks.

Walkthrough

Changes

Governance now accepts a concurrency-safe embedding executor, creates timeout-bounded internal requests, normalizes multiple embedding formats to []float32, and gates semantic classification on configuration readiness. Server bootstrap and reload wire the executor automatically, with tests covering decoding, cancellation, request shape, and guards.

Governance embedding execution

Layer / File(s)	Summary
Executor contract and server wiring plugins/governance/embedding.go, plugins/governance/main.go, transports/bifrost-http/server/server.go	Defines and atomically stores the embedding executor, then wires s.Client.EmbeddingRequest during bootstrap and plugin reload.
Internal embedding request generation core/utils.go, plugins/governance/embedding.go	Prepares internal request context, applies semantic timeouts, skips recursive plugin processing, clears caller routing state, invokes the executor, and converts supported formats to []float32.
Semantic readiness and validation plugins/governance/embedding.go, plugins/governance/embedding_test.go	Requires an executor and valid semantic configuration, with tests for decoding, token usage, request fields, timeout cancellation, empty responses, unset executors, and readiness guards.

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

Sequence Diagram(s)

sequenceDiagram
  participant Server
  participant GovernancePlugin
  participant EmbeddingRequest
  participant BifrostEmbeddingResponse
  Server->>GovernancePlugin: Wire s.Client.EmbeddingRequest
  GovernancePlugin->>GovernancePlugin: Prepare timeout-bounded internal context
  GovernancePlugin->>EmbeddingRequest: Send embedding request
  EmbeddingRequest-->>GovernancePlugin: Return embedding response
  GovernancePlugin->>GovernancePlugin: Normalize embedding values

Loading

Possibly related PRs

• maximhq/bifrost#5680: Adds the semantic complexity classifier and tiering logic that consumes governance embedding execution.

Suggested reviewers: akshaydeo, pratham-mishra04

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.36% 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
Title check	✅ Passed	The title is concise and accurately reflects the main change: wiring an embedding executor into semantic routing.
Description check	✅ Passed	The description follows the template and includes the required summary, changes, testing, type, affected areas, security, and checklist sections.
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.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch 07-29-semantic_router_embedding_executor

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 07-29-semantic_router_embedding_executor

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.2)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

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

• smenatic router: budgeting+telemetry management #5686
• semantic routing #5: added semantic classifier for complexity router + handlers changes #5680
• semantic router #3: embedding executor #5656 👈 (View in Graphite)
• 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)

plugins/governance/embedding.go (1)

68-75: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

generateEmbedding doesn't re-validate Dimension >= 2 like CanClassifySemantically.

If a caller ever invokes generateEmbedding without first gating on CanClassifySemantically, an under-specified Dimension (e.g. 0 or 1) would slip through and produce a vector whose length is never checked against the configured dimension, risking silent mismatches downstream in similarity comparisons.

🛡️ Optional defensive check

 	if semantic == nil || semantic.Provider == "" || semantic.EmbeddingModel == "" {
 		return nil, 0, fmt.Errorf("semantic classification is not configured")
 	}
+	if semantic.Dimension < 2 {
+		return nil, 0, fmt.Errorf("semantic classification dimension is not configured")
+	}

🤖 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/embedding.go` around lines 68 - 75, Update
GovernancePlugin.generateEmbedding to validate semantic.Dimension is at least 2,
matching CanClassifySemantically, before issuing the embedding request; return
the existing configuration error path for invalid dimensions so direct callers
cannot produce unchecked vector-length mismatches.

🤖 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 `@plugins/governance/embedding.go`:
- Around line 68-75: Update GovernancePlugin.generateEmbedding to validate
semantic.Dimension is at least 2, matching CanClassifySemantically, before
issuing the embedding request; return the existing configuration error path for
invalid dimensions so direct callers cannot produce unchecked vector-length
mismatches.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 2d0bb6f7-10f9-4ebe-8e31-7c52b27420df

📥 Commits

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

📒 Files selected for processing (4)

• plugins/governance/embedding.go
• plugins/governance/embedding_test.go
• plugins/governance/main.go
• transports/bifrost-http/server/server.go

[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/embedding.go`:
- Line 97: Remove the BifrostContextKeySkipPluginPipeline assignment from the
embedding plugin and move the anti-recursion behavior into a core-owned executor
API or option. Update the relevant core execution path to apply this behavior
internally, then have the plugin invoke that API without setting reserved
context keys.

🪄 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 Plus

Run ID: 72d93fbc-300d-4ee7-b75c-102e93e9033c

📥 Commits

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

📒 Files selected for processing (4)

• plugins/governance/embedding.go
• plugins/governance/embedding_test.go
• plugins/governance/main.go
• transports/bifrost-http/server/server.go

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

• plugins/governance/main.go