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

pylitmus/__init__.py

@@ -26,9 +26,9 @@ from .storage import (
     RuleRepository,
 )
 from .strategies import MaxStrategy, ScoringStrategy, SumStrategy, WeightedStrategy
-from .types import AssessmentResult, Operator, Rule, RuleResult, Severity
+from .types import AssessmentResult, DecisionTier, Operator, Rule, RuleResult, Severity
 
-__version__ = "1.0.0"
+__version__ = "1.2.0"
 
 __all__ = [
     # Main
@@ -40,6 +40,7 @@ __all__ = [
     "Rule",
     "RuleResult",
     "AssessmentResult",
+    "DecisionTier",
     "Operator",
     "Severity",
     # Conditions

pylitmus/engine.py

@@ -7,9 +7,10 @@ import time
 from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 from .exceptions import EvaluationError
-from .types import AssessmentResult, Rule, RuleResult
+from .types import AssessmentResult, DecisionTier, Rule, RuleResult
 
 if TYPE_CHECKING:
+    from .rete import RETENetwork, RuleCompiler
     from .storage.base import RuleRepository
     from .strategies.base import ScoringStrategy
 
@@ -21,25 +22,43 @@ class RuleEngine:
     Main rules engine for evaluating data against configured rules.
 
     Usage:
+        # Without decision tiers (returns None for decision)
         engine = RuleEngine(
             repository=DatabaseRuleRepository(db_url),
             scoring_strategy=WeightedStrategy()
         )
 
+        # With user-defined decision tiers
+        engine = RuleEngine(
+            repository=DatabaseRuleRepository(db_url),
+            scoring_strategy=WeightedStrategy(),
+            decision_tiers=[
+                DecisionTier("AUTO_APPROVE", 0, 20, "Very low risk"),
+                DecisionTier("APPROVE", 20, 40, "Low risk"),
+                DecisionTier("SOFT_REVIEW", 40, 60, "Medium risk"),
+                DecisionTier("HARD_REVIEW", 60, 80, "Higher risk"),
+                DecisionTier("FLAG", 80, 95, "High risk"),
+                DecisionTier("AUTO_REJECT", 95, 101, "Very high risk"),
+            ]
+        )
+
+        # With RETE algorithm for optimized evaluation (recommended for 50+ rules)
+        engine = RuleEngine(
+            repository=repo,
+            scoring_strategy=WeightedStrategy(),
+            use_rete=True  # Enable RETE optimization
+        )
+
         result = engine.evaluate(claim, context)
     """
 
-    DEFAULT_THRESHOLDS = {
-        "approve": 30,
-        "review": 70,
-    }
-
     def __init__(
         self,
         repository: "RuleRepository",
         scoring_strategy: Optional["ScoringStrategy"] = None,
-        decision_thresholds: Optional[Dict[str, int]] = None,
+        decision_tiers: Optional[List[DecisionTier]] = None,
         condition_builder: Optional[Any] = None,
+        use_rete: bool = False,
     ):
         """
         Initialize the rule engine.
@@ -47,16 +66,39 @@ class RuleEngine:
         Args:
             repository: Rule storage backend
             scoring_strategy: Strategy for calculating scores
-            decision_thresholds: Custom thresholds for decisions
+            decision_tiers: User-defined decision tiers with score ranges.
+                           If not provided, decision will be None.
             condition_builder: Builder for creating conditions from dicts
+            use_rete: Enable RETE algorithm for optimized rule evaluation.
+                     Recommended for rule sets with 50+ rules or significant
+                     condition sharing. Default is False (use standard evaluation).
         """
         self.repository = repository
         self._scoring_strategy = scoring_strategy
-        self._thresholds = decision_thresholds or self.DEFAULT_THRESHOLDS.copy()
+        self._decision_tiers = decision_tiers
         self._condition_builder = condition_builder
         self._rules_cache: Optional[List[Rule]] = None
 
-        logger.info("RuleEngine initialized")
+        # RETE configuration
+        self._use_rete = use_rete
+        self._rete_network: Optional["RETENetwork"] = None
+        self._rete_compiled = False
+
+        logger.info(f"RuleEngine initialized (use_rete={use_rete})")
+
+    @property
+    def use_rete(self) -> bool:
+        """Check if RETE algorithm is enabled."""
+        return self._use_rete
+
+    @use_rete.setter
+    def use_rete(self, value: bool) -> None:
+        """Enable or disable RETE algorithm."""
+        if value != self._use_rete:
+            self._use_rete = value
+            self._rete_network = None
+            self._rete_compiled = False
+            logger.info(f"RETE algorithm {'enabled' if value else 'disabled'}")
 
     @property
     def scoring_strategy(self) -> "ScoringStrategy":
@@ -76,6 +118,30 @@ class RuleEngine:
             self._condition_builder = ConditionBuilder()
         return self._condition_builder
 
+    def _ensure_rete_compiled(self, filters: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Ensure the RETE network is compiled with current rules.
+
+        Args:
+            filters: Filters to apply when fetching rules
+        """
+        if self._rete_compiled and self._rete_network is not None:
+            return
+
+        from .rete import RuleCompiler
+
+        rules = self.repository.get_enabled(filters)
+        compiler = RuleCompiler()
+        self._rete_network = compiler.compile(rules)
+        self._rete_compiled = True
+
+        stats = self._rete_network.get_stats()
+        logger.info(
+            f"RETE network compiled: {stats['alpha_nodes']} alpha nodes, "
+            f"{stats['shared_conditions']} shared conditions, "
+            f"{stats['terminal_nodes']} rules"
+        )
+
     def evaluate(
         self,
         data: Dict[str, Any],
@@ -85,6 +151,104 @@ class RuleEngine:
         """
         Evaluate data against all applicable rules.
 
+        Args:
+            data: Data to evaluate
+            context: Additional context for evaluation
+            filters: Filters to apply when fetching rules
+
+        Returns:
+            AssessmentResult with score, decision, and triggered rules
+        """
+        if self._use_rete:
+            return self._evaluate_with_rete(data, context, filters)
+        else:
+            return self._evaluate_standard(data, context, filters)
+
+    def _evaluate_with_rete(
+        self,
+        data: Dict[str, Any],
+        context: Optional[Dict[str, Any]] = None,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> AssessmentResult:
+        """
+        Evaluate data using the RETE algorithm.
+
+        Args:
+            data: Data to evaluate
+            context: Additional context for evaluation
+            filters: Filters to apply when fetching rules
+
+        Returns:
+            AssessmentResult with score, decision, and triggered rules
+        """
+        start_time = time.time()
+        context = context or {}
+
+        logger.debug(f"Starting RETE evaluation with {len(data)} data fields")
+
+        # Ensure RETE network is compiled
+        self._ensure_rete_compiled(filters)
+
+        try:
+            # Evaluate through RETE network
+            triggered_results = self._rete_network.evaluate(data)
+
+            # Convert severity strings back to Severity enum for consistency
+            from .types import Severity
+
+            for result in triggered_results:
+                if isinstance(result.severity, str):
+                    try:
+                        result.severity = Severity(result.severity)
+                    except ValueError:
+                        pass  # Keep as string if not a valid Severity
+
+        except Exception as e:
+            logger.error(f"Error in RETE evaluation: {e}")
+            raise EvaluationError(f"RETE evaluation failed: {e}") from e
+
+        # Calculate total score using scoring strategy
+        total_score = self.scoring_strategy.calculate(triggered_results)
+
+        # Determine decision
+        decision = self._make_decision(total_score)
+
+        processing_time = (time.time() - start_time) * 1000
+
+        # Get total rules count from network stats
+        stats = self._rete_network.get_stats()
+        total_rules = stats["terminal_nodes"]
+
+        result = AssessmentResult(
+            total_score=total_score,
+            decision=decision,
+            triggered_rules=triggered_results,
+            all_rules_evaluated=total_rules,
+            processing_time_ms=processing_time,
+            metadata={
+                "context": context,
+                "filters": filters,
+                "evaluation_method": "rete",
+                "rete_stats": stats,
+            },
+        )
+
+        logger.info(
+            f"RETE evaluation complete: score={total_score}, decision={decision}, "
+            f"triggered={len(triggered_results)}/{total_rules}, time={processing_time:.2f}ms"
+        )
+
+        return result
+
+    def _evaluate_standard(
+        self,
+        data: Dict[str, Any],
+        context: Optional[Dict[str, Any]] = None,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> AssessmentResult:
+        """
+        Evaluate data using standard (non-RETE) algorithm.
+
         Args:
             data: Data to evaluate
             context: Additional context for evaluation
@@ -96,7 +260,7 @@ class RuleEngine:
         start_time = time.time()
         context = context or {}
 
-        logger.debug(f"Starting evaluation with {len(data)} data fields")
+        logger.debug(f"Starting standard evaluation with {len(data)} data fields")
 
         # Get applicable rules
         rules = self.repository.get_enabled(filters)
@@ -135,11 +299,15 @@ class RuleEngine:
             triggered_rules=triggered_results,
             all_rules_evaluated=len(rules),
             processing_time_ms=processing_time,
-            metadata={"context": context, "filters": filters},
+            metadata={
+                "context": context,
+                "filters": filters,
+                "evaluation_method": "standard",
+            },
         )
 
         logger.info(
-            f"Evaluation complete: score={total_score}, decision={decision}, "
+            f"Standard evaluation complete: score={total_score}, decision={decision}, "
             f"triggered={len(triggered_results)}/{len(rules)}, time={processing_time:.2f}ms"
         )
 
@@ -189,30 +357,34 @@ class RuleEngine:
             explanation=rule.description if triggered else "Condition not met",
         )
 
-    def _make_decision(self, score: int) -> str:
+    def _make_decision(self, score: int) -> Optional[str]:
         """
-        Make a decision based on the total score.
+        Make a decision based on the total score and configured decision tiers.
 
         Args:
             score: Total calculated score
 
         Returns:
-            Decision string: 'APPROVE', 'REVIEW', or 'FLAG'
+            Decision string if a matching tier is found, None otherwise.
+            If no decision tiers are configured, returns None.
         """
-        approve_threshold = self._thresholds.get("approve", 30)
-        review_threshold = self._thresholds.get("review", 70)
+        if not self._decision_tiers:
+            return None
 
-        if score < approve_threshold:
-            return "APPROVE"
-        elif score < review_threshold:
-            return "REVIEW"
-        else:
-            return "FLAG"
+        for tier in self._decision_tiers:
+            if tier.matches(score):
+                return tier.name
+
+        return None
 
     def reload_rules(self) -> None:
         """Force reload rules from repository."""
         self._rules_cache = None
 
+        # Invalidate RETE network to force recompilation
+        self._rete_network = None
+        self._rete_compiled = False
+
         # If repository has cache, invalidate it
         if hasattr(self.repository, "invalidate"):
             self.repository.invalidate()
@@ -242,3 +414,14 @@ class RuleEngine:
             Rule if found, None otherwise
         """
         return self.repository.get_by_code(code)
+
+    def get_rete_stats(self) -> Optional[Dict[str, int]]:
+        """
+        Get RETE network statistics.
+
+        Returns:
+            Dictionary with stats if RETE is enabled and compiled, None otherwise
+        """
+        if self._rete_network is not None:
+            return self._rete_network.get_stats()
+        return None

pylitmus/factory.py

@@ -4,7 +4,7 @@ Factory functions for creating RuleEngine instances with sensible defaults.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict, List, Optional, Union
+from typing import TYPE_CHECKING, List, Optional, Union
 
 from .engine import RuleEngine
 from .storage import (
@@ -15,6 +15,7 @@ from .storage import (
     RuleRepository,
 )
 from .strategies import MaxStrategy, ScoringStrategy, SumStrategy, WeightedStrategy
+from .types import DecisionTier
 
 if TYPE_CHECKING:
     from .types import Rule
@@ -34,7 +35,9 @@ def create_engine(
     # Scoring
     scoring_strategy: Union[str, ScoringStrategy] = "sum",
     # Decision
-    decision_thresholds: Optional[Dict[str, int]] = None,
+    decision_tiers: Optional[List[DecisionTier]] = None,
+    # RETE optimization
+    use_rete: bool = False,
 ) -> RuleEngine:
     """
     Create a configured RuleEngine instance.
@@ -52,13 +55,17 @@ def create_engine(
         cache_url: Redis URL (for 'redis' cache)
         cache_ttl: Cache TTL in seconds
         scoring_strategy: 'sum', 'weighted', 'max', or ScoringStrategy instance
-        decision_thresholds: Custom thresholds {'approve': 30, 'review': 70}
+        decision_tiers: User-defined decision tiers with score ranges.
+                       If not provided, decision will be None in results.
+        use_rete: Enable RETE algorithm for optimized rule evaluation.
+                 Recommended for rule sets with 50+ rules or significant
+                 condition sharing across rules. Default is False.
 
     Returns:
         Configured RuleEngine instance
 
     Examples:
-        # Simple in-memory engine
+        # Simple in-memory engine (no decision tiers - decision will be None)
         engine = create_engine()
 
         # In-memory with predefined rules
@@ -78,10 +85,24 @@ def create_engine(
             rules_file='./rules/fraud_rules.yaml'
         )
 
-        # With weighted scoring
+        # With user-defined decision tiers
         engine = create_engine(
             scoring_strategy='weighted',
-            decision_thresholds={'approve': 25, 'review': 60}
+            decision_tiers=[
+                DecisionTier("AUTO_APPROVE", 0, 20, "Very low risk"),
+                DecisionTier("APPROVE", 20, 40, "Low risk"),
+                DecisionTier("SOFT_REVIEW", 40, 60, "Medium risk"),
+                DecisionTier("HARD_REVIEW", 60, 80, "Higher risk"),
+                DecisionTier("FLAG", 80, 95, "High risk"),
+                DecisionTier("AUTO_REJECT", 95, 101, "Very high risk"),
+            ]
+        )
+
+        # With RETE algorithm optimization (for large rule sets)
+        engine = create_engine(
+            storage_backend='database',
+            database_url='postgresql://localhost/mydb',
+            use_rete=True  # Enable RETE for performance
         )
     """
 
@@ -112,7 +133,8 @@ def create_engine(
     return RuleEngine(
         repository=repo,
         scoring_strategy=strategy,
-        decision_thresholds=decision_thresholds,
+        decision_tiers=decision_tiers,
+        use_rete=use_rete,
     )
 
 

pylitmus/integrations/flask/extension.py

@@ -2,11 +2,12 @@
 Flask extension for cmap-rules-engine.
 """
 
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 from ...engine import RuleEngine
 from ...storage import CachedRuleRepository, InMemoryRuleRepository
 from ...strategies import MaxStrategy, SumStrategy, WeightedStrategy
+from ...types import DecisionTier
 
 try:
     from flask import Flask, current_app
@@ -83,6 +84,47 @@ def create_strategy(config: Dict[str, Any]) -> Any:
     return strategies[strategy_name]()
 
 
+def create_decision_tiers(config: Dict[str, Any]) -> Optional[List[DecisionTier]]:
+    """
+    Create decision tiers from Flask config.
+
+    Supports two formats:
+    1. Legacy dict format: {"approve": 30, "review": 70}
+       - Creates APPROVE (0-30), REVIEW (30-70), FLAG (70-101) tiers
+    2. List format: [DecisionTier(...), ...]
+
+    Args:
+        config: Flask app configuration
+
+    Returns:
+        List of DecisionTier objects or None
+    """
+    thresholds = config.get("CMAP_RULES_THRESHOLDS")
+    decision_tiers = config.get("CMAP_RULES_DECISION_TIERS")
+
+    # If explicit decision tiers are provided, use them
+    if decision_tiers is not None:
+        return decision_tiers
+
+    # Convert legacy thresholds format to decision tiers
+    if thresholds is not None:
+        approve_threshold = thresholds.get("approve", 30)
+        review_threshold = thresholds.get("review", 70)
+
+        return [
+            DecisionTier("APPROVE", 0, approve_threshold),
+            DecisionTier("REVIEW", approve_threshold, review_threshold),
+            DecisionTier("FLAG", review_threshold, 101),
+        ]
+
+    # Default decision tiers
+    return [
+        DecisionTier("APPROVE", 0, 30),
+        DecisionTier("REVIEW", 30, 70),
+        DecisionTier("FLAG", 70, 101),
+    ]
+
+
 class CmapRulesEngine:
     """
     Flask extension for cmap-rules-engine.
@@ -119,7 +161,7 @@ class CmapRulesEngine:
         if not HAS_FLASK:
             raise ImportError(
                 "Flask is required for the Flask integration. "
-                "Install it with: pip install cmap-rules-engine[flask]"
+                "Install it with: pip install pylitmus[flask]"
             )
 
         self._engine: Optional[RuleEngine] = None
@@ -137,7 +179,7 @@ class CmapRulesEngine:
         # Store reference in extensions
         if not hasattr(app, "extensions"):
             app.extensions = {}
-        app.extensions["cmap_rules_engine"] = self
+        app.extensions["pylitmus"] = self
 
         # Set default configuration
         app.config.setdefault("CMAP_RULES_STORAGE", "memory")
@@ -181,13 +223,13 @@ class CmapRulesEngine:
         # Create strategy
         strategy = create_strategy(config)
 
-        # Get thresholds
-        thresholds = config.get("CMAP_RULES_THRESHOLDS")
+        # Create decision tiers from config
+        decision_tiers = create_decision_tiers(config)
 
         return RuleEngine(
             repository=repository,
             scoring_strategy=strategy,
-            decision_thresholds=thresholds,
+            decision_tiers=decision_tiers,
         )
 
     @property
@@ -209,7 +251,7 @@ def get_engine() -> RuleEngine:
     Get rule engine from current Flask app.
 
     Usage:
-        from cmap_rules_engine.integrations.flask import get_engine
+        from pylitmus.integrations.flask import get_engine
 
         @app.route('/assess')
         def assess():
@@ -226,9 +268,9 @@ def get_engine() -> RuleEngine:
     if not HAS_FLASK:
         raise ImportError("Flask is required for the Flask integration")
 
-    if "cmap_rules_engine" not in current_app.extensions:
+    if "pylitmus" not in current_app.extensions:
         raise RuntimeError(
             "CmapRulesEngine not initialized for this app. Did you call init_app()?"
         )
 
-    return current_app.extensions["cmap_rules_engine"].engine
+    return current_app.extensions["pylitmus"].engine

pylitmus/rete/__init__.py

@@ -0,0 +1,26 @@
+"""
+RETE Algorithm Implementation for PyLitmus.
+
+This module provides a lightweight RETE network implementation optimized
+for the PyLitmus rule engine. It maintains the same user-facing API while
+providing performance benefits for large rule sets through:
+
+1. Condition sharing - identical conditions across rules are evaluated once
+2. Alpha network - single-condition tests with memory
+3. Beta network - join nodes for combining conditions (AND/OR logic)
+
+Usage:
+    from pylitmus.rete import RETENetwork, RuleCompiler
+
+    # Compile rules into RETE network
+    compiler = RuleCompiler()
+    network = compiler.compile(rules)
+
+    # Evaluate data
+    triggered_rules = network.evaluate(data)
+"""
+
+from .compiler import RuleCompiler
+from .network import RETENetwork
+
+__all__ = ["RETENetwork", "RuleCompiler"]