Implement Signal Fusion Engine for prompt classification routing

[Copilot]

Overview

This PR implements the Signal Fusion Engine, a policy-driven decision-making system that combines multiple signals (keyword, regex, embedding similarity, and BERT) into actionable routing decisions. This is a core component of the Prompt Classification Routing proposal.

Motivation

The Signal Fusion Engine enables intelligent routing decisions by:

• Combining multiple signal sources - Allows consensus-based decisions that are more reliable than single-signal routing
• Priority-based safety controls - Ensures safety blocks (e.g., PII detection) always take precedence over routing rules
• Flexible policy configuration - Users can define complex routing logic without code changes
• Short-circuit optimization - First matching rule wins for efficient evaluation

Implementation

Core Components

1. Boolean Expression Parser (expression.go)

// Supports complex expressions like:
"keyword.kubernetes.matched && similarity.infrastructure.score > 0.75"
"regex.ssn.matched || regex.credit-card.matched"
"(keyword.security.matched && bert.category.value == 'security') || similarity.security.score > 0.9"

2. Priority-Based Engine (engine.go)

policy := &Policy{
    Rules: []Rule{
        {Name: "safety-block", Priority: 200, Action: ActionBlock},
        {Name: "k8s-routing", Priority: 150, Action: ActionRoute},
        {Name: "boost-reasoning", Priority: 100, Action: ActionBoostCategory},
    },
}
engine := NewEngine(policy)  // Automatically sorted by priority

3. Type-Safe Data Structures (types.go)

• Signal - Results from signal providers
• Rule - Policy rule with condition and action
• Policy - Collection of rules evaluated in priority order
• EvaluationResult - Result with matched rule and action details

Features

Action Types

• block - Immediately reject requests (e.g., PII detected)
• route - Route to specific model candidates
• boost_category - Apply weight multipliers to BERT categories
• fallthrough - Use default BERT classification

Expression Language

• Boolean operators: && (AND), || (OR), ! (NOT)
• Comparisons: ==, !=, >, <, >=, <=
• Signal references: provider.name.field (e.g., keyword.kubernetes.matched, similarity.reasoning.score)
• Parentheses for grouping complex logic

Testing

Comprehensive test coverage using Ginkgo/Gomega (consistent with project standards):

• 27 unit test specs covering:

  • Simple and complex boolean expressions
  • All comparison operators
  • Nested expressions with parentheses
  • Priority-based evaluation
  • Short-circuit behavior
  • All action types
  • Edge cases and error handling

• 10 example tests demonstrating real-world usage:

  • Basic usage
  • Priority evaluation
  • Complex multi-signal consensus
  • Category boosting
  • Short-circuit behavior
  • Fallthrough handling
  • End-to-end integration
  • Action handling patterns
  • Policy loading from configuration
  • Signal provider integration

All tests passing: 27 Passed | 0 Failed

Example Usage

context := fusion.NewSignalContext()

// Add signals from providers
context.AddSignal(fusion.Signal{
    Provider: "keyword",
    Name:     "kubernetes",
    Matched:  true,
})
context.AddSignal(fusion.Signal{
    Provider: "similarity",
    Name:     "infrastructure",
    Score:    0.85,
})

// Define policy
policy := &fusion.Policy{
    Rules: []fusion.Rule{
        {
            Name:      "safety-block",
            Condition: "regex.ssn.matched || regex.credit-card.matched",
            Action:    fusion.ActionBlock,
            Priority:  200,
            Message:   "PII detected",
        },
        {
            Name:      "k8s-routing",
            Condition: "keyword.kubernetes.matched && similarity.infrastructure.score > 0.75",
            Action:    fusion.ActionRoute,
            Priority:  150,
            Models:    []string{"k8s-expert", "devops-model"},
        },
    },
}

// Evaluate
engine := fusion.NewEngine(policy)
result, _ := engine.Evaluate(context)
// Result: Matched rule "k8s-routing", route to ["k8s-expert", "devops-model"]

Configuration and Integration

Configuration Guide

Comprehensive configuration documentation is provided in CONFIGURATION.md, including:

• Router Configuration Structure: How to extend RouterConfig with ContentScanningConfig
• YAML Configuration: Complete examples for both inline and external configuration files
• Signal Provider Setup: Configuration for keyword matching, regex scanning, and embedding similarity
• Fusion Policy Rules: How to define and organize policy rules by priority

Example Configuration Files

Ready-to-use example configurations in config/fusion/:

