# 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](https://ambiqai.github.io/compressionkit/rvq-v11-release/) 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](https://ambiqai.github.io/compressionkit/experiments/). The RVQ example below uses the RVQ-specific loader.

## 1. Install

From the [source checkout](https://ambiqai.github.io/compressionkit/getting-started/#1-install):

```bash
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

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`](https://ambiqai.github.io/compressionkit/reference/api/compressionkit/runtime/codec/#compressionkit.runtime.codec.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.

```python
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:

```python
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:

```bash
scripts/devcontainer.sh exec -- uv run python scripts/attach_rvq_demo_recordings.py --modality all
```

:::note[Note]
Use `RVQCodec.from_pretrained(repo_id)` rather than `RVQCodec(local_dir)` on a raw
`snapshot_download` directory. Older HuggingFace bundles use `config.json` and
`*_int8.tflite` aliases; `from_pretrained` reconciles those names. The v1.1
releases retain the canonical deploy filenames as well as the aliases and can
be validated directly.

:::

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

:::note[Use a package containing a prior]
The optional entropy-prior stage (`prior_int8.tflite` + `prior_manifest.json`) is
reproducible from the `*-prior` golden registry entries
(`compressionkit golden list` → `ppg-rvq-4x-prior`, `ppg-rvq-8x-prior`,
`ecg-rvq-4x-prior`, `ecg-rvq-8x-prior`) and runs from locally built deploy
packages. The snippet below uses that local-package path, so
reproduce one first, e.g. `uv run compressionkit golden run ppg-rvq-8x-prior`.

:::

Two-stage deploy packages add `prior_int8.tflite` and `prior_manifest.json`. Use
[`TwoStageCodec`](https://ambiqai.github.io/compressionkit/reference/api/compressionkit/runtime/two_stage/#compressionkit.runtime.two_stage.TwoStageCodec) to estimate entropy-prior bitrate uplift on top
of the codec's downsample ratio.

```python
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

- [Experiments index](https://ambiqai.github.io/compressionkit/experiments/) — every golden + its reproduction command.
- [Deployment guide](https://ambiqai.github.io/compressionkit/deployment/) — moving the same artifacts onto an Ambiq-class MCU.
- [Model Zoo](https://ambiqai.github.io/compressionkit/models/) — full quality metrics for each tier.