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

pylitmus/rete/nodes.py

@@ -0,0 +1,318 @@
+"""
+RETE Network Node Implementations.
+
+This module contains the core node types for the RETE network:
+- AlphaNode: Tests single conditions
+- AlphaMemory: Stores facts that pass alpha tests
+- BetaNode: Joins results from multiple conditions (AND logic)
+- OrNode: Handles OR logic by tracking any matching branch
+- TerminalNode: Represents rule activation points
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Set
+
+from ..evaluators import EvaluatorFactory
+
+
+@dataclass
+class ConditionKey:
+    """
+    Unique key for identifying conditions for sharing.
+
+    Two conditions with the same key can share an alpha node.
+    """
+
+    field: str
+    operator: str
+    value: Any
+
+    def __hash__(self) -> int:
+        # Handle unhashable values (like lists)
+        value_hash = (
+            hash(tuple(self.value))
+            if isinstance(self.value, list)
+            else hash(self.value)
+        )
+        return hash((self.field, self.operator, value_hash))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ConditionKey):
+            return False
+        return (
+            self.field == other.field
+            and self.operator == other.operator
+            and self.value == other.value
+        )
+
+
+class AlphaNode:
+    """
+    Tests a single condition against incoming facts.
+
+    Alpha nodes form the first layer of the RETE network and perform
+    intra-element tests (tests on a single fact/data item).
+    """
+
+    def __init__(
+        self,
+        field: str,
+        operator: str,
+        value: Any,
+        condition_key: Optional[ConditionKey] = None,
+    ):
+        """
+        Initialize an alpha node.
+
+        Args:
+            field: The field path to test (supports nested paths like "user.age")
+            operator: The comparison operator (equals, greater_than, etc.)
+            value: The value to compare against
+            condition_key: Optional key for condition sharing
+        """
+        self.field = field
+        self.operator = operator
+        self.value = value
+        self.condition_key = condition_key or ConditionKey(field, operator, value)
+
+        # Get the evaluator for this operator
+        self._evaluator = EvaluatorFactory.get(operator)
+
+        # Memory of facts that passed this condition
+        self.memory: List[Dict[str, Any]] = []
+
+        # Child nodes to notify when a fact passes
+        self.children: List["BetaNode"] = []
+
+        # Track the last evaluation result for the current fact
+        self._last_result: Optional[bool] = None
+
+    def evaluate(self, data: Dict[str, Any]) -> bool:
+        """
+        Test if data passes this condition.
+
+        Args:
+            data: The fact/data to test
+
+        Returns:
+            True if the condition passes, False otherwise
+        """
+        field_value = self._get_nested_value(data, self.field)
+        result = self._evaluator.evaluate(field_value, self.value)
+        self._last_result = result
+        return result
+
+    def activate(self, data: Dict[str, Any]) -> bool:
+        """
+        Activate this node with a fact.
+
+        If the fact passes the condition, it's stored in memory and
+        child nodes are notified.
+
+        Args:
+            data: The fact/data to process
+
+        Returns:
+            True if the fact passed the condition
+        """
+        if self.evaluate(data):
+            self.memory.append(data)
+            # Notify children
+            for child in self.children:
+                child.alpha_activation(self, data)
+            return True
+        return False
+
+    def clear_memory(self) -> None:
+        """Clear the alpha memory."""
+        self.memory.clear()
+        self._last_result = None
+
+    def _get_nested_value(self, data: Dict[str, Any], field_path: str) -> Any:
+        """
+        Get a value from nested data using dot notation.
+
+        Args:
+            data: The data dictionary
+            field_path: Path like "user.address.city"
+
+        Returns:
+            The value at the path, or None if not found
+        """
+        keys = field_path.split(".")
+        value = data
+
+        for key in keys:
+            if isinstance(value, dict):
+                value = value.get(key)
+            else:
+                return None
+
+            if value is None:
+                return None
+
+        return value
+
+    def __repr__(self) -> str:
+        return f"AlphaNode({self.field} {self.operator} {self.value})"
+
+
+class BetaNode:
+    """
+    Joins results from multiple alpha nodes (AND logic).
+
+    Beta nodes form the second layer of the RETE network and perform
+    inter-element tests (combining results from multiple conditions).
+    """
+
+    def __init__(self, required_alphas: List[AlphaNode]):
+        """
+        Initialize a beta node.
+
+        Args:
+            required_alphas: List of alpha nodes that must all pass
+        """
+        self.required_alphas = required_alphas
+        self.alpha_set = set(id(a) for a in required_alphas)
+
+        # Track which alphas have been satisfied for current evaluation
+        self._satisfied: Set[int] = set()
+
+        # Memory of complete matches
+        self.memory: List[Dict[str, Any]] = []
+
+        # Child nodes (terminal nodes or other beta nodes)
+        self.children: List["TerminalNode"] = []
+
+    def alpha_activation(self, alpha: AlphaNode, data: Dict[str, Any]) -> None:
+        """
+        Called when an alpha node passes.
+
+        Args:
+            alpha: The alpha node that passed
+            data: The fact that passed the alpha test
+        """
+        self._satisfied.add(id(alpha))
+
+    def is_satisfied(self) -> bool:
+        """Check if all required alpha conditions are satisfied."""
+        return self._satisfied == self.alpha_set
+
+    def activate(self, data: Dict[str, Any]) -> bool:
+        """
+        Check if this beta node is fully satisfied and activate children.
+
+        Args:
+            data: The fact being evaluated
+
+        Returns:
+            True if all conditions are satisfied
+        """
+        if self.is_satisfied():
+            self.memory.append(data)
+            for child in self.children:
+                child.activate(data)
+            return True
+        return False
+
+    def clear(self) -> None:
+        """Clear state for new evaluation."""
+        self._satisfied.clear()
+        self.memory.clear()
+
+    def __repr__(self) -> str:
+        return f"BetaNode(requires={len(self.required_alphas)} alphas)"
+
+
+class OrNode:
+    """
+    Handles OR logic by tracking if any branch matches.
+
+    Unlike BetaNode (AND), OrNode passes if ANY of its child conditions pass.
+    """
+
+    def __init__(self, branches: List[List[AlphaNode]]):
+        """
+        Initialize an OR node.
+
+        Args:
+            branches: List of condition branches, where each branch is
+                     a list of alpha nodes that must all pass (AND within branch)
+        """
+        self.branches = branches
+
+        # Track which branches have been satisfied
+        self._satisfied_branches: Set[int] = set()
+
+        # Child nodes
+        self.children: List["TerminalNode"] = []
+
+    def branch_satisfied(self, branch_index: int) -> None:
+        """Mark a branch as satisfied."""
+        self._satisfied_branches.add(branch_index)
+
+    def is_satisfied(self) -> bool:
+        """Check if any branch is satisfied."""
+        return len(self._satisfied_branches) > 0
+
+    def activate(self, data: Dict[str, Any]) -> bool:
+        """
+        Check if any branch is satisfied and activate children.
+
+        Args:
+            data: The fact being evaluated
+
+        Returns:
+            True if any branch is satisfied
+        """
+        if self.is_satisfied():
+            for child in self.children:
+                child.activate(data)
+            return True
+        return False
+
+    def clear(self) -> None:
+        """Clear state for new evaluation."""
+        self._satisfied_branches.clear()
+
+    def __repr__(self) -> str:
+        return f"OrNode(branches={len(self.branches)})"
+
+
+@dataclass
+class TerminalNode:
+    """
+    Represents a rule activation point.
+
+    When a terminal node is activated, it means all conditions for the
+    associated rule have been satisfied.
+    """
+
+    rule_code: str
+    rule_name: str
+    score: int
+    severity: str
+    category: str
+    description: str
+
+    # Track activation state
+    activated: bool = False
+    activation_data: Optional[Dict[str, Any]] = None
+
+    def activate(self, data: Dict[str, Any]) -> None:
+        """
+        Activate this terminal node (rule triggered).
+
+        Args:
+            data: The fact that triggered the rule
+        """
+        self.activated = True
+        self.activation_data = data
+
+    def clear(self) -> None:
+        """Clear activation state."""
+        self.activated = False
+        self.activation_data = None
+
+    def __repr__(self) -> str:
+        return f"TerminalNode({self.rule_code}, activated={self.activated})"

pylitmus/types.py

@@ -3,13 +3,14 @@ Core type definitions for the CMAP Rules Engine.
 """
 
 from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional
