docs: revise model card and remove misleading base_model field

Remove base_model: bert-base-uncased from YAML metadata since the
model was pre-trained from scratch, not fine-tuned from bert-base.

README.md

@@ -1,109 +1,84 @@
 ---
+language:
+- ar
 license: apache-2.0
-base_model: bert-base-uncased
 tags:
-- generated_from_trainer
+- bert
+- masked-language-modeling
+- arabic
+- social-media
+- fill-mask
+- pilot
 datasets:
-- nuha-dataset
-model-index:
-- name: nuha-mlm
-  results: []
+- thejosango/nuha-dataset
 ---
 
-<!-- This model card has been generated automatically according to the information the Trainer had access to. You
-should probably proofread and complete it, then remove this comment. -->
-
 # nuha-mlm
 
-This model is a fine-tuned version of [bert-base-uncased](https://huggingface.co/bert-base-uncased) on the nuha-dataset dataset.
-It achieves the following results on the evaluation set:
-- Loss: 5.7881
-
-## Model description
-
-More information needed
-
-## Intended uses & limitations
-
-More information needed
-
-## Training and evaluation data
-
-More information needed
-
-## Training procedure
-
-### Training hyperparameters
-
-The following hyperparameters were used during training:
-- learning_rate: 0.0001
-- train_batch_size: 128
-- eval_batch_size: 128
-- seed: 42
-- optimizer: Adam with betas=(0.9,0.999) and epsilon=1e-08
-- lr_scheduler_type: linear
-- lr_scheduler_warmup_steps: 5000.0
-- num_epochs: 25
-- label_smoothing_factor: 0.1
-
-### Training results
-
-| Training Loss | Epoch | Step  | Validation Loss |
-|:-------------:|:-----:|:-----:|:---------------:|
-| 9.2913        | 0.5   | 500   | 8.9187          |
-| 8.5364        | 1.0   | 1000  | 8.4350          |
-| 8.3161        | 1.51  | 1500  | 8.1825          |
-| 8.1276        | 2.01  | 2000  | 7.9889          |
-| 8.0073        | 2.51  | 2500  | 7.8551          |
-| 7.8206        | 3.01  | 3000  | 7.7101          |
-| 7.7224        | 3.51  | 3500  | 7.6287          |
-| 7.6264        | 4.02  | 4000  | 7.4921          |
-| 7.5062        | 4.52  | 4500  | 7.4265          |
-| 7.408         | 5.02  | 5000  | 7.2955          |
-| 7.2433        | 5.52  | 5500  | 7.1658          |
-| 7.1062        | 6.02  | 6000  | 7.0132          |
-| 6.9815        | 6.53  | 6500  | 6.9592          |
-| 6.9258        | 7.03  | 7000  | 6.8659          |
-| 6.801         | 7.53  | 7500  | 6.7687          |
-| 6.7334        | 8.03  | 8000  | 6.7175          |
-| 6.6422        | 8.53  | 8500  | 6.6583          |
-| 6.5958        | 9.04  | 9000  | 6.5778          |
-| 6.5044        | 9.54  | 9500  | 6.5266          |
-| 6.4488        | 10.04 | 10000 | 6.4990          |
-| 6.3713        | 10.54 | 10500 | 6.4321          |
-| 6.3531        | 11.04 | 11000 | 6.4003          |
-| 6.2718        | 11.55 | 11500 | 6.3708          |
-| 6.2478        | 12.05 | 12000 | 6.2975          |
-| 6.1886        | 12.55 | 12500 | 6.2802          |
-| 6.1405        | 13.05 | 13000 | 6.2521          |
-| 6.0967        | 13.55 | 13500 | 6.1969          |
-| 6.0378        | 14.06 | 14000 | 6.1440          |
-| 5.9893        | 14.56 | 14500 | 6.1456          |
-| 5.9551        | 15.06 | 15000 | 6.1178          |
-| 5.9215        | 15.56 | 15500 | 6.0791          |
-| 5.8603        | 16.06 | 16000 | 6.0696          |
-| 5.7924        | 16.57 | 16500 | 6.0288          |
-| 5.7764        | 17.07 | 17000 | 6.0061          |
-| 5.7545        | 17.57 | 17500 | 5.9600          |
-| 5.7025        | 18.07 | 18000 | 5.9287          |
-| 5.6703        | 18.57 | 18500 | 5.9549          |
-| 5.6887        | 19.08 | 19000 | 5.8808          |
-| 5.629         | 19.58 | 19500 | 5.8967          |
-| 5.6139        | 20.08 | 20000 | 5.8629          |
-| 5.5925        | 20.58 | 20500 | 5.8651          |
-| 5.5506        | 21.08 | 21000 | 5.8567          |
-| 5.5177        | 21.59 | 21500 | 5.8216          |
-| 5.479         | 22.09 | 22000 | 5.8242          |
-| 5.468         | 22.59 | 22500 | 5.8100          |
-| 5.4426        | 23.09 | 23000 | 5.7828          |
-| 5.4648        | 23.59 | 23500 | 5.7881          |
-| 5.4199        | 24.1  | 24000 | 5.8162          |
-| 5.3976        | 24.6  | 24500 | 5.7881          |
-
-
-### Framework versions
-
-- Transformers 4.32.1
-- Pytorch 2.0.1+cu117
-- Datasets 2.14.4
-- Tokenizers 0.13.3
+## Model Summary
+
+`nuha-mlm` is an Arabic BERT model pre-trained from scratch on Jordanian social media text using masked language modelling (MLM). It serves as the domain-adapted base for the NUHA classifier family — [`nuha-binary`](https://huggingface.co/thejosango/nuha-binary) and [`nuha-multiclass`](https://huggingface.co/thejosango/nuha-multiclass) — and was developed as part of a **pilot proof-of-concept** for the NUHA project by the [Jordan Open Source Association (JOSA)](https://josa.ngo).
+
+Starting from a fresh vocabulary trained on the NUHA corpus rather than fine-tuning an existing Arabic BERT, the model is adapted to the vocabulary and linguistic patterns of colloquial Jordanian Arabic social media text.
+
+## Uses
+
+### Direct Use
+
+`nuha-mlm` can be used for masked token prediction on Arabic social media text, or as a base model for fine-tuning downstream Arabic NLP tasks — particularly those involving informal Jordanian or Levantine Arabic.
+
+```python
+from transformers import pipeline
+
+fill_mask = pipeline("fill-mask", model="thejosango/nuha-mlm")
+results = fill_mask("هذه المرأة [MASK] جداً")
+for r in results:
+    print(r["token_str"], r["score"])
+```
+
+### Downstream Use
+
+The primary intended downstream use is fine-tuning for hate speech and gender-based violence detection using the NUHA dataset, as demonstrated by [`nuha-binary`](https://huggingface.co/thejosango/nuha-binary) and [`nuha-multiclass`](https://huggingface.co/thejosango/nuha-multiclass).
+
+### Out-of-Scope Use
+
+This model was pre-trained on a relatively small, domain-specific corpus of Jordanian social media comments. It is not suitable as a general-purpose Arabic language model and should not be used as a replacement for models trained on broader Arabic corpora (e.g. for MSA tasks, translation, or summarisation).
+
+## Bias, Risks, and Limitations
+
+- **Corpus bias**: The pre-training corpus consists entirely of social media comments, many of which contain offensive or harmful language. The model may reflect biases present in that content.
+- **Dialect coverage**: The corpus is primarily Jordanian Arabic. Performance on other Arabic dialects or Modern Standard Arabic is not guaranteed.
+- **Pilot scale**: As part of an initial proof-of-concept effort, the pre-training corpus size and training duration are modest. A larger corpus and longer training would likely yield a stronger base model.
+- **Vocabulary size**: The tokenizer vocabulary (17,513 tokens) was trained specifically on this corpus and is much smaller than general Arabic BERT vocabularies.
+
+## Training Details
+
+### Training Data
+
+Pre-trained on the text portion of the [`thejosango/nuha-dataset`](https://huggingface.co/datasets/thejosango/nuha-dataset) — a corpus of Arabic social media comments collected from Jordanian platforms. The `binary` dataset split was used for pre-training (text only, labels ignored).
+
+### Training Procedure
+
+- **Architecture**: BERT (`BertForMaskedLM`), 12 layers, 12 attention heads, 768 hidden size
+- **Vocabulary**: Custom BPE tokenizer trained from scratch on the corpus (17,513 tokens), with `[URL]` as an added special token
+- **MLM probability**: 15%
+- **Optimizer**: Adam (β₁=0.9, β₂=0.999, ε=1e-8)
+- **Learning rate**: 1e-4 with linear schedule, 5,000 warmup steps
+- **Batch size**: 128
+- **Epochs**: 25
+- **Framework**: Transformers 4.32.1, PyTorch 2.0.1
+
+### Training Results
+
+| Epoch | Validation Loss |
+|---|---|
+| 1 | 8.435 |
+| 5 | 7.296 |
+| 10 | 6.499 |
+| 15 | 6.118 |
+| 20 | 5.863 |
+| 25 | 5.788 |
+
+---
+
+*This model was developed as part of an initial pilot study. It is intended as a stepping stone for the downstream NUHA classifiers rather than as a general-purpose Arabic language model.*