pylitmus 1.0.0__py3-none-any.whl

pylitmus/__init__.py

@@ -0,0 +1,76 @@
+"""
+pylitmus - A high-performance rules engine for Python.
+
+Evaluate data against configurable rules and get clear verdicts.
+Like a litmus test for your data.
+"""
+
+from .conditions import CompositeCondition, Condition, ConditionBuilder, SimpleCondition
+from .engine import RuleEngine
+from .evaluators import Evaluator, EvaluatorFactory
+from .exceptions import (
+    ConditionError,
+    ConfigurationError,
+    EvaluationError,
+    RuleEngineError,
+    StorageError,
+    UnknownOperatorError,
+)
+from .factory import create_engine, create_repository, create_strategy
+from .patterns import EnhancedPatternEngine, PatternMatcher
+from .storage import (
+    CachedRuleRepository,
+    DatabaseRuleRepository,
+    FileRuleRepository,
+    InMemoryRuleRepository,
+    RuleRepository,
+)
+from .strategies import MaxStrategy, ScoringStrategy, SumStrategy, WeightedStrategy
+from .types import AssessmentResult, Operator, Rule, RuleResult, Severity
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Main
+    "RuleEngine",
+    "create_engine",
+    "create_repository",
+    "create_strategy",
+    # Types
+    "Rule",
+    "RuleResult",
+    "AssessmentResult",
+    "Operator",
+    "Severity",
+    # Conditions
+    "Condition",
+    "SimpleCondition",
+    "CompositeCondition",
+    "ConditionBuilder",
+    # Evaluators
+    "Evaluator",
+    "EvaluatorFactory",
+    # Strategies
+    "ScoringStrategy",
+    "SumStrategy",
+    "WeightedStrategy",
+    "MaxStrategy",
+    # Storage
+    "RuleRepository",
+    "InMemoryRuleRepository",
+    "DatabaseRuleRepository",
+    "FileRuleRepository",
+    "CachedRuleRepository",
+    # Patterns
+    "PatternMatcher",
+    "EnhancedPatternEngine",
+    # Exceptions
+    "RuleEngineError",
+    "UnknownOperatorError",
+    "ConditionError",
+    "StorageError",
+    "ConfigurationError",
+    "EvaluationError",
+    # Version
+    "__version__",
+]

pylitmus/conditions/__init__.py

@@ -0,0 +1,15 @@
+"""
+Conditions module for the CMAP Rules Engine.
+"""
+
+from .base import Condition
+from .builder import ConditionBuilder
+from .composite import CompositeCondition
+from .simple import SimpleCondition
+
+__all__ = [
+    "Condition",
+    "SimpleCondition",
+    "CompositeCondition",
+    "ConditionBuilder",
+]

pylitmus/conditions/base.py

@@ -0,0 +1,53 @@
+"""
+Base condition class for the CMAP Rules Engine.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+
+class Condition(ABC):
+    """Abstract base class for all conditions."""
+
+    @abstractmethod
+    def evaluate(self, data: Dict[str, Any]) -> bool:
+        """
+        Evaluate condition against data.
+
+        Args:
+            data: Data dictionary to evaluate
+
+        Returns:
+            True if condition is met, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Serialize condition to dictionary.
+
+        Returns:
+            Dictionary representation of condition
+        """
+        pass
+
+    def get_nested_value(self, data: Dict[str, Any], field_path: str) -> Any:
+        """
+        Get value from nested dict using dot notation.
+
+        Args:
+            data: Data dictionary
+            field_path: Dot-separated path (e.g., 'provider.type')
+
+        Returns:
+            Value at 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
+        return value

pylitmus/conditions/builder.py

@@ -0,0 +1,92 @@
+"""
+Condition builder for creating conditions from dictionaries.
+"""
+
+from typing import Any, Dict
+
+from .base import Condition
+from .composite import CompositeCondition
+from .simple import SimpleCondition
+
+
+class ConditionBuilder:
+    """Build Condition objects from dictionary definitions."""
+
+    def build(self, definition: Dict[str, Any]) -> Condition:
+        """
+        Build a Condition from a dictionary definition.
+
+        Args:
+            definition: Dictionary defining the condition
+
+        Returns:
+            Condition object
+
+        Examples:
+            # Simple condition
+            builder.build({
+                'field': 'amount',
+                'operator': 'greater_than',
+                'value': 1000
+            })
+
+            # Composite condition (AND)
+            builder.build({
+                'all': [
+                    {'field': 'amount', 'operator': 'greater_than', 'value': 1000},
+                    {'field': 'status', 'operator': 'equals', 'value': 'pending'}
+                ]
+            })
+
+            # Composite condition (OR)
+            builder.build({
+                'any': [
+                    {'field': 'type', 'operator': 'equals', 'value': 'urgent'},
+                    {'field': 'priority', 'operator': 'equals', 'value': 'high'}
+                ]
+            })
+        """
+        if "all" in definition:
+            return self._build_composite("all", definition["all"])
+        elif "any" in definition:
+            return self._build_composite("any", definition["any"])
+        elif "type" in definition and "conditions" in definition:
+            # Support alternative format: {"type": "AND", "conditions": [...]}
+            condition_type = definition["type"].upper()
+            operator = "all" if condition_type == "AND" else "any"
+            return self._build_composite(operator, definition["conditions"])
+        else:
+            return self._build_simple(definition)
+
+    def _build_composite(
+        self, operator: str, conditions_data: list
+    ) -> CompositeCondition:
+        """
+        Build a composite condition.
+
+        Args:
+            operator: 'all' or 'any'
+            conditions_data: List of condition definitions
+
+        Returns:
+            CompositeCondition object
+        """
+        conditions = [self.build(c) for c in conditions_data]
+        return CompositeCondition(operator=operator, conditions=conditions)
+
+    def _build_simple(self, definition: Dict[str, Any]) -> SimpleCondition:
+        """
+        Build a simple condition.
+
+        Args:
+            definition: Dictionary with field, operator, value
+
+        Returns:
+            SimpleCondition object
+        """
+        return SimpleCondition(
+            field=definition["field"],
+            operator=definition["operator"],
+            value=definition.get("value"),
+            case_sensitive=definition.get("case_sensitive", True),
+        )

pylitmus/conditions/composite.py

@@ -0,0 +1,52 @@
+"""
+Composite condition implementation.
+"""
+
+from typing import Any, Dict, List, Literal
+
+from .base import Condition
+
+
+class CompositeCondition(Condition):
+    """A composite condition combining multiple conditions with AND/OR."""
+
+    def __init__(self, operator: Literal["all", "any"], conditions: List[Condition]):
+        """
+        Initialize a composite condition.
+
+        Args:
+            operator: 'all' for AND logic, 'any' for OR logic
+            conditions: List of conditions to combine
+        """
+        self.operator = operator
+        self.conditions = conditions
+
+    def evaluate(self, data: Dict[str, Any]) -> bool:
+        """
+        Evaluate the composite condition against data.
+
+        Args:
+            data: Data dictionary to evaluate
+
+        Returns:
+            True if condition is met based on operator logic
+        """
+        if not self.conditions:
+            return True
+
+        if self.operator == "all":
+            return all(c.evaluate(data) for c in self.conditions)
+        else:  # 'any'
+            return any(c.evaluate(data) for c in self.conditions)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Serialize condition to dictionary.
+
+        Returns:
+            Dictionary representation of condition
+        """
+        return {self.operator: [c.to_dict() for c in self.conditions]}
+
+    def __repr__(self) -> str:
+        return f"CompositeCondition({self.operator}, {len(self.conditions)} conditions)"

pylitmus/conditions/simple.py

@@ -0,0 +1,62 @@
+"""
+Simple condition implementation.
+"""
+
+from typing import Any, Dict
+
+from ..evaluators import EvaluatorFactory
+from .base import Condition
+
+
+class SimpleCondition(Condition):
+    """A simple condition that compares a field to a value."""
+
+    def __init__(
+        self, field: str, operator: str, value: Any, case_sensitive: bool = True
+    ):
+        """
+        Initialize a simple condition.
+
+        Args:
+            field: Field path to evaluate (supports dot notation)
+            operator: Comparison operator name
+            value: Value to compare against
+            case_sensitive: Whether string comparisons are case-sensitive
+        """
+        self.field = field
+        self.operator = operator
+        self.value = value
+        self.case_sensitive = case_sensitive
+
+    def evaluate(self, data: Dict[str, Any]) -> bool:
+        """
+        Evaluate the condition against data.
+
+        Args:
+            data: Data dictionary to evaluate
+
+        Returns:
+            True if condition is met, False otherwise
+        """
+        field_value = self.get_nested_value(data, self.field)
+        evaluator = EvaluatorFactory.get(self.operator)
+        return evaluator.evaluate(field_value, self.value, self.case_sensitive)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Serialize condition to dictionary.
+
+        Returns:
+            Dictionary representation of condition
+        """
+        result = {
+            "field": self.field,
+            "operator": self.operator,
+            "value": self.value,
+        }
+        if not self.case_sensitive:
+            result["case_sensitive"] = False
+        return result
+
+    def __repr__(self) -> str:
+        return f"SimpleCondition({self.field} {self.operator} {self.value})"

pylitmus/engine.py

@@ -0,0 +1,244 @@
+"""
+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, Rule, RuleResult
+
+if TYPE_CHECKING:
+    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:
+        engine = RuleEngine(
+            repository=DatabaseRuleRepository(db_url),
+            scoring_strategy=WeightedStrategy()
+        )
+
+        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,
+        condition_builder: Optional[Any] = None,
+    ):
+        """
+        Initialize the rule engine.
+
+        Args:
+            repository: Rule storage backend
+            scoring_strategy: Strategy for calculating scores
+            decision_thresholds: Custom thresholds for decisions
+            condition_builder: Builder for creating conditions from dicts
+        """
+        self.repository = repository
+        self._scoring_strategy = scoring_strategy
+        self._thresholds = decision_thresholds or self.DEFAULT_THRESHOLDS.copy()
+        self._condition_builder = condition_builder
+        self._rules_cache: Optional[List[Rule]] = None
+
+        logger.info("RuleEngine initialized")
+
+    @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 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
+        """
+        start_time = time.time()
+        context = context or {}
+
+        logger.debug(f"Starting 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},
+        )
+
+        logger.info(
+            f"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) -> str:
+        """
+        Make a decision based on the total score.
+
+        Args:
+            score: Total calculated score
+
+        Returns:
+            Decision string: 'APPROVE', 'REVIEW', or 'FLAG'
+        """
+        approve_threshold = self._thresholds.get("approve", 30)
+        review_threshold = self._thresholds.get("review", 70)
+
+        if score < approve_threshold:
+            return "APPROVE"
+        elif score < review_threshold:
+            return "REVIEW"
+        else:
+            return "FLAG"
+
+    def reload_rules(self) -> None:
+        """Force reload rules from repository."""
+        self._rules_cache = None
+
+        # 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)

pylitmus/evaluators/__init__.py

@@ -0,0 +1,11 @@
+"""
+Evaluators module for the CMAP Rules Engine.
+"""
+
+from .base import Evaluator
+from .factory import EvaluatorFactory
+
+__all__ = [
+    "Evaluator",
+    "EvaluatorFactory",
+]

pylitmus/evaluators/base.py

@@ -0,0 +1,27 @@
+"""
+Base evaluator class for the CMAP Rules Engine.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Evaluator(ABC):
+    """Abstract base class for condition evaluators."""
+
+    @abstractmethod
+    def evaluate(
+        self, field_value: Any, compare_value: Any, case_sensitive: bool = True
+    ) -> bool:
+        """
+        Evaluate a condition.
+
+        Args:
+            field_value: The actual value from data
+            compare_value: The value to compare against
+            case_sensitive: Whether to use case-sensitive comparison
+
+        Returns:
+            True if condition is met, False otherwise
+        """
+        pass