Add model card

README.md

@@ -1,199 +1,251 @@
 ---
+language:
+  - ary
+  - ar
+license: cc-by-nc-4.0
 library_name: transformers
-tags: []
+pipeline_tag: token-classification
+base_model: SI2M-Lab/DarijaBERT
+tags:
+  - part-of-speech
+  - pos-tagging
+  - token-classification
+  - moroccan-darija
+  - darija
+  - low-resource-languages
+  - bert
+metrics:
+  - precision
+  - recall
+  - f1
+  - accuracy
+model-index:
+  - name: DarijaPOSTagger v0.1 (preliminary)
+    results:
+      - task:
+          type: token-classification
+          name: Part-of-Speech Tagging
+        dataset:
+          name: Darija POS corpus (validation split, dev+test merged)
+          type: darija-pos-corpus
+        metrics:
+          - type: f1
+            value: 0.9999
+            name: Seqeval F1 (validation)
+          - type: accuracy
+            value: 0.9999
+            name: Token accuracy (validation)
+widget:
+  - text: "شربت أتاي مع صحابي"
+    example_title: "Simple sentence (verb + nouns)"
+  - text: "غادي نمشي للسوق غدا"
+    example_title: "Future (غادي + verb)"
+  - text: "ما عند ي ش الفلوس"
+    example_title: "Negation, clitic-segmented (ما … ش)"
 ---
 
-# Model Card for Model ID
+# DarijaPOSTagger (v0.1) — Part-of-Speech Tagging for Moroccan Darija
 
