Skip to content
compressionKIT
Models & experiments
HELIA

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

Section titled “Overview”

Dataset & License

Section titled “Dataset & License”
  • Dataset: Open unified PPG v1 (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).

Reproduction

Section titled “Reproduction”
Terminal window
# 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

Section titled “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. The historical codec and prior artifacts use the v1.0 HuggingFace repo (Ambiq/compressionkit-ppg-4x-v1.0).

Evaluation Metrics

Section titled “Evaluation Metrics”

See the modality model zoo for the full metrics table:

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

Deploy Artifacts

Section titled “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

Section titled “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.