Improve bilingual model card

README.md

@@ -8,59 +8,251 @@ datasets:
 library_name: transformers
 pipeline_tag: text-generation
 tags:
-  - nederlands
   - dutch
-  - pretrained
+  - nederlands
+  - instruction-tuned
+  - conversational
+  - question-answering
+  - summarization
+  - qwen3
+---
+
+# Boterham 0.5B
+
+## English
+
+### Model description
+
+**Boterham 0.5B** is a compact, primarily Dutch decoder-only language model
+developed by ToetsChecker Research. It was pretrained from scratch and then
+instruction-tuned for working with Dutch text and documents. The model is
+particularly intended for grounded tasks: give it a passage and ask it to
+extract an answer, summarize the passage, or abstain when the requested
+information is absent.
+
+The Hugging Face export uses the `Qwen3ForCausalLM` implementation because the
+architectures are compatible. **Boterham does not use Qwen weights and is not a
+fine-tune or derivative of Qwen**; its tokenizer and model weights were trained
+from scratch.
+
+| Property | Value |
+|---|---|
+| Parameters | 488.3M total; 447.4M excluding tied token embeddings |
+| Architecture | Decoder-only Transformer, RMSNorm, GQA, RoPE, SwiGLU, QK-norm |
+| Layers / hidden size | 26 / 1,280 |
+| Attention heads | 20 query heads, 4 key/value heads |
+| Context length | 2,048 tokens |
+| Vocabulary | 32,002-token byte-level BPE |
+| Languages | Primarily Dutch; some English and Dutch-English translation data |
+| License | Apache 2.0 |
+
+### Intended tasks
+
+The instruction-tuning mixture contains the following task families:
+
+- grounded extractive question answering;
+- abstention when an answer is not present in the supplied text;
+- Dutch document summarization;
+- arithmetic and short worked calculations;
+- grammar and multiple-choice classification;
+- Dutch-English translation;
+- open questions, basic factual questions and short conversation.
+
+Its main intended use is experimentation with Dutch NLP, document-grounded
+assistants and retrieval-augmented generation. It is not intended as a
+high-stakes decision system or as an authoritative source of facts.
+
+### Training
+
+The base model was pretrained from scratch on approximately **8.0 billion
+tokens**. The corpus consists of public-domain and permissively licensed
+material, including Dutch government publications, legislation, parliamentary
+proceedings, case law and Wikimedia sources. The documented source dataset is
+available at [ToetsChecker-Research/beleg](https://huggingface.co/datasets/ToetsChecker-Research/beleg).
+No general web crawl or model-generated distillation dataset was used.
+
+Instruction tuning used 575,211 training examples and a held-out set of 1,000
+examples. It ran for **2 epochs / 4,786 optimizer steps** on four NVIDIA L4
+GPUs, with a peak learning rate of `5e-5` and a cosine schedule. Training loss
+was applied only to answer tokens and weighted globally by the number of answer
+tokens. The best held-out validation loss was **0.8348**.
+
+The instruction data was built from verifiable source documents where
+possible. Extractive answers must occur in the context; abstention examples are
+checked so that the answer is absent; and reference summaries originate from
+the source collection. The model uses the Boterham chat tokens included in the
+published tokenizer.
+
+### Usage with Transformers
+
+```bash
+pip install "transformers>=4.51" torch
+```
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_id = "ToetsChecker-Research/boterham"
+
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(
+    model_id,
+    dtype=torch.bfloat16 if torch.cuda.is_available() else torch.float32,
+).to("cuda" if torch.cuda.is_available() else "cpu")
+
+messages = [{
+    "role": "user",
+    "content": (
+        "Answer only from the text. If the answer is absent, say exactly: "
+        "Ik weet dit niet.\n\n"
+        "Tekst: De vergadering begint vrijdag om 14.00 uur in Utrecht.\n\n"
+        "Vraag: Hoe laat begint de vergadering?"
+    ),
+}]
+
+prompt = tokenizer.apply_chat_template(
+    messages,
+    tokenize=False,
+    add_generation_prompt=True,
+)
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+
+with torch.inference_mode():
+    output = model.generate(
+        **inputs,
+        max_new_tokens=128,
+        do_sample=False,
+        eos_token_id=tokenizer.eos_token_id,
+        pad_token_id=tokenizer.pad_token_id,
+    )
+
+generated = output[0, inputs.input_ids.shape[1]:]
+raw = tokenizer.decode(generated, skip_special_tokens=False)
+
+# Some prompts produce a private reasoning block before the final answer.
+answer = raw.split("<|einde_denken|>")[-1].split("<|einde|>")[0].strip()
+print(answer)
+```
+
+For the most reproducible task evaluation, use greedy decoding
+(`do_sample=False`) and reproduce the benchmark's required answer format.
+
+### Checkpoints in this repository
+
+- Root-level `model.safetensors`: compact Transformers inference export.
+- `sft-0.5B/beste.pt`: best instruction-tuned native PyTorch checkpoint.
+- `sft-0.5B/laatste.pt`: final native checkpoint including optimizer state,
+  intended for resuming training.
+- `boterham-0.5B/`: original pretrained native checkpoints.
+
+### Limitations
+
+Boterham is a small experimental model. It has limited world knowledge and can
+produce incorrect, fabricated or biased text. Factual claims about people,
+dates, numbers, law, medicine or current events should not be trusted without
+verification and supporting context. Its 2,048-token context window is short by
+current standards. Open-ended conversation and creative writing received less
+training emphasis than document-grounded tasks.
+
+Official EuroEval benchmark results have not yet been published. Validation
+loss is a training diagnostic and must not be interpreted as a benchmark score.
+
 ---
 
-# boterham-0.5B
+## Nederlands
 
-Een Nederlandstalig taalmodel, getraind op uitsluitend rechtmatig
-verkregen materiaal: publiek domein en permissief gelicentieerde
-bronnen. Geen geschraapt web, geen destillatie uit een ander model.
+### Modelbeschrijving
 
-De dataset waarop het draait staat los gepubliceerd als
-[`ToetsChecker-Research/beleg`](https://huggingface.co/datasets/ToetsChecker-Research/beleg),
-met per document de herkomst, de licentie en de ophaaldatum. Dat
-corpus is het eigenlijke product; een model veroudert binnen een jaar
-en een goed gedocumenteerde dataset niet.
+**Boterham 0.5B** is een compact, voornamelijk Nederlandstalig decoder-only
+taalmodel van ToetsChecker Research. Het model is vanaf nul voorgetraind en
+daarna instructiegetuned voor het werken met Nederlandse tekst en documenten.
+Het is vooral bedoeld voor gegronde taken: geef het een passage en laat het een
+antwoord uit de tekst halen, de passage samenvatten, of aangeven dat gevraagde
+informatie ontbreekt.
 
-## Wat het is
+De Hugging Face-export gebruikt `Qwen3ForCausalLM` omdat de architecturen
+compatibel zijn. **Boterham gebruikt geen Qwen-gewichten en is geen finetune of
+afgeleide van Qwen**; zowel de tokenizer als de modelgewichten zijn vanaf nul
+getraind.
 
-| | |
+| Eigenschap | Waarde |
 |---|---|
-| parameters | 488,3M (447,4M zonder embeddings) |
-| architectuur | decoder-only, GQA, RoPE, SwiGLU, RMSNorm, QK-norm |
-| contextlengte | 2048 tokens |
-| vocabulaire | 32,002 BPE, byte-level |
-| val-loss na finetuning | 0.8348 |
+| Parameters | 488,3M totaal; 447,4M zonder de gedeelde tokenembeddings |
+| Architectuur | Decoder-only Transformer, RMSNorm, GQA, RoPE, SwiGLU, QK-norm |
+| Lagen / verborgen breedte | 26 / 1.280 |
+| Attention-heads | 20 query-heads, 4 key/value-heads |
+| Contextlengte | 2.048 tokens |
+| Woordenschat | byte-level BPE met 32.002 tokens |
+| Talen | Vooral Nederlands; ook Engels en Nederlands-Engelse vertaaldata |
+| Licentie | Apache 2.0 |
+
+### Taken
+
+De instructiefinetuning bevat de volgende taakfamilies:
+
+- extractieve vraagbeantwoording op basis van meegegeven tekst;
+- onthouding wanneer het antwoord niet in de tekst staat;
+- samenvatten van Nederlandse documenten;
+- rekenen en korte uitgewerkte berekeningen;
+- grammatica- en meerkeuzeclassificatie;
+- Nederlands-Engelse vertaling;
+- open vragen, eenvoudige feitenvragen en korte gesprekken.
+
+Het belangrijkste gebruiksdoel is onderzoek naar Nederlandse NLP,
+documentgestuurde assistenten en retrieval-augmented generation. Het model is
+niet bedoeld voor beslissingen met grote gevolgen of als gezaghebbende
+feitenbron.
+
+### Training
+
+Het basismodel is vanaf nul voorgetraind op ongeveer **8,0 miljard tokens**.
+Het corpus bestaat uit publiek domein en permissief gelicentieerd materiaal,
+waaronder Nederlandse overheidspublicaties, wetgeving, parlementaire
+Handelingen, rechtspraak en Wikimedia-bronnen. De gedocumenteerde brondataset
+staat op [ToetsChecker-Research/beleg](https://huggingface.co/datasets/ToetsChecker-Research/beleg).
+Er is geen algemene webcrawl of door een ander model gegenereerde
+destillatiedataset gebruikt.
+
+De instructiefinetuning gebruikte 575.211 trainingsvoorbeelden en 1.000
+apart gehouden validatievoorbeelden. De run duurde **2 epochs / 4.786
+optimizerstappen** op vier NVIDIA L4-GPU's, met een maximale learning rate van
+`5e-5` en een cosine schedule. Alleen antwoordtokens telden mee voor de loss;
+de weging gebeurde globaal op basis van het aantal antwoordtokens. De beste
+validatieloss was **0,8348**.
 
-## Hoe het getraind is
+Waar mogelijk is de instructiedata opgebouwd uit controleerbare
+brondocumenten. Extractieve antwoorden moeten letterlijk in de context staan,
+bij onthoudingsvoorbeelden wordt gecontroleerd dat het antwoord ontbreekt, en
+referentiesamenvattingen komen uit de broncollectie. Het model gebruikt de
+Boterham-chattokens die in de gepubliceerde tokenizer zijn opgenomen.
 
-Daarna gefinetuned op instructiedata die uit datzelfde corpus is afgeleid, 2.0 epochs, met het verlies alleen op het antwoord.
+### Gebruik met Transformers
 
-Alle taken in de instructiedata zijn afgeleid uit echte documenten en
-achteraf gecontroleerd: een extractief antwoord moet letterlijk in de
-context staan, een onthoudingsvoorbeeld moet aantoonbaar niet in de
-context staan, en een samenvatting moet korter zijn dan de bron. Wat
-niet te controleren viel is niet meegegaan.
+Het Python-voorbeeld in de Engelse sectie is direct bruikbaar. De belangrijke
+stappen zijn `AutoTokenizer.from_pretrained`,
+`AutoModelForCausalLM.from_pretrained` en `tokenizer.apply_chat_template`.
+Gebruik voor reproduceerbare evaluatie greedy decoding (`do_sample=False`) en
+houd het antwoordformaat van de benchmark exact aan.
 
-## Wat het niet kan
+### Checkpoints in deze repository
 
-Dit is een model van een halve miljard parameters, getraind op een
-budget in miljarden tokens waar vergelijkbare modellen er biljoenen
-zien. Verwacht geen brede wereldkennis en geen betrouwbare feiten over
-personen, datums of getallen zonder context erbij. Het is gebouwd om
-te werken met een document in de prompt, niet om uit het hoofd te
-antwoorden.
+- `model.safetensors` in de hoofdmap: compacte Transformers-export voor
+  inference en benchmarks.
+- `sft-0.5B/beste.pt`: beste native PyTorch-checkpoint na instructiefinetuning.
+- `sft-0.5B/laatste.pt`: laatste native checkpoint inclusief optimizerstaat,
+  bedoeld om training te hervatten.
+- `boterham-0.5B/`: oorspronkelijke voorgetrainde native checkpoints.
 
-Losse conversatie en creatief schrijven zitten nauwelijks in de
-trainingsdata, want daar bestaat geen rechtmatige Nederlandstalige
-bron van omvang voor. Dat is een bewuste keuze en geen omissie.
+### Beperkingen
 
-## Licentie en herkomst
+Boterham is een klein experimenteel model. Het heeft beperkte wereldkennis en
+kan onjuiste, verzonnen of bevooroordeelde tekst produceren. Feiten over
+personen, datums, getallen, recht, geneeskunde of actuele gebeurtenissen mogen
+niet zonder controle en ondersteunende context worden vertrouwd. Het
+contextvenster van 2.048 tokens is naar huidige maatstaven kort. Open
+conversatie en creatief schrijven kregen minder nadruk dan documentgebonden
+taken.
 
-Het model staat onder Apache 2.0. De onderliggende teksten zijn
-publiek domein (artikel 11 Auteurswet voor overheidspublicaties en
-rechtspraak) of permissief gelicentieerd (CC BY, CC BY-SA, CC0).
-Per document staat de herkomst in de datasheet bij de dataset.
+Officiële EuroEval-benchmarkresultaten zijn nog niet gepubliceerd.
+Validatieloss is een trainingsdiagnose en geen benchmarkscore.