Rewrite model card in plain language

README.md

@@ -17,11 +17,11 @@ tags:
 
 # Sol Milkshake
 
-Sol Milkshake is a recurrent language model that runs with MLX on Apple Silicon. It has 2,990,000 parameters, and the released checkpoint received 2,526,565,888 token exposures across pretraining and recovery training.
+Milkshake tests recurrence and hyperspherical optimization in MLX on Apple Silicon. Five stored transformer blocks produce eleven block applications. Local token-pattern memory and rolling chunk memory accompany the shared blocks.
 
-The experiment combines hyperspherical optimization with shared transformer blocks. It also has two kinds of memory: local token-pattern memory and rolling memory across chunks. Milkshake completes text; it hasn't been instruction-tuned.
+The model has 2,990,000 parameters. Its released checkpoint received 2,526,565,888 token exposures across pretraining and recovery. It generates text completions and hasn't been instruction-tuned.
 
-## What's in the model
+## Configuration
 
 | Setting | Value |
 |---|---|
@@ -42,15 +42,15 @@ The experiment combines hyperspherical optimization with shared transformer bloc
 | Token embeddings | Tied to the output head |
 | Weights | MLX NPZ |
 
-## Try it on Apple Silicon
+## Run with MLX
 
-Install MLX and the tokenizer library, along with the Hub client:
+Install MLX, the tokenizer library, and the Hugging Face Hub client:
 
 ```bash
 pip install "mlx>=0.29" "tokenizers>=0.22" huggingface_hub
 ```
 
-Download the repository, then import the model code and loader included here:
+The downloaded repository contains the model implementation, loader, and generation function:
 
 ```python
 from huggingface_hub import snapshot_download
@@ -73,7 +73,7 @@ text = generate(
 print(text)
 ```
 
-## Results and checkpoint selection
+## Evaluation and selection
 
 | Benchmark | Examples | Normalized accuracy |
 |---|---:|---:|
@@ -83,20 +83,20 @@ print(text)
 | PIQA | 1,838 | 52.50% |
 | ArithMark-3 | 1,000 | 30.60% |
 
-The reported Intelligence Index is 3.158. The four language-model tasks use the full zero-shot splits with `lm-eval` 0.4.12. ArithMark-3 uses independent tokenization and normalized accuracy. The raw outputs are in `evals/`.
+Milkshake's local Intelligence Index score is 3.158. The four language-model tasks used their complete zero-shot splits and `lm-eval` 0.4.12. ArithMark-3 used independent tokenization and normalized accuracy. See `evals/` for the raw outputs.
 
-Recovery runs used this same suite to choose the checkpoint. That means the scores include the effect of checkpoint selection; they aren't an untouched held-out estimate. No independent evaluation has verified them.
+We used this same benchmark suite to select the recovery checkpoint, so selection affects the reported scores. They aren't an untouched held-out estimate, and no independent evaluation has verified them.
 
-## Training
+## Pretraining and recovery
 
-Pretraining used FineWeb-Edu and FinePDFs-Edu, English UltraFineWeb multi-domain and question-answer subsets, Cosmopedia, and FineMath. Recovery mixed 70% of the original frozen curriculum with 15% Cosmopedia-v2 English and 15% FinePhrase.
+Pretraining drew on FineWeb-Edu, FinePDFs-Edu, English UltraFineWeb multi-domain and question-answer subsets, Cosmopedia, and FineMath. For recovery, the mixture was 70% original frozen curriculum, 15% Cosmopedia-v2 English, and 15% FinePhrase.
 
-The tokenizer and prepared streams stayed fixed during recovery, as did the existing filtering, deduplication, and decontamination rules. `training_state.json` records the run details.
+Recovery kept the tokenizer and prepared streams fixed. Filtering, deduplication, and decontamination rules also stayed the same. The run record is `training_state.json`.
 
-## Files and limits
+## Repository contents
 
-`model.npz` contains the MLX weights. The loader and generator are in `modeling_sol_milkshake.py`; `sol_config.py` holds the architecture settings. You'll also find `config.json`, tokenizer files, training metadata, and evaluation outputs here.
+Load the MLX weights from `model.npz` with `modeling_sol_milkshake.py`. That file also provides generation; `sol_config.py` defines the architecture. The download includes `config.json`, tokenizer files, training metadata, and evaluation outputs.
 
-Milkshake is a small research model for studying recurrence, memory, and hyperspherical optimization, as well as MLX inference. It can produce repetitive or incoherent text and get answers wrong.
+Milkshake is intended for research on recurrence, memory, hyperspherical optimization, and MLX inference. Completions can be repetitive, incoherent, or incorrect.
 
-The model uses [CC BY 4.0](LICENSE). The training datasets keep their own licenses.
+The model license is [CC BY 4.0](LICENSE). Dataset licenses apply separately.