training code: data generation, SFT, eval, GRPO

code/README.md

@@ -0,0 +1,196 @@
+# Nawah-Math-Reasoning — training code
+
+Everything that produced the model in this repo: two dataset pipelines, the SFT trainer, the eval
+harness, a `pass@k` diagnostic, and a GRPO implementation. Run top to bottom and you get the
+release; run any single stage and it resumes from what is already on disk.
+
+Paths below assume this directory is the working directory and `$P` is a Python with
+`torch`, `transformers>=5.15`, `pyarrow` and `huggingface_hub`.
+
+## 0. Two environments, and why
+
+| env | for | pins |
+|---|---|---|
+| training / eval / Hub | `train_reasoning.py`, `eval_reasoning.py`, everything else | torch 2.9 + cu126, **transformers 5.15** |
+| generation | `translate_gsm.py`, `synth_generate.py` | **vLLM 0.8.5.post1**, torch 2.6 + cu124, **transformers 4.51.3** |
+
+They are not interchangeable. The model configs are transformers-v5 format (`rope_parameters`,
+`dtype`, `tokenizer_class: TokenizersBackend`) and transformers 4.x cannot read them — but vLLM
+0.8.5 breaks on transformers 5.x (`TokenizersBackend has no attribute
+all_special_tokens_extended`), so the generation env must stay at 4.51.3. Do not `pip install -U`
+in it.
+
+vLLM 0.8.5 is itself a pin: every release from 0.20.2 up requires torch 2.11, which is a CUDA 13
+build needing driver ≥ 580. On a CUDA 12.4 host that is a hard stop, and cu12 wheels do not rescue
+it (`ImportError: libcudart.so.13`). 0.8.5 is the last cu124 release.
+
+In transformers v5 `TrainingArguments` it is `eval_strategy` (not `evaluation_strategy`) and
+`warmup_steps` (there is no `warmup_ratio`).
+
+## 1. `gsm8k-reasoning-ar` — 142,969 machine-translated rows
+
+```bash
+$V translate_gsm.py 150000     # vLLM env; ~95 min on 1x A6000; resumable
+$P build_dataset.py            # -> out_gsm/*.parquet + rejects.jsonl
+$P push_dataset.py --repo <user>/gsm8k-reasoning-ar
+```
+
+`Ajhesh7/gsm8k-reasoning-SFT-datas` translated with `ByteDance-Seed/Seed-X-PPO-7B`. The trailing
+language tag in the prompt is **mandatory**: `Translate the following English sentence into
+Arabic:\n{text} <ar>`.
+
+Only 150k of the source's 600,000 rows are translated, and the sample is stratified by question
+pattern with a floor of 13 rows/pattern: the corpus expands from just **2,814** question patterns,
+so translating all 600k is ~99% redundant.
+
+**The reason `build_dataset.py` has a validator at all:** Seed-X silently corrupts arithmetic in
+~0.6% of segments — `$13751` → `13571`, `4 × 44 = 176` → `4 × 46 = 176`. These read as fluent
+Arabic and pass any fluency check. So every row is numeral-audited, asymmetrically: **reasoning
+chains strictly** (every numeral must survive exactly), **questions leniently** (a value ≤ 12 may
+be verbalised — `6 friends` → `أصدقائها الستة` — but any number the English never contained is
+rejected). Naive exact-multiset matching rejects ~6% of *correct* translations; do not "simplify"
+it back to that.
+
+`translate_gsm.py` appends every chunk to `out_gsm/translations.jsonl` and skips cached segments on
+restart, so an interruption costs at most one 20k chunk. Do not pass `enable_prefix_caching=True`
+— it hangs at startup on this vLLM/V1 engine.
+
+## 2. `arabic-math-reasoning-synth` — 120,462 verified rows
+
+```bash
+# general pool: 100,323 rows, ~22 h
+GEN_MODEL=<path>/gemma-3-12b-it BACKEND=vllm OUT_DIR=out_synth TARGET=100000 \
+BATCH=256 MAX_NEW=1200 MAX_LEN=3072 GPU_UTIL=0.90 \
+nohup $V -u synth_generate.py > synth_run.log 2>&1 &
+
+# relational pool: 20,139 rows, ~3.5 h. Disjoint task-id range, on purpose.
+GEN_MODEL=<path>/gemma-3-12b-it BACKEND=vllm OUT_DIR=out_synth_rel POOL=relational \
+START_TASK=1000000 TARGET=20000 BATCH=256 MAX_NEW=1200 MAX_LEN=3072 GPU_UTIL=0.90 SEED=1234 \
+nohup $V -u synth_generate.py > synth_rel.log 2>&1 &
+
+./finish_merge_push.sh          # merge primary cache + any node shards -> out_merged_v6/
+$P split_synth_v6.py            # -> data_synth_v6_sft/{train,eval,eval_rel}.jsonl
+$P push_synth_dataset.py --repo <user>/arabic-math-reasoning-synth
+```
+
+**Resumability is the design, not a feature.** A task is one generation call asking for 4 problems,
+and task *N*'s prompt is a pure function of *N* (`synth_common.build_task`) — nothing about the
+plan is persisted, so a restart redraws identical prompts. Finished tasks are appended to
+`generations.jsonl` and fsynced; a torn final line is dropped with a warning. The stop condition is
+**accepted rows, not tasks**.
+
+**Raw completions are stored, never just the parsed rows.** Every validator change can be re-scored
+over the whole cache with no GPU — which is how the accept rate went 48.4% → 64.9% without
+regenerating anything.
+
+**The arithmetic audit** (`synth_common.validate`) re-evaluates every `a op b = c` in the reasoning
+and one wrong equation rejects the row. Two things it must keep doing, both of which were bugs that
+rejected *correct* rows:
+
+1. **Equation chains.** Models write `75 + 15 × 5 = 75 + 75 = 150`. Reading only to the first `=`
+   compares 150 against 75 and rejects a correct chain. Split the whole chain, require every
+   segment to agree.
+2. **Rounding.** `3200 / 60 = 53.33` is arithmetic as people write it. `_close()` forgives rounding
+   *at the precision the model displayed* (and floor/ceil for integers), so a genuinely wrong
+   number still fails.
+
+Also rejected: `noop_step` (`63 + 0 = 63`, padding to hit a step count), `meta_commentary`, Latin
+residue, missing conclusion marker, and answers that disagree with the last computed value.
+
+**The relational pool is a separate pool** (`RELATIONAL_OPS`), deliberately not appended to
+`OPERATIONS`. Appending would change `rng.choice()` for every task id and silently break
+reproducibility of the first 100,323 rows. `build_task(task_id, seed, pool)` takes
+`pool="default"` or `"relational"`; keep it that way.
+
+Check `unique_templates` in `build_stats.json` rather than assuming the variation grid worked.
+
+## 3. SFT
+
+```bash
+$P prepare_data.py              # Arabic_Reasoning_Dataset -> data/{train,eval}.jsonl
+$P prepare_gsm_sft.py           # -> data_gsm_sft/{train,eval}.jsonl
+$P prepare_v6_sft.py            # three-way mix -> data_v6_sft/{train,eval}.jsonl
+
+BASE_MODEL=<base> OUTPUT_DIR=./Nawah-Math-Reasoning \
+TRAIN_FILE=data_v6_sft/train.jsonl EVAL_FILE=data_v6_sft/eval.jsonl \
+MAX_LENGTH=768 EPOCHS=5 BATCH_SIZE=64 GRAD_ACCUM=1 WARMUP_STEPS=200 EVAL_STEPS=1000 LOAD_BEST=0 \
+$P -u train_reasoning.py 2>&1 | tee train.log      # 21,535 steps, ~85 min on 1x A6000
+```
+
+**`LOAD_BEST=0` is load-bearing.** Eval loss selects the *worse* checkpoint on this ladder, and
+that was measured rather than assumed: on a corpus with no repeated rows, the minimum-loss
+checkpoint scored 30.9% where the final scored 35.6%. It held for four consecutive runs. Ship the
+final checkpoint.
+
+**Answer styles are not normalised.** GSM8K rows end in a bare numeral, the other two corpora in an
+`إذن، …` sentence. Rewriting them into one style deletes what the mix adds, so a `source` tag rides
+on every row and eval scores each half on its own terms.
+
+The eval splits are **pinned across versions** — the same 400 `Arabic_Reasoning` rows and the same
+600 GSM8K rows since the first model, and `split_synth_v6.py` copies the previous synth eval rows
+through verbatim rather than re-shuffling. Re-drawing would have moved 1,955 of 2,000 held-out
+items into train.
+
+## 4. Eval
+
+```bash
+EVAL_FILE=data_v6_sft/eval.jsonl        $P eval_reasoning.py ./Nawah-Math-Reasoning 1800
+EVAL_FILE=data_synth_sft/eval.jsonl     $P eval_reasoning.py ./Nawah-Math-Reasoning 1000
+```
+
+Greedy. Reports well-formedness, **number agreement**, exact match and reasoning length, broken
+down per `source` when the rows carry the tag. `EVAL_FILE` comes from the env — pointing it at the
+wrong split silently scores against the wrong data.
+
+Score on **number agreement**, not exact match: with two answer styles in the mix, exact match
+measures style compliance, not arithmetic.
+
+## 5. RL — run the diagnostic first
+
+```bash
+$P -u passk_diag.py ./Nawah-Math-Reasoning     # 240 problems x k=8 @ T=1.0, ~25 min
+```
+
+RLVR reweights samples the model already produces. A group where every sample is wrong scores
+all-zero, the advantage is zero, and there is no gradient — so exploitable headroom is bounded by
+`pass@k − pass@1`. On the previous version that was **+27.1 points**, with 40.4% of problems never
+solved in 8 tries. Run this before spending a GPU-hour.
+
+That diagnostic is also what produced this release: the dead 40% turned out to be a *data* gap
+(relational comparisons were 1.34% of the corpus), so the fix was §2's relational pool through
+SFT, not RL. **Data first, then RL** — running RL first leaves the dead tail untouched and caps
+the gain.
+
+```bash
+MODEL=./Nawah-Math-Reasoning OUTPUT_DIR=./Nawah-Math-Reasoning-grpo \
+GROUP=8 PROMPTS_PER=8 STEPS=500 LR=1e-6 BETA=0.02 \
+$P -u grpo_train.py 2>&1 | tee grpo.log
+```
+
+`grpo_train.py` is hand-rolled — TRL is not installable against these pins. Group-normalised
+advantage with no value network, binary final-answer reward (not partial credit — the failure being
+fixed is fluent reasoning landing on a wrong number), KL to a frozen reference via Schulman's k3
+estimator, and no importance ratio or PPO clipping because sampling is on-policy with one step per
+batch. Zero-spread groups are skipped **and counted**; the dead-group percentage in the log is the
+number to watch.
+
+## 6. Release
+
+```bash
+$P build_release_code.py                    # stage this directory
+$P push_release.py --dry-run                # render the card only
+$P push_release.py
+```
+
+Every number in the model card is read from an eval JSON on disk. Nothing is typed by hand, so the
+card cannot drift from the measurements.
+
+## Demo
+
+`space/` is the Gradio demo, deployable as-is to a Space. Two things that break it if "cleaned up":
+the streamer must use `skip_special_tokens=False` (`<think>`/`</think>` are real special tokens and
+stripping them destroys the reasoning/answer split), and `render_prompt()` must stay byte-identical
+to the trainer's rendering — a 52M model is very sensitive to format drift.
+
+On ZeroGPU, `import spaces` must come **before** torch, and `model.to("cuda")` at startup must stay
+unguarded: no GPU is attached at startup and the call is replayed inside the forked GPU process.

code/build_dataset.py

@@ -0,0 +1,144 @@
+"""
+Assemble the Arabic dataset from the translation cache and validate it.
+
+Validation per row (a translation is only kept if it passes):
+  * both segments translated and non-empty
+  * the numbers in the Arabic text match the English exactly (order-insensitive multiset)
+  * no degenerate repetition loop from the translator
+  * not left largely untranslated (Latin-script residue)
+
+Writes out_gsm/gsm8k_reasoning_ar.parquet plus a rejects file for inspection/retry.
+"""
+import collections
+import json
+import re
+import sys
+from pathlib import Path
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+sys.path.insert(0, ".")
+from gsm_common import build_record
+
+OUT = Path("out_gsm")
+AR_DIGITS = str.maketrans("٠١٢٣٤٥٦٧٨٩", "0123456789")
+NUM_RE = re.compile(r"\d+(?:\.\d+)?")
+LATIN_RE = re.compile(r"[A-Za-z]")
+ARABIC_RE = re.compile(r"[؀-ۿ]")
+
+
+def numbers(text):
+    return NUM_RE.findall(text.translate(AR_DIGITS).replace(",", ""))
+
+
+def has_repetition_loop(text, n=6, times=3):
+    """Detect the translator getting stuck repeating an n-word window."""
+    words = text.split()
+    if len(words) < n * times:
+        return False
+    counts = collections.Counter(
+        " ".join(words[i : i + n]) for i in range(len(words) - n + 1)
+    )
+    return counts.most_common(1)[0][1] >= times
+
+
+VERBALISABLE_MAX = 12  # Arabic writes small quantities as words ("ضعف" for 2, "الستة" for 6)
+
+
+def check(en, ar, strict=True):
+    """
+    strict=True (reasoning chains): every numeral must survive exactly — the arithmetic depends
+    on it. strict=False (questions): a small number may be verbalised, but a number the source
+    never contained is a translation error (observed: '$13751' -> '13571', '4 × 44' -> '4 × 46'),
+    which silently corrupts the math and is always rejected.
+    """
+    if not ar or not ar.strip():
+        return "empty"
+    en_n, ar_n = collections.Counter(numbers(en)), collections.Counter(numbers(ar))
+    if ar_n - en_n:
+        return "invented_number"
+    missing = en_n - ar_n
+    if missing:
+        if strict:
+            return "number_dropped"
+        if any(float(v) > VERBALISABLE_MAX for v in missing):
+            return "number_dropped"
+    if has_repetition_loop(ar):
+        return "repetition"
+    if not ARABIC_RE.search(ar):
+        return "not_arabic"
+    latin = len(LATIN_RE.findall(ar))
+    if latin > 0.25 * len(ar.replace(" ", "")):
+        return "latin_residue"
+    return None
+
+
+def main():
+    trans = {}
+    with open(OUT / "translations.jsonl", encoding="utf-8") as fh:
+        for line in fh:
+            try:
+                r = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            trans[r["src"]] = r["tgt"]
+    print(f"[*] {len(trans)} cached translations")
+
+    rows = [json.loads(l) for l in open(OUT / "selected_rows.jsonl", encoding="utf-8")]
+    print(f"[*] {len(rows)} selected rows")
+
+    kept, rejects = [], []
+    reasons = collections.Counter()
+    for r in rows:
+        q_ar, t_ar = trans.get(r["question"]), trans.get(r["thinking"])
+        if q_ar is None or t_ar is None:
+            reasons["missing"] += 1
+            rejects.append({**r, "reason": "missing"})
+            continue
+        why = check(r["question"], q_ar, strict=False) or check(r["thinking"], t_ar, strict=True)
+        if why:
+            reasons[why] += 1
+            rejects.append({**r, "question_ar": q_ar, "thinking_ar": t_ar, "reason": why})
+            continue
+        kept.append(
+            {
+                "text": build_record(q_ar, t_ar, r["answer"]),
+                "question": q_ar,
+                "thinking": t_ar,
+                "answer": r["answer"],
+                "question_en": r["question"],
+                "thinking_en": r["thinking"],
+                "source_index": r["idx"],
+            }
+        )
+
+    print(f"[*] kept {len(kept)}/{len(rows)} ({len(kept)/len(rows):.2%})")
+    print(f"[*] rejects: {dict(reasons)}")
+
+    table = pa.table({k: [row[k] for row in kept] for k in kept[0]})
+    pq.write_table(table, OUT / "gsm8k_reasoning_ar.parquet", compression="zstd")
+    print(f"[+] wrote {OUT / 'gsm8k_reasoning_ar.parquet'} ({table.num_rows} rows)")
+
+    with open(OUT / "rejects.jsonl", "w", encoding="utf-8") as fh:
+        for r in rejects:
+            fh.write(json.dumps(r, ensure_ascii=False) + "\n")
+    print(f"[+] wrote {OUT / 'rejects.jsonl'} ({len(rejects)} rows)")
+
+    stats = {
+        "selected": len(rows),
+        "kept": len(kept),
+        "kept_pct": 100 * len(kept) / len(rows),
+        "rejects": dict(reasons),
+        "unique_translations": len(trans),
+    }
+    (OUT / "build_stats.json").write_text(json.dumps(stats, ensure_ascii=False, indent=2), encoding="utf-8")
+    for row in kept[:3]:
+        print("-" * 70)
+        print("EN:", row["question_en"][:120])
+        print("AR:", row["question"][:120])
+        print("AR think:", row["thinking"][:160])
+
+
+if __name__ == "__main__":
+    main()

code/build_release_code.py

