aiecs 1.2.2__py3-none-any.whl → 1.3.3__py3-none-any.whl

aiecs/tools/search_tool/cache.py

@@ -0,0 +1,280 @@
+"""
+Intelligent Caching with Redis
+
+This module implements intelligent caching with intent-aware TTL strategies
+using Redis as the backend.
+"""
+
+import hashlib
+import json
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from .constants import QueryIntentType, CacheError
+
+logger = logging.getLogger(__name__)
+
+
+class IntelligentCache:
+    """Redis-based intelligent cache with intent-aware TTL"""
+    
+    # TTL strategies by intent type (in seconds)
+    TTL_STRATEGIES = {
+        QueryIntentType.DEFINITION.value: 86400 * 30,    # 30 days (rarely changes)
+        QueryIntentType.HOW_TO.value: 86400 * 7,         # 7 days
+        QueryIntentType.FACTUAL.value: 86400 * 7,        # 7 days
+        QueryIntentType.ACADEMIC.value: 86400 * 30,      # 30 days (papers don't change)
+        QueryIntentType.RECENT_NEWS.value: 3600,         # 1 hour (fast-changing)
+        QueryIntentType.PRODUCT.value: 86400,            # 1 day
+        QueryIntentType.COMPARISON.value: 86400 * 3,     # 3 days
+        QueryIntentType.GENERAL.value: 3600              # 1 hour default
+    }
+    
+    def __init__(self, redis_client: Optional[Any] = None, enabled: bool = True):
+        """
+        Initialize intelligent cache.
+        
+        Args:
+            redis_client: Redis client instance (optional)
+            enabled: Whether caching is enabled
+        """
+        self.redis_client = redis_client
+        self.enabled = enabled and redis_client is not None
+        self.cache_prefix = "search_tool:"
+        
+        if not self.enabled:
+            logger.info("Intelligent cache is disabled (no Redis client)")
+    
+    async def get(
+        self, 
+        query: str,
+        params: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Get cached search results.
+        
+        Args:
+            query: Search query
+            params: Search parameters
+            
+        Returns:
+            Cached results dictionary or None if not found
+        """
+        if not self.enabled:
+            return None
+        
+        try:
+            cache_key = self._generate_cache_key(query, params)
+            redis = await self.redis_client.get_client()
+            cached_data = await redis.get(cache_key)
+            
+            if cached_data:
+                logger.debug(f"Cache hit for query: {query}")
+                return json.loads(cached_data)
+            
+            logger.debug(f"Cache miss for query: {query}")
+            return None
+            
+        except Exception as e:
+            logger.warning(f"Cache get error: {e}")
+            return None
+    
+    async def set(
+        self,
+        query: str,
+        params: Dict[str, Any],
+        results: List[Dict[str, Any]],
+        intent_type: str = QueryIntentType.GENERAL.value,
+        metadata: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Cache search results with intelligent TTL.
+        
+        Args:
+            query: Search query
+            params: Search parameters
+            results: Search results to cache
+            intent_type: Query intent type for TTL calculation
+            metadata: Optional metadata about the search
+        """
+        if not self.enabled:
+            return
+        
+        try:
+            cache_key = self._generate_cache_key(query, params)
+            
+            # Calculate intelligent TTL
+            ttl = self.calculate_ttl(query, intent_type, results)
+            
+            # Prepare cache data
+            cache_data = {
+                'query': query,
+                'params': params,
+                'results': results,
+                'intent_type': intent_type,
+                'metadata': metadata or {},
+                'cached_at': datetime.utcnow().isoformat(),
+                'ttl': ttl
+            }
+            
+            # Store in Redis
+            redis = await self.redis_client.get_client()
+            await redis.set(
+                cache_key,
+                json.dumps(cache_data),
+                ex=ttl
+            )
+            
+            logger.debug(f"Cached results for query: {query} (TTL: {ttl}s)")
+            
+        except Exception as e:
+            logger.warning(f"Cache set error: {e}")
+    
+    def calculate_ttl(
+        self, 
+        query: str,
+        intent_type: str,
+        results: List[Dict[str, Any]]
+    ) -> int:
+        """
+        Calculate intelligent TTL based on intent and result quality.
+        
+        Args:
+            query: Search query
+            intent_type: Query intent type
+            results: Search results
+            
+        Returns:
+            TTL in seconds
+        """
+        # Base TTL from intent type
+        base_ttl = self.TTL_STRATEGIES.get(
+            intent_type, 
+            self.TTL_STRATEGIES[QueryIntentType.GENERAL.value]
+        )
+        
+        if not results:
+            # No results: shorter cache time
+            return base_ttl // 2
+        
+        # Adjust based on result freshness
+        try:
+            avg_freshness = sum(
+                r.get('_quality', {}).get('freshness_score', 0.5)
+                for r in results
+            ) / len(results)
+            
+            # Very fresh results can be cached longer
+            if avg_freshness > 0.9:
+                base_ttl = int(base_ttl * 2)
+            # Old results should have shorter cache
+            elif avg_freshness < 0.3:
+                base_ttl = base_ttl // 2
+        except Exception:
+            pass
+        
+        # Adjust based on result quality
+        try:
+            avg_quality = sum(
+                r.get('_quality', {}).get('quality_score', 0.5)
+                for r in results
+            ) / len(results)
+            
+            # High quality results can be cached longer
+            if avg_quality > 0.8:
+                base_ttl = int(base_ttl * 1.5)
+        except Exception:
+            pass
+        
+        return base_ttl
+    
+    async def invalidate(self, query: str, params: Dict[str, Any]):
+        """
+        Invalidate cached results.
+        
+        Args:
+            query: Search query
+            params: Search parameters
+        """
+        if not self.enabled:
+            return
+        
+        try:
+            cache_key = self._generate_cache_key(query, params)
+            redis = await self.redis_client.get_client()
+            await redis.delete(cache_key)
+            logger.debug(f"Invalidated cache for query: {query}")
+        except Exception as e:
+            logger.warning(f"Cache invalidate error: {e}")
+    
+    async def clear_all(self):
+        """Clear all cached search results"""
+        if not self.enabled:
+            return
+        
+        try:
+            redis = await self.redis_client.get_client()
+            # Find all search_tool cache keys
+            pattern = f"{self.cache_prefix}*"
+            keys = []
+            async for key in redis.scan_iter(match=pattern):
+                keys.append(key)
+            
+            if keys:
+                await redis.delete(*keys)
+                logger.info(f"Cleared {len(keys)} cached entries")
+        except Exception as e:
+            logger.warning(f"Cache clear error: {e}")
+    
+    def _generate_cache_key(self, query: str, params: Dict[str, Any]) -> str:
+        """
+        Generate unique cache key from query and parameters.
+        
+        Args:
+            query: Search query
+            params: Search parameters
+            
+        Returns:
+            Cache key string
+        """
+        # Create deterministic string from query and params
+        param_str = json.dumps(params, sort_keys=True)
+        key_data = f"{query}:{param_str}"
+        key_hash = hashlib.sha256(key_data.encode()).hexdigest()[:16]
+        
+        return f"{self.cache_prefix}{key_hash}"
+    
+    async def get_stats(self) -> Dict[str, Any]:
+        """
+        Get cache statistics.
+        
+        Returns:
+            Cache statistics dictionary
+        """
+        if not self.enabled:
+            return {
+                'enabled': False,
+                'total_keys': 0
+            }
+        
+        try:
+            redis = await self.redis_client.get_client()
+            # Count cache keys
+            pattern = f"{self.cache_prefix}*"
+            key_count = 0
+            async for _ in redis.scan_iter(match=pattern):
+                key_count += 1
+            
+            return {
+                'enabled': True,
+                'total_keys': key_count,
+                'prefix': self.cache_prefix
+            }
+        except Exception as e:
+            logger.warning(f"Cache stats error: {e}")
+            return {
+                'enabled': True,
+                'error': str(e)
+            }
+

aiecs/tools/search_tool/constants.py

@@ -0,0 +1,127 @@
+"""
+Constants, Enums, and Exception Classes for Search Tool
+
+This module contains all the shared constants, enumeration types, and
+custom exception classes used across the search tool package.
+"""
+
+from enum import Enum
+
+
+# ============================================================================
+# Enums
+# ============================================================================
+
+class SearchType(str, Enum):
+    """Supported search types"""
+    WEB = "web"
+    IMAGE = "image"
+    NEWS = "news"
+    VIDEO = "video"
+
+
+class SafeSearch(str, Enum):
+    """Safe search levels"""
+    OFF = "off"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class ImageSize(str, Enum):
+    """Image size filters"""
+    ICON = "icon"
+    SMALL = "small"
+    MEDIUM = "medium"
+    LARGE = "large"
+    XLARGE = "xlarge"
+    XXLARGE = "xxlarge"
+    HUGE = "huge"
+
+
+class ImageType(str, Enum):
+    """Image type filters"""
+    CLIPART = "clipart"
+    FACE = "face"
+    LINEART = "lineart"
+    STOCK = "stock"
+    PHOTO = "photo"
+    ANIMATED = "animated"
+
+
+class ImageColorType(str, Enum):
+    """Image color type filters"""
+    COLOR = "color"
+    GRAY = "gray"
+    MONO = "mono"
+    TRANS = "trans"
+
+
+class CircuitState(str, Enum):
+    """Circuit breaker states"""
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+class QueryIntentType(str, Enum):
+    """Query intent types"""
+    DEFINITION = "definition"
+    HOW_TO = "how_to"
+    COMPARISON = "comparison"
+    FACTUAL = "factual"
+    RECENT_NEWS = "recent_news"
+    ACADEMIC = "academic"
+    PRODUCT = "product"
+    GENERAL = "general"
+
+
+class CredibilityLevel(str, Enum):
+    """Result credibility levels"""
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+# ============================================================================
+# Exception Hierarchy
+# ============================================================================
+
+class SearchToolError(Exception):
+    """Base exception for SearchTool errors"""
+    pass
+
+
+class AuthenticationError(SearchToolError):
+    """Authentication-related errors"""
+    pass
+
+
+class QuotaExceededError(SearchToolError):
+    """API quota exceeded"""
+    pass
+
+
+class RateLimitError(SearchToolError):
+    """Rate limit exceeded"""
+    pass
+
+
+class CircuitBreakerOpenError(SearchToolError):
+    """Circuit breaker is open"""
+    pass
+
+
+class SearchAPIError(SearchToolError):
+    """Search API errors"""
+    pass
+
+
+class ValidationError(SearchToolError):
+    """Input validation errors"""
+    pass
+
+
+class CacheError(SearchToolError):
+    """Cache-related errors"""
+    pass
+

aiecs/tools/search_tool/context.py

@@ -0,0 +1,219 @@
+"""
+Search Context Management
+
+This module tracks search history, learns user preferences, and provides
+contextual suggestions for better search results.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Set
+
+
+class SearchContext:
+    """Manages search history and context for improved results"""
+    
+    def __init__(self, max_history: int = 10):
+        """
+        Initialize search context.
+        
+        Args:
+            max_history: Maximum number of searches to keep in history
+        """
+        self.search_history: List[Dict[str, Any]] = []
+        self.max_history = max_history
+        self.topic_context: Optional[List[str]] = None
+        self.user_preferences = {
+            'preferred_domains': set(),
+            'avoided_domains': set(),
+            'preferred_content_types': [],
+            'language': 'en'
+        }
+    
+    def add_search(
+        self, 
+        query: str, 
+        results: List[Dict[str, Any]],
+        user_feedback: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Add search to history and update context.
+        
+        Args:
+            query: Search query
+            results: Search results
+            user_feedback: Optional user feedback for learning
+        """
+        search_record = {
+            'timestamp': datetime.utcnow().isoformat(),
+            'query': query,
+            'result_count': len(results),
+            'clicked_results': [],
+            'feedback': user_feedback
+        }
+        
+        self.search_history.append(search_record)
+        
+        # Maintain history size limit
+        if len(self.search_history) > self.max_history:
+            self.search_history.pop(0)
+        
+        # Update topic context
+        self._update_topic_context(query, results)
+        
+        # Learn from feedback if provided
+        if user_feedback:
+            self._learn_preferences(results, user_feedback)
+    
+    def get_contextual_suggestions(self, current_query: str) -> Dict[str, Any]:
+        """
+        Generate context-aware suggestions for the current query.
+        
+        Args:
+            current_query: Current search query
+            
+        Returns:
+            Suggestions dictionary with related queries and parameters
+        """
+        suggestions = {
+            'related_queries': [],
+            'refinement_suggestions': [],
+            'context_aware_params': {}
+        }
+        
+        if not self.search_history:
+            return suggestions
+        
+        # Find related historical queries
+        for record in reversed(self.search_history[-5:]):
+            prev_query = record['query']
+            similarity = self._calculate_query_similarity(current_query, prev_query)
+            
+            if similarity > 0.5:
+                suggestions['related_queries'].append({
+                    'query': prev_query,
+                    'similarity': similarity,
+                    'timestamp': record['timestamp']
+                })
+        
+        # Suggest preferred sites if available
+        if self.user_preferences['preferred_domains']:
+            suggestions['context_aware_params']['preferred_sites'] = list(
+                self.user_preferences['preferred_domains']
+            )
+        
+        return suggestions
+    
+    def get_history(self, limit: Optional[int] = None) -> List[Dict[str, Any]]:
+        """
+        Get search history.
+        
+        Args:
+            limit: Maximum number of records to return
+            
+        Returns:
+            List of search history records
+        """
+        if limit:
+            return self.search_history[-limit:]
+        return self.search_history.copy()
+    
+    def clear_history(self):
+        """Clear search history"""
+        self.search_history.clear()
+        self.topic_context = None
+    
+    def get_preferences(self) -> Dict[str, Any]:
+        """
+        Get current user preferences.
+        
+        Returns:
+            User preferences dictionary
+        """
+        return {
+            'preferred_domains': list(self.user_preferences['preferred_domains']),
+            'avoided_domains': list(self.user_preferences['avoided_domains']),
+            'preferred_content_types': self.user_preferences['preferred_content_types'].copy(),
+            'language': self.user_preferences['language']
+        }
+    
+    def set_preference(self, key: str, value: Any):
+        """
+        Set a user preference.
+        
+        Args:
+            key: Preference key
+            value: Preference value
+        """
+        if key in self.user_preferences:
+            if isinstance(self.user_preferences[key], set):
+                if isinstance(value, (list, set)):
+                    self.user_preferences[key] = set(value)
+                else:
+                    self.user_preferences[key].add(value)
+            else:
+                self.user_preferences[key] = value
+    
+    def _update_topic_context(self, query: str, results: List[Dict[str, Any]]):
+        """
+        Update topic context from query and results.
+        
+        Args:
+            query: Search query
+            results: Search results
+        """
+        # Simple implementation: extract common words
+        words = query.lower().split()
+        self.topic_context = words
+    
+    def _learn_preferences(
+        self, 
+        results: List[Dict[str, Any]], 
+        feedback: Dict[str, Any]
+    ):
+        """
+        Learn user preferences from feedback.
+        
+        Args:
+            results: Search results
+            feedback: User feedback
+        """
+        # Learn from clicked/used results
+        if 'clicked_indices' in feedback:
+            for idx in feedback['clicked_indices']:
+                if 0 <= idx < len(results):
+                    result = results[idx]
+                    domain = result.get('displayLink', '')
+                    if domain:
+                        self.user_preferences['preferred_domains'].add(domain)
+        
+        # Learn from disliked results
+        if 'disliked_indices' in feedback:
+            for idx in feedback['disliked_indices']:
+                if 0 <= idx < len(results):
+                    result = results[idx]
+                    domain = result.get('displayLink', '')
+                    if domain:
+                        self.user_preferences['avoided_domains'].add(domain)
+    
+    def _calculate_query_similarity(self, query1: str, query2: str) -> float:
+        """
+        Calculate similarity between two queries using Jaccard index.
+        
+        Args:
+            query1: First query
+            query2: Second query
+            
+        Returns:
+            Similarity score (0-1)
+        """
+        words1 = set(query1.lower().split())
+        words2 = set(query2.lower().split())
+        
+        if not words1 or not words2:
+            return 0.0
+        
+        intersection = words1 & words2
+        union = words1 | words2
+        
+        return len(intersection) / len(union) if union else 0.0
+