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

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,195 @@
+"""
+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

aiecs/application/knowledge_graph/profiling/query_profiler.py

@@ -0,0 +1,223 @@
+"""
+Query Profiler for Knowledge Graph
+
+Provides detailed profiling and timing metrics for graph queries.
+"""
+
+import time
+import logging
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass, field
+from contextlib import asynccontextmanager
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class QueryProfile:
+    """
+    Profile data for a single query execution
+
+    Attributes:
+        query_id: Unique identifier for the query
+        query_type: Type of query (search, traverse, etc.)
+        start_time: When the query started
+        end_time: When the query completed
+        duration_ms: Total duration in milliseconds
+        steps: List of execution steps with timing
+        metadata: Additional query metadata
+    """
+
+    query_id: str
+    query_type: str
+    start_time: datetime
+    end_time: Optional[datetime] = None
+    duration_ms: Optional[float] = None
+    steps: List[Dict[str, Any]] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def complete(self) -> None:
+        """Mark query as complete and calculate duration"""
+        self.end_time = datetime.utcnow()
+        if self.start_time:
+            delta = self.end_time - self.start_time
+            self.duration_ms = delta.total_seconds() * 1000
+
+    def add_step(
+        self,
+        name: str,
+        duration_ms: float,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Add an execution step"""
+        self.steps.append(
+            {
+                "name": name,
+                "duration_ms": duration_ms,
+                "metadata": metadata or {},
+            }
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary"""
+        return {
+            "query_id": self.query_id,
+            "query_type": self.query_type,
+            "start_time": self.start_time.isoformat(),
+            "end_time": self.end_time.isoformat() if self.end_time else None,
+            "duration_ms": self.duration_ms,
+            "steps": self.steps,
+            "metadata": self.metadata,
+        }
+
+
+class QueryProfiler:
+    """
+    Query profiler for detailed performance analysis
+
+    Tracks query execution with step-by-step timing and metadata.
+
+    Example:
+        ```python
+        profiler = QueryProfiler()
+
+        # Profile a query
+        async with profiler.profile("search_query", "vector_search") as profile:
+            # Step 1
+            async with profiler.step(profile, "embedding_lookup"):
+                embedding = await get_embedding(query)
+
+            # Step 2
+            async with profiler.step(profile, "vector_search"):
+                results = await search(embedding)
+
+        # Get profile
+        profile_data = profiler.get_profile("search_query")
+        print(f"Total: {profile_data.duration_ms}ms")
+        for step in profile_data.steps:
+            print(f"  {step['name']}: {step['duration_ms']}ms")
+        ```
+    """
+
+    def __init__(self, max_profiles: int = 1000):
+        """
+        Initialize query profiler
+
+        Args:
+            max_profiles: Maximum number of profiles to keep in memory
+        """
+        self.max_profiles = max_profiles
+        self.profiles: Dict[str, QueryProfile] = {}
+        self._profile_order: List[str] = []
+
+    @asynccontextmanager
+    async def profile(
+        self,
+        query_id: str,
+        query_type: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Context manager for profiling a query
+
+        Args:
+            query_id: Unique identifier for the query
+            query_type: Type of query
+            metadata: Additional metadata
+
+        Yields:
+            QueryProfile object
+        """
+        # Create profile
+        profile = QueryProfile(
+            query_id=query_id,
+            query_type=query_type,
+            start_time=datetime.utcnow(),
+            metadata=metadata or {},
+        )
+
+        try:
+            yield profile
+        finally:
+            # Complete profile
+            profile.complete()
+
+            # Store profile
+            self._store_profile(profile)
+
+    @asynccontextmanager
+    async def step(
+        self,
+        profile: QueryProfile,
+        step_name: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Context manager for profiling a query step
+
+        Args:
+            profile: Parent query profile
+            step_name: Name of the step
+            metadata: Additional metadata
+        """
+        start_time = time.perf_counter()
+
+        try:
+            yield
+        finally:
+            end_time = time.perf_counter()
+            duration_ms = (end_time - start_time) * 1000
+            profile.add_step(step_name, duration_ms, metadata)
+
+    def _store_profile(self, profile: QueryProfile) -> None:
+        """Store profile with LRU eviction"""
+        # Add to storage
+        self.profiles[profile.query_id] = profile
+        self._profile_order.append(profile.query_id)
+
+        # Evict oldest if over limit
+        while len(self._profile_order) > self.max_profiles:
+            oldest_id = self._profile_order.pop(0)
+            if oldest_id in self.profiles:
+                del self.profiles[oldest_id]
+
+    def get_profile(self, query_id: str) -> Optional[QueryProfile]:
+        """Get profile by query ID"""
+        return self.profiles.get(query_id)
+
+    def get_all_profiles(self) -> List[QueryProfile]:
+        """Get all stored profiles"""
+        return list(self.profiles.values())
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get profiling statistics"""
+        if not self.profiles:
+            return {
+                "total_queries": 0,
+                "avg_duration_ms": 0,
+                "min_duration_ms": 0,
+                "max_duration_ms": 0,
+            }
+
+        durations = [p.duration_ms for p in self.profiles.values() if p.duration_ms]
+
+        return {
+            "total_queries": len(self.profiles),
+            "avg_duration_ms": (sum(durations) / len(durations) if durations else 0),
+            "min_duration_ms": min(durations) if durations else 0,
+            "max_duration_ms": max(durations) if durations else 0,
+            "query_types": self._get_query_type_stats(),
+        }
+
+    def _get_query_type_stats(self) -> Dict[str, int]:
+        """Get statistics by query type"""
+        stats: Dict[str, int] = {}
+        for profile in self.profiles.values():
+            stats[profile.query_type] = stats.get(profile.query_type, 0) + 1
+        return stats
+
+    def clear(self) -> None:
+        """Clear all profiles"""
+        self.profiles.clear()
+        self._profile_order.clear()

aiecs/application/knowledge_graph/reasoning/__init__.py

@@ -0,0 +1,27 @@
+"""
+Knowledge Graph Reasoning Module
+
+Provides query planning, multi-hop reasoning, and inference capabilities.
+"""
+
+from aiecs.application.knowledge_graph.reasoning.query_planner import (
+    QueryPlanner,
+)
+from aiecs.application.knowledge_graph.reasoning.reasoning_engine import (
+    ReasoningEngine,
+)
+from aiecs.application.knowledge_graph.reasoning.inference_engine import (
+    InferenceEngine,
+    InferenceCache,
+)
+from aiecs.application.knowledge_graph.reasoning.evidence_synthesis import (
+    EvidenceSynthesizer,
+)
+
+__all__ = [
+    "QueryPlanner",
+    "ReasoningEngine",
+    "InferenceEngine",
+    "InferenceCache",
+    "EvidenceSynthesizer",
+]