Update README: remove broken github link, point to bundled code

README.md

@@ -22,10 +22,87 @@ tags:
 
 # Lance-3B-Video-MLX
 
-Video variant of [Lance-3B-MLX](https://huggingface.co/RockTalk/Lance-3B-MLX). First native [MLX](https://github.com/ml-explore/mlx) port of [ByteDance Research's Lance](https://huggingface.co/bytedance-research/Lance) — a 3B-parameter unified multimodal model for image/video generation, editing, and understanding. Runs natively on Apple Silicon, no CUDA required.
+Video variant of [Lance-3B-MLX](https://huggingface.co/RockTalk/Lance-3B-MLX). First native [MLX](https://github.com/ml-explore/mlx) port of [ByteDance Research's Lance](https://huggingface.co/bytedance-research/Lance) — a 3 B-parameter unified multimodal model for image/video generation, editing, and understanding. Runs natively on Apple Silicon, no CUDA required.
 
 The architecture is **Qwen2.5-VL-3B + parallel MoE-gen experts + Wan 2.2 VAE**. Lance uses a "Mixture-of-Tokens" routing: every attention block and MLP has a parallel `*_moe_gen` branch. Text tokens go through normal weights; VAE-latent (generation) tokens go through the `_moe_gen` weights, in the same forward pass.
 
+## Quick start (self-contained — no external repo needed)
+
+```bash
+# 1. Download the model (one-time, ~30 GB total)
+hf download RockTalk/Lance-3B-Video-MLX --local-dir Lance-3B-Video-MLX
+
+# 2. Install runtime deps
+cd Lance-3B-Video-MLX
+pip install -r requirements.txt
+
+# 3. Generate a 9-frame video (T_lat=3 → 9 output frames)
+python inference.py --prompt "a calm ocean wave rolling onto a sandy beach"
+
+# Longer video (29 frames):
+python inference.py --prompt "..." --t-lat 8
+
+# Pure image (T_lat=1):
+python inference.py --prompt "..." --t-lat 1 --size 512 --steps 30
+```
+
+First run auto-fetches the companion VAE ([`RockTalk/Wan2.2-VAE-MLX`](https://huggingface.co/RockTalk/Wan2.2-VAE-MLX), ~2.6 GB, cached as `wan22_vae.safetensors`) so all subsequent runs are fully offline.
+
+### CLI options
+
+```
+python inference.py \
+  --prompt "..." \
+  --out output.png       # frame strip + per-frame PNGs saved next to it
+  --size 256             # 256 recommended for T2V
+  --t-lat 3              # latent frames; output = (t_lat-1)*4 + 1 frames
+  --steps 24             # 24 typical for T2V
+  --cfg 4.0
+  --seed 0
+  --mp4                  # also emit output.mp4 (needs `pip install 'imageio[ffmpeg]'`)
+  --fps 8
+```
+
+Frame-count table: `T_lat=1 → 1`, `T_lat=3 → 9`, `T_lat=8 → 29`, `T_lat=31 → 121` (max).
+
+### Programmatic use
+
+```python
+from inference import build_lance_config, ensure_vae_weights
+from lance_mlx.lance import Lance, LanceConfig
+from lance_mlx.vae_wan22 import Wan2_2_VAE
+from transformers import AutoTokenizer
+import json, mlx.core as mx
+from pathlib import Path
+
+repo = Path(".")
+cfg_json = json.loads((repo / "config.json").read_text())
+lance_cfg = build_lance_config(cfg_json)
+
+model = Lance(lance_cfg)
+weights = mx.load("model.safetensors")
+non_vit = {k: v for k, v in weights.items() if not k.startswith("vit_model.")}
+model.load_weights(list(non_vit.items()), strict=True)
+
+vae = Wan2_2_VAE(z_dim=48, c_dim=160, dim_mult=(1, 2, 4, 4),
+                 temperal_downsample=(False, True, True))
+vae.model.load_weights(list(mx.load(str(ensure_vae_weights(repo))).items()), strict=True)
+
+tok = AutoTokenizer.from_pretrained(".")
+text_ids = mx.array(tok("a calm ocean wave", add_special_tokens=False,
+                        return_tensors="np").input_ids[0], dtype=mx.int32)
+
+latent = model.sample_t2i(
+    prompt_token_ids=text_ids,
+    latent_shape=(3, 16, 16),    # T_lat=3 → 9 output frames @ 256×256
+    special_token_ids={"bos": 151644, "eos": 151645,
+                       "start_of_image": 151652, "end_of_image": 151653,
+                       "image_token_id": 151655},
+    num_steps=24, timestep_shift=3.5, cfg_scale=4.0, seed=0,
+)
+video = vae.decode(latent)        # (1, 9, 256, 256, 3) in [-1, 1]
+```
+
 ## What works
 
 | Capability | Status |
@@ -70,64 +147,25 @@ First-call kernel-compile penalty: ~few seconds per new resolution.
 ## Differences vs Lance-3B-MLX
 
 This is the same architecture as the image variant, with two differences:
+
 - `model.safetensors`: 26.5 GB (vs 23 GB) — extra weights for multi-frame attention
 - `latent_pos_embed.pos_embed`: 31 × 64 × 64 = 126,976 positions (vs 1 × 64 × 64 = 4,096) — supports up to 31 latent frames (≈ 121 video frames @ 4× temporal downsample)
 
 T2I via this checkpoint works the same as Lance-3B-MLX. **T2V is now live** — uses the [Wan 2.2 VAE v0.1.0 streaming cache](https://huggingface.co/RockTalk/Wan2.2-VAE-MLX) under the hood. Pass `latent_shape=(T_lat, H_lat, W_lat)` with `T_lat > 1` to `sample_t2i` to generate a video.
 
-T_lat → output frames: T = (T_lat - 1) × 4 + 1.
-- T_lat=1 → 1 frame (image)
-- T_lat=3 → 9 frames
-- T_lat=8 → 29 frames
-- T_lat=31 → 121 frames (max for this checkpoint)
-
 ## Files
 
 | File | Size | Description |
 |---|---|---|
 | `model.safetensors` | 26.5 GB | LLM (Qwen2.5-VL with MoE-gen) + Lance adapters + bundled ViT (`vit_model.*` prefix), 1411 tensors total |
 | `vit.safetensors` | 1.25 GB | Qwen2.5-VL ViT, also extractable from `model.safetensors` |
-| `vae.safetensors` | 2.62 GB | Wan 2.2 VAE (older keying — for compatibility; the standalone [RockTalk/Wan2.2-VAE-MLX](https://huggingface.co/RockTalk/Wan2.2-VAE-MLX) is recommended) |
+| `vae.safetensors` | 2.62 GB | Wan 2.2 VAE (older "nested-conv" keying, kept for archival — `inference.py` auto-fetches the cleanly-keyed [RockTalk/Wan2.2-VAE-MLX](https://huggingface.co/RockTalk/Wan2.2-VAE-MLX) instead) |
 | `config.json` | — | Distilled architecture config |
 | `tokenizer.json`, `vocab.json`, `merges.txt` | — | Qwen2.5-VL tokenizer, verbatim |
 | `samples/ocean_wave_*.png` | — | Verified 9-frame T2V outputs |
-
-## Usage
-
-Requires `mlx >= 0.29`, `mlx-vlm >= 0.3`, `numpy`, `einops`, `transformers`, `pillow`, and the [`lance-mlx`](https://github.com/RockTalk/Lance-MLX) companion repo for the `Lance` Python class.
-
-```bash
-pip install mlx mlx-vlm numpy einops transformers pillow
-```
-
-```python
-import mlx.core as mx
-from lance_mlx.lance import Lance, LanceConfig
-from lance_mlx.vae_wan22 import Wan2_2_VAE
-
-# Build + strict-load (see tools/lance_t2i.py in the companion repo for the
-# full builder; LanceConfig takes a Qwen2.5-VL ModelConfig built from
-# config.json).
-model = Lance(lance_cfg)
-model.load_weights(list(mx.load("model.safetensors").items()), strict=True)
-
-vae = Wan2_2_VAE(z_dim=48, c_dim=160, dim_mult=(1, 2, 4, 4),
-                 temperal_downsample=(False, True, True))
-vae.model.load_weights(list(mx.load("vae.safetensors").items()), strict=True)
-
-# Sample
-latent = model.sample_t2i(
-    prompt_token_ids=text_ids,                  # (P,) int32 from tokenizer (no specials)
-    latent_shape=(1, 32, 32),                   # (T_lat, H_lat, W_lat) for 512×512 image
-    special_token_ids={"bos": 151644, "eos": 151645,
-                       "start_of_image": 151652, "end_of_image": 151653,
-                       "image_token_id": 151655},
-    num_steps=30, timestep_shift=3.5, cfg_scale=4.0, seed=0,
-)
-img = vae.decode(latent)                        # (1, 1, 512, 512, 3) in [-1, 1]
-```
-
-End-to-end script: `tools/lance_t2i.py` in the [companion repo](https://github.com/RockTalk/Lance-MLX).
+| `lance_mlx/` | — | **Bundled MLX implementation** (model + VAE + utils) |
+| `inference.py` | — | **Self-contained T2V/T2I runner** |
+| `requirements.txt` | — | Pip dependencies |
 
 ## How the MoE-gen routing is implemented in MLX
 
@@ -149,17 +187,21 @@ For T2I/T2V the sequence layout is:
                                                           ↑ everything else: normal weights
 ```
 
-The MLX port (`qwen2_navit_mlx.py`) routes by slicing the sequence into the latent slab vs the surrounding text, applying the appropriate expert to each slab, and concatenating. mrope position ids continue to flow normally across both slabs (with axis-T/H/W coordinates only varying inside the latent slab).
+The MLX port (`lance_mlx/qwen2_navit_mlx.py`) routes by slicing the sequence into the latent slab vs the surrounding text, applying the appropriate expert to each slab, and concatenating. mrope position ids continue to flow normally across both slabs (with axis-T/H/W coordinates only varying inside the latent slab).
 
 ## Conversion source
 
-Converted from `bytedance-research/Lance/Lance_3B/*` using the open-source pipeline at https://github.com/RockTalk/Lance-MLX (`tools/convert_weights.py`). Layout transforms:
+Converted from `bytedance-research/Lance/Lance_3B/*` using a local conversion pipeline. Layout transforms:
 
 - Conv weights: PT `(O, I, [T,] H, W)` → MLX `(O, [T,] H, W, I)`
 - Embedding weights: shape preserved
 - `lm_head.weight` tied to `embed_tokens.weight` (Qwen default)
 - All `*_moe_gen.*` keys copied verbatim under the same names
 
+## Related ports
+
+A parallel MLX port exists at [mlx-community/Lance-3B-Video-bf16](https://huggingface.co/mlx-community/Lance-3B-Video-bf16) (Apache-2.0). The two checkpoints have been verified numerically equivalent: remapping this repo's F32 weights into their layout and casting to bf16 produces byte-identical pixel output through their pipeline. Use whichever fits your workflow.
+
 ## License
 
 Apache 2.0, inherited from upstream `bytedance-research/Lance`. The Wan 2.2 VAE component is also Apache 2.0 from Alibaba's Wan team.
@@ -170,6 +212,7 @@ Apache 2.0, inherited from upstream `bytedance-research/Lance`. The Wan 2.2 VAE
 - **Qwen team** — Qwen2.5-VL-3B-Instruct backbone
 - **Alibaba Wan team** — Wan 2.2 VAE training
 - **Apple `mlx` and `mlx-vlm` teams** — the underlying frameworks
+- **mlx-community Lance porters** — parallel bf16 port, numerically cross-checked against this one
 - **This MLX port** — RockTalk
 
 ## Citation