Add model card

README.md

@@ -0,0 +1,154 @@
+---
+license: cc-by-sa-4.0
+base_model: itzune/gector-eus-v2
+language: eu
+pipeline_tag: token-classification
+tags:
+  - grammatical-error-correction
+  - gector
+  - basque
+  - euskara
+  - seq2edit
+  - error-type-classification
+  - multitask
+  - onnx
+  - in-browser
+library_name: onnx
+---
+
+# GECToR v2 ONNX — In-browser Basque Grammatical Error Correction
+
+**int4-quantized ONNX** version of [`itzune/gector-eus-v2`](https://huggingface.co/itzune/gector-eus-v2)
+for in-browser/edge deployment via ONNX Runtime Web (WASM) or
+Transformers.js. ~83 MB download, ~50-100ms per sentence, runs on all
+browsers (no WebGPU required).
+
+This is the **explainable** GEC model — it outputs both corrections **and**
+error-type labels (spelling, morphology, punctuation, etc.) per token,
+enabling rich linting UIs like [txukun](https://github.com/itzune/txukun).
+
+## Model details
+
+| | |
+|---|---|
+| **Architecture** | GECToR (RoBERTa-eus-base encoder + 3 heads: edit-label, detect, type) |
+| **Source model** | [`itzune/gector-eus-v2`](https://huggingface.co/itzune/gector-eus-v2) |
+| **Quantization** | int4 MatMul weights + int8 embeddings (via onnxruntime) |
+| **Model size** | 83 MB (int4) / 128 MB (int8 fallback) |
+| **License** | CC-BY-SA 4.0 |
+| **Error types** | `none, spelling, punctuation, capitalization, word_level, zalantza, morphology, proper_noun, calque` |
+
+## ONNX outputs
+
+The model takes `input_ids` + `attention_mask` and returns three logit tensors:
+
+| Output | Shape | Description |
+|--------|-------|-------------|
+| `logits_labels` | `[batch, seq_len, 5000]` | Edit-label logits (GECToR tag vocabulary) |
+| `logits_d` | `[batch, seq_len, 2]` | Detection logits (correct / incorrect) |
+| `logits_t` | `[batch, seq_len, 9]` | Error-type logits (8 types + none) |
+
+The `logits_t` output is **new in v2** — v1 only had `logits_labels` and
+`logits_d`. This enables per-token error-type classification in the browser.
+
+## File structure
+
+```
+gector-eus-v2-onnx/
+├── onnx/
+│   ├── model_q4.onnx              # int4 (83 MB) — primary browser model
+│   └── model_quantized.onnx       # int8 (128 MB) — fallback
+├── gector_vocab.json              # label vocabulary + type vocab + config
+├── tokenizer.json                 # HF tokenizer (for AutoTokenizer)
+├── sentencepiece.bpe.model        # SentencePiece model
+├── tokenizer_config.json
+├── special_tokens_map.json
+├── config.json                    # model config (reference)
+├── README.md
+└── LICENSE
+```
+
+## Usage (browser)
+
+```javascript
+import { AutoTokenizer } from '@huggingface/transformers';
+import { InferenceSession, Tensor } from 'onnxruntime-web';
+
+const REPO = 'itzune/gector-eus-v2-onnx';
+const BASE = `https://huggingface.co/${REPO}/resolve/main`;
+
+// Load tokenizer, vocab, and model
+const [tokenizer, vocab, modelBuf] = await Promise.all([
+  AutoTokenizer.from_pretrained(REPO),
+  fetch(`${BASE}/gector_vocab.json`).then(r => r.json()),
+  fetch(`${BASE}/onnx/model_q4.onnx`).then(r => r.arrayBuffer()),
+]);
+
+const session = await InferenceSession.create(modelBuf, {
+  executionProviders: ['wasm'],
+});
+
+// Tokenize (pre-tokenized input: punctuation split from words)
+const words = 'Ni uste hiru hilabetez ohean egoteak eragin zidala .'.split(' ');
+const enc = tokenizer(words, { add_special_tokens: true, padding: true, truncation: true });
+
+// Run inference
+const outputs = await session.run({
+  input_ids: new Tensor('int64', enc.input_ids.data, enc.input_ids.dims),
+  attention_mask: new Tensor('int64', enc.attention_mask.data, enc.attention_mask.dims),
+});
+
+// outputs.logits_labels  → [batch, seq_len, 5000] edit labels
+// outputs.logits_d       → [batch, seq_len, 2] detection
+// outputs.logits_t       → [batch, seq_len, 9] error types (NEW)
+```
+
+See [`txukun/src/gector.js`](https://github.com/itzune/txukun/blob/main/src/gector.js)
+for a full production implementation with iterative correction, verb-form
+reinflection, and error-type surfacing.
+
+## Evaluation
+
+See [`itzune/gector-eus-v2`](https://huggingface.co/itzune/gector-eus-v2) for
+full evaluation results. Summary:
+
+| Metric | Value |
+|--------|-------|
+| F0.5 (correction) | 77.6 |
+| Exact match | 51.3% |
+| Clean FP | 1.8% |
+| Type accuracy (error words) | 75.8% |
+
+Quantization (int4) has negligible impact on accuracy — the model is
+robust to 4-bit weight quantization due to the large label vocabulary
+(5000 labels) being stored in full precision.
+
+## Comparison with v1 ONNX
+
+| | v1 (`gector-eus-onnx`) | **v2** (`gector-eus-v2-onnx`) |
+|---|---|---|
+| Error types | ❌ no type head | ✅ 8 categories |
+| Model size | 87 MB | 83 MB |
+| Training data | Elhuyar (NC license) | horkonpon (CC-BY-SA) |
+| License | CC-BY-NC-SA 4.0 | **CC-BY-SA 4.0** (commercial OK) |
+| Outputs | `logits_labels`, `logits_d` | + `logits_t` (error types) |
+
+## Citation
+
+```bibtex
+@misc{ezpeleta2026gectoreusv2onnx,
+  author       = {Ezpeleta, Xabi},
+  title        = {GECToR v2 ONNX: In-browser Basque Grammatical Error Correction},
+  year         = {2026},
+  howpublished = {Hugging Face model},
+  url          = {https://huggingface.co/itzune/gector-eus-v2-onnx}
+}
+```
+
+## Related
+
+- [itzune/gector-eus-v2](https://huggingface.co/itzune/gector-eus-v2) — source PyTorch model
+- [itzune/gector-eus-onnx](https://huggingface.co/itzune/gector-eus-onnx) — v1 ONNX (no type head, NC license)
+- [itzune/gemma-4-e4b-horkonpon](https://huggingface.co/itzune/gemma-4-e4b-horkonpon) — LLM-based Basque GEC
+- [horkonpon-corpus](https://github.com/itzune/horkonpon-corpus) — training data
+- [txukun](https://github.com/itzune/txukun) — Basque writing assistant (consumes this model)