emdash-core 0.1.7__py3-none-any.whl

emdash_core/context/providers/explored_areas.py

@@ -0,0 +1,183 @@
+"""ExploredAreasProvider - Context from agent exploration with tool-based relevance."""
+
+from dataclasses import asdict
+from typing import Optional, Union
+
+from ..models import ContextItem, ContextProviderSpec
+from .base import ContextProvider
+from ..registry import ContextProviderRegistry
+from ...graph.connection import KuzuConnection
+from ...utils.logger import log
+
+
+class ExploredAreasProvider(ContextProvider):
+    """Context provider that extracts entities from agent exploration.
+
+    Analyzes the steps recorded during an agent session and assigns
+    relevance scores based on the tool type used to discover each entity.
+
+    High relevance: deliberate investigation (expand_node, get_callers, etc.)
+    Medium relevance: targeted search (semantic_search, text_search)
+    Low relevance: broad search (grep, get_top_pagerank)
+    """
+
+    # Tool-based relevance scores
+    TOOL_RELEVANCE = {
+        # High relevance - deliberate investigation
+        "expand_node": 1.0,
+        "get_callers": 0.9,
+        "get_callees": 0.9,
+        "get_class_hierarchy": 0.9,
+        "get_neighbors": 0.85,
+        "get_impact_analysis": 0.85,
+        "read_file": 0.8,  # Reading a file is deliberate investigation
+        # Medium relevance - targeted search
+        "semantic_search": 0.7,
+        "text_search": 0.6,
+        "get_file_dependencies": 0.6,
+        "find_entity": 0.6,
+        # Lower relevance - broad search/modification
+        "grep": 0.4,
+        "write_to_file": 0.4,
+        "apply_diff": 0.4,
+        "get_top_pagerank": 0.3,
+        "get_communities": 0.3,
+        "list_files": 0.2,
+        "execute_command": 0.1,
+    }
+
+    # Only top N results from search tools are considered highly relevant
+    TOP_RESULTS_LIMIT = 3
+
+    # Tools where we limit to top results
+    SEARCH_TOOLS = {"semantic_search", "text_search", "grep", "find_entity"}
+
+    def __init__(self, connection: KuzuConnection, config: Optional[dict] = None):
+        super().__init__(connection, config)
+
+    @property
+    def spec(self) -> ContextProviderSpec:
+        return ContextProviderSpec(
+            name="explored_areas",
+            description="Context from agent exploration with tool-based relevance",
+            requires_graph=False,  # Uses session data, not graph queries
+        )
+
+    def extract_context(self, exploration_steps: list) -> list[ContextItem]:
+        """Extract context items from exploration steps.
+
+        Args:
+            exploration_steps: List of ExplorationStep objects or dicts from AgentSession
+
+        Returns:
+            Context items with relevance-based scores
+        """
+        if not exploration_steps:
+            return []
+
+        # Track best score for each entity
+        entity_scores: dict[str, tuple[float, Optional[str], Optional[str]]] = {}
+
+        for step in exploration_steps:
+            # Handle both ExplorationStep objects and dicts
+            if hasattr(step, "tool_name"):
+                tool_name = step.tool_name
+                entities = step.entities_discovered
+            else:
+                tool_name = step.get("tool_name", "")
+                entities = step.get("entities_discovered", [])
+
+            # Get base relevance score for this tool
+            base_score = self.TOOL_RELEVANCE.get(tool_name, 0.2)
+
+            # For search tools, only top results are highly relevant
+            if tool_name in self.SEARCH_TOOLS:
+                # Process top results with full score, others with reduced score
+                for i, entity in enumerate(entities):
+                    qname = self._extract_qualified_name(entity)
+                    if not qname:
+                        continue
+
+                    # Top results get full score, others get reduced
+                    if i < self.TOP_RESULTS_LIMIT:
+                        score = base_score
+                    else:
+                        score = base_score * 0.5  # Reduced score for non-top results
+
+                    self._update_entity_score(entity_scores, qname, score, entity)
+            else:
+                # Non-search tools: all entities get the same score
+                for entity in entities:
+                    qname = self._extract_qualified_name(entity)
+                    if not qname:
+                        continue
+                    self._update_entity_score(entity_scores, qname, base_score, entity)
+
+        # Convert to ContextItems
+        items = []
+        for qname, (score, entity_type, file_path) in entity_scores.items():
+            # Skip file: prefix for display if it's a File type
+            display_name = qname
+            if qname.startswith("file:"):
+                display_name = qname[5:]  # Remove "file:" prefix
+            items.append(
+                ContextItem(
+                    qualified_name=display_name,
+                    entity_type=entity_type or "Unknown",
+                    file_path=file_path,
+                    score=score,
+                    neighbors=[],  # Could fetch from graph if needed
+                )
+            )
+
+        log.info(
+            f"ExploredAreasProvider: extracted {len(items)} context items "
+            f"from {len(exploration_steps)} exploration steps"
+        )
+        return items
+
+    def _extract_qualified_name(self, entity: Union[str, dict]) -> Optional[str]:
+        """Extract qualified name from entity (string or dict)."""
+        if isinstance(entity, str):
+            return entity
+        if isinstance(entity, dict):
+            return entity.get("qualified_name")
+        return None
+
+    def _update_entity_score(
+        self,
+        entity_scores: dict,
+        qname: str,
+        score: float,
+        entity: Union[str, dict],
+    ) -> None:
+        """Update entity score, keeping the highest score."""
+        current = entity_scores.get(qname)
+        if current is None or score > current[0]:
+            entity_type = self._infer_type(entity)
+            file_path = self._infer_file(entity)
+            entity_scores[qname] = (score, entity_type, file_path)
+
+    def _infer_type(self, entity: Union[str, dict]) -> Optional[str]:
+        """Infer entity type from entity data."""
+        if isinstance(entity, dict):
+            return entity.get("type") or entity.get("entity_type")
+        # Try to infer from qualified name pattern
+        if isinstance(entity, str):
+            if "." in entity:
+                parts = entity.split(".")
+                # If last part starts with uppercase, likely a class
+                if parts[-1] and parts[-1][0].isupper():
+                    return "Class"
+            return "Function"  # Default assumption
+        return None
+
+    def _infer_file(self, entity: Union[str, dict]) -> Optional[str]:
+        """Infer file path from entity data."""
+        if isinstance(entity, dict):
+            return entity.get("file_path") or entity.get("path")
+        return None
+
+
+# Auto-register provider
+ContextProviderRegistry.register("explored_areas", ExploredAreasProvider)

