vortexa 0.3.4__tar.gz → 0.3.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortexa
-Version: 0.3.4
+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.4 → 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.4 → vortexa-0.3.5}/pyproject.toml

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

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

@@ -87,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:
@@ -113,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

{vortexa-0.3.4 → vortexa-0.3.5}/src/vortexa/core/inference.py

@@ -24,6 +24,10 @@ Quick start:
     nano = VortexEmbedInference("nano")
     print(nano.dim)                                # nano's native dim
 
+    # Use LF2 models (native 2-bit quantization)
+    mini_lf2 = VortexEmbedInference("mini-lf2")
+    nano_lf2 = VortexEmbedInference("nano-lf2")
+
 Convenience function (stateless):
     from vortexa.core.inference import embed
 
@@ -41,12 +45,24 @@ import numpy as np
 import numpy.typing as npt
 
 _MODEL_ALIASES = {
-    "mini": "VTXAI/vtx-embed-7M",
-    "nano": "VTXAI/vtx-embed-1M",
+    "mini": "VTXAI/vtx-embed-7M-lf2",
+    "nano": "VTXAI/vtx-embed-1M-lf2",
+    "mini-lf2": "VTXAI/vtx-embed-7M-lf2",
+    "nano-lf2": "VTXAI/vtx-embed-1M-lf2",
+    "mini-full": "VTXAI/vtx-embed-7M",
+    "nano-full": "VTXAI/vtx-embed-1M",
+}
+_FAST_MODEL_IDS = {
+    "mini-full": _MODEL_ALIASES["mini-lf2"],
+    "nano-full": _MODEL_ALIASES["nano-lf2"],
+    _MODEL_ALIASES["mini-full"]: _MODEL_ALIASES["mini-lf2"],
+    _MODEL_ALIASES["nano-full"]: _MODEL_ALIASES["nano-lf2"],
 }
 
 
-def _resolve_model_id(model: str) -> str:
+def _resolve_model_id(model: str, *, fast: bool = False) -> str:
+    if fast and model in _FAST_MODEL_IDS:
+        return _FAST_MODEL_IDS[model]
     return _MODEL_ALIASES.get(model, model)
 
 
@@ -83,15 +99,18 @@ def similarity(
 class VortexEmbedInference:
     """A sentence-transformers-style inference engine for Vortex-Embed models.
 
-    Supports on-the-fly LF4 4-bit dequantization, SIF+PC weighting, and
+    Supports on-the-fly LF4/LF2 dequantization, SIF+PC weighting, and
     Matryoshka representation learning for dimension truncation.
 
     Args:
-        model: Model ID or alias (``mini``, ``nano``, or any
-            HuggingFace model name). Default: ``mini``.
+        model: Model ID or alias (``mini``, ``nano``, ``mini-full``, ``nano-full``, or any
+            HuggingFace model name). ``mini`` and ``nano`` use LF2 by default.
+            Default: ``mini``.
         dim: If set, truncate all output embeddings to this number of
             dimensions via Matryoshka truncation. Can be overridden per-call
             in ``encode()``.
+        fast: Explicitly select LF2 for a full-model alias. This is already
+            the default for ``mini`` and ``nano``.
 
     Example:
         >>> from vortexa.core.inference import VortexEmbedInference
@@ -104,10 +123,19 @@ class VortexEmbedInference:
         (1, 128)
         >>> model.dim
         256
+        >>> # Use fast native 2-bit inference
+        >>> lf2 = VortexEmbedInference("mini", fast=True)
+        >>> vec = lf2.encode("Native 2-bit embedding text...")
     """
 
-    def __init__(self, model: str = "mini", *, dim: int | None = None) -> None:
-        self._model_id = _resolve_model_id(model)
+    def __init__(
+        self,
+        model: str = "mini",
+        *,
+        dim: int | None = None,
+        fast: bool = False,
+    ) -> None:
+        self._model_id = _resolve_model_id(model, fast=fast)
         from vortexa.core.v4_embedder import VortexEmbedderV4
 
         self._embedder = VortexEmbedderV4(self._model_id)
@@ -202,6 +230,7 @@ def embed(
     model: str = "mini",
     dim: int | None = None,
     normalize: bool = True,
+    fast: bool = False,
 ) -> npt.NDArray[np.float32]:
     """Encode text strings into dense vector embeddings (stateless convenience).
 
@@ -210,12 +239,15 @@ def embed(
 
     Args:
         texts: A single string or a list of strings to encode.
-        model: Model ID or alias (``mini``, ``nano``, or any
-            HuggingFace model name). Default: ``mini``.
+        model: Model ID or alias (``mini``, ``nano``, ``mini-full``, ``nano-full``, or any
+            HuggingFace model name). ``mini`` and ``nano`` use LF2 by default.
+            Default: ``mini``.
         dim: If set, truncate embeddings to this dimension via
             Matryoshka truncation. Default: ``None`` (full dimension).
         normalize: Whether to L2-normalize the output vectors.
             Default: ``True``.
+        fast: Use the corresponding native 2-bit LF2 checkpoint when
+            ``model`` is ``mini`` or ``nano``.
 
     Returns:
         A numpy array of shape ``(N, D)`` where ``N`` is the number
@@ -229,8 +261,11 @@ def embed(
         >>> vec = embed(["Indian cricket team is strong", "Chennai is a major city"], model="nano", dim=64)
         >>> vec.shape
         (2, 64)
+        >>> # Use LF2 models (native 2-bit embeddings)
+        >>> vec = embed("Native 2-bit embedding text...", model="mini-lf2")
+
     """
-    model_id = _resolve_model_id(model)
+    model_id = _resolve_model_id(model, fast=fast)
     from vortexa.core.v4_embedder import VortexEmbedderV4
 
     embedder = VortexEmbedderV4(model_id)