flexvec 0.0.1__tar.gz → 0.1.0__tar.gz

flexvec-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Damian Delmas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flexvec-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: flexvec
+Version: 0.1.0
+Summary: numpy-backed semantic search for any SQLite database
+License: MIT
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: embed
+Requires-Dist: onnxruntime; extra == "embed"
+Requires-Dist: tokenizers; extra == "embed"
+Provides-Extra: graph
+Requires-Dist: networkx; extra == "graph"
+Dynamic: license-file

flexvec-0.1.0/README.md

@@ -0,0 +1,174 @@
+# flexvec
+
+Semantic similarity has a differentiation problem. You want chunks about `authentication` but not `OAuth` — the embeddings are too similar. A vector database can't help. You get `.query()` and metadata filters. The embeddings are abstracted away. You can't touch them.
+
+flexvec keeps embeddings as numpy arrays you can operate on. Subtract a concept. Decay by recency. Spread across subtopics. Project a direction through embedding space. These aren't metadata filters — they're operations on the vectors themselves.
+
+```bash
+pip install flexvec
+```
+
+---
+
+## Three-Phase Pipeline
+
+Every query runs three steps. SQL narrows the candidates. NumPy scores them. SQL composes the results.
+
+```
+SQL pre-filter  →  NumPy vector operations  →  SQL compose
+```
+
+This solves the pre-filter problem that sqlite-vec and sqlite-vss never solved. They run vector search first, filter second. flexvec filters first, searches second. If your WHERE returns 500 rows, NumPy operates on 500 vectors — not your whole table.
+
+```python
+import sqlite3
+from flexvec import VectorCache, register_vec_ops, execute, get_embed_fn
+
+db = sqlite3.connect("my.db")
+
+# Load vectors into memory (once)
+cache = VectorCache()
+cache.load_from_db(db, "chunks", "embedding", "id")
+
+# Default: bundled Nomic ONNX model (pip install flexvec[embed])
+embed_fn = get_embed_fn()
+
+# Register vec_ops as a SQL function
+register_vec_ops(db, {"chunks": cache}, embed_fn)
+
+# Query — three phases in one statement
+rows = execute(db, """
+    SELECT v.id, v.score, c.content
+    FROM vec_ops('chunks', 'authentication patterns',
+      'diverse unlike:oauth recent:7',
+      'SELECT id FROM chunks WHERE created_at > 1709000000') v
+    JOIN chunks c ON v.id = c.id
+    ORDER BY v.score DESC
+    LIMIT 10
+""")
+```
+
+---
+
+## Modulation Tokens
+
+Tokens reshape the scoring landscape before candidate selection. They compose freely. `diverse unlike:oauth recent:7` is three operations in one pass.
+
+| token | what it does |
+|---|---|
+| `diverse` | MMR — spread results across subtopics |
+| `recent:N` | temporal decay with N-day half-life |
+| `unlike:TEXT` | contrastive — suppress similarity to a concept in embedding space |
+| `like:id1,id2` | centroid — search from the mean of example chunks |
+| `from:T to:T` | trajectory — a direction vector through embedding space |
+| `local_communities` | per-query Louvain clustering, adds `_community` column |
+| `limit:N` | candidate pool size (default 500) |
+
+`unlike:TEXT` isn't a metadata filter. It embeds TEXT separately and penalizes similarity to it in the vector space. The dominant signal gets suppressed — what surfaces are the edges that a normal query drowns out.
+
+`from:T to:T` isn't "search for X then Y." It computes the delta between two concepts and uses that direction as a lens. Content along the conceptual arc surfaces.
+
+---
+
+## FTS5 Keyword Search
+
+`keyword()` is the FTS5 peer to `vec_ops`. Same materializer pattern. Both compose through SQL.
+
+```python
+# Keyword search
+rows = execute(db, """
+    SELECT k.id, k.rank, k.snippet
+    FROM keyword('authentication') k
+    ORDER BY k.rank DESC
+""")
+
+# Hybrid: only chunks matching BOTH keyword AND semantic
+rows = execute(db, """
+    SELECT k.id, k.rank, v.score
+    FROM keyword('auth') k
+    JOIN vec_ops('chunks', 'authentication patterns') v ON k.id = v.id
+    ORDER BY k.rank + v.score DESC
+    LIMIT 10
+""")
+```
+
+---
+
+## Bring Your Own Embeddings
+
+flexvec doesn't care how vectors got into your table. Any BLOB column of float32 arrays works.
+
+```python
+# OpenAI
+embed_fn = lambda text: openai_client.embeddings.create(
+    input=text, model="text-embedding-3-small").data[0].embedding
+
+# sentence-transformers
+embed_fn = lambda text: st_model.encode([text])
+
+# Any table layout
+cache.load_from_db(db, "documents", "ada_embedding", "doc_id")
+cache.load_from_db(db, "paragraphs", "embedding", "id")
+```
+
+---
+
+## Performance
+
+All vectors loaded once into a numpy matrix. Queries are a single matmul. Benchmarked on Apple M-series, 768 dimensions.
+
+| corpus size | query time |
+|---|---|
+| 1K vectors | 0.1ms |
+| 10K vectors | 0.5ms |
+| 100K vectors | 5ms |
+| 367K vectors | 12ms |
+
+Memory: ~30MB per 10K vectors at 768 dimensions.
+
+---
+
+## Schema
+
+One table. An ID column and an embedding BLOB column. That's it.
+
+```sql
+CREATE TABLE chunks (
+    id TEXT PRIMARY KEY,
+    content TEXT,
+    embedding BLOB,       -- float32 array, any dimension
+    timestamp INTEGER     -- optional: epoch seconds, enables recent:N
+);
+```
+
+---
+
+## vs sqlite-vec
+
+| | flexvec | sqlite-vec |
+|---|---|---|
+| install | `pip install` | compile C extension |
+| engine | numpy matmul | custom C SIMD |
+| pre-filter | any SQL, before vector search | after vector search, limited |
+| modulation tokens | 7 composable tokens | none |
+| FTS5 hybrid | built-in | manual |
+| dependency | numpy | C toolchain |
+
+sqlite-vec is faster at raw KNN on large corpora. flexvec is faster to ship and more composable with SQL. For personal knowledge bases under 500K chunks, brute force numpy with pre-filtering is fast enough and gives you operations that indexed search can't.
+
+---
+
+## Install
+
+```bash
+pip install flexvec              # core: vec_ops + keyword (numpy only)
+pip install flexvec[embed]       # + ONNX embedder (onnxruntime, tokenizers)
+pip install flexvec[graph]       # + local_communities token (networkx)
+pip install flexvec[embed,graph] # everything
+```
+
+---
+
+flexvec powers retrieval in [flex](https://github.com/damian-delmas/flex), a SQL-first knowledge engine for AI agents. Extracted as a standalone library — same code, zero dependencies on flex.
+
+MIT · Python 3.10+ · SQLite · numpy

flexvec-0.1.0/flexvec/__init__.py

@@ -0,0 +1,7 @@
+"""flexvec — numpy-backed semantic search for any SQLite database."""
+from .vec_ops import (
+    VectorCache, register_vec_ops, materialize_vec_ops, parse_modifiers,
+)
+from .keyword import materialize_keyword
+from .execute import execute
+from .embed import get_embed_fn

flexvec-0.1.0/flexvec/__main__.py

@@ -0,0 +1,8 @@
+"""python -m flexvec download-model"""
+import sys
+
+if len(sys.argv) > 1 and sys.argv[1] == "download-model":
+    from flexvec.onnx.fetch import download_model
+    download_model()
+else:
+    print("usage: python -m flexvec download-model")

flexvec-0.1.0/flexvec/embed.py

@@ -0,0 +1,31 @@
+"""Default embedding function — wraps the bundled ONNX model."""
+
+
+def get_embed_fn(prefix='search_query: '):
+    """Return an embedding function using the bundled Nomic ONNX model.
+
+    Requires: pip install flexvec[embed]
+
+    Usage:
+        from flexvec import get_embed_fn
+        embed_fn = get_embed_fn()
+    """
+    try:
+        from .onnx.embed import get_model
+        from .onnx.fetch import model_ready, download_model
+    except ImportError:
+        raise ImportError(
+            "flexvec[embed] is required for get_embed_fn(). "
+            "Install with: pip install flexvec[embed]"
+        )
+
+    if not model_ready():
+        print("flexvec: downloading embedding model (~87MB)...")
+        download_model()
+
+    model = get_model()
+
+    def embed(text):
+        return model.encode([text], prefix=prefix)
+
+    return embed

flexvec-0.1.0/flexvec/execute.py

@@ -0,0 +1,20 @@
+"""Convenience wrapper — chains both materializers, then executes."""
+
+from .vec_ops import materialize_vec_ops
+from .keyword import materialize_keyword
+
+
+def execute(db, sql):
+    """Chain vec_ops and keyword materializers, then execute.
+
+    Usage:
+        from flexvec import execute
+        rows = execute(db, "SELECT v.id FROM vec_ops('chunks', 'auth') v LIMIT 10")
+    """
+    sql = materialize_vec_ops(db, sql)
+    if sql.startswith('{"error"'):
+        return sql
+    sql = materialize_keyword(db, sql)
+    if sql.startswith('{"error"'):
+        return sql
+    return db.execute(sql).fetchall()

flexvec-0.1.0/flexvec/keyword.py

@@ -0,0 +1,146 @@
+"""FTS5 keyword materializer — peer primitive to vec_ops.
+
+AI writes:  FROM keyword('search term') k
+Becomes:    FROM _kw_results_xxxx k  (temp table with id, rank, snippet)
+"""
+
+import json
+import re
+import sqlite3
+import uuid
+
+
+def materialize_keyword(db, sql: str) -> str:
+    """Transparently materialize keyword() as a temp table.
+
+    Returns original SQL unchanged if no keyword() table source found.
+    Returns JSON error string on failure.
+    """
+    # Find keyword(...) call
+    start = re.search(r'keyword\s*\(', sql)
+    if not start:
+        return sql
+
+    # Only materialize when used as a table source (FROM/JOIN position)
+    before = sql[:start.start()].rstrip().upper()
+    if not (before.endswith('FROM') or before.endswith('JOIN') or before.endswith(',')):
+        return sql
+
+    # Balanced-paren extraction (handles quoted strings with escaped '' quotes)
+    paren_start = start.end() - 1
+    depth = 0
+    in_quote = False
+    end_pos = None
+    i = paren_start
+    while i < len(sql):
+        c = sql[i]
+        if in_quote:
+            if c == "'":
+                if i + 1 < len(sql) and sql[i + 1] == "'":
+                    i += 2
+                    continue
+                else:
+                    in_quote = False
+        else:
+            if c == "'":
+                in_quote = True
+            elif c == '(':
+                depth += 1
+            elif c == ')':
+                depth -= 1
+                if depth == 0:
+                    end_pos = i + 1
+                    break
+        i += 1
+    if end_pos is None:
+        return sql
+
+    # Extract args from keyword('term', 'modifiers')
+    inner = sql[paren_start + 1:end_pos - 1].strip()
+    args = _split_args(inner)
+    if not args:
+        return json.dumps({"error": "keyword() requires a non-empty search term"})
+
+    term = args[0].strip()
+    # Strip surrounding quotes
+    if len(term) >= 2 and term[0] == "'" and term[-1] == "'":
+        term = term[1:-1].replace("''", "'")
+
+    if not term or not term.strip():
+        return json.dumps({"error": "keyword() requires a non-empty search term"})
+
+    # Parse modifiers (2nd arg)
+    limit = 200
+    if len(args) > 1:
+        mod_str = args[1].strip()
+        if len(mod_str) >= 2 and mod_str[0] == "'" and mod_str[-1] == "'":
+            mod_str = mod_str[1:-1]
+        m = re.search(r'limit:(\d+)', mod_str)
+        if m:
+            limit = int(m.group(1)) or 200
+
+    # Execute FTS5 query — raw-first, quote-on-error fallback
+    fts_sql = (
+        "SELECT c.id, "
+        "  -bm25(chunks_fts) as rank, "
+        "  snippet(chunks_fts, 0, '>>>', '<<<', '...', 30) as snippet "
+        "FROM chunks_fts "
+        "JOIN _raw_chunks c ON chunks_fts.rowid = c.rowid "
+        "WHERE chunks_fts MATCH ? "
+        "ORDER BY bm25(chunks_fts) "
+        "LIMIT ?"
+    )
+
+    try:
+        try:
+            rows = db.execute(fts_sql, (term, limit)).fetchall()
+        except sqlite3.OperationalError:
+            # Fallback: double-quote for literal matching
+            escaped = '"' + term.replace('"', '""') + '"'
+            rows = db.execute(fts_sql, (escaped, limit)).fetchall()
+    except Exception as e:
+        return json.dumps({"error": f"keyword() search failed: {e}"})
+
+    # Create temp table (always — even on empty results)
+    tmp_name = f"_kw_results_{uuid.uuid4().hex[:8]}"
+    db.execute(f"CREATE TEMP TABLE [{tmp_name}] (id TEXT PRIMARY KEY, rank REAL, snippet TEXT)")
+    if rows:
+        db.executemany(
+            f"INSERT INTO [{tmp_name}] VALUES (?, ?, ?)",
+            [(r[0], r[1], r[2]) for r in rows]
+        )
+
+    # Rewrite: replace keyword(...) with temp table name
+    return sql[:start.start()] + tmp_name + sql[end_pos:]
+
+
+def _split_args(inner: str) -> list[str]:
+    """Split comma-separated args respecting single-quoted strings."""
+    args = []
+    current = []
+    in_quote = False
+    i = 0
+    while i < len(inner):
+        c = inner[i]
+        if in_quote:
+            current.append(c)
+            if c == "'":
+                if i + 1 < len(inner) and inner[i + 1] == "'":
+                    current.append("'")
+                    i += 2
+                    continue
+                else:
+                    in_quote = False
+        else:
+            if c == "'":
+                in_quote = True
+                current.append(c)
+            elif c == ',':
+                args.append(''.join(current))
+                current = []
+            else:
+                current.append(c)
+        i += 1
+    if current:
+        args.append(''.join(current))
+    return args

flexvec-0.1.0/flexvec/onnx/__init__.py

@@ -0,0 +1,2 @@
+"""ONNX embedding model — local inference, no PyTorch."""
+from .embed import ONNXEmbedder, get_model, encode, MAX_LENGTH

flexvec-0.1.0/flexvec/onnx/embed.py

@@ -0,0 +1,265 @@
+"""
+ONNX-based embedding model — Nomic embed-text-v1.5 (768-dim, Matryoshka).
+
+Drop-in replacement for sentence-transformers. Uses ONNX runtime.
+No PyTorch dependency. ~87MB int8 model.
+
+Task prefixes (mandatory for Nomic):
+  search_document:  — index time (default)
+  search_query:     — query time
+  clustering:       — clustering tasks
+  classification:   — classification tasks
+
+Memory-safe adaptive batching:
+  Attention is O(seq_len²). One long text in a batch pads the entire batch
+  to max_seq_len, spiking memory. We sort by tokenized length and scale
+  batch_size inversely with sequence length. Budget: 512MB attention ceiling.
+
+Performance:
+    Adaptive batching: sorts inputs by tokenized length so short texts batch
+    together (fast, low padding) and long texts batch together (predictable).
+    Attention memory stays under 512MB at any input mix. Results returned in
+    original order.
+
+Usage:
+    from flex.onnx import ONNXEmbedder
+
+    model = ONNXEmbedder()
+    embeddings = model.encode(["text1", "text2"])                    # index
+    embeddings = model.encode(["query"], prefix='search_query: ')    # search
+"""
+import numpy as np
+from pathlib import Path
+from typing import List, Union
+
+# Lazy imports
+_ort = None
+_tokenizer = None
+
+ONNX_DIR = Path(__file__).parent
+
+
+def _resolve_model_path() -> Path:
+    """Bundled first, then $FLEX_HOME/models/ (FLEX_HOME-aware)."""
+    import os
+    bundled = ONNX_DIR / "model.onnx"
+    if bundled.exists():
+        return bundled
+    flex_home = Path(os.environ.get("FLEX_HOME", Path.home() / ".flex"))
+    user = flex_home / "models" / "model.onnx"
+    if user.exists():
+        return user
+    raise RuntimeError(
+        "Embedding model not found.\n"
+        f"  Checked: {bundled}\n"
+        f"  Checked: {user}\n"
+        "  Run 'flexvec.onnx.fetch.download_model()' to download it."
+    )
+
+
+# Attention memory budget: batch × 12_heads × seq² × 4_bytes ≤ ATTN_BUDGET_BYTES
+# 512MB keeps us safe on 8GB machines with headroom for hidden states + OS.
+ATTN_BUDGET_BYTES = 512 * 1024 * 1024
+ATTN_HEADS = 12
+MAX_BATCH = 256
+MAX_LENGTH = 512
+MAX_CHARS = MAX_LENGTH * 8  # pre-truncate before tokenizer sees the text
+
+
+def _safe_batch_size(seq_len: int) -> int:
+    """Max batch size that keeps attention intermediates under budget."""
+    if seq_len <= 0:
+        return MAX_BATCH
+    max_bs = ATTN_BUDGET_BYTES // (ATTN_HEADS * seq_len * seq_len * 4)
+    return max(1, min(max_bs, MAX_BATCH))
+
+
+def _get_onnxruntime():
+    global _ort
+    if _ort is None:
+        import onnxruntime as ort
+        _ort = ort
+    return _ort
+
+
+def has_gpu() -> bool:
+    """Return True if CUDAExecutionProvider is available."""
+    try:
+        ort = _get_onnxruntime()
+        return "CUDAExecutionProvider" in ort.get_available_providers()
+    except Exception:
+        return False
+
+
+def _get_tokenizer():
+    global _tokenizer
+    if _tokenizer is None:
+        from tokenizers import Tokenizer
+        _tokenizer = Tokenizer.from_file(str(ONNX_DIR / "tokenizer.json"))
+    return _tokenizer
+
+
+class ONNXEmbedder:
+    """ONNX-based sentence embedder compatible with sentence-transformers API."""
+
+    def __init__(self, model_path: Path = None):
+        self.model_path = model_path or _resolve_model_path()
+        self._session = None
+        self._tokenizer = None
+
+    @property
+    def session(self):
+        if self._session is None:
+            ort = _get_onnxruntime()
+            opts = ort.SessionOptions()
+            # ORT_ENABLE_ALL: fuses QKV attention, layer norm, GELU, embedding
+            # layers into single kernels. 2-5x speedup on transformers.
+            opts.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+            # intra_op=0 lets ONNX use all physical cores (default heuristic).
+            # inter_op=1 because we run one model sequentially.
+            opts.intra_op_num_threads = 0
+            opts.inter_op_num_threads = 1
+            # Prefer CUDA if available, fall back to CPU transparently
+            available = ort.get_available_providers()
+            providers = (
+                ["CUDAExecutionProvider", "CPUExecutionProvider"]
+                if "CUDAExecutionProvider" in available
+                else ["CPUExecutionProvider"]
+            )
+            self._session = ort.InferenceSession(
+                str(self.model_path),
+                sess_options=opts,
+                providers=providers,
+            )
+        return self._session
+
+    @property
+    def tokenizer(self):
+        if self._tokenizer is None:
+            self._tokenizer = _get_tokenizer()
+        return self._tokenizer
+
+    def _encode_batch(self, batch: list, normalize: bool) -> np.ndarray:
+        """Tokenize and run inference on a single pre-sorted batch."""
+        tok = self.tokenizer
+        encoded = tok.encode_batch(batch)
+        input_ids = np.array([e.ids for e in encoded], dtype=np.int64)
+        attention_mask = np.array([e.attention_mask for e in encoded], dtype=np.int64)
+
+        feed = {"input_ids": input_ids, "attention_mask": attention_mask}
+        # token_type_ids is optional — only send if the model expects it
+        if any(i.name == "token_type_ids" for i in self.session.get_inputs()):
+            feed["token_type_ids"] = np.zeros_like(input_ids)
+        outputs = self.session.run(None, feed)
+
+        # Mean pooling
+        last_hidden = outputs[0]
+        mask_expanded = np.expand_dims(attention_mask, -1).astype(np.float32)
+        sum_embeddings = np.sum(last_hidden * mask_expanded, axis=1)
+        sum_mask = np.sum(mask_expanded, axis=1)
+        embeddings = sum_embeddings / np.maximum(sum_mask, 1e-9)
+
+        if normalize:
+            norms = np.linalg.norm(embeddings, axis=1, keepdims=True)
+            embeddings = embeddings / np.maximum(norms, 1e-9)
+
+        return embeddings
+
+    def encode(
+        self,
+        sentences: Union[str, List[str]],
+        batch_size: int = 32,
+        normalize: bool = True,
+        prefix: str = 'search_document: ',
+        show_progress_bar: bool = False,  # noqa: ARG002 — sentence-transformers API compat
+        matryoshka_dim: int = 128,
+    ) -> np.ndarray:
+        """
+        Encode sentences to embeddings with adaptive batching.
+
+        Sorts inputs by tokenized length so short texts batch together (fast)
+        and long texts get smaller batches (safe). Attention memory stays under
+        512MB regardless of input mix. Results returned in original order.
+
+        Args:
+            sentences: Single sentence or list of sentences
+            batch_size: Max batch size hint (actual size may be smaller for long texts)
+            normalize: Whether to L2-normalize embeddings
+            prefix: Task prefix for Nomic (default 'search_document: ' for indexing,
+                    use 'search_query: ' for retrieval). Empty string for no prefix.
+            show_progress_bar: Ignored. Exists for sentence-transformers API compatibility.
+            matryoshka_dim: Truncate output to this many dimensions (Matryoshka).
+                    Default 128. Set to 768 for full embeddings. Re-normalizes after
+                    truncation so cosine similarity remains valid.
+
+        Returns:
+            numpy array of shape (n_sentences, matryoshka_dim)
+        """
+        if isinstance(sentences, str):
+            sentences = [sentences]
+        if prefix:
+            sentences = [prefix + s for s in sentences]
+        # Pre-truncate: no point tokenizing 214K chars to keep 512 tokens
+        sentences = [s[:MAX_CHARS] for s in sentences]
+
+        n = len(sentences)
+        if n == 0:
+            return np.empty((0, 768), dtype=np.float32)
+
+        tok = self.tokenizer
+        tok.enable_truncation(max_length=MAX_LENGTH)
+        tok.enable_padding()
+
+        # Tokenize all to get lengths for sorting + adaptive batch sizing
+        pre_encoded = tok.encode_batch(sentences)
+        lengths = [len(e.ids) for e in pre_encoded]
+
+        # Sort by length: short texts first, long texts last
+        order = np.argsort(lengths)
+        sorted_sentences = [sentences[i] for i in order]
+        sorted_lengths = [lengths[i] for i in order]
+
+        all_embeddings = []
+        i = 0
+        while i < n:
+            # Adaptive batch size from longest text in this slice
+            max_seq = sorted_lengths[min(i + batch_size - 1, n - 1)]
+            safe_bs = min(batch_size, _safe_batch_size(max_seq))
+            end = min(i + safe_bs, n)
+            batch = sorted_sentences[i:end]
+
+            all_embeddings.append(self._encode_batch(batch, normalize))
+            i = end
+
+        stacked = np.vstack(all_embeddings)
+
+        # Unsort back to original order
+        result = np.empty_like(stacked)
+        result[order] = stacked
+
+        # Matryoshka truncation: slice to target dim and re-normalize
+        if matryoshka_dim and matryoshka_dim < result.shape[1]:
+            result = result[:, :matryoshka_dim].copy()
+            if normalize:
+                norms = np.linalg.norm(result, axis=1, keepdims=True)
+                norms = np.where(norms < 1e-9, 1.0, norms)
+                result = result / norms
+
+        return result
+
+
+# Singleton
+_model = None
+
+
+def get_model() -> ONNXEmbedder:
+    """Get singleton ONNX embedder instance."""
+    global _model
+    if _model is None:
+        _model = ONNXEmbedder()
+    return _model
+
+
+def encode(sentences: Union[str, List[str]], prefix: str = 'search_document: ', **kwargs) -> np.ndarray:
+    """Convenience function to encode sentences."""
+    return get_model().encode(sentences, prefix=prefix, **kwargs)