README.md

---
language:
- en
license: mit
library_name: tokenizers
tags:
- sentence-similarity
- feature-extraction
- embeddings
- rag
- quantized
- 4-bit
- matryoshka
- ultra-lightweight
- code-search
- retrieval
- vortexa
pipeline_tag: feature-extraction
metrics:
- spearman_cosine
model-index:
- name: vtx-embed-1M
  results:
  - task:
      type: sts
      name: Semantic Textual Similarity
    dataset:
      name: STSBenchmark
      type: mteb/stsbenchmark-sts
    metrics:
    - type: cosine_spearman
      value: 0.7149
  - task:
      type: sts
      name: Semantic Textual Similarity
    dataset:
      name: SICK-R
      type: mteb/sickr-sts
    metrics:
    - type: cosine_spearman
      value: 0.5916
  - task:
      type: classification
      name: Classification
    dataset:
      name: Banking77Classification
      type: mteb/banking77
    metrics:
    - type: accuracy
      value: 0.8384
  - task:
      type: classification
      name: Classification
    dataset:
      name: AmazonCounterfactualClassification
      type: mteb/amazon_counterfactual
    metrics:
    - type: accuracy
      value: 0.7731
  - task:
      type: clustering
      name: Clustering
    dataset:
      name: TwentyNewsgroupsClustering
      type: mteb/twentynewsgroups-clustering
    metrics:
    - type: v_measure
      value: 0.2511
  - task:
      type: clustering
      name: Clustering
    dataset:
      name: RedditClustering
      type: mteb/reddit-clustering
    metrics:
    - type: v_measure
      value: 0.3762
---

<div align="center">

# 🚀 vtx-embed-1M (`nano`)

**The world's most memory-efficient static embedding model powering [vortexa](https://github.com/OEvortex/vortexa).**
Native 4-Bit quantization · 0.57 MB RAM · 1.05M Parameters · Matryoshka MRL · Sub-millisecond CPU latency

[![HuggingFace](https://img.shields.io/badge/🤗%20HuggingFace-VTXAI%2Fvtx-embed-1M-blue)](https://huggingface.co/VTXAI/vtx-embed-1M)
[![GitHub Vortexa](https://img.shields.io/badge/GitHub-OEvortex%2Fvortexa-black?logo=github)](https://github.com/OEvortex/vortexa)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-blue)](https://python.org)

</div>

---

## ⚡ Integration with Vortexa

This model powers **[vortexa](https://github.com/OEvortex/vortexa)** — a standalone codebase indexing and semantic search engine designed for AI agents and developers.

`vortexa` builds a persistent, hybrid search index over source code using:
- **Dense Retrieval**: Driven natively by `vtx-embed-1M` (on-the-fly LF4 4-bit dequantization, SIF+PC pooling, Matryoshka truncation).
- **Sparse Retrieval**: BM25 keyword scoring for exact symbol matches.
- **AST-Aware Chunking**: Tree-sitter powered chunking respecting function and class boundaries.
- **LMDB Storage**: Fast, persistent vector and document chunk storage.

---

## 📄 Model Details

| Property | Value |
| :--- | :--- |
| **Model Name / Tier** | **vtx-embed-1M** (`"nano"`) |
| **Total Parameters** | **1.05M** |
| **Tensor Storage Format** | `lf4` — 4-bit per-block with FP16 scale + zero |
| **In-RAM Memory** | **0.57 MB** |
| **On-Disk Size** | **0.57 MB** |
| **Vocabulary Size** | 16,384 |
| **Max Sequence Length** | 512 tokens |
| **Output Dimensions** | 64 *(Matryoshka supported)* |
| **Pooling** | SIF IDF-weighted + PC-1 removal |
| **Primary Engine Integration** | [OEvortex/vortexa](https://github.com/OEvortex/vortexa) |
| **License** | MIT |

---

## 📊 Official Benchmark Results

| Dataset | Metric | **vtx-embed-1M (0.57 MB)** | MiniLM-L6-v2 (90 MB) | bge-small-en-v1.5 (134 MB) |
| :--- | :---: | :---: | :---: | :---: |
| **STSBenchmark** | Spearman ρ | **0.7149** | 0.8284 | 0.8278 |
| **SICK-R** | Spearman ρ | **0.5916** | 0.7572 | 0.7460 |
| **Banking77Classification** | Accuracy | **0.8384** | 0.7451 | 0.7884 |
| **AmazonCounterfactual** | Accuracy | **0.7731** | 0.7371 | 0.7279 |
| **TwentyNewsgroups** | V-Measure | **0.2511** | 0.3529 | 0.4419 |
| **RedditClustering** | V-Measure | **0.3762** | 0.4342 | 0.5376 |

---

## 💻 Quickstart Usage

### Native Vortexa Core API

```python
from vortexa.core.inference import VortexEmbedInference, similarity

# Load model using the "nano" model alias
model = VortexEmbedInference("nano")

queries = [
    "What is the capital of India?",
    "Explain gravity and general relativity",
]
documents = [
    "The capital of India is New Delhi.",
    "Gravity is a fundamental interaction that causes mutual attraction between all things with mass or energy.",
]

# 1. Encode queries and documents
query_embeddings = model.encode(queries)
document_embeddings = model.encode(documents)

# 2. Compute similarity matrix directly
similarity_matrix = query_embeddings @ document_embeddings.T
print("Similarity Matrix:")
print(similarity_matrix)
# Example output:
# [[0.82, 0.12],
#  [0.11, 0.74]]

# 3. Use built-in model similarity method
scores = model.similarity(query_embeddings, document_embeddings)

# 4. Single query against document list lookup
scores_single = model.similarity("What is the capital of India?", documents)
print("Single query scores:", scores_single)
```

---

## 📜 Citation

```bibtex
@misc{vtx-embed-1m},
  title  = {vtx-embed-1M: Native 4-Bit Embeddings for Standalone Codebase Indexing},
  author = {VTXAI},
  year   = {2026},
  url    = {https://huggingface.co/VTXAI/vtx-embed-1M}
}
```

---

## 📄 License

MIT License — free for commercial and research use.