krnl-code 1.0.4__py3-none-any.whl

krnl_agent/graph.py

@@ -0,0 +1,928 @@
+"""Code Knowledge Graph - Phase 1.
+
+Builds a queryable map of the codebase using Tree-sitter, NetworkX, and SQLite.
+Tracks what calls what, what imports what, what inherits from what.
+
+Schema:
+- Node types: Module (file), Class, Function (methods distinguished by parent_class attribute)
+- Edge types: imports (Module→Module), calls (Function→Function), inherits (Class→Class),
+  defines (Module→Class, Module→Function, Class→Function)
+
+Sync model:
+- SQLite is source of truth
+- On session start: load full graph from SQLite into in-memory NetworkX MultiDiGraph
+- All reads during session hit in-memory graph only
+- All writes write to SQLite AND patch in-memory graph (never let them drift)
+
+Invalidation:
+- Wholesale per-file replace (not incremental diffing)
+- On file save: delete all nodes for that file, re-parse, re-insert, re-resolve
+
+Cross-file resolution:
+- Build module path index first
+- Look up imports in index
+- Never resolve by name-similarity guessing
+- External packages recorded as metadata on unresolved edges
+"""
+from __future__ import annotations
+
+import ast
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+import networkx as nx
+
+
+# --------------------------------------------------------------------------- #
+# Dataclasses
+# --------------------------------------------------------------------------- #
+@dataclass
+class Node:
+    id: str
+    type: str  # Module, Class, Function
+    name: str
+    qualified_name: str
+    file_path: str
+    line_start: int
+    line_end: int
+    language: str
+    parent_class: Optional[str] = None  # For methods
+
+
+@dataclass
+class Edge:
+    id: str
+    source_id: str
+    target_id: str
+    type: str  # imports, calls, inherits, defines
+    resolved: bool
+    raw_reference: Optional[str] = None
+
+
+# --------------------------------------------------------------------------- #
+# Graph Database
+# --------------------------------------------------------------------------- #
+class GraphDB:
+    """SQLite persistence for the code knowledge graph."""
+
+    def __init__(self, db_path: str):
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn: Optional[sqlite3.Connection] = None
+        self._init_db()
+
+    def _init_db(self) -> None:
+        """Initialize SQLite schema with WAL mode for concurrency."""
+        conn = self._get_conn()
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS nodes (
+                id TEXT PRIMARY KEY,
+                type TEXT NOT NULL,
+                name TEXT NOT NULL,
+                qualified_name TEXT NOT NULL,
+                file_path TEXT NOT NULL,
+                line_start INTEGER NOT NULL,
+                line_end INTEGER NOT NULL,
+                language TEXT NOT NULL,
+                parent_class TEXT
+            )
+        """)
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS edges (
+                id TEXT PRIMARY KEY,
+                source_id TEXT NOT NULL,
+                target_id TEXT NOT NULL,
+                type TEXT NOT NULL,
+                resolved BOOLEAN NOT NULL,
+                raw_reference TEXT,
+                FOREIGN KEY (source_id) REFERENCES nodes(id),
+                FOREIGN KEY (target_id) REFERENCES nodes(id)
+            )
+        """)
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file_path)")
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id)")
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id)")
+        conn.commit()
+
+    def _get_conn(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self._conn = sqlite3.connect(self.db_path)
+        return self._conn
+
+    def close(self) -> None:
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    def insert_node(self, node: Node) -> None:
+        conn = self._get_conn()
+        conn.execute(
+            """
+            INSERT OR REPLACE INTO nodes
+            (id, type, name, qualified_name, file_path, line_start, line_end, language, parent_class)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                node.id,
+                node.type,
+                node.name,
+                node.qualified_name,
+                node.file_path,
+                node.line_start,
+                node.line_end,
+                node.language,
+                node.parent_class,
+            ),
+        )
+        conn.commit()
+
+    def insert_edge(self, edge: Edge) -> None:
+        conn = self._get_conn()
+        conn.execute(
+            """
+            INSERT OR REPLACE INTO edges
+            (id, source_id, target_id, type, resolved, raw_reference)
+            VALUES (?, ?, ?, ?, ?, ?)
+            """,
+            (edge.id, edge.source_id, edge.target_id, edge.type, edge.resolved, edge.raw_reference),
+        )
+        conn.commit()
+
+    def delete_nodes_for_file(self, file_path: str) -> list[str]:
+        """Delete all nodes for a file and return their IDs."""
+        conn = self._get_conn()
+        cursor = conn.execute("SELECT id FROM nodes WHERE file_path = ?", (file_path,))
+        node_ids = [row[0] for row in cursor.fetchall()]
+        if node_ids:
+            placeholders = ",".join("?" * len(node_ids))
+            conn.execute(f"DELETE FROM edges WHERE source_id IN ({placeholders})", node_ids)
+            conn.execute(f"DELETE FROM edges WHERE target_id IN ({placeholders})", node_ids)
+            conn.execute("DELETE FROM nodes WHERE file_path = ?", (file_path,))
+            conn.commit()
+        return node_ids
+
+    def load_all_nodes(self) -> list[Node]:
+        conn = self._get_conn()
+        cursor = conn.execute("SELECT * FROM nodes")
+        nodes = []
+        for row in cursor.fetchall():
+            nodes.append(
+                Node(
+                    id=row[0],
+                    type=row[1],
+                    name=row[2],
+                    qualified_name=row[3],
+                    file_path=row[4],
+                    line_start=row[5],
+                    line_end=row[6],
+                    language=row[7],
+                    parent_class=row[8],
+                )
+            )
+        return nodes
+
+    def load_all_edges(self) -> list[Edge]:
+        conn = self._get_conn()
+        cursor = conn.execute("SELECT * FROM edges")
+        edges = []
+        for row in cursor.fetchall():
+            edges.append(
+                Edge(
+                    id=row[0],
+                    source_id=row[1],
+                    target_id=row[2],
+                    type=row[3],
+                    resolved=bool(row[4]),
+                    raw_reference=row[5],
+                )
+            )
+        return edges
+
+    def get_unresolved_edges_targeting_module(self, module_path: str) -> list[Edge]:
+        """Get unresolved edges that might resolve to a module path."""
+        conn = self._get_conn()
+        cursor = conn.execute(
+            """
+            SELECT * FROM edges
+            WHERE resolved = 0 AND raw_reference LIKE ?
+            """,
+            (f"%{module_path}%",),
+        )
+        edges = []
+        for row in cursor.fetchall():
+            edges.append(
+                Edge(
+                    id=row[0],
+                    source_id=row[1],
+                    target_id=row[2],
+                    type=row[3],
+                    resolved=bool(row[4]),
+                    raw_reference=row[5],
+                )
+            )
+        return edges
+
+
+# --------------------------------------------------------------------------- #
+# In-Memory Graph
+# --------------------------------------------------------------------------- #
+class CodeGraph:
+    """In-memory NetworkX MultiDiGraph wrapper for fast queries."""
+
+    def __init__(self):
+        self.graph: nx.MultiDiGraph = nx.MultiDiGraph()
+        self.node_by_id: dict[str, Node] = {}
+        self.edge_by_id: dict[str, Edge] = {}
+
+    def add_node(self, node: Node) -> None:
+        self.graph.add_node(
+            node.id,
+            type=node.type,
+            name=node.name,
+            qualified_name=node.qualified_name,
+            file_path=node.file_path,
+            line_start=node.line_start,
+            line_end=node.line_end,
+            language=node.language,
+            parent_class=node.parent_class,
+        )
+        self.node_by_id[node.id] = node
+
+    def add_edge(self, edge: Edge) -> None:
+        # Only add edge to graph if both source and target exist
+        # Unresolved edges with empty target_id are stored in edge_by_id but not in graph
+        if edge.target_id and edge.source_id:
+            self.graph.add_edge(
+                edge.source_id,
+                edge.target_id,
+                key=edge.id,
+                type=edge.type,
+                resolved=edge.resolved,
+                raw_reference=edge.raw_reference,
+            )
+        self.edge_by_id[edge.id] = edge
+
+    def remove_nodes(self, node_ids: list[str]) -> None:
+        for nid in node_ids:
+            if nid in self.graph:
+                self.graph.remove_node(nid)
+                self.node_by_id.pop(nid, None)
+        # Remove edges
+        to_remove = [eid for eid, e in self.edge_by_id.items() if e.source_id in node_ids or e.target_id in node_ids]
+        for eid in to_remove:
+            self.edge_by_id.pop(eid, None)
+
+    def get_node(self, node_id: str) -> Optional[Node]:
+        return self.node_by_id.get(node_id)
+
+    def get_neighbors(self, node_id: str, edge_type: Optional[str] = None, direction: str = "out") -> list[Node]:
+        """Get neighboring nodes. direction: 'out', 'in', or 'both'."""
+        if node_id not in self.graph:
+            return []
+        neighbors = []
+        if direction in ("out", "both"):
+            for _, target, key, data in self.graph.out_edges(node_id, keys=True, data=True):
+                if edge_type is None or data.get("type") == edge_type:
+                    node = self.node_by_id.get(target)
+                    if node:
+                        neighbors.append(node)
+        if direction in ("in", "both"):
+            for source, _, key, data in self.graph.in_edges(node_id, keys=True, data=True):
+                if edge_type is None or data.get("type") == edge_type:
+                    node = self.node_by_id.get(source)
+                    if node:
+                        neighbors.append(node)
+        return neighbors
+
+    def get_nodes_by_file(self, file_path: str) -> list[Node]:
+        return [n for n in self.node_by_id.values() if n.file_path == file_path]
+
+    def get_nodes_by_type(self, node_type: str) -> list[Node]:
+        return [n for n in self.node_by_id.values() if n.type == node_type]
+
+    def find_nodes_by_name(self, name: str, node_type: Optional[str] = None) -> list[Node]:
+        candidates = [n for n in self.node_by_id.values() if n.name == name]
+        if node_type:
+            candidates = [n for n in candidates if n.type == node_type]
+        return candidates
+
+
+# --------------------------------------------------------------------------- #
+# Module Path Index
+# --------------------------------------------------------------------------- #
+class ModulePathIndex:
+    """Index of importable module paths for cross-file resolution."""
+
+    def __init__(self, workspace: str):
+        self.workspace = Path(workspace)
+        self.index: dict[str, str] = {}  # module_path -> file_path
+
+    def build(self) -> None:
+        """Build the module path index for Python."""
+        self.index.clear()
+        self._build_python_index()
+
+    def _build_python_index(self) -> None:
+        """Build Python module index respecting package boundaries."""
+        for py_file in self.workspace.rglob("*.py"):
+            if "__pycache__" in str(py_file) or ".venv" in str(py_file):
+                continue
+            rel_path = py_file.relative_to(self.workspace)
+            # Convert to module path
+            parts = list(rel_path.parts)
+            if parts[-1] == "__init__.py":
+                # Package directory
+                if len(parts) > 1:
+                    module_path = ".".join(parts[:-1])
+                else:
+                    # Root __init__.py - use directory name
+                    module_path = parts[0].replace(".py", "")
+            else:
+                # Module file
+                if parts[-1].endswith(".py"):
+                    parts[-1] = parts[-1][:-3]
+                module_path = ".".join(parts)
+            if module_path:
+                self.index[module_path] = str(py_file)
+
+    def resolve(self, import_path: str) -> Optional[str]:
+        """Resolve an import path to a file path, or None if not found."""
+        # Direct match
+        if import_path in self.index:
+            return self.index[import_path]
+        # Try relative resolution (e.g., "package.module" -> "package.module.submodule")
+        for key, path in self.index.items():
+            if key == import_path or key.startswith(import_path + "."):
+                return path
+        return None
+
+
+# --------------------------------------------------------------------------- #
+# Python Parser (Tree-sitter with AST fallback)
+# --------------------------------------------------------------------------- #
+class PythonParser:
+    """Parse Python files using Tree-sitter, with AST fallback."""
+
+    def __init__(self):
+        self._parser = None
+        self._language = None
+        self._use_ast_fallback = False
+
+    def _get_parser(self):
+        """Lazy-load Tree-sitter parser."""
+        if self._use_ast_fallback:
+            return None
+        if self._parser is None:
+            try:
+                import tree_sitter_python as tspython
+                from tree_sitter import Language, Parser
+
+                self._language = Language(tspython.language())
+                self._parser = Parser()
+                self._parser.set_language(self._language)
+            except ImportError:
+                # Tree-sitter not installed, use AST fallback
+                self._use_ast_fallback = True
+                return None
+        return self._parser
+
+    def parse_file(self, file_path: str) -> tuple[list[Node], list[Edge]]:
+        """Parse a Python file and extract nodes/edges."""
+        parser = self._get_parser()
+        if parser is not None:
+            return self._parse_with_tree_sitter(file_path)
+        else:
+            return self._parse_with_ast(file_path)
+
+    def _parse_with_tree_sitter(self, file_path: str) -> tuple[list[Node], list[Edge]]:
+        """Parse using Tree-sitter."""
+        try:
+            source = Path(file_path).read_text(encoding="utf-8")
+        except Exception:
+            return [], []
+
+        tree = self._parser.parse(source.encode("utf-8"))
+        nodes: list[Node] = []
+        edges: list[Edge] = []
+
+        # Extract module node
+        module_id = f"module:{file_path}"
+        module_node = Node(
+            id=module_id,
+            type="Module",
+            name=Path(file_path).stem,
+            qualified_name=Path(file_path).stem,
+            file_path=file_path,
+            line_start=1,
+            line_end=source.count("\n") + 1,
+            language="python",
+        )
+        nodes.append(module_node)
+
+        # Walk the AST
+        self._extract_nodes_and_edges_ts(tree.root_node, file_path, module_id, nodes, edges)
+
+        return nodes, edges
+
+    def _parse_with_ast(self, file_path: str) -> tuple[list[Node], list[Edge]]:
+        """Parse using Python's built-in ast module."""
+        import ast
+
+        try:
+            source = Path(file_path).read_text(encoding="utf-8")
+        except Exception:
+            return [], []
+
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            return [], []
+
+        nodes: list[Node] = []
+        edges: list[Edge] = []
+
+        # Extract module node
+        module_id = f"module:{file_path}"
+        module_node = Node(
+            id=module_id,
+            type="Module",
+            name=Path(file_path).stem,
+            qualified_name=Path(file_path).stem,
+            file_path=file_path,
+            line_start=1,
+            line_end=len(source.splitlines()),
+            language="python",
+        )
+        nodes.append(module_node)
+
+        # Walk the AST
+        self._extract_nodes_and_edges_ast(tree, file_path, module_id, nodes, edges)
+
+        return nodes, edges
+
+    def _extract_nodes_and_edges_ts(
+        self,
+        node,
+        file_path: str,
+        module_id: str,
+        nodes: list[Node],
+        edges: list[Edge],
+        parent_class: Optional[str] = None,
+    ) -> None:
+        """Recursively extract nodes and edges from Tree-sitter AST."""
+        if node.type == "function_definition":
+            func_node = self._extract_function_ts(node, file_path, parent_class)
+            if func_node:
+                nodes.append(func_node)
+                edges.append(
+                    Edge(
+                        id=f"edge:{module_id}->{func_node.id}",
+                        source_id=module_id,
+                        target_id=func_node.id,
+                        type="defines",
+                        resolved=True,
+                    )
+                )
+                # Extract calls within function
+                self._extract_calls_ts(node, func_node.id, edges)
+
+        elif node.type == "class_definition":
+            class_node = self._extract_class_ts(node, file_path)
+            if class_node:
+                nodes.append(class_node)
+                edges.append(
+                    Edge(
+                        id=f"edge:{module_id}->{class_node.id}",
+                        source_id=module_id,
+                        target_id=class_node.id,
+                        type="defines",
+                        resolved=True,
+                    )
+                )
+                # Extract inheritance
+                self._extract_inheritance_ts(node, class_node.id, edges)
+                # Recurse into class body
+                for child in node.children:
+                    self._extract_nodes_and_edges_ts(child, file_path, module_id, nodes, edges, parent_class=class_node.name)
+
+        elif node.type == "import_statement":
+            self._extract_import_ts(node, module_id, edges)
+
+        elif node.type == "import_from_statement":
+            self._extract_import_from_ts(node, module_id, edges)
+
+        # Recurse into children
+        for child in node.children:
+            self._extract_nodes_and_edges_ts(child, file_path, module_id, nodes, edges, parent_class)
+
+    def _extract_nodes_and_edges_ast(
+        self,
+        node: ast.AST,
+        file_path: str,
+        module_id: str,
+        nodes: list[Node],
+        edges: list[Edge],
+        parent_class: Optional[str] = None,
+    ) -> None:
+        """Recursively extract nodes and edges from Python AST."""
+        if isinstance(node, ast.FunctionDef):
+            func_node = self._extract_function_ast(node, file_path, parent_class)
+            if func_node:
+                nodes.append(func_node)
+                edges.append(
+                    Edge(
+                        id=f"edge:{module_id}->{func_node.id}",
+                        source_id=module_id,
+                        target_id=func_node.id,
+                        type="defines",
+                        resolved=True,
+                    )
+                )
+                # Extract calls within function
+                self._extract_calls_ast(node, func_node.id, edges)
+
+        elif isinstance(node, ast.ClassDef):
+            class_node = self._extract_class_ast(node, file_path)
+            if class_node:
+                nodes.append(class_node)
+                edges.append(
+                    Edge(
+                        id=f"edge:{module_id}->{class_node.id}",
+                        source_id=module_id,
+                        target_id=class_node.id,
+                        type="defines",
+                        resolved=True,
+                    )
+                )
+                # Extract inheritance
+                self._extract_inheritance_ast(node, class_node.id, edges)
+                # Recurse into class body
+                for child in node.body:
+                    self._extract_nodes_and_edges_ast(child, file_path, module_id, nodes, edges, parent_class=class_node.name)
+
+        elif isinstance(node, ast.Import):
+            self._extract_import_ast(node, module_id, edges)
+
+        elif isinstance(node, ast.ImportFrom):
+            self._extract_import_from_ast(node, module_id, edges)
+
+        # Recurse into children
+        for child in ast.iter_child_nodes(node):
+            self._extract_nodes_and_edges_ast(child, file_path, module_id, nodes, edges, parent_class)
+
+    def _extract_function_ts(self, node, file_path: str, parent_class: Optional[str]) -> Optional[Node]:
+        """Extract a function node from Tree-sitter."""
+        name_node = node.child_by_field_name("name")
+        if not name_node:
+            return None
+        name = name_node.text.decode("utf-8")
+        qualified_name = f"{parent_class}.{name}" if parent_class else name
+        return Node(
+            id=f"function:{file_path}:{qualified_name}",
+            type="Function",
+            name=name,
+            qualified_name=qualified_name,
+            file_path=file_path,
+            line_start=node.start_point[0] + 1,
+            line_end=node.end_point[0] + 1,
+            language="python",
+            parent_class=parent_class,
+        )
+
+    def _extract_function_ast(self, node: ast.FunctionDef, file_path: str, parent_class: Optional[str]) -> Optional[Node]:
+        """Extract a function node from AST."""
+        name = node.name
+        qualified_name = f"{parent_class}.{name}" if parent_class else name
+        return Node(
+            id=f"function:{file_path}:{qualified_name}",
+            type="Function",
+            name=name,
+            qualified_name=qualified_name,
+            file_path=file_path,
+            line_start=node.lineno,
+            line_end=node.end_lineno if node.end_lineno else node.lineno,
+            language="python",
+            parent_class=parent_class,
+        )
+
+    def _extract_class_ts(self, node, file_path: str) -> Optional[Node]:
+        """Extract a class node from Tree-sitter."""
+        name_node = node.child_by_field_name("name")
+        if not name_node:
+            return None
+        name = name_node.text.decode("utf-8")
+        return Node(
+            id=f"class:{file_path}:{name}",
+            type="Class",
+            name=name,
+            qualified_name=name,
+            file_path=file_path,
+            line_start=node.start_point[0] + 1,
+            line_end=node.end_point[0] + 1,
+            language="python",
+        )
+
+    def _extract_class_ast(self, node: ast.ClassDef, file_path: str) -> Optional[Node]:
+        """Extract a class node from AST."""
+        name = node.name
+        return Node(
+            id=f"class:{file_path}:{name}",
+            type="Class",
+            name=name,
+            qualified_name=name,
+            file_path=file_path,
+            line_start=node.lineno,
+            line_end=node.end_lineno if node.end_lineno else node.lineno,
+            language="python",
+        )
+
+    def _extract_calls_ts(self, node, source_id: str, edges: list[Edge]) -> None:
+        """Extract function calls within a node (Tree-sitter)."""
+        if node.type == "call":
+            func_node = node.child_by_field_name("function")
+            if func_node:
+                func_name = func_node.text.decode("utf-8")
+                # Create unresolved edge - will be resolved later
+                edges.append(
+                    Edge(
+                        id=f"edge:call:{source_id}:{func_name}",
+                        source_id=source_id,
+                        target_id="",  # Will be resolved
+                        type="calls",
+                        resolved=False,
+                        raw_reference=func_name,
+                    )
+                )
+        for child in node.children:
+            self._extract_calls_ts(child, source_id, edges)
+
+    def _extract_calls_ast(self, node: ast.FunctionDef, source_id: str, edges: list[Edge]) -> None:
+        """Extract function calls within a node (AST)."""
+        for child in ast.walk(node):
+            if isinstance(child, ast.Call):
+                func_name = None
+                if isinstance(child.func, ast.Name):
+                    func_name = child.func.id
+                elif isinstance(child.func, ast.Attribute):
+                    func_name = child.func.attr
+                if func_name:
+                    edges.append(
+                        Edge(
+                            id=f"edge:call:{source_id}:{func_name}",
+                            source_id=source_id,
+                            target_id="",  # Will be resolved
+                            type="calls",
+                            resolved=False,
+                            raw_reference=func_name,
+                        )
+                    )
+
+    def _extract_import_ts(self, node, source_id: str, edges: list[Edge]) -> None:
+        """Extract import statements (Tree-sitter)."""
+        for child in node.children:
+            if child.type == "dotted_name":
+                module_name = child.text.decode("utf-8")
+                edges.append(
+                    Edge(
+                        id=f"edge:import:{source_id}:{module_name}",
+                        source_id=source_id,
+                        target_id="",  # Will be resolved
+                        type="imports",
+                        resolved=False,
+                        raw_reference=module_name,
+                    )
+                )
+
+    def _extract_import_ast(self, node: ast.Import, source_id: str, edges: list[Edge]) -> None:
+        """Extract import statements (AST)."""
+        for alias in node.names:
+            module_name = alias.name
+            edges.append(
+                Edge(
+                    id=f"edge:import:{source_id}:{module_name}",
+                    source_id=source_id,
+                    target_id="",  # Will be resolved
+                    type="imports",
+                    resolved=False,
+                    raw_reference=module_name,
+                )
+            )
+
+    def _extract_import_from_ts(self, node, source_id: str, edges: list[Edge]) -> None:
+        """Extract from ... import statements (Tree-sitter)."""
+        for child in node.children:
+            if child.type == "dotted_name":
+                module_name = child.text.decode("utf-8")
+                edges.append(
+                    Edge(
+                        id=f"edge:import:{source_id}:{module_name}",
+                        source_id=source_id,
+                        target_id="",  # Will be resolved
+                        type="imports",
+                        resolved=False,
+                        raw_reference=module_name,
+                    )
+                )
+
+    def _extract_import_from_ast(self, node: ast.ImportFrom, source_id: str, edges: list[Edge]) -> None:
+        """Extract from ... import statements (AST)."""
+        if node.module:
+            module_name = node.module
+            edges.append(
+                Edge(
+                    id=f"edge:import:{source_id}:{module_name}",
+                    source_id=source_id,
+                    target_id="",  # Will be resolved
+                    type="imports",
+                    resolved=False,
+                    raw_reference=module_name,
+                )
+            )
+
+    def _extract_inheritance_ts(self, node, class_id: str, edges: list[Edge]) -> None:
+        """Extract class inheritance (Tree-sitter)."""
+        for child in node.children:
+            if child.type == "argument_list":
+                for arg in child.children:
+                    if arg.type == "identifier":
+                        parent_name = arg.text.decode("utf-8")
+                        edges.append(
+                            Edge(
+                                id=f"edge:inherits:{class_id}:{parent_name}",
+                                source_id=class_id,
+                                target_id="",  # Will be resolved
+                                type="inherits",
+                                resolved=False,
+                                raw_reference=parent_name,
+                            )
+                        )
+
+    def _extract_inheritance_ast(self, node: ast.ClassDef, class_id: str, edges: list[Edge]) -> None:
+        """Extract class inheritance (AST)."""
+        for base in node.bases:
+            if isinstance(base, ast.Name):
+                parent_name = base.id
+                edges.append(
+                    Edge(
+                        id=f"edge:inherits:{class_id}:{parent_name}",
+                        source_id=class_id,
+                        target_id="",  # Will be resolved
+                        type="inherits",
+                        resolved=False,
+                        raw_reference=parent_name,
+                    )
+                )
+
+
+# --------------------------------------------------------------------------- #
+# Main Graph Manager
+# --------------------------------------------------------------------------- #
+class GraphManager:
+    """Main entry point for code knowledge graph operations."""
+
+    def __init__(self, workspace: str, db_path: str, languages: list[str]):
+        self.workspace = workspace
+        self.db = GraphDB(db_path)
+        self.graph = CodeGraph()
+        self.module_index = ModulePathIndex(workspace)
+        self.parser = PythonParser()
+        self.languages = languages
+        self._loaded = False
+
+    def load(self) -> None:
+        """Load the full graph from SQLite into memory."""
+        if self._loaded:
+            return
+        nodes = self.db.load_all_nodes()
+        edges = self.db.load_all_edges()
+        for node in nodes:
+            self.graph.add_node(node)
+        for edge in edges:
+            self.graph.add_edge(edge)
+        self._loaded = True
+
+    def build_initial(self) -> None:
+        """Build the initial graph for the workspace."""
+        self.module_index.build()
+        self._build_graph()
+        self.load()
+
+    def _build_graph(self) -> None:
+        """Build graph by parsing all supported language files."""
+        if "python" in self.languages or not self.languages:
+            self._build_python_graph()
+
+    def _build_python_graph(self) -> None:
+        """Build graph for Python files."""
+        workspace_path = Path(self.workspace)
+        for py_file in workspace_path.rglob("*.py"):
+            if "__pycache__" in str(py_file) or ".venv" in str(py_file):
+                continue
+            self._update_file(str(py_file))
+        # Resolve cross-file references
+        self._resolve_cross_file_references()
+
+    def _update_file(self, file_path: str) -> None:
+        """Update graph for a single file (wholesale replace)."""
+        # Delete existing nodes/edges for this file
+        deleted_ids = self.db.delete_nodes_for_file(file_path)
+        if deleted_ids:
+            self.graph.remove_nodes(deleted_ids)
+
+        # Parse file
+        nodes, edges = self.parser.parse_file(file_path)
+
+        # Insert into DB and in-memory graph
+        for node in nodes:
+            self.db.insert_node(node)
+            self.graph.add_node(node)
+        for edge in edges:
+            self.db.insert_edge(edge)
+            self.graph.add_edge(edge)
+
+    def _resolve_cross_file_references(self) -> None:
+        """Resolve cross-file import/call/inheritance references."""
+        # Resolve imports
+        for edge in list(self.graph.edge_by_id.values()):
+            if not edge.resolved and edge.type in ("imports", "calls", "inherits"):
+                target_path = self.module_index.resolve(edge.raw_reference or "")
+                if target_path:
+                    # Find target node
+                    target_node = self._find_target_node(edge.raw_reference or "", target_path, edge.type)
+                    if target_node:
+                        # Update edge
+                        edge.target_id = target_node.id
+                        edge.resolved = True
+                        self.db.insert_edge(edge)
+                        # Add the resolved edge to the in-memory graph
+                        self.graph.graph.add_edge(
+                            edge.source_id,
+                            edge.target_id,
+                            key=edge.id,
+                            type=edge.type,
+                            resolved=edge.resolved,
+                            raw_reference=edge.raw_reference,
+                        )
+
+    def _find_target_node(self, reference: str, file_path: str, edge_type: str) -> Optional[Node]:
+        """Find a target node by reference and file path."""
+        nodes_in_file = self.graph.get_nodes_by_file(file_path)
+        if edge_type == "imports":
+            # For imports, find the module node
+            for node in nodes_in_file:
+                if node.type == "Module":
+                    return node
+        elif edge_type == "calls":
+            # For calls, find a function with matching name
+            ref_name = reference.split(".")[-1]
+            for node in nodes_in_file:
+                if node.type == "Function" and node.name == ref_name:
+                    return node
+        elif edge_type == "inherits":
+            # For inheritance, find a class with matching name
+            for node in nodes_in_file:
+                if node.type == "Class" and node.name == reference:
+                    return node
+        return None
+
+    def invalidate_file(self, file_path: str) -> None:
+        """Invalidate and re-parse a file."""
+        self._update_file(file_path)
+        self._resolve_cross_file_references()
+
+    def query_neighbors(self, node_id: str, hop_limit: int = 1, edge_types: Optional[list[str]] = None) -> list[Node]:
+        """Query neighbors up to hop_limit."""
+        if hop_limit < 1:
+            return []
+        visited = {node_id}
+        current_level = {node_id}
+        result = []
+
+        for hop in range(hop_limit):
+            next_level = set()
+            for nid in current_level:
+                neighbors = self.graph.get_neighbors(nid, edge_type=None, direction="out")
+                for neighbor in neighbors:
+                    if neighbor.id not in visited:
+                        visited.add(neighbor.id)
+                        next_level.add(neighbor.id)
+                        result.append(neighbor)
+            current_level = next_level
+            if not current_level:
+                break
+
+        return result
+
+    def get_node_by_qualified_name(self, qualified_name: str) -> Optional[Node]:
+        """Find a node by its qualified name."""
+        for node in self.graph.node_by_id.values():
+            if node.qualified_name == qualified_name:
+                return node
+        return None
+
+    def close(self) -> None:
+        """Clean up resources."""
+        self.db.close()