vortexa 0.3.3__tar.gz → 0.3.5__tar.gz

{vortexa-0.3.3 → vortexa-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortexa
-Version: 0.3.3
+Version: 0.3.5
 Summary: Codebase indexing and semantic search engine
 Author-email: VortexAI <koulabhay25@gmail.com>
 License-Expression: Apache-2.0
@@ -63,6 +63,7 @@ _Dense + sparse hybrid retrieval · AST-aware chunking · LMDB persistence · MC
 - [CLI Search](#cli-search)
 - [MCP Server](#mcp-server)
   - [Usage with Claude Code / Cursor](#usage-with-claude-code--cursor)
+- [Agent Skill](#agent-skill)
 - [Architecture](#architecture)
 - [Dependencies](#dependencies)
 - [License](#license)
@@ -77,7 +78,7 @@ _Dense + sparse hybrid retrieval · AST-aware chunking · LMDB persistence · MC
 
 vortexa is a standalone **codebase indexing and semantic search engine** designed for AI agents and developers. It builds a persistent, hybrid search index over source code using:
 
-- **Dense retrieval** via VortexEmbedderV4 (on-the-fly LF4 4-bit dequant, SIF+PC, Matryoshka) or static embeddings (Model2Vec / SentenceTransformers)
+- **Dense retrieval** via VortexEmbedderV4 (native LF2/LF4 dequant, SIF+PC, Matryoshka) or static embeddings (Model2Vec / SentenceTransformers)
 - **Sparse retrieval** via BM25 keyword scoring
 - **AST-aware chunking** that respects function and class boundaries via tree-sitter
 - **LMDB-backed storage** for fast, persistent vector and chunk storage
@@ -126,7 +127,7 @@ vortexa can run as a **standalone Python library**, be embedded into any agent,
 </tr>
 <tr>
 <td><strong>MCP server</strong></td>
-<td>Expose as a single <code>search</code> tool for any MCP-compatible agent (Claude Code, Cursor, etc.)</td>
+<td>Expose <code>search</code>, <code>resolve</code>, and <code>explain</code> tools for MCP-compatible agents (Claude Code, Cursor, etc.)</td>
 </tr>
 <tr>
 <td><strong>Zero mandatory heavy deps</strong></td>
@@ -310,7 +311,8 @@ Useful flags:
 | `--force` | Force a full re-index before searching. |
 | `--no-index` | Search the existing index only. |
 | `--plain` | Print human-readable results instead of JSON. |
-| `--model` | Embedding model ID or alias (`mini`, `nano`). Default: `mini`. |
+| `--model` | Embedding model ID or alias (`mini`, `nano`; both use LF2 by default). Use `mini-full` or `nano-full` for LF4. |
+| `-f`, `--fast` | Explicitly select LF2 for a full-model alias. The `mini` and `nano` aliases already use LF2. |
 
 By default CLI output is JSON:
 
@@ -338,14 +340,18 @@ vortexa-serve
 
 ## Model Configuration
 
-vortexa supports configurable embedding models. The default is `mini` (`VTXAI/vtx-embed-7M`).
+vortexa supports configurable embedding models. The default is `mini`
+(`VTXAI/vtx-embed-7M-lf2`), using the native LF2 2-bit checkpoint. Use
+`mini-full` or `nano-full` to select the original LF4 checkpoints.
 
 ### Available Models
 
 | Alias | Model ID | Description |
 |-------|----------|-------------|
-| `mini` | `VTXAI/vtx-embed-7M` | Default. 7M-parameter Vortex-Embed v4.5 with LF4 4-bit dequant, SIF+PC, Matryoshka. |
-| `nano` | `VTXAI/vtx-embed-1M` | Lightweight 1M-parameter variant. Lower RAM, lower dim. |
+| `mini` | `VTXAI/vtx-embed-7M-lf2` | Default native 2-bit 7M model. 256-dimensional embeddings. |
+| `nano` | `VTXAI/vtx-embed-1M-lf2` | Default native 2-bit 1M model. 64-dimensional embeddings. |
+| `mini-full` | `VTXAI/vtx-embed-7M` | Original LF4 checkpoint for maximum quality. |
+| `nano-full` | `VTXAI/vtx-embed-1M` | Original LF4 lightweight checkpoint. |
 
 ### CLI Usage
 
@@ -365,11 +371,14 @@ vortexa -q "authentication" --model VTXAI/vtx-embed-1M /path/to/project
 ```python
 from vortexa.core.indexer import CodebaseIndexer
 
-# Use nano model
-indexer = CodebaseIndexer(root="/path/to/project", model_id="VTXAI/vtx-embed-1M")
+# Use nano model (LF2 by default)
+indexer = CodebaseIndexer(root="/path/to/project", model_id="nano")
 
-# Use mini model (default)
-indexer = CodebaseIndexer(root="/path/to/project", model_id="VTXAI/vtx-embed-7M")
+# Use mini model (LF2 by default)
+indexer = CodebaseIndexer(root="/path/to/project", model_id="mini")
+
+# Opt into the original LF4 checkpoint
+indexer = CodebaseIndexer(root="/path/to/project", model_id="mini-full")
 ```
 
 ### Alternative Embedders
@@ -441,11 +450,17 @@ On startup it indexes the current working directory and prints stats to stderr:
 [vortexa] Auto-reindex watcher started (polling every 3s)
 ```
 
-The server exposes one tool:
+The server exposes three tools:
 
 | Tool | Description | Arguments |
 |------|-------------|-----------|
 | `search` | Semantic + BM25 hybrid code search | `query` (str), `top_k` (int, default 10) |
+| `resolve` | Feature-level search with graph context, tests, imports, callers, and callees | `query` (str), `top_k` (int, default 5) |
+| `explain` | Explain a file, `file:line` location, or symbol | `location` (str) |
+
+Use `search` for discovery, `resolve` when you need feature context, and
+`explain` when the file or symbol is already known. The server indexes the
+current directory and auto-reindexes it while running.
 
 ### Usage with Claude Code / Cursor
 
@@ -469,6 +484,36 @@ The agent will now have access to semantic code search — it can find functions
 
 <div align="center">
 
+## Agent Skill
+
+</div>
+
+Vortexa ships with an Agent Skills-compatible skill at
+[`skills/vortexa/SKILL.md`](skills/vortexa/SKILL.md). It teaches compatible
+agents when to prefer Vortexa, how to choose between `search`, `resolve`, and
+`explain`, and how to interpret returned file paths, line ranges, scores, and
+graph context.
+
+The skill follows the standard `SKILL.md` structure: YAML frontmatter with a
+lowercase hyphenated name and trigger-oriented description, followed by
+workflow instructions. Copy or link the `skills/vortexa` directory into the
+skills directory used by your agent environment.
+
+```markdown
+---
+name: vortexa
+description: Use Vortexa to index and semantically search local codebases...
+---
+```
+
+Use the installed MCP server when available; otherwise the same workflow is
+available through the `vortexa search`, `vortexa resolve`, and
+`vortexa explain` commands.
+
+---
+
+<div align="center">
+
 ## Architecture
 
 </div>
@@ -613,7 +658,7 @@ graph TD
 | `bm25s` | Yes | Fast BM25 keyword index and persistence |
 | `pathspec` | Yes | `.gitignore` pattern matching in file walker |
 | `model2vec` | Optional | Alternative static embeddings |
-| `huggingface-hub` | Yes (default model) | Loading `VTXAI/vtx-embed-7M` (mini) or `VTXAI/vtx-embed-1M` (nano) |
+| `huggingface-hub` | Yes (default model) | Loading LF2 defaults (`VTXAI/vtx-embed-7M-lf2`, `VTXAI/vtx-embed-1M-lf2`) |
 | `tokenizers` | Yes (default model) | HF tokenizer for embedding model |
 | `safetensors` | Yes (default model) | Safe tensor loading for 4-bit weights |
 | `sentence-transformers` | Optional | Transformer-based dense embeddings |

{vortexa-0.3.3 → vortexa-0.3.5}/README.md

@@ -28,6 +28,7 @@ _Dense + sparse hybrid retrieval · AST-aware chunking · LMDB persistence · MC
 - [CLI Search](#cli-search)
 - [MCP Server](#mcp-server)
   - [Usage with Claude Code / Cursor](#usage-with-claude-code--cursor)
+- [Agent Skill](#agent-skill)
 - [Architecture](#architecture)
 - [Dependencies](#dependencies)
 - [License](#license)
@@ -42,7 +43,7 @@ _Dense + sparse hybrid retrieval · AST-aware chunking · LMDB persistence · MC
 
 vortexa is a standalone **codebase indexing and semantic search engine** designed for AI agents and developers. It builds a persistent, hybrid search index over source code using:
 
-- **Dense retrieval** via VortexEmbedderV4 (on-the-fly LF4 4-bit dequant, SIF+PC, Matryoshka) or static embeddings (Model2Vec / SentenceTransformers)
+- **Dense retrieval** via VortexEmbedderV4 (native LF2/LF4 dequant, SIF+PC, Matryoshka) or static embeddings (Model2Vec / SentenceTransformers)
 - **Sparse retrieval** via BM25 keyword scoring
 - **AST-aware chunking** that respects function and class boundaries via tree-sitter
 - **LMDB-backed storage** for fast, persistent vector and chunk storage
@@ -91,7 +92,7 @@ vortexa can run as a **standalone Python library**, be embedded into any agent,
 </tr>
 <tr>
 <td><strong>MCP server</strong></td>
-<td>Expose as a single <code>search</code> tool for any MCP-compatible agent (Claude Code, Cursor, etc.)</td>
+<td>Expose <code>search</code>, <code>resolve</code>, and <code>explain</code> tools for MCP-compatible agents (Claude Code, Cursor, etc.)</td>
 </tr>
 <tr>
 <td><strong>Zero mandatory heavy deps</strong></td>
@@ -275,7 +276,8 @@ Useful flags:
 | `--force` | Force a full re-index before searching. |
 | `--no-index` | Search the existing index only. |
 | `--plain` | Print human-readable results instead of JSON. |
-| `--model` | Embedding model ID or alias (`mini`, `nano`). Default: `mini`. |
+| `--model` | Embedding model ID or alias (`mini`, `nano`; both use LF2 by default). Use `mini-full` or `nano-full` for LF4. |
+| `-f`, `--fast` | Explicitly select LF2 for a full-model alias. The `mini` and `nano` aliases already use LF2. |
 
 By default CLI output is JSON:
 
@@ -303,14 +305,18 @@ vortexa-serve
 
 ## Model Configuration
 
-vortexa supports configurable embedding models. The default is `mini` (`VTXAI/vtx-embed-7M`).
+vortexa supports configurable embedding models. The default is `mini`
+(`VTXAI/vtx-embed-7M-lf2`), using the native LF2 2-bit checkpoint. Use
+`mini-full` or `nano-full` to select the original LF4 checkpoints.
 
 ### Available Models
 
 | Alias | Model ID | Description |
 |-------|----------|-------------|
-| `mini` | `VTXAI/vtx-embed-7M` | Default. 7M-parameter Vortex-Embed v4.5 with LF4 4-bit dequant, SIF+PC, Matryoshka. |
-| `nano` | `VTXAI/vtx-embed-1M` | Lightweight 1M-parameter variant. Lower RAM, lower dim. |
+| `mini` | `VTXAI/vtx-embed-7M-lf2` | Default native 2-bit 7M model. 256-dimensional embeddings. |
+| `nano` | `VTXAI/vtx-embed-1M-lf2` | Default native 2-bit 1M model. 64-dimensional embeddings. |
+| `mini-full` | `VTXAI/vtx-embed-7M` | Original LF4 checkpoint for maximum quality. |
+| `nano-full` | `VTXAI/vtx-embed-1M` | Original LF4 lightweight checkpoint. |
 
 ### CLI Usage
 
@@ -330,11 +336,14 @@ vortexa -q "authentication" --model VTXAI/vtx-embed-1M /path/to/project
 ```python
 from vortexa.core.indexer import CodebaseIndexer
 
-# Use nano model
-indexer = CodebaseIndexer(root="/path/to/project", model_id="VTXAI/vtx-embed-1M")
+# Use nano model (LF2 by default)
+indexer = CodebaseIndexer(root="/path/to/project", model_id="nano")
 
-# Use mini model (default)
-indexer = CodebaseIndexer(root="/path/to/project", model_id="VTXAI/vtx-embed-7M")
+# Use mini model (LF2 by default)
+indexer = CodebaseIndexer(root="/path/to/project", model_id="mini")
+
+# Opt into the original LF4 checkpoint
+indexer = CodebaseIndexer(root="/path/to/project", model_id="mini-full")
 ```
 
 ### Alternative Embedders
@@ -406,11 +415,17 @@ On startup it indexes the current working directory and prints stats to stderr:
 [vortexa] Auto-reindex watcher started (polling every 3s)
 ```
 
-The server exposes one tool:
+The server exposes three tools:
 
 | Tool | Description | Arguments |
 |------|-------------|-----------|
 | `search` | Semantic + BM25 hybrid code search | `query` (str), `top_k` (int, default 10) |
+| `resolve` | Feature-level search with graph context, tests, imports, callers, and callees | `query` (str), `top_k` (int, default 5) |
+| `explain` | Explain a file, `file:line` location, or symbol | `location` (str) |
+
+Use `search` for discovery, `resolve` when you need feature context, and
+`explain` when the file or symbol is already known. The server indexes the
+current directory and auto-reindexes it while running.
 
 ### Usage with Claude Code / Cursor
 
@@ -434,6 +449,36 @@ The agent will now have access to semantic code search — it can find functions
 
 <div align="center">
 
+## Agent Skill
+
+</div>
+
+Vortexa ships with an Agent Skills-compatible skill at
+[`skills/vortexa/SKILL.md`](skills/vortexa/SKILL.md). It teaches compatible
+agents when to prefer Vortexa, how to choose between `search`, `resolve`, and
+`explain`, and how to interpret returned file paths, line ranges, scores, and
+graph context.
+
+The skill follows the standard `SKILL.md` structure: YAML frontmatter with a
+lowercase hyphenated name and trigger-oriented description, followed by
+workflow instructions. Copy or link the `skills/vortexa` directory into the
+skills directory used by your agent environment.
+
+```markdown
+---
+name: vortexa
+description: Use Vortexa to index and semantically search local codebases...
+---
+```
+
+Use the installed MCP server when available; otherwise the same workflow is
+available through the `vortexa search`, `vortexa resolve`, and
+`vortexa explain` commands.
+
+---
+
+<div align="center">
+
 ## Architecture
 
 </div>
@@ -578,7 +623,7 @@ graph TD
 | `bm25s` | Yes | Fast BM25 keyword index and persistence |
 | `pathspec` | Yes | `.gitignore` pattern matching in file walker |
 | `model2vec` | Optional | Alternative static embeddings |
-| `huggingface-hub` | Yes (default model) | Loading `VTXAI/vtx-embed-7M` (mini) or `VTXAI/vtx-embed-1M` (nano) |
+| `huggingface-hub` | Yes (default model) | Loading LF2 defaults (`VTXAI/vtx-embed-7M-lf2`, `VTXAI/vtx-embed-1M-lf2`) |
 | `tokenizers` | Yes (default model) | HF tokenizer for embedding model |
 | `safetensors` | Yes (default model) | Safe tensor loading for 4-bit weights |
 | `sentence-transformers` | Optional | Transformer-based dense embeddings |

{vortexa-0.3.3 → vortexa-0.3.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortexa"
-version = "0.3.3"
+version = "0.3.5"
 description = "Codebase indexing and semantic search engine"
 readme = "README.md"
 requires-python = ">=3.10"

{vortexa-0.3.3 → vortexa-0.3.5}/src/vortexa/core/graph.py

@@ -92,6 +92,24 @@ class RepoGraph:
             return [e.dst if direction == "out" else e.src for e in edges if e.kind == kind]
         return [e.dst if direction == "out" else e.src for e in edges]
 
+    def edges_from(self, node_id: str, kind: Optional[str] = None) -> List[GraphEdge]:
+        return [e for e in self._out.get(node_id, []) if kind is None or e.kind == kind]
+
+    def edges_to(self, node_id: str, kind: Optional[str] = None) -> List[GraphEdge]:
+        return [e for e in self._in.get(node_id, []) if kind is None or e.kind == kind]
+
+    def find_file_node(self, file_path: str) -> Optional[GraphNode]:
+        for node in self.nodes.values():
+            if node.kind == "file" and node.path == file_path:
+                return node
+        return None
+
+    def find_nodes_in_file(self, file_path: str) -> List[GraphNode]:
+        return [self.nodes[nid] for nid in self._file_symbols.get(file_path, set()) if nid in self.nodes]
+
+    def find_nodes_by_name(self, name: str) -> List[GraphNode]:
+        return [self.nodes[nid] for nid in self._name_index.get(name, set()) if nid in self.nodes]
+
     def expand(self, seed_ids: List[str], max_hops: int = 2, max_size: int = 100) -> List[Tuple[str, int]]:
         """BFS from seed nodes, return (node_id, hop_count) pairs."""
         visited: Set[str] = set()
@@ -238,6 +256,7 @@ class RepoGraphBuilder:
                 candidates = self.graph.resolve_name(name)
                 for cid in candidates[:3]:  # limit candidates
                     self.graph.add_edge(file_id, cid, "REFERENCES", weight=0.3)
+                    self.graph.add_edge(file_id, cid, "CALLS", weight=0.3)
 
     def build(self, files: Dict[str, str]) -> RepoGraph:
         """Build the graph from a {path: content} dict."""

{vortexa-0.3.3 → vortexa-0.3.5}/src/vortexa/core/indexer.py

@@ -20,14 +20,17 @@ from typing import cast
 
 import lmdb
 import numpy as np
+
 from vortexa.core.chunking import chunk_source
 from vortexa.core.embedding import Embedder
+from vortexa.core.graph import RepoGraph
 from vortexa.core.language import detect_language, get_extensions
 from vortexa.core.types import (
     Chunk,
     ChunkConfig,
     Encoder,
     IndexStats,
+    SearchMode,
     SearchResult,
 )
 from vortexa.search.search import search as _search
@@ -84,7 +87,7 @@ class CodebaseIndexer:
         self,
         root: str | Path,
         model: Encoder | Embedder | None = None,
-        model_id: str = "VTXAI/vtx-embed-7M",
+        model_id: str = "VTXAI/vtx-embed-7M-lf2",
         index_dir: str | Path | None = None,
         chunk_config: ChunkConfig | None = None,
     ) -> None:
@@ -110,7 +113,7 @@ class CodebaseIndexer:
                 self._model = model
         else:
             from vortexa.core.v4_embedder import VortexEmbedderV4
-            self._embedder = VortexEmbedderV4(model_id or "VTXAI/vtx-embed-7M")
+            self._embedder = VortexEmbedderV4(model_id or "VTXAI/vtx-embed-7M-lf2")
             self._model = self._embedder
 
         # In-memory state
@@ -120,6 +123,7 @@ class CodebaseIndexer:
         self.chunk_memo: dict[str, str] = {}  # chunk_id -> chunk_hash (for memoization)
         self._vector_store: VectorStore | None = None
         self._bm25_index: BM25Index | None = None
+        self._repo_graph: RepoGraph | None = None
 
         # Stats
         self._memo_hits = 0
@@ -303,6 +307,283 @@ class CodebaseIndexer:
             alpha=alpha,
         )
 
+    # ── Context resolution ──────────────────────────────────────────────
+
+    def _build_repo_graph(self) -> RepoGraph:
+        """Build a repo graph from indexed Python files."""
+        from vortexa.core.graph import RepoGraphBuilder
+        builder = RepoGraphBuilder()
+        files: dict[str, str] = {}
+        for rel in self.file_hashes:
+            file_path = self.root / rel
+            if file_path.suffix == ".py":
+                try:
+                    files[rel] = file_path.read_text(encoding="utf-8", errors="replace")
+                except OSError:
+                    pass
+        return builder.build(files)
+
+    def _find_test_files(self, primary_files: set[str]) -> list[str]:
+        test_files: list[str] = []
+        for file_path in primary_files:
+            path = Path(file_path)
+            stem = path.stem
+            suffix = path.suffix
+            parent = path.parent
+            candidates = [
+                parent / f"test_{stem}{suffix}",
+                parent / f"{stem}_test{suffix}",
+            ]
+            for candidate in candidates:
+                candidate_str = str(candidate)
+                if candidate_str != file_path and candidate_str not in test_files:
+                    if candidate_str in self.file_hashes:
+                        test_files.append(candidate_str)
+        return test_files
+
+    def _find_imports_importers(
+        self, primary_files: set[str], graph: RepoGraph
+    ) -> tuple[list[str], list[str]]:
+        imports: list[str] = []
+        imported_by: list[str] = []
+        for file_path in primary_files:
+            file_node = graph.find_file_node(file_path)
+            if file_node is None:
+                continue
+            for edge in graph.edges_from(file_node.id, kind="IMPORTS"):
+                target = graph.nodes.get(edge.dst)
+                if target and target.path and target.path not in primary_files:
+                    if target.path not in imports:
+                        imports.append(target.path)
+            for edge in graph.edges_from(file_node.id, kind="IMPORTS_FROM"):
+                target = graph.nodes.get(edge.dst)
+                if target and target.path and target.path not in primary_files:
+                    if target.path not in imports:
+                        imports.append(target.path)
+            for edge in graph.edges_to(file_node.id, kind="IMPORTS"):
+                source = graph.nodes.get(edge.src)
+                if source and source.path and source.path not in primary_files:
+                    if source.path not in imported_by:
+                        imported_by.append(source.path)
+            for edge in graph.edges_to(file_node.id, kind="IMPORTS_FROM"):
+                source = graph.nodes.get(edge.src)
+                if source and source.path and source.path not in primary_files:
+                    if source.path not in imported_by:
+                        imported_by.append(source.path)
+        return imports, imported_by
+
+    def _find_symbols(self, primary_files: set[str], graph: RepoGraph) -> list[dict]:
+        symbols: list[dict] = []
+        seen: set[str] = set()
+        skip_kinds = {"file"}
+        for file_path in primary_files:
+            for node_id in graph._file_symbols.get(file_path, set()):
+                if node_id in seen:
+                    continue
+                seen.add(node_id)
+                node = graph.nodes.get(node_id)
+                if not node or node.kind in skip_kinds:
+                    continue
+                symbols.append({
+                    "name": node.name,
+                    "kind": node.kind,
+                    "file": node.path,
+                    "line": node.line,
+                })
+        return symbols[:15]
+
+    def _find_callers_callees(
+        self, primary_files: set[str], graph: RepoGraph
+    ) -> tuple[list[dict], list[dict]]:
+        callers: list[dict] = []
+        callees: list[dict] = []
+        for file_path in primary_files:
+            for node_id in graph._file_symbols.get(file_path, set()):
+                node = graph.nodes.get(node_id)
+                if not node:
+                    continue
+                for edge in graph.edges_from(node_id, kind="CALLS"):
+                    target = graph.nodes.get(edge.dst)
+                    if target and target.path != file_path:
+                        callees.append({
+                            "name": target.name,
+                            "file": target.path,
+                            "line": target.line,
+                        })
+                        break
+                for edge in graph.edges_to(node_id, kind="CALLS"):
+                    source = graph.nodes.get(edge.src)
+                    if source and source.path != file_path:
+                        callers.append({
+                            "name": source.name,
+                            "file": source.path,
+                            "line": source.line,
+                        })
+                        break
+        return callers[:10], callees[:10]
+
+    def _find_dependency_chain(
+        self, primary_files: set[str], graph: RepoGraph, depth: int = 1
+    ) -> list[str]:
+        chain: list[str] = []
+        visited: set[str] = set(primary_files)
+        for file_path in primary_files:
+            file_node = graph.find_file_node(file_path)
+            if file_node is None:
+                continue
+            expanded = graph.expand([file_node.id], max_hops=depth, max_size=50)
+            for nid, hop in expanded:
+                if hop == 0:
+                    continue
+                node = graph.nodes.get(nid)
+                if node and node.path and node.path not in visited:
+                    visited.add(node.path)
+                    chain.append(node.path)
+        return chain[:10]
+
+    def _expand_context(
+        self, query: str, primary: list[SearchResult], graph: RepoGraph
+    ) -> dict:
+        primary_files = {r.chunk.file_path for r in primary}
+        test_files = self._find_test_files(primary_files)
+        imports, imported_by = self._find_imports_importers(primary_files, graph)
+        symbols = self._find_symbols(primary_files, graph)
+        callers, callees = self._find_callers_callees(primary_files, graph)
+        dependency_chain = self._find_dependency_chain(primary_files, graph, depth=1)
+
+        scores = [r.score for r in primary if r.score > 0]
+        confidence = sum(scores) / len(scores) if scores else 0.0
+
+        related_files = list(
+            primary_files | set(imports) | set(imported_by) | set(test_files)
+        )
+
+        return {
+            "query": query,
+            "confidence": round(confidence, 3),
+            "primary_chunks": primary,
+            "related_files": related_files,
+            "test_files": test_files,
+            "imports": imports,
+            "imported_by": imported_by,
+            "symbols": symbols,
+            "callers": callers,
+            "callees": callees,
+            "dependency_chain": dependency_chain,
+            "total_tokens": sum(len(r.chunk.content) for r in primary) // 4,
+        }
+
+    def _compress_pack(self, pack: dict) -> dict:
+        if not pack.get("primary_chunks"):
+            return pack
+        pack = dict(pack)
+        pack["primary_chunks"] = pack["primary_chunks"][:10]
+        pack["related_files"] = pack["related_files"][:5]
+        pack["test_files"] = pack["test_files"][:3]
+        pack["imports"] = pack["imports"][:2]
+        pack["imported_by"] = pack["imported_by"][:1]
+        pack["symbols"] = pack["symbols"][:5]
+        pack["callers"] = pack["callers"][:2]
+        pack["callees"] = pack["callees"][:2]
+        pack["dependency_chain"] = pack["dependency_chain"][:3]
+        pack["total_tokens"] = sum(len(r.chunk.content) for r in pack["primary_chunks"]) // 4
+        return pack
+
+    def _empty_pack(self, query: str) -> dict:
+        return {
+            "query": query,
+            "confidence": 0.0,
+            "primary_chunks": [],
+            "related_files": [],
+            "test_files": [],
+            "imports": [],
+            "imported_by": [],
+            "symbols": [],
+            "callers": [],
+            "callees": [],
+            "dependency_chain": [],
+            "total_tokens": 0,
+        }
+
+    def resolve(self, query: str, top_k: int = 5) -> dict:
+        """Full context resolution: search + expand + compress."""
+        if not self.chunks:
+            return self._empty_pack(query)
+        primary = self.search(query, top_k=top_k)
+        if not primary:
+            return self._empty_pack(query)
+        graph = self._build_repo_graph()
+        pack = self._expand_context(query, primary, graph)
+        return self._compress_pack(pack)
+
+    def explain(self, code_location: str) -> dict:
+        """Explain a code location: find symbol, expand context, return pack."""
+        query = code_location
+        if ":" in code_location:
+            parts = code_location.rsplit(":", 1)
+            if parts[0].endswith(
+                (".py", ".js", ".ts", ".rs", ".go", ".java", ".jsx", ".tsx")
+            ):
+                file_path = parts[0]
+                try:
+                    line = int(parts[1])
+                except ValueError:
+                    line = 0
+                chunks_here = [c for c in self.chunks if c.file_path == file_path]
+                if line > 0:
+                    chunks_here = [
+                        c for c in chunks_here if c.start_line <= line <= c.end_line
+                    ]
+                if chunks_here:
+                    primary = [
+                        SearchResult(
+                            chunk=chunks_here[0], score=1.0, source=SearchMode.SEMANTIC
+                        )
+                    ]
+                    graph = self._build_repo_graph()
+                    pack = self._expand_context(query, primary, graph)
+                    return self._compress_pack(pack)
+        return self.resolve(code_location, top_k=3)
+
+    def format_context(self, pack: dict) -> str:
+        """Format a context pack as a human-readable string for agents."""
+        lines = [f"[{pack['confidence']:.2f}] {pack['query']}"]
+        if pack.get("primary_chunks"):
+            lines.append(f"  ({len(pack['primary_chunks'])} files)")
+        lines.append("")
+        for i, result in enumerate(pack.get("primary_chunks", []), 1):
+            chunk = result.chunk
+            span = (
+                f"{chunk.start_line}-{chunk.end_line}"
+                if chunk.end_line != chunk.start_line
+                else str(chunk.start_line)
+            )
+            lines.append(f"  {i}. {chunk.file_path}:{span}  [{result.score:.2f}]")
+            snippet = chunk.content.strip()[:300]
+            for line in snippet.split("\n"):
+                lines.append(f"     {line}")
+        if pack.get("symbols"):
+            names = [s["name"] for s in pack["symbols"][:6]]
+            if len(pack["symbols"]) > 6:
+                names.append("...")
+            lines.append(f"  sym: {' '.join(names)}")
+        hints = []
+        if pack.get("test_files"):
+            hints.append(
+                f"tests: {', '.join(f.split('/')[-1] for f in pack['test_files'][:2])}"
+            )
+        if pack.get("imports"):
+            hints.append(
+                f"deps: {', '.join(f.split('/')[-1] for f in pack['imports'][:2])}"
+            )
+        if pack.get("callers"):
+            hints.append(
+                f"callers: {', '.join(c['name'] for c in pack['callers'][:2])}"
+            )
+        if hints:
+            lines.append(f"  {' | '.join(hints)}")
+        return "\n".join(lines)
+
     def find_related(self, chunk_idx: int, top_k: int = 5) -> list[SearchResult]:
         """Find chunks semantically similar to a given chunk (cocoindex find_related)."""
         if chunk_idx < 0 or chunk_idx >= len(self.chunks):