• config.fusion-example.yaml - Complete router configuration with fusion engine enabled
• policy_rules.yaml - Example fusion policy rules organized by priority (safety, routing, boosting, consensus)
• keyword_rules.yaml - Keyword matching rules for various topics (Kubernetes, security, databases, etc.)
• regex_patterns.yaml - Security patterns for PII detection, CVE IDs, and injection attempts
• similarity_concepts.yaml - Embedding similarity concepts for reasoning, infrastructure, and code generation

Integration Examples

Working integration examples in integration_example_test.go demonstrate:

• End-to-end flow: From signal gathering through policy evaluation to routing decision
• Action handling: How to handle block, route, boost, and fallthrough actions
• Configuration loading: Converting YAML configuration to fusion policy
• Signal provider integration: How different providers contribute signals

Integration Path

This engine integrates with the existing semantic router architecture:

1. Load Configuration: Parse YAML config with fusion policy rules
2. Initialize Engine: Create fusion engine from policy configuration
3. Gather Signals: Collect signals from keyword, regex, similarity, and BERT providers
4. Evaluate Policy: Run fusion engine to determine routing decision
5. Execute Action: Handle block, route, boost, or fallthrough based on result

See CONFIGURATION.md for detailed integration guide with code examples.

Documentation

• README.md: Core functionality, usage examples, and architecture
• CONFIGURATION.md: Complete configuration guide with YAML examples and router integration
• Inline code documentation throughout
• 10 working example tests demonstrating all features
• Example configuration files for all components

Closes

Resolves the Signal Fusion Engine requirements from the Prompt Classification Routing issue.

[!WARNING]

Fixes #367

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Prompt Classification] Implement Signal Fusion Engine</issue_title>
<issue_description># Goal
Build policy engine to combine signals into routing decisions.

Acceptance Criteria

• Configurable boolean expression parser for conditions
• Configurable priority-based rule evaluation
• Configurable short-circuit evaluation (e.g. first match wins)
• Unit tests
  </issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #367

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[netlify]

✅ Deploy Preview for vllm-semantic-router ready!

Name	Link
🔨 Latest commit	6c759d9
🔍 Latest deploy log	https://app.netlify.com/projects/vllm-semantic-router/deploys/68ef476a7153c80008b9f3ed
😎 Deploy Preview	https://deploy-preview-437--vllm-semantic-router.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[wangchen615]

The engine implementation looks good to me, yet I need more support from how to configure the config.yaml and how the router can read those routing rules and use the engine to route the request. @copilot

[github-actions]

👥 vLLM Semantic Team Notification

The following members have been identified for the changed files in this PR and have been automatically assigned:

📁 config

Owners: @rootfs
Files changed:

• config/config.fusion-example.yaml
• config/fusion/keyword_rules.yaml
• config/fusion/policy_rules.yaml
• config/fusion/regex_patterns.yaml
• config/fusion/similarity_concepts.yaml

📁 src

Owners: @rootfs, @Xunzhuo, @wangchen615
Files changed:

• src/semantic-router/pkg/utils/fusion/CONFIGURATION.md
• src/semantic-router/pkg/utils/fusion/README.md
• src/semantic-router/pkg/utils/fusion/engine.go
• src/semantic-router/pkg/utils/fusion/example_test.go
• src/semantic-router/pkg/utils/fusion/expression.go
• src/semantic-router/pkg/utils/fusion/fusion_test.go
• src/semantic-router/pkg/utils/fusion/integration_example_test.go
• src/semantic-router/pkg/utils/fusion/types.go

---

🎉 Thanks for your contributions!

This comment was automatically generated based on the OWNER files in the repository.

[Copilot]

The engine implementation looks good to me, yet I need more support from how to configure the config.yaml and how the router can read those routing rules and use the engine to route the request. @Copi...

I've added comprehensive configuration documentation and integration examples. See the new files:

Configuration Guide:

• CONFIGURATION.md - Complete guide with YAML examples and integration patterns

Example Config Files:

• config/config.fusion-example.yaml - Full router config with fusion engine enabled
• config/fusion/policy_rules.yaml - Example fusion policy rules
• config/fusion/keyword_rules.yaml - Keyword matching rules
• config/fusion/regex_patterns.yaml - Regex patterns for security scanning
• config/fusion/similarity_concepts.yaml - Embedding similarity concepts

Integration Examples:

• integration_example_test.go - Working examples showing how to integrate with router

The configuration guide shows:

1. How to add ContentScanningConfig to RouterConfig
2. YAML configuration structure (both inline and external files)
3. Step-by-step integration with the router (load config → initialize engine → gather signals → evaluate policy → route)
4. Complete examples for different use cases (safety-first, specialized routing, multi-signal consensus)

All examples are tested and working (commit 8ae9adb).