-from enum import Enum
 from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
 
 
 class Operator(str, Enum):
     """Supported condition operators."""
+
     EQUALS = "equals"
     NOT_EQUALS = "not_equals"
     GREATER_THAN = "greater_than"
@@ -32,6 +33,7 @@ class Operator(str, Enum):
 
 class Severity(str, Enum):
     """Rule severity levels."""
+
     LOW = "LOW"
     MEDIUM = "MEDIUM"
     HIGH = "HIGH"
@@ -41,6 +43,7 @@ class Severity(str, Enum):
 @dataclass
 class Rule:
     """A rule definition."""
+
     code: str
     name: str
     description: str
@@ -73,6 +76,7 @@ class Rule:
 @dataclass
 class RuleResult:
     """Result of evaluating a single rule."""
+
     rule_code: str
     rule_name: str
     triggered: bool
@@ -82,11 +86,33 @@ class RuleResult:
     explanation: str
 
 
+@dataclass
+class DecisionTier:
+    """
+    A decision tier definition with score range.
+
+    Example:
+        DecisionTier(name="APPROVE", min_score=0, max_score=30)
+        DecisionTier(name="REVIEW", min_score=30, max_score=70)
+        DecisionTier(name="FLAG", min_score=70, max_score=100)
+    """
+
+    name: str
+    min_score: int
+    max_score: int
+    description: Optional[str] = None
+
+    def matches(self, score: int) -> bool:
+        """Check if score falls within this tier's range (min inclusive, max exclusive)."""
+        return self.min_score <= score < self.max_score
+
+
 @dataclass
 class AssessmentResult:
     """Complete assessment result."""
