# Teacher Reference Caches

Ready-made teacher reference artifacts for the teacher-normalized
distribution evaluation of
[DistillAlign](https://huggingface.co/LiJiaxing/DistillAlign). They replace
the `teacher-sample` + `extract` stage entirely: pass the `.npz` file to
`--teacher-features` and only the student side needs to be generated.

## Contents

```text
wan2.1_t2v_1.3b_reference_vjepa2.npz        V-JEPA2 features, 256 x 2560
wan2.1_t2v_1.3b_reference_vjepa2.meta.json  extraction + sampling protocol
wan2.1_t2v_14b_reference_vjepa2.npz
wan2.1_t2v_14b_reference_vjepa2.meta.json
videos/wan2.1_t2v_1.3b_reference/           256 reference videos (p{prompt}_s{seed}.mp4)
videos/wan2.1_t2v_14b_reference/            256 reference videos
```

## Protocol

Both caches follow the paper protocol:

- Teacher: Wan2.1-T2V-1.3B / Wan2.1-T2V-14B, 25-step UniPC, timestep
  shift 8.0, classifier-free guidance 5.0, official negative prompt.
- Grid: 16 prompts (`prompts/distribution_eval_16.txt`) x 16 seeds
  (`11,22,33,42,44,55,66,77,88,123,456,789,2024,3407,7777,9999`),
  256 samples per teacher.
- Features: `facebook/vjepa2-vith-fpc64-256`, 8 uniform frames from the
  first 81 frames, token mean/std concat pooling, L2-normalized, 2560-D.

The exact extractor fingerprint and prompt/seed hash are embedded in each
`.npz` and validated by the metric CLI, which rejects incompatible student
caches instead of producing incomparable numbers.

## Usage

```bash
python evaluate_distribution.py run \
  --checkpoint checkpoints/distillalign_distill_14b_teacher.pt \
  --jobs outputs/eval_jobs.jsonl \
  --teacher-model Wan2.1-T2V-14B \
  --teacher-features teacher_caches/wan2.1_t2v_14b_reference_vjepa2.npz \
  --output-dir outputs/my_eval
```

The videos are provided for inspection and for re-extraction under future
feature encoders; they are not needed when using the `.npz` caches.