Update README.md

README.md

@@ -37,7 +37,7 @@ model-index:
     metrics:
     - type: accuracy
       name: avg@16
-      value: 0.390
+      value: 0.417
   - task:
       type: text-generation
       name: Code Generation
@@ -64,7 +64,7 @@ model-index:
       type: livecodebench_v6
     metrics:
     - type: pass@1
-      value: 0.357
+      value: 0.3741
   - task:
       type: text-generation
       name: General Knowledge / Reasoning
@@ -160,7 +160,18 @@ K2-Horizon-0.9B is the compact dense member of the K2-Horizon family: a 0.9B-cla
 | BFCL v4 | **28.0** | 25.3 | 25.15 | 43.6 |
 
 
-## Model Details
+## Model Series Overview
+
+K2-Horizon spans compact and larger dense models for transparent foundation-model research, staged checkpoint analysis, and practical deployment. The repositories share a common release structure while preserving model-specific training and serving guidance.
+
+| Model | Architecture | Parameters | Context length | Intended use |
+| --- | --- | ---: | ---: | --- |
+| **K2-Horizon-0.9B** | Dense decoder-only | 1.08B including embeddings | 131,072 | Compact reasoning, local inference, and distillation research |
+| K2-Horizon-3.7B | Dense decoder-only | 3.78B core | 524,288 | Efficient research, evaluation, and single-node serving |
+| K2-Horizon-7B | Dense decoder-only | 7B core | 524,288 | General research, fine-tuning, and cost-conscious deployment |
+| K2-Horizon-32B | Dense decoder-only | 32B core | 524,288 | Stronger long-context and reasoning experiments |
+
+## This Repository
 
 | Property | Value |
 |---|---|
@@ -179,7 +190,16 @@ The `main` revision publishes `K2HorizonForCausalLM`,
 `modeling_k2_horizon.py` modules. The Transformers and vLLM preflights below
 validate that public contract before loading weights.
 
-### Training Lineage
+<!-- ## Checkpoint Revisions
+
+| Revision | Stage | Max context |
+| --- | --- | ---: |
+| `main` | Distilled release checkpoint, step 249 | 128K |
+| `mid2_47k` | Second context-extension stage | 128K |
+| `mid1_75k` | First context-extension stage | 40K |
+| Base model | Pre-distillation specialist merge | 8K |
+ -->
+## Training Provenance
 
 Training examples were routed to a math-and-code teacher, a STEM teacher, or
 an instruction-following teacher through the example's `opd_domain` metadata.
@@ -197,7 +217,7 @@ to 131,072 tokens. The `mid1_75k` and `mid2_47k` repository revisions preserve
 the corresponding intermediate checkpoints. The distilled release checkpoint
 is on `main`; all stages use a vocabulary of 64,256 tokens.
 
-## Model Description
+## Training Loss
 
 K2-Horizon-0.9B begins with a task-arithmetic merge of three specialist
 checkpoints. mOPD then trains that merged student against math-and-code, STEM,
@@ -212,8 +232,7 @@ submetric over the pre-distillation merge. This makes the model useful for
 research on compact reasoning models, local inference, distillation, and
 task-specific adaptation.
 
-
-## How to Use
+## Deployment Guide
 
 K2-Horizon-0.9B emits a reasoning segment before its final answer when the
 chat template is used. The template supports `reasoning_effort` values `high`,
@@ -227,7 +246,7 @@ IFBench used `temperature=0.8`. Long math and coding tasks may require several
 thousand output tokens; choose limits from application measurements rather
 than treating an evaluation limit as a universal default.
 
-### Option A - vLLM (recommended, native architecture support)
+### vLLM
 
 The validated serving image was reconstructed into the following manual
 runtime contract:
@@ -349,7 +368,7 @@ print(message.content)
 
 </details>
 
-### Option B - SGLang (native architecture support)
+### SGLang
 
 Native K2 Horizon support is provided by
 [sgl-project/sglang#37654](https://github.com/sgl-project/sglang/pull/37654).
@@ -387,7 +406,7 @@ This uses SGLang's native `K2HorizonForCausalLM` implementation; no
 8,192-token limit is a conservative starting point; increase it only after
 measuring KV-cache capacity.
 
-### Option C - plain Transformers (no vLLM, no container)
+### Transformers
 
 The checkpoint can also be loaded directly from the Hugging Face repository.
 Its `configuration_k2_horizon.py` and `modeling_k2_horizon.py` files are loaded
@@ -465,7 +484,7 @@ print(tokenizer.decode(new_tokens, skip_special_tokens=True))
 
 </details>
 
-## Hardware Requirements
+## Hardware Planning
 
 The BF16 weights occupy approximately 2.0 GiB. One CUDA GPU is sufficient for
 short-context inference; 8 GiB is a practical minimum for a one-request smoke
@@ -475,7 +494,7 @@ tokens and approximately 7 GiB at 131,072 tokens, before allocator, activation,
 CUDA-graph, and framework overhead. Start with a short context and one sequence,
 then increase context length and concurrency from measured memory headroom.
 
-## Repository Contents
+## Source Code
 
 The model repository stores the checkpoint directly at its root. It includes:
 
@@ -488,7 +507,7 @@ Use `chat_template.jinja` for ordinary chat and OpenAI-compatible serving.
 `chat_template_generation.jinja` and `chat_template_asst_tool_gen.jinja` are
 specialized generation and assistant-tool-generation variants.
 
-## Training and Evaluation Provenance
+## Evaluation
 
 - **Training:** multi-teacher on-policy distillation with OPD loss weight 0.1,
   reference-KL weight 0.01, learning rate `1e-7`, and a 500-step schedule. The
@@ -501,4 +520,36 @@ specialized generation and assistant-tool-generation variants.
   matched. The architecture label was later updated from `XllmForCausalLM` to
   `K2HorizonForCausalLM` without changing the weights.
 
+## Intended Use
+
+K2-Horizon-0.9B is intended for compact reasoning research, local inference, evaluation dry runs, distillation studies, and task-specific adaptation. It is a research release and should be evaluated on representative prompts before deployment.
+
+## Limitations and Safety
+
+- AIME 2025 remains below the math-and-code teacher, and AIME results have high
+  sampling uncertainty because each benchmark contains only 30 problems.
+- GPQA-Diamond is statistically close to the pre-distillation base result, so
+  the reported run does not demonstrate a clear STEM improvement.
+- Long-horizon tool use remains substantially weaker than single-turn tool
+  calling in the BFCL v4 breakdown.
+- Benchmark scores depend on prompt templates, reasoning effort, sampling
+  parameters, framework versions, and evaluation harness details. Validate the
+  model on representative prompts before deployment.
+- As with other language models, K2-Horizon-0.9B can produce inaccurate,
+  biased, or unsafe text. Applications should use task-specific evaluation,
+  input and output controls, monitoring, and human review where appropriate.
+
+## Citation
+
+```bibtex
+@misc{k2horizon2026,
+  title  = {Introducing K2 Horizon: Frontier Performance, Radically Open},
+  author = {{IFM Team}},
+  year   = {2026},
+  url    = {https://ifm.ai/blog/k2/},
+}
+```
+
+## Contact
 
+For questions and feedback, open a discussion in this Hugging Face repository or contact the IFM team through the K2-Horizon project channels.