docs: pin revision in usage, v2 benchmark table + reproduction section

README.md

@@ -40,8 +40,13 @@ This is the **tutor (instruct) model**: it answers student questions directly wi
 ```python
 from transformers import AutoModelForCausalLM, AutoTokenizer
 
-tok = AutoTokenizer.from_pretrained("zyoralabs/AQ-academic-ai")
-model = AutoModelForCausalLM.from_pretrained("zyoralabs/AQ-academic-ai", trust_remote_code=True)
+# Pin a released revision so the loaded code + weights are immutable
+# (trust_remote_code executes this repo's modeling files).
+REV = "v2.0"
+
+tok = AutoTokenizer.from_pretrained("zyoralabs/AQ-academic-ai", revision=REV)
+model = AutoModelForCausalLM.from_pretrained(
+    "zyoralabs/AQ-academic-ai", revision=REV, trust_remote_code=True)
 
 prompt = "### Student:\nWhat is a stack in data structures?\n\n### Tutor:\n"
 ids = tok(prompt, return_tensors="pt").input_ids
@@ -50,6 +55,8 @@ out = model.generate(ids, max_new_tokens=200, do_sample=True,
 print(tok.decode(out[0][ids.shape[1]:]))
 ```
 
+Tested environment: `transformers==4.53.0`, `torch==2.7.1`, `tokenizers==0.21`, dtype `bfloat16`, single GPU or CPU.
+
 ## Architecture (proprietary, from scratch)
 
 | | |
@@ -66,15 +73,32 @@ print(tok.decode(out[0][ids.shape[1]:]))
 
 ## Benchmarks (0-shot, lm-evaluation-harness)
 
-| Benchmark | AQ v1 Tutor | Notes |
+| Benchmark | AQ v2 Tutor | Notes |
 |---|---|---|
-| SciQ | 69.2 | strong science knowledge for the size/data budget |
-| PIQA | 62.3 | |
-| ARC-easy | 45.1 | |
-| Winogrande | 49.5 | |
+| SciQ | 70.0 | strong science knowledge for the size/data budget |
+| PIQA | 61.9 | |
+| ARC-easy | 45.2 | |
+| Winogrande | 50.1 | |
 | HellaSwag | 29.6 | |
 | MMLU | 25.2 | at-chance, like all ~1B-class models |
-| ARC-challenge | 21.2 | |
+| ARC-challenge | 20.8 | |
+
+### Reproducing these numbers
+
+Scores were produced with **lm-evaluation-harness 0.4.8** (`pip install lm-eval==0.4.8`),
+0-shot, default task configs, on a single H100 (bf16):
+
+```bash
+lm_eval --model hf \
+  --model_args pretrained=zyoralabs/AQ-academic-ai,revision=v2.0,trust_remote_code=True,dtype=bfloat16 \
+  --tasks mmlu,arc_easy,arc_challenge,hellaswag,piqa,winogrande,sciq \
+  --batch_size auto
+```
+
+Environment: `transformers==4.53.0`, `torch==2.7.1` (cu128), `datasets==3.2.0`, `accelerate`.
+The machine-readable harness output is published in this repo at
+[`eval/aq_v2_tutor_results.json`](./eval/aq_v2_tutor_results.json).
+Reported metric is `acc` (see the artifact for `acc_norm` and per-subtask MMLU results).
 
 For context: models of this size trained on **15×–150× more tokens** (e.g. 300B–3T) reach SciQ ~84–89. AQ reaches ~70 on just **20B tokens** — the concept-first, knowledge-dense corpus is the point.