additory 0.1.0a4__py3-none-any.whl → 0.1.1a1__py3-none-any.whl

additory/core/enhanced_matchers.py

@@ -1,473 +0,0 @@
-# additory/core/enhanced_matchers.py
-
-"""
-Enhanced Match Parameters System for Intelligent String Matching
-
-This module provides the enhanced matching system for add.to() with case-insensitive
-defaults and comprehensive matching strategies. It builds upon the existing matchers
-but provides a more user-friendly interface with intelligent defaults.
-
-New Match Parameter Design:
-- "exact": Case-insensitive exact match (DEFAULT) - maps to "iexact"
-- "exact_case": Case-sensitive exact match - maps to "exact"
-- "contains": Case-insensitive substring matching - maps to "icontains"
-- "contains_case": Case-sensitive substring matching - maps to "contains"
-- "startswith": Case-insensitive prefix matching - maps to "ibeginswith"
-- "startswith_case": Case-sensitive prefix matching - maps to "beginswith"
-- "endswith": Case-insensitive suffix matching - maps to "iendswith"
-- "endswith_case": Case-sensitive suffix matching - maps to "endswith"
-- "regex": Regular expression matching (case-sensitive by default)
-- "range": Numeric range matching
-- "fuzzy": Fuzzy string matching with configurable threshold
-
-Design Philosophy:
-- Case-insensitive by default for real-world messy data
-- Explicit "_case" suffix when case sensitivity is needed
-- Backward compatibility with existing matchers
-- Enhanced fuzzy matching with configurable parameters
-- Comprehensive validation and helpful error messages
-"""
-
-import logging
-import re
-from typing import List, Dict, Any, Tuple, Optional, Union
-from dataclasses import dataclass
-
-# Import existing matchers
-from ..ops.matchers import (
-    match_exact, match_iexact, match_contains, match_icontains,
-    match_beginswith, match_ibeginswith, match_endswith, match_iendswith,
-    match_regex, match_numeric_range, match_fuzzy,
-    _safe_contains, _safe_startswith, _safe_endswith, _calculate_similarity
-)
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class MatchConfig:
-    """Configuration for enhanced matching operations"""
-    strategy: str
-    case_sensitive: bool
-    fuzzy_threshold: float = 0.8
-    regex_flags: int = 0
-    numeric_tolerance: float = 0.0
-    description: str = ""
-    examples: List[str] = None
-
-
-class EnhancedMatcherSystem:
-    """
-    Enhanced matching system with case-insensitive defaults and comprehensive strategies
-    """
-    
-    def __init__(self):
-        self._match_configs = self._initialize_match_configs()
-        self._match_stats = {
-            'total_matches': 0,
-            'exact_matches': 0,
-            'case_insensitive_matches': 0,
-            'case_sensitive_matches': 0,
-            'fuzzy_matches': 0,
-            'regex_matches': 0,
-            'contains_matches': 0,
-            'prefix_suffix_matches': 0,
-            'range_matches': 0
-        }
-    
-    def get_matcher_function(self, match_strategy: str) -> callable:
-        """
-        Get the appropriate matcher function for the given strategy
-        
-        Args:
-            match_strategy: Enhanced match strategy name
-            
-        Returns:
-            Callable matcher function
-        """
-        
-        # Validate strategy
-        if match_strategy not in self._match_configs:
-            available = list(self._match_configs.keys())
-            raise ValueError(f"Unknown match strategy: '{match_strategy}'. Available: {available}")
-        
-        config = self._match_configs[match_strategy]
-        
-        # Map enhanced strategies to existing matcher functions
-        strategy_mapping = {
-            "exact": match_iexact,           # Case-insensitive by default
-            "exact_case": match_exact,       # Case-sensitive when explicit
-            "contains": match_icontains,     # Case-insensitive by default
-            "contains_case": match_contains, # Case-sensitive when explicit
-            "startswith": match_ibeginswith, # Case-insensitive by default
-            "startswith_case": match_beginswith, # Case-sensitive when explicit
-            "endswith": match_iendswith,     # Case-insensitive by default
-            "endswith_case": match_endswith, # Case-sensitive when explicit
-            "regex": match_regex,            # Case-sensitive (standard regex behavior)
-            "range": match_numeric_range,    # Numeric range matching
-            "fuzzy": self._create_fuzzy_matcher(config.fuzzy_threshold)
-        }
-        
-        matcher_func = strategy_mapping.get(match_strategy)
-        if matcher_func is None:
-            raise ValueError(f"No matcher implementation for strategy: '{match_strategy}'")
-        
-        # Wrap the matcher to collect statistics
-        return self._wrap_matcher_with_stats(matcher_func, match_strategy)
-    
-    def _create_fuzzy_matcher(self, threshold: float = 0.8) -> callable:
-        """Create a fuzzy matcher with configurable threshold"""
-        
-        def fuzzy_matcher_with_threshold(key, lookup):
-            """Fuzzy matching with configurable threshold"""
-            matches = []
-            
-            for k, rows in lookup.items():
-                similarity = _calculate_similarity(key, k)
-                if similarity >= threshold:
-                    matches.extend(rows)
-            
-            return matches
-        
-        return fuzzy_matcher_with_threshold
-    
-    def _wrap_matcher_with_stats(self, matcher_func: callable, strategy: str) -> callable:
-        """Wrap matcher function to collect statistics"""
-        
-        def wrapped_matcher(key, lookup):
-            """Wrapped matcher that collects statistics"""
-            matches = matcher_func(key, lookup)
-            
-            # Update statistics
-            self._match_stats['total_matches'] += 1
-            
-            if strategy in ['exact', 'contains', 'startswith', 'endswith']:
-                self._match_stats['case_insensitive_matches'] += 1
-            elif strategy in ['exact_case', 'contains_case', 'startswith_case', 'endswith_case']:
-                self._match_stats['case_sensitive_matches'] += 1
-            elif strategy == 'fuzzy':
-                self._match_stats['fuzzy_matches'] += 1
-            elif strategy == 'regex':
-                self._match_stats['regex_matches'] += 1
-            elif strategy == 'range':
-                self._match_stats['range_matches'] += 1
-            
-            if strategy in ['exact', 'exact_case']:
-                self._match_stats['exact_matches'] += 1
-            elif strategy in ['contains', 'contains_case']:
-                self._match_stats['contains_matches'] += 1
-            elif strategy in ['startswith', 'startswith_case', 'endswith', 'endswith_case']:
-                self._match_stats['prefix_suffix_matches'] += 1
-            
-            return matches
-        
-        return wrapped_matcher
-    
-    def validate_match_strategy(self, strategy: str) -> Dict[str, Any]:
-        """
-        Validate match strategy and provide helpful information
-        
-        Returns:
-            Dict with validation results, description, and examples
-        """
-        
-        result = {
-            'valid': strategy in self._match_configs,
-            'strategy': strategy,
-            'config': None,
-            'suggestions': [],
-            'similar_strategies': []
-        }
-        
-        if result['valid']:
-            config = self._match_configs[strategy]
-            result['config'] = {
-                'description': config.description,
-                'case_sensitive': config.case_sensitive,
-                'examples': config.examples or [],
-                'fuzzy_threshold': config.fuzzy_threshold if strategy == 'fuzzy' else None
-            }
-        else:
-            # Provide suggestions for invalid strategies
-            result['suggestions'] = [
-                "Valid match strategies:",
-                "  Case-insensitive (default):",
-                "    - 'exact': Exact match, ignoring case",
-                "    - 'contains': Substring match, ignoring case", 
-                "    - 'startswith': Prefix match, ignoring case",
-                "    - 'endswith': Suffix match, ignoring case",
-                "  Case-sensitive (explicit):",
-                "    - 'exact_case': Exact match, case-sensitive",
-                "    - 'contains_case': Substring match, case-sensitive",
-                "    - 'startswith_case': Prefix match, case-sensitive",
-                "    - 'endswith_case': Suffix match, case-sensitive",
-                "  Advanced:",
-                "    - 'fuzzy': Fuzzy string matching",
-                "    - 'regex': Regular expression matching",
-                "    - 'range': Numeric range matching"
-            ]
-            
-            # Find similar strategies
-            available_strategies = list(self._match_configs.keys())
-            result['similar_strategies'] = [
-                s for s in available_strategies 
-                if strategy.lower() in s.lower() or s.lower() in strategy.lower()
-            ][:3]  # Top 3 similar
-        
-        return result
-    
-    def get_match_examples(self, strategy: str) -> List[Dict[str, Any]]:
-        """Get practical examples for a match strategy"""
-        
-        examples = {
-            "exact": [
-                {"target": "Apple", "reference": "APPLE", "matches": True, "reason": "Case-insensitive exact match"},
-                {"target": "Apple", "reference": "Orange", "matches": False, "reason": "Different values"},
-                {"target": "Apple Inc", "reference": "apple inc", "matches": True, "reason": "Case-insensitive exact match"}
-            ],
-            "exact_case": [
-                {"target": "Apple", "reference": "APPLE", "matches": False, "reason": "Case-sensitive, different case"},
-                {"target": "Apple", "reference": "Apple", "matches": True, "reason": "Exact case match"},
-                {"target": "Apple", "reference": "apple", "matches": False, "reason": "Case-sensitive, different case"}
-            ],
-            "contains": [
-                {"target": "laptop", "reference": "Gaming Laptop Pro", "matches": True, "reason": "Contains 'laptop' (case-insensitive)"},
-                {"target": "MOUSE", "reference": "wireless mouse", "matches": True, "reason": "Contains 'mouse' (case-insensitive)"},
-                {"target": "keyboard", "reference": "Monitor", "matches": False, "reason": "Does not contain 'keyboard'"}
-            ],
-            "contains_case": [
-                {"target": "Laptop", "reference": "Gaming Laptop Pro", "matches": True, "reason": "Contains 'Laptop' (exact case)"},
-                {"target": "laptop", "reference": "Gaming Laptop Pro", "matches": False, "reason": "Case-sensitive, different case"},
-                {"target": "MOUSE", "reference": "wireless mouse", "matches": False, "reason": "Case-sensitive, different case"}
-            ],
-            "startswith": [
-                {"target": "tech", "reference": "TechCorp Inc", "matches": True, "reason": "Starts with 'tech' (case-insensitive)"},
-                {"target": "PROD", "reference": "product-001", "matches": True, "reason": "Starts with 'prod' (case-insensitive)"},
-                {"target": "sales", "reference": "Marketing Dept", "matches": False, "reason": "Does not start with 'sales'"}
-            ],
-            "fuzzy": [
-                {"target": "John Smith", "reference": "Jon Smith", "matches": True, "reason": "High similarity (typo tolerance)"},
-                {"target": "TechCorp", "reference": "Tech Corp", "matches": True, "reason": "High similarity (spacing difference)"},
-                {"target": "Apple", "reference": "Orange", "matches": False, "reason": "Low similarity, different words"}
-            ],
-            "regex": [
-                {"target": r"P\d{3}", "reference": "P001", "matches": True, "reason": "Matches pattern P + 3 digits"},
-                {"target": r"^[A-Z]{2}\d{4}$", "reference": "AB1234", "matches": True, "reason": "Matches 2 letters + 4 digits"},
-                {"target": r"\d+", "reference": "Product123", "matches": True, "reason": "Contains digits"}
-            ]
-        }
-        
-        return examples.get(strategy, [])
-    
-    def _initialize_match_configs(self) -> Dict[str, MatchConfig]:
-        """Initialize match strategy configurations"""
-        
-        return {
-            "exact": MatchConfig(
-                strategy="exact",
-                case_sensitive=False,
-                description="Case-insensitive exact match (default)",
-                examples=["'Apple' matches 'APPLE', 'apple', 'Apple'"]
-            ),
-            "exact_case": MatchConfig(
-                strategy="exact_case", 
-                case_sensitive=True,
-                description="Case-sensitive exact match",
-                examples=["'Apple' matches only 'Apple', not 'APPLE' or 'apple'"]
-            ),
-            "contains": MatchConfig(
-                strategy="contains",
-                case_sensitive=False,
-                description="Case-insensitive substring matching",
-                examples=["'laptop' matches 'Gaming Laptop Pro', 'LAPTOP-001'"]
-            ),
-            "contains_case": MatchConfig(
-                strategy="contains_case",
-                case_sensitive=True,
-                description="Case-sensitive substring matching", 
-                examples=["'Laptop' matches 'Gaming Laptop Pro' but not 'gaming laptop pro'"]
-            ),
-            "startswith": MatchConfig(
-                strategy="startswith",
-                case_sensitive=False,
-                description="Case-insensitive prefix matching",
-                examples=["'tech' matches 'TechCorp', 'TECHNOLOGY', 'tech-support'"]
-            ),
-            "startswith_case": MatchConfig(
-                strategy="startswith_case",
-                case_sensitive=True,
-                description="Case-sensitive prefix matching",
-                examples=["'Tech' matches 'TechCorp' but not 'technology'"]
-            ),
-            "endswith": MatchConfig(
-                strategy="endswith",
-                case_sensitive=False,
-                description="Case-insensitive suffix matching",
-                examples=["'corp' matches 'TechCorp', 'RETAILCORP', 'my-corp'"]
-            ),
-            "endswith_case": MatchConfig(
-                strategy="endswith_case",
-                case_sensitive=True,
-                description="Case-sensitive suffix matching",
-                examples=["'Corp' matches 'TechCorp' but not 'techcorp'"]
-            ),
-            "fuzzy": MatchConfig(
-                strategy="fuzzy",
-                case_sensitive=False,
-                fuzzy_threshold=0.8,
-                description="Fuzzy string matching with similarity threshold",
-                examples=["'John Smith' matches 'Jon Smith', 'John Smyth' (typo tolerance)"]
-            ),
-            "regex": MatchConfig(
-                strategy="regex",
-                case_sensitive=True,
-                description="Regular expression pattern matching",
-                examples=["r'P\\d{3}' matches 'P001', 'P123' (product codes)"]
-            ),
-            "range": MatchConfig(
-                strategy="range",
-                case_sensitive=False,
-                description="Numeric range matching",
-                examples=["(10, 50) matches values between 10 and 50 inclusive"]
-            )
-        }
-    
-    def get_strategy_recommendations(self, use_case: str) -> List[str]:
-        """Get strategy recommendations based on use case"""
-        
-        recommendations = {
-            "messy_data": ["exact", "fuzzy", "contains"],
-            "clean_data": ["exact_case", "exact", "contains_case"],
-            "product_codes": ["exact", "regex", "startswith"],
-            "names": ["fuzzy", "exact", "contains"],
-            "categories": ["exact", "contains", "startswith"],
-            "ids": ["exact_case", "exact", "regex"],
-            "text_search": ["contains", "fuzzy", "startswith"],
-            "strict_matching": ["exact_case", "regex"],
-            "flexible_matching": ["fuzzy", "contains", "exact"]
-        }
-        
-        return recommendations.get(use_case.lower(), ["exact", "contains", "fuzzy"])
-    
-    def get_stats(self) -> Dict[str, Any]:
-        """Get matching statistics"""
-        return self._match_stats.copy()
-    
-    def reset_stats(self):
-        """Reset matching statistics"""
-        self._match_stats = {
-            'total_matches': 0,
-            'exact_matches': 0,
-            'case_insensitive_matches': 0,
-            'case_sensitive_matches': 0,
-            'fuzzy_matches': 0,
-            'regex_matches': 0,
-            'contains_matches': 0,
-            'prefix_suffix_matches': 0,
-            'range_matches': 0
-        }
-
-
-# Global enhanced matcher system
-_enhanced_matcher = EnhancedMatcherSystem()
-
-
-# Convenience functions
-def get_enhanced_matcher(strategy: str) -> callable:
-    """Get enhanced matcher function for strategy"""
-    return _enhanced_matcher.get_matcher_function(strategy)
-
-
-def validate_enhanced_match_strategy(strategy: str) -> Dict[str, Any]:
-    """Validate enhanced match strategy"""
-    return _enhanced_matcher.validate_match_strategy(strategy)
-
-
-def get_enhanced_match_examples(strategy: str) -> List[Dict[str, Any]]:
-    """Get examples for enhanced match strategy"""
-    return _enhanced_matcher.get_match_examples(strategy)
-
-
-def get_strategy_recommendations(use_case: str) -> List[str]:
-    """Get strategy recommendations for use case"""
-    return _enhanced_matcher.get_strategy_recommendations(use_case)
-
-
-def get_enhanced_match_stats() -> Dict[str, Any]:
-    """Get enhanced matching statistics"""
-    return _enhanced_matcher.get_stats()
-
-
-# Enhanced matcher mapping for backward compatibility
-ENHANCED_MATCHERS = {
-    # Case-insensitive defaults (new behavior)
-    "exact": "iexact",           # Maps to existing case-insensitive matcher
-    "contains": "icontains",     # Maps to existing case-insensitive matcher
-    "startswith": "ibeginswith", # Maps to existing case-insensitive matcher
-    "endswith": "iendswith",     # Maps to existing case-insensitive matcher
-    
-    # Case-sensitive explicit (when needed)
-    "exact_case": "exact",       # Maps to existing case-sensitive matcher
-    "contains_case": "contains", # Maps to existing case-sensitive matcher
-    "startswith_case": "beginswith", # Maps to existing case-sensitive matcher
-    "endswith_case": "endswith", # Maps to existing case-sensitive matcher
-    
-    # Advanced matching (unchanged)
-    "fuzzy": "fuzzy",
-    "regex": "regex", 
-    "range": "range"
-}
-
-
-def map_enhanced_to_legacy_strategy(enhanced_strategy: str) -> str:
-    """Map enhanced strategy name to legacy matcher name"""
-    return ENHANCED_MATCHERS.get(enhanced_strategy, enhanced_strategy)
-
-
-# Demonstration and validation
-def demonstrate_enhanced_matching():
-    """Demonstrate enhanced matching capabilities"""
-    
-    print("Enhanced Match Parameters Demonstration")
-    print("=" * 50)
-    
-    # Test data
-    test_cases = [
-        ("exact", "Apple", ["APPLE", "apple", "Apple Inc"]),
-        ("exact_case", "Apple", ["APPLE", "apple", "Apple"]),
-        ("contains", "laptop", ["Gaming Laptop", "LAPTOP-001", "My Laptop"]),
-        ("startswith", "tech", ["TechCorp", "TECHNOLOGY", "tech-support"]),
-        ("fuzzy", "John Smith", ["Jon Smith", "John Smyth", "Jane Doe"])
-    ]
-    
-    for strategy, target, candidates in test_cases:
-        print(f"\nStrategy: {strategy}")
-        print(f"Target: '{target}'")
-        print("Candidates:")
-        
-        # Get matcher function
-        try:
-            matcher = get_enhanced_matcher(strategy)
-            
-            # Create simple lookup structure
-            lookup = {(candidate,): [i] for i, candidate in enumerate(candidates)}
-            
-            # Test matching
-            matches = matcher((target,), lookup)
-            
-            for i, candidate in enumerate(candidates):
-                match_status = "✅" if i in matches else "❌"
-                print(f"  {match_status} '{candidate}'")
-                
-        except Exception as e:
-            print(f"  Error: {e}")
-    
-    # Show statistics
-    stats = get_enhanced_match_stats()
-    print(f"\nMatching Statistics:")
-    for key, value in stats.items():
-        print(f"  {key}: {value}")
-
-
-if __name__ == "__main__":
-    demonstrate_enhanced_matching()