BicycleButler/m2v2-gemma2-256d-int4

M2V2: Gemma-2 256d Int4 Client-Side Embedding Container

BicycleButler/m2v2-gemma2-256d-int4 is a high-efficiency, isomorphic 256-dimensional static embedding model distilled from Google's embeddinggemma-2 using Model2Vec / POTION (Zipf/SIF) norm-preserving quantization.

Packaged into a self-contained 16.7 KB binary container format (version v2:gemma2-m2v-int4:256), this model executes sub-0.1ms vector embeddings directly in browser Web Workers, service workers, Node.js runtimes, and mobile edge environments with zero Python or native C++ dependencies.

Key Features

• Isomorphic Sub-0.1ms Inference: Evaluates vector representations using a static UTF-8 prefix vocabulary trie, pre-computed Zipf/SIF row scales, and 4-bit packed integer matrix lookup.
• Identifier & SKU Protection: Guards alphanumeric codes, SKUs (e.g. BR-M8100), serials, phone numbers, and emails from semantic vector drift, preserving exact match tokens for lexical engines.
• Zero-Knowledge Architecture: Enables client-side vector search across local encrypted caches (OPFS LSM Vault) without decrypting records or leaking vectors to remote servers.
• Global CDN & Offline Cache API: Hosted on Hugging Face Hub with Access-Control-Allow-Origin: * for direct browser streaming and persistent Cache API storage (caches.open('m2v2-weights-v2')).

Model Details

• Base Architecture: Distilled from google/embeddinggemma-2
• Quantization: Symmetric 4-bit (Int4), 2 nibbles per byte (128 bytes per 256-dimensional vector)
• Dimensions: 256
• Normalization: Preserved POTION Zipf/SIF token scales with unit L2 post-normalization
• Container Format: M2V2 Binary Container (Magic: 0x4D325632, Version 2)
• Container Integrity: CRC32 header verification checksum

Usage

1. Browser & Node.js (via @wiltermoodj/search)

In JavaScript / TypeScript applications, install and consume via @wiltermoodj/search:

import { M2V2Engine, fetchM2V2Container } from '@wiltermoodj/search';

// Fetch from Hugging Face Hub with automatic browser Cache API persistence
const containerBuffer = await fetchM2V2Container();

const engine = new M2V2Engine();
engine.loadFromBinary(containerBuffer);

// Compute 256-dimensional unit vector in <0.1ms
const vector = engine.embedText("hydraulic disc brake pads");
console.log(vector); // Float32Array(256)

2. Python (Direct Binary Loading)

In Python applications, the container can be parsed directly with struct:

import struct
import zlib
from huggingface_hub import hf_hub_download

# Download binary container from Hugging Face Hub
model_path = hf_hub_download(
    repo_id="BicycleButler/m2v2-gemma2-256d-int4",
    filename="m2v2-gemma2-256d-int4.bin"
)

with open(model_path, "rb") as f:
    data = f.read()

# Validate header
magic, version, dim, vocab_count = struct.unpack_from("<IHHI", data, 0)
assert magic == 0x4D325632, "Invalid M2V2 magic"
assert version == 2, "Unsupported M2V2 container version"
print(f"Loaded M2V2 Container: {dim}d, {vocab_count} tokens")

Binary Container Layout

The .bin container uses an aligned low-overhead structure:

Offset Range	Section	Size	Description
0..63	Header	64 bytes	Magic 0x4D325632, Version 2, Dimension 256, Vocab Count, Offsets, CRC32
64..T	Vocabulary Trie	Dynamic	Flattened UTF-8 prefix trie mapping substrings to token IDs
T..S	Float16 Scales	Vocab * 2 bytes	Per-token Zipf/SIF scales preserving POTION norms
S..End	Packed Int4 Matrix	Vocab * 128 bytes	Contiguous 4-bit quantized embedding rows

Lineage & Acknowledgments

• Base Model: Distilled from Google's EmbeddingGemma-2, adhering to the Gemma Terms of Use.
• Model2Vec & POTION: Architectural concepts built upon the Model2Vec framework by MinishLab.
• Ecosystem: Engineered for the Bicycle Butler zero-knowledge federated commerce ecosystem.

License

This model container and associated weights are released under the Apache-2.0 License.