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

aiecs/application/knowledge_graph/pattern_matching/pattern_matcher.py

@@ -0,0 +1,342 @@
+"""
+Pattern Matching Engine
+
+Implements graph pattern matching for custom query execution.
+
+Phase: 3.3 - Full Custom Query Execution
+Version: 1.0
+"""
+
+from typing import List, Dict, Any, Optional
+from aiecs.domain.knowledge_graph.models.entity import Entity
+from aiecs.domain.knowledge_graph.models.relation import Relation
+from aiecs.domain.knowledge_graph.models.path import Path
+from aiecs.domain.knowledge_graph.models.path_pattern import PathPattern
+from aiecs.infrastructure.graph_storage.base import GraphStore
+
+
+class PatternMatch:
+    """
+    Represents a single pattern match result
+
+    Attributes:
+        entities: Matched entities
+        relations: Matched relations
+        bindings: Variable bindings (if pattern uses variables)
+        score: Match score (0.0-1.0)
+    """
+
+    def __init__(
+        self,
+        entities: List[Entity],
+        relations: List[Relation],
+        bindings: Optional[Dict[str, Any]] = None,
+        score: float = 1.0,
+    ):
+        self.entities = entities
+        self.relations = relations
+        self.bindings = bindings or {}
+        self.score = score
+
+    def __repr__(self) -> str:
+        return f"PatternMatch(entities={len(self.entities)}, relations={len(self.relations)}, score={self.score})"
+
+
+class PatternMatcher:
+    """
+    Graph Pattern Matching Engine
+
+    Executes pattern matching queries against a graph store.
+    Supports:
+    - Single pattern matching
+    - Multiple pattern matching (AND semantics)
+    - Optional pattern matching
+    - Cycle detection and handling
+    - Result projection and aggregation
+    """
+
+    def __init__(self, graph_store: GraphStore):
+        """
+        Initialize pattern matcher
+
+        Args:
+            graph_store: Graph storage backend
+        """
+        self.graph_store = graph_store
+
+    async def match_pattern(
+        self,
+        pattern: PathPattern,
+        start_entity_id: Optional[str] = None,
+        max_matches: int = 100,
+    ) -> List[PatternMatch]:
+        """
+        Match a single pattern in the graph
+
+        Args:
+            pattern: Pattern to match
+            start_entity_id: Optional starting entity ID
+            max_matches: Maximum number of matches to return
+
+        Returns:
+            List of pattern matches
+        """
+        matches = []
+
+        if start_entity_id:
+            # Start from specific entity
+            start_entity = await self.graph_store.get_entity(start_entity_id)
+            if not start_entity:
+                return []
+
+            # Find paths matching the pattern
+            paths = await self._find_matching_paths(start_entity, pattern, max_matches)
+
+            for path in paths:
+                match = PatternMatch(entities=path.nodes, relations=path.edges, score=1.0)
+                matches.append(match)
+        else:
+            # Find all entities matching the pattern
+            # This is more expensive - iterate through all entities
+            all_entities = await self._get_all_entities(pattern.entity_types)
+
+            for entity in all_entities[:max_matches]:
+                paths = await self._find_matching_paths(entity, pattern, max_matches=1)
+
+                if paths:
+                    match = PatternMatch(
+                        entities=paths[0].nodes,
+                        relations=paths[0].edges,
+                        score=1.0,
+                    )
+                    matches.append(match)
+
+                    if len(matches) >= max_matches:
+                        break
+
+        return matches
+
+    async def match_multiple_patterns(
+        self,
+        patterns: List[PathPattern],
+        start_entity_id: Optional[str] = None,
+        max_matches: int = 100,
+    ) -> List[PatternMatch]:
+        """
+        Match multiple patterns (AND semantics)
+
+        All patterns must match for a result to be included.
+
+        Args:
+            patterns: List of patterns to match
+            start_entity_id: Optional starting entity ID
+            max_matches: Maximum number of matches to return
+
+        Returns:
+            List of pattern matches where all patterns matched
+        """
+        if not patterns:
+            return []
+
+        # Match first pattern
+        first_matches = await self.match_pattern(patterns[0], start_entity_id, max_matches)
+
+        if len(patterns) == 1:
+            return first_matches
+
+        # Filter matches that also match remaining patterns
+        combined_matches = []
+
+        for match in first_matches:
+            # Check if remaining patterns match
+            all_match = True
+            combined_entities = list(match.entities)
+            combined_relations = list(match.relations)
+
+            for pattern in patterns[1:]:
+                # Try to match pattern starting from any entity in current
+                # match
+                pattern_matched = False
+
+                for entity in match.entities:
+                    sub_matches = await self.match_pattern(pattern, entity.id, max_matches=1)
+
+                    if sub_matches:
+                        # Add new entities and relations
+                        for sub_match in sub_matches:
+                            combined_entities.extend(sub_match.entities)
+                            combined_relations.extend(sub_match.relations)
+                        pattern_matched = True
+                        break
+
+                if not pattern_matched:
+                    all_match = False
+                    break
+
+            if all_match:
+                combined_match = PatternMatch(
+                    entities=combined_entities,
+                    relations=combined_relations,
+                    score=match.score,
+                )
+                combined_matches.append(combined_match)
+
+        return combined_matches[:max_matches]
+
+    async def match_optional_patterns(
+        self,
+        required_patterns: List[PathPattern],
+        optional_patterns: List[PathPattern],
+        start_entity_id: Optional[str] = None,
+        max_matches: int = 100,
+    ) -> List[PatternMatch]:
+        """
+        Match required patterns with optional patterns
+
+        Required patterns must match. Optional patterns are included if they match.
+
+        Args:
+            required_patterns: Patterns that must match
+            optional_patterns: Patterns that may or may not match
+            start_entity_id: Optional starting entity ID
+            max_matches: Maximum number of matches to return
+
+        Returns:
+            List of pattern matches
+        """
+        # Match required patterns first
+        required_matches = await self.match_multiple_patterns(required_patterns, start_entity_id, max_matches)
+
+        if not optional_patterns:
+            return required_matches
+
+        # Try to extend with optional patterns
+        extended_matches = []
+
+        for match in required_matches:
+            combined_entities = list(match.entities)
+            combined_relations = list(match.relations)
+
+            # Try to match each optional pattern
+            for pattern in optional_patterns:
+                for entity in match.entities:
+                    sub_matches = await self.match_pattern(pattern, entity.id, max_matches=1)
+
+                    if sub_matches:
+                        # Add optional entities and relations
+                        for sub_match in sub_matches:
+                            combined_entities.extend(sub_match.entities)
+                            combined_relations.extend(sub_match.relations)
+                        break
+
+            extended_match = PatternMatch(
+                entities=combined_entities,
+                relations=combined_relations,
+                score=match.score,
+            )
+            extended_matches.append(extended_match)
+
+        return extended_matches
+
+    async def _find_matching_paths(
+        self,
+        start_entity: Entity,
+        pattern: PathPattern,
+        max_matches: int = 100,
+    ) -> List[Path]:
+        """
+        Find paths matching a pattern starting from an entity
+
+        Args:
+            start_entity: Starting entity
+            pattern: Pattern to match
+            max_matches: Maximum number of paths to return
+
+        Returns:
+            List of matching paths
+        """
+        # Use graph store's traverse method with pattern constraints
+        paths = await self.graph_store.traverse(
+            start_entity.id,
+            relation_type=(pattern.relation_types[0] if pattern.relation_types else None),
+            max_depth=pattern.max_depth,
+            max_results=max_matches,
+        )
+
+        # Filter paths based on pattern constraints
+        matching_paths = []
+
+        for path in paths:
+            if self._path_matches_pattern(path, pattern):
+                matching_paths.append(path)
+
+        return matching_paths
+
+    def _path_matches_pattern(self, path: Path, pattern: PathPattern) -> bool:
+        """
+        Check if a path matches a pattern
+
+        Args:
+            path: Path to check
+            pattern: Pattern to match against
+
+        Returns:
+            True if path matches pattern
+        """
+        # Check path length
+        if len(path.edges) < pattern.min_path_length:
+            return False
+
+        if len(path.edges) > pattern.max_depth:
+            return False
+
+        # Check entity types
+        if pattern.entity_types:
+            for entity in path.nodes:
+                if entity.entity_type not in pattern.entity_types:
+                    return False
+
+        # Check relation types
+        if pattern.relation_types:
+            for relation in path.edges:
+                if relation.relation_type not in pattern.relation_types:
+                    return False
+
+        # Check required relation sequence
+        if pattern.required_relation_sequence:
+            if len(path.edges) != len(pattern.required_relation_sequence):
+                return False
+
+            for i, relation in enumerate(path.edges):
+                if relation.relation_type != pattern.required_relation_sequence[i]:
+                    return False
+
+        # Check cycles
+        if not pattern.allow_cycles:
+            entity_ids = [entity.id for entity in path.nodes]
+            if len(entity_ids) != len(set(entity_ids)):
+                return False
+
+        # Check excluded entities
+        if pattern.excluded_entity_ids:
+            for entity in path.nodes:
+                if entity.id in pattern.excluded_entity_ids:
+                    return False
+
+        return True
+
+    async def _get_all_entities(self, entity_types: Optional[List[str]] = None) -> List[Entity]:
+        """
+        Get all entities, optionally filtered by type
+
+        Args:
+            entity_types: Optional list of entity types to filter by
+
+        Returns:
+            List of entities
+        """
+        # This is a placeholder - actual implementation depends on graph store
+        # For now, we'll return empty list and rely on start_entity_id
+        # In a real implementation, this would query the graph store for all
+        # entities
+        return []

