VQ-Pocket

VQ-Pocket is a discrete-latent generative model for handwritten digits. A compact VQ-VAE compresses each 8x8 image into sixteen tokens from a 32-entry visual codebook. A class-conditional GRU then models those tokens autoregressively.

The codebook is initialized from warm-started encoder activations with k-means before joint vector-quantized training. This avoids presenting a collapsed codebook as a successful discrete representation. The report includes active-code count, codebook perplexity, reconstruction fidelity, generation fidelity, and unique token-sequence rate.

Verified local result

The 14,193-parameter VQ-VAE used every one of its 32 codes and reached an effective codebook perplexity of 22.72. Its held-out reconstruction MSE was 0.00673 with 95.93% frozen-judge fidelity. The 28,512-parameter conditional prior generated 1,000 samples at 95.6% class fidelity with 99.6% unique code sequences.

Reproduce

uv run python projects/vq-pocket/train.py
uv run pytest tests/test_vq_pocket.py

The model bundle contains both SafeTensors checkpoints and measured evaluation artifacts. The Space displays decoded samples beside the 4x4 token map that generated them. Local artifacts do not imply that the Hub repositories are live.