Clarify BigSmall vs DFloat11 positioning

README.md

@@ -5,66 +5,62 @@ tags:
   - compression
   - lossless
   - gpt2
+  - openai
 ---
 
-# GPT-2 (BigSmall compressed)
+# GPT-2 117M (BigSmall compressed)
 
-**548MB → 414MB (75.5%). Bit-identical. Under 500MB peak RAM with streaming.**
+**0.55 GB -> 0.39 GB (FP32). Full quality -- not quantization. Zero inference overhead.**
 
-This is GPT-2 117M compressed with [BigSmall](https://github.com/wpferrell/Bigsmall) — lossless neural network weight compression. Not quantization. Every weight is bit-identical to the original.
+Losslessly compressed with [BigSmall](https://github.com/wpferrell/Bigsmall). Every weight is bit-identical to the original. Decompresses once at load time then runs at full native speed -- no inference overhead, ever.
 
-## Install
-
-```bash
-pip install bigsmall
-```
+## BigSmall vs DFloat11 -- what is the difference?
 
-## Load and run inference (streaming)
+Both are lossless. The difference is *when* decompression happens:
 
-```python
-from bigsmall import StreamingLoader
-from transformers import GPT2LMHeadModel, GPT2Tokenizer
+| | BigSmall | DFloat11 |
+|--|--|--|
+| Decompresses | Once at load time | Every forward pass on GPU |
+| Inference overhead | **None** | ~2x slower at batch=1 |
+| Hardware | **CPU, Apple Silicon, AMD, any GPU** | CUDA only |
+| Use case | Smaller downloads, faster loads | Less VRAM during inference |
 
-# Streams one layer at a time — under 500MB peak RAM
-loader = StreamingLoader("wpferrell/gpt2-bigsmall")
-model = loader.load_model(GPT2LMHeadModel)
-tokenizer = GPT2Tokenizer.from_pretrained("openai-community/gpt2")
+**Use BigSmall if** you want to download less, load faster, and run at full native speed on any hardware.
+**Use DFloat11 if** you need the model to stay compressed in GPU memory during inference and have a CUDA GPU.
 
-inputs = tokenizer("Hello, I'm a language model", return_tensors="pt")
-outputs = model.generate(**inputs, max_new_tokens=50)
-print(tokenizer.decode(outputs[0]))
-```
 
-## Or decompress to disk first
+## Install
 
-```python
-from bigsmall import from_pretrained
-from transformers import GPT2LMHeadModel
-model = from_pretrained("wpferrell/gpt2-bigsmall", model_class=GPT2LMHeadModel)
-```
+`ash
+pip install bigsmall
+`
 
-## What's inside
+## Load (transparent -- works like any HuggingFace model)
 
-| File | Original | Compressed | Ratio |
-|------|----------|------------|-------|
-| model.safetensors (FP32) | 548 MB | 414 MB | 75.5% |
+`python
+import bigsmall
+bigsmall.install_hook()
 
-Verified lossless: md5 of every weight tensor matches original after decompression.
+from transformers import AutoModelForCausalLM
+model = AutoModelForCausalLM.from_pretrained("wpferrell/gpt2-bigsmall")
+`
 
-## Comparison
+## Or stream layer by layer (peak RAM under 2GB even for 7B models)
 
-| Tool | BF16 Ratio | FP32 Ratio | Inference Overhead | Hardware |
-|------|------------|------------|-------------------|---------|
-| [ZipNN](https://arxiv.org/abs/2411.05239) | 67% | 83% | None | CPU |
-| [DFloat11](https://arxiv.org/abs/2504.11651) | ~70% | BF16 only | ~2x at batch=1 | CUDA only |
-| [ZipServ](https://arxiv.org/abs/2603.17435) | ~70% | BF16 only | 1.22x faster | GDDR GPU |
-| **BigSmall** | **65.6%** | **75.5%** | **None** | **CPU + any GPU** |
+`python
+from bigsmall import StreamingLoader
+from transformers import AutoModelForCausalLM
 
-*Lower ratio = better compression. BigSmall BF16 measured on Mistral 7B.*
+with StreamingLoader("wpferrell/gpt2-bigsmall", device="cuda") as loader:
+    model = loader.load_model(AutoModelForCausalLM)
+`
 
-## About BigSmall
+## Compression stats
 
-BigSmall compresses at the joint entropy floor for neural network weights. It codes sign+exponent jointly and mantissa conditioned on exponent, achieving the information-theoretic minimum. The streaming loader decompresses one transformer layer at a time directly into VRAM.
+| Original | Compressed | Ratio | Format | Lossless |
+|----------|------------|-------|--------|---------|
+| 0.55 GB | 0.39 GB | 70.9% | FP32 | md5 verified every tensor |
 
 - GitHub: [wpferrell/Bigsmall](https://github.com/wpferrell/Bigsmall)
-- PyPI: `pip install bigsmall`
+- PyPI: pip install bigsmall
+- All pre-compressed models: [huggingface.co/wpferrell](https://huggingface.co/wpferrell)