Skip to content

ecg-rvq-8x

Overview

Dataset & License

  • Dataset: 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 #26 and the dataset contract).

Reproduction

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

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

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

Two-Stage Variant

Paired entropy prior: ecg-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:

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 ecg-rvq-8x --publish.