@@ -0,0 +1,274 @@
+"""
+Stage the training code that ships inside the released model repo, under `code/`.
+
+Copies a curated subset of the working directory — the scripts that actually produce the released
+model, not the whole scratch dir — into `release_code/`, and writes the recipe README beside them.
+`push_release.py` uploads the result to `code/` in the model repo.
+
+The list below is deliberate. Excluded: dead ends (`latex_segment.py`, `pilot_*.py`), the
+per-version push scripts for models that stay private, and the logs. Included: everything a reader
+needs to rebuild both datasets and rerun the training and eval end to end.
+"""
+import shutil
+from pathlib import Path
+
+OUT = Path("release_code")
+
+FILES = {
+    # ── data: translation pipeline (gsm8k-reasoning-ar) ───────────────────────
+    "gsm_common.py":            "data",
+    "translate_gsm.py":         "data",
+    "build_dataset.py":         "data",
+    "retry_failed.py":          "data",
+    "push_dataset.py":          "data",
+    # ── data: synthetic pipeline (arabic-math-reasoning-synth) ────────────────
+    "synth_common.py":          "data",
+    "synth_generate.py":        "data",
+    "build_synth_dataset.py":   "data",
+    "split_synth_v6.py":        "data",
+    "finish_merge_push.sh":     "data",
+    "push_synth_dataset.py":    "data",
+    # ── SFT splits ────────────────────────────────────────────────────────────
+    "prepare_data.py":          "data",
+    "prepare_gsm_sft.py":       "data",
+    "prepare_v6_sft.py":        "data",
+    # ── train / eval / RL ─────────────────────────────────────────────────────
+    "train_reasoning.py":       "train",
+    "eval_reasoning.py":        "train",
+    "passk_diag.py":            "train",
+    "grpo_train.py":            "train",
+    "chat.py":                  "train",
+    # ── release ───────────────────────────────────────────────────────────────
+    "push_release.py":          "release",
+    "build_release_code.py":    "release",
+}
+
+SPACE_FILES = ["app.py", "requirements.txt", "README.md"]
+
+README = """# Nawah-Math-Reasoning — training code
+
+Everything that produced the model in this repo: two dataset pipelines, the SFT trainer, the eval
+harness, a `pass@k` diagnostic, and a GRPO implementation. Run top to bottom and you get the
+release; run any single stage and it resumes from what is already on disk.
+
+Paths below assume this directory is the working directory and `$P` is a Python with
+`torch`, `transformers>=5.15`, `pyarrow` and `huggingface_hub`.
+
+## 0. Two environments, and why
+
+| env | for | pins |
+|---|---|---|
+| training / eval / Hub | `train_reasoning.py`, `eval_reasoning.py`, everything else | torch 2.9 + cu126, **transformers 5.15** |
+| generation | `translate_gsm.py`, `synth_generate.py` | **vLLM 0.8.5.post1**, torch 2.6 + cu124, **transformers 4.51.3** |
+
+They are not interchangeable. The model configs are transformers-v5 format (`rope_parameters`,
+`dtype`, `tokenizer_class: TokenizersBackend`) and transformers 4.x cannot read them — but vLLM
+0.8.5 breaks on transformers 5.x (`TokenizersBackend has no attribute
+all_special_tokens_extended`), so the generation env must stay at 4.51.3. Do not `pip install -U`
+in it.
+
+vLLM 0.8.5 is itself a pin: every release from 0.20.2 up requires torch 2.11, which is a CUDA 13
+build needing driver ≥ 580. On a CUDA 12.4 host that is a hard stop, and cu12 wheels do not rescue
+it (`ImportError: libcudart.so.13`). 0.8.5 is the last cu124 release.
+
+In transformers v5 `TrainingArguments` it is `eval_strategy` (not `evaluation_strategy`) and
+`warmup_steps` (there is no `warmup_ratio`).
+
+## 1. `gsm8k-reasoning-ar` — 142,969 machine-translated rows
+
+```bash
+$V translate_gsm.py 150000     # vLLM env; ~95 min on 1x A6000; resumable
+$P build_dataset.py            # -> out_gsm/*.parquet + rejects.jsonl
+$P push_dataset.py --repo <user>/gsm8k-reasoning-ar
+```
+
+`Ajhesh7/gsm8k-reasoning-SFT-datas` translated with `ByteDance-Seed/Seed-X-PPO-7B`. The trailing
+language tag in the prompt is **mandatory**: `Translate the following English sentence into
+Arabic:\\n{text} <ar>`.
+
+Only 150k of the source's 600,000 rows are translated, and the sample is stratified by question
+pattern with a floor of 13 rows/pattern: the corpus expands from just **2,814** question patterns,
+so translating all 600k is ~99% redundant.
+
+**The reason `build_dataset.py` has a validator at all:** Seed-X silently corrupts arithmetic in
+~0.6% of segments — `$13751` → `13571`, `4 × 44 = 176` → `4 × 46 = 176`. These read as fluent
+Arabic and pass any fluency check. So every row is numeral-audited, asymmetrically: **reasoning
+chains strictly** (every numeral must survive exactly), **questions leniently** (a value ≤ 12 may
+be verbalised — `6 friends` → `أصدقائها الستة` — but any number the English never contained is
+rejected). Naive exact-multiset matching rejects ~6% of *correct* translations; do not "simplify"
+it back to that.
+
+`translate_gsm.py` appends every chunk to `out_gsm/translations.jsonl` and skips cached segments on
+restart, so an interruption costs at most one 20k chunk. Do not pass `enable_prefix_caching=True`
+— it hangs at startup on this vLLM/V1 engine.
+
+## 2. `arabic-math-reasoning-synth` — 120,462 verified rows
+
+```bash
+# general pool: 100,323 rows, ~22 h
+GEN_MODEL=<path>/gemma-3-12b-it BACKEND=vllm OUT_DIR=out_synth TARGET=100000 \\
+BATCH=256 MAX_NEW=1200 MAX_LEN=3072 GPU_UTIL=0.90 \\
+nohup $V -u synth_generate.py > synth_run.log 2>&1 &
+
+# relational pool: 20,139 rows, ~3.5 h. Disjoint task-id range, on purpose.
+GEN_MODEL=<path>/gemma-3-12b-it BACKEND=vllm OUT_DIR=out_synth_rel POOL=relational \\
+START_TASK=1000000 TARGET=20000 BATCH=256 MAX_NEW=1200 MAX_LEN=3072 GPU_UTIL=0.90 SEED=1234 \\
+nohup $V -u synth_generate.py > synth_rel.log 2>&1 &
+
+./finish_merge_push.sh          # merge primary cache + any node shards -> out_merged_v6/
+$P split_synth_v6.py            # -> data_synth_v6_sft/{train,eval,eval_rel}.jsonl
+$P push_synth_dataset.py --repo <user>/arabic-math-reasoning-synth
+```
+
+**Resumability is the design, not a feature.** A task is one generation call asking for 4 problems,
+and task *N*'s prompt is a pure function of *N* (`synth_common.build_task`) — nothing about the
+plan is persisted, so a restart redraws identical prompts. Finished tasks are appended to
+`generations.jsonl` and fsynced; a torn final line is dropped with a warning. The stop condition is
+**accepted rows, not tasks**.
+
+**Raw completions are stored, never just the parsed rows.** Every validator change can be re-scored
+over the whole cache with no GPU — which is how the accept rate went 48.4% → 64.9% without
+regenerating anything.
+
+**The arithmetic audit** (`synth_common.validate`) re-evaluates every `a op b = c` in the reasoning
+and one wrong equation rejects the row. Two things it must keep doing, both of which were bugs that
+rejected *correct* rows:
+
+1. **Equation chains.** Models write `75 + 15 × 5 = 75 + 75 = 150`. Reading only to the first `=`
+   compares 150 against 75 and rejects a correct chain. Split the whole chain, require every
+   segment to agree.
+2. **Rounding.** `3200 / 60 = 53.33` is arithmetic as people write it. `_close()` forgives rounding
+   *at the precision the model displayed* (and floor/ceil for integers), so a genuinely wrong
+   number still fails.
+
+Also rejected: `noop_step` (`63 + 0 = 63`, padding to hit a step count), `meta_commentary`, Latin
+residue, missing conclusion marker, and answers that disagree with the last computed value.
+
+**The relational pool is a separate pool** (`RELATIONAL_OPS`), deliberately not appended to
+`OPERATIONS`. Appending would change `rng.choice()` for every task id and silently break
+reproducibility of the first 100,323 rows. `build_task(task_id, seed, pool)` takes
+`pool="default"` or `"relational"`; keep it that way.
+
+Check `unique_templates` in `build_stats.json` rather than assuming the variation grid worked.
+
+## 3. SFT
+
+```bash
+$P prepare_data.py              # Arabic_Reasoning_Dataset -> data/{train,eval}.jsonl
+$P prepare_gsm_sft.py           # -> data_gsm_sft/{train,eval}.jsonl
+$P prepare_v6_sft.py            # three-way mix -> data_v6_sft/{train,eval}.jsonl
+
+BASE_MODEL=<base> OUTPUT_DIR=./Nawah-Math-Reasoning \\
+TRAIN_FILE=data_v6_sft/train.jsonl EVAL_FILE=data_v6_sft/eval.jsonl \\
+MAX_LENGTH=768 EPOCHS=5 BATCH_SIZE=64 GRAD_ACCUM=1 WARMUP_STEPS=200 EVAL_STEPS=1000 LOAD_BEST=0 \\
+$P -u train_reasoning.py 2>&1 | tee train.log      # 21,535 steps, ~85 min on 1x A6000
+```
+
+**`LOAD_BEST=0` is load-bearing.** Eval loss selects the *worse* checkpoint on this ladder, and
+that was measured rather than assumed: on a corpus with no repeated rows, the minimum-loss
+checkpoint scored 30.9% where the final scored 35.6%. It held for four consecutive runs. Ship the
+final checkpoint.
+
+**Answer styles are not normalised.** GSM8K rows end in a bare numeral, the other two corpora in an
+`إذن، …` sentence. Rewriting them into one style deletes what the mix adds, so a `source` tag rides
+on every row and eval scores each half on its own terms.
+
+The eval splits are **pinned across versions** — the same 400 `Arabic_Reasoning` rows and the same
+600 GSM8K rows since the first model, and `split_synth_v6.py` copies the previous synth eval rows
+through verbatim rather than re-shuffling. Re-drawing would have moved 1,955 of 2,000 held-out
+items into train.
+
+## 4. Eval
+
+```bash
+EVAL_FILE=data_v6_sft/eval.jsonl        $P eval_reasoning.py ./Nawah-Math-Reasoning 1800
+EVAL_FILE=data_synth_sft/eval.jsonl     $P eval_reasoning.py ./Nawah-Math-Reasoning 1000
+```
+
+Greedy. Reports well-formedness, **number agreement**, exact match and reasoning length, broken
+down per `source` when the rows carry the tag. `EVAL_FILE` comes from the env — pointing it at the
+wrong split silently scores against the wrong data.
+
+Score on **number agreement**, not exact match: with two answer styles in the mix, exact match
+measures style compliance, not arithmetic.
+
+## 5. RL — run the diagnostic first
+
+```bash
+$P -u passk_diag.py ./Nawah-Math-Reasoning     # 240 problems x k=8 @ T=1.0, ~25 min
+```
+
+RLVR reweights samples the model already produces. A group where every sample is wrong scores
+all-zero, the advantage is zero, and there is no gradient — so exploitable headroom is bounded by
+`pass@k − pass@1`. On the previous version that was **+27.1 points**, with 40.4% of problems never
+solved in 8 tries. Run this before spending a GPU-hour.
+
+That diagnostic is also what produced this release: the dead 40% turned out to be a *data* gap
+(relational comparisons were 1.34% of the corpus), so the fix was §2's relational pool through
+SFT, not RL. **Data first, then RL** — running RL first leaves the dead tail untouched and caps
+the gain.
+
+```bash
+MODEL=./Nawah-Math-Reasoning OUTPUT_DIR=./Nawah-Math-Reasoning-grpo \\
+GROUP=8 PROMPTS_PER=8 STEPS=500 LR=1e-6 BETA=0.02 \\
+$P -u grpo_train.py 2>&1 | tee grpo.log
+```
+
+`grpo_train.py` is hand-rolled — TRL is not installable against these pins. Group-normalised
+advantage with no value network, binary final-answer reward (not partial credit — the failure being
+fixed is fluent reasoning landing on a wrong number), KL to a frozen reference via Schulman's k3
+estimator, and no importance ratio or PPO clipping because sampling is on-policy with one step per
+batch. Zero-spread groups are skipped **and counted**; the dead-group percentage in the log is the
+number to watch.
+
+## 6. Release
+
+```bash
+$P build_release_code.py                    # stage this directory
+$P push_release.py --dry-run                # render the card only
+$P push_release.py
+```
+
+Every number in the model card is read from an eval JSON on disk. Nothing is typed by hand, so the
+card cannot drift from the measurements.
+
+## Demo
+
+`space/` is the Gradio demo, deployable as-is to a Space. Two things that break it if "cleaned up":
+the streamer must use `skip_special_tokens=False` (`<think>`/`</think>` are real special tokens and
+stripping them destroys the reasoning/answer split), and `render_prompt()` must stay byte-identical
+to the trainer's rendering — a 52M model is very sensitive to format drift.
+
+On ZeroGPU, `import spaces` must come **before** torch, and `model.to("cuda")` at startup must stay
+unguarded: no GPU is attached at startup and the call is replayed inside the forked GPU process.
+"""
+
+
+def main():
+    if OUT.exists():
+        shutil.rmtree(OUT)
+    OUT.mkdir()
+
+    missing = [f for f in FILES if not Path(f).is_file()]
+    if missing:
+        raise SystemExit(f"missing source files: {missing}")
+
+    for name in FILES:
+        shutil.copy2(name, OUT / name)
+
+    space_out = OUT / "space"
+    space_out.mkdir()
+    for name in SPACE_FILES:
+        shutil.copy2(Path("space") / name, space_out / name)
+
+    (OUT / "README.md").write_text(README, encoding="utf-8")
+
+    n = sum(1 for _ in OUT.rglob("*") if _.is_file())
+    print(f"[+] {OUT}/ — {n} files")
+    for p in sorted(OUT.rglob("*")):
+        if p.is_file():
+            print(f"    {p.relative_to(OUT)}  ({p.stat().st_size:,} B)")
+
+
+if __name__ == "__main__":
+    main()

code/build_synth_dataset.py

@@ -0,0 +1,115 @@
+"""
+Turn out_synth/generations.jsonl into the finished synthetic corpus.
+
+Re-parses and re-validates every cached generation with synth_common (the generator's inline
+accounting is only a progress estimate; this is the authoritative pass), drops duplicates, and
+writes a parquet plus the SFT splits train_reasoning.py reads directly.
+
+Duplicates are keyed on the question with its numbers masked out, so "3 apples at 5 riyal" and
+"7 apples at 9 riyal" collapse to one template — this is the exact failure the translated GSM8K
+set has (142,969 rows from 2,814 templates), and the whole point of the variation grid is to not
+repeat it. The template count is reported so it can be checked rather than assumed.
+
+Writes:
+  out_synth/arabic_math_reasoning_synth.parquet   the corpus
+  out_synth/rejects.jsonl                         every rejected item with its reason
+  out_synth/build_stats.json                      counts, reject histogram, axis coverage
+  data_synth_sft/{train,eval}.jsonl               ready for train_reasoning.py
+"""
+import collections
+import json
+import os
+import random
+from pathlib import Path
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+import synth_common as sc
+
+OUT_DIR = Path(os.environ.get("OUT_DIR", "out_synth"))
+CACHE = OUT_DIR / "generations.jsonl"
+SFT_DIR = Path(os.environ.get("SFT_DIR", "data_synth_sft"))
+EVAL_N = int(os.environ.get("EVAL_N", 2000))
+LIMIT = int(os.environ.get("LIMIT", 0))          # 0 = keep everything that validates
+SEED = 42
+
+
+def main():
+    stats = collections.Counter()
+    rejects_by_reason = collections.Counter()
+    axes_seen = collections.defaultdict(collections.Counter)
+    rows, rejects = [], []
+    seen = {}
+
+    with open(CACHE, encoding="utf-8") as fh:
+        for line in fh:
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError:
+                stats["truncated_lines"] += 1        # a crash mid-write; the rest is still good
+                continue
+            stats["tasks"] += 1
+            items = sc.parse_items(rec["raw"])
+            stats["parsed_items"] += len(items)
+            if not items:
+                stats["tasks_with_no_parsable_item"] += 1
+            for item in items:
+                ok, reason = sc.validate(item)
+                if not ok:
+                    rejects_by_reason[reason] += 1
+                    rejects.append({**item, "reason": reason, "task_id": rec["task_id"]})
+                    continue
+                key = sc.dedup_key(item["instruction"])
+                if key in seen:
+                    stats["dropped_duplicate_template"] += 1
+                    continue
+                seen[key] = True
+                for axis, value in rec["axes"].items():
+                    axes_seen[axis][value] += 1
+                rows.append({**item, **{f"axis_{k}": v for k, v in rec["axes"].items()},
+                             "task_id": rec["task_id"],
+                             # rows cached before multi-node generation carry no model field
+                             "gen_model": rec.get("model", "gemma-3-12b-it")})
+
+    for r in rows:
+        stats[f"model_{r['gen_model']}"] += 1
+
+    stats["kept"] = len(rows)
+    stats["rejected"] = sum(rejects_by_reason.values())
+
+    random.Random(SEED).shuffle(rows)
+    if LIMIT:
+        rows = rows[:LIMIT]
+
+    OUT_DIR.mkdir(exist_ok=True)
+    pq.write_table(pa.Table.from_pylist(rows), OUT_DIR / "arabic_math_reasoning_synth.parquet")
+    with open(OUT_DIR / "rejects.jsonl", "w", encoding="utf-8") as fh:
+        for r in rejects:
+            fh.write(json.dumps(r, ensure_ascii=False) + "\n")
+
+    SFT_DIR.mkdir(exist_ok=True)
+    eval_rows, train_rows = rows[:EVAL_N], rows[EVAL_N:]
+    for name, split in (("train", train_rows), ("eval", eval_rows)):
+        with open(SFT_DIR / f"{name}.jsonl", "w", encoding="utf-8") as fh:
+            for r in split:
+                fh.write(json.dumps({"instruction": r["instruction"], "reasoning": r["reasoning"],
+                                     "answer": r["answer"], "source": "synth_math_ar"},
+                                    ensure_ascii=False) + "\n")
+        print(f"[+] {name}: {len(split):,} -> {SFT_DIR / f'{name}.jsonl'}")
+
+    summary = {
+        "stats": dict(stats),
+        "reject_reasons": dict(rejects_by_reason.most_common()),
+        "accept_rate": stats["kept"] / max(stats["parsed_items"], 1),
+        "unique_templates": len(seen),
+        "axis_coverage": {k: len(v) for k, v in axes_seen.items()},
+    }
+    (OUT_DIR / "build_stats.json").write_text(json.dumps(summary, ensure_ascii=False, indent=2),
+                                              encoding="utf-8")
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+    print(f"[+] {OUT_DIR / 'arabic_math_reasoning_synth.parquet'}")
+
+
+if __name__ == "__main__":
+    main()

code/chat.py

@@ -0,0 +1,16 @@
+"""Quick manual probe: python chat.py "سؤالك هنا" [model_dir]"""
+import sys, torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+question = sys.argv[1] if len(sys.argv) > 1 else "إذا كان لديك 1500 ريال وأنفقت 20% منها على الكتب، فكم تبقى معك؟"
+model_dir = sys.argv[2] if len(sys.argv) > 2 else "./Nawah-Reasoning-v1"
+
+tok = AutoTokenizer.from_pretrained(model_dir)
+model = AutoModelForCausalLM.from_pretrained(model_dir, dtype=torch.bfloat16).cuda().eval()
+
+prompt = tok.apply_chat_template([{"role": "user", "content": question}], tokenize=False, add_generation_prompt=True)
+ids = tok(prompt, return_tensors="pt").to("cuda")
+out = model.generate(**ids, max_new_tokens=512, do_sample=False,
+                     eos_token_id=[tok.eos_token_id, tok.convert_tokens_to_ids("<|im_end|>")],
+                     pad_token_id=tok.pad_token_id)
+print(tok.decode(out[0][ids["input_ids"].shape[1]:], skip_special_tokens=False).split("<|im_end|>")[0])

code/eval_reasoning.py

