pylitmus 1.0.0__py3-none-any.whl

pylitmus/evaluators/factory.py

@@ -0,0 +1,372 @@
+"""
+Evaluator factory for creating condition evaluators.
+"""
+
+import re
+from datetime import datetime, timedelta
+from functools import lru_cache
+from typing import Any, Dict, Optional, Type, Union
+
+from ..exceptions import UnknownOperatorError
+from .base import Evaluator
+
+
+class EqualsEvaluator(Evaluator):
+    """Evaluator for equals comparison."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        if isinstance(field_value, str) and isinstance(compare_value, str):
+            if not case_sensitive:
+                return field_value.lower() == compare_value.lower()
+        return field_value == compare_value
+
+
+class NotEqualsEvaluator(Evaluator):
+    """Evaluator for not equals comparison."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        if isinstance(field_value, str) and isinstance(compare_value, str):
+            if not case_sensitive:
+                return field_value.lower() != compare_value.lower()
+        return field_value != compare_value
+
+
+class GreaterThanEvaluator(Evaluator):
+    """Evaluator for greater than comparison."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        try:
+            return field_value > compare_value
+        except TypeError:
+            return False
+
+
+class GreaterThanOrEqualEvaluator(Evaluator):
+    """Evaluator for greater than or equal comparison."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        try:
+            return field_value >= compare_value
+        except TypeError:
+            return False
+
+
+class LessThanEvaluator(Evaluator):
+    """Evaluator for less than comparison."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        try:
+            return field_value < compare_value
+        except TypeError:
+            return False
+
+
+class LessThanOrEqualEvaluator(Evaluator):
+    """Evaluator for less than or equal comparison."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        try:
+            return field_value <= compare_value
+        except TypeError:
+            return False
+
+
+class InEvaluator(Evaluator):
+    """Evaluator for in collection comparison."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        if not isinstance(compare_value, (list, tuple, set)):
+            return False
+        if isinstance(field_value, str) and not case_sensitive:
+            return field_value.lower() in [
+                v.lower() if isinstance(v, str) else v for v in compare_value
+            ]
+        return field_value in compare_value
+
+
+class NotInEvaluator(Evaluator):
+    """Evaluator for not in collection comparison."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        if not isinstance(compare_value, (list, tuple, set)):
+            return True
+        if isinstance(field_value, str) and not case_sensitive:
+            return field_value.lower() not in [
+                v.lower() if isinstance(v, str) else v for v in compare_value
+            ]
+        return field_value not in compare_value
+
+
+class ContainsEvaluator(Evaluator):
+    """Evaluator for contains (substring) comparison."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        if field_value is None or compare_value is None:
+            return False
+        field_str = str(field_value)
+        compare_str = str(compare_value)
+        if not case_sensitive:
+            return compare_str.lower() in field_str.lower()
+        return compare_str in field_str
+
+
+class StartsWithEvaluator(Evaluator):
+    """Evaluator for starts with comparison."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        if field_value is None or compare_value is None:
+            return False
+        field_str = str(field_value)
+        compare_str = str(compare_value)
+        if not case_sensitive:
+            return field_str.lower().startswith(compare_str.lower())
+        return field_str.startswith(compare_str)
+
+
+class EndsWithEvaluator(Evaluator):
+    """Evaluator for ends with comparison."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        if field_value is None or compare_value is None:
+            return False
+        field_str = str(field_value)
+        compare_str = str(compare_value)
+        if not case_sensitive:
+            return field_str.lower().endswith(compare_str.lower())
+        return field_str.endswith(compare_str)
+
+
+class IsNullEvaluator(Evaluator):
+    """Evaluator for null check."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        return field_value is None
+
+
+class IsNotNullEvaluator(Evaluator):
+    """Evaluator for not null check."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        return field_value is not None
+
+
+class MatchesRegexEvaluator(Evaluator):
+    """Evaluator for regex pattern matching."""
+
+    @staticmethod
+    @lru_cache(maxsize=1000)
+    def _compile_pattern(pattern: str, flags: int = 0) -> re.Pattern:
+        """Compile and cache regex pattern."""
+        return re.compile(pattern, flags)
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        if field_value is None:
+            return False
+
+        try:
+            flags = 0 if case_sensitive else re.IGNORECASE
+            pattern = self._compile_pattern(compare_value, flags)
+            return bool(pattern.search(str(field_value)))
+        except (re.error, TypeError):
+            return False
+
+
+class BetweenEvaluator(Evaluator):
+    """Evaluator for range check (inclusive)."""
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        if field_value is None:
+            return False
+
+        try:
+            # compare_value should be [min, max] or {"min": x, "max": y}
+            if isinstance(compare_value, (list, tuple)) and len(compare_value) == 2:
+                min_val, max_val = compare_value
+            elif isinstance(compare_value, dict):
+                min_val = compare_value.get("min")
+                max_val = compare_value.get("max")
+            else:
+                return False
+
+            return min_val <= field_value <= max_val
+        except (TypeError, KeyError):
+            return False
+
+
+class WithinDaysEvaluator(Evaluator):
+    """Evaluator for checking if date is within N days from now."""
+
+    def _parse_date(self, value: Any) -> Optional[datetime]:
+        """Parse various date formats."""
+        if value is None:
+            return None
+
+        if isinstance(value, datetime):
+            return value
+
+        if isinstance(value, str):
+            # Try common formats
+            formats = [
+                "%Y-%m-%d",
+                "%Y-%m-%dT%H:%M:%S",
+                "%Y-%m-%dT%H:%M:%S.%f",
+                "%Y-%m-%dT%H:%M:%SZ",
+                "%Y-%m-%dT%H:%M:%S.%fZ",
+                "%d/%m/%Y",
+                "%m/%d/%Y",
+            ]
+            for fmt in formats:
+                try:
+                    return datetime.strptime(value, fmt)
+                except ValueError:
+                    continue
+
+        return None
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        field_date = self._parse_date(field_value)
+        if not field_date:
+            return False
+
+        try:
+            days = int(compare_value)
+            cutoff = datetime.utcnow() - timedelta(days=days)
+            return field_date >= cutoff
+        except (ValueError, TypeError):
+            return False
+
+
+class BeforeEvaluator(Evaluator):
+    """Evaluator for checking if date is before another date."""
+
+    def _parse_date(self, value: Any) -> Optional[datetime]:
+        """Parse various date formats."""
+        if value is None:
+            return None
+
+        if isinstance(value, datetime):
+            return value
+
+        if isinstance(value, str):
+            formats = [
+                "%Y-%m-%d",
+                "%Y-%m-%dT%H:%M:%S",
+                "%Y-%m-%dT%H:%M:%S.%f",
+                "%Y-%m-%dT%H:%M:%SZ",
+            ]
+            for fmt in formats:
+                try:
+                    return datetime.strptime(value, fmt)
+                except ValueError:
+                    continue
+
+        return None
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        field_date = self._parse_date(field_value)
+        compare_date = self._parse_date(compare_value)
+
+        if field_date is None or compare_date is None:
+            return False
+
+        return field_date < compare_date
+
+
+class AfterEvaluator(Evaluator):
+    """Evaluator for checking if date is after another date."""
+
+    def _parse_date(self, value: Any) -> Optional[datetime]:
+        """Parse various date formats."""
+        if value is None:
+            return None
+
+        if isinstance(value, datetime):
+            return value
+
+        if isinstance(value, str):
+            formats = [
+                "%Y-%m-%d",
+                "%Y-%m-%dT%H:%M:%S",
+                "%Y-%m-%dT%H:%M:%S.%f",
+                "%Y-%m-%dT%H:%M:%SZ",
+            ]
+            for fmt in formats:
+                try:
+                    return datetime.strptime(value, fmt)
+                except ValueError:
+                    continue
+
+        return None
+
+    def evaluate(self, field_value, compare_value, case_sensitive=True):
+        field_date = self._parse_date(field_value)
+        compare_date = self._parse_date(compare_value)
+
+        if field_date is None or compare_date is None:
+            return False
+
+        return field_date > compare_date
+
+
+class EvaluatorFactory:
+    """Factory for creating condition evaluators."""
+
+    _evaluators: Dict[str, Type[Evaluator]] = {
+        # Comparison
+        "equals": EqualsEvaluator,
+        "not_equals": NotEqualsEvaluator,
+        "greater_than": GreaterThanEvaluator,
+        "greater_than_or_equal": GreaterThanOrEqualEvaluator,
+        "less_than": LessThanEvaluator,
+        "less_than_or_equal": LessThanOrEqualEvaluator,
+        "between": BetweenEvaluator,
+        # Collection
+        "in": InEvaluator,
+        "not_in": NotInEvaluator,
+        # String
+        "contains": ContainsEvaluator,
+        "starts_with": StartsWithEvaluator,
+        "ends_with": EndsWithEvaluator,
+        "matches_regex": MatchesRegexEvaluator,
+        # Null
+        "is_null": IsNullEvaluator,
+        "is_not_null": IsNotNullEvaluator,
+        # Temporal
+        "within_days": WithinDaysEvaluator,
+        "before": BeforeEvaluator,
+        "after": AfterEvaluator,
+    }
+
+    @classmethod
+    def get(cls, operator: str) -> Evaluator:
+        """
+        Get an evaluator for the given operator.
+
+        Args:
+            operator: Operator name
+
+        Returns:
+            Evaluator instance
+
+        Raises:
+            UnknownOperatorError: If operator is not registered
+        """
+        if operator not in cls._evaluators:
+            raise UnknownOperatorError(f"Unknown operator: {operator}")
+        return cls._evaluators[operator]()
+
+    @classmethod
+    def register(cls, operator: str, evaluator_class: Type[Evaluator]) -> None:
+        """
+        Register a custom evaluator.
+
+        Args:
+            operator: Operator name
+            evaluator_class: Evaluator class
+        """
+        cls._evaluators[operator] = evaluator_class
+
+    @classmethod
+    def get_supported_operators(cls) -> list:
+        """Get list of supported operators."""
+        return list(cls._evaluators.keys())

pylitmus/exceptions.py

@@ -0,0 +1,39 @@
+"""
+Custom exceptions for the CMAP Rules Engine.
+"""
+
+
+class RuleEngineError(Exception):
+    """Base exception for rule engine errors."""
+
+    pass
+
+
+class UnknownOperatorError(RuleEngineError):
+    """Raised when an unknown operator is used."""
+
+    pass
+
+
+class ConditionError(RuleEngineError):
+    """Raised when condition evaluation fails."""
+
+    pass
+
+
+class StorageError(RuleEngineError):
+    """Raised when storage operations fail."""
+
+    pass
+
+
+class ConfigurationError(RuleEngineError):
+    """Raised when configuration is invalid."""
+
+    pass
+
+
+class EvaluationError(RuleEngineError):
+    """Raised when rule evaluation fails."""
+
+    pass

pylitmus/factory.py

@@ -0,0 +1,179 @@
+"""
+Factory functions for creating RuleEngine instances with sensible defaults.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, List, Optional, Union
+
+from .engine import RuleEngine
+from .storage import (
+    CachedRuleRepository,
+    DatabaseRuleRepository,
+    FileRuleRepository,
+    InMemoryRuleRepository,
+    RuleRepository,
+)
+from .strategies import MaxStrategy, ScoringStrategy, SumStrategy, WeightedStrategy
+
+if TYPE_CHECKING:
+    from .types import Rule
+
+
+def create_engine(
+    # Storage
+    storage_backend: str = "memory",
+    database_url: Optional[str] = None,
+    rules_file: Optional[str] = None,
+    rules: Optional[List["Rule"]] = None,
+    repository: Optional[RuleRepository] = None,
+    # Caching
+    cache_backend: str = "memory",
+    cache_url: Optional[str] = None,
+    cache_ttl: int = 300,
+    # Scoring
+    scoring_strategy: Union[str, ScoringStrategy] = "sum",
+    # Decision
+    decision_thresholds: Optional[Dict[str, int]] = None,
+) -> RuleEngine:
+    """
+    Create a configured RuleEngine instance.
+
+    This is the recommended way to create a RuleEngine with
+    sensible defaults for most use cases.
+
+    Args:
+        storage_backend: 'memory', 'database', or 'file'
+        database_url: Database connection URL (for 'database' backend)
+        rules_file: Path to rules file (for 'file' backend)
+        rules: List of Rule objects (for 'memory' backend)
+        repository: Pre-configured repository (overrides other storage options)
+        cache_backend: 'memory', 'redis', or 'none'
+        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}
+
+    Returns:
+        Configured RuleEngine instance
+
+    Examples:
+        # Simple in-memory engine
+        engine = create_engine()
+
+        # In-memory with predefined rules
+        engine = create_engine(rules=[rule1, rule2])
+
+        # Database-backed with Redis cache
+        engine = create_engine(
+            storage_backend='database',
+            database_url='postgresql://localhost/mydb',
+            cache_backend='redis',
+            cache_url='redis://localhost:6379/0'
+        )
+
+        # File-based rules
+        engine = create_engine(
+            storage_backend='file',
+            rules_file='./rules/fraud_rules.yaml'
+        )
+
+        # With weighted scoring
+        engine = create_engine(
+            scoring_strategy='weighted',
+            decision_thresholds={'approve': 25, 'review': 60}
+        )
+    """
+
+    # Build or use provided repository
+    if repository is not None:
+        repo = repository
+    else:
+        repo = create_repository(
+            backend=storage_backend,
+            database_url=database_url,
+            rules_file=rules_file,
+            rules=rules,
+        )
+
+    # Wrap with cache if needed
+    if cache_backend != "none" and not isinstance(repo, CachedRuleRepository):
+        repo = CachedRuleRepository(
+            repository=repo,
+            cache_backend=cache_backend,
+            cache_url=cache_url,
+            ttl_seconds=cache_ttl,
+        )
+
+    # Build or use provided strategy
+    strategy = create_strategy(scoring_strategy)
+
+    # Create engine
+    return RuleEngine(
+        repository=repo,
+        scoring_strategy=strategy,
+        decision_thresholds=decision_thresholds,
+    )
+
+
+def create_repository(
+    backend: str = "memory",
+    database_url: Optional[str] = None,
+    rules_file: Optional[str] = None,
+    rules: Optional[List["Rule"]] = None,
+    **kwargs,
+) -> RuleRepository:
+    """
+    Create a rule repository.
+
+    Args:
+        backend: 'memory', 'database', or 'file'
+        database_url: Database URL for 'database' backend
+        rules_file: File path for 'file' backend
+        rules: Rules list for 'memory' backend
+
+    Returns:
+        RuleRepository instance
+    """
+    if backend == "memory":
+        return InMemoryRuleRepository(rules=rules or [])
+
+    elif backend == "database":
+        if not database_url:
+            raise ValueError("database_url required for 'database' backend")
+        return DatabaseRuleRepository(database_url)
+
+    elif backend == "file":
+        if not rules_file:
+            raise ValueError("rules_file required for 'file' backend")
+        return FileRuleRepository(rules_file)
+
+    else:
+        raise ValueError(f"Unknown storage backend: {backend}")
+
+
+def create_strategy(strategy: Union[str, ScoringStrategy]) -> ScoringStrategy:
+    """
+    Create a scoring strategy.
+
+    Args:
+        strategy: Strategy name ('sum', 'weighted', 'max') or instance
+
+    Returns:
+        ScoringStrategy instance
+    """
+    if isinstance(strategy, ScoringStrategy):
+        return strategy
+
+    strategies = {
+        "sum": SumStrategy,
+        "weighted": WeightedStrategy,
+        "max": MaxStrategy,
+    }
+
+    if strategy not in strategies:
+        raise ValueError(
+            f"Unknown strategy: {strategy}. Use: {list(strategies.keys())}"
+        )
+
+    return strategies[strategy]()

pylitmus/integrations/__init__.py

@@ -0,0 +1,3 @@
+"""
+Framework integrations for the CMAP Rules Engine.
+"""

pylitmus/integrations/flask/__init__.py

@@ -0,0 +1,10 @@
+"""
+Flask integration for the CMAP Rules Engine.
+"""
+
+from .extension import CmapRulesEngine, get_engine
+
+__all__ = [
+    "CmapRulesEngine",
+    "get_engine",
+]