-<!-- Provide a quick summary of what the model is/does. -->
+> 🚧 **Preliminary release (v0.1) — for education & research.** This model was trained on a small corpus (1,225 sentences) and released early, with its limitations openly documented, as a teaching artifact and a baseline for the Darija NLP community. Read the [Preliminary Validation](#preliminary-validation-july-2026) and [Known Limitations](#known-limitations--bias) sections before using it. Not intended for production use.
 
+**DarijaPOSTagger** is a BERT-based token classification model that assigns **part-of-speech (POS) tags** to **Moroccan Darija** text (Moroccan Arabic dialect, Arabic script). It is fine-tuned from [SI2M-Lab/DarijaBERT](https://huggingface.co/SI2M-Lab/DarijaBERT) on a manually POS-annotated Darija corpus, using a 15-tag tagset adapted to Darija morphology — including dialect-specific particles such as the progressive **كي** (`PROG_PART`), the future marker **غادي** (`FUT_PART`), and the discontinuous negation **ما … ش** (`NEG_PART`).
 
+The model is released by [Typica.ai](https://typica.ai) as part of its applied research on **culturally localized AI for underserved languages**, and is **open-sourced for educational and research purposes**. It complements Typica.ai's Darija NLP suite (NER, sentiment, toxicity detection).
 
 ## Model Details
 
-### Model Description
-
-<!-- Provide a longer summary of what this model is. -->
-
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
-
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
-
-### Model Sources [optional]
-
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
-
-## Uses
-
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
-### Direct Use
-
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
-
-[More Information Needed]
-
-### Downstream Use [optional]
-
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
-
-### Out-of-Scope Use
-
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
-
-[More Information Needed]
-
-## Bias, Risks, and Limitations
-
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
-
-### Recommendations
-
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
-
-## How to Get Started with the Model
-
-Use the code below to get started with the model.
-
-[More Information Needed]
-
-## Training Details
-
-### Training Data
-
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
-
-### Training Procedure
-
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
-
-
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
+| | |
+|---|---|
+| **Developed by** | Hicham Assoudi — Typica.ai |
+| **Model type** | BERT-based token classification (POS tagging) |
+| **Language** | Moroccan Darija (`ary`), Arabic script |
+| **Base model** | [SI2M-Lab/DarijaBERT](https://huggingface.co/SI2M-Lab/DarijaBERT) |
+| **License** | CC BY-NC 4.0 (non-commercial — education & research) |
+| **Version** | v0.1 (preliminary) |
+| **Released** | July 2026 |
+| **Contact** | assoudi@typica.ai |
+
+### Tagset (15 tags)
+
+| Tag | Meaning | Example (Darija) |
+|-----|---------|------------------|
+| `NOUN` | Noun | الولد، السوق، الفلوس |
+| `V` | Verb | مشيت، كيلعب، نمشي |
+| `ADJ` | Adjective | زوين، كبير |
+| `ADV` | Adverb | غدا، بزاف، دابا |
+| `PRON` | Pronoun | هو، ديالي، ها |
+| `DET` | Determiner | ال، هاد، واحد |
+| `PREP` | Preposition | ف، ل، على، من |
+| `CONJ` | Conjunction | و، ولكن، حيت |
+| `PART` | Particle (general) | را، واش |
+| `PROG_PART` | Progressive/aspectual particle | كي، تا (كيلعب) |
+| `FUT_PART` | Future particle | غادي، غا (غادي نمشي) |
+| `NEG_PART` | Negation particle | ما، ش (ما عندي ش) |
+| `NSUFF` | Noun suffix (inflection) | ة، ات، ين |
+| `CASE` | Case marker | — |
+| `O` | Other (punctuation, numbers, URLs, mentions, emoticons, foreign tokens) | — |
+
+## Intended Uses
+
+**Direct intended uses:**
+- Research on morphosyntactic analysis of Moroccan Darija and Arabic dialects.
+- Education: teaching token classification, subword/label alignment, and fine-tuning for low-resource languages.
+- Preprocessing component in Darija NLP pipelines (e.g., feature extraction, chunking, linguistic annotation, corpus building).
+
+**Out-of-scope uses:**
+- ❌ Commercial deployment without a separate agreement with Typica.ai (license is non-commercial).
+- ❌ Latin-script Darija (Arabizi), French, or English text: non-Arabic tokens were cleaned from training data.
+- ❌ Modern Standard Arabic or other Arabic dialects — the tagset and training data are Darija-specific.
+
+## How to Use
+
+```python
+from transformers import pipeline
+
+pos_tagger = pipeline(
+    "token-classification",
+    model="TypicaAI/DarijaPOSTagger",
+    aggregation_strategy="first",
+    ignore_labels=[],   # important: show 'O' predictions too (POS ≠ NER — every word needs a tag)
+)
+
+sentences = [
+    "غادي نمشي للسوق غدا",          # I will go to the market tomorrow
+    "شربت أتاي مع صحابي",           # I drank tea with my friends
+    "ما عنديش الفلوس",              # I don't have money
+]
+
+for sentence in sentences:
+    print(f"\n{sentence}")
+    for token in pos_tagger(sentence):
+        print(f"  {token['word']:<15} → {token['entity_group']:<10} ({token['score']:.3f})")
+```
+
+> ℹ️ **Input format matters.** The training corpus is *morpheme-segmented* (clitics like ال، ف، كي، ش appear as separate tokens), while raw Darija text fuses them into surface words (فالزنقة، عنديش). The model is noticeably more reliable on clitic-segmented input; on raw text, expect degraded accuracy on fused forms (see Preliminary Validation below). Also note that `aggregation_strategy` may merge adjacent same-label words into one span — for strict one-tag-per-word output, tokenize with `is_split_into_words=True` and read per-word predictions directly.
+
+## Training Data
+
+The model was trained on a manually POS-annotated Moroccan Darija corpus in CoNLL-style format (one `token  tag` pair per line, sentences separated by `EOS` markers).
+
+**Preprocessing:**
+- Tokens were cleaned with a character filter keeping Arabic script, digits, and basic punctuation.
+- The original 22-tag scheme was simplified to 15 tags: formatting and non-linguistic tags (`WB`, `TB`, `EMOT`, `HASH`, `FOREIGN`, `MENTION`, `PUNC`, `URL`, `NUM`) were collapsed into a single `O` class, keeping the tagset focused on linguistically meaningful categories.
+- Subword/label alignment: only the first subword of each word receives the word's label during tokenization (WordPiece), with special tokens masked at `-100`.
+
+### Splits
+
+| Split | Sentences | Used for |
+|-------|----------:|----------|
+| Train | 1,225 | Fine-tuning |
+| Dev | 175 | — |
+| Test | 350 | — |
+| Validation (dev + test merged) | 525 | Evaluation during training |
+
+## Training Procedure
+
+- **Base checkpoint:** `SI2M-Lab/DarijaBERT` with a freshly initialized token classification head (15 labels)
+- **Objective:** token-level cross-entropy (seqeval-based evaluation)
+- **Hardware:** single T4 GPU (Google Colab)
+
+**Hyperparameters:**
+
+| Hyperparameter | Value |
+|---|---|
+| Learning rate | 2e-5 |
+| Epochs | 10 |
+| Weight decay | 0.01 |
+| Eval/save strategy | per epoch |
+| Data collator | `DataCollatorForTokenClassification` (dynamic padding) |
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
-
-#### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
-
-### Results
-
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
+### Quantitative (in-corpus)
 
-[More Information Needed]
+On the validation split (525 sentences, dev + test merged), the model converges to near-perfect seqeval scores:
 
-### Compute Infrastructure
+| Metric | Score |
+|---|---:|
+| Precision | ≈ 0.9999 |
+| Recall | ≈ 0.9999 |
+| F1 | ≈ 0.9999 |
+| Token accuracy | ≈ 0.9999 |
 
-[More Information Needed]
+> ⚠️ **Interpret with care.** The validation set is small, merges the original dev and test splits, and was used for checkpoint selection during training — it is not a clean held-out test set. Near-perfect scores reflect in-corpus fit on a small, homogeneous, morpheme-segmented corpus — not expected real-world accuracy. The qualitative validation below gives a more realistic picture.
 
-#### Hardware
+### Preliminary Validation (July 2026)
 
-[More Information Needed]
+Manual spot-checks on **raw (unsegmented) everyday Darija sentences** — a harder condition than the segmented training data — showed a consistent pattern:
 
-#### Software
+**What works well** — open-class words in canonical surface forms are tagged reliably, typically at ≥ 0.99 confidence:
 
-[More Information Needed]
+| Word | Predicted | Confidence |
+|---|---|---:|
+| كيلعب | V | 1.000 |
+| نمشي | V | 1.000 |
+| شربت | V | 1.000 |
+| غدا | ADV | 0.989 |
+| الفلوس | NOUN | 0.998 |
+| للسوق | NOUN | 0.999 |
 
-## Citation [optional]
+**Known error patterns on raw text:**
 
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+| Input | Predicted | Expected | Likely cause |
+|---|---|---|---|
+| الولد | O (0.512) | DET+NOUN | Fused article ال unseen as one token |
+| عنديش | ADV (0.582) | PREP+PRON+NEG_PART | Fused clitics (عند+ي+ش) unseen as one token |
+| فالزنقة | (merged into NOUN span) | PREP+DET+NOUN | Fused preposition ف lost |
+| غادي | PART (0.988) | FUT_PART | Closed-class near-miss |
+| مع | CONJ (0.996) | PREP | Closed-class confusion, confidently wrong |
 
-**BibTeX:**
+**Root cause:** a train/inference input mismatch. The corpus is morpheme-segmented (clitics as separate tokens — hence the `NSUFF` tag and clitic-level `NEG_PART`), so fused surface words are out-of-distribution at inference. Low confidence (≈ 0.5) on fused forms is a useful signal of this. Note also that closed-class errors (مع → CONJ) can be high-confidence, so confidence alone is not a reliability guarantee.
 
-[More Information Needed]
+**Planned for v0.2:** an independent held-out evaluation on raw text, and either a paired rule-based clitic segmenter or retraining on de-segmented surface-word data.
 
-**APA:**
+## Known Limitations & Bias
 
-[More Information Needed]
+- **Preliminary release:** v0.1 is an educational baseline, not a production tagger. Error patterns above are documented, not yet fixed.
+- **Segmentation mismatch:** best results require clitic-segmented input; raw text degrades accuracy on fused forms (fused articles, prepositions, and negation clitics).
+- **Small training corpus:** 1,225 training sentences; limited coverage of rare constructions, regional sub-dialects, and domain vocabulary.
+- **In-corpus evaluation:** the quantitative metrics overestimate real-world performance (see Evaluation).
+- **Closed-class confusions:** some function words (e.g., مع، غادي) can be tagged incorrectly with high confidence.
+- **Script coverage:** Arabic script only; Arabizi/Latin-script Darija is out of scope.
+- **Tag granularity:** numbers, punctuation, URLs, mentions, and foreign words are collapsed into `O`.
 
-## Glossary [optional]
+## Citation
 
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+No dedicated paper accompanies this model yet. If you use it, please cite the model directly:
 
-[More Information Needed]
+```bibtex
+@misc{assoudi2026darijapostagger,
+  title        = {DarijaPOSTagger v0.1: Part-of-Speech Tagging for Moroccan Darija (Preliminary Release)},
+  author       = {Assoudi, Hicham},
+  year         = {2026},
+  month        = {July},
+  publisher    = {Hugging Face},
+  organization = {Typica.ai},
+  url          = {https://huggingface.co/TypicaAI/DarijaPOSTagger}
+}
+```
 
-## More Information [optional]
+Please also cite the base model:
 
-[More Information Needed]
+```bibtex
+@article{gaanoun2023darijabert,
+  title   = {DarijaBERT: a step forward in NLP for the written Moroccan dialect},
+  author  = {Gaanoun, Kamel and Naira, Abdou Mohamed and Allak, Anass and Benelallam, Imade},
+  journal = {International Journal of Data Science and Analytics},
+  year    = {2023},
+  doi     = {10.1007/s41060-023-00498-2}
+}
+```
 
-## Model Card Authors [optional]
+## Related Models by Typica.ai
 
-[More Information Needed]
+- [MAGBERT-NER](https://huggingface.co/TypicaAI/magbert-ner) — Named Entity Recognition for Moroccan Darija/French
+- Darija Toxicity Detection — culturally grounded content moderation (see [arXiv:2505.04640](https://arxiv.org/abs/2505.04640))
 
-## Model Card Contact
+## Contact
 
-[More Information Needed]
+**Hicham Assoudi** — Founder & Applied AI Researcher, Typica.ai · PhD (AI/NLP)
+*Typica.ai* — Independent applied research initiative
+📧 assoudi@typica.ai · [Linkedin](https://www.linkedin.com/in/assoudi) . 🌐 [typica.ai](https://typica.ai) · 🤗 [TypicaAI on Hugging Face](https://huggingface.co/TypicaAI)