Werk model card bij

README.md

@@ -2,74 +2,156 @@
 language: nl
 license: mit
 base_model: microsoft/mdeberta-v3-base
+pipeline_tag: zero-shot-classification
 tags:
-  - text-classification
   - zero-shot-classification
+  - text-classification
   - natural-language-inference
   - dutch
+  - nederlands
 ---
 
-# NBClas mDeBERTa NLI — Choice & Noul
+# Arlo Classify 1.0
 
-Onderdeel van [NBClas](https://github.com/Noaber-AI/NBClas), een open-source
-Nederlands "System One"-model: snelle, getypeerde beslissingen met een
-confidence score, zonder de latency en kosten van tekstgeneratie.
+**Arlo** is een Nederlandse modelfamilie voor snelle, getypeerde beslissingen.
+Waar een taalmodel tekst genereert die je daarna moet interpreteren, geeft Arlo
+direct een waarde terug waar software mee kan werken — een label, een getal, een
+veld — altijd met een confidence score.
 
-Dit model dekt twee primitieven:
-- **Choice** — kiezen uit een lijst opties, met een kansverdeling per label.
-- **Noul** — een waarheidsgraad (0-1) voor een stelling gegeven een tekst.
+Dit model dekt twee van de vier Arlo-primitieven: **Choice** (kiezen uit opties)
+en **Noul** (hoe waar is een stelling).
 
-Beide draaien op dezelfde NLI-backbone (entailment/neutral/contradiction) en
-werken **zero-shot**: je geeft de labels of stellingen pas op het moment van
-gebruik mee, geen hertraining nodig per taak.
+## Waarom dit anders is dan een taalmodel
 
-Getraind op een NVIDIA A100, op multilinguale NLI-data plus Nederlandse
-domeinspecifieke voorbeelden (overheid, klantenservice).
+Een LLM beantwoordt zo'n vraag door token voor token tekst te genereren. Dat
+kost tijd, kost geld per token, en levert output op die je nog moet parsen —
+met het risico dat er iets terugkomt dat niet in je schema past.
 
-## Gebruik
+Arlo doet per vraag **één forward pass** door een encoder-model van 280M
+parameters. Het genereert niets; het weegt de vraag tegen de tekst en geeft een
+score. Daardoor:
 
-### Standaard — zero-shot classificatie via de transformers-pipeline
+- **snel**: tientallen milliseconden per vraag, ook op een CPU
+- **voorspelbaar**: de uitkomst is altijd een label uit jouw lijst of een getal
+  tussen 0 en 1 — nooit iets daarbuiten
+- **lokaal draaibaar**: geen API-aanroep nodig, dus geschikt voor situaties waar
+  data de deur niet uit mag
+- **zonder tokenkosten**: je draait het zelf
+
+## Gebruik
 
 ```python
-from transformers import pipeline
+from transformers import AutoModel, AutoTokenizer
+
+model = AutoModel.from_pretrained("NoaberAI/arlo-classify", trust_remote_code=True)
+tokenizer = AutoTokenizer.from_pretrained("NoaberAI/arlo-classify")
+```
+
+### Choice — kiezen uit opties
 
-classifier = pipeline("zero-shot-classification", model="NoaberAI/nbclas-mdeberta-nli")
-classifier(
+De opties geef je pas op het moment van gebruik mee. Er is geen hertraining
+nodig om een nieuwe categorie-indeling te gebruiken: je verandert simpelweg de
+lijst.
+
+```python
+model.choice(tokenizer,
     "De put op de Kerkstraat is verstopt.",
-    candidate_labels=["verkeer", "riolering", "afval", "overig"],
-)
+    ["verkeer", "riolering", "afval", "overig"])
+# [{"label": "riolering", "confidence": 0.91},
+#  {"label": "overig",    "confidence": 0.05}, ...]
 ```
 
-### Choice + Noul via de NBClas-wrapper (aanbevolen)
+Voor gevallen waar meerdere labels tegelijk waar kunnen zijn:
 
 ```python
-from src.infer import Classifier  # uit github.com/Noaber-AI/NBClas
+model.choice(tokenizer, tekst, labels, multi_label=True)
+```
 
-clf = Classifier("NoaberAI/nbclas-mdeberta-nli")
+### Noul — hoe waar is deze stelling?
 
-clf.classify(
-    "De put op de Kerkstraat is verstopt.",
-    ["verkeer", "riolering", "afval", "overig"],
-)
-# [{"label": "riolering", "confidence": 0.91}, ...]
+Noul geeft een waarheidsgraad tussen 0 en 1 in plaats van een hard ja/nee, zodat
+je zelf de drempel bepaalt die bij jouw proces past.
 
-clf.noul(
+```python
+model.noul(tokenizer,
     "Er hangt al twee dagen een losse tak dreigend boven het fietspad.",
-    "Dit is een spoedeisende melding.",
-)
-# {"truth": 0.8}
+    "Dit is een spoedeisende melding.")
+# {"truth": 0.85}
+
+model.noul(tokenizer,
+    "Geen haast bij, maar het voetpad bij nummer 12 is wat verzakt.",
+    "Dit is een spoedeisende melding.")
+# {"truth": 0.39}
+```
+
+### Zonder trust_remote_code
+
+Het model is een gewone NLI-classifier, dus de standaardpipeline werkt ook:
+
+```python
+from transformers import pipeline
+
+classifier = pipeline("zero-shot-classification", model="NoaberAI/arlo-classify")
+classifier("De put op de Kerkstraat is verstopt.",
+           candidate_labels=["verkeer", "riolering", "afval"])
 ```
 
-## Voorbeelden
+## Hoe het werkt
+
+Het model is getraind als natural language inference-classifier: het krijgt een
+tekst en een stelling, en bepaalt of die stelling volgt uit de tekst
+(*entailment*), eruit weersproken wordt (*contradiction*), of geen van beide
+(*neutral*).
+
+Beide primitieven bouwen daarop voort:
+
+- **Choice** zet elk label om in een stelling ("Dit gaat over riolering.") en
+  vergelijkt de entailment-scores. Daardoor werkt het zero-shot met elke
+  labelverzameling die je meegeeft.
+- **Noul** neemt je stelling rechtstreeks en normaliseert entailment tegen
+  contradiction tot één waarheidsgraad.
+
+## De Arlo-familie
+
+Arlo bestaat uit drie modellen die samen een complete laag vormen voor
+gestructureerde beslissingen. Ze delen dezelfde backbone-architectuur en
+hetzelfde output-contract — een waarde plus een confidence — en zijn
+onafhankelijk of gecombineerd te gebruiken.
+
+| Model | Primitieven | Waarvoor |
+|---|---|---|
+| **[arlo-classify](https://huggingface.co/NoaberAI/arlo-classify)** | Choice, Noul | categoriseren, routeren, waarheidsvragen |
+| [arlo-score](https://huggingface.co/NoaberAI/arlo-score) | Score | numeriek beoordelen tegen een rubric |
+| [arlo-extract](https://huggingface.co/NoaberAI/arlo-extract) | Extraction | getypeerde velden uit tekst halen |
+
+Eén binnenkomende tekst door alle drie halen geeft in één keer een volledig
+gestructureerd beeld:
 
 ```python
-clf.classify(
-    "Ik wil me graag inschrijven op mijn nieuwe adres.",
-    ["openbare ruimte", "vergunningen", "burgerzaken", "belastingen", "sociaal domein"],
-)
-# [{"label": "burgerzaken", "confidence": 0.9x}, ...]
-
-clf.noul("Geen haast bij, maar het voetpad bij nummer 12 is wat verzakt.",
-         "Dit is een spoedeisende melding.")
-# {"truth": 0.4}  -- lage urgentie correct herkend
+tekst = ("Al drie dagen ligt er een dode boom over het fietspad aan de "
+         "Dorpsstraat, gevaarlijke situatie voor fietsers, graag snel actie.")
+
+classify.choice(tokenizer_c, tekst, ["openbare ruimte", "vergunningen", "burgerzaken"])
+# [{"label": "openbare ruimte", "confidence": 0.99}, ...]
+
+classify.noul(tokenizer_c, tekst, "Dit is een spoedeisende melding.")
+# {"truth": 0.74}
+
+extract.extract(tokenizer_e, tekst, "Waar is het probleem?")
+# {"value": "Dorpsstraat", "confidence": 0.99}
 ```
+
+Van vrije tekst naar een compleet ingevuld formulier, in een fractie van de tijd
+die een taalmodel nodig heeft — en zonder dat er iets te parsen valt.
+
+## Technische details
+
+- **Backbone**: `microsoft/mdeberta-v3-base` (~280M parameters)
+- **Kop**: sequence classification, 3 klassen (entailment / neutral / contradiction)
+- **Taal**: Nederlands
+- **Trainingsdata**: Nederlandse natural language inference-data, aangevuld met
+  domeinspecifieke voorbeelden uit overheid en klantenservice
+- **Hardware**: getraind op een NVIDIA A100
+- **Licentie**: MIT
+
+Gemaakt door [NoaberAI](https://huggingface.co/NoaberAI).