docs: publish clean model card (validation + control telemetry)

README.md

@@ -20,27 +20,40 @@ inference: false
 
 # Shannon Control Unit (SCU) — Cruise Control for LLM Training
 
-[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Patent Pending](https://img.shields.io/badge/Patent-Pending-orange.svg)](https://shannonlabs.dev)
 [![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97-Models-yellow)](https://huggingface.co/hunterbown/shannon-control-unit)
-[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/hmbown/shannon-control-unit/blob/main/notebooks/SCU_Demo.ipynb)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Hmbown/shannon-control-unit/blob/main/notebooks/SCU_Demo.ipynb)
 [![Website](https://img.shields.io/badge/Website-shannonlabs.dev-green)](https://shannonlabs.dev)
 
+**Model Weights:** Llama 3.2 Community License | **Code:** Apache-2.0 ([GitHub](https://github.com/Hmbown/shannon-control-unit))
+
 **Like cruise control maintains your speed regardless of hills, SCU maintains optimal regularization regardless of data complexity.**
 
 Set your target information ratio \( S^* \), and our PI controller automatically adjusts \( \lambda \) to maintain it throughout training. No manual hyperparameter tuning required.
 
 **Validated Results:**
-- **Llama-3.2-1B:** Base 3.920 BPT → SCU 3.676 BPT (15.6% lower perplexity, 6.2% lower BPT)
-- **🎯 Llama-3.2-3B:** Base 1.8295 BPT → SCU 1.6351 BPT (10.6% lower BPT)
-- **Production ready:** Seeking partnerships for 7B+ scale validation
+
+| Model | Metric | Baseline | SCU | Improvement |
+|-------|--------|----------|-----|-------------|
+| **Llama-3.2-1B** | BPT | 3.920 | 3.676 | **-6.2%** |
+| | Perplexity | 15.14 | 12.78 | **-15.6%** |
+| **Llama-3.2-3B** 🎯 | BPT | 1.830 | 1.635 | **-10.6%** |
+| | Perplexity | 3.56 | 3.11 | **-12.6%** |
+
+**Status:** Validated at 1B/3B scales | Seeking partners for 7B+ external validation
+
+[View validation artifacts](./3b_validation_results.json) | [Evaluation protocol](./scripts/eval_bpt.py)
 
 ## Available Models
 
-- **Main directory**: Llama-3.2-1B SCU adapter (validated, S=1.0%)
-- **1b-scu/**: Same as main (Llama-3.2-1B SCU, S=1.0%, λ adaptive)
-- **3b-scu/**: Llama-3.2-3B SCU adapter (S=2.88%, λ=2.61) 
-- **3b-fixed/**: Llama-3.2-3B fixed λ=0.5 (S=3.35%)
+| Directory | Model | S* Target | λ Control | Notes |
+|-----------|-------|-----------|-----------|-------|
+| **main** | Llama-3.2-1B | 1.0% | Adaptive PI | Primary validated model |
+| **1b-scu/** | Llama-3.2-1B | 1.0% | Adaptive PI | Same as main |
+| **3b-scu/** | Llama-3.2-3B | 2.88% | Adaptive (λ=2.61) | Best 3B performance |
+| **3b-fixed/** | Llama-3.2-3B | 3.35% | Fixed λ=0.5 | Ablation study |
+
+**Note:** HuggingFace UI shows only the root 1B model. Load 3B models using `subfolder="3b-scu"` parameter in code.
 
 ![Validation: Base vs SCU](assets/figures/validation_delta.png)
 
@@ -74,7 +87,7 @@ from transformers import AutoModelForCausalLM, AutoTokenizer
 from peft import PeftModel
 import torch
 
-# For 1B model (recommended - validated with 6.2% improvement)
+# For 1B model (validated with 6.2% BPT improvement)
 base_id = "meta-llama/Llama-3.2-1B"  # accept terms on HF first
 base = AutoModelForCausalLM.from_pretrained(base_id, device_map="auto", torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32)
 tok  = AutoTokenizer.from_pretrained(base_id)
@@ -89,28 +102,31 @@ model = PeftModel.from_pretrained(base, "hunterbown/shannon-control-unit")
 # model = PeftModel.from_pretrained(base, "hunterbown/shannon-control-unit", subfolder="3b-scu")
 ```
 
-**Demo notebook:** [Open in Colab](https://huggingface.co/hunterbown/shannon-control-unit/blob/main/notebooks/SCU_Demo.ipynb) (hosted on HuggingFace)
+**Demo notebook:** [Open in Colab](https://colab.research.google.com/github/Hmbown/shannon-control-unit/blob/main/notebooks/SCU_Demo.ipynb)
 
 ---
 
 ## How It Works (Cruise Control Analogy)
 
 Just like cruise control in your car:
-- **You set the target:** Choose your information ratio $S^*$ (typically 1.0%)  
+- **You set the target:** Choose your information ratio $S^*$  
 - **SCU maintains it automatically:** PI controller adjusts $\lambda$ in real-time
 - **No manual intervention:** Works across data distribution shifts and training dynamics
 
 **Technical Details:**
 - **Control variable:** $S=\frac{\text{ParamBPT}}{\text{DataBPT}+\text{ParamBPT}}$
-- **Control law:** $\lambda \leftarrow \lambda \cdot \exp(-(K_p\,\text{error}+K_i\,I))$
+- **Control law:** $\lambda \leftarrow \lambda \cdot \exp(-(K_p \cdot \text{error} + K_i \cdot I))$
 - **Result:** Automatic regularization without hyperparameter sweeps
 
+**Key Research Question:** 
+Optimal $S^*$ scaling laws are still being discovered. We found 1.0% works for 1B models and 2.88% for 3B models. The relationship between model size, training data, and optimal $S^*$ is an active area of research.
+
 ---
 
 ## Licensing & IP
 
-* **Adapters/models:** Meta **Llama 3.2** Community License
-* **SCU training code:** **Apache-2.0**
-* **IP status:** U.S. **patent pending** (provisional filed September 2025)
+* **Model weights:** Meta Llama 3.2 Community License (inherited from base model)
+* **SCU training code:** Apache-2.0 License ([GitHub repository](https://github.com/Hmbown/shannon-control-unit))
+* **IP status:** U.S. patent pending (provisional filed September 2025)
 
 > Repro tips: block size 1024, batch 1, grad-accum 4, gradient checkpointing on, `use_cache=False`.