aiecs 1.5.1__py3-none-any.whl

aiecs/application/knowledge_graph/pattern_matching/query_executor.py

@@ -0,0 +1,378 @@
+"""
+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 = {}
+
+            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

aiecs/application/knowledge_graph/profiling/__init__.py

@@ -0,0 +1,12 @@
+"""
+Knowledge Graph Profiling
+
+Performance profiling and analysis tools for knowledge graph operations.
+"""
+
+from aiecs.application.knowledge_graph.profiling.query_profiler import (
+    QueryProfiler,
+    QueryProfile,
+)
+
+__all__ = ["QueryProfiler", "QueryProfile"]

aiecs/application/knowledge_graph/profiling/query_plan_visualizer.py

@@ -0,0 +1,199 @@
+"""
+Query Plan Visualizer
+
+Visualize query execution plans and performance profiles.
+"""
+
+from typing import Dict, Any, List
+from aiecs.application.knowledge_graph.profiling.query_profiler import (
+    QueryProfile,
+)
+from aiecs.domain.knowledge_graph.models.query_plan import QueryPlan
+
+
+class QueryPlanVisualizer:
+    """
+    Visualize query plans and execution profiles
+
+    Generates text-based visualizations of query plans and performance data.
+
+    Example:
+        ```python
+        visualizer = QueryPlanVisualizer()
+
+        # Visualize query plan
+        plan_viz = visualizer.visualize_plan(query_plan)
+        print(plan_viz)
+
+        # Visualize execution profile
+        profile_viz = visualizer.visualize_profile(query_profile)
+        print(profile_viz)
+        ```
+    """
+
+    def visualize_plan(self, plan: QueryPlan, show_costs: bool = True) -> str:
+        """
+        Visualize a query plan
+
+        Args:
+            plan: Query plan to visualize
+            show_costs: Whether to show cost estimates
+
+        Returns:
+            Text visualization of the plan
+        """
+        lines = []
+        lines.append("=" * 60)
+        lines.append("QUERY PLAN")
+        lines.append("=" * 60)
+
+        if show_costs:
+            total_cost = plan.calculate_total_cost()
+            lines.append(f"Total Estimated Cost: {total_cost:.2f}")
+            lines.append("")
+
+        for i, step in enumerate(plan.steps, 1):
+            lines.append(f"Step {i}: {step.operation.value}")
+            lines.append(f"  Description: {step.description}")
+
+            if show_costs:
+                lines.append(f"  Estimated Cost: {step.estimated_cost:.2f}")
+
+            if step.depends_on:
+                lines.append(f"  Depends On: {', '.join(step.depends_on)}")
+
+            if step.metadata:
+                lines.append(f"  Metadata: {step.metadata}")
+
+            lines.append("")
+
+        lines.append("=" * 60)
+        return "\n".join(lines)
+
+    def visualize_profile(self, profile: QueryProfile, show_steps: bool = True) -> str:
+        """
+        Visualize a query execution profile
+
+        Args:
+            profile: Query profile to visualize
+            show_steps: Whether to show individual steps
+
+        Returns:
+            Text visualization of the profile
+        """
+        lines = []
+        lines.append("=" * 60)
+        lines.append("QUERY EXECUTION PROFILE")
+        lines.append("=" * 60)
+        lines.append(f"Query ID: {profile.query_id}")
+        lines.append(f"Query Type: {profile.query_type}")
+        lines.append(f"Total Duration: {profile.duration_ms:.2f}ms")
+        lines.append("")
+
+        if show_steps and profile.steps:
+            lines.append("Execution Steps:")
+            lines.append("-" * 60)
+
+            for i, step in enumerate(profile.steps, 1):
+                duration = step["duration_ms"]
+                percentage = (duration / profile.duration_ms * 100) if profile.duration_ms else 0
+
+                lines.append(f"{i}. {step['name']}")
+                lines.append(f"   Duration: {duration:.2f}ms ({percentage:.1f}%)")
+
+                # Show bar chart
+                bar_length = int(percentage / 2)  # Scale to 50 chars max
+                bar = "█" * bar_length
+                lines.append(f"   [{bar:<50}]")
+
+                if step.get("metadata"):
+                    lines.append(f"   Metadata: {step['metadata']}")
+
+                lines.append("")
+
+        if profile.metadata:
+            lines.append("Query Metadata:")
+            for key, value in profile.metadata.items():
+                lines.append(f"  {key}: {value}")
+            lines.append("")
+
+        lines.append("=" * 60)
+        return "\n".join(lines)
+
+    def visualize_comparison(self, profiles: List[QueryProfile]) -> str:
+        """
+        Visualize comparison of multiple query profiles
+
+        Args:
+            profiles: List of profiles to compare
+
+        Returns:
+            Text visualization comparing profiles
+        """
+        if not profiles:
+            return "No profiles to compare"
+
+        lines = []
+        lines.append("=" * 60)
+        lines.append("QUERY PROFILE COMPARISON")
+        lines.append("=" * 60)
+
+        # Summary table
+        lines.append(f"{'Query ID':<20} {'Type':<15} {'Duration (ms)':<15}")
+        lines.append("-" * 60)
+
+        for profile in profiles:
+            duration = f"{profile.duration_ms:.2f}" if profile.duration_ms else "N/A"
+            lines.append(f"{profile.query_id:<20} {profile.query_type:<15} {duration:<15}")
+
+        lines.append("")
+
+        # Statistics
+        durations = [p.duration_ms for p in profiles if p.duration_ms]
+        if durations:
+            lines.append("Statistics:")
+            lines.append(f"  Average: {sum(durations) / len(durations):.2f}ms")
+            lines.append(f"  Min: {min(durations):.2f}ms")
+            lines.append(f"  Max: {max(durations):.2f}ms")
+
+        lines.append("=" * 60)
+        return "\n".join(lines)
+
+    def export_to_json(self, profile: QueryProfile) -> Dict[str, Any]:
+        """
+        Export profile to JSON format
+
+        Args:
+            profile: Query profile to export
+
+        Returns:
+            Dictionary representation suitable for JSON export
+        """
+        return profile.to_dict()
+
+    def generate_flamegraph_data(self, profile: QueryProfile) -> List[Dict[str, Any]]:
+        """
+        Generate data for flamegraph visualization
+
+        Args:
+            profile: Query profile
+
+        Returns:
+            List of flamegraph data points
+        """
+        data = []
+
+        for step in profile.steps:
+            data.append(
+                {
+                    "name": step["name"],
+                    "value": step["duration_ms"],
+                    "percentage": (
+                        (step["duration_ms"] / profile.duration_ms * 100)
+                        if profile.duration_ms
+                        else 0
+                    ),
+                }
+            )
+
+        return data