@@ -0,0 +1,136 @@
+"""
+Greedy evaluation of the reasoning model on the held-out split.
+
+Reports:
+  * format compliance   — a single well-formed <think>…</think> block followed by an answer
+  * numeric agreement   — do the numbers in the generated conclusion match the reference's
+  * length stats        — how long the produced reasoning is
+
+When the eval rows carry a `source` tag (the v3 mix), every metric is also broken down per
+source, since the two corpora answer in different styles.
+
+Usage: python eval_reasoning.py [model_dir] [n_samples]
+"""
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+MODEL_DIR = sys.argv[1] if len(sys.argv) > 1 else "./Nawah-Reasoning-v1"
+LIMIT     = int(sys.argv[2]) if len(sys.argv) > 2 else 400
+EVAL_FILE = os.environ.get("EVAL_FILE", "data/eval.jsonl")
+MAX_NEW   = 512
+BATCH     = 16
+
+AR_DIGITS = str.maketrans("٠١٢٣٤٥٦٧٨٩٫٬", "0123456789.,")
+NUM_RE    = re.compile(r"\d+(?:\.\d+)?")
+
+
+def numbers(text: str):
+    text = text.translate(AR_DIGITS).replace(",", "")
+    out = []
+    for tok in NUM_RE.findall(text):
+        val = float(tok)
+        out.append(int(val) if val.is_integer() else val)
+    return out
+
+
+def parse(completion: str):
+    """-> (reasoning, final_answer, well_formed)"""
+    m = re.match(r"\s*<think>(.*?)</think>(.*)", completion, re.S)
+    if not m:
+        return None, completion.strip(), False
+    reasoning, final = m.group(1).strip(), m.group(2).strip()
+    well_formed = (
+        completion.count("<think>") == 1
+        and completion.count("</think>") == 1
+        and bool(reasoning)
+        and bool(final)
+    )
+    return reasoning, final, well_formed
+
+
+def metrics(results):
+    n = len(results)
+    return {
+        "n": n,
+        "well_formed_pct": 100 * sum(r["well_formed"] for r in results) / n,
+        "numbers_match_pct": 100 * sum(r["numbers_match"] for r in results) / n,
+        "primary_number_match_pct": 100 * sum(r["primary_number_match"] for r in results) / n,
+        "answer_exact_pct": 100 * sum(r["answer_exact"] for r in results) / n,
+        "mean_reasoning_tokens": sum(r["reasoning_tokens"] for r in results) / n,
+    }
+
+
+def main():
+    tok = AutoTokenizer.from_pretrained(MODEL_DIR)
+    model = AutoModelForCausalLM.from_pretrained(MODEL_DIR, dtype=torch.bfloat16).cuda().eval()
+    model.config.use_cache = True
+
+    rows = [json.loads(l) for l in open(EVAL_FILE, encoding="utf-8")][:LIMIT]
+    im_end = tok.convert_tokens_to_ids("<|im_end|>")
+
+    results = []
+    for start in range(0, len(rows), BATCH):
+        chunk = rows[start : start + BATCH]
+        prompts = [
+            f"<|im_start|>user\n{r['instruction']}<|im_end|>\n<|im_start|>assistant\n" for r in chunk
+        ]
+        encoded = [[tok.bos_token_id] + tok.encode(p, add_special_tokens=False) for p in prompts]
+        width = max(len(e) for e in encoded)
+        # left-pad so every row's generation starts at the same offset
+        input_ids = torch.tensor([[tok.pad_token_id] * (width - len(e)) + e for e in encoded]).cuda()
+        attn = torch.tensor([[0] * (width - len(e)) + [1] * len(e) for e in encoded]).cuda()
+
+        with torch.no_grad():
+            out = model.generate(
+                input_ids=input_ids,
+                attention_mask=attn,
+                max_new_tokens=MAX_NEW,
+                do_sample=False,
+                eos_token_id=[im_end, tok.eos_token_id],
+                pad_token_id=tok.pad_token_id,
+            )
+        for row, seq in zip(chunk, out):
+            gen = tok.decode(seq[width:], skip_special_tokens=False)
+            gen = gen.split("<|im_end|>")[0].replace("</s>", "").replace("<pad>", "")
+            reasoning, final, ok = parse(gen)
+            ref_nums, gen_nums = numbers(row["answer"]), numbers(final)
+            results.append(
+                {
+                    "source": row.get("source"),
+                    "instruction": row["instruction"],
+                    "reference_reasoning": row["reasoning"],
+                    "reference_answer": row["answer"],
+                    "generated_reasoning": reasoning,
+                    "generated_answer": final,
+                    "well_formed": ok,
+                    "answer_exact": final.strip() == row["answer"].strip(),
+                    "numbers_match": bool(ref_nums) and ref_nums == gen_nums,
+                    "primary_number_match": bool(ref_nums) and ref_nums[0] in gen_nums,
+                    "reasoning_tokens": len(tok.encode(reasoning or "", add_special_tokens=False)),
+                }
+            )
+        print(f"  {min(start + BATCH, len(rows))}/{len(rows)}", flush=True)
+
+    summary = metrics(results)
+    summary["model"] = MODEL_DIR
+    # A mixed corpus (v3) answers in two different styles, so a single exact-match number is
+    # meaningless — score each source on its own terms.
+    sources = sorted({r["source"] for r in results if r["source"]})
+    if len(sources) > 1:
+        summary["by_source"] = {s: metrics([r for r in results if r["source"] == s]) for s in sources}
+    print(json.dumps(summary, indent=2))
+
+    Path(MODEL_DIR, "eval_reasoning.json").write_text(
+        json.dumps({"summary": summary, "samples": results}, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    print(f"[+] wrote {Path(MODEL_DIR, 'eval_reasoning.json')}")
+
+
+if __name__ == "__main__":
+    main()

code/finish_merge_push.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Merge the primary cache with every node shard, rebuild the corpus, push to the Hub.
+#
+# Run this after the primary generator exits. Idempotent: it re-merges from the two
+# caches every time, so re-running after a resumed generation just produces a larger
+# corpus. Neither node's live cache is touched — the merge lands in out_merged/.
+#
+#   ./finish_merge_push.sh            # build + card, no push  (review, then re-run with push)
+#   ./finish_merge_push.sh --push     # build + card + upload
+set -euo pipefail
+cd /notebooks/50M/reasonsing
+P=/notebooks/50M/.venv-lfm2/bin/python
+REPO=oddadmix/arabic-math-reasoning-synth
+SHARD_DIR=shards_dl/shards
+
+# 1. merge — primary cache first, then every shard pulled from the Hub
+mkdir -p out_merged
+cat out_synth/generations.jsonl > out_merged/generations.jsonl
+for gz in "$SHARD_DIR"/*.jsonl.gz; do
+    echo "[*] merging shard $(basename "$gz")"
+    gunzip -c "$gz" >> out_merged/generations.jsonl
+done
+echo "[+] merged cache: $(wc -l < out_merged/generations.jsonl) tasks"
+
+# 2. authoritative re-parse / re-validate / dedup over the whole merged cache
+OUT_DIR=out_merged SFT_DIR=data_synth_sft $P build_synth_dataset.py > /tmp/build.log 2>&1
+$P - <<'PY'
+import json
+d = json.load(open("out_merged/build_stats.json")); s = d["stats"]
+print(f"[+] kept {s['kept']:,} rows | templates {d['unique_templates']:,} | "
+      f"accept {d['accept_rate']:.1%} | dup drops {s.get('dropped_duplicate_template',0):,}")
+for k in sorted(s):
+    if k.startswith("model_"):
+        print(f"      {k[6:]:36s} {s[k]:,}")
+PY
+
+# 3. card + upload
+if [[ "${1:-}" == "--push" ]]; then
+    OUT_DIR=out_merged $P push_synth_dataset.py --repo "$REPO"
+else
+    OUT_DIR=out_merged $P push_synth_dataset.py --repo "$REPO" --dry-run
+fi

code/grpo_train.py

@@ -0,0 +1,193 @@
+"""
+GRPO (Group Relative Policy Optimization) with a verifiable reward, for the Nawah reasoning models.
+
+Why hand-rolled: TRL is not installed and cannot be added cleanly here — .venv-lfm2 runs
+transformers 5.15 while current TRL targets 4.x, and .venv-vllm is pinned to transformers 4.51.3
+and must not be upgraded (see HANDOFF.md). At 51.8M parameters the algorithm is small enough that
+a direct implementation is less risk than a third environment.
+
+The method, briefly: sample G completions per prompt, score each with a mechanical verifier,
+normalise the rewards WITHIN the group to get advantages, and do a policy-gradient step. No value
+network — the group mean is the baseline, which is the whole point of GRPO.
+
+    A_i = (r_i - mean(r)) / (std(r) + eps)
+    loss = -mean_i( A_i * mean_t log pi(token_t) ) + beta * KL_k3(pi || pi_ref)
+
+Sampling is on-policy and each batch takes exactly one gradient step, so there is no importance
+ratio and no PPO clipping to get wrong — the ratio would be identically 1.
+
+⚠️ The measured precondition: a group where every sample scores the same has zero advantage and
+contributes NO gradient. On v5, 40.4% of synth problems are never solved in 8 tries, so those
+groups are dead weight — they are skipped and counted, not silently averaged in. The exploitable
+headroom is pass@k - pass@1, measured at +27.1 points (32.5% -> 59.6%) by passk_diag.py.
+"""
+import json
+import os
+import sys
+from pathlib import Path
+
+import torch
+import torch.nn.functional as F
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+sys.path.insert(0, ".")
+from eval_reasoning import numbers, parse
+
+MODEL      = os.environ.get("MODEL", "./Nawah-Reasoning-v5")
+OUTPUT_DIR = os.environ.get("OUTPUT_DIR", "./Nawah-Reasoning-v6-grpo")
+TRAIN_FILE = os.environ.get("TRAIN_FILE", "data_synth_sft/train.jsonl")
+
+GROUP        = int(os.environ.get("GROUP", 8))          # completions per prompt
+PROMPTS_PER  = int(os.environ.get("PROMPTS_PER", 8))    # prompts per optimiser step
+STEPS        = int(os.environ.get("STEPS", 500))
+LR           = float(os.environ.get("LR", 1e-6))        # RL wants far less than SFT's 3e-4
+BETA         = float(os.environ.get("BETA", 0.02))      # KL to the frozen reference
+TEMP         = float(os.environ.get("TEMP", 1.0))
+MAX_NEW      = int(os.environ.get("MAX_NEW", 320))
+MAX_GRAD     = 1.0
+SAVE_EVERY   = int(os.environ.get("SAVE_EVERY", 100))
+LOG_EVERY    = int(os.environ.get("LOG_EVERY", 5))
+SEED         = int(os.environ.get("SEED", 42))
+FORMAT_PENALTY = float(os.environ.get("FORMAT_PENALTY", 0.1))
+
+
+def reward(completion: str, ref: float) -> float:
+    """Verifiable reward: does the stated final answer equal the reference number?
+
+    Deliberately NOT a partial-credit score. The failure this is meant to fix is a model that
+    reasons plausibly and lands on the wrong number, so rewarding anything short of the right
+    number would reinforce exactly that.
+    """
+    _, ans, well_formed = parse(completion)
+    ns = numbers(ans or "")
+    correct = bool(ns) and ref is not None and ns[-1] == ref
+    r = 1.0 if correct else 0.0
+    if not well_formed:
+        r -= FORMAT_PENALTY
+    return r
+
+
+def completion_logprobs(model, ids, attn, prompt_len):
+    """-> (mean log pi over completion tokens, per-token log pi, completion mask).
+
+    Prompt tokens are masked out: the prompt is not an action the policy chose, so including it
+    would add a term with no gradient meaning and would dilute the per-sequence mean.
+    """
+    out = model(input_ids=ids, attention_mask=attn)
+    logits = out.logits[:, :-1]                       # position t predicts token t+1
+    targets = ids[:, 1:]
+    logp = torch.log_softmax(logits.float(), dim=-1)
+    tok_logp = logp.gather(-1, targets.unsqueeze(-1)).squeeze(-1)
+    mask = attn[:, 1:].clone().float()
+    mask[:, : prompt_len - 1] = 0.0                   # only the generated part is the "action"
+    mean_lp = (tok_logp * mask).sum(1) / mask.sum(1).clamp(min=1)
+    return mean_lp, tok_logp, mask
+
+
+def k3_kl(pol_tok, ref_tok, mask):
+    """Schulman's k3 estimator of KL(pi || pi_ref): exp(d) - d - 1 where d = log pi_ref - log pi.
+
+    Unbiased and always non-negative, unlike the naive (log pi - log pi_ref) difference. Computed
+    per token and averaged over the completion, which is what GRPO regularises.
+    """
+    d = (ref_tok - pol_tok).clamp(-20, 20)
+    per_tok = torch.exp(d) - d - 1.0
+    return (per_tok * mask).sum(1) / mask.sum(1).clamp(min=1)
+
+
+def main():
+    torch.manual_seed(SEED)
+    tok = AutoTokenizer.from_pretrained(MODEL)
+    policy = AutoModelForCausalLM.from_pretrained(MODEL, dtype=torch.float32).cuda()
+    ref = AutoModelForCausalLM.from_pretrained(MODEL, dtype=torch.float32).cuda().eval()
+    for p in ref.parameters():
+        p.requires_grad_(False)
+    policy.config.use_cache = True
+
+    rows = [json.loads(l) for l in open(TRAIN_FILE, encoding="utf-8")]
+    refs = []
+    for r in rows:
+        ns = numbers(r["answer"])
+        if ns:
+            refs.append((r["instruction"], ns[-1]))
+    print(f"[*] {len(refs):,} prompts with a parseable reference answer", flush=True)
+
+    opt = torch.optim.AdamW(policy.parameters(), lr=LR, weight_decay=0.0)
+    rng = torch.Generator().manual_seed(SEED)
+    Path(OUTPUT_DIR).mkdir(exist_ok=True)
+    history, dead_groups, seen = [], 0, 0
+
+    for step in range(1, STEPS + 1):
+        idx = torch.randint(0, len(refs), (PROMPTS_PER,), generator=rng).tolist()
+        batch = [refs[i] for i in idx]
+        step_rewards, step_solved, losses = [], [], []
+        opt.zero_grad(set_to_none=True)
+        used_groups = 0
+
+        for question, ref_num in batch:
+            prompt = tok.apply_chat_template([{"role": "user", "content": question}],
+                                             tokenize=False, add_generation_prompt=True)
+            enc = tok(prompt, return_tensors="pt").to("cuda")
+            plen = enc["input_ids"].shape[1]
+
+            policy.eval()
+            with torch.no_grad():
+                gen = policy.generate(**enc, max_new_tokens=MAX_NEW, do_sample=True,
+                                      temperature=TEMP, top_p=0.95,
+                                      num_return_sequences=GROUP,
+                                      pad_token_id=tok.pad_token_id)
+            policy.train()
+
+            texts = tok.batch_decode(gen[:, plen:], skip_special_tokens=True)
+            r = torch.tensor([reward(t, ref_num) for t in texts], dtype=torch.float32)
+            step_rewards.append(r.mean().item())
+            step_solved.append(float((r > 0.5).any()))
+            seen += 1
+
+            # A group with no reward spread carries no learning signal — skip it rather than
+            # letting a zero-advantage group dilute the batch.
+            if r.std() < 1e-6:
+                dead_groups += 1
+                continue
+            adv = ((r - r.mean()) / (r.std() + 1e-6)).cuda()
+
+            attn = (gen != tok.pad_token_id).long()
+            attn[:, :plen] = 1
+            mean_lp, pol_tok, mask = completion_logprobs(policy, gen, attn, plen)
+            with torch.no_grad():
+                _, ref_tok, _ = completion_logprobs(ref, gen, attn, plen)
+
+            pg = -(adv * mean_lp).mean()
+            kl = k3_kl(pol_tok, ref_tok, mask).mean()
+            loss = (pg + BETA * kl) / PROMPTS_PER
+            loss.backward()
+            losses.append(pg.item())
+            used_groups += 1
+
+        if used_groups:
+            torch.nn.utils.clip_grad_norm_(policy.parameters(), MAX_GRAD)
+            opt.step()
+
+        history.append({"step": step, "mean_reward": sum(step_rewards) / len(step_rewards),
+                        "any_solved": sum(step_solved) / len(step_solved),
+                        "pg_loss": (sum(losses) / len(losses)) if losses else None,
+                        "live_groups": used_groups})
+        if step % LOG_EVERY == 0:
+            h = history[-1]
+            print(f"[{step:>4}/{STEPS}] reward {h['mean_reward']:.3f}  "
+                  f"pass@{GROUP} {h['any_solved']:.2f}  live {used_groups}/{PROMPTS_PER}  "
+                  f"dead so far {100*dead_groups/max(seen,1):.0f}%", flush=True)
+
+        if step % SAVE_EVERY == 0 or step == STEPS:
+            policy.config.use_cache = True
+            policy.save_pretrained(OUTPUT_DIR)
+            tok.save_pretrained(OUTPUT_DIR)
+            Path(OUTPUT_DIR, "grpo_history.json").write_text(
+                json.dumps(history, ensure_ascii=False, indent=2), encoding="utf-8")
+            print(f"    [+] saved at step {step}", flush=True)
+
+    print(f"[+] done -> {OUTPUT_DIR}  ({100*dead_groups/max(seen,1):.1f}% of groups had no signal)")
+
+
+if __name__ == "__main__":
+    main()

code/gsm_common.py

@@ -0,0 +1,45 @@
+"""Shared parsing/masking helpers for the GSM8K reasoning dataset translation."""
+import re
+
+RECORD_RE = re.compile(
+    r"<question>(.*?)</question>\s*<thinking>(.*?)</thinking>\s*<answer>(.*?)</answer>", re.S
+)
+NUM_RE = re.compile(r"\d+(?:\.\d+)?")
+PH_RE = re.compile(r"#(\d+)#")
+
+SRC_PROMPT = "Translate the following English sentence into Arabic:\n{text} <ar>"
+
+
+def parse(text):
+    m = RECORD_RE.match(text.strip())
+    if not m:
+        return None
+    return m.group(1).strip(), m.group(2).strip(), m.group(3).strip()
+
+
+def mask_numbers(text):
+    """'168 + 19 = 187' -> ('#0# + #1# = #2#', ['168', '19', '187'])"""
+    nums = []
+
+    def repl(m):
+        nums.append(m.group(0))
+        return f"#{len(nums) - 1}#"
+
+    return NUM_RE.sub(repl, text), nums
+
+
+def unmask_numbers(text, nums):
+    """Restore. Returns (text, ok) — ok is False if any placeholder was lost or duplicated."""
+    seen = []
+
+    def repl(m):
+        i = int(m.group(1))
+        seen.append(i)
+        return nums[i] if i < len(nums) else m.group(0)
+
+    out = PH_RE.sub(repl, text)
+    return out, sorted(seen) == list(range(len(nums)))
+
+
+def build_record(question, thinking, answer):
+    return f"<question>{question}</question> <thinking>{thinking}</thinking> <answer>{answer}</answer>"

code/passk_diag.py

@@ -0,0 +1,68 @@
+"""
+pass@1 vs pass@k on the synthetic held-out set, broken down by step count.
+
+This is the go/no-go diagnostic for RL with verifiable rewards. RLVR (GRPO/RLOO) reweights samples
+the model ALREADY produces: if a problem is never solved in k tries, every sample in the group gets
+reward 0, the advantage is 0, and there is no gradient. So the headroom RL can capture is bounded
+by (pass@k - pass@1), and only on problems where pass@k > 0.
+"""
+import json, os, sys, collections
+import torch, pyarrow.parquet as pq
+from transformers import AutoModelForCausalLM, AutoTokenizer
+sys.path.insert(0, ".")
+from eval_reasoning import numbers, parse
+
+MODEL = sys.argv[1] if len(sys.argv) > 1 else "./Nawah-Reasoning-v5"
+PER_BUCKET = int(os.environ.get("PER_BUCKET", 60))
+K = int(os.environ.get("K", 8))
+TEMP = float(os.environ.get("TEMP", 1.0))
+
+tok = AutoTokenizer.from_pretrained(MODEL)
+model = AutoModelForCausalLM.from_pretrained(MODEL, dtype=torch.bfloat16).cuda().eval()
+
+rows = pq.read_table("out_merged/arabic_math_reasoning_synth.parquet").to_pylist()[:2000]
+buckets = collections.defaultdict(list)
+for r in rows:
+    buckets[r["axis_steps"]].append(r)
+sample = [r for b in buckets.values() for r in b[:PER_BUCKET]]
+print(f"[*] {len(sample)} problems x k={K} @ T={TEMP} -> {len(sample)*K} generations", flush=True)
+
+def ref_number(r):
+    ns = numbers(r["answer"])
+    return ns[-1] if ns else None
+
+stats = collections.defaultdict(lambda: {"n": 0, "p1": 0, "pk": 0})
+BATCH = 16
+for start in range(0, len(sample), BATCH):
+    chunk = sample[start:start + BATCH]
+    prompts = [tok.apply_chat_template([{"role": "user", "content": r["instruction"]}],
+                                       tokenize=False, add_generation_prompt=True) for r in chunk]
+    enc = tok(prompts, return_tensors="pt", padding=True, padding_side="left").to("cuda")
+    torch.manual_seed(1234 + start)
+    out = model.generate(**enc, max_new_tokens=320, do_sample=True, temperature=TEMP,
+                         top_p=0.95, num_return_sequences=K)
+    gen = tok.batch_decode(out[:, enc["input_ids"].shape[1]:], skip_special_tokens=True)
+    for i, r in enumerate(chunk):
+        ref = ref_number(r)
+        hits = []
+        for j in range(K):
+            _, ans, _ = parse(gen[i * K + j])
+            ns = numbers(ans or "")
+            hits.append(bool(ns) and ref is not None and ns[-1] == ref)
+        s = stats[r["axis_steps"]]
+        s["n"] += 1
+        s["p1"] += hits[0]
+        s["pk"] += any(hits)
+    print(f"    {start + len(chunk)}/{len(sample)}", flush=True)
+
+print("\n| steps | n | pass@1 | pass@%d | headroom |" % K)
+print("|---|---:|---:|---:|---:|")
+tot = {"n": 0, "p1": 0, "pk": 0}
+for k, s in sorted(stats.items(), key=lambda kv: kv[1]["n"], reverse=True):
+    for f in tot: tot[f] += s[f]
+    print(f"| {k} | {s['n']} | {100*s['p1']/s['n']:.1f}% | {100*s['pk']/s['n']:.1f}% | "
+          f"{100*(s['pk']-s['p1'])/s['n']:+.1f} |")
+print(f"| **all** | {tot['n']} | {100*tot['p1']/tot['n']:.1f}% | {100*tot['pk']/tot['n']:.1f}% | "
+      f"{100*(tot['pk']-tot['p1'])/tot['n']:+.1f} |")
+print(f"\nnever-solved (pass@{K}=0): {100*(tot['n']-tot['pk'])/tot['n']:.1f}% of problems "
+      f"-> zero RL gradient on these")

code/prepare_data.py

@@ -0,0 +1,140 @@
+"""
+Prepare Omartificial-Intelligence-Space/Arabic_Reasoning_Dataset for reasoning SFT.
+
+Each row (instruction, answer) becomes a ChatML sample where the derivation lives
+inside <think>...</think> and the conclusion follows it:
+
+    <|im_start|>user\n{instruction}<|im_end|>\n<|im_start|>assistant\n<think>\n{reasoning}\n</think>\n{answer}<|im_end|>
+
+Only rows whose derivation ends in an explicit conclusion line ("إذن، ...") are kept.
+Expository rows without one have no real "final answer" to place after </think> — their
+closing paragraph is a side remark, so training on them would teach the model to think and
+then trail off. They are dropped rather than force-split.
+
+Writes data/train.jsonl and data/eval.jsonl.
+"""
+import json, re, random, unicodedata, collections
+from pathlib import Path
+
+import pyarrow.parquet as pq
+
+SRC      = Path("data/data/train-00000-of-00001.parquet")
+OUT_DIR  = Path("data")
+EVAL_N   = 400
+SEED     = 42
+
+# Lines that mark the final conclusion of a derivation.
+CONCLUSION = ["إذن،", "إذن ", "لذا،", "لذلك،", "باختصار،", "وبالتالي،", "في النهاية،",
+              "الخلاصة", "النتيجة النهائية", "النتيجة:", "الإجابة", "الجواب", "بالتالي،"]
+# Chatty sign-offs that are not part of the answer.
+FLUFF = ["تذكر", "آمل", "أتمنى", "يرجى", "لا تتردد", "إذا كان لديك أي", "هل لديك",
+         "أرجو", "نصيحة:", "ملاحظة:", "إذا كانت لديك"]
+# Prompt suffix present on a subset of instructions; stripped so reasoning is unconditional.
+SUFFIX_RE = re.compile(r"\s*خذ\s+نفسًا?\s+عميقًا.*$", re.S)
+
+MIN_THINK_CHARS  = 60
+MIN_ANSWER_CHARS = 10
+
+MD_NOISE_RE  = re.compile(r"\*\*|__|#{2,}")
+# Some source rows bundle several problems; the conclusion of one is followed by the next
+# problem's header. Anything from that header on is not part of the answer.
+NEXT_PROBLEM_RE = re.compile(r"^\s*(المشكلة|المسألة|السؤال|التمرين|مثال|Problem|Question|Example)\b")
+ANSWER_ARTIFACT_RE = re.compile(r"^\s*(\*\*)?Answer:\s*", re.I)
+
+
+def norm(text: str) -> str:
+    text = unicodedata.normalize("NFC", text.replace("‏", "").replace("‎", ""))
+    text = re.sub(r"[ \t]+", " ", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+def clean_instruction(text: str) -> str:
+    return norm(SUFFIX_RE.sub("", norm(text))).rstrip(". ").strip() or norm(text)
+
+
+def is_fluff(line: str) -> bool:
+    head = line.lstrip("*#- ").strip()
+    return any(head.startswith(f) for f in FLUFF)
+
+
+def is_conclusion(line: str) -> bool:
+    head = line.lstrip("*#- ").strip()
+    return any(head.startswith(m) for m in CONCLUSION)
+
+
+def strip_markup(line: str) -> str:
+    """Drop markdown emphasis and the stray "**Answer:" prefix some rows carry."""
+    return norm(MD_NOISE_RE.sub("", ANSWER_ARTIFACT_RE.sub("", line)))
+
+
+def split_answer(answer: str, instruction: str):
+    """-> (reasoning, final_answer) or None when the row can't be split cleanly."""
+    lines = [strip_markup(l) for l in norm(answer).split("\n")]
+    lines = [l for l in lines if l]
+    if len(lines) < 2:
+        return None
+
+    # Drop trailing chatter first — it belongs to neither part.
+    while lines and is_fluff(lines[-1]):
+        lines.pop()
+    if len(lines) < 2:
+        return None
+
+    # A leading restatement of the question adds nothing to the derivation.
+    if lines and lines[0][:40] == instruction.strip()[:40]:
+        lines.pop(0)
+
+    idx = next((i for i in range(len(lines) - 1, 0, -1) if is_conclusion(lines[i])), None)
+    if idx is None:
+        return None
+    reasoning = "\n".join(lines[:idx])
+    tail = lines[idx:]
+    cut = next((i for i in range(1, len(tail)) if NEXT_PROBLEM_RE.match(tail[i])), len(tail))
+    final = "\n".join(tail[:cut])
+
+    if len(reasoning) < MIN_THINK_CHARS or len(final) < MIN_ANSWER_CHARS:
+        return None
+    # A "conclusion" longer than the derivation means the split went the wrong way.
+    if len(final) > len(reasoning):
+        return None
+    return reasoning, final
+
+
+def main():
+    table = pq.read_table(SRC).to_pydict()
+    rows  = list(zip(table["instruction"], table["answer"]))
+    stats = collections.Counter(total=len(rows))
+
+    seen, samples = set(), []
+    for raw_ins, raw_ans in rows:
+        ins = clean_instruction(raw_ins)
+        key = re.sub(r"\W+", "", ins)
+        if key in seen:
+            stats["dropped_duplicate"] += 1
+            continue
+        seen.add(key)
+
+        split = split_answer(raw_ans, ins)
+        if split is None:
+            stats["dropped_no_conclusion"] += 1
+            continue
+        reasoning, final = split
+        stats["kept"] += 1
+        samples.append({"instruction": ins, "reasoning": reasoning, "answer": final})
+
+    random.Random(SEED).shuffle(samples)
+    eval_set, train_set = samples[:EVAL_N], samples[EVAL_N:]
+
+    OUT_DIR.mkdir(exist_ok=True)
+    for name, split in (("train", train_set), ("eval", eval_set)):
+        with open(OUT_DIR / f"{name}.jsonl", "w", encoding="utf-8") as fh:
+            for s in split:
+                fh.write(json.dumps(s, ensure_ascii=False) + "\n")
+        print(f"[+] {name}: {len(split)} samples -> {OUT_DIR / f'{name}.jsonl'}")
+
+    print("[*] stats:", dict(stats))
+
+
+if __name__ == "__main__":
+    main()

code/prepare_gsm_sft.py

@@ -0,0 +1,38 @@
+"""
+Convert the Arabic GSM8K dataset into the SFT schema train_reasoning.py already reads
+({instruction, reasoning, answer}), so v2 trains in the same ChatML + <think> format as v1.
+
+The final answer is kept as the bare numeral: it matches the source's intent and makes
+exact-match evaluation trivial.
+"""
+import json
+import random
+from pathlib import Path
+
+import pyarrow.parquet as pq
+
+SRC = Path("out_gsm/gsm8k_reasoning_ar.parquet")
+OUT = Path("data_gsm_sft")
+EVAL_N = 2000
+SEED = 42
+
+
+def main():
+    d = pq.read_table(SRC).to_pydict()
+    rows = [
+        {"instruction": q, "reasoning": t, "answer": a}
+        for q, t, a in zip(d["question"], d["thinking"], d["answer"])
+    ]
+    random.Random(SEED).shuffle(rows)
+    eval_rows, train_rows = rows[:EVAL_N], rows[EVAL_N:]
+
+    OUT.mkdir(exist_ok=True)
+    for name, split in (("train", train_rows), ("eval", eval_rows)):
+        with open(OUT / f"{name}.jsonl", "w", encoding="utf-8") as fh:
+            for r in split:
+                fh.write(json.dumps(r, ensure_ascii=False) + "\n")
+        print(f"[+] {name}: {len(split)} -> {OUT / f'{name}.jsonl'}")
+
+
+if __name__ == "__main__":
+    main()

code/prepare_v6_sft.py

@@ -0,0 +1,139 @@
+"""
+Build the v6 SFT corpus: the v5 three-way mix, with the synthetic corpus swapped for the larger
+one that carries the relational pool.
+
+This is `prepare_v5_sft.py` with `SYNTH_DIR` repointed and a fourth eval column added. Separate
+file, same reason v5 was separate from v3: v5 is the shipped model and must stay reproducible.
+
+The synth split comes from `split_synth_v6.py`, not `build_synth_dataset.py` — the v6 corpus is
+20,139 rows larger, so a re-drawn shuffle would put 1,955 of v5's held-out rows into v6's train.
+The eval rows are pinned to v5's instead, which keeps the synth cell comparable and, because
+`eval.jsonl` is byte-identical to v5's, makes the mix-eval synth column the *same 400 rows* v5 was
+scored on.
+
+`eval_rel.jsonl` (400 relational rows, held out of train) is the column that actually measures
+what v6 was built for — none of the legacy eval rows test a relational comparison.
+
+    data/{train,eval}.jsonl            <- prepare_data.py       (Arabic_Reasoning_Dataset)
+    data_gsm_sft/{train,eval}.jsonl    <- prepare_gsm_sft.py    (oddadmix/gsm8k-reasoning-ar)
+    data_synth_v6_sft/{train,eval,eval_rel}.jsonl <- split_synth_v6.py (120,462-row corpus)
+
+Why all three: v3 scores 77.3% on GSM8K-ar but 2.0% on the synth held-out set, and v4 (synth only)
+inverts that — 35.6% synth, 19.5% GSM. Neither corpus alone covers the other's distribution, so v5
+trains on all three at once.
+
+Answer styles are NOT normalised — GSM8K ends in a bare numeral, Arabic_Reasoning and the synth
+corpus in an "إذن، …" sentence. A `source` tag rides on every row so eval_reasoning.py scores each
+on its own terms. The eval set keeps v1's 400 AR rows and v2's first 600 GSM rows *unchanged*, so
+the AR and GSM cells stay directly comparable to v1/v2/v3.
+
+Writes data_v6_sft/{train,eval}.jsonl.
+"""
+import json
+import os
+import random
+from collections import Counter
+from pathlib import Path
+
+AR_DIR    = Path("data")             # v1 splits
+GSM_DIR   = Path("data_gsm_sft")     # v2 splits
+SYNTH_DIR = Path("data_synth_v6_sft")  # the 120,462-row corpus, relational pool included
+OUT       = Path("data_v6_sft")
+
+# Arabic_Reasoning is ~25x smaller than GSM8K, so it is repeated (same value v3 used).
+REPEAT       = int(os.environ.get("REPEAT", 3))
+SYNTH_REPEAT = int(os.environ.get("SYNTH_REPEAT", 1))
+# Eval: v1's 400 AR rows are all kept and v2's first 600 GSM rows, exactly as v3 built them, plus
+# synth rows so all three distributions are scored in one pass.
+EVAL_GSM   = int(os.environ.get("EVAL_GSM", 600))
+EVAL_SYNTH = int(os.environ.get("EVAL_SYNTH", 400))
+EVAL_REL   = int(os.environ.get("EVAL_REL", 400))
+SEED       = 42
+
+
+def load(path):
+    with open(path, encoding="utf-8") as fh:
+        return [json.loads(line) for line in fh]
+
+
+def tag(rows, source):
+    return [{**r, "source": source} for r in rows]
+
+
+def token_stats(rows, tok):
+    per_source, lengths = Counter(), []
+    for r in rows:
+        text = (f"<|im_start|>user\n{r['instruction']}<|im_end|>\n<|im_start|>assistant\n"
+                f"<think>\n{r['reasoning']}\n</think>\n{r['answer']}<|im_end|>")
+        n = len(tok.encode(text, add_special_tokens=False))
+        per_source[r["source"]] += n
+        lengths.append(n)
+    lengths.sort()
+    pct = lambda p: lengths[min(int(len(lengths) * p / 100), len(lengths) - 1)]
+    return per_source, {"p50": pct(50), "p95": pct(95), "p99": pct(99), "max": lengths[-1]}
+
+
+def interleave(groups):
+    """Round-robin proportional to each group's size, so a truncated eval run still covers all
+    three sources instead of whichever landed first."""
+    groups = [g for g in groups if g]
+    if not groups:
+        return []
+    total = sum(len(g) for g in groups)
+    out, idx = [], [0] * len(groups)
+    for _ in range(total):
+        # pick the group that is furthest behind its target share
+        pick = min(range(len(groups)), key=lambda i: (idx[i] / len(groups[i])) if idx[i] < len(groups[i]) else 2.0)
+        if idx[pick] >= len(groups[pick]):
+            break
+        out.append(groups[pick][idx[pick]])
+        idx[pick] += 1
+    for g, i in zip(groups, idx):          # anything the loop could not place
+        out.extend(g[i:])
+    return out
+
+
+def main():
+    for d in (AR_DIR, GSM_DIR, SYNTH_DIR):
+        for split in ("train", "eval"):
+            if not (d / f"{split}.jsonl").exists():
+                raise SystemExit(f"missing {d/f'{split}.jsonl'}")
+
+    ar_train    = tag(load(AR_DIR / "train.jsonl"), "arabic_reasoning")
+    ar_eval     = tag(load(AR_DIR / "eval.jsonl"), "arabic_reasoning")
+    gsm_train   = tag(load(GSM_DIR / "train.jsonl"), "gsm8k_ar")
+    gsm_eval    = tag(load(GSM_DIR / "eval.jsonl"), "gsm8k_ar")
+    synth_train = tag(load(SYNTH_DIR / "train.jsonl"), "synth_math_ar")
+    synth_eval  = tag(load(SYNTH_DIR / "eval.jsonl"), "synth_math_ar")
+    rel_eval    = tag(load(SYNTH_DIR / "eval_rel.jsonl"), "synth_relational_ar")
+
+    train = gsm_train + ar_train * REPEAT + synth_train * SYNTH_REPEAT
+    random.Random(SEED).shuffle(train)
+
+    eval_rows = interleave([ar_eval, gsm_eval[:EVAL_GSM], synth_eval[:EVAL_SYNTH],
+                            rel_eval[:EVAL_REL]])
+
+    OUT.mkdir(exist_ok=True)
+    for name, split in (("train", train), ("eval", eval_rows)):
+        with open(OUT / f"{name}.jsonl", "w", encoding="utf-8") as fh:
+            for r in split:
+                fh.write(json.dumps(r, ensure_ascii=False) + "\n")
+        print(f"[+] {name}: {len(split):,} -> {OUT / f'{name}.jsonl'}  "
+              f"{dict(Counter(r['source'] for r in split))}")
+
+    try:
+        from transformers import AutoTokenizer
+        tok = AutoTokenizer.from_pretrained(os.environ.get("BASE_MODEL", "/notebooks/50M/50M-2048-Emhotob"))
+        tok.add_special_tokens({"additional_special_tokens": ["<|im_start|>", "<|im_end|>", "<think>", "</think>"]})
+        per_source, pct = token_stats(train, tok)
+        total = sum(per_source.values())
+        print(f"[*] train tokens: {total/1e6:.1f}M/epoch  (REPEAT={REPEAT}, SYNTH_REPEAT={SYNTH_REPEAT})")
+        for src, n in per_source.most_common():
+            print(f"      {src:<18} {n/1e6:6.2f}M  {100*n/total:5.1f}%")
+        print(f"[*] sample length: p50 {pct['p50']}  p95 {pct['p95']}  p99 {pct['p99']}  max {pct['max']}")
+    except Exception as exc:
+        print(f"[!] token stats skipped: {exc}")
+
+
+if __name__ == "__main__":
+    main()

code/push_dataset.py

@@ -0,0 +1,150 @@
+"""
+Push the Arabic GSM8K reasoning dataset to the Hub as a PRIVATE dataset repo.
+
+Usage: python push_dataset.py [--repo oddadmix/gsm8k-reasoning-ar] [--dry-run]
+"""
+import argparse
+import json
+from pathlib import Path
+
+import pyarrow.parquet as pq
+from huggingface_hub import HfApi
+
+OUT = Path("out_gsm")
+PARQUET = OUT / "gsm8k_reasoning_ar.parquet"
+SOURCE = "Ajhesh7/gsm8k-reasoning-SFT-datas"
+MT_MODEL = "ByteDance-Seed/Seed-X-PPO-7B"
+
+CARD = """---
+license: apache-2.0
+language:
+- ar
+- en
+task_categories:
+- text-generation
+tags:
+- arabic
+- reasoning
+- chain-of-thought
+- math
+- gsm8k
+- machine-translated
+size_categories:
+- 100K<n<1M
+dataset_info:
+  features:
+  - name: text
+    dtype: string
+  - name: question
+    dtype: string
+  - name: thinking
+    dtype: string
+  - name: answer
+    dtype: string
+  - name: question_en
+    dtype: string
+  - name: thinking_en
+    dtype: string
+  - name: source_index
+    dtype: int64
+  splits:
+  - name: train
+    num_examples: {rows}
+configs:
+- config_name: default
+  data_files:
+  - split: train
+    path: data/train-*
+---
+
+# GSM8K Reasoning — Arabic (مترجم آليًا)
+
+**{rows:,}** grade-school math reasoning items translated from English into Arabic with
+[`{mt}`](https://huggingface.co/{mt}), a 7B translation model.
+
+Source: [`{source}`](https://huggingface.co/datasets/{source}) (600,000 rows).
+
+> **بالعربية:** مجموعة بيانات للاستدلال الرياضي بالعربية، مترجمة آليًا من الإنجليزية.
+> كل مثال يحتوي على سؤال، وخطوات التفكير، والإجابة النهائية.
+
+## Format
+
+`text` keeps the source's tag layout, with Arabic content:
+
+```
+<question>يجمع فريا 168 صندوقًا وجمعت هانا 19 صندوقًا...</question> <thinking>دعونا نفكر خطوة بخطوة...</thinking> <answer>187</answer>
+```
+
+The parts are also available as separate columns — `question`, `thinking`, `answer` (Arabic;
+`answer` is the untouched numeral) — with `question_en` / `thinking_en` carrying the English
+source so every row is auditable, and `source_index` pointing back into the source dataset.
+
+## How it was built
+
+1. **Sampling.** {selected:,} of the 600,000 source rows. The corpus is generated from only
+   **2,814** underlying question patterns (numbers and names masked), so the sample is stratified
+   by pattern with a floor of {floor} rows per pattern — every pattern is represented rather than
+   over-weighting the common ones.
+2. **Translation.** Question and reasoning translated separately, each as its own sentence, with
+   `Translate the following English sentence into Arabic:\\n{{text}} <ar>` and greedy decoding.
+   Numbers and names were left in place rather than masked, so Arabic gender agreement follows the
+   actual name (`اشترت` for Aisha) and number agreement follows the actual quantity. The final
+   `answer` numeral is never sent to the translator.
+3. **Validation.** A row is kept only if, for **both** segments, the numbers in the Arabic exactly
+   match the English (order-insensitive), the output is non-empty Arabic script, has no degenerate
+   repetition loop, and has no significant Latin-script residue. **{kept_pct:.2f}%** of translated
+   rows passed.
+
+Rejection breakdown: `{rejects}`
+
+## Limitations
+
+This is **machine translation**, not human-verified Arabic. It inherits the source's synthetic,
+templated phrasing — {selected:,} rows expand from 2,814 patterns, so linguistic diversity is far
+lower than the row count suggests.
+
+**Gender agreement.** The English source pairs names with pronouns arbitrarily ("This week Emil
+did chores and earned $76. **She** bought a bottle…"), which English mostly hides but Arabic does
+not: a row can read `قام جورج …` and then `اشترت …` for the same person. The translator rendered
+the source faithfully; the disagreement is upstream, and it is visible throughout. The arithmetic itself is copied from the source and was not
+re-verified; in the source, the reasoning's final number agrees with the `answer` field ~96.6% of
+the time, so a small fraction of items are internally inconsistent. Suitable for SFT on reasoning
+*format* and basic Arabic math phrasing; not a benchmark.
+"""
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--repo", default="oddadmix/gsm8k-reasoning-ar")
+    ap.add_argument("--dry-run", action="store_true")
+    args = ap.parse_args()
+
+    stats = json.loads((OUT / "build_stats.json").read_text(encoding="utf-8"))
+    rows = pq.ParquetFile(PARQUET).metadata.num_rows
+    floor = max(1, stats["selected"] // (2814 * 4))
+
+    card = CARD.format(
+        rows=rows, mt=MT_MODEL, source=SOURCE, selected=stats["selected"],
+        kept_pct=stats["kept_pct"], rejects=stats["rejects"], floor=floor,
+    )
+    (OUT / "README.md").write_text(card, encoding="utf-8")
+    print(f"[+] wrote card ({len(card)} chars), {rows} rows")
+
+    if args.dry_run:
+        print("[dry-run] not pushing")
+        return
+
+    api = HfApi()
+    api.create_repo(args.repo, repo_type="dataset", private=True, exist_ok=True)
+    api.upload_file(path_or_fileobj=str(PARQUET), path_in_repo="data/train-00000-of-00001.parquet",
+                    repo_id=args.repo, repo_type="dataset")
+    api.upload_file(path_or_fileobj=str(OUT / "README.md"), path_in_repo="README.md",
+                    repo_id=args.repo, repo_type="dataset")
+    for script in ("gsm_common.py", "translate_gsm.py", "build_dataset.py"):
+        api.upload_file(path_or_fileobj=script, path_in_repo=f"scripts/{script}",
+                        repo_id=args.repo, repo_type="dataset")
+    print(f"[+] https://huggingface.co/datasets/{args.repo}")
+
+
+if __name__ == "__main__":
+    main()

code/push_release.py

@@ -0,0 +1,321 @@
+"""
+Public release of the v6 weights as **oddadmix/Nawah-Math-Reasoning**.
+
+This is `push_model_v6.py` retargeted at a public repo under the release name. The differences
+that matter:
+
+  * `private=False` — this is the release, unlike every rung of the v1→v6 ladder.
+  * The card is written for someone who has never seen the ladder. v1–v5 stay private, so the
+    comparison table names them but does not link them, and the text does not send readers to
+    repos they cannot open.
+  * The training code ships **inside the repo** under `code/`, so the recipe and the weights are
+    one link. `code/README.md` is generated by `build_release_code.py`.
+
+Every number in the card is still read from an eval file on disk — nothing is typed by hand:
+
+    Nawah-Reasoning-v6/eval_reasoning.json   v6 on the 1,800-row v6 mix eval (by_source, 4 sources)
+    Nawah-Reasoning-v6/eval_on_synth.json    v6 on the same 1,000-row synth set v4/v5 used
+    Nawah-Reasoning-v5/eval_reasoning.json   v5 on the 1,400-row v5 mix eval
+    Nawah-Reasoning-v5/eval_on_synth.json    v5, same 1,000 synth rows
+    Nawah-Reasoning-v5/eval_on_rel.json      v5 on v6's 400 held-out relational rows (the baseline)
+    Nawah-Reasoning-v4/eval_on_mix.json      v4 on v3's mix eval
+    Nawah-Reasoning-v4/eval_on_synth.json    v4, same 1,000 synth rows
+    Nawah-Reasoning-v3/eval_reasoning.json   v3 on the same mix eval
+    Nawah-Reasoning-v3/eval_on_synth.json    v3, same 1,000 synth rows
+
+Usage: python push_release.py [--repo oddadmix/Nawah-Math-Reasoning] [--dry-run] [--no-code]
+"""
+import argparse
+import json
+from pathlib import Path
+
+from huggingface_hub import HfApi
+
+MODEL_DIR = Path("./Nawah-Reasoning-v6")
+V5_DIR = Path("./Nawah-Reasoning-v5")
+V4_DIR = Path("./Nawah-Reasoning-v4")
+V3_DIR = Path("./Nawah-Reasoning-v3")
+CODE_DIR = Path("./release_code")
+BASE = "oddadmix/50M-2048-Emhotob"
+DEMO = "oddadmix/Nawah-Math-Reasoning-Demo"
+
+CARD = """---
+license: apache-2.0
+language:
+- ar
+base_model: {base}
+datasets:
+- oddadmix/arabic-math-reasoning-synth
+- oddadmix/gsm8k-reasoning-ar
+- Omartificial-Intelligence-Space/Arabic_Reasoning_Dataset
+library_name: transformers
+pipeline_tag: text-generation
+tags:
+- arabic
+- reasoning
+- chain-of-thought
+- math
+- gsm8k
+- small-language-model
+- slm
+- llama
+- sft
+---
+
+# Nawah-Math-Reasoning — نموذج استدلال رياضي عربي
+
+A **{params:.1f}M-parameter** Arabic math reasoning model. It writes its derivation step by step
+inside `<think>…</think>`, then gives the answer. It is small enough to run on a CPU.
+
+> **بالعربية:** نموذج عربي صغير (~{params:.0f} مليون معامل) لحل المسائل الحسابية: يكتب خطوات
+> تفكيره داخل وسم `<think>` ثم يعطي الإجابة. صغير بما يكفي ليعمل على المعالج (CPU).
+
+| | |
+|---|---|
+| 🤗 **Demo** | [`{demo}`](https://huggingface.co/spaces/{demo}) |
+| 🧩 **Base model** | [`{base}`](https://huggingface.co/{base}) — Llama architecture, 12 layers, hidden 512, 2048 ctx, pre-trained from scratch on ~20B Arabic tokens |
+| 📚 **Data** | [`arabic-math-reasoning-synth`](https://huggingface.co/datasets/oddadmix/arabic-math-reasoning-synth) · [`gsm8k-reasoning-ar`](https://huggingface.co/datasets/oddadmix/gsm8k-reasoning-ar) · [`Arabic_Reasoning_Dataset`](https://huggingface.co/datasets/Omartificial-Intelligence-Space/Arabic_Reasoning_Dataset) |
+| 🛠️ **Training code** | [`code/`](https://huggingface.co/{repo}/tree/main/code) in this repo — data generation, translation, SFT, eval, GRPO |
+| 🔤 **Vocab** | {vocab} (4 chat/reasoning tokens added to the 32000 base vocab) |
+
+## Results
+
+Number agreement, greedy decoding. **Every cell is measured on identical held-out rows.** The
+`Arabic_Reasoning` and `GSM8K-ar` rows are the eval splits fixed at the start of the project and
+never re-drawn; the synthetic rows are pinned to the same 1,000 items every earlier version was
+scored on.
+
+The `v3 / v4 / v5` columns are internal development runs, kept here because they are what makes
+the release number mean something. They are not published — the numbers are, so the ablation is
+readable without them.
+
+| eval set | n | v3 | v4 | v5 | **release** |
+|---|---:|---:|---:|---:|---:|
+| GSM8K-ar | {g_n} | {v3_gsm:.1f}% | {v4_gsm:.1f}% | {v5_gsm:.1f}% | **{v6_gsm:.1f}%** |
+| Arabic_Reasoning | {a_n} | {v3_ar:.1f}% | {v4_ar:.1f}% | **{v5_ar:.1f}%** | {v6_ar:.1f}% |
+| synthetic math | 1000 | {v3_synth:.1f}% | {v4_synth:.1f}% | {v5_synth:.1f}% | **{v6_synth:.1f}%** |
+| **synthetic relational** | {r_n} | — | — | {v5_rel:.1f}% | **{v6_rel:.1f}%** |
+
+**The relational row is what this release adds.** On problems whose difficulty is the *relation*
+between quantities (`ضعف`, `نصف`, `أكثر بـ…`) rather than the arithmetic, it scores
+**{v6_rel:.1f}%** where the previous run scores {v5_rel:.1f}% — a **{rel_gain:+.1f} point** gain and
+the largest single-cell move anywhere in the development ladder. It did not cost the other
+distributions: GSM8K-ar is simultaneously the best of the series at **{v6_gsm:.1f}%**, and
+synthetic math gains {synth_delta:+.1f}.
+
+The one regression is `Arabic_Reasoning` at **{ar_delta:+.1f}** against v5 — on {a_n} rows that is
+close to sampling noise, but it is the second consecutive mix where this column is the give.
+
+| detail | GSM8K-ar | Arabic_Reasoning | synth math | synth relational |
+|---|---:|---:|---:|---:|
+| final-answer number correct | {g_primary:.1f}% | {a_primary:.1f}% | {s_primary:.1f}% | {r_primary:.1f}% |
+| all numbers match | {v6_gsm:.1f}% | {v6_ar:.1f}% | {s_nums:.1f}% | {v6_rel:.1f}% |
+| well-formed `<think>` + answer | {g_well:.1f}% | {a_well:.1f}% | {s_well:.1f}% | {r_well:.1f}% |
+| mean reasoning length | {g_tokens:.0f} tok | {a_tokens:.0f} tok | {s_tokens:.0f} tok | {r_tokens:.0f} tok |
+
+*(the synth-math column here is the 400-row mix cell; the {v6_synth:.1f}% in the table above is the
+1,000-row set used for the cross-model comparison.)*
+
+Reproduce any cell with `code/eval_reasoning.py` — it is the same script for every model and every
+row, which is the only reason these are comparable.
+
+### The final checkpoint ships, and eval loss disagrees
+
+Loss bottoms at **{best_loss:.4f}** (epoch {best_epoch:.2f}) and rises to **{shipped_loss:.4f}** by
+epoch {epochs} — yet the epoch-{epochs} weights are the better model. This was measured directly on
+an earlier run whose corpus contained **no repeated rows**, which rules out memorisation: the
+minimum-loss checkpoint scored 30.9% where the final scored 35.6%. It happened on four consecutive
+runs. `train_reasoning.py` therefore takes `LOAD_BEST=0`, and that is not an oversight.
+
+## Training mix
+
+{train_n:,} rows, {tok_per_epoch:.1f}M tokens/epoch:
+
+| source | rows | tokens/epoch | share |
+|---|---:|---:|---:|
+| [`oddadmix/arabic-math-reasoning-synth`](https://huggingface.co/datasets/oddadmix/arabic-math-reasoning-synth) | {synth_rows:,} | {synth_tok:.2f}M | {synth_share:.1f}% |
+| [`oddadmix/gsm8k-reasoning-ar`](https://huggingface.co/datasets/oddadmix/gsm8k-reasoning-ar) | {gsm_rows:,} | {gsm_tok:.2f}M | {gsm_share:.1f}% |
+| [`Omartificial-Intelligence-Space/Arabic_Reasoning_Dataset`](https://huggingface.co/datasets/Omartificial-Intelligence-Space/Arabic_Reasoning_Dataset) | {ar_rows:,} (5,536 × 3) | {ar_tok:.2f}M | {ar_share:.1f}% |
+
+Of the synthetic corpus's {corpus_rows:,} rows, {rel_rows:,} are **relational** problems generated
+specifically for this release, after a `pass@k` diagnostic showed the previous model went 0/8 on
+`ضعف`-style problems and a corpus audit found the relation appears in only 1.34% of rows. The
+synthetic eval split was **pinned, not re-drawn** when those rows were added: re-shuffling would
+have moved 1,955 of the 2,000 previously held-out items into train, turning that column into a
+memorisation score.
+
+Full fine-tune from the base (not from the previous version). Loss on the assistant turn only, user
+prompt masked with `-100`. `Arabic_Reasoning` is ~25× smaller than GSM8K, so it is repeated 3×.
+
+| | |
+|---|---|
+| epochs | {epochs} ({steps:,} steps) |
+| effective batch | 64 |
+| learning rate | 3e-4 cosine, 200 warmup steps |
+| max length | 768 tokens (mix p100 is {p100} — nothing truncated) |
+| precision | bf16 |
+| checkpoint | final (`load_best_model_at_end` disabled — it picks the worse model) |
+| hardware | 1× RTX A6000, ~{minutes} min |
+
+## Usage
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+import torch
+
+model_id = "{repo}"
+tok = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(model_id, dtype=torch.bfloat16).eval()
+
+messages = [{{"role": "user", "content": "اشترى خالد 4 دفاتر بسعر 15 جنيهًا للدفتر، ودفع بورقة 100 جنيه. كم المبلغ المتبقي؟"}}]
+prompt = tok.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+ids = tok(prompt, return_tensors="pt")
+
+out = model.generate(**ids, max_new_tokens=384, do_sample=False)
+print(tok.decode(out[0][ids["input_ids"].shape[1]:], skip_special_tokens=False))
+```
+
+Split the parts with `re.match(r"\\s*<think>(.*?)</think>(.*)", completion, re.S)`.
+Decode with `skip_special_tokens=False` — `<think>` and `</think>` are real tokens in this
+tokenizer, and stripping them destroys the split.
+
+It is **single-turn**: one user message per call. Chat history is out of distribution.
+
+**Answer style is not something you can request.** The three corpora disagree — GSM8K rows end in a
+bare numeral, the other two in an `إذن، …` sentence — and arithmetic word problems look alike in
+all of them, so the model picks a style per prompt. **Score it on number agreement, not exact
+string match**, and parse the answer by extracting its numbers.
+
+## Limitations
+
+At ~{params:.0f}M parameters this is a **proof of concept**, and the honest headline is the
+synthetic columns — **{v6_synth:.1f}%** and **{v6_rel:.1f}%** on multi-step problems, well below the
+{v6_gsm:.1f}% it scores on GSM8K's narrower phrasing. Arithmetic is the dominant failure mode: the
+reasoning is usually structurally right, one computation step is wrong, and the model then stays
+faithful to its own bad number.
+
+Each corpus brings its own defect. The GSM8K half is machine-translated, its 140,969 rows expanding
+from only 2,814 question patterns, so that score partly reflects narrow phrasing. The synthetic
+half is verified for **arithmetic, not for sense** — rows survive where every equation checks out
+but a step introduces an entity never mentioned, or the answer resolves the reverse of what was
+asked. The `Arabic_Reasoning` half excludes open-ended expository rows (they have no final answer
+to place after `</think>`), so expository prompts remain out of distribution.
+
+Everything is MSA; the synthetic corpus's region axis sets currency and context, not dialect. The
+Arabic inherits source artifacts including inconsistent gender agreement. Its reasoning trace is
+not a faithful account of any internal computation. Do not use it for anything consequential.
+
+## Citation
+
+```bibtex
+@misc{{nawah_math_reasoning_2026,
+  title  = {{Nawah-Math-Reasoning: a 52M-parameter Arabic chain-of-thought math model}},
+  author = {{Ahmed Wasfy}},
+  year   = {{2026}},
+  url    = {{https://huggingface.co/{repo}}}
+}}
+```
+"""
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--repo", default="oddadmix/Nawah-Math-Reasoning")
+    ap.add_argument("--dry-run", action="store_true")
+    ap.add_argument("--no-code", action="store_true", help="skip the code/ upload")
+    ap.add_argument("--minutes", default="85")
+    args = ap.parse_args()
+
+    def summary(p):
+        return json.loads(Path(p).read_text(encoding="utf-8"))["summary"]
+
+    v6 = summary(MODEL_DIR / "eval_reasoning.json")
+    v6_synth = summary(MODEL_DIR / "eval_on_synth.json")
+    v5_mix = summary(V5_DIR / "eval_reasoning.json")
+    v5_synth = summary(V5_DIR / "eval_on_synth.json")
+    v5_rel = summary(V5_DIR / "eval_on_rel.json")
+    v4_mix, v4_synth = summary(V4_DIR / "eval_on_mix.json"), summary(V4_DIR / "eval_on_synth.json")
+    v3_mix, v3_synth = summary(V3_DIR / "eval_reasoning.json"), summary(V3_DIR / "eval_on_synth.json")
+
+    g, a, s, r = (v6["by_source"]["gsm8k_ar"], v6["by_source"]["arabic_reasoning"],
+                  v6["by_source"]["synth_math_ar"], v6["by_source"]["synth_relational_ar"])
+
+    tm = json.loads(Path(MODEL_DIR, "train_metrics.json").read_text(encoding="utf-8"))
+    cfg = json.loads(Path(MODEL_DIR, "config.json").read_text(encoding="utf-8"))
+    evals = [h for h in tm["log_history"] if "eval_loss" in h]
+    last = max(h["step"] for h in evals)
+    shipped_loss = next(h["eval_loss"] for h in evals if h["step"] == last)
+    best = min(evals, key=lambda h: h["eval_loss"])
+
+    v3_gsm, v4_gsm, v5_gsm = (v3_mix["by_source"]["gsm8k_ar"], v4_mix["by_source"]["gsm8k_ar"],
+                              v5_mix["by_source"]["gsm8k_ar"])
+    v3_ar, v4_ar, v5_ar = (v3_mix["by_source"]["arabic_reasoning"],
+                           v4_mix["by_source"]["arabic_reasoning"],
+                           v5_mix["by_source"]["arabic_reasoning"])
+
+    # measured from data_v6_sft/train.jsonl with the base tokenizer (+12 tok/row of chat scaffold)
+    MIX = {"synth_math_ar": (118062, 16.79, 53.9), "gsm8k_ar": (140969, 11.88, 38.2),
+           "arabic_reasoning": (16608, 2.45, 7.9)}
+
+    card = CARD.format(
+        repo=args.repo, base=BASE, demo=DEMO, params=51.79, vocab=cfg["vocab_size"],
+        g_n=g["n"], a_n=a["n"], r_n=r["n"],
+        v3_gsm=v3_gsm["numbers_match_pct"], v4_gsm=v4_gsm["numbers_match_pct"],
+        v5_gsm=v5_gsm["numbers_match_pct"], v6_gsm=g["numbers_match_pct"],
+        v3_ar=v3_ar["numbers_match_pct"], v4_ar=v4_ar["numbers_match_pct"],
+        v5_ar=v5_ar["numbers_match_pct"], v6_ar=a["numbers_match_pct"],
+        v3_synth=v3_synth["numbers_match_pct"], v4_synth=v4_synth["numbers_match_pct"],
+        v5_synth=v5_synth["numbers_match_pct"], v6_synth=v6_synth["numbers_match_pct"],
+        v5_rel=v5_rel["numbers_match_pct"], v6_rel=r["numbers_match_pct"],
+        rel_gain=r["numbers_match_pct"] - v5_rel["numbers_match_pct"],
+        ar_delta=a["numbers_match_pct"] - v5_ar["numbers_match_pct"],
+        synth_delta=v6_synth["numbers_match_pct"] - v5_synth["numbers_match_pct"],
+        g_primary=g["primary_number_match_pct"], a_primary=a["primary_number_match_pct"],
+        s_primary=s["primary_number_match_pct"], r_primary=r["primary_number_match_pct"],
+        s_nums=s["numbers_match_pct"],
+        g_well=g["well_formed_pct"], a_well=a["well_formed_pct"],
+        s_well=s["well_formed_pct"], r_well=r["well_formed_pct"],
+        g_tokens=g["mean_reasoning_tokens"], a_tokens=a["mean_reasoning_tokens"],
+        s_tokens=s["mean_reasoning_tokens"], r_tokens=r["mean_reasoning_tokens"],
+        best_loss=best["eval_loss"], best_epoch=best["epoch"], shipped_loss=shipped_loss,
+        epochs=round(max(h.get("epoch", 0) for h in tm["log_history"])),
+        steps=max(h.get("step", 0) for h in tm["log_history"]),
+        train_n=sum(v[0] for v in MIX.values()),
+        tok_per_epoch=sum(v[1] for v in MIX.values()),
+        synth_rows=MIX["synth_math_ar"][0], synth_tok=MIX["synth_math_ar"][1],
+        synth_share=MIX["synth_math_ar"][2],
+        gsm_rows=MIX["gsm8k_ar"][0], gsm_tok=MIX["gsm8k_ar"][1], gsm_share=MIX["gsm8k_ar"][2],
+        ar_rows=MIX["arabic_reasoning"][0], ar_tok=MIX["arabic_reasoning"][1],
+        ar_share=MIX["arabic_reasoning"][2],
+        corpus_rows=120462, rel_rows=20139, p100=703, minutes=args.minutes,
+    )
+    out = Path("release_README.md")
+    out.write_text(card, encoding="utf-8")
+    print(f"[+] wrote {out} ({len(card)} chars)")
+
+    if args.dry_run:
+        print("[dry-run] not pushing")
+        return
+
+    api = HfApi()
+    api.create_repo(args.repo, private=False, exist_ok=True)
+
+    # Weights first, then the card, so the repo is never public-and-uncarded for long.
+    api.upload_folder(
+        folder_path=str(MODEL_DIR), repo_id=args.repo,
+        ignore_patterns=["checkpoint-*/*", "checkpoint-*", "eval_on_*.json", "README.md"],
+        commit_message="Nawah-Math-Reasoning: weights, tokenizer, eval + training metrics")
+    api.upload_file(path_or_fileobj=str(out), path_in_repo="README.md", repo_id=args.repo,
+                    commit_message="model card")
+
+    if not args.no_code:
+        if not CODE_DIR.is_dir():
+            raise SystemExit(f"{CODE_DIR} missing — run build_release_code.py first")
+        api.upload_folder(folder_path=str(CODE_DIR), repo_id=args.repo, path_in_repo="code",
+                          commit_message="training code: data generation, SFT, eval, GRPO")
+
+    print(f"[+] https://huggingface.co/{args.repo}")
+
+
+if __name__ == "__main__":
+    main()

code/push_synth_dataset.py

@@ -0,0 +1,200 @@
+"""
+Push the synthetic Arabic math-reasoning corpus to the Hub as a PRIVATE dataset with a card.
+
+Usage: python push_synth_dataset.py [--repo oddadmix/arabic-math-reasoning-synth] [--dry-run]
+"""
+import argparse
+import collections
+import json
+import os
+from pathlib import Path
+
+import pyarrow.parquet as pq
+from huggingface_hub import HfApi
+
+OUT_DIR = Path(os.environ.get("OUT_DIR", "out_synth"))
+PARQUET = OUT_DIR / "arabic_math_reasoning_synth.parquet"
+
+# Hub ids for the generators, keyed by the `model` field the nodes record per row.
+GEN_MODEL_HUB = {
+    "gemma-3-12b-it": "google/gemma-3-12b-it",
+    "Qwen3.6-27B-NVFP4": "nvidia/Qwen3.6-27B-NVFP4",
+    "Qwen3.8-27B-Uncensored-NVFP4": "orcarouter/Qwen3.8-27B-Uncensored-NVFP4",
+}
+
+CARD = """---
+license: apache-2.0
+language:
+- ar
+size_categories:
+- {size_cat}
+task_categories:
+- text-generation
+tags:
+- arabic
+- math
+- reasoning
+- chain-of-thought
+- gsm8k
+- synthetic
+configs:
+- config_name: default
+  data_files:
+  - split: train
+    path: arabic_math_reasoning_synth.parquet
+---
+
+# Arabic Math Reasoning (synthetic) — مسائل رياضيات عربية مع خطوات الحل
+{status_note}
+**{n:,}** Arabic grade-school math word problems, each with a step-by-step derivation and a
+concluding sentence. Generated with {gen_blurb} and
+**arithmetically verified** — every equation the reasoning states was re-evaluated, and rows whose
+own arithmetic does not check out were dropped.
+
+{gen_table}
+
+> **بالعربية:** {n:,} مسألة حسابية عربية مع خطوات حل مفصّلة وجملة إجابة نهائية. جميع المعادلات
+> داخل خطوات الحل تم التحقق منها حسابيًا، والصفوف التي تحتوي على خطأ حسابي مستبعدة.
+
+## Schema
+
+| field | description |
+|---|---|
+| `instruction` | the word problem, ending in a question |
+| `reasoning` | numbered derivation, each step containing an explicit equation |
+| `answer` | one concluding sentence (`إذن، …`) carrying the final number and its unit |
+| `axis_*` | the variation axes this item was drawn from (domain, operation, steps, numbers, region, twist) |
+| `task_id` | the generation task it came from |
+| `gen_model` | which model generated the row |
+
+It matches the `{{instruction, reasoning, answer}}` schema used by the Nawah-Reasoning training
+scripts, so it drops straight into ChatML + `<think>` SFT.
+
+## How it was built
+
+Prompts are drawn from a **variation grid** — {n_domains} domains × {n_ops} operation types ×
+step counts × number styles × {n_regions} country/currency pairs × {n_twists} structural twists —
+seeded deterministically from the task index. This is a deliberate reaction to the corpus this was
+built to supplement: a machine-translated Arabic GSM8K whose {gsm_rows:,} rows expand from only
+2,814 underlying question templates. Here, **{templates:,}** distinct templates survive
+number-masked deduplication.
+{pool_note}
+
+### Verification
+
+Generated math is fluent and often wrong, so acceptance is mechanical rather than stylistic:
+
+1. every `a op b = c` in the reasoning is re-evaluated with real arithmetic — one bad equation
+   rejects the row;
+2. the number in the answer sentence must equal the last computed result (a chain that is
+   internally correct but ends on a different number is the failure that survives fluency checks);
+3. no Latin characters, length bounds, and the answer must open with a conclusion marker.
+
+**{accept_rate:.1%}** of parsed items passed. Rejections:
+
+{reject_table}
+
+`out_synth/rejects.jsonl` in the source repo keeps every rejected item with its reason, so the
+filter itself can be audited.
+
+## Limitations
+
+This is **synthetic** data: the problems are machine-written and reflect that model's habits of
+phrasing, its distribution of scenarios, and its idea of what a "typical" Arabic math problem
+looks like. Verification proves each row's arithmetic is self-consistent — it does **not** prove
+the problem is well-posed, that the setup is the only reasonable reading, or that the wording is
+natural to any particular dialect region (the `axis_region` field sets currency and context, not
+dialect; everything is MSA). Rows whose reasoning states no explicit equation are dropped, which
+biases the corpus toward problems that decompose into clean arithmetic steps.
+"""
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--repo", default="oddadmix/arabic-math-reasoning-synth")
+    ap.add_argument("--target", type=int, default=100_000)
+    ap.add_argument("--dry-run", action="store_true")
+    args = ap.parse_args()
+
+    import synth_common as sc
+
+    n = pq.read_metadata(PARQUET).num_rows
+    stats = json.loads((OUT_DIR / "build_stats.json").read_text(encoding="utf-8"))
+
+    # Credit every generator that actually contributed, from the build's own per-model counts.
+    by_model = collections.Counter({k[len("model_"):]: v
+                                    for k, v in stats["stats"].items() if k.startswith("model_")})
+    def _link(name):
+        hub = GEN_MODEL_HUB.get(name)
+        return f"[`{name}`](https://huggingface.co/{hub})" if hub else f"`{name}`"
+    names = [m for m, _ in by_model.most_common()]
+    gen_blurb = " and ".join(filter(None, [", ".join(_link(m) for m in names[:-1]),
+                                           _link(names[-1])])) if names else "an unrecorded model"
+    gen_table = ("| generator | rows | share |\n|---|---:|---:|\n" + "\n".join(
+        f"| {_link(m)} | {c:,} | {100 * c / max(n, 1):.1f}% |"
+        for m, c in by_model.most_common())) if len(names) > 1 else ""
+    total_rejects = max(sum(stats["reject_reasons"].values()), 1)
+    folded = collections.Counter()
+    for k, v in stats["reject_reasons"].items():
+        folded[k.split(":", 1)[0]] += v
+    reject_table = "| reason | count | share of rejects |\n|---|---:|---:|\n" + "\n".join(
+        f"| `{k}` | {v:,} | {100 * v / total_rejects:.1f}% |"
+        for k, v in folded.most_common(8))
+
+    if n < args.target:
+        status_note = (
+            f"\n> ⚠️ **Interim snapshot — generation is still running.** This is "
+            f"{n:,} of a planned {args.target:,} rows, published early so it can be reviewed and "
+            f"trained against. Rows are only ever *appended*: the generator is resumable and "
+            f"deterministic per task index, so everything here stays in the finished corpus "
+            f"unchanged. Expect this repo to be overwritten with a larger version.\n")
+    else:
+        status_note = ""
+
+    # The relational pool (task ids from 1,000,000) is a second, disjoint operation set added
+    # after the first 100,323 rows shipped. Count it from the data rather than asserting it.
+    n_rel = sum(1 for tid in pq.read_table(PARQUET, columns=["task_id"]).column("task_id").to_pylist()
+                if tid >= 1_000_000)
+    pool_note = ("""
+The operation axis is drawn from **two disjoint pools**. The first {n_default:,} rows use 15
+general operations (totals, percentages, unit rates, remainders, …). A later pass added a
+**relational pool** of 8 operations — *ضعف* / *أضعاف*, *نصف*, *ثلث* و *ربع*, absolute increase and
+decrease, three-way chains, and the inverse direction — contributing **{n_rel:,}** rows. These
+express a quantity *relative to another entity* ("Ziad bought **double that number**"), which
+forces a derivation step that a percentage problem does not. In the original corpus *ضعف /
+أضعاف* appeared in 1.34% of rows and *أكثر بـ / أقل بـ* in 0.26% — against 17.6% for percentages —
+and that gap is the documented weak spot of models trained on it, so the pool was generated
+deliberately rather than left to the grid.
+""".format(n_rel=n_rel, n_default=n - n_rel) if n_rel else "")
+
+    size_cat = "100K<n<1M" if n >= 100_000 else "10K<n<100K" if n >= 10_000 else "1K<n<10K"
+    card = CARD.format(
+        n=n, gen_blurb=gen_blurb, gen_table=gen_table, size_cat=size_cat,
+        n_domains=len(sc.DOMAINS), n_ops=stats["axis_coverage"]["op"], n_regions=len(sc.REGIONS),
+        n_twists=len(sc.TWISTS), gsm_rows=142_969,
+        templates=stats["unique_templates"], accept_rate=stats["accept_rate"],
+        status_note=status_note,
+        reject_table=reject_table,
+        pool_note=pool_note,
+    )
+    (OUT_DIR / "README.md").write_text(card, encoding="utf-8")
+    print(f"[+] wrote card ({len(card)} chars) | {n:,} rows | accept {stats['accept_rate']:.1%}")
+
+    if args.dry_run:
+        print("[dry-run] not pushing")
+        return
+
+    api = HfApi()
+    api.create_repo(args.repo, repo_type="dataset", private=True, exist_ok=True)
+    api.upload_file(path_or_fileobj=str(PARQUET), path_in_repo=PARQUET.name,
+                    repo_id=args.repo, repo_type="dataset")
+    api.upload_file(path_or_fileobj=str(OUT_DIR / "README.md"), path_in_repo="README.md",
+                    repo_id=args.repo, repo_type="dataset")
+    for script in ("synth_common.py", "synth_generate.py", "build_synth_dataset.py"):
+        api.upload_file(path_or_fileobj=script, path_in_repo=script,
+                        repo_id=args.repo, repo_type="dataset")
+    print(f"[+] https://huggingface.co/datasets/{args.repo}")
+
+
+if __name__ == "__main__":
+    main()

code/retry_failed.py

@@ -0,0 +1,102 @@
+"""
+Second pass over segments whose greedy translation failed validation.
+
+Two recovery strategies, tried in order, keeping the first candidate that validates:
+  1. beam search (beam_width=4) — what the Seed-X authors recommend
+  2. sampled best-of-8 — a different part of the distribution when beam search repeats the error
+
+Recovered translations are appended to the cache, overriding the greedy result.
+"""
+import json
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, ".")
+from build_dataset import check
+from gsm_common import SRC_PROMPT
+
+OUT = Path("out_gsm")
+CACHE = OUT / "translations.jsonl"
+MODEL = "./models/Seed-X-PPO-7B"
+
+
+def load():
+    trans = {}
+    with open(CACHE, encoding="utf-8") as fh:
+        for line in fh:
+            try:
+                r = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            trans[r["src"]] = r["tgt"]
+    rows = [json.loads(l) for l in open(OUT / "selected_rows.jsonl", encoding="utf-8")]
+    kind = {}
+    for r in rows:
+        kind.setdefault(r["question"], "question")
+        kind.setdefault(r["thinking"], "thinking")
+    return trans, kind
+
+
+def main():
+    trans, kind = load()
+    failed = [
+        s for s, t in trans.items()
+        if check(s, t, strict=(kind.get(s) == "thinking")) is not None
+    ]
+    print(f"[*] {len(failed)}/{len(trans)} segments failed validation ({len(failed)/len(trans):.2%})")
+    if not failed:
+        return
+
+    from vllm import LLM, SamplingParams
+    from vllm.sampling_params import BeamSearchParams
+
+    llm = LLM(model=MODEL, max_num_seqs=256, gpu_memory_utilization=0.92, max_model_len=1024)
+    prompts = [SRC_PROMPT.format(text=s) for s in failed]
+    recovered = {}
+
+    # Beam search is disabled by default: vLLM 0.8.5 runs it as a Python-level loop and it took
+    # >50 min on ~4.8k segments without finishing, versus ~2 min for the batched sampling path
+    # below. Set RETRY_BEAM=1 to use it anyway.
+    if os.environ.get("RETRY_BEAM") == "1":
+        print("[*] pass 1: beam search")
+        outs = llm.beam_search([{"prompt": p} for p in prompts], BeamSearchParams(beam_width=4, max_tokens=256))
+        still = []
+        for src, o in zip(failed, outs):
+            strict = kind.get(src) == "thinking"
+            for seq in o.sequences:
+                cand = seq.text.strip()
+                if check(src, cand, strict=strict) is None:
+                    recovered[src] = cand
+                    break
+            else:
+                still.append(src)
+        print(f"    recovered {len(recovered)}, still failing {len(still)}")
+    else:
+        print("[*] pass 1: skipped (beam search disabled)")
+        still = list(failed)
+
+    if still:
+        print("[*] pass 2: sampled best-of-8")
+        params = SamplingParams(n=8, temperature=0.8, top_p=0.95, max_tokens=256, skip_special_tokens=True)
+        outs = llm.generate([SRC_PROMPT.format(text=s) for s in still], params)
+        final = []
+        for src, o in zip(still, outs):
+            strict = kind.get(src) == "thinking"
+            for cand in o.outputs:
+                text = cand.text.strip()
+                if check(src, text, strict=strict) is None:
+                    recovered[src] = text
+                    break
+            else:
+                final.append(src)
+        print(f"    recovered {len(recovered)} total, unrecoverable {len(final)}")
+
+    with open(CACHE, "a", encoding="utf-8") as fh:
+        for src, tgt in recovered.items():
+            fh.write(json.dumps({"src": src, "tgt": tgt}, ensure_ascii=False) + "\n")
+    print(f"[+] appended {len(recovered)} recovered translations to {CACHE}")
+
+
+if __name__ == "__main__":
+    main()

