truthound-dashboard 1.3.1__py3-none-any.whl → 1.4.0__py3-none-any.whl

truthound_dashboard/core/notifications/routing/__init__.py

@@ -0,0 +1,169 @@
+"""Advanced routing engine for notification dispatch.
+
+This module provides a flexible, rule-based routing system for directing
+notifications to appropriate channels based on configurable conditions.
+
+Features:
+    - 13 built-in rule types (severity, issue count, time window, expression, jinja2, etc.)
+    - Rule combinators (AllOf, AnyOf, NotRule)
+    - Plugin architecture for custom rules
+    - YAML/JSON configuration support
+    - Priority-based route ordering
+    - Safe Python expression evaluation for complex routing conditions
+    - Jinja2 template-based rules for flexible matching (optional)
+
+Example:
+    from truthound_dashboard.core.notifications.routing import (
+        ActionRouter,
+        Route,
+        RouteContext,
+        SeverityRule,
+        ExpressionRule,
+        AllOf,
+    )
+
+    # Create rules
+    critical_rule = SeverityRule(min_severity="critical")
+    production_rule = TagRule(tags=["production"])
+    combined_rule = AllOf(rules=[critical_rule, production_rule])
+
+    # Python expression-based rule for complex conditions
+    expr_rule = ExpressionRule(
+        expression="severity == 'critical' and pass_rate < 0.8",
+    )
+
+    # Create route
+    route = Route(
+        name="critical_production",
+        rule=combined_rule,
+        actions=["channel-1", "channel-2"],
+        priority=100,
+    )
+
+    # Create router and match
+    router = ActionRouter(routes=[route])
+    context = RouteContext(event=event, metadata={"tags": ["production"]})
+    matched_routes = await router.match(context)
+"""
+
+from .combinators import AllOf, AnyOf, NotRule
+from .config import RouteConfigParser
+from .config_parser import (
+    ConfigBuilder,
+    ConfigParser,
+    RouteConfig,
+    RoutingConfig,
+    parse_routing_config,
+)
+from .engine import ActionRouter, Route, RouteContext, RoutingResult
+from .expression_engine import (
+    ExpressionContext,
+    ExpressionError,
+    ExpressionRule,
+    ExpressionSecurityError,
+    ExpressionTimeout,
+    SafeExpressionEvaluator,
+)
+from .rules import (
+    AlwaysRule,
+    BaseRule,
+    DataAssetRule,
+    ErrorRule,
+    IssueCountRule,
+    MetadataRule,
+    NeverRule,
+    PassRateRule,
+    RuleRegistry,
+    SeverityRule,
+    StatusRule,
+    TagRule,
+    TimeWindowRule,
+)
+from .validator import (
+    RuleValidationConfig,
+    RuleValidationError,
+    RuleValidationResult,
+    RuleValidator,
+    ValidationError,
+    ValidationErrorType,
+    ValidationWarning,
+    validate_rule_config,
+)
+
+# Jinja2 support (optional dependency)
+try:
+    from .jinja2_engine import (
+        JINJA2_AVAILABLE,
+        Jinja2Evaluator,
+        Jinja2Rule,
+        Jinja2SecurityError,
+        Jinja2TemplateError,
+        Jinja2TimeoutError,
+        TemplateNotificationFormatter,
+    )
+except ImportError:
+    JINJA2_AVAILABLE = False
+    Jinja2Evaluator = None  # type: ignore
+    Jinja2Rule = None  # type: ignore
+    Jinja2TemplateError = None  # type: ignore
+    Jinja2TimeoutError = None  # type: ignore
+    Jinja2SecurityError = None  # type: ignore
+    TemplateNotificationFormatter = None  # type: ignore
+
+__all__ = [
+    # Base
+    "BaseRule",
+    "RuleRegistry",
+    # Rules
+    "SeverityRule",
+    "IssueCountRule",
+    "PassRateRule",
+    "TimeWindowRule",
+    "TagRule",
+    "DataAssetRule",
+    "MetadataRule",
+    "StatusRule",
+    "ErrorRule",
+    "AlwaysRule",
+    "NeverRule",
+    "ExpressionRule",
+    # Expression Engine
+    "ExpressionContext",
+    "ExpressionError",
+    "ExpressionTimeout",
+    "ExpressionSecurityError",
+    "SafeExpressionEvaluator",
+    # Combinators
+    "AllOf",
+    "AnyOf",
+    "NotRule",
+    # Engine
+    "ActionRouter",
+    "Route",
+    "RouteContext",
+    "RoutingResult",
+    # Config
+    "RouteConfigParser",
+    "ConfigParser",
+    "ConfigBuilder",
+    "RouteConfig",
+    "RoutingConfig",
+    "parse_routing_config",
+    # Validator
+    "RuleValidator",
+    "RuleValidationConfig",
+    "RuleValidationResult",
+    "RuleValidationError",
+    "ValidationError",
+    "ValidationErrorType",
+    "ValidationWarning",
+    "validate_rule_config",
+    # Jinja2 (optional)
+    "JINJA2_AVAILABLE",
+    "Jinja2Evaluator",
+    "Jinja2Rule",
+    "Jinja2TemplateError",
+    "Jinja2TimeoutError",
+    "Jinja2SecurityError",
+    "TemplateNotificationFormatter",
+]

