# PPG RVQ · 8×

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

## Overview

The v1.1 bundle corrects the export of the existing checkpoint without retraining.
Its physiological scorecard remains historical; see [release validation](https://ambiqai.github.io/compressionkit/rvq-v11-release/).

## 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-8x

```

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

## Two-Stage Variant

Paired entropy prior: [`ppg-rvq-8x-prior`](https://ambiqai.github.io/compressionkit/experiments/ppg-rvq-8x-prior/). Run via the lifecycle runner to chain codec → prior
and bundle `prior_int8.tflite` into this experiment's `deploy/`.

## 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.
- To resume publishing without retraining, pass `--skip-train` to `compressionkit golden run ppg-rvq-8x --publish`.