Add hybrid analyzer combining heuristic and LLM judgment

[krugis]

Summary

Introduces a new hybrid analyzer mode that blends deterministic heuristic signals with LLM judgment, combining the explainability and reliability of heuristic analysis with the accuracy of LLM classification on ambiguous prompts.

Key Changes

• New HybridAnalyzer (internal/analyzer/hybrid.go):

  • Always runs the heuristic analyzer first (cheap, never fails)
  • Optionally refines results with LLM judgment when available
  • Blends complexity scores: w * llm_score + (1-w) * heuristic_score where w is configurable (default 0.5)
  • Overrides category only when heuristic had low confidence (detected general)
  • Falls back gracefully to heuristic result on any LLM error
  • Records raw LLM complexity in signals for auditability

• LLMAnalyzer improvements:

  • Exported Classify() method (was private classify()) for use by HybridAnalyzer
  • Enhanced prompt with few-shot examples (6 worked examples spanning all categories with non-round complexity values: 0.05, 0.12, 0.22, 0.38, 0.64, 0.93) to eliminate round-number clustering and calibrate scoring across the full range

• Configuration:

  • Added analyzer.llm.hybrid_weight config field (0..1, default 0.5)
  • Added ModeHybrid constant and validation for new mode
  • Updated config validation to require LLM model for both llm and hybrid modes
  • Added environment variable support: ROUTE42_ANALYZER_LLM_HYBRID_WEIGHT

• Factory pattern:

  • Updated New() to instantiate HybridAnalyzer when mode is hybrid

• Type definitions:

  • Added NameHybrid constant for analyzer identification

• Comprehensive test suite (internal/analyzer/hybrid_test.go):

  • Tests complexity blending with LLM success
  • Tests category override when heuristic detects general
  • Tests fallback to heuristic on LLM errors
  • Tests weight edge cases (0.0 and 1.0)
  • Tests default weight handling for invalid values
  • Tests elimination of round-number clustering problem

• Documentation:

  • Updated analyzer.md, config.md, and README.md with hybrid mode explanation
  • Documented few-shot prompting approach and its benefits
  • Clarified cost, fallback behavior, and signal recording

Notable Implementation Details

• Hybrid mode is a strict superset of heuristic mode's reliability: any LLM failure returns the heuristic result unchanged
• The few-shot prompt examples use non-round complexity values to prevent the LLM from clustering predictions around 0, 0.5, and 1.0
• Heuristic signals are always present; LLM complexity is added to signals only on successful classification for auditability
• Weight validation clamps invalid values (≤0) to default 0.5, ensuring safe operation

https://claude.ai/code/session_01AatiioR5QBGq6NPvHYbLHj