pylitmus 1.0.0__py3-none-any.whl

pylitmus/integrations/flask/extension.py

@@ -0,0 +1,234 @@
+"""
+Flask extension for cmap-rules-engine.
+"""
+
+from typing import Any, Dict, Optional
+
+from ...engine import RuleEngine
+from ...storage import CachedRuleRepository, InMemoryRuleRepository
+from ...strategies import MaxStrategy, SumStrategy, WeightedStrategy
+
+try:
+    from flask import Flask, current_app
+
+    HAS_FLASK = True
+except ImportError:
+    HAS_FLASK = False
+    Flask = Any
+
+
+def create_repository(config: Dict[str, Any]) -> Any:
+    """
+    Create a rule repository from Flask config.
+
+    Args:
+        config: Flask app configuration
+
+    Returns:
+        RuleRepository instance
+    """
+    backend = config.get("CMAP_RULES_STORAGE", "memory")
+
+    if backend == "memory":
+        return InMemoryRuleRepository()
+
+    elif backend == "database":
+        from ...storage import DatabaseRuleRepository
+
+        db_url = config.get("CMAP_RULES_DATABASE_URL")
+        if not db_url:
+            raise ValueError("CMAP_RULES_DATABASE_URL required for database backend")
+
+        # Note: User needs to provide their own session factory
+        session_factory = config.get("CMAP_RULES_SESSION_FACTORY")
+        if not session_factory:
+            raise ValueError("CMAP_RULES_SESSION_FACTORY required for database backend")
+
+        model_class = config.get("CMAP_RULES_MODEL_CLASS")
+        return DatabaseRuleRepository(session_factory, model_class)
+
+    elif backend == "file":
+        from ...storage import FileRuleRepository
+
+        file_path = config.get("CMAP_RULES_FILE_PATH")
+        if not file_path:
+            raise ValueError("CMAP_RULES_FILE_PATH required for file backend")
+        return FileRuleRepository(file_path)
+
+    else:
+        raise ValueError(f"Unknown storage backend: {backend}")
+
+
+def create_strategy(config: Dict[str, Any]) -> Any:
+    """
+    Create a scoring strategy from Flask config.
+
+    Args:
+        config: Flask app configuration
+
+    Returns:
+        ScoringStrategy instance
+    """
+    strategy_name = config.get("CMAP_RULES_SCORING_STRATEGY", "sum")
+
+    strategies = {
+        "sum": SumStrategy,
+        "weighted": WeightedStrategy,
+        "max": MaxStrategy,
+    }
+
+    if strategy_name not in strategies:
+        raise ValueError(f"Unknown strategy: {strategy_name}")
+
+    return strategies[strategy_name]()
+
+
+class CmapRulesEngine:
+    """
+    Flask extension for cmap-rules-engine.
+
+    Usage:
+        # Initialize
+        rules_engine = CmapRulesEngine()
+
+        # With app factory
+        def create_app():
+            app = Flask(__name__)
+            rules_engine.init_app(app)
+            return app
+
+        # Or direct initialization
+        app = Flask(__name__)
+        rules_engine = CmapRulesEngine(app)
+
+        # In routes
+        @app.route('/evaluate')
+        def evaluate():
+            engine = get_engine()
+            result = engine.evaluate(data)
+            return jsonify(result)
+    """
+
+    def __init__(self, app: Optional[Flask] = None):
+        """
+        Initialize the Flask extension.
+
+        Args:
+            app: Flask application instance (optional)
+        """
+        if not HAS_FLASK:
+            raise ImportError(
+                "Flask is required for the Flask integration. "
+                "Install it with: pip install cmap-rules-engine[flask]"
+            )
+
+        self._engine: Optional[RuleEngine] = None
+
+        if app is not None:
+            self.init_app(app)
+
+    def init_app(self, app: Flask) -> None:
+        """
+        Initialize extension with Flask app.
+
+        Args:
+            app: Flask application instance
+        """
+        # Store reference in extensions
+        if not hasattr(app, "extensions"):
+            app.extensions = {}
+        app.extensions["cmap_rules_engine"] = self
+
+        # Set default configuration
+        app.config.setdefault("CMAP_RULES_STORAGE", "memory")
+        app.config.setdefault("CMAP_RULES_CACHE", "memory")
+        app.config.setdefault("CMAP_RULES_SCORING_STRATEGY", "sum")
+        app.config.setdefault("CMAP_RULES_CACHE_TTL", 300)
+        app.config.setdefault("CMAP_RULES_THRESHOLDS", {"approve": 30, "review": 70})
+
+        # Build engine
+        self._engine = self._create_engine(app.config)
+
+        # Register teardown
+        app.teardown_appcontext(self._teardown)
+
+    def _create_engine(self, config: Dict[str, Any]) -> RuleEngine:
+        """
+        Create engine from Flask config.
+
+        Args:
+            config: Flask app configuration
+
+        Returns:
+            Configured RuleEngine
+        """
+        # Create repository
+        repository = create_repository(config)
+
+        # Wrap with cache if enabled
+        cache_backend = config.get("CMAP_RULES_CACHE", "memory")
+        if cache_backend != "none":
+            cache_url = config.get("CMAP_RULES_CACHE_URL")
+            cache_ttl = config.get("CMAP_RULES_CACHE_TTL", 300)
+
+            repository = CachedRuleRepository(
+                repository=repository,
+                cache_backend=cache_backend,
+                cache_url=cache_url,
+                ttl_seconds=cache_ttl,
+            )
+
+        # Create strategy
+        strategy = create_strategy(config)
+
+        # Get thresholds
+        thresholds = config.get("CMAP_RULES_THRESHOLDS")
+
+        return RuleEngine(
+            repository=repository,
+            scoring_strategy=strategy,
+            decision_thresholds=thresholds,
+        )
+
+    @property
+    def engine(self) -> RuleEngine:
+        """Get the rule engine instance."""
+        if self._engine is None:
+            raise RuntimeError(
+                "CmapRulesEngine not initialized. Call init_app() first."
+            )
+        return self._engine
+
+    def _teardown(self, exception: Optional[Exception]) -> None:
+        """Cleanup on request teardown."""
+        pass
+
+
+def get_engine() -> RuleEngine:
+    """
+    Get rule engine from current Flask app.
+
+    Usage:
+        from cmap_rules_engine.integrations.flask import get_engine
+
+        @app.route('/assess')
+        def assess():
+            engine = get_engine()
+            result = engine.evaluate(request.json)
+            return jsonify(result)
+
+    Returns:
+        RuleEngine instance
+
+    Raises:
+        RuntimeError: If not in a Flask application context
+    """
+    if not HAS_FLASK:
+        raise ImportError("Flask is required for the Flask integration")
+
+    if "cmap_rules_engine" 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

