Upload README.md with huggingface_hub

README.md

@@ -16,24 +16,72 @@ arxiv: "2603.29078"
 
 **PQ5 quantized** LTX-2.3 — joint audio-video generation, 22B params.
 
-**46 GB → ~19 GB (-59%)** | cos_sim **0.9986** | 1347 layers quantized
+**46 GB → 15 GB (-68%)** | cos_sim **0.9986** | 1,347 layers quantized
+
+## Download Size
+
+![Download](https://huggingface.co/caiovicentino1/LTX-2.3-22B-PolarQuant-Q5/resolve/main/assets/chart_download.png)
 
 ## Compression
 
-| Component | Original | PQ5 Packed |
-|---|---|---|
-| **Transformer (48 blocks)** | ~44 GB | ~17 GB |
-| **Audio/Video VAE** | ~0.1 GB | 0.1 GB (BF16) |
-| **Text embeddings** | ~2 GB | 2 GB (BF16) |
-| **Upscalers** | ~2.3 GB | 2.3 GB (BF16) |
-| **Total** | **46.2 GB** | **~19 GB (-59%)** |
+![Compression](https://huggingface.co/caiovicentino1/LTX-2.3-22B-PolarQuant-Q5/resolve/main/assets/chart_compression.png)
+
+| Component | Original | PQ5 Packed | Reduction |
+|---|---|---|---|
+| **Transformer (1,347 layers)** | 37 GB | 4.6 GB | -88% |
+| **VAE + Skip (4,600 layers)** | 9.1 GB | 9.1 GB | BF16 kept |
+| **Upscalers** | 1.3 GB | 1.3 GB | BF16 kept |
+| **Total** | **46.2 GB** | **15 GB** | **-68%** |
+
+## Quick Start
+
+```bash
+# 1. Install
+pip install safetensors huggingface_hub scipy
+
+# 2. Download & setup (15 GB)
+git clone https://huggingface.co/caiovicentino1/LTX-2.3-22B-PolarQuant-Q5 ./LTX-PQ5
+cd LTX-PQ5 && python setup.py
+
+# 3. Generate video
+python generate_ltx.py --prompt "A cat playing piano in a jazz club"
+```
 
 ## Architecture
 
+- **22B parameters** — largest video model we've quantized
 - 48 transformer blocks, hidden=4096, MLP=16384
-- Joint audio-video generation
-- Single safetensors file (5947 tensors)
-- BF16 native
+- **Joint audio-video generation** — synchronized audio + video
+- head_dim=64 (Hadamard-compatible)
+- 5,947 tensors total (BF16)
+- Spatial + temporal upscalers included
+
+## Files
+
+```
+LTX-2.3-22B-PolarQuant-Q5/
+├── setup.py                          # One-command setup
+├── generate_ltx.py                   # Easy generation wrapper
+├── polarquant/
+│   ├── codes/
+│   │   ├── chunk_00_codes.safetensors (1.5 GB)
+│   │   ├── chunk_01_codes.safetensors (1.5 GB)
+│   │   ├── chunk_02_codes.safetensors (1.5 GB)
+│   │   └── chunk_03_codes.safetensors (0.1 GB)
+│   └── bf16/
+│       └── ltx23_bf16.safetensors    (9.1 GB)
+└── upscalers/
+    ├── ltx-2.3-spatial-upscaler-x2-1.1.safetensors  (1.0 GB)
+    └── ltx-2.3-temporal-upscaler-x2-1.0.safetensors (0.3 GB)
+```
+
+## Hardware
+
+| GPU | VRAM | Status |
+|-----|------|--------|
+| A100 (40 GB) | 40 GB | Recommended |
+| A100 (80 GB) | 80 GB | Full speed |
+| RTX 4090 (24 GB) | 24 GB | With offloading |
 
 ## Links
 
@@ -42,3 +90,17 @@ arxiv: "2603.29078"
 - [Original LTX-2.3](https://huggingface.co/Lightricks/LTX-2.3)
 - [LTX-2 Paper](https://arxiv.org/abs/2601.03233)
 - [LTX GitHub](https://github.com/Lightricks/LTX-2)
+
+## Citation
+
+```bibtex
+@article{polarquant2026,
+  title={PolarQuant: Hadamard-Rotated Lloyd-Max Quantization},
+  author={Vicentino, Caio},
+  journal={arXiv preprint arXiv:2603.29078},
+  year={2026}
+}
+```
+
+---
+*46 GB → 15 GB with cos_sim 0.9986. Quantized with [PolarQuant](https://github.com/caiovicentino/polarengine-vllm).*