opusmanSEEKv4/src/nexus_os/engine/route_classes.py

"""Route class definitions for NexusRoutePlane.

Defines logical route classes that abstract provider/model specifics.
Following the redesign doc: coding_fast, coding_deep, research_fast, etc.
Each route class has specific weights for trust, latency, and cost optimization.
"""

from enum import Enum
from typing import Any, Dict, List, Optional
from dataclasses import dataclass, field


class RouteClass(Enum):
    """Logical route classes for model selection."""
    CODING_FAST = "coding_fast"
    CODING_DEEP = "coding_deep"
    RESEARCH_FAST = "research_fast"
    RESEARCH_BROAD = "research_broad"
    GOVERNED_CRITICAL = "governed_critical"
    JOKER_OPUS = "joker_opus"
    JOKER_GROK = "joker_grok"
    LOCAL_ONLY = "local_only"
    CHEAP_FALLBACK = "cheap_fallback"
    BENCHMARK_PROBE = "benchmark_probe"


@dataclass
class RouteWeights:
    """Weight configuration for route class optimization.

    Weights are multiplicative factors applied to provider scores.
    Higher values = more important for this route class.

    Default weights (1.0) mean no special preference.
    Values > 1.0 increase importance, < 1.0 decrease importance.
    """
    trust: float = 1.0
    latency: float = 1.0
    cost: float = 1.0
    health: float = 1.0
    availability: float = 1.0


@dataclass
class RouteProvider:
    """Provider instance within a route class."""
    provider_id: str
    model_family: str
    provider_instance: str
    priority: int = 100
    trust_weight: float = 1.0
    health_weight: float = 1.0
    cost_weight: float = 1.0
    latency_weight: float = 1.0
    availability_weight: float = 1.0
    metadata: Dict[str, Any] = field(default_factory=dict)


@dataclass
class RouteClassConfig:
    """Configuration for a route class."""
    route_class: RouteClass
    providers: List[RouteProvider] = field(default_factory=list)
    policy_gate: str = "allow"  # allow, deny, review
    description: str = ""
    weights: RouteWeights = field(default_factory=RouteWeights)


# =============================================================================
# ROUTE CLASS CONFIGURATIONS WITH SPECIFIC WEIGHTS
# =============================================================================

CODING_FAST_WEIGHTS = RouteWeights(
    trust=1.0,      # Standard trust requirements
    latency=2.0,    # PRIORITY: Fast responses critical
    cost=1.2,       # Slightly prefer cheaper options
    health=1.5,     # High health importance for reliability
    availability=1.5,  # Must be highly available
)

CODING_DEEP_WEIGHTS = RouteWeights(
    trust=1.5,      # PRIORITY: Higher trust for complex reasoning
    latency=0.8,    # Slower acceptable for quality
    cost=0.8,       # Cost less important than quality
    health=1.2,     # Good health needed
    availability=1.2,  # Good availability
)

RESEARCH_BROAD_WEIGHTS = RouteWeights(
    trust=1.3,      # PRIORITY: Trust important for research accuracy
    latency=0.6,    # Latency less critical for research
    cost=1.5,       # PRIORITY: Cost efficiency for large research tasks
    health=1.0,     # Standard health
    availability=1.0,  # Standard availability
)

