Update README.md

README.md

@@ -1,3 +1,192 @@
----
-license: mit
----
+---
+language:
+- ar
+license: mit
+tags:
+- arabic
+- punctuation-restoration
+- token-classification
+- xlm-roberta
+- natural-language-processing
+pipeline_tag: token-classification
+base_model: xlm-roberta-large
+model-index:
+- name: Naqta
+  results:
+  - task:
+      type: token-classification
+      name: Arabic Punctuation Restoration
+    dataset:
+      name: Mixed Arabic punctuation restoration corpus
+      type: custom
+    metrics:
+    - type: f1
+      value: 0.8176
+      name: Validation Macro F1
+    - type: accuracy
+      value: 0.9589
+      name: Validation Accuracy
+---
+
+# Naqta
+
+**Naqta** is an Arabic punctuation restoration model. It predicts missing punctuation marks in unpunctuated Arabic text using token-level sequence classification.
+
+The model is designed to restore the following punctuation marks:
+
+| Label | Meaning |
+|---|---|
+| `O` | No punctuation |
+| `.` | Period |
+| `،` | Arabic comma |
+| `؟` | Arabic question mark |
+| `!` | Exclamation mark |
+| `:` | Colon |
+| `؛` | Arabic semicolon |
+| `-` | Dash |
+
+## Model Details
+
+- **Model name:** Naqta
+- **Task:** Arabic punctuation restoration
+- **Architecture:** XLM-RoBERTa Large for token classification
+- **Base model:** `xlm-roberta-large`
+- **Maximum sequence length:** 384 tokens
+- **Training objective:** token-level punctuation classification
+- **Loss:** weighted focal loss during fine-tuning
+- **Focal gamma:** 2.0
+
+## Training Summary
+
+Naqta was trained on a mixed Arabic corpus built from multiple sources, including books, Arabic corpora, Wikipedia-style text, and question-answering data. The training pipeline used sliding-window context, class balancing, rare punctuation oversampling, and a two-phase training strategy.
+
+### Training Strategy
+
+| Phase | Description |
+|---|---|
+| Phase 1 | General token-classification training for 2 epochs |
+| Phase 2 | Focal-loss fine-tuning for 2 epochs with lower encoder layers frozen |
+
+### Data Balancing
+
+The final training setup used stronger sampling for rare punctuation marks:
+
+- Strong rare marks: `؟`, `!`
+- Light rare marks: `؛`, `-`
+- Sliding-window context was applied to training data only
+- Validation and test data remained unwindowed to avoid leakage
+
+## Validation Results
+
+Final best validation result:
+
+| Metric | Score |
+|---|---:|
+| **Macro F1** | **0.8176** |
+| Accuracy | 0.9589 |
+
+### Per-Class Validation F1
+
+| Class | F1 |
+|---|---:|
+| `!` | 0.6512 |
+| `؛` | 0.7180 |
+| `؟` | 0.9066 |
+| `-` | 0.8562 |
+| `،` | 0.7422 |
+| `.` | 0.8030 |
+
+## Example
+
+Input:
+
+```text
+اذا اردت ان تنجح في حياتك فعليك ان تفتح اهدافك واضحة وان تعمل بجد واستمرارية ولا تيأس عند اول عقبة تواجهها
+```
+
+Possible output:
+
+```text
+اذا اردت ان تنجح في حياتك، فعليك ان تفتح اهدافك واضحة، وان تعمل بجد واستمرارية، ولا تيأس عند اول عقبة تواجهها.
+```
+
+## Usage
+
+```python
+from transformers import AutoTokenizer, AutoModelForTokenClassification
+import torch
+
+repo_id = "MostafaMaroof/Naqta"
+
+tokenizer = AutoTokenizer.from_pretrained(repo_id)
+model = AutoModelForTokenClassification.from_pretrained(repo_id)
+model.eval()
+
+id2label = model.config.id2label
+
+text = "بلغت نسبة النمو الاقتصادي 4.7 بالمئة خلال الربع الثالث من عام 2024 وهو اعلى مستوى منذ خمس سنوات"
+words = text.split()
+
+inputs = tokenizer(
+    words,
+    is_split_into_words=True,
+    return_tensors="pt",
+    truncation=True,
+    max_length=384,
+)
+
+with torch.no_grad():
+    logits = model(**inputs).logits
+
+pred_ids = logits.argmax(dim=-1)[0].tolist()
+word_ids = inputs.word_ids(batch_index=0)
+
+restored_words = []
+previous_word_id = None
+for token_id, word_id in zip(pred_ids, word_ids):
+    if word_id is None or word_id == previous_word_id:
+        continue
+
+    word = words[word_id]
+    label = id2label[token_id]
+    if label != "O":
+        word = word + label
+    restored_words.append(word)
+    previous_word_id = word_id
+
+restored_text = " ".join(restored_words)
+print(restored_text)
+```
+
+## Intended Use
+
+Naqta can be used for:
+
+- Restoring punctuation in Arabic ASR transcripts
+- Improving readability of unpunctuated Arabic text
+- Preprocessing Arabic text for downstream NLP tasks
+- Educational or research applications involving Arabic punctuation
+
+## Limitations
+
+- Punctuation restoration is partly stylistic, so multiple outputs may be valid.
+- The model may over-insert commas in long literary or formal sentences.
+- Very short or fragmented text may produce less reliable punctuation.
+- Domain-specific text, such as legal, medical, or highly dialectal content, may require additional fine-tuning.
+- The model predicts punctuation after words and does not perform full grammar correction.
+
+## Training Notes
+
+The model was optimized to improve rare punctuation classes, especially `!`, `؟`, `؛`, and `-`. The final configuration achieved a validation Macro F1 above 0.81, with especially strong performance on question marks and dashes.
+
+## License
+
+This model is released under the MIT License.
+
+## Citation
+
+If you use this model, please cite or reference the Hugging Face repository:
+
+```text
+MostafaMaroof/Naqta
+```