+
     total_score: int
-    decision: str
+    decision: Optional[str]
     triggered_rules: List[RuleResult] = field(default_factory=list)
     all_rules_evaluated: int = 0
     processing_time_ms: float = 0.0

{pylitmus-1.0.0.dist-info → pylitmus-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pylitmus
-Version: 1.0.0
+Version: 1.2.0
 Summary: A high-performance rules engine for Python - evaluate data against configurable rules and get clear verdicts
 Project-URL: Homepage, https://github.com/yourorg/pylitmus
 Project-URL: Documentation, https://pylitmus.readthedocs.io/

{pylitmus-1.0.0.dist-info → pylitmus-1.2.0.dist-info}/RECORD

@@ -1,8 +1,8 @@
-pylitmus/__init__.py,sha256=MivCPQfBek8sZneeSOBIoYA575Se4pUlunP9uBvS_s0,1843
-pylitmus/engine.py,sha256=j-5w4AhH3FVaUnvTnJQLGREWfV8fFjaGifTOIkDI2YE,7371
+pylitmus/__init__.py,sha256=JFhGwboRoytGdSWpRMLnC21aQoB-gfu5ahEh7Fd7FDA,1877
+pylitmus/engine.py,sha256=TTS4eumtMdljsXFhrTvGuG3qql-ChrQPgzRawgvvcZg,13932
 pylitmus/exceptions.py,sha256=c5AcD1LXAH52NDWTVp3xHp4vXaHwQW75n6JuaJ4D0Dk,653
-pylitmus/factory.py,sha256=BrhFtm0iuMg7uFlaNb5QnFTwPGkyozeVRNnEAhDWqjw,5143
-pylitmus/types.py,sha256=bqU4dsBfzlcBnbiLjD90zQ8LW9nJZqdj9VDcZYcYvI8,2274
+pylitmus/factory.py,sha256=k-HrZhKIkWXfPzyW0cCI1ZKr-Z_7aYC_S4wocvE-SgI,6211
+pylitmus/types.py,sha256=d0BgF5K7EpGSvpeH8B5sveqqDIPKhyZ1DYrt5gTGnf0,2875
 pylitmus/conditions/__init__.py,sha256=jGfOpD4cLBk2lpbnfPyNtPFbUAs0lkMO9AJ5FO4rHgc,303
 pylitmus/conditions/base.py,sha256=OaNyyf4eCy2kUYE2xEw4b2XdTzeHlF3r0XB18CSEshg,1261
 pylitmus/conditions/builder.py,sha256=kymvWoMNH_ss1B1u7hs49InNjW8WWS8kyp5-rCdVk_c,2924
@@ -13,7 +13,7 @@ pylitmus/evaluators/base.py,sha256=POX8EyPTPYyEvZgBIuVWNqvS0AYR-m3X6uQXirHXWCQ,6
 pylitmus/evaluators/factory.py,sha256=_lMB9dWBu9qBS3tF_Xli5hBkeaLhzF0dZszJaYJdq00,11593
 pylitmus/integrations/__init__.py,sha256=DFmjG3bvDpHuhXA3nMXyeu9UXObylxjqYa-5DXgWJW4,58
 pylitmus/integrations/flask/__init__.py,sha256=Blahqk76BmYGgaFfuw8ZX-V4-uIay-nDni5gVgOeBtg,161
-pylitmus/integrations/flask/extension.py,sha256=KZyEZCPCeC4qdwAC0YQH7BeqmkV1FTpK5mwkgX_yiPM,6564
+pylitmus/integrations/flask/extension.py,sha256=Uq41kE0OB_SaoBNi5QZvUTnjXSna_1EbAsXPJOOKNCc,7853
 pylitmus/patterns/__init__.py,sha256=3jjbMmo4BDLIE9IYPKApgahgxjUHOgqlaE7I9s7KLHA,458
 pylitmus/patterns/base.py,sha256=7AyyZvYtpLOGNt54A2XVjTdgsRoyAM2vQUDBifZIzm0,549
 pylitmus/patterns/engine.py,sha256=I_52LseNZjwPDpZc0jVuq3sw1tjiEd2YPt-noqpWe7A,2264
@@ -22,6 +22,10 @@ pylitmus/patterns/fuzzy.py,sha256=EVNHgWVifb3KAnUlwair4gZcOwtbjv7W_6tZzCQXkFU,18
 pylitmus/patterns/glob.py,sha256=y7w4cI6X0dACivWoZKSIyRcOMWfrE4YtAPV_PtSELQA,928
 pylitmus/patterns/range.py,sha256=ARhPipHn7hyLG7LaPVp4vqz_7oNgrBiwPlEUxFCvjxk,1441
 pylitmus/patterns/regex.py,sha256=RaElvD0bsmLN3IknVz6NzfCDmDFyQI6dPmvpL-j93X0,1360
+pylitmus/rete/__init__.py,sha256=d0YU7fF_SdOfMoTplwGrYRF4eCbyEav0N8d2aqKRYOo,809
+pylitmus/rete/compiler.py,sha256=nLMee3oDJ-34JHvMZtnfHnimjDmA8oMzsmqhhXdG9s8,11231
+pylitmus/rete/network.py,sha256=kZt-NW5GqGul9f42S5sG_qRJDpoQPOQ2vd81PxNM7tI,8105
+pylitmus/rete/nodes.py,sha256=3Z1p0yvaOW231CdVviN_ysrwnpoNFFj0sJr-UMv4jBQ,8993
 pylitmus/storage/__init__.py,sha256=-H455-ISCkaFltpPIoqFuJTPc2bMDYN9o-mBnnRbEi0,410
 pylitmus/storage/base.py,sha256=SuaT--Ao90R4nxQc8_f63Xp9TzvQ70wYFBEK_1DUPiQ,1620
 pylitmus/storage/cached.py,sha256=o3a_Fq6DqfzJ-61GE3G2KNcNJrxaweddWRWLvpI24eI,5465
@@ -33,7 +37,7 @@ pylitmus/strategies/base.py,sha256=Fq9JgUVdbuPlwEk8pdSyiLZ-RBRm_3DnJkWAWCtGmRk,5
 pylitmus/strategies/max.py,sha256=BUjZ9P3DUrDShcvy7_0pVo3Pa9lSLJI5cX9bRELUAlU,553
 pylitmus/strategies/sum.py,sha256=kA0MHiYSpLa-lYR0nMmTGGKMMKm58jrqkuC9a5sTy0U,831
 pylitmus/strategies/weighted.py,sha256=GqTt8yqS3m2GYgX9nElhjk7p8ah6lAFrtpZiCDHTSQg,1019
-pylitmus-1.0.0.dist-info/METADATA,sha256=el-ecW2t9Lqg9vMFppw7xD5m7guNpULSW6PAKj2axP0,11220
-pylitmus-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-pylitmus-1.0.0.dist-info/licenses/LICENSE,sha256=BtvJ2KboQyfSvjSh9-nxRiVFK4VjxFWXe5x4sFpe7Xw,1066
-pylitmus-1.0.0.dist-info/RECORD,,
+pylitmus-1.2.0.dist-info/METADATA,sha256=uPfL-CWlizBXtkWUz56Kz4TGn5hqnJ_Q-1s73ZZFmII,11220
+pylitmus-1.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pylitmus-1.2.0.dist-info/licenses/LICENSE,sha256=BtvJ2KboQyfSvjSh9-nxRiVFK4VjxFWXe5x4sFpe7Xw,1066
+pylitmus-1.2.0.dist-info/RECORD,,