pylitmus 1.0.0__tar.gz → 1.2.0__tar.gz

{pylitmus-1.0.0 → pylitmus-1.2.0}/PKG-INFO

@@ -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 → pylitmus-1.2.0}/docs/flask-integration.md

@@ -1,11 +1,11 @@
 # Flask Integration Guide
 
-This guide covers integrating cmap-rules-engine with Flask applications.
+This guide covers integrating pylitmus with Flask applications.
 
 ## Installation
 
 ```bash
-pip install cmap-rules-engine[flask]
+pip install pylitmus[flask]
 ```
 
 ## Basic Setup
@@ -14,7 +14,7 @@ pip install cmap-rules-engine[flask]
 
 ```python
 from flask import Flask
-from cmap_rules_engine.integrations.flask import CmapRulesEngine
+from pylitmus.integrations.flask import CmapRulesEngine
 
 rules_engine = CmapRulesEngine()
 
@@ -35,7 +35,7 @@ def create_app():
 
 ```python
 from flask import Flask
-from cmap_rules_engine.integrations.flask import CmapRulesEngine
+from pylitmus.integrations.flask import CmapRulesEngine
 
 app = Flask(__name__)
 app.config['CMAP_RULES_FILE'] = 'rules.yaml'
@@ -62,7 +62,7 @@ rules_engine = CmapRulesEngine(app)
 
 ```python
 from flask import Flask, request, jsonify
-from cmap_rules_engine.integrations.flask import CmapRulesEngine, get_engine
+from pylitmus.integrations.flask import CmapRulesEngine, get_engine
 
 app = Flask(__name__)
 app.config['CMAP_RULES_FILE'] = 'rules.yaml'
@@ -98,7 +98,7 @@ def evaluate():
 
 ```python
 from flask import Blueprint, request, jsonify
-from cmap_rules_engine.integrations.flask import get_engine
+from pylitmus.integrations.flask import get_engine
 
 api = Blueprint('api', __name__)
 
@@ -201,7 +201,7 @@ rules:
 
 ```python
 from flask import Flask, request, jsonify
-from cmap_rules_engine.integrations.flask import CmapRulesEngine, get_engine
+from pylitmus.integrations.flask import CmapRulesEngine, get_engine
 
 def create_app(config_class='config.Config'):
     app = Flask(__name__)
@@ -326,7 +326,7 @@ curl -X POST http://localhost:5000/evaluate \
 ```python
 from flask import Flask
 from flask_sqlalchemy import SQLAlchemy
-from cmap_rules_engine.integrations.flask import CmapRulesEngine
+from pylitmus.integrations.flask import CmapRulesEngine
 
 app = Flask(__name__)
 app.config['SQLALCHEMY_DATABASE_URI'] = 'postgresql://localhost/mydb'
@@ -341,7 +341,7 @@ rules_engine = CmapRulesEngine(app)
 
 ```python
 from flask import Flask
-from cmap_rules_engine.integrations.flask import CmapRulesEngine
+from pylitmus.integrations.flask import CmapRulesEngine
 
 app = Flask(__name__)
 
@@ -357,8 +357,8 @@ rules_engine = CmapRulesEngine(app)
 
 ```python
 from flask import Flask, jsonify
-from cmap_rules_engine.integrations.flask import CmapRulesEngine, get_engine
-from cmap_rules_engine import RuleEngineError, EvaluationError
+from pylitmus.integrations.flask import CmapRulesEngine, get_engine
+from pylitmus import RuleEngineError, EvaluationError
 
 app = Flask(__name__)
 rules_engine = CmapRulesEngine(app)

{pylitmus-1.0.0 → pylitmus-1.2.0}/docs/quickstart.md

@@ -1,27 +1,27 @@
 # Quick Start Guide
 
-This guide will help you get started with cmap-rules-engine in minutes.
+This guide will help you get started with pylitmus in minutes.
 
 ## Installation
 
 ```bash
-pip install cmap-rules-engine
+pip install pylitmus
 ```
 
 For additional features:
 
 ```bash
 # Database support (PostgreSQL, MySQL, SQLite)
-pip install cmap-rules-engine[database]
+pip install pylitmus[database]
 
 # Redis caching
-pip install cmap-rules-engine[redis]
+pip install pylitmus[redis]
 
 # Flask integration
-pip install cmap-rules-engine[flask]
+pip install pylitmus[flask]
 
 # All extras
-pip install cmap-rules-engine[all]
+pip install pylitmus[all]
 ```
 
 ## Basic Usage
@@ -31,7 +31,7 @@ pip install cmap-rules-engine[all]
 The simplest way to create a rules engine:
 
 ```python
-from cmap_rules_engine import create_engine
+from pylitmus import create_engine
 
 # Simple in-memory engine
 engine = create_engine()
@@ -40,7 +40,7 @@ engine = create_engine()
 ### Defining Rules in Python
 
 ```python