# Default route class configurations with specific weights
DEFAULT_ROUTE_CONFIGS: Dict[RouteClass, RouteClassConfig] = {
    RouteClass.CODING_FAST: RouteClassConfig(
        route_class=RouteClass.CODING_FAST,
        description="Fast coding tasks, quick responses - optimized for latency",
        weights=CODING_FAST_WEIGHTS,
        providers=[
            RouteProvider(
                provider_id="minimax-fast",
                model_family="minimax_m2",
                provider_instance="nvidia_openai_compatible",
                priority=10,
                latency_weight=1.5,  # Fast provider
                cost_weight=1.2,
            ),
            RouteProvider(
                provider_id="openrouter-fast",
                model_family="mixed",
                provider_instance="openrouter",
                priority=20,
                latency_weight=1.3,
                availability_weight=1.3,  # Good fallback
            ),
            RouteProvider(
                provider_id="groq-llama",
                model_family="llama3",
                provider_instance="groq",
                priority=15,
                latency_weight=1.8,  # Very fast
                cost_weight=1.1,
            ),
        ],
    ),
    RouteClass.CODING_DEEP: RouteClassConfig(
        route_class=RouteClass.CODING_DEEP,
        description="Deep reasoning coding tasks - optimized for trust and accuracy",
        weights=CODING_DEEP_WEIGHTS,
        providers=[
            RouteProvider(
                provider_id="opus-deep",
                model_family="claude_opus",
                provider_instance="foundry-joker",
                priority=10,
                trust_weight=1.5,  # High trust
                latency_weight=0.7,  # Slower OK
            ),
            RouteProvider(
                provider_id="claude-sonnet",
                model_family="claude_sonnet",
                provider_instance="anthropic",
                priority=20,
                trust_weight=1.3,
                cost_weight=0.9,
            ),
        ],
    ),
    RouteClass.RESEARCH_BROAD: RouteClassConfig(
        route_class=RouteClass.RESEARCH_BROAD,
        description="Broad research tasks - optimized for cost and breadth",
        weights=RESEARCH_BROAD_WEIGHTS,
        providers=[
            RouteProvider(
                provider_id="openrouter-mixed",
                model_family="mixed",
                provider_instance="openrouter",
                priority=10,
                cost_weight=1.8,  # Cost efficient
                trust_weight=1.1,
            ),
            RouteProvider(
                provider_id="local-ollama",
                model_family="llama3",
                provider_instance="ollama",
                priority=20,
                cost_weight=2.0,  # Very cheap (local)
                latency_weight=0.5,  # Slower
            ),
            RouteProvider(
                provider_id="perplexity-online",
                model_family="perplexity",
                provider_instance="perplexity",
                priority=15,
                trust_weight=1.4,  # Good for research
                cost_weight=1.2,
            ),
        ],
    ),
    RouteClass.GOVERNED_CRITICAL: RouteClassConfig(
        route_class=RouteClass.GOVERNED_CRITICAL,
        description="Critical governed operations - maximum trust required",
        weights=RouteWeights(
            trust=2.0,      # MAXIMUM trust
            latency=0.5,    # Can be slow
            cost=0.5,       # Cost irrelevant
            health=1.5,     # High health
            availability=1.0,
        ),
        providers=[
            RouteProvider(
                provider_id="opus-governed",
                model_family="claude_opus",
                provider_instance="foundry-joker",
                priority=10,
                trust_weight=2.0,
                health_weight=1.5,
            ),
        ],
    ),
    RouteClass.JOKER_OPUS: RouteClassConfig(
        route_class=RouteClass.JOKER_OPUS,
        description="Opus joker lane for high-capacity reasoning",
        weights=RouteWeights(
            trust=1.4,
            latency=0.7,
            cost=0.8,
            health=1.2,
            availability=1.1,
        ),
        providers=[
            RouteProvider(
                provider_id="joker-opus",
                model_family="claude_opus",
                provider_instance="foundry",
                priority=10,
                trust_weight=1.5,
            ),
        ],
    ),
    RouteClass.JOKER_GROK: RouteClassConfig(
        route_class=RouteClass.JOKER_GROK,
        description="Grok joker lane for fast synthesis",
        weights=RouteWeights(
            trust=1.2,
            latency=1.5,
            cost=1.0,
            health=1.1,
            availability=1.2,
        ),
        providers=[
            RouteProvider(
                provider_id="joker-grok",
                model_family="grok",
                provider_instance="foundry",
                priority=10,
                trust_weight=1.2,
                latency_weight=1.4,
            ),
        ],
    ),
    RouteClass.LOCAL_ONLY: RouteClassConfig(
        route_class=RouteClass.LOCAL_ONLY,
        description="Local-only execution for privacy",
        weights=RouteWeights(
            trust=1.0,
            latency=0.8,
            cost=2.0,      # Free (local)
            health=1.0,
            availability=0.8,
        ),
        providers=[
            RouteProvider(
                provider_id="local-llama",
                model_family="llama3",
                provider_instance="ollama",
                priority=10,
                cost_weight=2.0,
            ),
        ],
    ),
    RouteClass.CHEAP_FALLBACK: RouteClassConfig(
        route_class=RouteClass.CHEAP_FALLBACK,
        description="Cost-optimized fallback for non-critical tasks",
        weights=RouteWeights(
            trust=0.8,
            latency=1.0,
            cost=2.0,      # MAXIMUM cost optimization
            health=0.9,
            availability=1.2,
        ),
        providers=[
            RouteProvider(
                provider_id="openrouter-free",
                model_family="mixed",
                provider_instance="openrouter",
                priority=10,
                cost_weight=2.0,
                trust_weight=0.8,
            ),
            RouteProvider(
                provider_id="local-fallback",
                model_family="llama3",
                provider_instance="ollama",
                priority=20,
                cost_weight=2.0,
            ),
        ],
    ),
    RouteClass.BENCHMARK_PROBE: RouteClassConfig(
        route_class=RouteClass.BENCHMARK_PROBE,
        description="Benchmarking probe for provider evaluation",
        weights=RouteWeights(
            trust=1.0,
            latency=1.0,
            cost=0.5,      # Cost OK for testing
            health=1.0,
            availability=1.0,
        ),
        providers=[
            RouteProvider(
                provider_id="benchmark-multi",
                model_family="mixed",
                provider_instance="multi",
                priority=10,
            ),
        ],
    ),
}


def get_route_class_config(route_class: RouteClass) -> Optional[RouteClassConfig]:
    """Get configuration for a route class."""
    return DEFAULT_ROUTE_CONFIGS.get(route_class)


def get_route_class_by_name(name: str) -> Optional[RouteClass]:
    """Get RouteClass enum by string name."""
    try:
        return RouteClass(name.lower())
    except ValueError:
        # Try matching by value
        for rc in RouteClass:
            if rc.value == name.lower():
                return rc
    return None