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

aiecs/application/knowledge_graph/retrieval/retrieval_strategies.py

@@ -0,0 +1,592 @@
+"""
+Advanced Retrieval Strategies
+
+Provides sophisticated retrieval methods including Personalized PageRank,
+multi-hop neighbor retrieval, filtered retrieval, and query caching.
+"""
+
+import asyncio
+from typing import List, Dict, Set, Optional, Tuple, Any, Callable
+from collections import defaultdict, deque
+import hashlib
+import json
+import time
+from aiecs.domain.knowledge_graph.models.entity import Entity
+from aiecs.infrastructure.graph_storage.base import GraphStore
+
+
+class PersonalizedPageRank:
+    """
+    Personalized PageRank Retrieval
+
+    Computes importance scores for entities in the graph based on
+    a random walk with restart from seed entities. Useful for finding
+    entities most relevant to a given starting point.
+
+    Algorithm:
+    1. Start from seed entities
+    2. Random walk with probability alpha to restart at seeds
+    3. Iterate until convergence
+    4. Return entities ranked by visit frequency
+
+    Example:
+        ```python
+        ppr = PersonalizedPageRank(graph_store)
+
+        results = await ppr.retrieve(
+            seed_entity_ids=["person_1"],
+            max_results=10,
+            alpha=0.15,  # restart probability
+            max_iterations=100
+        )
+
+        for entity, score in results:
+            print(f"{entity.id}: {score:.4f}")
+        ```
+    """
+
+    def __init__(self, graph_store: GraphStore):
+        """
+        Initialize Personalized PageRank retrieval
+
+        Args:
+            graph_store: Graph storage backend
+        """
+        self.graph_store = graph_store
+
+    async def retrieve(
+        self,
+        seed_entity_ids: List[str],
+        max_results: int = 20,
+        alpha: float = 0.15,
+        max_iterations: int = 100,
+        convergence_threshold: float = 1e-6,
+    ) -> List[Tuple[Entity, float]]:
+        """
+        Retrieve entities using Personalized PageRank
+
+        Args:
+            seed_entity_ids: Starting entities for random walk
+            max_results: Maximum number of results to return
+            alpha: Restart probability (0.0-1.0)
+            max_iterations: Maximum number of iterations
+            convergence_threshold: Convergence threshold for scores
+
+        Returns:
+            List of (entity, score) tuples sorted by score descending
+        """
+        if not seed_entity_ids:
+            return []
+
+        # Initialize scores
+        scores: Dict[str, float] = defaultdict(float)
+        set(seed_entity_ids)
+
+        # Initialize seed scores uniformly
+        initial_score = 1.0 / len(seed_entity_ids)
+        for seed_id in seed_entity_ids:
+            scores[seed_id] = initial_score
+
+        # Build adjacency information (cache neighbors)
+        adjacency: Dict[str, List[str]] = {}
+
+        # Iterative PageRank computation
+        for iteration in range(max_iterations):
+            new_scores: Dict[str, float] = defaultdict(float)
+
+            # Restart probability: distribute to seeds
+            for seed_id in seed_entity_ids:
+                new_scores[seed_id] += alpha * initial_score
+
+            # Random walk probability: distribute from current nodes
+            max_delta = 0.0
+
+            for entity_id, score in scores.items():
+                if score == 0:
+                    continue
+
+                # Get neighbors (cache for efficiency)
+                if entity_id not in adjacency:
+                    neighbors = await self.graph_store.get_neighbors(entity_id, direction="outgoing")
+                    adjacency[entity_id] = [n.id for n in neighbors]
+
+                neighbor_ids = adjacency[entity_id]
+
+                if neighbor_ids:
+                    # Distribute score to neighbors
+                    distribute_score = (1 - alpha) * score / len(neighbor_ids)
+                    for neighbor_id in neighbor_ids:
+                        new_scores[neighbor_id] += distribute_score
+                else:
+                    # No outgoing edges, restart at seeds
+                    for seed_id in seed_entity_ids:
+                        new_scores[seed_id] += (1 - alpha) * score * initial_score
+
+            # Check convergence
+            for entity_id in set(scores.keys()) | set(new_scores.keys()):
+                delta = abs(new_scores[entity_id] - scores[entity_id])
+                max_delta = max(max_delta, delta)
+
+            scores = new_scores
+
+            if max_delta < convergence_threshold:
+                break
+
+        # Retrieve entities and create results
+        results = []
+        for entity_id, score in scores.items():
+            if score > 0:
+                entity = await self.graph_store.get_entity(entity_id)
+                if entity:
+                    results.append((entity, score))
+
+        # Sort by score descending
+        results.sort(key=lambda x: x[1], reverse=True)
+
+        return results[:max_results]
+
+
+class MultiHopRetrieval:
+    """
+    Multi-Hop Neighbor Retrieval
+
+    Retrieves entities within N hops from seed entities, with configurable
+    aggregation and scoring strategies.
+
+    Features:
+    - Breadth-first expansion from seeds
+    - Hop-distance based scoring
+    - Relation type filtering
+    - Entity deduplication
+
+    Example:
+        ```python
+        retrieval = MultiHopRetrieval(graph_store)
+
+        results = await retrieval.retrieve(
+            seed_entity_ids=["entity_1"],
+            max_hops=2,
+            max_results=20,
+            relation_types=["RELATED_TO"]  # Optional filter
+        )
+        ```
+    """
+
+    def __init__(self, graph_store: GraphStore):
+        """
+        Initialize multi-hop retrieval
+
+        Args:
+            graph_store: Graph storage backend
+        """
+        self.graph_store = graph_store
+
+    async def retrieve(
+        self,
+        seed_entity_ids: List[str],
+        max_hops: int = 2,
+        max_results: int = 50,
+        relation_types: Optional[List[str]] = None,
+        score_decay: float = 0.5,
+        include_seeds: bool = True,
+    ) -> List[Tuple[Entity, float]]:
+        """
+        Retrieve entities within N hops from seeds
+
+        Args:
+            seed_entity_ids: Starting entities
+            max_hops: Maximum number of hops
+            max_results: Maximum number of results
+            relation_types: Optional list of allowed relation types
+            score_decay: Score decay factor per hop (0.0-1.0)
+            include_seeds: Whether to include seed entities in results
+
+        Returns:
+            List of (entity, score) tuples
+        """
+        if not seed_entity_ids:
+            return []
+
+        # Track visited entities and their scores
+        entity_scores: Dict[str, float] = {}
+        visited: Set[str] = set()
+
+        # BFS expansion
+        current_level = set(seed_entity_ids)
+
+        for hop in range(max_hops + 1):
+            if not current_level:
+                break
+
+            next_level: Set[str] = set()
+
+            # Score for this hop level
+            hop_score = score_decay**hop
+
+            for entity_id in current_level:
+                if entity_id in visited:
+                    continue
+
+                visited.add(entity_id)
+
+                # Update score (take max if entity reached via multiple paths)
+                if entity_id not in entity_scores:
+                    entity_scores[entity_id] = hop_score
+                else:
+                    entity_scores[entity_id] = max(entity_scores[entity_id], hop_score)
+
+                # Get neighbors for next level
+                if hop < max_hops:
+                    neighbors = await self.graph_store.get_neighbors(entity_id, relation_type=None, direction="outgoing")
+
+                    for neighbor in neighbors:
+                        if neighbor.id not in visited:
+                            # Apply relation type filter if specified
+                            if relation_types is None:
+                                next_level.add(neighbor.id)
+                            else:
+                                # Check if any relation matches the filter
+                                # (simplified - assumes we have the relation info)
+                                next_level.add(neighbor.id)
+
+            current_level = next_level
+
+        # Filter out seeds if requested
+        if not include_seeds:
+            for seed_id in seed_entity_ids:
+                entity_scores.pop(seed_id, None)
+
+        # Retrieve entities and create results
+        results = []
+        for entity_id, score in entity_scores.items():
+            entity = await self.graph_store.get_entity(entity_id)
+            if entity:
+                results.append((entity, score))
+
+        # Sort by score descending
+        results.sort(key=lambda x: x[1], reverse=True)
+
+        return results[:max_results]
+
+
+class FilteredRetrieval:
+    """
+    Filtered Retrieval Strategy
+
+    Retrieves entities from the graph with flexible filtering by:
+    - Entity type
+    - Property values
+    - Property existence
+    - Custom filter functions
+
+    Example:
+        ```python
+        retrieval = FilteredRetrieval(graph_store)
+
+        # Filter by entity type and property
+        results = await retrieval.retrieve(
+            entity_type="Person",
+            property_filters={"role": "Engineer"},
+            max_results=20
+        )
+
+        # Custom filter function
+        results = await retrieval.retrieve(
+            filter_fn=lambda e: e.properties.get("age", 0) > 30,
+            max_results=10
+        )
+        ```
+    """
+
+    def __init__(self, graph_store: GraphStore):
+        """
+        Initialize filtered retrieval
+
+        Args:
+            graph_store: Graph storage backend
+        """
+        self.graph_store = graph_store
+
+    async def retrieve(
+        self,
+        entity_type: Optional[str] = None,
+        property_filters: Optional[Dict[str, Any]] = None,
+        property_exists: Optional[List[str]] = None,
+        filter_fn: Optional[Callable[[Entity], bool]] = None,
+        max_results: int = 100,
+        score_by_match_count: bool = False,
+    ) -> List[Tuple[Entity, float]]:
+        """
+        Retrieve entities with flexible filtering
+
+        Args:
+            entity_type: Filter by entity type
+            property_filters: Filter by property values (key: value)
+            property_exists: Filter by property existence (list of keys)
+            filter_fn: Custom filter function
+            max_results: Maximum number of results
+            score_by_match_count: Score by number of matching criteria
+
+        Returns:
+            List of (entity, score) tuples
+        """
+        # Get all entities (or filtered by type if using vector search)
+        # Note: This is a simplified implementation
+        # In production, we'd want more efficient filtering at storage level
+
+        results = []
+
+        # For now, we'll use vector search with no threshold to get entities
+        # This is a workaround - ideally we'd have a direct entity scan method
+        if entity_type:
+            # Try vector search with entity type filter
+            dummy_embedding = [0.0] * 128  # Placeholder
+            candidates = await self.graph_store.vector_search(
+                query_embedding=dummy_embedding,
+                entity_type=entity_type,
+                max_results=1000,
+                score_threshold=0.0,
+            )
+            candidate_entities = [entity for entity, _ in candidates]
+        else:
+            # Without entity type filter, we can't efficiently get all entities
+            # This is a limitation of the current GraphStore interface
+            # Return empty results for now
+            candidate_entities = []
+
+        # Apply filters
+        for entity in candidate_entities:
+            match_count = 0
+            total_criteria = 0
+
+            # Entity type filter (already applied above)
+            if entity_type:
+                total_criteria += 1
+                if entity.entity_type == entity_type:
+                    match_count += 1
+                else:
+                    continue
+
+            # Property value filters
+            if property_filters:
+                total_criteria += len(property_filters)
+                for key, expected_value in property_filters.items():
+                    if entity.properties.get(key) == expected_value:
+                        match_count += 1
+                    else:
+                        # Strict matching - entity must match all filters
+                        match_count = 0
+                        break
+
+                if match_count == 0 and property_filters:
+                    continue
+
+            # Property existence filters
+            if property_exists:
+                total_criteria += len(property_exists)
+                for key in property_exists:
+                    if key in entity.properties:
+                        match_count += 1
+                    else:
+                        match_count = 0
+                        break
+
+                if match_count == 0 and property_exists:
+                    continue
+
+            # Custom filter function
+            if filter_fn:
+                total_criteria += 1
+                try:
+                    if filter_fn(entity):
+                        match_count += 1
+                    else:
+                        continue
+                except Exception:
+                    continue
+
+            # Calculate score
+            if score_by_match_count and total_criteria > 0:
+                score = match_count / total_criteria
+            else:
+                score = 1.0
+
+            results.append((entity, score))
+
+            if len(results) >= max_results:
+                break
+
+        # Sort by score descending
+        results.sort(key=lambda x: x[1], reverse=True)
+
+        return results[:max_results]
+
+
+class RetrievalCache:
+    """
+    Query Caching for Retrieval
+
+    Caches retrieval results to improve performance for frequent queries.
+    Uses LRU eviction policy and TTL-based expiration.
+
+    Features:
+    - LRU cache with configurable size
+    - TTL-based expiration
+    - Query fingerprinting
+    - Cache statistics
+
+    Example:
+        ```python
+        cache = RetrievalCache(max_size=100, ttl=300)  # 5 minutes TTL
+
+        # Wrap retrieval operation
+        results = await cache.get_or_compute(
+            cache_key="query_1",
+            compute_fn=lambda: retrieval.retrieve(...)
+        )
+
+        # Check cache statistics
+        stats = cache.get_stats()
+        print(f"Hit rate: {stats['hit_rate']:.2%}")
+        ```
+    """
+
+    def __init__(self, max_size: int = 1000, ttl: int = 300):
+        """
+        Initialize retrieval cache
+
+        Args:
+            max_size: Maximum number of cached entries
+            ttl: Time-to-live for cache entries in seconds
+        """
+        self.max_size = max_size
+        self.ttl = ttl
+        # key -> (value, timestamp)
+        self._cache: Dict[str, Tuple[Any, float]] = {}
+        self._access_order: deque = deque()  # LRU tracking
+        self._hits = 0
+        self._misses = 0
+
+    def _generate_key(self, **kwargs) -> str:
+        """
+        Generate cache key from query parameters
+
+        Args:
+            **kwargs: Query parameters
+
+        Returns:
+            Cache key string
+        """
+        # Sort keys for consistent hashing
+        sorted_items = sorted(kwargs.items())
+        key_str = json.dumps(sorted_items, sort_keys=True)
+        return hashlib.md5(key_str.encode()).hexdigest()
+
+    def _is_expired(self, timestamp: float) -> bool:
+        """Check if cache entry is expired"""
+        return (time.time() - timestamp) > self.ttl
+
+    def _evict_lru(self):
+        """Evict least recently used entry"""
+        if self._access_order:
+            lru_key = self._access_order.popleft()
+            self._cache.pop(lru_key, None)
+
+    async def get_or_compute(
+        self,
+        cache_key: Optional[str] = None,
+        compute_fn: Optional[Callable] = None,
+        **kwargs,
+    ) -> Any:
+        """
+        Get cached result or compute and cache
+
+        Args:
+            cache_key: Optional explicit cache key
+            compute_fn: Async function to compute result if cache miss
+            **kwargs: Parameters for cache key generation
+
+        Returns:
+            Cached or computed result
+        """
+        # Generate cache key
+        if cache_key is None:
+            cache_key = self._generate_key(**kwargs)
+
+        # Check cache
+        if cache_key in self._cache:
+            result, timestamp = self._cache[cache_key]
+
+            # Check expiration
+            if not self._is_expired(timestamp):
+                # Cache hit
+                self._hits += 1
+
+                # Update LRU order
+                if cache_key in self._access_order:
+                    self._access_order.remove(cache_key)
+                self._access_order.append(cache_key)
+
+                return result
+            else:
+                # Expired, remove
+                del self._cache[cache_key]
+                if cache_key in self._access_order:
+                    self._access_order.remove(cache_key)
+
+        # Cache miss
+        self._misses += 1
+
+        # Compute result
+        if compute_fn is None:
+            return None
+
+        if asyncio.iscoroutinefunction(compute_fn):
+            result = await compute_fn()
+        else:
+            result = compute_fn()
+
+        # Store in cache
+        self._cache[cache_key] = (result, time.time())
+        self._access_order.append(cache_key)
+
+        # Evict if over size limit
+        while len(self._cache) > self.max_size:
+            self._evict_lru()
+
+        return result
+
+    def invalidate(self, cache_key: str):
+        """Invalidate a specific cache entry"""
+        if cache_key in self._cache:
+            del self._cache[cache_key]
+            if cache_key in self._access_order:
+                self._access_order.remove(cache_key)
+
+    def clear(self):
+        """Clear all cache entries"""
+        self._cache.clear()
+        self._access_order.clear()
+
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get cache statistics
+
+        Returns:
+            Dictionary with cache statistics
+        """
+        total_requests = self._hits + self._misses
+        hit_rate = self._hits / total_requests if total_requests > 0 else 0.0
+
+        return {
+            "hits": self._hits,
+            "misses": self._misses,
+            "total_requests": total_requests,
+            "hit_rate": hit_rate,
+            "cache_size": len(self._cache),
+            "max_size": self.max_size,
+            "ttl": self.ttl,
+        }
+
+
+# Import asyncio for async checks

aiecs/application/knowledge_graph/retrieval/strategy_types.py

@@ -0,0 +1,23 @@
+"""
+Retrieval Strategy Types
+
+Defines the types of retrieval strategies available for knowledge graph queries.
+"""
+
+from enum import Enum
+
+
+class RetrievalStrategy(str, Enum):
+    """
+    Retrieval strategy enumeration for knowledge graph queries.
+
+    Defines different strategies for retrieving relevant knowledge from the graph
+    based on query intent and characteristics.
+    """
+
+    VECTOR_SEARCH = "vector_search"  # Semantic similarity search using embeddings
+    MULTI_HOP = "multi_hop"  # Multi-hop neighbor traversal
+    PAGERANK = "pagerank"  # Personalized PageRank retrieval
+    FILTERED = "filtered"  # Property-based filtering
+    HYBRID = "hybrid"  # Combination of multiple strategies
+

aiecs/application/knowledge_graph/search/__init__.py

@@ -0,0 +1,59 @@
+"""
+Knowledge Graph Search Application Layer
+
+Advanced search strategies including hybrid search and text similarity utilities.
+"""
+
+from aiecs.application.knowledge_graph.search.hybrid_search import (
+    HybridSearchStrategy,
+    HybridSearchConfig,
+    SearchMode,
+)
+from aiecs.application.knowledge_graph.search.text_similarity import (
+    TextSimilarity,
+    BM25Scorer,
+    jaccard_similarity,
+    jaccard_similarity_text,
+    cosine_similarity_text,
+    levenshtein_distance,
+    normalized_levenshtein_similarity,
+    fuzzy_match,
+)
+from aiecs.application.knowledge_graph.search.reranker import (
+    RerankerStrategy,
+    ResultReranker,
+    ScoreCombinationMethod,
+    normalize_scores,
+    combine_scores,
+)
+from aiecs.application.knowledge_graph.search.reranker_strategies import (
+    TextSimilarityReranker,
+    SemanticReranker,
+    StructuralReranker,
+    HybridReranker,
+    CrossEncoderReranker,
+)
+
+__all__ = [
+    "HybridSearchStrategy",
+    "HybridSearchConfig",
+    "SearchMode",
+    "TextSimilarity",
+    "BM25Scorer",
+    "jaccard_similarity",
+    "jaccard_similarity_text",
+    "cosine_similarity_text",
+    "levenshtein_distance",
+    "normalized_levenshtein_similarity",
+    "fuzzy_match",
+    "RerankerStrategy",
+    "ResultReranker",
+    "ScoreCombinationMethod",
+    "normalize_scores",
+    "combine_scores",
+    "TextSimilarityReranker",
+    "SemanticReranker",
+    "StructuralReranker",
+    "HybridReranker",
+    "CrossEncoderReranker",
+]