-from cmap_rules_engine import create_engine, Rule, Severity
+from pylitmus import create_engine, Rule, Severity
 
 rules = [
     Rule(

{pylitmus-1.0.0 → pylitmus-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pylitmus"
-version = "1.0.0"
+version = "1.2.0"
 description = "A high-performance rules engine for Python - evaluate data against configurable rules and get clear verdicts"
 readme = "README.md"
 license = {text = "MIT"}

{pylitmus-1.0.0 → pylitmus-1.2.0}/src/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-1.2.0/src/pylitmus/engine.py

@@ -0,0 +1,427 @@
+"""
+Main RuleEngine class for evaluating data against configured rules.
+"""
+
+import logging
+import time
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from .exceptions import EvaluationError
+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
+
+logger = logging.getLogger(__name__)
+
+
+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)
+    """
+
+    def __init__(
+        self,
+        repository: "RuleRepository",
+        scoring_strategy: Optional["ScoringStrategy"] = None,
+        decision_tiers: Optional[List[DecisionTier]] = None,
+        condition_builder: Optional[Any] = None,
+        use_rete: bool = False,
+    ):
+        """
+        Initialize the rule engine.
+
+        Args:
+            repository: Rule storage backend
+            scoring_strategy: Strategy for calculating scores
+            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._decision_tiers = decision_tiers
+        self._condition_builder = condition_builder
+        self._rules_cache: Optional[List[Rule]] = None
+
+        # 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":
+        """Get the scoring strategy, creating default if needed."""
+        if self._scoring_strategy is None:
+            from .strategies import SumStrategy
+
+            self._scoring_strategy = SumStrategy()
+        return self._scoring_strategy
+
+    @property
+    def condition_builder(self) -> Any:
+        """Get the condition builder, creating default if needed."""
+        if self._condition_builder is None:
+            from .conditions import ConditionBuilder
+
+            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],
+        context: Optional[Dict[str, Any]] = None,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> AssessmentResult:
+        """
+        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
+            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 standard evaluation with {len(data)} data fields")
+
+        # Get applicable rules
+        rules = self.repository.get_enabled(filters)
+
+        triggered_results: List[RuleResult] = []
+        all_results: List[RuleResult] = []
+
+        for rule in rules:
+            try:
+                result = self.evaluate_rule(rule, data, context)
+                all_results.append(result)
+
+                if result.triggered:
+                    triggered_results.append(result)
+                    logger.debug(
+                        f"Rule {rule.code} triggered with score {result.score}"
+                    )
+
+            except Exception as e:
+                logger.error(f"Error evaluating rule {rule.code}: {e}")
+                raise EvaluationError(
+                    f"Failed to evaluate rule {rule.code}: {e}"
+                ) from e
+
+        # Calculate total score
+        total_score = self.scoring_strategy.calculate(triggered_results)
+
+        # Determine decision
+        decision = self._make_decision(total_score)
+
+        processing_time = (time.time() - start_time) * 1000
+
+        result = AssessmentResult(
+            total_score=total_score,
+            decision=decision,
+            triggered_rules=triggered_results,
+            all_rules_evaluated=len(rules),
+            processing_time_ms=processing_time,
+            metadata={
+                "context": context,
+                "filters": filters,
+                "evaluation_method": "standard",
+            },
+        )
+
+        logger.info(
+            f"Standard evaluation complete: score={total_score}, decision={decision}, "
+            f"triggered={len(triggered_results)}/{len(rules)}, time={processing_time:.2f}ms"
+        )
+
+        return result
+
+    def evaluate_rule(
+        self, rule: Rule, data: Dict[str, Any], context: Optional[Dict[str, Any]] = None
+    ) -> RuleResult:
+        """
+        Evaluate a single rule against data.
+
+        Args:
+            rule: Rule to evaluate
+            data: Data to evaluate against
+            context: Additional context
+
+        Returns:
+            RuleResult indicating if rule triggered
+        """
+        context = context or {}
+
+        # Check if rule is effective
+        if not rule.is_effective():
+            return RuleResult(
+                rule_code=rule.code,
+                rule_name=rule.name,
+                triggered=False,
+                score=0,
+                severity=rule.severity,
+                category=rule.category,
+                explanation="Rule is not currently effective",
+            )
+
+        # Build condition from rule definition
+        condition = self.condition_builder.build(rule.conditions)
+
+        # Evaluate condition
+        triggered = condition.evaluate(data)
+
+        return RuleResult(
+            rule_code=rule.code,
+            rule_name=rule.name,
+            triggered=triggered,
+            score=rule.score if triggered else 0,
+            severity=rule.severity,
+            category=rule.category,
+            explanation=rule.description if triggered else "Condition not met",
+        )
+
+    def _make_decision(self, score: int) -> Optional[str]:
+        """
+        Make a decision based on the total score and configured decision tiers.
+
+        Args:
+            score: Total calculated score
+
+        Returns:
+            Decision string if a matching tier is found, None otherwise.
+            If no decision tiers are configured, returns None.
+        """
+        if not self._decision_tiers:
+            return None
+
+        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()
+
+        logger.info("Rules cache invalidated")
+
+    def get_rules(self, filters: Optional[Dict[str, Any]] = None) -> List[Rule]:
+        """
+        Get all rules, optionally filtered.
+
+        Args:
+            filters: Optional filters to apply
+
+        Returns:
+            List of rules
+        """
+        return self.repository.get_all(filters)
+
+    def get_rule(self, code: str) -> Optional[Rule]:
+        """
+        Get a specific rule by code.
+
+        Args:
+            code: Rule code
+
+        Returns:
+            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-1.0.0 → pylitmus-1.2.0}/src/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,
     )