pylitmus 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

pylitmus/rete/compiler.py

@@ -0,0 +1,356 @@
+"""
+Rule Compiler for RETE Network.
+
+The RuleCompiler transforms PyLitmus Rule definitions into a RETE network
+structure, handling condition extraction, sharing detection, and network
+construction.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from ..types import Rule
+from .network import RETENetwork
+from .nodes import AlphaNode, BetaNode, OrNode, TerminalNode
+
+logger = logging.getLogger(__name__)
+
+
+class RuleCompiler:
+    """
+    Compiles PyLitmus rules into a RETE network.
+
+    The compiler:
+    1. Extracts conditions from rule definitions
+    2. Identifies opportunities for condition sharing
+    3. Builds alpha nodes for simple conditions
+    4. Builds beta nodes for AND combinations
+    5. Builds OR nodes for ANY combinations
+    6. Connects terminal nodes for rule activation
+
+    Usage:
+        compiler = RuleCompiler()
+        network = compiler.compile(rules)
+        results = network.evaluate(data)
+    """
+
+    def __init__(self):
+        """Initialize the compiler."""
+        self._network: Optional[RETENetwork] = None
+
+    def compile(self, rules: List[Rule]) -> RETENetwork:
+        """
+        Compile a list of rules into a RETE network.
+
+        Args:
+            rules: List of PyLitmus Rule objects
+
+        Returns:
+            Compiled RETENetwork ready for evaluation
+        """
+        self._network = RETENetwork()
+
+        for rule in rules:
+            if not rule.is_effective():
+                logger.debug(f"Skipping ineffective rule: {rule.code}")
+                continue
+
+            self._compile_rule(rule)
+
+        logger.info(
+            f"Compiled {len(rules)} rules into RETE network: "
+            f"{self._network.get_stats()}"
+        )
+
+        return self._network
+
+    def _compile_rule(self, rule: Rule) -> None:
+        """
+        Compile a single rule into the network.
+
+        Args:
+            rule: The rule to compile
+        """
+        # Create terminal node for this rule
+        terminal = self._network.create_terminal(rule)
+
+        # Parse and compile the conditions
+        conditions = rule.conditions
+
+        if not conditions:
+            # Rule with no conditions always triggers
+            terminal.activated = True
+            return
+
+        # Compile the condition tree and get the root nodes
+        root_nodes = self._compile_conditions(conditions, terminal)
+
+        logger.debug(
+            f"Compiled rule {rule.code} with {len(root_nodes)} root conditions"
+        )
+
+    def _compile_conditions(
+        self, conditions: Dict[str, Any], terminal: TerminalNode
+    ) -> List[Union[AlphaNode, BetaNode, OrNode]]:
+        """
+        Compile a conditions dictionary into network nodes.
+
+        Handles:
+        - Simple conditions: {"field": "x", "operator": "equals", "value": 1}
+        - AND conditions: {"all": [...]}
+        - OR conditions: {"any": [...]}
+
+        Args:
+            conditions: The conditions dictionary
+            terminal: The terminal node to connect to
+
+        Returns:
+            List of root nodes created
+        """
+        # Check for composite conditions
+        if "all" in conditions:
+            return self._compile_all(conditions["all"], terminal)
+        elif "any" in conditions:
+            return self._compile_any(conditions["any"], terminal)
+        else:
+            # Simple condition
+            return self._compile_simple(conditions, terminal)
+
+    def _compile_simple(
+        self, condition: Dict[str, Any], terminal: TerminalNode
+    ) -> List[AlphaNode]:
+        """
+        Compile a simple condition.
+
+        Args:
+            condition: Simple condition dict with field, operator, value
+            terminal: Terminal node to connect to
+
+        Returns:
+            List containing the alpha node
+        """
+        field = condition.get("field")
+        operator = condition.get("operator")
+        value = condition.get("value")
+
+        if not all([field, operator]):
+            logger.warning(f"Invalid simple condition: {condition}")
+            return []
+
+        # Get or create alpha node (enables sharing)
+        alpha = self._network.get_or_create_alpha(field, operator, value)
+
+        # For a single condition, create a simple beta that just wraps it
+        beta = self._network.create_beta([alpha])
+        beta.children.append(terminal)
+
+        return [alpha]
+
+    def _compile_all(
+        self, conditions: List[Dict[str, Any]], terminal: TerminalNode
+    ) -> List[Union[AlphaNode, BetaNode]]:
+        """
+        Compile an ALL (AND) composite condition.
+
+        All conditions must pass for the rule to trigger.
+
+        Args:
+            conditions: List of condition dictionaries
+            terminal: Terminal node to connect to
+
+        Returns:
+            List of nodes created
+        """
+        all_alphas: List[AlphaNode] = []
+        nested_nodes: List[Union[BetaNode, OrNode]] = []
+
+        for cond in conditions:
+            if "all" in cond:
+                # Nested ALL - flatten it
+                nested = self._compile_all_without_terminal(cond["all"])
+                all_alphas.extend(nested)
+            elif "any" in cond:
+                # Nested ANY - create OR node
+                or_node = self._compile_any_as_or_node(cond["any"])
+                if or_node:
+                    nested_nodes.append(or_node)
+            else:
+                # Simple condition
+                field = cond.get("field")
+                operator = cond.get("operator")
+                value = cond.get("value")
+
+                if field and operator:
+                    alpha = self._network.get_or_create_alpha(field, operator, value)
+                    all_alphas.append(alpha)
+
+        # Create beta node joining all alpha conditions
+        if all_alphas:
+            beta = self._network.create_beta(all_alphas)
+
+            # If there are nested OR nodes, we need special handling
+            if nested_nodes:
+                # Create a combined check that requires both beta AND or_nodes
+                # For now, connect terminal to both
+                beta.children.append(terminal)
+                for node in nested_nodes:
+                    node.children.append(terminal)
+            else:
+                beta.children.append(terminal)
+        elif nested_nodes:
+            # Only OR nodes, no direct alphas
+            for node in nested_nodes:
+                node.children.append(terminal)
+
+        return all_alphas
+
+    def _compile_all_without_terminal(
+        self, conditions: List[Dict[str, Any]]
+    ) -> List[AlphaNode]:
+        """
+        Compile ALL conditions without connecting to a terminal.
+        Used for nested ALL conditions.
+
+        Args:
+            conditions: List of condition dictionaries
+
+        Returns:
+            List of alpha nodes
+        """
+        alphas = []
+
+        for cond in conditions:
+            if "all" in cond:
+                # Recursively flatten
+                alphas.extend(self._compile_all_without_terminal(cond["all"]))
+            elif "any" in cond:
+                # Skip OR in nested ALL for now (complex case)
+                logger.warning("Nested ANY inside ALL not fully supported in RETE")
+            else:
+                field = cond.get("field")
+                operator = cond.get("operator")
+                value = cond.get("value")
+
+                if field and operator:
+                    alpha = self._network.get_or_create_alpha(field, operator, value)
+                    alphas.append(alpha)
+
+        return alphas
+
+    def _compile_any(
+        self, conditions: List[Dict[str, Any]], terminal: TerminalNode
+    ) -> List[Union[AlphaNode, OrNode]]:
+        """
+        Compile an ANY (OR) composite condition.
+
+        Any one condition passing triggers the rule.
+
+        Args:
+            conditions: List of condition dictionaries
+            terminal: Terminal node to connect to
+
+        Returns:
+            List of nodes created
+        """
+        # For OR, each branch independently can trigger the terminal
+        branches: List[List[AlphaNode]] = []
+
+        for cond in conditions:
+            if "all" in cond:
+                # Branch is an AND - collect its alphas
+                branch_alphas = self._compile_all_without_terminal(cond["all"])
+                if branch_alphas:
+                    branches.append(branch_alphas)
+            elif "any" in cond:
+                # Nested OR - flatten by adding each as separate branch
+                for nested_cond in cond["any"]:
+                    nested_alphas = self._extract_alphas_from_condition(nested_cond)
+                    if nested_alphas:
+                        branches.append(nested_alphas)
+            else:
+                # Simple condition is its own branch
+                field = cond.get("field")
+                operator = cond.get("operator")
+                value = cond.get("value")
+
+                if field and operator:
+                    alpha = self._network.get_or_create_alpha(field, operator, value)
+                    branches.append([alpha])
+
+        if branches:
+            # Create OR node
+            or_node = self._network.create_or_node(branches)
+            or_node.children.append(terminal)
+            return [or_node]
+
+        return []
+
+    def _compile_any_as_or_node(
+        self, conditions: List[Dict[str, Any]]
+    ) -> Optional[OrNode]:
+        """
+        Compile ANY conditions into an OR node without terminal.
+
+        Args:
+            conditions: List of condition dictionaries
+
+        Returns:
+            OrNode or None
+        """
+        branches: List[List[AlphaNode]] = []
+
+        for cond in conditions:
+            alphas = self._extract_alphas_from_condition(cond)
+            if alphas:
+                branches.append(alphas)
+
+        if branches:
+            return self._network.create_or_node(branches)
+
+        return None
+
+    def _extract_alphas_from_condition(
+        self, condition: Dict[str, Any]
+    ) -> List[AlphaNode]:
+        """
+        Extract alpha nodes from a condition dict.
+
+        Args:
+            condition: Condition dictionary
+
+        Returns:
+            List of alpha nodes
+        """
+        if "all" in condition:
+            return self._compile_all_without_terminal(condition["all"])
+        elif "any" in condition:
+            # For extraction, just get the first branch
+            # (full OR handling is done elsewhere)
+            alphas = []
+            for cond in condition["any"]:
+                alphas.extend(self._extract_alphas_from_condition(cond))
+            return alphas
+        else:
+            field = condition.get("field")
+            operator = condition.get("operator")
+            value = condition.get("value")
+
+            if field and operator:
+                alpha = self._network.get_or_create_alpha(field, operator, value)
+                return [alpha]
+
+        return []
+
+    def recompile(self, rules: List[Rule]) -> RETENetwork:
+        """
+        Recompile rules into a fresh network.
+
+        Use this when rules have changed.
+
+        Args:
+            rules: Updated list of rules
+
+        Returns:
+            New RETENetwork
+        """
+        return self.compile(rules)

pylitmus/rete/network.py

@@ -0,0 +1,269 @@
+"""
+RETE Network Implementation.
+
+The RETENetwork class is the main entry point for RETE-based rule evaluation.
+It manages the alpha and beta networks and coordinates rule evaluation.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Set
+
+from ..types import Rule, RuleResult
+from .nodes import AlphaNode, BetaNode, ConditionKey, OrNode, TerminalNode
+
+logger = logging.getLogger(__name__)
+
+
+class RETENetwork:
+    """
+    Main RETE network for rule evaluation.
+
+    The network consists of:
+    - Alpha network: Single-condition tests with sharing
+    - Beta network: Join nodes for combining conditions
+    - Terminal nodes: Rule activation points
+
+    Usage:
+        network = RETENetwork()
+        network.add_rule(rule)  # Add rules one by one
+        # Or use RuleCompiler.compile(rules) to build the network
+
+        results = network.evaluate(data)
+    """
+
+    def __init__(self):
+        """Initialize an empty RETE network."""
+        # Alpha nodes indexed by condition key for sharing
+        self._alpha_nodes: Dict[ConditionKey, AlphaNode] = {}
+
+        # All alpha nodes in order of creation
+        self._alpha_list: List[AlphaNode] = []
+
+        # Beta nodes (AND joins)
+        self._beta_nodes: List[BetaNode] = []
+
+        # OR nodes
+        self._or_nodes: List[OrNode] = []
+
+        # Terminal nodes (one per rule)
+        self._terminal_nodes: List[TerminalNode] = []
+
+        # Rule code to terminal node mapping
+        self._rule_terminals: Dict[str, TerminalNode] = {}
+
+        # Track if network has been compiled
+        self._compiled = False
+
+        # Statistics
+        self._stats = {
+            "alpha_nodes": 0,
+            "shared_conditions": 0,
+            "beta_nodes": 0,
+            "or_nodes": 0,
+            "terminal_nodes": 0,
+        }
+
+    def get_or_create_alpha(self, field: str, operator: str, value: Any) -> AlphaNode:
+        """
+        Get an existing alpha node or create a new one.
+
+        This is the key to condition sharing - if an identical condition
+        already exists, we reuse its alpha node.
+
+        Args:
+            field: Field path to test
+            operator: Comparison operator
+            value: Value to compare against
+
+        Returns:
+            Alpha node for this condition
+        """
+        key = ConditionKey(field, operator, value)
+
+        if key in self._alpha_nodes:
+            self._stats["shared_conditions"] += 1
+            logger.debug(f"Reusing alpha node for {field} {operator} {value}")
+            return self._alpha_nodes[key]
+
+        # Create new alpha node
+        alpha = AlphaNode(field, operator, value, key)
+        self._alpha_nodes[key] = alpha
+        self._alpha_list.append(alpha)
+        self._stats["alpha_nodes"] += 1
+
+        logger.debug(f"Created alpha node for {field} {operator} {value}")
+        return alpha
+
+    def create_beta(self, alphas: List[AlphaNode]) -> BetaNode:
+        """
+        Create a beta node joining multiple alpha nodes.
+
+        Args:
+            alphas: List of alpha nodes to join (AND logic)
+
+        Returns:
+            New beta node
+        """
+        beta = BetaNode(alphas)
+
+        # Register beta with its alpha nodes
+        for alpha in alphas:
+            alpha.children.append(beta)
+
+        self._beta_nodes.append(beta)
+        self._stats["beta_nodes"] += 1
+
+        return beta
+
+    def create_or_node(self, branches: List[List[AlphaNode]]) -> OrNode:
+        """
+        Create an OR node with multiple branches.
+
+        Args:
+            branches: List of branches, each branch is a list of alpha nodes
+
+        Returns:
+            New OR node
+        """
+        or_node = OrNode(branches)
+        self._or_nodes.append(or_node)
+        self._stats["or_nodes"] += 1
+        return or_node
+
+    def create_terminal(self, rule: Rule) -> TerminalNode:
+        """
+        Create a terminal node for a rule.
+
+        Args:
+            rule: The rule this terminal represents
+
+        Returns:
+            New terminal node
+        """
+        terminal = TerminalNode(
+            rule_code=rule.code,
+            rule_name=rule.name,
+            score=rule.score,
+            severity=rule.severity.value
+            if hasattr(rule.severity, "value")
+            else str(rule.severity),
+            category=rule.category,
+            description=rule.description,
+        )
+
+        self._terminal_nodes.append(terminal)
+        self._rule_terminals[rule.code] = terminal
+        self._stats["terminal_nodes"] += 1
+
+        return terminal
+
+    def evaluate(self, data: Dict[str, Any]) -> List[RuleResult]:
+        """
+        Evaluate data through the RETE network.
+
+        Args:
+            data: The fact/data to evaluate
+
+        Returns:
+            List of RuleResult for triggered rules
+        """
+        # Clear previous evaluation state
+        self._clear_evaluation_state()
+
+        # Phase 1: Activate alpha network
+        for alpha in self._alpha_list:
+            alpha.activate(data)
+
+        # Phase 2: Check beta nodes (AND conditions)
+        for beta in self._beta_nodes:
+            beta.activate(data)
+
+        # Phase 3: Check OR nodes
+        for or_node in self._or_nodes:
+            # Check each branch
+            for i, branch in enumerate(or_node.branches):
+                # A branch is satisfied if all its alphas passed
+                branch_satisfied = all(alpha._last_result for alpha in branch)
+                if branch_satisfied:
+                    or_node.branch_satisfied(i)
+
+            or_node.activate(data)
+
+        # Phase 4: Collect triggered rules
+        results = []
+        for terminal in self._terminal_nodes:
+            if terminal.activated:
+                results.append(
+                    RuleResult(
+                        rule_code=terminal.rule_code,
+                        rule_name=terminal.rule_name,
+                        triggered=True,
+                        score=terminal.score,
+                        severity=terminal.severity,
+                        category=terminal.category,
+                        explanation=terminal.description,
+                    )
+                )
+
+        return results
+
+    def _clear_evaluation_state(self) -> None:
+        """Clear all evaluation state for a fresh evaluation."""
+        # Clear alpha memories and last results
+        for alpha in self._alpha_list:
+            alpha.clear_memory()
+
+        # Clear beta nodes
+        for beta in self._beta_nodes:
+            beta.clear()
+
+        # Clear OR nodes
+        for or_node in self._or_nodes:
+            or_node.clear()
+
+        # Clear terminal nodes
+        for terminal in self._terminal_nodes:
+            terminal.clear()
+
+    def get_stats(self) -> Dict[str, int]:
+        """Get network statistics."""
+        return self._stats.copy()
+
+    def dump(self) -> str:
+        """
+        Dump network structure for debugging.
+
+        Returns:
+            String representation of the network
+        """
+        lines = ["RETE Network Structure:", "=" * 40]
+
+        lines.append(f"\nAlpha Nodes ({len(self._alpha_list)}):")
+        for alpha in self._alpha_list:
+            shared = "SHARED" if self._stats["shared_conditions"] > 0 else ""
+            lines.append(f"  - {alpha} {shared}")
+
+        lines.append(f"\nBeta Nodes ({len(self._beta_nodes)}):")
+        for beta in self._beta_nodes:
+            lines.append(f"  - {beta}")
+
+        lines.append(f"\nOR Nodes ({len(self._or_nodes)}):")
+        for or_node in self._or_nodes:
+            lines.append(f"  - {or_node}")
+
+        lines.append(f"\nTerminal Nodes ({len(self._terminal_nodes)}):")
+        for terminal in self._terminal_nodes:
+            lines.append(f"  - {terminal}")
+
+        lines.append("\nStatistics:")
+        for key, value in self._stats.items():
+            lines.append(f"  {key}: {value}")
+
+        return "\n".join(lines)
+
+    def __repr__(self) -> str:
+        return (
+            f"RETENetwork(alphas={len(self._alpha_list)}, "
+            f"betas={len(self._beta_nodes)}, "
+            f"terminals={len(self._terminal_nodes)})"
+        )