pylitmus/patterns/__init__.py

@@ -0,0 +1,21 @@
+"""
+Pattern matching module for the CMAP Rules Engine.
+"""
+
+from .base import PatternMatcher
+from .engine import EnhancedPatternEngine
+from .exact import ExactMatcher
+from .fuzzy import FuzzyMatcher
+from .glob import GlobMatcher
+from .range import RangeMatcher
+from .regex import RegexMatcher
+
+__all__ = [
+    "PatternMatcher",
+    "ExactMatcher",
+    "RegexMatcher",
+    "FuzzyMatcher",
+    "RangeMatcher",
+    "GlobMatcher",
+    "EnhancedPatternEngine",
+]

pylitmus/patterns/base.py

@@ -0,0 +1,25 @@
+"""
+Base pattern matcher class.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class PatternMatcher(ABC):
+    """Base class for pattern matchers."""
+
+    @abstractmethod
+    def match(self, value: Any, pattern: Any, **options) -> bool:
+        """
+        Check if value matches pattern.
+
+        Args:
+            value: Value to check
+            pattern: Pattern to match against
+            **options: Additional matcher-specific options
+
+        Returns:
+            True if matches, False otherwise
+        """
+        pass

pylitmus/patterns/engine.py

@@ -0,0 +1,82 @@
+"""
+Enhanced pattern engine aggregating all pattern matchers.
+"""
+
+from typing import Any, Dict
+
+from .base import PatternMatcher
+from .exact import ExactMatcher
+from .fuzzy import FuzzyMatcher
+from .glob import GlobMatcher
+from .range import RangeMatcher
+from .regex import RegexMatcher
+
+
+class EnhancedPatternEngine:
+    """Aggregator for all pattern matchers."""
+
+    def __init__(self):
+        """Initialize with default matchers."""
+        self.matchers: Dict[str, PatternMatcher] = {
+            "exact": ExactMatcher(),
+            "regex": RegexMatcher(),
+            "fuzzy": FuzzyMatcher(),
+            "range": RangeMatcher(),
+            "glob": GlobMatcher(),
+        }
+
+    def match(
+        self, value: Any, pattern: Any, pattern_type: str = "exact", **options
+    ) -> bool:
+        """
+        Match value against pattern using specified matcher.
+
+        Args:
+            value: Value to check
+            pattern: Pattern to match
+            pattern_type: Type of pattern matching
+            **options: Matcher-specific options
+
+        Returns:
+            True if matches
+
+        Raises:
+            ValueError: If pattern_type is not registered
+        """
+        matcher = self.matchers.get(pattern_type)
+        if not matcher:
+            raise ValueError(f"Unknown pattern type: {pattern_type}")
+
+        return matcher.match(value, pattern, **options)
+
+    def register(self, name: str, matcher: PatternMatcher) -> None:
+        """
+        Register a custom pattern matcher.
+
+        Args:
+            name: Matcher name
+            matcher: PatternMatcher instance
+        """
+        self.matchers[name] = matcher
+
+    def get_matcher(self, pattern_type: str) -> PatternMatcher:
+        """
+        Get a specific matcher.
+
+        Args:
+            pattern_type: Type of matcher
+
+        Returns:
+            PatternMatcher instance
+
+        Raises:
+            ValueError: If pattern_type is not registered
+        """
+        matcher = self.matchers.get(pattern_type)
+        if not matcher:
+            raise ValueError(f"Unknown pattern type: {pattern_type}")
+        return matcher
+
+    def get_supported_types(self) -> list:
+        """Get list of supported pattern types."""
+        return list(self.matchers.keys())

pylitmus/patterns/exact.py

@@ -0,0 +1,34 @@
+"""
+Exact pattern matcher.
+"""
+
+from typing import Any
+
+from .base import PatternMatcher
+
+
+class ExactMatcher(PatternMatcher):
+    """Exact match pattern matcher."""
+
+    def match(self, value: Any, pattern: Any, **options) -> bool:
+        """
+        Check for exact match.
+
+        Args:
+            value: Value to check
+            pattern: Pattern to match
+            case_insensitive: If True, ignore case for strings
+
+        Returns:
+            True if exact match
+        """
+        if value is None or pattern is None:
+            return value == pattern
+
+        case_insensitive = options.get("case_insensitive", False)
+
+        if isinstance(value, str) and isinstance(pattern, str):
+            if case_insensitive:
+                return value.lower() == pattern.lower()
+
+        return value == pattern

pylitmus/patterns/fuzzy.py

@@ -0,0 +1,69 @@
+"""
+Fuzzy pattern matcher using difflib.
+"""
+
+from difflib import SequenceMatcher
+from typing import Any
+
+from .base import PatternMatcher
+
+
+class FuzzyMatcher(PatternMatcher):
+    """Fuzzy string matcher using difflib."""
+
+    DEFAULT_THRESHOLD = 0.8
+
+    def match(self, value: Any, pattern: Any, **options) -> bool:
+        """
+        Check if value fuzzy matches pattern.
+
+        Args:
+            value: Value to check
+            pattern: Pattern to match
+            threshold: Minimum similarity ratio (0.0 to 1.0)
+            case_insensitive: If True, ignore case
+
+        Returns:
+            True if similarity >= threshold
+        """
+        if value is None or pattern is None:
+            return False
+
+        threshold = options.get("threshold", self.DEFAULT_THRESHOLD)
+        case_insensitive = options.get("case_insensitive", True)
+
+        str_value = str(value)
+        str_pattern = str(pattern)
+
+        if case_insensitive:
+            str_value = str_value.lower()
+            str_pattern = str_pattern.lower()
+
+        ratio = SequenceMatcher(None, str_value, str_pattern).ratio()
+        return ratio >= threshold
+
+    def get_ratio(
+        self, value: Any, pattern: Any, case_insensitive: bool = True
+    ) -> float:
+        """
+        Get the similarity ratio between value and pattern.
+
+        Args:
+            value: Value to check
+            pattern: Pattern to compare
+            case_insensitive: If True, ignore case
+
+        Returns:
+            Similarity ratio (0.0 to 1.0)
+        """
+        if value is None or pattern is None:
+            return 0.0
+
+        str_value = str(value)
+        str_pattern = str(pattern)
+
+        if case_insensitive:
+            str_value = str_value.lower()
+            str_pattern = str_pattern.lower()
+
+        return SequenceMatcher(None, str_value, str_pattern).ratio()

pylitmus/patterns/glob.py

@@ -0,0 +1,38 @@
+"""
+Glob pattern matcher.
+"""
+
+import fnmatch
+from typing import Any
+
+from .base import PatternMatcher
+
+
+class GlobMatcher(PatternMatcher):
+    """Glob/wildcard pattern matcher using fnmatch."""
+
+    def match(self, value: Any, pattern: Any, **options) -> bool:
+        """
+        Check if value matches glob pattern.
+
+        Args:
+            value: Value to check
+            pattern: Glob pattern (e.g., "*.txt", "file_*")
+            case_insensitive: If True, ignore case
+
+        Returns:
+            True if matches glob pattern
+        """
+        if value is None or pattern is None:
+            return False
+
+        case_insensitive = options.get("case_insensitive", False)
+
+        str_value = str(value)
+        str_pattern = str(pattern)
+
+        if case_insensitive:
+            str_value = str_value.lower()
+            str_pattern = str_pattern.lower()
+
+        return fnmatch.fnmatch(str_value, str_pattern)

pylitmus/patterns/range.py

@@ -0,0 +1,53 @@
+"""
+Range pattern matcher.
+"""
+
+from typing import Any
+
+from .base import PatternMatcher
+
+
+class RangeMatcher(PatternMatcher):
+    """Numeric range matcher."""
+
+    def match(self, value: Any, pattern: Any, **options) -> bool:
+        """
+        Check if value is within range.
+
+        Args:
+            value: Value to check
+            pattern: Range as [min, max] or {'min': x, 'max': y}
+            inclusive: If True (default), range is inclusive
+
+        Returns:
+            True if value is within range
+        """
+        if value is None:
+            return False
+
+        try:
+            num_value = float(value)
+        except (ValueError, TypeError):
+            return False
+
+        # Parse pattern
+        if isinstance(pattern, (list, tuple)) and len(pattern) == 2:
+            min_val, max_val = pattern
+        elif isinstance(pattern, dict):
+            min_val = pattern.get("min", float("-inf"))
+            max_val = pattern.get("max", float("inf"))
+        else:
+            return False
+
+        inclusive = options.get("inclusive", True)
+
+        try:
+            min_val = float(min_val) if min_val is not None else float("-inf")
+            max_val = float(max_val) if max_val is not None else float("inf")
+        except (ValueError, TypeError):
+            return False
+
+        if inclusive:
+            return min_val <= num_value <= max_val
+        else:
+            return min_val < num_value < max_val

pylitmus/patterns/regex.py

@@ -0,0 +1,51 @@
+"""
+Regex pattern matcher.
+"""
+
+import re
+from functools import lru_cache
+from typing import Any
+
+from .base import PatternMatcher
+
+
+class RegexMatcher(PatternMatcher):
+    """Regex pattern matcher with compiled pattern cache."""
+
+    @staticmethod
+    @lru_cache(maxsize=1000)
+    def _compile(pattern: str, flags: int = 0) -> re.Pattern:
+        """Compile and cache regex pattern."""
+        return re.compile(pattern, flags)
+
+    def match(self, value: Any, pattern: Any, **options) -> bool:
+        """
+        Check if value matches regex pattern.
+
+        Args:
+            value: Value to check
+            pattern: Regex pattern
+            case_insensitive: If True, ignore case
+            full_match: If True, require full string match
+
+        Returns:
+            True if matches regex
+        """
+        if value is None:
+            return False
+
+        case_insensitive = options.get("case_insensitive", False)
+        full_match = options.get("full_match", False)
+
+        flags = re.IGNORECASE if case_insensitive else 0
+
+        try:
+            compiled = self._compile(str(pattern), flags)
+            str_value = str(value)
+
+            if full_match:
+                return bool(compiled.fullmatch(str_value))
+            else:
+                return bool(compiled.search(str_value))
+        except re.error:
+            return False

pylitmus/storage/__init__.py

@@ -0,0 +1,17 @@
+"""
+Storage backends module for the CMAP Rules Engine.
+"""
+
+from .base import RuleRepository
+from .cached import CachedRuleRepository
+from .database import DatabaseRuleRepository
+from .file import FileRuleRepository
+from .memory import InMemoryRuleRepository
+
+__all__ = [
+    "RuleRepository",
+    "InMemoryRuleRepository",
+    "FileRuleRepository",
+    "CachedRuleRepository",
+    "DatabaseRuleRepository",
+]