code/space/README.md

@@ -0,0 +1,76 @@
+---
+title: Nawah Math Reasoning
+emoji: 🧠
+colorFrom: indigo
+colorTo: purple
+sdk: gradio
+sdk_version: 6.26.0
+python_version: '3.12'
+app_file: app.py
+pinned: false
+models:
+- oddadmix/Nawah-Math-Reasoning
+datasets:
+- oddadmix/arabic-math-reasoning-synth
+- oddadmix/gsm8k-reasoning-ar
+short_description: نموذج استدلال رياضي عربي (52M) يفكّر خطوة بخطوة قبل الإجابة
+---
+
+# Nawah-Math-Reasoning — Demo
+
+A **51.8M-parameter** Arabic math reasoning model. It writes its derivation inside
+`<think>…</think>` and then gives the final answer; the demo splits the two live as it streams —
+the reasoning trace in one panel, the answer in the other.
+
+Fine-tuned from [`oddadmix/50M-2048-Emhotob`](https://huggingface.co/oddadmix/50M-2048-Emhotob),
+a Llama-architecture base pre-trained from scratch on ~20B Arabic tokens (12 layers, hidden 512,
+2048 context).
+
+> **بالعربية:** نموذج عربي صغير (~52 مليون معامل) يكتب خطوات تفكيره داخل وسم `<think>` ثم يعطي
+> الإجابة النهائية. الديمو بيفصل الاتنين وانت بتتفرج على النموذج وهو بيكتب.
+
+## Everything is open — Apache 2.0
+
+| | |
+|---|---|
+| 🧠 **Model** | [`oddadmix/Nawah-Math-Reasoning`](https://huggingface.co/oddadmix/Nawah-Math-Reasoning) |
+| 🛠️ **Training code** | [`code/`](https://huggingface.co/oddadmix/Nawah-Math-Reasoning/tree/main/code) — data generation, translation, SFT, eval, GRPO |
+| 📚 **Synthetic corpus** | [`oddadmix/arabic-math-reasoning-synth`](https://huggingface.co/datasets/oddadmix/arabic-math-reasoning-synth) — 120,462 arithmetically verified rows |
+| 📚 **Translated corpus** | [`oddadmix/gsm8k-reasoning-ar`](https://huggingface.co/datasets/oddadmix/gsm8k-reasoning-ar) — 142,969 rows |
+
+## Results
+
+Number agreement, greedy decoding, on held-out splits. Every version of the model was scored on
+identical rows, so the numbers are comparable across the whole development ladder.
+
+| eval set | n | score |
+|---|---:|---:|
+| GSM8K-ar | 600 | **79.0%** |
+| Arabic_Reasoning | 400 | **73.0%** |
+| synthetic math | 1000 | **40.4%** |
+| synthetic relational | 400 | **52.2%** |
+
+The last row is what this release adds: problems where the difficulty is the *relation* between
+quantities (`ضعف`, `نصف`, `أكثر بـ…`) rather than the arithmetic. The previous version scored
+34.0% there — the relation appeared in barely 1.3% of the training corpus, so 20,139 rows were
+generated specifically to fill the gap.
+
+## Limitations
+
+A 52M proof of concept. It reliably produces the *shape* of Arabic step-by-step reasoning, but
+**arithmetic errors are the dominant failure mode** — the derivation is usually structurally
+right, one computation is wrong, and the model then stays faithful to its own bad number. The
+40.4% and 52.2% above are the honest ceiling on multi-step problems. Single-turn only; open-ended
+and non-mathematical questions are out of distribution.
+
+نموذج تجريبي: بيعرف يمشي خطوة خطوة بالعربي، بس بيغلط في الحساب كتير.
+
+Runs on **ZeroGPU**. The model is small enough for CPU too — switch the Space to `cpu-basic` and
+it still works, just slower.
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `MODEL_ID` | Model repo to load (default `oddadmix/Nawah-Math-Reasoning`) |
+| `MODEL_HF_TOKEN` | Only needed if `MODEL_ID` points at a **private** repo. (`HF_TOKEN` is reserved by Spaces and does not reach the container.) |

code/space/app.py

@@ -0,0 +1,222 @@
+"""
+Nawah-Math-Reasoning — Gradio demo.
+
+The prompt rendering (ChatML + BOS prepend) is IDENTICAL to train_reasoning.py. A 51M model
+is very sensitive to format drift, so do not change render_prompt() without changing training.
+
+Runs on ZeroGPU. The model is only ~52M parameters and works on CPU too, but ZeroGPU keeps
+responses snappy. `import spaces` must come BEFORE torch so it can patch the CUDA calls.
+
+The model emits <think>…</think> before its answer, so the stream is split live into two
+panels: the reasoning trace and the final answer.
+
+Deploy: push this + requirements.txt + README.md to a Gradio Space. The released model is
+public, so no token is needed; MODEL_HF_TOKEN is still read for pointing MODEL_ID at a private
+checkpoint.
+"""
+
+import os
+import re
+import threading
+
+import spaces  # import BEFORE torch so it can patch CUDA calls
+import gradio as gr
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer, TextIteratorStreamer
+
+# ── Config ────────────────────────────────────────────────────────────────────
+
+MODEL_ID = os.environ.get("MODEL_ID", "oddadmix/Nawah-Math-Reasoning")
+# Unused for the public release; needed only if MODEL_ID is repointed at a private repo.
+# HF_TOKEN is reserved by Spaces (a secret set under that name does not reach the container),
+# so MODEL_HF_TOKEN is the one to set.
+HF_TOKEN = os.environ.get("MODEL_HF_TOKEN") or os.environ.get("HF_TOKEN")
+
+IM_START, IM_END = "<|im_start|>", "<|im_end|>"
+THINK_OPEN, THINK_CLOSE = "<think>", "</think>"
+MAX_NEW_TOKENS_CAP = 1500
+
+# ── Load (once, at startup) ───────────────────────────────────────────────────
+
+print("[*] token env vars present:",
+      [k for k in ("MODEL_HF_TOKEN", "HF_TOKEN") if os.environ.get(k)] or "NONE")
+print(f"[*] Loading {MODEL_ID} ...")
+tokenizer = AutoTokenizer.from_pretrained(MODEL_ID, token=HF_TOKEN)
+model = AutoModelForCausalLM.from_pretrained(MODEL_ID, dtype=torch.bfloat16, token=HF_TOKEN)
+model.to("cuda").eval()
+
+CTX = getattr(model.config, "max_position_embeddings", 2048)
+
+_eos = {tokenizer.eos_token_id} if tokenizer.eos_token_id is not None else set()
+_im_end = tokenizer.convert_tokens_to_ids(IM_END)
+if isinstance(_im_end, int) and _im_end >= 0:
+    _eos.add(_im_end)
+EOS_IDS = list(_eos) or None
+PAD_ID = tokenizer.pad_token_id if tokenizer.pad_token_id is not None else tokenizer.eos_token_id
+
+print(f"[+] {model.num_parameters():,} params | eos_ids={EOS_IDS} | ctx={CTX}")
+
+# ── Prompt rendering — must match train_reasoning.py ──────────────────────────
+
+def render_prompt(question: str) -> str:
+    # Single-turn only: the model was trained on one user turn per sample, so a chat
+    # history would be out of distribution.
+    return f"{IM_START}user\n{question.strip()}{IM_END}\n{IM_START}assistant\n"
+
+
+STRIP_RE = re.compile(r"<\|im_end\|>|</s>|<pad>|<s>")
+
+
+def split_stream(text: str):
+    """-> (reasoning_so_far, answer_so_far). Handles the partial state mid-stream."""
+    text = STRIP_RE.sub("", text)
+    if THINK_CLOSE in text:
+        reasoning, answer = text.split(THINK_CLOSE, 1)
+        return reasoning.replace(THINK_OPEN, "").strip(), answer.strip()
+    return text.replace(THINK_OPEN, "").strip(), ""
+
+
+# ── Generate ──────────────────────────────────────────────────────────────────
+
+@spaces.GPU(duration=60)
+def solve(question, max_new_tokens, temperature, repetition_penalty):
+    question = (question or "").strip()
+    if not question:
+        yield "", "", ""
+        return
+
+    ids = tokenizer(render_prompt(question), add_special_tokens=False)["input_ids"]
+    if tokenizer.bos_token_id is not None:
+        ids = [tokenizer.bos_token_id] + ids  # match training's explicit BOS
+    input_ids = torch.tensor([ids], device=model.device)
+
+    # skip_special_tokens must stay False — <think>/</think> are real special tokens
+    # in this tokenizer, and stripping them would destroy the split.
+    streamer = TextIteratorStreamer(tokenizer, skip_prompt=True, skip_special_tokens=False)
+
+    kwargs = dict(
+        input_ids=input_ids,
+        attention_mask=torch.ones_like(input_ids),
+        max_new_tokens=int(max_new_tokens),
+        repetition_penalty=float(repetition_penalty),
+        eos_token_id=EOS_IDS,
+        pad_token_id=PAD_ID,
+        streamer=streamer,
+    )
+    if temperature and temperature > 0:
+        kwargs.update(do_sample=True, temperature=float(temperature), top_p=0.95)
+    else:
+        kwargs.update(do_sample=False)  # greedy — how the model was evaluated
+
+    threading.Thread(target=model.generate, kwargs=kwargs).start()
+
+    out = ""
+    for chunk in streamer:
+        out += chunk
+        reasoning, answer = split_stream(out)
+        yield reasoning, (answer or "…"), out
+
+    reasoning, answer = split_stream(out)
+    if not answer:
+        answer = "⚠️ لم يُغلق النموذج وسم التفكير — جرّب سؤالًا أقرب لأمثلة التدريب.\n" \
+                 "(The model never closed `</think>` — try a question closer to its training distribution.)"
+    yield reasoning, answer, out
+
+
+# ── UI ────────────────────────────────────────────────────────────────────────
+
+DESCRIPTION = """
+<div style="text-align:center">
+<h1>🧠 Nawah-Math-Reasoning</h1>
+<p>نموذج استدلال عربي صغير (~52M بارامتر) يفكّر خطوة بخطوة داخل وسم <code>&lt;think&gt;</code>
+ثم يعطي الإجابة النهائية.<br>
+A ~52M-parameter Arabic reasoning model that thinks step by step inside
+<code>&lt;think&gt;</code> before answering.</p>
+<p><i>نموذج صغير بما يكفي ليعمل حتى على المعالج (CPU).<br>
+Small enough to run on a CPU — this Space uses ZeroGPU for snappier responses.</i></p>
+<p>
+<a href="https://huggingface.co/oddadmix/Nawah-Math-Reasoning">Model</a> ·
+<a href="https://huggingface.co/oddadmix/Nawah-Math-Reasoning/tree/main/code">Training code</a> ·
+<a href="https://huggingface.co/datasets/oddadmix/arabic-math-reasoning-synth">Synthetic dataset</a> ·
+<a href="https://huggingface.co/datasets/oddadmix/gsm8k-reasoning-ar">GSM8K-ar dataset</a>
+<br><i>Weights, both datasets and the full training code are open — Apache 2.0.</i>
+</p>
+</div>
+"""
+
+NOTE = """
+### 📊 النتائج / Results
+
+Number agreement, greedy decoding, on held-out splits — the same rows for every version of the
+model, so the numbers are comparable.
+
+| eval set | n | score |
+|---|---:|---:|
+| GSM8K-ar | 600 | **79.0%** |
+| Arabic_Reasoning | 400 | **73.0%** |
+| synthetic math | 1000 | **40.4%** |
+| synthetic relational (`ضعف`, `نصف`, `أكثر بـ…`) | 400 | **52.2%** |
+
+### ⚠️ حدود النموذج / Limitations
+نموذج تجريبي بحجم 52M: يجيد **شكل** الاستدلال العربي ويحلّ مسائل النِّسب والحساب البسيطة،
+لكنه **يخطئ في الحساب كثيرًا** — غالبًا خطوات الحل سليمة ثم تقع غلطة في عملية حسابية واحدة
+ويكمل النموذج على رقمه الخاطئ. الأسئلة المفتوحة وغير الحسابية خارج نطاقه، والحوار متعدد
+الأدوار كذلك.
+
+A 52M proof of concept. It reliably produces the *shape* of Arabic step-by-step reasoning, but
+**arithmetic errors are the dominant failure mode**: the derivation is usually structurally
+right, one computation is wrong, and the model then stays faithful to its own bad number. The
+40.4% and 52.2% above are the honest ceiling on multi-step problems. Single-turn only;
+open-ended and non-mathematical questions are out of distribution.
+"""
+
+EXAMPLES = [
+    "إذا كان لديك 1500 ريال وأنفقت 20% منها على الكتب، فكم تبقى معك؟",
+    "في مصنع تم إنتاج 5000 وحدة، وكانت نسبة الوحدات المعيبة 2%، فما عدد الوحدات السليمة؟",
+    "في مدرسة بها 500 طالب، إذا كانت نسبة الذكور 55%، فما عدد الطالبات؟",
+    "لدى تاجر 240 كيلوغرامًا من الأرز، باع منها 35%، فكم كيلوغرامًا تبقى لديه؟",
+    "إذا كان عمر أحمد 12 سنة وعمر أخيه ضعف عمره، فما مجموع عمريهما؟",
+    "في حديقة 80 حيوانًا، 25% منها طيور، ونصف الطيور بيضاء. كم عدد الطيور البيضاء؟",
+    "جمع سامي 45 صدفة، وجمع أخوه ضعف هذا العدد. كم صدفة جمعا معًا؟",
+    "لدى ليلى 60 جنيهًا، ولدى ندى أقل منها بـ 18 جنيهًا. كم معهما معًا؟",
+]
+
+with gr.Blocks(title="Nawah-Math-Reasoning") as demo:
+    gr.HTML(DESCRIPTION)
+
+    with gr.Row():
+        with gr.Column(scale=3):
+            question = gr.Textbox(
+                label="السؤال / Question", rtl=True, lines=3,
+                placeholder="اكتب مسألة حسابية هنا…",
+            )
+            with gr.Row():
+                submit = gr.Button("🧮 حل / Solve", variant="primary")
+                clear = gr.Button("مسح / Clear")
+
+            with gr.Accordion("⚙️ إعدادات التوليد / Generation settings", open=False):
+                max_new_tokens = gr.Slider(32, MAX_NEW_TOKENS_CAP, value=320, step=8,
+                                           label="أقصى عدد توكنز / Max new tokens")
+                temperature = gr.Slider(0.0, 1.5, value=0.0, step=0.05,
+                                        label="درجة الحرارة / Temperature (0 = greedy, as evaluated)")
+                repetition_penalty = gr.Slider(1.0, 1.5, value=1.0, step=0.01,
+                                               label="عقوبة التكرار / Repetition penalty")
+
+        with gr.Column(scale=4):
+            answer_box = gr.Textbox(label="✅ الإجابة / Answer", rtl=True, lines=3)
+            with gr.Accordion("🧠 التفكير / Reasoning trace", open=True):
+                reasoning_box = gr.Textbox(label="", rtl=True, lines=12)
+            with gr.Accordion("🔍 المخرجات الخام / Raw output", open=False):
+                raw_box = gr.Textbox(label="", lines=8)
+
+    gr.Examples(examples=EXAMPLES, inputs=question, label="أمثلة / Examples")
+    gr.Markdown(NOTE)
+
+    inputs = [question, max_new_tokens, temperature, repetition_penalty]
+    outputs = [reasoning_box, answer_box, raw_box]
+    submit.click(solve, inputs=inputs, outputs=outputs)
+    question.submit(solve, inputs=inputs, outputs=outputs)
+    clear.click(lambda: ("", "", "", ""), outputs=[question] + outputs)
+
+if __name__ == "__main__":
+    demo.queue().launch(theme=gr.themes.Soft())

code/space/requirements.txt

@@ -0,0 +1,5 @@
+--extra-index-url https://download.pytorch.org/whl/cu128
+spaces
+torch==2.8.0
+transformers>=5.15,<6
+gradio

code/split_synth_v6.py

@@ -0,0 +1,75 @@
+"""
+Re-split the merged v6 synthetic corpus so v5 -> v6 stays a fair comparison.
+
+build_synth_dataset.py shuffles with SEED=42 over whatever rows it is given. The v6 corpus has
+20,139 more rows than the v5 one, so that shuffle lands differently and **1,955 of v5's 2,000
+held-out synth rows fall into v6's train split**. Training on them and then reporting the synth
+cell would be scoring memorisation.
+
+So the eval split is not re-drawn, it is *pinned*: `data_synth_sft/eval.jsonl` (v5's rows, in v5's
+order) is copied through verbatim, and every one of those instructions is removed from train. The
+first 1,000 of them are the same rows v4 and v5 were scored on, so the cell stays comparable
+across all three models.
+
+A second held-out set, `eval_rel.jsonl`, is carved from the relational pool (task_id >= 1,000,000)
+— the whole point of v6 is a capability v5 lacks, and none of the legacy eval rows test it.
+
+Writes data_synth_v6_sft/{train,eval,eval_rel}.jsonl.
+"""
+import json
+import random
+from pathlib import Path
+
+import pyarrow.parquet as pq
+
+CORPUS   = Path("out_merged_v6/arabic_math_reasoning_synth.parquet")
+LEGACY   = Path("data_synth_sft/eval.jsonl")      # v5's held-out synth rows — pinned, not redrawn
+OUT      = Path("data_synth_v6_sft")
+EVAL_REL = 400
+REL_MIN_TASK_ID = 1_000_000
+SEED = 42
+
+FIELDS = ("instruction", "reasoning", "answer")
+
+
+def sft(row, source="synth_math_ar"):
+    return {**{k: row[k] for k in FIELDS}, "source": source}
+
+
+def main():
+    rows = pq.read_table(CORPUS).to_pylist()
+    by_instruction = {r["instruction"]: r for r in rows}
+    print(f"[*] corpus {len(rows):,} rows")
+
+    legacy = [json.loads(l) for l in open(LEGACY, encoding="utf-8")]
+    missing = [r for r in legacy if r["instruction"] not in by_instruction]
+    print(f"[*] pinned eval {len(legacy):,} rows, {len(missing)} no longer in the corpus")
+
+    held = {r["instruction"] for r in legacy}
+
+    # relational held-out: deterministic sample of the new pool, also excluded from train
+    rel = [r for r in rows if r["task_id"] >= REL_MIN_TASK_ID and r["instruction"] not in held]
+    rel.sort(key=lambda r: (r["task_id"], r["instruction"]))       # parquet order is shuffled
+    eval_rel = random.Random(SEED).sample(rel, min(EVAL_REL, len(rel)))
+    held |= {r["instruction"] for r in eval_rel}
+    print(f"[*] relational rows {len(rel):,}, holding out {len(eval_rel):,}")
+
+    train = [r for r in rows if r["instruction"] not in held]
+    n_rel_train = sum(1 for r in train if r["task_id"] >= REL_MIN_TASK_ID)
+
+    OUT.mkdir(exist_ok=True)
+    for name, split in (("train", [sft(r) for r in train]),
+                        ("eval", legacy),                 # verbatim, v5's order
+                        ("eval_rel", [sft(r) for r in eval_rel])):
+        with open(OUT / f"{name}.jsonl", "w", encoding="utf-8") as fh:
+            for r in split:
+                fh.write(json.dumps(r, ensure_ascii=False) + "\n")
+        print(f"[+] {name}: {len(split):,} -> {OUT / f'{name}.jsonl'}")
+    print(f"[*] train carries {n_rel_train:,} relational rows ({n_rel_train/len(train):.1%})")
+
+    leak = sum(1 for r in train if r["instruction"] in held)
+    print(f"[{'+' if leak == 0 else '!'}] contamination check: {leak} held-out rows in train")
+
+
+if __name__ == "__main__":
+    main()

code/synth_common.py

@@ -0,0 +1,331 @@
+"""
+Shared pieces for the synthetic Arabic math-reasoning corpus.
+
+Holds everything both the generator and the dataset builder need, so the accept/reject decision
+is made by exactly one implementation:
+
+  * AXES        — the variation grid every prompt is drawn from
+  * build_task  — task_id -> (axes draw, prompt). Deterministic: task 7 always has the same draw,
+                  which is what makes the run resumable and reproducible.
+  * parse_items — split a raw completion into {instruction, reasoning, answer} records
+  * audit       — verify the arithmetic *inside* the reasoning and reject rows that don't check out
+
+Why the audit matters: a 12B model writes fluent Arabic derivations that are wrong roughly one
+time in ten. The reasoning states its own equations ("35 × 4 = 140"), so they can be re-evaluated
+exactly. This is the same discipline as the numeral audit in build_dataset.py, applied to
+generated arithmetic rather than translated arithmetic.
+"""
+import random
+import re
+import unicodedata
+
+# ---------------------------------------------------------------- variation grid
+
+DOMAINS = [
+    "التسوق وشراء البقالة", "الرواتب والأجور اليومية", "المسافات والسفر بالسيارة",
+    "وصفات الطبخ والمقادير", "المدرسة والطلاب والدرجات", "المزرعة والمحاصيل والحيوانات",
+    "الرياضة والمباريات والنقاط", "الادخار والميزانية الشهرية", "البناء والدهان والبلاط",
+    "فواتير الهاتف والإنترنت", "الوقود واستهلاك السيارة", "السوق وبيع الخضار والفواكه",
+    "المكتبة وشراء الكتب", "ورشة الخياطة والأقمشة", "توصيل الطلبات والمندوبين",
+    "المستشفى والجرعات والمواعيد", "الحديقة والأشجار والري", "المخبز وإنتاج الخبز",
+    "محل الحلويات والطلبيات", "النقل المدرسي والحافلات", "تربية الدواجن والبيض",
+    "مصنع صغير وخط الإنتاج", "الرحلات المدرسية والتذاكر", "تأجير المعدات باليوم",
+    "صيد السمك وبيعه", "محطة تحلية ومياه الشرب", "متجر إلكتروني والشحن",
+    "معرض السيارات والأقساط", "الزكاة وتوزيع الصدقات", "تنظيم حفل وعدد الضيوف",
+]
+
+OPERATIONS = [
+    ("الجمع والطرح", "خطوتان من الجمع والطرح على أعداد صحيحة"),
+    ("الضرب والقسمة", "الضرب ثم القسمة للوصول إلى نصيب الواحد"),
+    ("النسبة المئوية", "حساب نسبة مئوية من مبلغ ثم الزيادة أو النقصان"),
+    ("الكسور", "أخذ كسر من كمية ثم التعامل مع الباقي"),
+    ("النسبة والتناسب", "توزيع كمية بنسبة معلومة بين طرفين أو ثلاثة"),
+    ("سعر الوحدة", "استنتاج سعر الوحدة ثم حساب تكلفة كمية مختلفة"),
+    ("المتوسط الحسابي", "حساب متوسط مجموعة قيم ثم استنتاج قيمة ناقصة"),
+    ("السرعة والزمن والمسافة", "علاقة السرعة بالزمن والمسافة على مرحلتين"),
+    ("المساحة والمحيط", "مساحة أو محيط شكل مستطيل ثم تكلفة تغطيته"),
+    ("الربح والخسارة", "شراء بسعر وبيع بسعر آخر وحساب الربح أو نسبته"),
+    ("الخصم والضريبة", "خصم على السعر ثم إضافة ضريبة القيمة المضافة"),
+    ("العمل والزمن", "عاملان أو ثلاثة ينجزون عملاً في أزمنة مختلفة"),
+    ("تحويل الوحدات", "تحويل بين الوحدات (كجم/جرام، ساعة/دقيقة، متر/سم) ضمن الحل"),
+    ("المتتاليات البسيطة", "نمط يزيد بمقدار ثابت كل يوم أو كل أسبوع"),
+    ("المعادلة ذات المجهول الواحد", "صياغة معادلة بسيطة بمجهول واحد وحلها"),
+]
+
+# --- relational comparison pool -------------------------------------------------------------
+# A SEPARATE pool, not appended to OPERATIONS, so build_task(N) stays byte-identical for the task
+# ids that produced the original 100,323-row corpus — that corpus must remain reproducible.
+#
+# Why this exists: v5 scores pass@8 = 0 on prompts like "عمر أخيه ضعف عمره" because the grid never
+# generated the relation. Measured coverage in the 100k corpus: ضعف/أضعاف 1.34%, أكثر بـ/أقل بـ
+# 0.26%. RL cannot repair that class (no correct sample in the group -> no gradient), so it has to
+# come from data.
+#
+# The defining trait: one quantity is stated ONLY in terms of another, so the solver must compute
+# the second quantity before it can do anything else. That first step is exactly what v5 skips.
+RELATIONAL_OPS = [
+    ("المقارنة بالمضاعفة", "كمية ثانية تساوي ضعف الأولى، ثم يُطلب المجموع أو الفرق"),
+    ("المقارنة بالتضعيف المتعدد", "كمية ثانية تساوي ثلاثة أو أربعة أضعاف الأولى، ثم المجموع"),
+    ("المقارنة بالتنصيف", "كمية ثانية تساوي نصف الأولى، ثم المجموع أو الباقي"),
+    ("المقارنة بالكسر", "كمية ثانية تساوي ثلث أو ربع الأولى، ثم المجموع"),
+    ("المقارنة بالزيادة المطلقة", "كمية ثانية تزيد عن الأولى بمقدار ثابت، ثم المجموع"),
+    ("المقارنة بالنقصان المطلق", "كمية ثانية تقل عن الأولى بمقدار ثابت، ثم المجموع"),
+    ("المقارنة بين ثلاث كميات", "ثلاث كميات كل واحدة معرّفة بدلالة سابقتها، ثم المجموع"),
+    ("المقارنة العكسية", "تُعطى الكمية الثانية وعلاقتها بالأولى، والمطلوب الأولى ثم المجموع"),
+]
+
+# Relational problems are naturally short — a 5-step chain forces padding with filler steps.
+RELATIONAL_STEPS = [(2, "خطوتين"), (2, "خطوتين"), (3, "ثلاث خطوات")]
+
+STEPS = [(2, "خطوتين"), (3, "ثلاث خطوات"), (3, "ثلاث خطوات"), (4, "أربع خطوات")]
+
+NUMBER_STYLE = [
+    "أعداد صحيحة صغيرة (أقل من 100)",
+    "أعداد صحيحة متوسطة (بين 100 و 5000)",
+    "مبالغ مالية تحتوي على كسور عشرية بمنزلتين",
+    "أعداد كبيرة نسبيًا (بالآلاف) تقبل القسمة بدون باقٍ",
+]
+
+REGIONS = [
+    ("السعودية", "ريال"), ("مصر", "جنيه"), ("الإمارات", "درهم"), ("الأردن", "دينار"),
+    ("المغرب", "درهم"), ("الكويت", "دينار"), ("تونس", "دينار"), ("العراق", "دينار"),
+    ("سوريا", "ليرة"), ("عُمان", "ريال"), ("قطر", "ريال"), ("الجزائر", "دينار"),
+]
+
+NAMES = [
+    "أحمد", "فاطمة", "محمد", "سارة", "خالد", "نور", "يوسف", "مريم", "عمر", "ليلى",
+    "سلمان", "هند", "طارق", "رنا", "بلال", "أسماء", "زياد", "دعاء", "كريم", "شيماء",
+    "ياسر", "بثينة", "حسن", "رغد", "إبراهيم", "جنى", "مصطفى", "لمى", "سعيد", "أروى",
+]
+
+TWISTS = [
+    "أضف رقمًا واحدًا في نص المسألة لا يُستخدم في الحل (معلومة زائدة)",
+    "اجعل المسألة تقارن بين شخصين أو بين يومين",
+    "اجعل السؤال يطلب الباقي أو المتبقي وليس المجموع",
+    "اجعل السؤال يطلب عدد المرات أو عدد المجموعات",
+    "اجعل المسألة على مرحلتين زمنيتين (اليوم الأول ثم اليوم الثاني)",
+    "اجعل الإجابة النهائية تحتاج تقريبًا لأقرب عدد صحيح مع توضيح سبب التقريب",
+    "لا تضف أي تعقيد إضافي، اجعلها مباشرة وواضحة",
+    "اجعل السؤال يطلب النسبة المئوية للنتيجة من الإجمالي",
+]
+
+ITEMS_PER_TASK = 4
+
+# ---------------------------------------------------------------- prompt
+
+Q, T, A, E = "### مسألة", "### تفكير", "### الإجابة", "### نهاية"
+
+PROMPT = """أنت معلم رياضيات عربي تكتب مسائل تدريبية عالية الجودة باللغة العربية الفصحى.
+
+اكتب {k} مسائل حسابية **مختلفة تمامًا عن بعضها** بالمواصفات التالية:
+
+- المجال: {domain}
+- نوع العملية: {op_name} — {op_hint}
+- عدد خطوات الحل: {steps_word} تقريبًا (اكتب فقط الخطوات التي يحتاجها الحل فعلًا)
+- طبيعة الأرقام: {numbers}
+- السياق: {region}، والعملة {currency}
+- استخدم أسماء مثل: {names}
+- {twist}
+
+اكتب كل مسألة بهذا الشكل بالضبط، ولا تكتب أي شيء آخر خارج هذه الوسوم:
+
+{Q}
+نص المسألة في جملة أو جملتين، وينتهي بسؤال واضح.
+{T}
+خطوات الحل مرقمة، وكل خطوة تحتوي على معادلة صريحة بالأرقام مثل: 45 × 3 = 135
+{A}
+إذن، جملة واحدة تذكر الإجابة النهائية بالرقم مع وحدتها.
+{E}
+
+قواعد إلزامية:
+1. كل معادلة تكتبها يجب أن تكون **صحيحة حسابيًا**. تحقق من كل عملية قبل كتابتها.
+2. الرقم في سطر الإجابة يجب أن يساوي ناتج آخر خطوة في التفكير.
+3. اكتب الأرقام بالأرقام الإنجليزية (0-9) وليس بالحروف ولا بالأرقام الهندية.
+4. اكتب بالعربية فقط، بدون أي كلمة إنجليزية.
+5. لا تكرر مسألة سبق أن كتبتها في هذه الإجابة.
+6. لا تكتب خطوات فارغة أو بلا فائدة مثل «63 + 0 = 63» أو «4500 = 4500» أو «24 × 1 = 24».
+   كل خطوة يجب أن تُنتج قيمة جديدة لم تكن معروفة قبلها.
+7. إذا لم تناسب العملية المطلوبة المجالَ المطلوب، غيّر تفاصيل المسألة لتناسبها من البداية،
+   ولا تعلّق على ذلك ولا تعِد صياغة المسألة داخل خطوات الحل.
+"""
+
+
+def build_task(task_id: int, seed: int = 1234, pool: str = "default"):
+    """task_id -> (axes, prompt). Deterministic, so a resumed run redraws identical prompts.
+
+    pool="default"    the original 15-operation grid — draws are byte-identical to the run that
+                      produced the 100,323-row corpus, so that corpus stays reproducible.
+    pool="relational" the relational-comparison pool (RELATIONAL_OPS). Use a disjoint task-id
+                      range for it, the same rule that keeps two generating nodes from colliding.
+    """
+    ops, steps_pool = (RELATIONAL_OPS, RELATIONAL_STEPS) if pool == "relational" else (OPERATIONS, STEPS)
+    rng = random.Random(seed * 1_000_003 + task_id)
+    domain = rng.choice(DOMAINS)
+    op_name, op_hint = rng.choice(ops)
+    _, steps_word = rng.choice(steps_pool)
+    numbers = rng.choice(NUMBER_STYLE)
+    region, currency = rng.choice(REGIONS)
+    names = "، ".join(rng.sample(NAMES, 3))
+    twist = rng.choice(TWISTS)
+    axes = {"domain": domain, "op": op_name, "steps": steps_word, "numbers": numbers,
+            "region": region, "twist": twist}
+    prompt = PROMPT.format(k=ITEMS_PER_TASK, domain=domain, op_name=op_name, op_hint=op_hint,
+                           steps_word=steps_word, numbers=numbers, region=region,
+                           currency=currency, names=names, twist=twist, Q=Q, T=T, A=A, E=E)
+    return axes, prompt
+
+
+# ---------------------------------------------------------------- parsing
+
+AR_DIGITS = str.maketrans("٠١٢٣٤٥٦٧٨٩٪", "0123456789%")
+BLOCK_RE = re.compile(
+    re.escape(Q) + r"(?P<q>.*?)" + re.escape(T) + r"(?P<t>.*?)" + re.escape(A) + r"(?P<a>.*?)"
+    + r"(?:" + re.escape(E) + r"|$)", re.S)
+LATIN_RE = re.compile(r"[A-Za-z]")
+CONCLUSION = ("إذن", "لذلك", "بالتالي", "وبالتالي", "لذا", "في النهاية", "الخلاصة")
+# The model sometimes breaks frame and rewrites the problem inside its own derivation
+# ("*تصحيح للمسألة لتناسب العملية المطلوبة*") when a drawn operation type does not fit the drawn
+# domain. The arithmetic in those rows often still checks out, so the audit alone won't catch them.
+META_MARKERS = ("تصحيح للمسألة", "سنعيد صياغة", "لتناسب العملية", "المسألة تطلب",
+                "إعادة صياغة", "لنفترض أن المسألة", "تصحيح السؤال", "بما أن المسألة")
+
+
+def norm(text: str) -> str:
+    text = unicodedata.normalize("NFC", text.replace("‏", "").replace("‎", ""))
+    text = text.translate(AR_DIGITS)
+    text = re.sub(r"[ \t]+", " ", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+def parse_items(raw: str):
+    """Raw completion -> list of {instruction, reasoning, answer}. Malformed blocks are skipped."""
+    out = []
+    for m in BLOCK_RE.finditer(raw):
+        q, t, a = (norm(m.group(g)) for g in ("q", "t", "a"))
+        if q and t and a:
+            out.append({"instruction": q, "reasoning": t, "answer": a})
+    return out
+
+
+# ---------------------------------------------------------------- arithmetic audit
+
+NUM = r"\d+(?:\.\d+)?"
+# "x + 0 = x", "x × 1 = x", "x = x" — vacuous steps the model emits to hit a requested step count.
+NOOP_RE = re.compile(r"(?<![\d.])(" + NUM + r")\s*(?:[+\-−–]\s*0+(?:\.0+)?|"
+                     r"[×xX*]\s*1(?:\.0+)?|[÷/]\s*1(?:\.0+)?)?\s*=\s*\1(?![\d.])")
+
+# One arithmetic segment: digits and operators only, at least one digit. Deliberately excludes
+# newlines — a chain never spans two steps.
+_SC = r"[\d.()+\-−–×xX*÷/ \t]"
+SEG = _SC + r"*\d" + _SC + r"*"
+# "1." / "2)" list numbering at the head of a step is not part of the arithmetic; left in, it
+# turns "1. 75 + 15" into the un-evaluatable "1. 75 + 15".
+LIST_NUM_RE = re.compile(r"^[ \t]*\d+[.)][ \t]*", re.M)
+# A *chain*: "a × b = c + d = e". Models routinely show their working this way, and reading only
+# the first "=" turns a correct chain into a false rejection — every segment must be compared.
+CHAIN_RE = re.compile(r"(?<![\d.])(" + SEG + r"(?:=" + SEG + r")+)")
+
+
+def _evaluate(expr: str):
+    """Evaluate a pure-arithmetic expression with normal precedence. None if it isn't one."""
+    expr = expr.replace("−", "-").replace("–", "-").replace("×", "*").replace("x", "*") \
+               .replace("X", "*").replace("÷", "/")
+    expr = expr.strip()
+    if not expr or not re.fullmatch(r"[\d.+\-*/() ]+", expr) or not re.search(r"\d", expr):
+        return None
+    try:
+        # The regex above admits only digits, operators, dots, parens and spaces — no names,
+        # no calls, no attribute access — so this cannot execute anything else.
+        value = eval(expr, {"__builtins__": {}}, {})            # noqa: S307
+    except Exception:
+        return None
+    return value if isinstance(value, (int, float)) else None
+
+
+def _decimals(text: str) -> int:
+    text = text.strip()
+    return len(text.split(".")[1]) if "." in text else 0
+
+
+def _close(a, b, shown: str | None = None):
+    """
+    Is the stated value `b` an acceptable rendering of the true value `a`?
+
+    Exact, or `b` is `a` rounded to the precision `b` is written with — "3200 / 60 = 53.33" and
+    "9.44 × 60 = 566.4 → 566" are how people write arithmetic, not arithmetic errors. Only
+    rounding at the displayed precision is forgiven, so a genuinely wrong number still fails.
+    """
+    if abs(a - b) <= max(1e-6, abs(b) * 1e-9):
+        return True
+    if shown is not None:
+        d = _decimals(shown)
+        if abs(round(a, d) - b) <= 1e-9:
+            return True
+        if d == 0 and b in (int(a), int(a) + 1 if a > 0 else int(a) - 1):
+            return True            # a step that floors or ceils, e.g. "3 crates with a remainder"
+    return False
+
+
+def audit(reasoning: str, answer: str, min_equations: int = 1):
+    """
+    -> (ok, reason, n_checked)
+
+    Every "a op b = c [= d ...]" chain the reasoning states is re-evaluated end to end. One
+    segment that disagrees rejects the row. The answer's number must also match the last chain's
+    final value — a derivation that is internally correct but ends on a different number is the
+    failure mode that survives any fluency check.
+    """
+    checked = 0
+    last = None
+    body = LIST_NUM_RE.sub("", reasoning)
+    for m in CHAIN_RE.finditer(body):
+        parts = m.group(1).split("=")
+        values = [_evaluate(part) for part in parts]
+        if any(v is None for v in values) or len(values) < 2:
+            continue                       # not pure arithmetic (units, words, %) — not our call
+        checked += 1
+        head = values[0]
+        for part, v in zip(parts[1:], values[1:]):
+            # Compare each stated value against the *first* segment, which is the one written in
+            # full precision; `part` carries how many decimals the model chose to show.
+            if not _close(head, v, part):
+                return False, f"bad_equation:{m.group(1).strip()[:60]}", checked
+        last = values[-1]
+    if checked < min_equations:
+        return False, "no_equations", checked
+
+    ans_shown = re.findall(NUM, answer)
+    if not ans_shown:
+        return False, "answer_has_no_number", checked
+    if last is not None and not any(_close(last, float(x), x) for x in ans_shown):
+        return False, "answer_not_last_result", checked
+    return True, "ok", checked
+
+
+def validate(item, min_reasoning=40, max_reasoning=1200):
+    """Full accept/reject for one parsed item -> (ok, reason)."""
+    q, t, a = item["instruction"], item["reasoning"], item["answer"]
+    if LATIN_RE.search(q) or LATIN_RE.search(t) or LATIN_RE.search(a):
+        return False, "latin_residue"
+    if not (20 <= len(q) <= 600):
+        return False, "question_length"
+    if not (min_reasoning <= len(t) <= max_reasoning):
+        return False, "reasoning_length"
+    if not (10 <= len(a) <= 300):
+        return False, "answer_length"
+    if not a.lstrip("*-# ").startswith(CONCLUSION):
+        return False, "no_conclusion_marker"
+    if any(mark in t for mark in (Q, A, E)):
+        return False, "tag_leak"
+    if any(mark in t or mark in q for mark in META_MARKERS):
+        return False, "meta_commentary"
+    if NOOP_RE.search(t):
+        return False, "noop_step"
+    ok, reason, _ = audit(t, a)
+    return ok, reason
+
+
+def dedup_key(instruction: str) -> str:
+    """Numbers masked out, so the same template with different values collapses to one key."""
+    return re.sub(r"\d+(?:\.\d+)?", "#", re.sub(r"\W+", "", instruction))

code/synth_generate.py

@@ -0,0 +1,212 @@
+"""
+Generate the synthetic Arabic math-reasoning corpus with google/gemma-4-12B-it.
+
+Resumable by construction:
+
+  * A "task" is one generation call that asks for ITEMS_PER_TASK problems. Task N's prompt is a
+    pure function of N (synth_common.build_task), so nothing about the plan is stored — restart
+    the script and it redraws the identical prompts.
+  * Every completed task is appended to out_synth/generations.jsonl as one line and fsynced.
+    On start the file is replayed, completed task_ids are skipped, and a torn final line (a
+    machine that died mid-write) is dropped. Worst case a crash costs one in-flight batch.
+  * The stop condition is *accepted rows*, not tasks: each cached generation is re-validated on
+    load, so a resumed run knows how many good rows it already has and issues only what's missing.
+
+Backends:
+  BACKEND=hf     transformers batched generation                       (default, works here)
+  BACKEND=vllm   vLLM continuous batching                             (see the note below)
+
+vLLM cannot serve Gemma 4 on this box: every vLLM release that knows the gemma4 architecture
+(>= 0.20.2) pins torch 2.11, which is a CUDA 13 build, and this host's driver (550 / CUDA 12.4)
+caps at CUDA 12.x — vllm imports die on `libcudart.so.13`. The vLLM path is kept working for a
+box with driver >= 580, or for a gemma3/Qwen generator on the pinned .venv-vllm stack.
+
+Usage:
+  P=/notebooks/50M/.venv-lfm2/bin/python
+  TARGET=100000 $P -u synth_generate.py
+"""
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+import synth_common as sc
+
+MODEL_DIR   = os.environ.get("GEN_MODEL", "./models/gemma-4-12B-it")
+OUT_DIR     = Path(os.environ.get("OUT_DIR", "out_synth"))
+CACHE       = OUT_DIR / "generations.jsonl"
+TARGET      = int(os.environ.get("TARGET", 100_000))
+BATCH       = int(os.environ.get("BATCH", 32))
+MAX_NEW     = int(os.environ.get("MAX_NEW", 1400))
+TEMPERATURE = float(os.environ.get("TEMPERATURE", 0.9))
+TOP_P       = float(os.environ.get("TOP_P", 0.95))
+SEED        = int(os.environ.get("SEED", 1234))
+BACKEND     = os.environ.get("BACKEND", "hf")
+# Recorded on every cached row so a merged multi-node corpus stays attributable.
+MODEL_NAME  = os.environ.get("GEN_MODEL_NAME", os.path.basename(MODEL_DIR.rstrip("/")))
+# Multimodal wrappers can default to eager attention, which is several times slower to decode.
+ATTN        = os.environ.get("ATTN", "sdpa")
+MAX_TASKS   = int(os.environ.get("MAX_TASKS", 400_000))
+# Two machines generating at once must own disjoint task-id ranges: build_task() is a pure
+# function of the id, so overlapping ranges redraw byte-identical prompts and every row the
+# second machine produces dies as a duplicate template in build_synth_dataset.py. START_TASK
+# offsets this node's range; MAX_TASKS is counted from there, not from zero.
+START_TASK  = int(os.environ.get("START_TASK", 0))
+# Which slice of the variation grid to draw from. "default" is the original 15-operation grid;
+# "relational" is the comparison pool (x = 2y, x = y/2, x = y + n ...) that the default grid never
+# produced. Use a disjoint START_TASK for a relational run — same rule as two nodes not colliding.
+POOL        = os.environ.get("POOL", "default")
+# Qwen3-style templates open a <think> block in the generation prompt unless this is passed,
+# and the model then spends the whole MAX_NEW budget reasoning before it ever emits a tag.
+CHAT_KWARGS = {"enable_thinking": False} if os.environ.get("NO_THINK", "0") == "1" else {}
+
+
+def load_cache():
+    """-> (set of finished task_ids, accepted row count). Tolerates a truncated final line."""
+    done, accepted = set(), 0
+    if not CACHE.exists():
+        return done, accepted
+    with open(CACHE, encoding="utf-8") as fh:
+        for line in fh:
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError:
+                print("[!] dropping truncated final line of the cache")
+                continue
+            done.add(rec["task_id"])
+            for item in sc.parse_items(rec["raw"]):
+                ok, _ = sc.validate(item)
+                accepted += ok
+    return done, accepted
+
+
+class HFBackend:
+    """Batched transformers generation. No paged attention, but B sequences decode in parallel."""
+
+    def __init__(self):
+        import torch
+        import transformers
+        from transformers import AutoProcessor, AutoTokenizer
+
+        self.torch = torch
+        try:
+            self.tok = AutoProcessor.from_pretrained(MODEL_DIR).tokenizer
+        except Exception:
+            self.tok = AutoTokenizer.from_pretrained(MODEL_DIR)
+        self.tok.padding_side = "left"
+        if self.tok.pad_token_id is None:
+            self.tok.pad_token = self.tok.eos_token
+        print(f"[*] loading {MODEL_DIR} (bf16)", flush=True)
+        # gemma-4-*-it is a unified multimodal checkpoint, so the plain causal-LM auto class does
+        # not always claim it. Try the multimodal auto classes first and fall back.
+        self.model, last = None, None
+        for name in ("AutoModelForMultimodalLM", "AutoModelForImageTextToText",
+                     "AutoModelForCausalLM"):
+            cls = getattr(transformers, name, None)
+            if cls is None:
+                continue
+            try:
+                self.model = cls.from_pretrained(
+                    MODEL_DIR, dtype=torch.bfloat16, device_map="cuda:0",
+                    attn_implementation=ATTN).eval()
+                print(f"    loaded via {name}", flush=True)
+                break
+            except Exception as exc:                       # noqa: BLE001 - report the last failure
+                last = f"{name}: {exc}"
+        if self.model is None:
+            raise RuntimeError(f"could not load {MODEL_DIR}; last error -> {last}")
+        self.model.config.use_cache = True
+
+    def generate(self, prompts):
+        texts = [self.tok.apply_chat_template([{"role": "user", "content": p}],
+                                              tokenize=False, add_generation_prompt=True,
+                                              **CHAT_KWARGS)
+                 for p in prompts]
+        enc = self.tok(texts, return_tensors="pt", padding=True, add_special_tokens=False).to("cuda:0")
+        with self.torch.no_grad():
+            out = self.model.generate(**enc, max_new_tokens=MAX_NEW, do_sample=True,
+                                      temperature=TEMPERATURE, top_p=TOP_P,
+                                      pad_token_id=self.tok.pad_token_id)
+        width = enc["input_ids"].shape[1]
+        return [self.tok.decode(seq[width:], skip_special_tokens=True) for seq in out]
+
+
+class VLLMBackend:
+    def __init__(self):
+        from vllm import LLM, SamplingParams
+
+        kw = {}
+        if os.environ.get("QUANT"):                 # e.g. QUANT=modelopt for NVFP4 checkpoints
+            kw["quantization"] = os.environ["QUANT"]
+        self.llm = LLM(model=MODEL_DIR, dtype=os.environ.get("DTYPE", "bfloat16"),
+                       max_num_seqs=BATCH,
+                       gpu_memory_utilization=float(os.environ.get("GPU_UTIL", 0.90)),
+                       max_model_len=int(os.environ.get("MAX_LEN", 4096)), **kw)
+        self.params = SamplingParams(temperature=TEMPERATURE, top_p=TOP_P, max_tokens=MAX_NEW,
+                                     seed=None)
+        self.tok = self.llm.get_tokenizer()
+
+    def generate(self, prompts):
+        texts = [self.tok.apply_chat_template([{"role": "user", "content": p}],
+                                              tokenize=False, add_generation_prompt=True,
+                                              **CHAT_KWARGS)
+                 for p in prompts]
+        outs = self.llm.generate(texts, self.params)
+        return [o.outputs[0].text for o in outs]
+
+
+def main():
+    OUT_DIR.mkdir(exist_ok=True)
+    done, accepted = load_cache()
+    print(f"[*] cache: {len(done):,} tasks done, {accepted:,} rows accepted "
+          f"(target {TARGET:,}) | model {MODEL_NAME} | tasks {START_TASK:,}.."
+          f"{START_TASK + MAX_TASKS:,}", flush=True)
+    if accepted >= TARGET:
+        print("[+] target already met — nothing to do")
+        return
+
+    backend = (VLLMBackend if BACKEND == "vllm" else HFBackend)()
+
+    next_id = START_TASK
+    last_id = START_TASK + MAX_TASKS
+    started, gen_rows, gen_tasks = time.time(), 0, 0
+    fh = open(CACHE, "a", encoding="utf-8")
+    while accepted < TARGET and next_id < last_id:
+        batch = []
+        while len(batch) < BATCH and next_id < last_id:
+            if next_id not in done:
+                batch.append((next_id, *sc.build_task(next_id, SEED, POOL)))
+            next_id += 1
+        if not batch:
+            break
+
+        t0 = time.time()
+        raws = backend.generate([p for _, _, p in batch])
+        batch_accept = 0
+        for (task_id, axes, _), raw in zip(batch, raws):
+            fh.write(json.dumps({"task_id": task_id, "axes": axes, "raw": raw,
+                                 "model": MODEL_NAME}, ensure_ascii=False) + "\n")
+            for item in sc.parse_items(raw):
+                ok, _ = sc.validate(item)
+                batch_accept += ok
+        fh.flush()
+        os.fsync(fh.fileno())          # a crash costs the in-flight batch, never the cache
+
+        accepted += batch_accept
+        gen_rows += batch_accept
+        gen_tasks += len(batch)
+        dt = time.time() - t0
+        rate = gen_rows / max(time.time() - started, 1e-9)
+        eta = (TARGET - accepted) / rate / 3600 if rate > 0 else float("inf")
+        print(f"[{accepted:>7,}/{TARGET:,}] +{batch_accept:>3} rows  "
+              f"batch {len(batch)} in {dt:5.1f}s  "
+              f"accept {batch_accept / (len(batch) * sc.ITEMS_PER_TASK):5.1%}  "
+              f"{rate * 3600:,.0f} rows/h  ETA {eta:4.1f}h", flush=True)
+
+    fh.close()
+    print(f"[+] {accepted:,} accepted rows in cache after {gen_tasks:,} new tasks")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

code/train_reasoning.py

@@ -0,0 +1,192 @@
+"""
+Reasoning SFT for oddadmix/50M-2048-Emhotob on Arabic_Reasoning_Dataset.
+
+ChatML format with the derivation wrapped in <think>...</think>. Loss is computed on the
+assistant turn only — the user prompt is masked out, same as the earlier Emhotob SFT runs.
+No TRL; plain HF Trainer.
+"""
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import torch
+from torch.utils.data import Dataset
+from transformers import (
+    AutoModelForCausalLM,
+    AutoTokenizer,
+    Trainer,
+    TrainingArguments,
+)
+
+os.environ.setdefault("CUDA_VISIBLE_DEVICES", "0")
+
+# Defaults reproduce v1 (Arabic_Reasoning_Dataset); every value can be overridden by env var
+# so the same recipe can be pointed at a different corpus.
+def _env(name, default, cast=str):
+    return cast(os.environ.get(name, default))
+
+BASE_MODEL   = _env("BASE_MODEL", "/notebooks/50M/50M-2048-Emhotob")
+OUTPUT_DIR   = _env("OUTPUT_DIR", "./Nawah-Reasoning-v1")
+TRAIN_FILE   = _env("TRAIN_FILE", "data/train.jsonl")
+EVAL_FILE    = _env("EVAL_FILE", "data/eval.jsonl")
+
+MAX_LENGTH   = _env("MAX_LENGTH", 768, int)   # v1: p100 of that corpus is 708 tokens
+IGNORE_INDEX = -100
+
+LEARNING_RATE = _env("LEARNING_RATE", 3e-4, float)   # same as the Emhotob translation SFT ladder
+EPOCHS        = _env("EPOCHS", 8, int)   # v1 is tiny (~840k tok/epoch); best checkpoint wins
+BATCH_SIZE    = _env("BATCH_SIZE", 16, int)
+GRAD_ACCUM    = _env("GRAD_ACCUM", 2, int)
+WARMUP_STEPS  = _env("WARMUP_STEPS", 100, int)
+EVAL_STEPS    = _env("EVAL_STEPS", 100, int)
+# On the v3 mix, eval loss is a bad model selector: the repeated Arabic_Reasoning rows start
+# memorising around epoch 1.4 and drag the loss up while generation quality on *both* halves is
+# still improving. Set LOAD_BEST=0 there and keep the final checkpoint.
+LOAD_BEST     = _env("LOAD_BEST", 1, int) == 1
+# Point at a checkpoint dir to continue an interrupted run (optimizer/scheduler/RNG/step are
+# restored from it). Empty = fresh run, so v1-v5 still reproduce exactly.
+RESUME        = _env("RESUME", "") or None
+WEIGHT_DECAY  = 0.0
+MAX_GRAD_NORM = 1.0
+SEED          = 42
+
+SPECIAL_TOKENS = ["<|im_start|>", "<|im_end|>", "<think>", "</think>"]
+
+CHAT_TEMPLATE = (
+    "{% for message in messages %}"
+    "{{ '<|im_start|>' + message['role'] + '\n' + message['content'] + '<|im_end|>' + '\n' }}"
+    "{% endfor %}"
+    "{% if add_generation_prompt %}{{ '<|im_start|>assistant\n' }}{% endif %}"
+)
+
+PROMPT_TMPL   = "<|im_start|>user\n{instruction}<|im_end|>\n<|im_start|>assistant\n"
+RESPONSE_TMPL = "<think>\n{reasoning}\n</think>\n{answer}<|im_end|>"
+
+
+def load_jsonl(path):
+    with open(path, encoding="utf-8") as fh:
+        return [json.loads(line) for line in fh]
+
+
+class ReasoningDataset(Dataset):
+    """Prompt tokens are masked so loss falls only on <think>…</think> + answer."""
+
+    def __init__(self, rows, tokenizer, max_length):
+        self.rows = rows
+        self.tok = tokenizer
+        self.max_length = max_length
+
+    def __len__(self):
+        return len(self.rows)
+
+    def __getitem__(self, idx):
+        row = self.rows[idx]
+        prompt = PROMPT_TMPL.format(instruction=row["instruction"])
+        response = RESPONSE_TMPL.format(reasoning=row["reasoning"], answer=row["answer"])
+
+        prompt_ids = [self.tok.bos_token_id] + self.tok.encode(prompt, add_special_tokens=False)
+        response_ids = self.tok.encode(response, add_special_tokens=False)
+
+        input_ids = (prompt_ids + response_ids)[: self.max_length]
+        prompt_len = min(len(prompt_ids), len(input_ids))
+        labels = [IGNORE_INDEX] * prompt_len + input_ids[prompt_len:]
+
+        return {
+            "input_ids": torch.tensor(input_ids, dtype=torch.long),
+            "labels": torch.tensor(labels, dtype=torch.long),
+        }
+
+
+@dataclass
+class PaddingCollator:
+    pad_token_id: int
+
+    def __call__(self, features):
+        longest = max(len(f["input_ids"]) for f in features)
+        input_ids, labels, attention = [], [], []
+        for f in features:
+            pad = longest - len(f["input_ids"])
+            input_ids.append(torch.cat([f["input_ids"], torch.full((pad,), self.pad_token_id, dtype=torch.long)]))
+            labels.append(torch.cat([f["labels"], torch.full((pad,), IGNORE_INDEX, dtype=torch.long)]))
+            attention.append(torch.cat([torch.ones(len(f["input_ids"]), dtype=torch.long), torch.zeros(pad, dtype=torch.long)]))
+        return {
+            "input_ids": torch.stack(input_ids),
+            "labels": torch.stack(labels),
+            "attention_mask": torch.stack(attention),
+        }
+
+
+def main():
+    print("[*] loading tokenizer + base model")
+    tok = AutoTokenizer.from_pretrained(BASE_MODEL)
+    added = tok.add_special_tokens({"additional_special_tokens": SPECIAL_TOKENS})
+    tok.chat_template = CHAT_TEMPLATE
+    print(f"    added {added} special tokens -> vocab {len(tok)}")
+
+    model = AutoModelForCausalLM.from_pretrained(BASE_MODEL, dtype=torch.float32)
+    model.resize_token_embeddings(len(tok))
+    model.config.use_cache = False
+    print(f"    params: {sum(p.numel() for p in model.parameters()) / 1e6:.2f}M")
+
+    train_rows, eval_rows = load_jsonl(TRAIN_FILE), load_jsonl(EVAL_FILE)
+    print(f"[*] train {len(train_rows)} / eval {len(eval_rows)}")
+
+    args = TrainingArguments(
+        output_dir=OUTPUT_DIR,
+        num_train_epochs=EPOCHS,
+        per_device_train_batch_size=BATCH_SIZE,
+        per_device_eval_batch_size=BATCH_SIZE,
+        gradient_accumulation_steps=GRAD_ACCUM,
+        learning_rate=LEARNING_RATE,
+        lr_scheduler_type="cosine",
+        warmup_steps=WARMUP_STEPS,
+        weight_decay=WEIGHT_DECAY,
+        max_grad_norm=MAX_GRAD_NORM,
+        bf16=True,
+        logging_steps=25,
+        eval_strategy="steps",
+        eval_steps=EVAL_STEPS,
+        save_strategy="steps",
+        save_steps=EVAL_STEPS,
+        save_total_limit=2,
+        load_best_model_at_end=LOAD_BEST,
+        metric_for_best_model="eval_loss",
+        greater_is_better=False,
+        report_to=[],
+        seed=SEED,
+        dataloader_num_workers=2,
+        remove_unused_columns=False,
+    )
+
+    trainer = Trainer(
+        model=model,
+        args=args,
+        train_dataset=ReasoningDataset(train_rows, tok, MAX_LENGTH),
+        eval_dataset=ReasoningDataset(eval_rows, tok, MAX_LENGTH),
+        data_collator=PaddingCollator(pad_token_id=tok.pad_token_id),
+    )
+
+    if RESUME:
+        print(f"[*] resuming from {RESUME}")
+    trainer.train(resume_from_checkpoint=RESUME)
+
+    print("[*] saving best checkpoint")
+    im_end_id = tok.convert_tokens_to_ids("<|im_end|>")
+    model.config.use_cache = True
+    model.generation_config.eos_token_id = [tok.eos_token_id, im_end_id]
+    model.generation_config.pad_token_id = tok.pad_token_id
+    trainer.save_model(OUTPUT_DIR)
+    tok.save_pretrained(OUTPUT_DIR)
+
+    metrics = trainer.evaluate()
+    print("[*] final eval:", metrics)
+    Path(OUTPUT_DIR, "train_metrics.json").write_text(
+        json.dumps({"final_eval": metrics, "log_history": trainer.state.log_history}, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+    print(f"[+] done -> {OUTPUT_DIR}")
+
+
+if __name__ == "__main__":
+    main()

code/translate_gsm.py

@@ -0,0 +1,119 @@
+"""
+Translate a stratified 150k-row subset of Ajhesh7/gsm8k-reasoning-SFT-datas into Arabic
+with ByteDance-Seed/Seed-X-PPO-7B (direct, per-row — numbers and names kept in place).
+
+Unique segments are translated once (greedy decoding is deterministic, so identical input
+gives identical output) and cached to a jsonl that makes the run resumable.
+
+Usage: python translate_gsm.py [n_rows]
+"""
+import json
+import os
+import random
+import re
+import sys
+import time
+from collections import defaultdict
+
+import pyarrow.parquet as pq
+
+sys.path.insert(0, ".")
+from gsm_common import NUM_RE, SRC_PROMPT, parse
+
+SRC_PARQUET = "data_gsm/data/train-00000-of-00001.parquet"
+CACHE = "out_gsm/translations.jsonl"
+N_ROWS = int(sys.argv[1]) if len(sys.argv) > 1 else 150_000
+CHUNK = 20_000
+SEED = 42
+MODEL = "./models/Seed-X-PPO-7B"
+
+NAME_RE = re.compile(r"\b[A-Z][a-z]{2,}\b")
+
+
+def select_rows(texts, n, seed=SEED):
+    """Stratify by name/number-agnostic question pattern so every pattern is represented."""
+    rows = []
+    for i, t in enumerate(texts):
+        p = parse(t)
+        if p:
+            rows.append((i,) + p)
+    buckets = defaultdict(list)
+    for r in rows:
+        key = NAME_RE.sub("@", NUM_RE.sub("#", r[1]))
+        buckets[key].append(r)
+
+    rng = random.Random(seed)
+    for b in buckets.values():
+        rng.shuffle(b)
+
+    chosen, leftover = [], []
+    floor = max(1, n // (len(buckets) * 4))
+    for b in buckets.values():
+        chosen.extend(b[:floor])
+        leftover.extend(b[floor:])
+    rng.shuffle(leftover)
+    chosen.extend(leftover[: max(0, n - len(chosen))])
+    rng.shuffle(chosen)
+    print(f"[*] {len(buckets)} question patterns; floor {floor}/pattern; selected {len(chosen)} rows")
+    return chosen[:n]
+
+
+def load_cache():
+    done = {}
+    if os.path.exists(CACHE):
+        with open(CACHE, encoding="utf-8") as fh:
+            for line in fh:
+                try:
+                    rec = json.loads(line)
+                    done[rec["src"]] = rec["tgt"]
+                except json.JSONDecodeError:
+                    continue  # truncated last line from a killed run
+    return done
+
+
+def main():
+    os.makedirs("out_gsm", exist_ok=True)
+    texts = pq.read_table(SRC_PARQUET).to_pydict()["text"]
+    rows = select_rows(texts, N_ROWS)
+
+    with open("out_gsm/selected_rows.jsonl", "w", encoding="utf-8") as fh:
+        for idx, q, t, a in rows:
+            fh.write(json.dumps({"idx": idx, "question": q, "thinking": t, "answer": a}, ensure_ascii=False) + "\n")
+
+    segments = []
+    seen = set()
+    for _, q, t, _ in rows:
+        for s in (q, t):
+            if s not in seen:
+                seen.add(s)
+                segments.append(s)
+    done = load_cache()
+    todo = [s for s in segments if s not in done]
+    print(f"[*] {len(rows)} rows -> {len(segments)} unique segments; {len(done)} cached, {len(todo)} to translate")
+    if not todo:
+        print("[+] nothing to do")
+        return
+
+    from vllm import LLM, SamplingParams
+
+    llm = LLM(model=MODEL, max_num_seqs=512, gpu_memory_utilization=0.92, max_model_len=1024)
+    params = SamplingParams(temperature=0, max_tokens=256, skip_special_tokens=True)
+
+    start = time.time()
+    with open(CACHE, "a", encoding="utf-8") as fh:
+        for i in range(0, len(todo), CHUNK):
+            chunk = todo[i : i + CHUNK]
+            outs = llm.generate([SRC_PROMPT.format(text=s) for s in chunk], params)
+            for src, o in zip(chunk, outs):
+                fh.write(json.dumps({"src": src, "tgt": o.outputs[0].text.strip()}, ensure_ascii=False) + "\n")
+            fh.flush()
+            done_n = i + len(chunk)
+            rate = done_n / (time.time() - start)
+            eta = (len(todo) - done_n) / rate / 60
+            print(f"[*] {done_n}/{len(todo)} segments  {rate:.1f} seg/s  ETA {eta:.0f} min", flush=True)
+
+    print(f"[+] done in {(time.time() - start)/60:.1f} min -> {CACHE}")
+
+
+if __name__ == "__main__":
+    main()