feat(router): add LLM routing with cost optimization and pretrained configs

Extend SemanticRouter to support LLM model selection by adding optional
model, confidence, cost optimization, and multi-match capabilities to
the existing routing infrastructure.

When a Route includes a `model` field, the router returns the LiteLLM-
compatible model identifier alongside the match, with a confidence score
derived from vector distance. Cost-optimized routing biases toward
cheaper models when semantic distances are close, using a configurable
cost_weight penalty.

Key additions to SemanticRouter:
- Route.model (optional) for LiteLLM model identifiers
- RouteMatch.confidence, .alternatives, .metadata fields
- RoutingConfig.cost_optimization and .cost_weight settings
- RoutingConfig.default_route for fallback when no match found
- from_pretrained() to load routers with pre-computed embeddings
- export_with_embeddings() to serialize routers with vectors
- AsyncSemanticRouter with full async parity

A built-in "default" pretrained config ships with 3 tiers (simple,
standard, expert) mapped to GPT-4.1 Nano, Claude Sonnet 4.5, and
Claude Opus 4.5, using pre-computed sentence-transformers embeddings.

Backward compatibility:
- LLMRouter/AsyncLLMRouter provided as deprecated wrappers
- ModelTier subclass enforces required model field
- Legacy field names (tiers/default_tier) mapped bidirectionally
- Existing SemanticRouter usage is fully unaffected

Includes integration tests, unit tests for schema validation,
a user guide notebook, and a pretrained config generation script.

Author: bsbodden

docs/user_guide/13_llm_router.ipynb

@@ -1,4 +1,25 @@
-from redisvl.extensions.router.schema import Route, RoutingConfig
-from redisvl.extensions.router.semantic import SemanticRouter
+from redisvl.extensions.router.schema import (
+    DistanceAggregationMethod,
+    PretrainedReference,
+    PretrainedRoute,
+    PretrainedRouterConfig,
+    Route,
+    RouteMatch,
+    RoutingConfig,
+)
+from redisvl.extensions.router.semantic import AsyncSemanticRouter, SemanticRouter
 
-__all__ = ["SemanticRouter", "Route", "RoutingConfig"]
+__all__ = [
+    # Main router classes
+    "SemanticRouter",
+    "AsyncSemanticRouter",
+    # Schema classes
+    "Route",
+    "RouteMatch",
+    "RoutingConfig",
+    "DistanceAggregationMethod",
+    # Pretrained classes
+    "PretrainedReference",
+    "PretrainedRoute",
+    "PretrainedRouterConfig",
+]

redisvl/extensions/router/__init__.py

@@ -0,0 +1,30 @@
+"""Pretrained router configurations.
+
+This module provides pre-built router configurations that can be loaded
+without needing to re-embed references.
+"""
+
+from pathlib import Path
+
+PRETRAINED_DIR = Path(__file__).parent
+
+
+def get_pretrained_path(name: str) -> Path:
+    """Get path to a pretrained configuration.
+
+    Args:
+        name: Pretrained config name (e.g., "default", "cost_optimized")
+
+    Returns:
+        Path to the pretrained JSON file.
+    """
+    path = PRETRAINED_DIR / f"{name}.json"
+    if not path.exists():
+        available = [f.stem for f in PRETRAINED_DIR.glob("*.json")]
+        raise ValueError(
+            f"Pretrained config '{name}' not found. " f"Available: {available}"
+        )
+    return path
+
+
+__all__ = ["get_pretrained_path", "PRETRAINED_DIR"]