Skip to content
compressionKIT
Getting started
HELIA

Load a Hugging Face bundle

Corrected single-stage RVQ bundles use Ambiq/compressionkit-{modality}-{cr}x-v1.1. The original v1.0 bundles remain available for historical results and packets. See release details for compatibility and validation. This page shows the minimum code to download one and run the encoder + decoder on a sample frame. SPIHT and hybrid package links are listed on their experiment pages. The RVQ example below uses the RVQ-specific loader.

1. Install

Section titled “1. Install”

From the source checkout:

Terminal window
uv sync --python 3.12 --extra hf

The hf extra adds huggingface_hub for downloading bundles. Inference can run offline once a bundle is on disk — the extra is only needed for the snapshot_download / from_pretrained calls below.

2. Single-stage codec

Section titled “2. Single-stage codec”

Single-stage repos contain encoder_int8.tflite, encoder_float32.tflite, decoder_int8.tflite, codebook.npz, normalized synthetic sample_data.npz, raw synthetic sample_stimulus.npz, independent reference_vectors.npz, and checksums.json. Real demo recordings are optional. The float32 encoder supports browser and host LiteRT integrations with float32 I/O. RVQCodec.from_pretrained downloads the bundle and wires up the LiteRT interpreters. Use the full source-checkout installation above: package imports also require Keras and evaluation dependencies.

from huggingface_hub import snapshot_download
from compressionkit.runtime import RVQCodec
import numpy as np


repo = "Ambiq/compressionkit-ppg-4x-v1.1"
codec = RVQCodec.from_pretrained(repo)


# Sanity check on the bundled license-safe sample (same cached files).
# sample_data carries normalized inputs, targets, and reconstructions.
deploy_dir = snapshot_download(repo)
signal = np.load(f"{deploy_dir}/sample_data.npz")["inputs"][:1]
indices = codec.encode(signal)
recon = codec.decode(indices)
print("shape:", recon.shape)

demo_recordings.npz holds ten real, quality-gated continuous examples at the model rate (signals has shape (10, samples)). Read demo_recordings_manifest.json with it: the manifest records source provenance, ODC-By attribution, signal offsets, and the quality measurements used for selection. Apply the model’s usual framing and normalization before inference.

For each 64 Hz PPG 320-sample frame or 256 Hz ECG 512-sample frame, use per-frame layer normalization before either encoder variant:

mean = frame.mean()
scale = np.sqrt(np.mean((frame - mean) ** 2) + 1e-3)
encoder_input = (frame - mean) / scale

For display in raw units, undo it after decoding with decoded * scale + mean. INT8 RVQ releases produced under the current release policy include quantization_report.json, which records parity against encoder_float32.tflite on a 2,048-frame real-preprocessed holdout distinct from the 4,096 frames used for LiteRT calibration.

To refresh all local RVQ bundles before publishing an asset update:

Terminal window
scripts/devcontainer.sh exec -- uv run python scripts/attach_rvq_demo_recordings.py --modality all

3. Two-stage codec (codec + entropy prior)

Section titled “3. Two-stage codec (codec + entropy prior)”

Two-stage deploy packages add prior_int8.tflite and prior_manifest.json. Use TwoStageCodec to estimate entropy-prior bitrate uplift on top of the codec’s downsample ratio.

from compressionkit.runtime import RVQCodec
from compressionkit.runtime.prior import EntropyPrior
from compressionkit.runtime.two_stage import TwoStageCodec
import numpy as np


deploy_dir = "results/ppg_rvq_64hz_08x_golden/deploy"  # locally built (golden run)
codec = RVQCodec(deploy_dir)
prior = EntropyPrior(f"{deploy_dir}/prior_int8.tflite")
two_stage = TwoStageCodec(codec, prior)


sample = np.load(f"{deploy_dir}/sample_data.npz")["inputs"][:1]
indices = codec.encode(sample)
rates = two_stage.estimate_bitrate(indices)
print(f"CR uplift estimate: {rates['cr_uplift']:.2f}x")

4. Where to look next

Section titled “4. Where to look next”