emdash_core/context/providers/touched_areas.py

@@ -0,0 +1,360 @@
+"""TouchedAreasProvider - Context from AST neighbors of modified code."""
+
+import os
+from typing import Optional
+
+from ..models import ContextItem, ContextProviderSpec
+from .base import ContextProvider
+from ..registry import ContextProviderRegistry
+from ...graph.connection import KuzuConnection
+from ...utils.logger import log
+
+
+class TouchedAreasProvider(ContextProvider):
+    """Context provider that extracts AST neighbors of touched code.
+
+    When files are modified, this provider:
+    1. Finds functions/classes in those files from the Kuzu AST
+    2. Gets N-hop neighbors (callers, callees, parent classes, etc.)
+    3. Returns context items with descriptions and relationships
+    """
+
+    def __init__(self, connection: KuzuConnection, config: Optional[dict] = None):
+        super().__init__(connection, config)
+        self._neighbor_depth = int(
+            config.get("neighbor_depth") if config else os.getenv("CONTEXT_NEIGHBOR_DEPTH", "2")
+        )
+
+    @property
+    def spec(self) -> ContextProviderSpec:
+        return ContextProviderSpec(
+            name="touched_areas",
+            description="AST-based context from modified code and neighbors",
+            requires_graph=True,
+        )
+
+    def extract_context(self, modified_files: list[str]) -> list[ContextItem]:
+        """Extract context items from modified files.
+
+        Args:
+            modified_files: List of file paths that were modified
+
+        Returns:
+            List of context items with AST neighbors
+        """
+        if not modified_files:
+            return []
+
+        items = []
+        seen_qualified_names = set()
+
+        for file_path in modified_files:
+            # Skip non-code files
+            if not self._is_code_file(file_path):
+                continue
+
+            # Normalize path to match what's in the database
+            normalized_path = self._normalize_path(file_path)
+
+            # Get entities in this file
+            entities = self._get_file_entities(normalized_path)
+
+            for entity in entities:
+                qname = entity.get("qualified_name")
+                if not qname or qname in seen_qualified_names:
+                    continue
+                seen_qualified_names.add(qname)
+
+                # Get neighbors up to configured depth
+                neighbors = self._get_neighbors(entity, depth=self._neighbor_depth)
+                neighbor_names = [n.get("qualified_name") for n in neighbors if n.get("qualified_name")]
+
+                items.append(
+                    ContextItem(
+                        qualified_name=qname,
+                        entity_type=entity.get("type", "Unknown"),
+                        description=entity.get("docstring"),
+                        file_path=file_path,
+                        neighbors=neighbor_names,
+                    )
+                )
+
+        log.info(f"TouchedAreasProvider: extracted {len(items)} context items from {len(modified_files)} files")
+        return items
+
+    def _normalize_path(self, file_path: str) -> str:
+        """Normalize file path to match database format."""
+        # Convert to absolute path if relative
+        if not os.path.isabs(file_path):
+            file_path = os.path.abspath(file_path)
+        return file_path
+
+    def _is_code_file(self, file_path: str) -> bool:
+        """Check if file is a code file worth tracking.
+
+        Filters out logs, build artifacts, and other non-code files.
+        """
+        if not file_path:
+            return False
+
+        lower_path = file_path.lower()
+
+        # Skip patterns
+        skip_patterns = (
+            ".log", "/logs/", "/log/",
+            "/node_modules/", "/__pycache__/",
+            "/dist/", "/build/", "/.git/",
+            ".pyc", ".pyo", ".so", ".dll",
+            "/coverage/", "/.nyc_output/",
+            ".env", ".lock",
+        )
+        if any(pattern in lower_path for pattern in skip_patterns):
+            return False
+
+        # Code file extensions
+        code_extensions = (
+            ".py", ".ts", ".tsx", ".js", ".jsx",
+            ".java", ".go", ".rs", ".rb", ".php",
+            ".c", ".cpp", ".h", ".hpp", ".cs",
+            ".swift", ".kt", ".scala", ".vue",
+            ".json", ".yaml", ".yml", ".toml",
+            ".md", ".sql", ".graphql",
+        )
+        return any(lower_path.endswith(ext) for ext in code_extensions)
+
+    def _get_file_entities(self, file_path: str) -> list[dict]:
+        """Query Kuzu for functions and classes in a file.
+
+        Args:
+            file_path: Absolute path to the file
+
+        Returns:
+            List of entity dictionaries
+        """
+        try:
+            # Try exact match first
+            results = self.connection.execute(
+                """
+                MATCH (f:File)-[:CONTAINS_FUNCTION]->(fn:Function)
+                WHERE f.path = $path
+                RETURN fn.qualified_name as qualified_name,
+                       'Function' as type,
+                       fn.docstring as docstring,
+                       fn.name as name
+                """,
+                {"path": file_path},
+            )
+
+            # Also get classes
+            class_results = self.connection.execute(
+                """
+                MATCH (f:File)-[:CONTAINS_CLASS]->(c:Class)
+                WHERE f.path = $path
+                RETURN c.qualified_name as qualified_name,
+                       'Class' as type,
+                       c.docstring as docstring,
+                       c.name as name
+                """,
+                {"path": file_path},
+            )
+
+            results.extend(class_results)
+
+            # If no results, try ENDS WITH for partial path match
+            if not results:
+                filename = os.path.basename(file_path)
+                results = self.connection.execute(
+                    """
+                    MATCH (f:File)-[:CONTAINS_FUNCTION]->(fn:Function)
+                    WHERE f.path ENDS WITH $filename
+                    RETURN fn.qualified_name as qualified_name,
+                           'Function' as type,
+                           fn.docstring as docstring,
+                           fn.name as name
+                    """,
+                    {"filename": filename},
+                )
+
+                class_results = self.connection.execute(
+                    """
+                    MATCH (f:File)-[:CONTAINS_CLASS]->(c:Class)
+                    WHERE f.path ENDS WITH $filename
+                    RETURN c.qualified_name as qualified_name,
+                           'Class' as type,
+                           c.docstring as docstring,
+                           c.name as name
+                    """,
+                    {"filename": filename},
+                )
+                results.extend(class_results)
+
+            return results
+
+        except Exception as e:
+            log.debug(f"Failed to get file entities for {file_path}: {e}")
+            return []
+
+    def _get_neighbors(self, entity: dict, depth: int = 2) -> list[dict]:
+        """Get N-hop neighbors of an entity.
+
+        Traverses CALLS, INHERITS_FROM, and HAS_METHOD relationships
+        to find related code entities.
+
+        Args:
+            entity: Entity dictionary with qualified_name and type
+            depth: Number of hops to traverse
+
+        Returns:
+            List of neighbor entity dictionaries
+        """
+        qname = entity.get("qualified_name")
+        entity_type = entity.get("type")
+
+        if not qname:
+            return []
+
+        neighbors = []
+
+        try:
+            if entity_type == "Function":
+                neighbors.extend(self._get_function_neighbors(qname, depth))
+            elif entity_type == "Class":
+                neighbors.extend(self._get_class_neighbors(qname, depth))
+
+        except Exception as e:
+            log.warning(f"Failed to get neighbors for {qname}: {e}")
+
+        return neighbors
+
+    def _get_function_neighbors(self, qualified_name: str, depth: int) -> list[dict]:
+        """Get neighbors of a function (callers, callees)."""
+        neighbors = []
+
+        # Get direct callers (functions that call this one)
+        callers = self.connection.execute(
+            """
+            MATCH (caller:Function)-[:CALLS]->(f:Function {qualified_name: $qname})
+            RETURN caller.qualified_name as qualified_name,
+                   'Function' as type,
+                   caller.docstring as docstring,
+                   caller.name as name
+            LIMIT 20
+            """,
+            {"qname": qualified_name},
+        )
+        neighbors.extend(callers)
+
+        # Get direct callees (functions this one calls)
+        callees = self.connection.execute(
+            """
+            MATCH (f:Function {qualified_name: $qname})-[:CALLS]->(callee:Function)
+            RETURN callee.qualified_name as qualified_name,
+                   'Function' as type,
+                   callee.docstring as docstring,
+                   callee.name as name
+            LIMIT 20
+            """,
+            {"qname": qualified_name},
+        )
+        neighbors.extend(callees)
+
+        # If depth > 1, get 2nd hop neighbors
+        if depth > 1:
+            # 2-hop callers (who calls my callers)
+            hop2_callers = self.connection.execute(
+                """
+                MATCH (caller2:Function)-[:CALLS]->(caller:Function)-[:CALLS]->(f:Function {qualified_name: $qname})
+                WHERE caller2.qualified_name <> $qname
+                RETURN DISTINCT caller2.qualified_name as qualified_name,
+                       'Function' as type,
+                       caller2.docstring as docstring,
+                       caller2.name as name
+                LIMIT 10
+                """,
+                {"qname": qualified_name},
+            )
+            neighbors.extend(hop2_callers)
+
+            # 2-hop callees (who my callees call)
+            hop2_callees = self.connection.execute(
+                """
+                MATCH (f:Function {qualified_name: $qname})-[:CALLS]->(callee:Function)-[:CALLS]->(callee2:Function)
+                WHERE callee2.qualified_name <> $qname
+                RETURN DISTINCT callee2.qualified_name as qualified_name,
+                       'Function' as type,
+                       callee2.docstring as docstring,
+                       callee2.name as name
+                LIMIT 10
+                """,
+                {"qname": qualified_name},
+            )
+            neighbors.extend(hop2_callees)
+
+        return neighbors
+
+    def _get_class_neighbors(self, qualified_name: str, depth: int) -> list[dict]:
+        """Get neighbors of a class (parents, children, methods)."""
+        neighbors = []
+
+        # Get parent classes
+        parents = self.connection.execute(
+            """
+            MATCH (c:Class {qualified_name: $qname})-[:INHERITS_FROM]->(parent:Class)
+            RETURN parent.qualified_name as qualified_name,
+                   'Class' as type,
+                   parent.docstring as docstring,
+                   parent.name as name
+            LIMIT 10
+            """,
+            {"qname": qualified_name},
+        )
+        neighbors.extend(parents)
+
+        # Get child classes
+        children = self.connection.execute(
+            """
+            MATCH (child:Class)-[:INHERITS_FROM]->(c:Class {qualified_name: $qname})
+            RETURN child.qualified_name as qualified_name,
+                   'Class' as type,
+                   child.docstring as docstring,
+                   child.name as name
+            LIMIT 10
+            """,
+            {"qname": qualified_name},
+        )
+        neighbors.extend(children)
+
+        # Get methods of this class
+        methods = self.connection.execute(
+            """
+            MATCH (c:Class {qualified_name: $qname})-[:HAS_METHOD]->(m:Function)
+            RETURN m.qualified_name as qualified_name,
+                   'Function' as type,
+                   m.docstring as docstring,
+                   m.name as name
+            LIMIT 20
+            """,
+            {"qname": qualified_name},
+        )
+        neighbors.extend(methods)
+
+        # If depth > 1, get grandparent/grandchild classes
+        if depth > 1:
+            grandparents = self.connection.execute(
+                """
+                MATCH (c:Class {qualified_name: $qname})-[:INHERITS_FROM]->(:Class)-[:INHERITS_FROM]->(gp:Class)
+                RETURN DISTINCT gp.qualified_name as qualified_name,
+                       'Class' as type,
+                       gp.docstring as docstring,
+                       gp.name as name
+                LIMIT 5
+                """,
+                {"qname": qualified_name},
+            )
+            neighbors.extend(grandparents)
+
+        return neighbors
+
+
+# Auto-register provider
+ContextProviderRegistry.register("touched_areas", TouchedAreasProvider)

