Update README.md

README.md

@@ -35,7 +35,9 @@ HPC-Quantize V2 (`hpc_quantize_v2/` + `gui.py`) has **zero C or `ctypes` depende
 4. **Bit-Identical Multi-Core Execution (`--workers 0`)**:
    Distributes block-independent candidate and analog solves across all CPU cores via zero-copy `fork` shared memory while keeping cross-block Sieve, 36-state Viterbi, and row-aware DC carry strictly sequential — producing **100% bit-for-bit identical** GGUF output regardless of worker count.
 5. **Real-Time Telemetry GUI (`gui.py`) & Direct GGUF-to-GGUF Pipeline (`hpc_quantize_v2/gguf.py`)**:
-   Ingests `F32`, `F16`, `BF16`, `Q8_0`, `Q4_0`, and `Q2_K` source GGUFs plus `llama.cpp` iMatrix files, displays live intra-tensor stage/block progress, dual **Tensor ETA** and block-weighted **Whole-Model ETA**, live `RMSE`/`RMSE/σ`, Sieve temperature, and floor hits, and emits a stock `llama.cpp` `Q2_K` GGUF.
+   Ingests `F32`, `F16`, `BF16`, `Q8_0`, `Q4_0`, and `Q2_K` source GGUFs plus `llama.cpp` iMatrix files, supports mixed `Q2_K` + full-HPC `Q4_0` (`hpc_quantize_v2/q4_0.py`) and PyTorch CUDA acceleration (`hpc_quantize_v2/cuda_backend.py`), and emits stock `llama.cpp`-compatible GGUFs.
+6. **SlimShard & CheckFree Universal Single-Shard LLM Recovery (`hpc_quantize_v2/slimshard.py`, `hpc_quantize_v2/slimshard_gui.py`)**:
+   Reconstructs a complete, runnable Hugging Face `.safetensors` model from **a single surviving `.safetensors` shard** (even without `model.safetensors.index.json`) across any Transformer or MoE architecture (Llama, Qwen2/3, Mistral, Mixtral, DeepSeek, Gemma, GPT-NeoX, Phi, VLMs, and Raon), or compresses a multi-shard HF model into a single self-contained SlimShard using HPC-Quantize V2 (`Q2_K`/`Q4_0`) and SlimMoE expert clustering.
 
 ---
 
@@ -183,6 +185,28 @@ Standard Q2_K GGUF Output
 
 ---
 
+### 5. SlimShard & CheckFree Universal Single-Shard LLM Recovery (`slimshard.py` & `slimshard_gui.py`)
+
+`hpc_quantize_v2.slimshard` provides two single-shard workflows for arbitrary Hugging Face `.safetensors` models (Llama, Qwen2/3, Mistral, Mixtral, DeepSeek, Gemma, GPT-NeoX, Phi, VLMs with `text_config`, and Raon):
+
+1. **CheckFree Single-Shard Recovery (`recover`)**:
+   Reconstructs a full, loadable Hugging Face model when **only one `.safetensors` shard** is available (with zero access to the remaining shards):
+   - **Exact Surviving Tensor Copy**: Every tensor present in the surviving shard is copied verbatim.
+   - **CheckFree Variance-Preserving Layer Interpolation**: Missing Transformer layers $\ell$ between surviving depth anchors $\ell_a < \ell < \ell_b$ (or extrapolated past $\ell_{\max}$ with smooth depth progression) are reconstructed via row-RMS/variance-preserving interpolation:
+     $$
+     \tilde{W}^{(\ell)} = \left((1 - \alpha) W^{(\ell_a)} + \alpha W^{(\ell_b)}\right) \cdot \frac{(1 - \alpha)\|W^{(\ell_a)}\|_{\text{rms}} + \alpha \|W^{(\ell_b)}\|_{\text{rms}}}{\|(1 - \alpha) W^{(\ell_a)} + \alpha W^{(\ell_b)}\|_{\text{rms}}},
+     \qquad \alpha = \frac{\ell - \ell_a}{\ell_b - \ell_a},
+     $$
+     separately tracking hybrid attention families (e.g. **RDA** vs. **Gated MLA** and **Raon-mHC** 4-stream parameters).
+   - **Per-Expert MXFP8 / FP16 Depth Interpolation**: Preserves exact routed expert identity $e \in \{0,\ldots,E-1\}$ across all MoE layers (`moe.experts`, `mlp.experts`, `block_sparse_moe.experts`, `feed_forward.experts`). For pre-quantized MXFP8 (`F8_E4M3` + `UE8M0` `weight_scale_inv`) experts, bracketing anchor experts are dequantized to FP32, CheckFree-interpolated with row-RMS preservation, and re-quantized in lockstep to production block-32 MXFP8.
+   - **Causal Forward-Calibrated `embed_tokens` & `lm_head` Synthesis**: When `embed_tokens` and `lm_head` reside in a missing shard, `slimshard` extracts the principal right-singular input subspace $B_{\text{in}}$ from Layer 0, regularizes it via `subblock_isomoment_analog`, runs an exact multi-layer causal forward pass over the reconstructed layer stack (supporting both 4-stream `RaonMHC` + `RDA`/`MLA` and standard 1-stream GQA/SwiGLU Transformers), projects background vocabulary rows strictly orthogonal to the network's fixed-point drift $\mu_{\text{out}}$, zeroes `<|reserved_*|>`/control tokens, and solves the regularized dual transition system in chunked 16K-row BF16 streams.
+   - **Index-Free Inference (`infer_weight_map_from_shard`)**: Even if `model.safetensors.index.json` is missing, `slimshard` automatically infers the full model's tensor map from the surviving shard and `config.json`.
+
+2. **Self-Contained SlimShard Compression (`build` & `regenerate`)**:
+   Compresses a multi-shard HF model into a single self-contained `.safetensors` file combining HPC-Quantize V2 (`Q2_K` / `Q4_0` / `exact`) with **SlimMoE** expert centroid + quantized residual clustering (`--expert-keep-ratio`), from which `regenerate` reconstructs the full HF checkpoint.
+
+---
+
 ## Measured Benchmarks
 
 Evaluated across 48 synthetic blocks (4 distributions) and a full row (47 superblocks = 12,032 weights) of `blk.0.ffn_down.weight` from `Raon.gguf` weighted by `imatrix.gguf`:
@@ -324,6 +348,8 @@ HPC-Quantize/
     ├── pipeline.py                # End-to-end Q2KQuantizer with multi-core Phase 2b & algebraic Phase 4
     ├── gguf.py                    # GGUF reader, iMatrix loader & GGUF-to-GGUF streaming writer
     ├── reference.py               # Faithful C-reference solver port for A/B benchmarking
+    └── tests/
+        └── test_v2.py             # 20 unit tests covering primitives, analogs, solver, GGUF & parallelism
 ```
 
 ## Running the Test Suite
@@ -331,3 +357,9 @@ HPC-Quantize/
 ```bash
 python3 -m unittest discover -s hpc_quantize_v2/tests -v
 ```
+
+---
+
+## License
+
+Released under the **MIT License**. Always verify the license of the underlying base model before redistributing quantized GGUF weights.