truthound_dashboard/core/notifications/routing/combinators.py

@@ -0,0 +1,184 @@
+"""Rule combinators for complex routing logic.
+
+This module provides combinators that compose multiple rules
+into complex conditions:
+
+- AllOf: All rules must match (AND logic)
+- AnyOf: Any rule must match (OR logic)
+- NotRule: Negates a rule
+
+Example:
+    # Critical severity AND production tag
+    rule = AllOf(rules=[
+        SeverityRule(min_severity="critical"),
+        TagRule(tags=["production"]),
+    ])
+
+    # Critical OR high issue count
+    rule = AnyOf(rules=[
+        SeverityRule(min_severity="critical"),
+        IssueCountRule(min_count=10),
+    ])
+
+    # NOT during business hours
+    rule = NotRule(rule=TimeWindowRule(start_hour=9, end_hour=17))
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from .rules import BaseRule, RuleRegistry
+
+if TYPE_CHECKING:
+    from .engine import RouteContext
+
+
+@RuleRegistry.register("all_of")
+@dataclass
+class AllOf(BaseRule):
+    """Combinator that requires all child rules to match.
+
+    Implements AND logic: the combinator matches only if
+    every child rule matches.
+
+    Attributes:
+        rules: List of rules that must all match.
+    """
+
+    rules: list[BaseRule] = field(default_factory=list)
+
+    @classmethod
+    def get_param_schema(cls) -> dict[str, Any]:
+        return {
+            "rules": {
+                "type": "array",
+                "required": True,
+                "description": "Rules that must all match",
+                "items": {"type": "object"},
+            }
+        }
+
+    async def matches(self, context: "RouteContext") -> bool:
+        """Check if all child rules match."""
+        if not self.rules:
+            return True
+
+        for rule in self.rules:
+            if not await rule.matches(context):
+                return False
+        return True
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": self.rule_type,
+            "rules": [rule.to_dict() for rule in self.rules],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "AllOf":
+        """Create AllOf from dictionary."""
+        rules_data = data.get("rules", [])
+        rules = []
+        for rule_data in rules_data:
+            rule = BaseRule.from_dict(rule_data)
+            if rule:
+                rules.append(rule)
+        return cls(rules=rules)
+
+
+@RuleRegistry.register("any_of")
+@dataclass
+class AnyOf(BaseRule):
+    """Combinator that requires any child rule to match.
+
+    Implements OR logic: the combinator matches if
+    at least one child rule matches.
+
+    Attributes:
+        rules: List of rules where at least one must match.
+    """
+
+    rules: list[BaseRule] = field(default_factory=list)
+
+    @classmethod
+    def get_param_schema(cls) -> dict[str, Any]:
+        return {
+            "rules": {
+                "type": "array",
+                "required": True,
+                "description": "Rules where at least one must match",
+                "items": {"type": "object"},
+            }
+        }
+
+    async def matches(self, context: "RouteContext") -> bool:
+        """Check if any child rule matches."""
+        if not self.rules:
+            return False
+
+        for rule in self.rules:
+            if await rule.matches(context):
+                return True
+        return False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": self.rule_type,
+            "rules": [rule.to_dict() for rule in self.rules],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "AnyOf":
+        """Create AnyOf from dictionary."""
+        rules_data = data.get("rules", [])
+        rules = []
+        for rule_data in rules_data:
+            rule = BaseRule.from_dict(rule_data)
+            if rule:
+                rules.append(rule)
+        return cls(rules=rules)
+
+
+@RuleRegistry.register("not")
+@dataclass
+class NotRule(BaseRule):
+    """Combinator that negates a rule.
+
+    Matches when the child rule does NOT match.
+
+    Attributes:
+        rule: The rule to negate.
+    """
+
+    rule: BaseRule | None = None
+
+    @classmethod
+    def get_param_schema(cls) -> dict[str, Any]:
+        return {
+            "rule": {
+                "type": "object",
+                "required": True,
+                "description": "Rule to negate",
+            }
+        }
+
+    async def matches(self, context: "RouteContext") -> bool:
+        """Check if child rule does NOT match."""
+        if self.rule is None:
+            return False
+        return not await self.rule.matches(context)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": self.rule_type,
+            "rule": self.rule.to_dict() if self.rule else None,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "NotRule":
+        """Create NotRule from dictionary."""
+        rule_data = data.get("rule")
+        rule = BaseRule.from_dict(rule_data) if rule_data else None
+        return cls(rule=rule)