Module spherical 

Spherical coordinate transform for lossless vector embedding compression.

L2-normalized embeddings (standard for cosine similarity search) live on a hypersphere. Converting from Cartesian to spherical coordinates collapses IEEE 754 exponent bits to predictable values and regularizes high-order mantissa bits. After transformation, lz4_flex achieves ~1.5x lossless compression — 25% better than any previous lossless method on embeddings.

The transform is lossless within f32 machine epsilon: reconstruction error < 1e-7.

Wire format:

[4 bytes] dimension count (LE u32)
[4 bytes] vector count (LE u32)
[1 byte]  transform type (0=cartesian/raw, 1=spherical)
[N bytes] compressed data (lz4 over transformed f32 bytes)

Functions

decode

Decode spherical-compressed embeddings back to f32 Cartesian coordinates.

encode

Encode f32 embeddings using spherical coordinate transformation + lz4.

encode_raw

Encode f32 embeddings without transformation (raw + lz4).

normalization_ratio

Check if embeddings are L2-normalized (suitable for spherical transform).