# ECG RVQ · 8× with entropy prior

Reproduce the `ecg-rvq-8x-prior` configuration. Prepare its dataset before running the workflow; use the linked configuration to inspect the exact settings.

## Overview

## Dataset & License

- **Dataset**: [PTB-XL](https://physionet.org/content/ptb-xl/) (`dataset_id: ptb-xl`)
- **License**: CC BY 4.0 (open)
- **Notes**: Auto-downloaded on first use.

The lifecycle runner pre-flights dataset availability before training (see the
[dataset contract](https://ambiqai.github.io/compressionkit/api/datasets/)).

## Reproduction

```bash
# Single command, end-to-end.
uv run compressionkit golden run ecg-rvq-8x-prior

```

Results land under `results/ecg_rvq_256hz_08x_golden/`; deploy artifacts under `results/ecg_rvq_256hz_08x_golden/deploy/`.

## Parent codec

The parent codec now uses corrected v1.1 exports. This prior remains on its
historical v1.0 track and has not been requalified for that release.

This entry is the entropy-prior stage paired with [`ecg-rvq-8x`](https://ambiqai.github.io/compressionkit/experiments/ecg-rvq-8x/).
The historical codec and prior artifacts use the v1.0 HuggingFace repo
([`Ambiq/compressionkit-ecg-8x-v1.0`](https://huggingface.co/Ambiq/compressionkit-ecg-8x-v1.0)).

## Evaluation Metrics

See the modality model zoo for the full metrics table:

- [ECG models](https://ambiqai.github.io/compressionkit/models/ecg/)

Evaluation writes `quality_scorecard.json` and `summary.json` under its `results/<run>/`.

## Deploy Artifacts

The deploy package contains the following artifacts, depending on the export configuration:

- `encoder.tflite` / `encoder.h` — INT8 encoder.
- `encoder.keras` — float32 Python reference encoder.
- `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8).
- `decoder.keras` — float32 Python reference decoder.
- `codebook.npz` / `codebook.h` — RVQ codebook tables.
- `sample_data.npz` — normalized synthetic inputs, targets and reconstructions; `sample_stimulus.npz` contains raw synthetic waveforms.
- `model_card.json`, `deploy_manifest.json` — metadata.
- `prior_int8.tflite` / `prior_int8.h` / `prior_manifest.json` — entropy prior (two-stage only).

## Customization Notes

- Tweak the YAML to explore neighbouring operating points; copy the file before editing.
- For new recipes, prefer the `compressionkit/recipes/` package recipes as a starting point.
- Publication is blocked until the prior is requalified against its parent's corrected v1.1 release.