emdash_core/context/registry.py

@@ -0,0 +1,73 @@
+"""Registry for context providers."""
+
+from typing import Type, Optional
+
+from ..graph.connection import KuzuConnection
+
+
+class ContextProviderRegistry:
+    """Registry for context providers using class-method pattern.
+
+    Providers register themselves at import time, allowing for
+    easy extensibility without modifying existing code.
+
+    Example:
+        ContextProviderRegistry.register("my_provider", MyProvider)
+        provider = ContextProviderRegistry.get_provider("my_provider", connection)
+    """
+
+    _providers: dict[str, Type] = {}
+
+    @classmethod
+    def register(cls, name: str, provider_class: Type):
+        """Register a context provider.
+
+        Args:
+            name: Unique name for the provider
+            provider_class: Provider class (must subclass ContextProvider)
+        """
+        cls._providers[name] = provider_class
+
+    @classmethod
+    def get_provider(cls, name: str, connection: KuzuConnection, config: Optional[dict] = None):
+        """Get a provider instance by name.
+
+        Args:
+            name: Provider name
+            connection: Kuzu database connection
+            config: Optional provider-specific configuration
+
+        Returns:
+            Instantiated provider
+
+        Raises:
+            ValueError: If provider name not found
+        """
+        if name not in cls._providers:
+            available = ", ".join(cls._providers.keys()) or "none"
+            raise ValueError(f"Unknown context provider: '{name}'. Available: {available}")
+        return cls._providers[name](connection, config)
+
+    @classmethod
+    def list_providers(cls) -> list[str]:
+        """Get list of registered provider names."""
+        return list(cls._providers.keys())
+
+    @classmethod
+    def is_registered(cls, name: str) -> bool:
+        """Check if a provider is registered."""
+        return name in cls._providers
+
+
+def get_provider(name: str, connection: KuzuConnection, config: Optional[dict] = None):
+    """Convenience function to get a provider.
+
+    Args:
+        name: Provider name
+        connection: Kuzu database connection
+        config: Optional provider-specific configuration
+
+    Returns:
+        Instantiated provider
+    """
+    return ContextProviderRegistry.get_provider(name, connection, config)