Skip to content

Router Module Architecture

The router module provides a dynamic, resilient, and domain-agnostic execution routing engine. It evaluates contextual criteria to resolve optimal execution paths across multiple target nodes, ensuring high availability through configured fallback chains and predictive scoring.

Core Components

SmartRouterFactory

The primary entry point for the module. It acts as a strategic gatekeeper that resolves dynamic strategies via registries or constructs a LocalFallbackRouter (static implementation) if smart routing is disabled in settings, enforcing the Single Responsibility Principle.

SmartRouterService

The concrete orchestrator implementing SmartRouterProtocol. It delegates route calculation purely to an injected RoutingStrategyProtocol, maintaining a clean separation between the execution context and the routing algorithm.

from nala.athomic.router.factory import SmartRouterFactory

def get_engine(router_settings):
    """
    Initialize the routing engine based on configuration.
    """
    # Factory resolves to SmartRouterService or LocalFallbackRouter
    return SmartRouterFactory.create(settings=router_settings)

Routing Criteria

The module utilizes a decoupled contract for requests. The DefaultRoutingCriteria provides a safe, immutable fallback implementation to prevent initialization errors when no explicit constraints are provided.

from typing import List, Optional, Any, Dict
from nala.athomic.router.criteria import RoutingCriteriaProtocol

class CustomCriteria(RoutingCriteriaProtocol):
    """
    Custom implementation of routing requirements.
    """
    @property
    def tier_name(self) -> Optional[str]:
        return "PREMIUM"

    @property
    def workload_weight(self) -> Optional[float]:
        return 1.0

    @property
    def token_length(self) -> Optional[int]:
        return 4096

    @property
    def required_capabilities(self) -> Optional[List[str]]:
        return ["vision"]

    @property
    def metadata(self) -> Dict[str, Any]:
        return {}

BaseRoutedProxy

The resilience engine that orchestrates RetryHandler, CircuitBreaker, and FallbackLogicHandler. It now features native support for resilient AsyncGenerator operations, intercepting the first chunk to verify node health before yielding.

from nala.athomic.router.proxy import BaseRoutedProxy

class ResilientProxy(BaseRoutedProxy[TClient]):
    """
    Proxy implementation with streaming failover support.
    """
    async def execute_stream(self, criteria, operation):
        """
        Execute a streaming operation with transparent fallback.
        """
        async for chunk in self._stream_with_fallback(criteria, operation):
            yield chunk

Strategies

Strategies are dynamically resolved through the strategy_creator_registry:

  • TierRoutingStrategy: Resolves nodes based on business-tier mappings.
  • CostOptimizationStrategy: Selects paths based on predictive models and max_budget_per_request.
  • CapabilityRoutingStrategy: A decorator strategy that filters chains based on required_capabilities and max_context_window metadata.

Configuration Schema

The router settings allow explicit control over optimization weights and heuristic penalties.

[default.router]
enabled = true
default_strategy = "cost"

[default.router.optimization]
enabled = true
strategy = "balanced"
cost_weight = 0.5
latency_weight = 0.5
max_budget_per_request = 0.01

[[default.router.global_fallback_chain]]
target_id = "primary_provider"
destination_name = "model-v1"
max_retries = 2
timeout_seconds = 10.0
metadata = { capabilities = ["vision"], max_context_window = 32000 }