Skip to content

ppg-rvq-4x-prior

Overview

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. Published v1 PPG goldens are MESA-free. Build the cache with scripts/build_ppg_cache.py.

The lifecycle runner pre-flights dataset availability before training (see #26 and the dataset contract).

Reproduction

# Single command, end-to-end.
uv run compressionkit golden run ppg-rvq-4x-prior

# Publish the deploy package to HuggingFace (requires HF_TOKEN).
uv run compressionkit golden run ppg-rvq-4x-prior --publish

Results land under results/ppg_rvq_64hz_04x_golden/; deploy artifacts under results/ppg_rvq_64hz_04x_golden/deploy/.

Parent codec

This entry is the entropy-prior stage paired with ppg-rvq-4x. Codec and prior artifacts publish to the same HuggingFace repo (Ambiq/compressionkit-ppg-4x-v1.0).

Evaluation Metrics

See the modality model zoo for the full metrics table:

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

Deploy Artifacts

Every successful run produces the canonical edge deploy package:

  • 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 — license-safe input/target/reconstruction reference frames (published to HuggingFace as sample_stimulus.npz).
  • 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-4x-prior --publish.