From 19873c9b591f712440c5e4f445e62cabd6482833 Mon Sep 17 00:00:00 2001 From: Adam Page Date: Fri, 3 Jul 2026 17:59:51 +0000 Subject: [PATCH] docs: fix RVQ deploy-artifact list to use local sample_data.npz naming (#60) render_experiment_docs.py's "Deploy Artifacts" section otherwise describes local results//deploy/ naming (encoder.tflite, decoder.keras, etc.), but the RVQ bullet list named sample_stimulus.npz -- which is only guaranteed to exist when a package was built via the compressionkit golden repackage path (experiments/repackage.py), not via the normal training recipe (recipes/base_rvq.py -> export_for_deployment(), which only ever writes sample_data.npz locally). sample_stimulus.npz IS the correct HuggingFace-published name (RVQ_HF_FILE_RENAMES maps sample_data.npz -> sample_stimulus.npz), but using it in a section otherwise describing local file names was inconsistent and could reference a non-existent local file depending on build path. Fixed by describing the actual local name (sample_data.npz, which every RVQ deploy package has regardless of build path) with a note about its HF-published name, matching the pattern already used correctly in docs/deployment.md and docs/release-contract.md. The SPIHT/hybrid branch already used sample_stimulus.npz correctly (that family's export_spiht_deploy() unconditionally writes that exact local filename, no ambiguity) -- left unchanged. Regenerated all 15 affected RVQ/two-stage experiment doc pages. Closes #60 --- docs/experiments/ecg-rvq-16x.md | 2 +- docs/experiments/ecg-rvq-2x.md | 2 +- docs/experiments/ecg-rvq-32x.md | 2 +- docs/experiments/ecg-rvq-4x-prior.md | 2 +- docs/experiments/ecg-rvq-4x.md | 2 +- docs/experiments/ecg-rvq-64x.md | 2 +- docs/experiments/ecg-rvq-8x-prior.md | 2 +- docs/experiments/ecg-rvq-8x.md | 2 +- docs/experiments/ppg-rvq-16x.md | 2 +- docs/experiments/ppg-rvq-2x.md | 2 +- docs/experiments/ppg-rvq-32x.md | 2 +- docs/experiments/ppg-rvq-4x-prior.md | 2 +- docs/experiments/ppg-rvq-4x.md | 2 +- docs/experiments/ppg-rvq-8x-prior.md | 2 +- docs/experiments/ppg-rvq-8x.md | 2 +- scripts/render_experiment_docs.py | 3 ++- 16 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/experiments/ecg-rvq-16x.md b/docs/experiments/ecg-rvq-16x.md index ab69f33..94c79b3 100644 --- a/docs/experiments/ecg-rvq-16x.md +++ b/docs/experiments/ecg-rvq-16x.md @@ -53,7 +53,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `sample_data.npz` — license-safe input/target/reconstruction reference frames (published to HuggingFace as `sample_stimulus.npz`). - `model_card.json`, `deploy_manifest.json` — metadata. ## Customization Notes diff --git a/docs/experiments/ecg-rvq-2x.md b/docs/experiments/ecg-rvq-2x.md index 9df4cb2..2d9a1c1 100644 --- a/docs/experiments/ecg-rvq-2x.md +++ b/docs/experiments/ecg-rvq-2x.md @@ -53,7 +53,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `sample_data.npz` — license-safe input/target/reconstruction reference frames (published to HuggingFace as `sample_stimulus.npz`). - `model_card.json`, `deploy_manifest.json` — metadata. ## Customization Notes diff --git a/docs/experiments/ecg-rvq-32x.md b/docs/experiments/ecg-rvq-32x.md index 141fc45..79698e1 100644 --- a/docs/experiments/ecg-rvq-32x.md +++ b/docs/experiments/ecg-rvq-32x.md @@ -53,7 +53,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `sample_data.npz` — license-safe input/target/reconstruction reference frames (published to HuggingFace as `sample_stimulus.npz`). - `model_card.json`, `deploy_manifest.json` — metadata. ## Customization Notes diff --git a/docs/experiments/ecg-rvq-4x-prior.md b/docs/experiments/ecg-rvq-4x-prior.md index 1e96a26..fa9a68d 100644 --- a/docs/experiments/ecg-rvq-4x-prior.md +++ b/docs/experiments/ecg-rvq-4x-prior.md @@ -59,7 +59,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `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). diff --git a/docs/experiments/ecg-rvq-4x.md b/docs/experiments/ecg-rvq-4x.md index c44030b..93cded0 100644 --- a/docs/experiments/ecg-rvq-4x.md +++ b/docs/experiments/ecg-rvq-4x.md @@ -58,7 +58,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `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). diff --git a/docs/experiments/ecg-rvq-64x.md b/docs/experiments/ecg-rvq-64x.md index 733df97..27f1c92 100644 --- a/docs/experiments/ecg-rvq-64x.md +++ b/docs/experiments/ecg-rvq-64x.md @@ -53,7 +53,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `sample_data.npz` — license-safe input/target/reconstruction reference frames (published to HuggingFace as `sample_stimulus.npz`). - `model_card.json`, `deploy_manifest.json` — metadata. ## Customization Notes diff --git a/docs/experiments/ecg-rvq-8x-prior.md b/docs/experiments/ecg-rvq-8x-prior.md index 2798df9..4ad2950 100644 --- a/docs/experiments/ecg-rvq-8x-prior.md +++ b/docs/experiments/ecg-rvq-8x-prior.md @@ -59,7 +59,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `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). diff --git a/docs/experiments/ecg-rvq-8x.md b/docs/experiments/ecg-rvq-8x.md index 9825126..4bd16fe 100644 --- a/docs/experiments/ecg-rvq-8x.md +++ b/docs/experiments/ecg-rvq-8x.md @@ -58,7 +58,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `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). diff --git a/docs/experiments/ppg-rvq-16x.md b/docs/experiments/ppg-rvq-16x.md index 23b5212..26b3918 100644 --- a/docs/experiments/ppg-rvq-16x.md +++ b/docs/experiments/ppg-rvq-16x.md @@ -53,7 +53,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `sample_data.npz` — license-safe input/target/reconstruction reference frames (published to HuggingFace as `sample_stimulus.npz`). - `model_card.json`, `deploy_manifest.json` — metadata. ## Customization Notes diff --git a/docs/experiments/ppg-rvq-2x.md b/docs/experiments/ppg-rvq-2x.md index 193faa8..858eb69 100644 --- a/docs/experiments/ppg-rvq-2x.md +++ b/docs/experiments/ppg-rvq-2x.md @@ -53,7 +53,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `sample_data.npz` — license-safe input/target/reconstruction reference frames (published to HuggingFace as `sample_stimulus.npz`). - `model_card.json`, `deploy_manifest.json` — metadata. ## Customization Notes diff --git a/docs/experiments/ppg-rvq-32x.md b/docs/experiments/ppg-rvq-32x.md index 59840b7..451f181 100644 --- a/docs/experiments/ppg-rvq-32x.md +++ b/docs/experiments/ppg-rvq-32x.md @@ -53,7 +53,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `sample_data.npz` — license-safe input/target/reconstruction reference frames (published to HuggingFace as `sample_stimulus.npz`). - `model_card.json`, `deploy_manifest.json` — metadata. ## Customization Notes diff --git a/docs/experiments/ppg-rvq-4x-prior.md b/docs/experiments/ppg-rvq-4x-prior.md index c368156..2e93eb6 100644 --- a/docs/experiments/ppg-rvq-4x-prior.md +++ b/docs/experiments/ppg-rvq-4x-prior.md @@ -59,7 +59,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `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). diff --git a/docs/experiments/ppg-rvq-4x.md b/docs/experiments/ppg-rvq-4x.md index 62958a7..c572b2b 100644 --- a/docs/experiments/ppg-rvq-4x.md +++ b/docs/experiments/ppg-rvq-4x.md @@ -58,7 +58,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `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). diff --git a/docs/experiments/ppg-rvq-8x-prior.md b/docs/experiments/ppg-rvq-8x-prior.md index c7ca798..93c6a70 100644 --- a/docs/experiments/ppg-rvq-8x-prior.md +++ b/docs/experiments/ppg-rvq-8x-prior.md @@ -59,7 +59,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `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). diff --git a/docs/experiments/ppg-rvq-8x.md b/docs/experiments/ppg-rvq-8x.md index 9c62f9c..da62c75 100644 --- a/docs/experiments/ppg-rvq-8x.md +++ b/docs/experiments/ppg-rvq-8x.md @@ -58,7 +58,7 @@ Every successful run produces the canonical edge deploy package: - `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8). - `decoder.keras` — float32 Python reference decoder. - `codebook.npz` / `codebook.h` — RVQ codebook tables. -- `sample_stimulus.npz` — license-safe input/output reference frames. +- `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). diff --git a/scripts/render_experiment_docs.py b/scripts/render_experiment_docs.py index e8b45d1..abc3ee3 100644 --- a/scripts/render_experiment_docs.py +++ b/scripts/render_experiment_docs.py @@ -227,7 +227,8 @@ def _render_experiment(exp: GoldenExperiment) -> str: "- `decoder.tflite` / `decoder.h` — decoder (float32 + optional INT8).", "- `decoder.keras` — float32 Python reference decoder.", "- `codebook.npz` / `codebook.h` — RVQ codebook tables.", - "- `sample_stimulus.npz` — license-safe input/output reference frames.", + "- `sample_data.npz` — license-safe input/target/reconstruction reference frames " + "(published to HuggingFace as `sample_stimulus.npz`).", "- `model_card.json`, `deploy_manifest.json` — metadata.", ] else: