OpenViSTAI · Agents · Blockchain · Crypto
Submit a project
Menu
AI Infrastructure & Serving

Semafold

Semafold is a Python library that compresses embedding vectors, retrieval representations and cache-shaped LLM key/value tensors using vector codecs, including its TurboQuant family. It includes a NumPy backend and optional PyTorch or MLX acceleration.

Explore the practical guide ↓

Independent OpenViST project profile, based on linked sources.

Semafold — OpenViST project profile in AI Infrastructure & Serving.
OpenViST project illustration. See the linked sources for product details.
Understand the project

Practical overview

When it fits

Use Semafold when a system stores or processes numeric embeddings, retrieval representations or KV tensors and you want codec-based compression with byte accounting. Consider its NumPy backend for CPU-based use, or the documented optional backends when using supported accelerator libraries.

Who it is for

  • AI infrastructure teams managing embedding or retrieval data storage.
  • Developers integrating vector compression into retrieval pipelines or custom inference stacks.
  • Teams exploring compression of cache-shaped key/value tensors.

Documented uses

  • Encode and decode embedding vectors with a vector codec.
  • Measure encoded artifact size and compression ratio for a vector workload.
  • Compress cache-shaped key/value tensors using the documented TurboQuant KV codec.
Before you choose

Requirements & limits

The repository is public and identifies the project as Apache-2.0 licensed. The README specifies Python 3.10 or later and installation through pip.

  • The default NumPy backend does not require a GPU; acceleration is optional through PyTorch (CUDA/MPS) or MLX (Metal).
  • TurboQuant codecs are documented as deep imports rather than stable root-package exports.
  • Compression figures in the README are tied to particular benchmark inputs, codecs and bit settings; results may differ for other workloads.

Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.

Source-based practical guide

Compress and decode embedding vectors with TurboQuant MSE

Encode an embedding matrix with the TurboQuant MSE codec, inspect its reported size and ratio, and decode it.

Before you start

  • Python 3.10 or later, as indicated by the repository’s Python badge.
  • Semafold installed, with NumPy available.
  • Embedding vectors represented as a NumPy array.

Steps

  1. Install the package with the command below.

    Documented command
    pip install semafold

  2. Import EncodeMetric, EncodeObjective, VectorEncodeRequest, and VectorDecodeRequest from semafold; import TurboQuantMSEConfig and TurboQuantMSEVectorCodec from semafold.turboquant.

  3. Create a TurboQuantMSEVectorCodec with TurboQuantMSEConfig(default_bits_per_scalar=3, default_rotation_seed=7), then encode the embedding array using a VectorEncodeRequest with reconstruction objective, MSE metric, role embedding, and seed 11.

  4. Decode the resulting encoding with codec.decode(VectorDecodeRequest(encoding=encoding)); inspect encoding.footprint.total_bytes and encoding.footprint.compression_ratio, and check that the decoded array shape matches the input.

Expected outcome

The example encodes and decodes an embedding matrix and exposes the encoding’s reported byte footprint and compression ratio.

Guide limitations

  • TurboQuant is currently a deep-import surface rather than part of the stable root exports.
  • Compression is lossy; the README describes distortion visibility and reports results for specific benchmark workloads, not a guaranteed ratio for every input.
Documentation 1 ↗
Source-based practical guide

Compress and decode cache-shaped K/V tensors with the preview codec

Encode and decode key and value tensors using Semafold’s TurboQuant KV preview codec.

Before you start

  • Python 3.10 or later, as indicated by the repository’s Python badge.
  • Semafold installed, with NumPy available.
  • Key and value arrays shaped as cache tensors; the README example uses (4, 8, 256, 128).

Steps

  1. Install the package with the command below.

    Documented command
    pip install semafold

  2. Import TurboQuantKVConfig and TurboQuantKVPreviewCodec from semafold.turboquant.kv.

  3. Create key and value NumPy arrays and configure a TurboQuantKVPreviewCodec with TurboQuantKVConfig, following the repository example at examples/turboquant_kv_block.py.

  4. Encode and decode the tensors using the preview codec, following that example.

Expected outcome

The documented example demonstrates a TurboQuant KV codec path for cache-shaped key and value tensors.

Guide limitations

  • The KV codec is on the TurboQuant deep-import surface, not the stable root exports.
Documentation 1 ↗
Evidence and transparency

Sources & review

Official repository ↗
Source record details
Source availability
Active
Sources checked
15 October 2026
Original website title
mindtro/semafold · Official homepage title · retained in its source language
How we review sourcesSuggest a correction