aiecs 1.0.1__py3-none-any.whl → 1.7.17__py3-none-any.whl

aiecs/tools/search_tool/cache.py

@@ -0,0 +1,264 @@
+"""
+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
+
+logger = logging.getLogger(__name__)
+
+
+class IntelligentCache:
+    """Redis-based intelligent cache with intent-aware TTL"""
+
+    # TTL strategies by intent type (in seconds)
+    TTL_STRATEGIES = {
+        # 30 days (rarely changes)
+        QueryIntentType.DEFINITION.value: 86400 * 30,
+        QueryIntentType.HOW_TO.value: 86400 * 7,  # 7 days
+        QueryIntentType.FACTUAL.value: 86400 * 7,  # 7 days
+        # 30 days (papers don't change)
+        QueryIntentType.ACADEMIC.value: 86400 * 30,
+        # 1 hour (fast-changing)
+        QueryIntentType.RECENT_NEWS.value: 3600,
+        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:
+            if self.redis_client is None:
+                return None
+            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
+            if self.redis_client is None:
+                return
+            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:
+            if self.redis_client is None:
+                return
+            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:
+            if self.redis_client is None:
+                return
+            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:
+            if self.redis_client is None:
+                return {"enabled": False, "total_keys": 0}
+            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,128 @@
+"""
+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"""
+
+
+class AuthenticationError(SearchToolError):
+    """Authentication-related errors"""
+
+
+class QuotaExceededError(SearchToolError):
+    """API quota exceeded"""
+
+
+class RateLimitError(SearchToolError):
+    """Rate limit exceeded"""
+
+
+class CircuitBreakerOpenError(SearchToolError):
+    """Circuit breaker is open"""
+
+
+class SearchAPIError(SearchToolError):
+    """Search API errors"""
+
+
+class ValidationError(SearchToolError):
+    """Input validation errors"""
+
+
+class CacheError(SearchToolError):
+    """Cache-related errors"""

aiecs/tools/search_tool/context.py

@@ -0,0 +1,224 @@
+"""
+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, cast
+
+
+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: Dict[str, Any] = {
+            "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: Dict[str, Any] = {
+            "related_queries": [],
+            "refinement_suggestions": [],
+            "context_aware_params": {},
+        }
+
+        if not self.search_history:
+            return suggestions
+
+        # Find related historical queries
+        related_queries = cast(List[Dict[str, Any]], suggestions["related_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:
+                related_queries.append(
+                    {
+                        "query": prev_query,
+                        "similarity": similarity,
+                        "timestamp": record["timestamp"],
+                    }
+                )
+
+        # Suggest preferred sites if available
+        preferred_domains = cast(Set[str], self.user_preferences["preferred_domains"])
+        if preferred_domains:
+            context_aware_params = cast(Dict[str, Any], suggestions["context_aware_params"])
+            context_aware_params["preferred_sites"] = list(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
+        """
+        preferred_domains = cast(Set[str], self.user_preferences["preferred_domains"])
+        avoided_domains = cast(Set[str], self.user_preferences["avoided_domains"])
+        preferred_content_types = cast(List[str], self.user_preferences["preferred_content_types"])
+        return {
+            "preferred_domains": list(preferred_domains),
+            "avoided_domains": list(avoided_domains),
+            "preferred_content_types": 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:
+            pref_value = self.user_preferences[key]
+            if isinstance(pref_value, set):
+                if isinstance(value, (list, set)):
+                    self.user_preferences[key] = set(value)
+                else:
+                    pref_set = cast(Set[str], pref_value)
+                    pref_set.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
+        preferred_domains = cast(Set[str], self.user_preferences["preferred_domains"])
+        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:
+                        preferred_domains.add(domain)
+
+        # Learn from disliked results
+        avoided_domains = cast(Set[str], self.user_preferences["avoided_domains"])
+        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:
+                        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