[Skills Router] Implement Hybrid Pre-Router with Heuristic Scoring

[fentz26]

Summary

Implement the hybrid pre-router component that uses multiple fast heuristics to score skills without LLM calls.

Parent Epic

• 🧭 Epic: Skills Router (Cross-Repo) #82

Components

• Exact Match: Direct ID or name match (highest weight)
• Keyword/Tag Matching: TF-IDF based tokenization and matching
• Capability Matching: Match required capabilities to skill capabilities
• Description Similarity: Simple TF-IDF scoring against skill descriptions
• Popularity Scoring: Factor in usage statistics
• Recency Scoring: Prefer recently updated skills

Implementation

Files to Create

• internal/registry/skill/router/pre_router.go
• internal/registry/skill/router/scorers.go

Key Data Structures

type HeuristicScorer struct {
    weights map[string]float64
}

func (h *HeuristicScorer) Score(query string, skill Skill) float64 {
    score := 0.0
    score += h.weights["exact"] * exactMatchScore(query, skill)
    score += h.weights["keyword"] * keywordScore(query, skill)
    score += h.weights["capability"] * capabilityScore(query, skill)
    score += h.weights["description"] * tfidfScore(query, skill.Description)
    score += h.weights["popularity"] * skill.PopularityScore
    score += h.weights["recency"] * recencyScore(skill.UpdatedAt)
    return score
}

Configuration

skills_router:
  heuristic_weights:
    exact: 1.0
    keyword: 0.7
    capability: 0.8
    description: 0.5
    popularity: 0.3
    recency: 0.2

Acceptance Criteria

• Can match skills by exact ID/name
• Can match skills by keywords/tags
• Can match skills by required capabilities
• Returns scored skill matches with confidence
• Configurable heuristic weights via config
• Unit tests for each scorer
• Benchmark tests for performance

Testing

• Test exact match scorer
• Test keyword scorer with various inputs
• Test capability matching logic
• Test weighted combination
• Verify latency < 50ms for 100 skills