docs: add architecture, RTX 3090 perf, dflash/PFlash usage, blog links

README.md

@@ -7,11 +7,14 @@ tags:
 - moe
 - code
 - quantized
+- laguna
+- pflash
+- dflash
 ---
 
 # Laguna-XS.2 GGUF (BF16 + Q4_K_M)
 
-GGUF conversions of [poolside/Laguna-XS.2](https://huggingface.co/poolside/Laguna-XS.2) for use with [lucebox-hub](https://github.com/Luce-Org/lucebox-hub).
+GGUF conversions of [poolside/Laguna-XS.2](https://huggingface.co/poolside/Laguna-XS.2), a 33B-A3B (3B active) MoE coding model from Poolside under Apache 2.0. Built for use with [lucebox-hub](https://github.com/Luce-Org/lucebox-hub) (dflash + PFlash) on consumer GPUs.
 
 ## Files
 
@@ -21,6 +24,15 @@ GGUF conversions of [poolside/Laguna-XS.2](https://huggingface.co/poolside/Lagun
 | `laguna-xs2-Q4_K_M.gguf` | Q4_K_M | 20.3 GB | 4.85 | imatrix-calibrated, fits a single 24 GB GPU |
 | `laguna-xs2.imatrix` | imatrix | 188 MB | — | Bartowski calibration_datav3 (134 chunks, 68608 tokens) |
 
+## Architecture
+
+- 40 layers, n_embd 2048, n_head_kv 8, head_dim 128
+- Per-layer head count [48, 64, 64, 64] × 10 (4-layer SWA pattern: full, sw, sw, sw)
+- 256 experts, top-8 routing, 1 always-on shared expert
+- Sigmoid router, expert weights scale 2.5
+- Sliding window 512, partial RoPE with YaRN (orig ctx 4096, factor 32)
+- Vocab 100,352, BOS=2, EOS=2, PAD=9
+
 ## Quality
 
 | Metric | BF16 | Q4_K_M | Δ |
@@ -31,4 +43,58 @@ Imatrix calibration uses Bartowski `calibration_datav3.txt` (multilingual + code
 
 Verified vs the official Poolside HF reference (BF16, eager attention, greedy decoding): logits match exactly for the first 30+ tokens on a B-tree explanation prompt; subsequent divergence is fp precision drift, not a graph bug.
 
-Tested on RTX 3090 24GB and A100 80GB. Inference ~155 tok/s on A100 SXM Q4_K_M.
+## Performance (RTX 3090 24 GB, Q4_K_M)
+
+Measured with `bench_laguna_generate` from lucebox-hub (dflash autoregressive forward, no spec-decode draft yet):
+
+| Workload | Throughput | Notes |
+|----------|-----------|-------|
+| Decode @ ctx=128 (greedy) | **113 tok/s** | n_gen=128 |
+| Decode @ ctx=1K | 104 tok/s | |
+| Decode @ ctx=4K | 60 tok/s | |
+| llama.cpp tg128 (Q8_0 KV, FA on) | 165 tok/s | for comparison |
+| 128K TTFT via dflash + PFlash | **15.91 s** | 5.4× faster than llama.cpp pp131072 (86.60 s) |
+| Loader VRAM | 18.77 GiB | + 110 MiB tok_embd kept on CPU |
+
+A100 SXM Q4_K_M: ~155 tok/s decode (single user, short ctx).
+
+## Usage
+
+### lucebox-hub (dflash + PFlash, recommended for 128K)
+
+```bash
+git clone https://github.com/Luce-Org/lucebox-hub
+cd lucebox-hub/dflash
+cmake -B build -DCMAKE_CUDA_ARCHITECTURES=86  # 86 for 3090, 89 for 4090, 120 for 5090
+cmake --build build -j
+
+hf download Lucebox/Laguna-XS.2-GGUF laguna-xs2-Q4_K_M.gguf --local-dir models/
+hf download poolside/Laguna-XS.2 chat_template.jinja tokenizer.json tokenizer_config.json special_tokens_map.json config.json --local-dir models/Laguna-XS-2
+
+python3 scripts/server.py \
+    --target models/laguna-xs2-Q4_K_M.gguf \
+    --tokenizer models/Laguna-XS-2 \
+    --port 8000 --max-ctx 131072
+
+curl http://localhost:8000/v1/chat/completions \
+    -H 'Content-Type: application/json' \
+    -d '{"model":"luce-dflash","messages":[{"role":"user","content":"hello"}],"stream":true}'
+```
+
+### llama.cpp
+
+Requires llama.cpp with `laguna` arch support. The lucebox-hub fork at `dflash/deps/llama.cpp` adds it; upstream PR pending.
+
+```bash
+./llama-bench -m laguna-xs2-Q4_K_M.gguf -p 0 -n 128 -ctk q8_0 -ctv q8_0 -fa 1 -ngl 99
+```
+
+## License
+
+Apache 2.0, inherited from upstream `poolside/Laguna-XS.2`.
+
+## See also
+
+- [PFlash 128K speedup blog post](https://lucebox.com/blog/pflash)
+- [DFlash on ggml blog post](https://lucebox.com/blog/dflash27b)
+- [lucebox-hub on GitHub](https://github.com/Luce-Org/lucebox-hub)