# PPG RVQ · 4× with entropy prior

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

## Overview

## Dataset & License

- **Dataset**: [Open unified PPG v1](https://ambiqai.github.io/compressionkit/datasets/) (`dataset_id: ppg-unified-strict-sanitize-v1`)
- **License**: Open (BIDMC, BUT PPG, PPG-DaLiA, WESAD — mixed open licenses, no restricted-access dependency)
- **Notes**: Sources: BIDMC, BUT PPG, PPG-DaLiA, and WESAD. The saved training configuration uses these open sources; complete pretraining ancestry was not independently audited in the export repair. Build the cache with `scripts/build_ppg_cache.py`.

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 ppg-rvq-4x-prior

```

Results land under `results/ppg_rvq_64hz_04x_golden/`; deploy artifacts under `results/ppg_rvq_64hz_04x_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 [`ppg-rvq-4x`](https://ambiqai.github.io/compressionkit/experiments/ppg-rvq-4x/).
The historical codec and prior artifacts use the v1.0 HuggingFace repo
([`Ambiq/compressionkit-ppg-4x-v1.0`](https://huggingface.co/Ambiq/compressionkit-ppg-4x-v1.0)).

## Evaluation Metrics

See the modality model zoo for the full metrics table:

- [PPG models](https://ambiqai.github.io/compressionkit/models/ppg/)

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.