Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,135 @@
+# Qwen3.8-27B-LabOpen v1
+
+Qwen3.8-27B strengthened for verifiable scientific computation — released both as **merged FP8 full weights** (drop-in for the base) and as the original **LoRA adapter**.
+
+LabOpen v1 adds six verifiable capability domains (fluid physics, materials mixture laws, classical genetics, ops action queries, prose style, agentic coding) on top of [Qwen/Qwen3.8-27B-FP8](https://huggingface.co/Qwen/Qwen3.8-27B-FP8), while preserving the base model's native code generation, function calling, intent understanding and formula rendering. The largest measured gain: **agentic coding 32% → 72% (+40pp)** on a 78-test deterministic battery.
+
+- **Base model**: Qwen3.8-27B (FP8 release, Apache 2.0)
+- **Training**: 15 reinforcement windows (G69–G84), LoRA r=4, group-relative RL (RLOO-style, k=8 sampling) with mechanically verifiable rewards
+- **License**: Apache 2.0 (same as base)
+- **Hardware target**: any FP8-capable GPU (H100 / GB10 / B200 class); ~28 GB in FP8
+
+## What's in this repo
+
+| Path | Content |
+|---|---|
+| `model-0000X-of-00007.safetensors` + index | **Merged FP8 full weights** (base + LoRA, blockwise-FP8 re-quantized). Same tensor layout and quantization format as the base — drop-in replacement |
+| `adapter/` | **LoRA adapter** (112 MB, PEFT format, 992 tensors). Numerically exact training artifact — no re-quantization |
+| `MERGE_REPORT.md` | Merge provenance: digests, shard SHA-256, re-quantization error stats, output-equivalence probes |
+| `EVALUATION.md` | Measured capability matrix and 5-model external comparison |
+| `USAGE.md` | Loading, domain tags, temperature guidance, troubleshooting |
+
+Use the **merged weights** for serving (vLLM/SGLang). Use the **adapter** on top of the base when you want the exact training-time numerics or a smaller download.
+
+## Capability matrix (measured, heldout sets)
+
+| Domain | Metric | Score | vs Base |
+|---|---|---|---|
+| **Agentic coding** | 78 deterministic tests, 3-round fix | **72%** (56/78) | **+40pp** (base: 32%) |
+| **Intent understanding** | 10-scene deep-intent probe | **8/10** | preserved |
+| **Formula display** | LaTeX integrity, 5 problems | **5/5** | preserved |
+| Fluid physics (CFM) | Pool-B heldout, T=0.3 k=8, tagged | 44% draws | new (base ≈ 0) |
+| Materials (mixture laws) | heldout 40 items, T=0.3 | 32% draws | new (base ≈ 0) |
+| Classical genetics | heldout 20 items, tagged | 79% draws | new (base: 47% natural) |
+| Ops (action queries) | 8 items, dual-temp | 4–5/8 | new |
+| Prose style | 20 open-ended, T=0.3 k=8 | 75% any-correct | new |
+
+### External comparison (same battery, 2026-10)
+
+| Model | Intent | Agentic tests | Rank |
+|---|---|---|---|
+| GLM 5.3 | 8/10 | 57/78 (73%) | #1 |
+| **LabOpen v1 (this)** | **8/10** | **56/78 (72%)** | **#2** |
+| Qwen3.8-max | 8/10 | 54/78 (69%) | #3 |
+| DeepSeek v4.1 flash | 6/10 | 48/78 (62%) | #4 |
+| Qwen3.8-27B (base) | 8/10 | 25/78 (32%) | #5 |
+
+A 27B + r4 LoRA reaching frontier-model agentic-coding territory at ~20 training windows is the headline result; see `EVALUATION.md` for gaps that remain (first-pass rate, general knowledge vs 100B+ models).
+
+## Usage
+
+### Serving the merged weights (recommended)
+
+```bash
+vllm serve HoomanBio/Qwen3.8-27B-LabOpen-v1
+# or: docker run ... vllm/vllm-openai --model HoomanBio/Qwen3.8-27B-LabOpen-v1
+```
+
+The merged checkpoint uses the same blockwise FP8 (e4m3, 128×128 scales) format as the base — any runtime that loads `Qwen/Qwen3.8-27B-FP8` loads this without changes.
+
+### Loading the adapter (exact training numerics)
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3.8-27B-FP8", device_map="auto")
+model = PeftModel.from_pretrained(base, "HoomanBio/Qwen3.8-27B-LabOpen-v1", subfolder="adapter")
+tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3.8-27B-FP8")
+```
+
+> **Do not run `merge_and_unload()` on the FP8 base yourself.** The base stores weights as blockwise-FP8 codes with 128×128 scales; a naive PEFT merge adds a BF16 delta directly onto FP8 codes and silently corrupts the weights. Use the merged checkpoint provided here — it was produced by dequantize → add delta → re-quantize with per-block scale recomputation and verified against the adapter (see `MERGE_REPORT.md`).
+
+### Domain tags
+
+The strengthened domains are addressed by a one-line tag at the **start of the prompt**:
+
+| Tag | Domain |
+|---|---|
+| `[domain: cfm-chain]` | fluid physics chains |
+| `[domain: mat-table]` | materials mixture laws |
+| `[domain: bio-genetics]` | classical genetics |
+| `[domain: ops-action]` | ops action queries |
+| `[domain: general-prose]` | open-ended prose style |
+
+Without a tag the model keeps base behavior (code / function calling need no tag).
+
+### Temperature
+
+| Use case | Temperature |
+|---|---|
+| Domain computation (cfm/mat/bio/ops) | **0.3** (greedy degrades on some domains) |
+| Open-ended prose | **0.3** (prose is in the distribution, not always the mode) |
+| Code generation | 0.0–0.2 |
+| General QA | 0.3–0.7 |
+
+## Technical notes
+
+- **Architecture**: Qwen3.8-27B hybrid — 64 decoder layers: 48 linear-attention + 16 full-attention layers.
+- **LoRA**: r=4, α=4 (scaling 1.0), dropout 0, on 496 projection modules across 13 module types (q/k/v/o/gate/up/down_proj, in_proj_a/b/qkv/z, out_proj) = 992 tensors, ~112 MB.
+- **Merge math**: per module `W = codes × scale(blockwise)` dequantized to FP32, LoRA delta `(B·A)·scaling` added, re-quantized per 128×128 block (`scale = amax/448`). Mean re-quantization relative error 0.33% — the same order as the base's own FP8 storage noise. Equivalence probes (greedy, 3 prompts × 48 tokens, adapter vs merged): see `MERGE_REPORT.md`.
+- **Training substrate**: a local FP8 copy of Qwen3.8-27B (community redistribution). Bit-equivalence with `Qwen/Qwen3.8-27B-FP8` was not verified; the adapter config points to the official release for loading.
+
+## Training methodology (summary)
+
+15 reinforcement windows (G69–G84) on a frozen FP8 serving stack with exact weight/update contracts: group-relative advantages with k=8 sampling and mechanically verifiable rewards; oracle injection for zero-mastery domains; verified distillation from champion checkpoints; frozen domain tags; substep advantage for multi-step composition; per-window heldout gates and retention protection. Single seed, single run — no capability claim in this card comes from a set seen during training.
+
+## Honest boundaries
+
+- Single seed, single training run; variance bands not fully characterized
+- Prose style is stable at T=0.3 sampling, unstable at greedy decoding
+- Domain capabilities require their tags; untagged behavior is base behavior
+- 27B parameter count — not comparable to 100B+ models on general knowledge
+- Merged FP8 weights add re-quantization noise vs the adapter path (stats in `MERGE_REPORT.md`); the adapter is the numerically exact artifact
+- All scores are single evaluation runs on heldout sets
+
+## Acknowledgments
+
+- **Alibaba Qwen team** — for Qwen3.8-27B, the open base model this work builds on, and for the open Apache-2.0 release that makes derivative research like this possible.
+- **Z.ai (Zhipu AI)** — GLM 5.3 served as the strongest external benchmark in our evaluation battery and as an engineering assistant during the release workflow.
+- **Moonshot AI** — Kimi K3's public work on long-context and agentic reasoning informed our evaluation design for intent understanding and multi-step tool use.
+
+We thank these teams for pushing open, measurable frontiers — this release aims to contribute back in the same spirit.
+
+## Citation
+
+```bibtex
+@software{labopen_v1,
+  title = {Qwen3.8-27B-LabOpen v1: Six-Domain Reinforcement of Qwen3.8-27B},
+  author = {Hooman AI Lab},
+  year = {2026},
+  url = {https://huggingface.co/HoomanBio/Qwen3.8-27B-LabOpen-v1},
+  base = {Qwen/Qwen3.8-27B-FP8},
+  license = {Apache-2.0}
+}
+```