aiecs/application/knowledge_graph/pattern_matching/query_executor.py

@@ -0,0 +1,366 @@
+"""
+Custom Query Executor
+
+Executes custom queries with pattern matching, projection, and aggregation.
+
+Phase: 3.3 - Full Custom Query Execution
+Version: 1.0
+"""
+
+from typing import List, Dict, Any, Optional
+from aiecs.domain.knowledge_graph.models.query import GraphQuery
+from aiecs.infrastructure.graph_storage.base import GraphStore
+from aiecs.application.knowledge_graph.pattern_matching.pattern_matcher import (
+    PatternMatcher,
+    PatternMatch,
+)
+
+
+class CustomQueryExecutor:
+    """
+    Custom Query Executor
+
+    Executes custom queries with:
+    - Pattern matching
+    - Result projection
+    - Aggregation
+    - Grouping
+    """
+
+    def __init__(self, graph_store: GraphStore):
+        """
+        Initialize custom query executor
+
+        Args:
+            graph_store: Graph storage backend
+        """
+        self.graph_store = graph_store
+        self.pattern_matcher = PatternMatcher(graph_store)
+
+    async def execute(self, query: GraphQuery, start_entity_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Execute a custom query
+
+        Args:
+            query: Graph query with custom patterns
+            start_entity_id: Optional starting entity ID
+
+        Returns:
+            Query results with matches, projections, and aggregations
+        """
+        # Execute pattern matching
+        matches = await self._execute_pattern_matching(query, start_entity_id)
+
+        # Apply projection if specified
+        if query.projection:
+            projected_results = self._apply_projection(matches, query.projection)
+        else:
+            projected_results = [self._match_to_dict(match) for match in matches]
+
+        # Apply aggregation if specified
+        if query.aggregations:
+            aggregated_results = self._apply_aggregation(projected_results, query.aggregations, query.group_by)
+            return {
+                "matches": len(matches),
+                "results": aggregated_results,
+                "aggregated": True,
+            }
+
+        return {
+            "matches": len(matches),
+            "results": projected_results,
+            "aggregated": False,
+        }
+
+    async def _execute_pattern_matching(self, query: GraphQuery, start_entity_id: Optional[str]) -> List[PatternMatch]:
+        """
+        Execute pattern matching based on query
+
+        Args:
+            query: Graph query
+            start_entity_id: Optional starting entity ID
+
+        Returns:
+            List of pattern matches
+        """
+        max_matches = query.max_results or 100
+
+        # Single pattern
+        if query.pattern:
+            return await self.pattern_matcher.match_pattern(query.pattern, start_entity_id, max_matches)
+
+        # Multiple patterns (required)
+        if query.patterns:
+            if query.optional_patterns:
+                # Required + optional patterns
+                return await self.pattern_matcher.match_optional_patterns(
+                    query.patterns,
+                    query.optional_patterns,
+                    start_entity_id,
+                    max_matches,
+                )
+            else:
+                # Only required patterns
+                return await self.pattern_matcher.match_multiple_patterns(query.patterns, start_entity_id, max_matches)
+
+        # No patterns specified
+        return []
+
+    def _match_to_dict(self, match: PatternMatch) -> Dict[str, Any]:
+        """
+        Convert pattern match to dictionary
+
+        Args:
+            match: Pattern match
+
+        Returns:
+            Dictionary representation
+        """
+        return {
+            "entities": [
+                {
+                    "id": entity.id,
+                    "type": entity.entity_type,
+                    "properties": entity.properties,
+                }
+                for entity in match.entities
+            ],
+            "relations": [
+                {
+                    "id": relation.id,
+                    "type": relation.relation_type,
+                    "source": relation.source_id,
+                    "target": relation.target_id,
+                    "properties": relation.properties,
+                }
+                for relation in match.relations
+            ],
+            "score": match.score,
+            "bindings": match.bindings,
+        }
+
+    def _apply_projection(self, matches: List[PatternMatch], projection: List[str]) -> List[Dict[str, Any]]:
+        """
+        Apply projection to matches
+
+        Args:
+            matches: Pattern matches
+            projection: Fields to project
+
+        Returns:
+            Projected results
+        """
+        projected = []
+
+        for match in matches:
+            result = {}
+
+            for field in projection:
+                value = self._extract_field(match, field)
+                result[field] = value
+
+            projected.append(result)
+
+        return projected
+
+    def _extract_field(self, match: PatternMatch, field: str) -> Any:
+        """
+        Extract a field value from a match
+
+        Supports dot notation for nested fields:
+        - "id" -> first entity's ID
+        - "entities[0].name" -> first entity's name
+        - "entities[0].properties.age" -> first entity's age property
+
+        Args:
+            match: Pattern match
+            field: Field path to extract
+
+        Returns:
+            Field value
+        """
+        # Handle simple fields
+        if field == "score":
+            return match.score
+
+        if field == "entity_count":
+            return len(match.entities)
+
+        if field == "relation_count":
+            return len(match.relations)
+
+        # Handle entity fields
+        if field.startswith("entities"):
+            # Parse entities[0].name or entities[0].properties.age
+            parts = field.split(".")
+
+            # Extract index
+            if "[" in parts[0]:
+                index_str = parts[0].split("[")[1].split("]")[0]
+                index = int(index_str)
+
+                if index >= len(match.entities):
+                    return None
+
+                entity = match.entities[index]
+
+                # Extract nested field
+                if len(parts) == 1:
+                    return {
+                        "id": entity.id,
+                        "type": entity.entity_type,
+                        "properties": entity.properties,
+                    }
+
+                if parts[1] == "id":
+                    return entity.id
+                elif parts[1] == "type":
+                    return entity.entity_type
+                elif parts[1] == "properties" and len(parts) > 2:
+                    return entity.properties.get(parts[2])
+                elif parts[1] == "properties":
+                    return entity.properties
+
+        # Handle relation fields
+        if field.startswith("relations"):
+            parts = field.split(".")
+
+            if "[" in parts[0]:
+                index_str = parts[0].split("[")[1].split("]")[0]
+                index = int(index_str)
+
+                if index >= len(match.relations):
+                    return None
+
+                relation = match.relations[index]
+
+                if len(parts) == 1:
+                    return {
+                        "id": relation.id,
+                        "type": relation.relation_type,
+                        "source": relation.source_id,
+                        "target": relation.target_id,
+                    }
+
+                if parts[1] == "id":
+                    return relation.id
+                elif parts[1] == "type":
+                    return relation.relation_type
+                elif parts[1] == "source":
+                    return relation.source_id
+                elif parts[1] == "target":
+                    return relation.target_id
+                elif parts[1] == "properties" and len(parts) > 2:
+                    return relation.properties.get(parts[2])
+
+        # Handle bindings
+        if field.startswith("bindings."):
+            binding_name = field.split(".")[1]
+            return match.bindings.get(binding_name)
+
+        return None
+
+    def _apply_aggregation(
+        self,
+        results: List[Dict[str, Any]],
+        aggregations: Dict[str, str],
+        group_by: Optional[List[str]] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Apply aggregations to results
+
+        Args:
+            results: Projected results
+            aggregations: Aggregation functions (e.g., {"count": "COUNT", "avg_age": "AVG(age)"})
+            group_by: Optional fields to group by
+
+        Returns:
+            Aggregated results
+        """
+        if group_by:
+            # Group results
+            groups: Dict[Any, List[Dict[str, Any]]] = {}
+
+            for result in results:
+                # Create group key
+                key_parts = []
+                for field in group_by:
+                    key_parts.append(str(result.get(field, "")))
+                key = tuple(key_parts)
+
+                if key not in groups:
+                    groups[key] = []
+                groups[key].append(result)
+
+            # Aggregate each group
+            aggregated = []
+
+            for key, group_results in groups.items():
+                agg_result = {}
+
+                # Add group by fields
+                for i, field in enumerate(group_by):
+                    agg_result[field] = key[i]
+
+                # Apply aggregations
+                for agg_name, agg_func in aggregations.items():
+                    agg_result[agg_name] = self._compute_aggregation(group_results, agg_func)
+
+                aggregated.append(agg_result)
+
+            return aggregated
+        else:
+            # Aggregate all results
+            agg_result = {}
+
+            for agg_name, agg_func in aggregations.items():
+                agg_result[agg_name] = self._compute_aggregation(results, agg_func)
+
+            return [agg_result]
+
+    def _compute_aggregation(self, results: List[Dict[str, Any]], agg_func: str) -> Any:
+        """
+        Compute an aggregation function
+
+        Supports:
+        - COUNT: Count of results
+        - SUM(field): Sum of field values
+        - AVG(field): Average of field values
+        - MIN(field): Minimum field value
+        - MAX(field): Maximum field value
+
+        Args:
+            results: Results to aggregate
+            agg_func: Aggregation function string
+
+        Returns:
+            Aggregated value
+        """
+        if agg_func == "COUNT":
+            return len(results)
+
+        # Parse function and field
+        if "(" in agg_func:
+            func_name = agg_func.split("(")[0]
+            field = agg_func.split("(")[1].split(")")[0]
+
+            # Extract field values
+            values = []
+            for result in results:
+                value = result.get(field)
+                if value is not None and isinstance(value, (int, float)):
+                    values.append(value)
+
+            if not values:
+                return None
+
+            if func_name == "SUM":
+                return sum(values)
+            elif func_name == "AVG":
+                return sum(values) / len(values)
+            elif func_name == "MIN":
+                return min(values)
+            elif func_name == "MAX":
+                return max(values)
+
+        return None