Update README with vortexa core API and Indian examples for mini tier

README.md

@@ -14,6 +14,7 @@ tags:
 - ultra-lightweight
 - code-search
 - retrieval
+- vortexa
 pipeline_tag: feature-extraction
 metrics:
 - spearman_cosine
@@ -52,7 +53,7 @@ model-index:
       name: Classification
     dataset:
       name: AmazonCounterfactualClassification
-      type: mteb/amazon_counterfactual_classification
+      type: mteb/amazon_counterfactual
     metrics:
     - type: accuracy
       value: 0.6679
@@ -78,12 +79,13 @@ model-index:
 
 <div align="center">
 
-# 🚀 vtx-embed-7M
+# 🚀 vtx-embed-7M (`mini`)
 
-**The world's most memory-efficient general-purpose embedding model.**
-Native 4-Bit quantization · 4.72 MB RAM · Matryoshka MRL · Sub-millisecond CPU latency
+**The world's most memory-efficient static embedding model powering [vortexa](https://github.com/OEvortex/vortexa).**
+Native 4-Bit quantization · 4.72 MB RAM · 7.56M Parameters · Matryoshka MRL · Sub-millisecond CPU latency
 
-[![HuggingFace](https://img.shields.io/badge/🤗%20HuggingFace-VTXAI%2Fvtx--embed--7M-blue)](https://huggingface.co/VTXAI/vtx-embed-7M)
+[![HuggingFace](https://img.shields.io/badge/🤗%20HuggingFace-VTXAI%2Fvtx-embed-7M-blue)](https://huggingface.co/VTXAI/vtx-embed-7M)
+[![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)
 
@@ -91,169 +93,95 @@ Native 4-Bit quantization · 4.72 MB RAM · Matryoshka MRL · Sub-millisecond CP
 
 ---
 
+## ⚡ 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-7M` (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 Type** | Native 4-Bit Static Embedding (LF4) |
-| **Total Parameters** | 7.55M (4-Bit packed) |
+| **Model Name / Tier** | **vtx-embed-7M** (`"mini"`) |
+| **Total Parameters** | **7.56M** |
 | **Tensor Storage Format** | `lf4` — 4-bit per-block with FP16 scale + zero |
 | **In-RAM Memory** | **4.72 MB** |
 | **On-Disk Size** | **4.72 MB** |
 | **Vocabulary Size** | 29,528 |
 | **Max Sequence Length** | 512 tokens |
-| **Output Dimensions** | 256 *(Matryoshka: also 128, 64)* |
+| **Output Dimensions** | 256 *(Matryoshka supported)* |
 | **Pooling** | SIF IDF-weighted + PC-1 removal |
-| **Similarity Metric** | Cosine |
+| **Primary Engine Integration** | [OEvortex/vortexa](https://github.com/OEvortex/vortexa) |
 | **License** | MIT |
 
 ---
 
-## 📊 Official MTEB Benchmark Results
-
-All scores below were produced by running the **official [MTEB](https://github.com/embeddings-benchmark/mteb) 2.18.7** evaluation framework directly against this model on CPU. No cheating — no overlap with training data.
-
-### Semantic Textual Similarity (STS)
+## 📊 Official Benchmark Results
 
-| Dataset | Metric | **vtx-embed-7M** | MiniLM-L6-v2 (90 MB) | bge-small-en-v1.5 (134 MB) |
+| Dataset | Metric | **vtx-embed-7M (4.72 MB)** | MiniLM-L6-v2 (90 MB) | bge-small-en-v1.5 (134 MB) |
 | :--- | :---: | :---: | :---: | :---: |
 | **STSBenchmark** | Spearman ρ | **0.7918** | 0.8284 | 0.8278 |
 | **SICK-R** | Spearman ρ | **0.6294** | 0.7572 | 0.7460 |
-
-### Classification
-
-| Dataset | Metric | **vtx-embed-7M** | MiniLM-L6-v2 (90 MB) | bge-small-en-v1.5 (134 MB) |
-| :--- | :---: | :---: | :---: | :---: |
 | **Banking77Classification** | Accuracy | **0.7043** | 0.7451 | 0.7884 |
-| **AmazonCounterfactualClassification** | Accuracy | **0.6679** | 0.7371 | 0.7279 |
-
-### Clustering
-
-| Dataset | Metric | **vtx-embed-7M** | MiniLM-L6-v2 (90 MB) | bge-small-en-v1.5 (134 MB) |
-| :--- | :---: | :---: | :---: | :---: |
-| **TwentyNewsgroupsClustering** | V-Measure | **0.2936** | 0.3529 | 0.4419 |
-| **RedditClustering** | V-Measure | **0.3880** | 0.4342 | 0.5376 |
+| **AmazonCounterfactual** | Accuracy | **0.6679** | 0.7371 | 0.7279 |
+| **TwentyNewsgroups** | V-Measure | **0.2936** | 0.3529 | 0.4419 |
+| **RedditClustering** | V-Measure | **0.388** | 0.4342 | 0.5376 |
 
 ---
 
-## ⚡ Efficiency Benchmark
-
-*Compared against LiquidAI's LFM2.5-Embedding-350M (from their published benchmarks):*
-
-| Model | RAM | Disk | CPU Latency p50 | CPU Latency p95 | Texts/sec |
-| :--- | :-: | :-: | :-: | :-: | :-: |
-| **vtx-embed-7M (256-dim)** | **4.72 MB** | **4.72 MB** | **0.575 ms** | **1.034 ms** | **18,151** |
-| **vtx-embed-7M (64-dim)** | **4.72 MB** | **4.72 MB** | **0.312 ms** | **0.620 ms** | **~32,000** |
-| LiquidAI/LFM2.5-Embedding-350M | ~700 MB | 708 MB | 7.30 ms | 9.60 ms | ~137 |
-| sentence-transformers/all-MiniLM-L6-v2 | 90 MB | 90 MB | 12.4 ms | 18.0 ms | ~80 |
-| BAAI/bge-small-en-v1.5 | 134 MB | 134 MB | 18.2 ms | 25.0 ms | ~55 |
-
-> **vtx-embed-7M is 12.7× faster and 148× smaller in RAM than LFM2.5-Embedding-350M.**
-
----
-
-## 🎯 Matryoshka Representation Learning
-
-vtx-embed-7M supports dynamic **truncation** of output vectors — encode once, use at any dimension:
-
-| Dimension | Spearman ρ (STS-B) | Relative Speed | Use-case |
-| :-: | :-: | :-: | :--- |
-| **256** | **0.7918** | 1.0× | Full quality RAG / semantic search |
-| **128** | **0.7753** | 1.4× | Balanced quality / storage |
-| **64** | **0.7577** | 2.0× | High-throughput edge / mobile |
-
----
-
-## 💻 Quickstart
-
-### Installation
-
-```bash
-pip install numpy tokenizers safetensors huggingface_hub
-```
-
-### Load & Encode
-
-```python
-from huggingface_hub import hf_hub_download
-import importlib.util
-
-# Download single-file client (no torch, no transformers needed!)
-path = hf_hub_download("VTXAI/vtx-embed-7M", "vortex_embed_v4_5.py")
-spec = importlib.util.spec_from_file_location("ve", path)
-mod  = importlib.util.module_from_spec(spec); spec.loader.exec_module(mod)
-
-# Load model — strict 4.72 MB RAM
-model = mod.VortexEmbedV4_5.from_pretrained("VTXAI/vtx-embed-7M")
-
-# Encode
-sentences = ["A plane is taking off.", "An airplane is ascending into the sky."]
-embeddings = model.encode(sentences, normalize=True)  # (2, 256) float32
-
-# Cosine similarity
-sim = (embeddings[0] * embeddings[1]).sum()
-print(f"Similarity: {sim:.4f}")   # ~0.84
-```
-
-### Matryoshka Truncation
-
-```python
-emb_128 = model.encode(sentences, truncate_dim=128)  # (2, 128)
-emb_64  = model.encode(sentences, truncate_dim=64)   # (2, 64)
-```
+## 💻 Quickstart Usage
 
-### RAG / Code Search Pipeline
+### Native Vortexa Core API
 
 ```python
-# Index a corpus
-corpus = ["def search(q): ...", "class RAGEngine: ...", "import numpy as np"]
-corpus_embs = model.encode(corpus, normalize=True)  # (N, 256)
-
-# Query
-query_emb = model.encode("how to build a search engine", normalize=True)  # (256,)
-scores    = corpus_embs @ query_emb
-top_k     = scores.argsort()[::-1][:3]
-for i in top_k:
-    print(f"[{scores[i]:.3f}] {corpus[i][:60]}")
-```
-
----
-
-## 🏗️ Architecture
-
-```
-VortexEmbedV4_5
-├── Tokenizer          BPE, vocab=29,528
-├── LF4 Embedding      (29528, 128) uint8 packed  →  3.78 MB
-│   ├── scale_fp16     (29528, 8) float16         →  0.47 MB
-│   └── zero_fp16      (29528, 8) float16         →  0.47 MB
-│   └── Total RAM                                 →  4.72 MB
-├── Pooling            SIF (sif_a=0.05, IDF-weighted mean)
-├── PCA Removal        Top-1 principal component removed
-└── Matryoshka         Truncation to 256 / 128 / 64 dims
+from vortexa.core.inference import VortexEmbedInference, similarity
+
+# Load model using the "mini" model alias
+model = VortexEmbedInference("mini")
+
+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)
 ```
 
-**Quantization:** Each token embedding is stored as 128 packed 4-bit values across 8 groups. During inference, only active tokens per batch are dequantized on-the-fly — zero FP32/FP16 matrix ever stored in RAM.
-
----
-
-## 📈 Why vtx-embed-7M?
-
-| Scenario | Why it matters |
-| :--- | :--- |
-| **Edge / Mobile Deployment** | Fits entirely in 4.72 MB — runs on microcontrollers, Raspberry Pi, or embedded systems |
-| **High-Throughput RAG** | 18,151 texts/sec on a single CPU core — no GPU needed |
-| **Large Codebase Indexing** | Indexes 26,000+ code chunks in seconds; 885 chunks/sec |
-| **Cost Reduction** | Eliminate GPU inference costs entirely for embedding workloads |
-| **Matryoshka Flexibility** | One model, three vector sizes — no retraining needed |
-
 ---
 
 ## 📜 Citation
 
 ```bibtex
-@misc{vtx-embed-7M,
-  title  = {vtx-embed-7M: Native 4-Bit Sentence Embeddings with Matryoshka Representation Learning},
+@misc{vtx-embed-7m},
+  title  = {vtx-embed-7M: Native 4-Bit Embeddings for Standalone Codebase Indexing},
   author = {VTXAI},
   year   = {2026},
   url    = {https://huggingface.co/VTXAI/vtx-embed-7M}