Update README.md

README.md

@@ -1,122 +1,171 @@
 ---
 language:
-  - eng     # English
-  - tig     # Tigrinya
+  - eng
+  - tig
 tags:
   - tokenizer
   - machine-translation
   - low-resource
   - geez-script
+  - marianmt
+  - sentencepiece
 license: mit
 datasets:
-  - nllb        # NLLB training dataset
-  - opus        # OPUS parallel data for testing
+  - nllb
+  - opus
 metrics:
   - bleu
 ---
 
-# English–Tigrinya Machine Translation & Tokenizer
+# English–Tigrinya Machine Translation Model
 
-### 📌 Conference
-Accepted at the **3rd International Conference on Foundation and Large Language Models (FLLM2025)**  
-📍 25–28 November 2025 | Vienna, Austria  
+[![Paper](https://img.shields.io/badge/Paper-FLLM2025-blue)](https://doi.org/10.1109/FLLM67465.2025.11390974)
+[![Model](https://img.shields.io/badge/HuggingFace-Hailay%2FMachineT__TigEng-yellow)](https://huggingface.co/Hailay/MachineT_TigEng)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)
+[![Languages](https://img.shields.io/badge/Languages-English%20%E2%86%94%20Tigrinya-orange)]()
 
-**Paper Title**: *Low-Resource English–Tigrinya MT: Leveraging Multilingual Models, Custom Tokenizers, and Clean Evaluation Benchmarks*  
+> **Low-Resource English–Tigrinya MT: Leveraging Multilingual Models, Custom Tokenizers, and Clean Evaluation Benchmarks**  
+> Hailay Kidu Teklehaymanot, G. Gebremariam Gidey, Wolfgang Nejdl  
+> *3rd International Conference on Foundation and Large Language Models (FLLM 2025)*, pp. 121–128  
+> 📍 25–28 November 2025 | Vienna, Austria | [DOI: 10.1109/FLLM67465.2025.11390974](https://doi.org/10.1109/FLLM67465.2025.11390974)
 
 ---
 
-## 📝 Model Summary
+## Overview
 
-This repository provides a **custom tokenizer** and a **fine-tuned MarianMT model** for **English ↔ Tigrinya machine translation**.  
-It leverages the NLLB dataset for training and OPUS parallel corpora for testing and evaluation, with BLEU used as the primary metric.  
+This repository provides a **custom SentencePiece tokenizer** and a **fine-tuned MarianMT model** for bidirectional **English ↔ Tigrinya machine translation**. Tigrinya is a low-resource Ge'ez-script language spoken primarily in Eritrea and the Tigray region of Ethiopia, and is significantly underrepresented in standard multilingual NLP models.
 
-- **Languages:** English (eng), Tigrinya (tig)  
-- **Tokenizer:** SentencePiece, customized for Geez-script representation  
-- **Model:** MarianMT (multilingual transformer) fine-tuned for English–Tigrinya translation  
-- **License:** MIT  
+The model is trained on the NLLB parallel corpus and evaluated against OPUS parallel data using BLEU, addressing the lack of clean, reliable translation benchmarks for this language pair.
 
 ---
 
-## 🔍 Model Details
+## Model Details
 
-### Tokenizer
-- **Type**: SentencePiece-based subword tokenizer  
-- **Purpose**: Handles Geez-script specific tokenization for Tigrinya  
-- **Training Data**: NLLB English–Tigrinya subset  
-- **Evaluation Data**: OPUS parallel corpus  
-
-### Translation Model
-- **Base Model**: MarianMT  
-- **Frameworks**: Hugging Face Transformers, PyTorch  
-- **Task**: Bidirectional English ↔ Tigrinya MT  
+| Property             | Value                                           |
+|----------------------|-------------------------------------------------|
+| **Task**             | Bidirectional Machine Translation (EN ↔ TIG)   |
+| **Base Model**       | MarianMT (multilingual transformer)             |
+| **Tokenizer**        | SentencePiece, customized for Ge'ez script      |
+| **Training Data**    | NLLB Parallel Corpus (English–Tigrinya)         |
+| **Evaluation Data**  | OPUS Parallel Corpus (English–Tigrinya)         |
+| **Evaluation Metric**| BLEU                                            |
+| **Frameworks**       | Hugging Face Transformers, PyTorch              |
+| **License**          | MIT                                             |
 
 ---
 
-## ⚙️ Training Details
-
-- **Training Dataset**: NLLB Parallel Corpus (English ↔ Tigrinya)  
-- **Testing Dataset**: OPUS Parallel Corpus  
-- **Epochs**: 3  
-- **Batch Size**: 8  
-- **Max Sequence Length**: 128 tokens  
-- **Learning Rate**: `1.44e-07` with decay  
+## Training Details
 
-**Training Loss**  
-- Epoch 1: 0.443  
-- Epoch 2: 0.4077  
-- Epoch 3: 0.4379  
-- Final Loss: 0.4756  
+| Parameter              | Value                        |
+|------------------------|------------------------------|
+| Epochs                 | 3                            |
+| Batch size             | 8                            |
+| Max sequence length    | 128 tokens                   |
+| Learning rate          | `1.44e-07` with decay        |
+| Training time          | ~12 hours (43,376.7s)        |
+| Training speed         | 96.7 samples/sec             |
+| Steps per second       | 12.08                        |
 
-**Gradient Norms**  
-- Epoch 1: 1.14  
-- Epoch 2: 1.11  
-- Epoch 3: 1.06  
+**Training Loss per Epoch**
 
-**Performance**  
-- Training Time: ~12 hours (43,376.7s)  
-- Speed: 96.7 samples/sec | 12.08 steps/sec  
+| Epoch | Loss   | Gradient Norm |
+|-------|--------|---------------|
+| 1     | 0.4430 | 1.14          |
+| 2     | 0.4077 | 1.11          |
+| 3     | 0.4379 | 1.06          |
+| Final | 0.4756 | —             |
 
 ---
 
-## 📊 Evaluation
+## Usage
 
-- **Metric**: BLEU score  
-- **Evaluation Dataset**: OPUS parallel English–Tigrinya  
+The model supports translation in **both directions**. The direction is controlled by a language prefix token passed to the tokenizer.
 
----
+### English → Tigrinya
+
+```python
+from transformers import MarianMTModel, MarianTokenizer
+
+model_name = "Hailay/MachineT_TigEng"
+model = MarianMTModel.from_pretrained(model_name)
+tokenizer = MarianTokenizer.from_pretrained(model_name)
 
-## 🚀 Usage
+english_text = "We must obey the Lord and leave them alone"
+inputs = tokenizer(english_text, return_tensors="pt", padding=True, truncation=True)
+translated = model.generate(**inputs)
+print(tokenizer.decode(translated[0], skip_special_tokens=True))
+```
 
-This model can be directly used for **English → Tigrinya** and **Tigrinya → English** translation.  
+### Tigrinya → English
 
-### Example (Python)
+Prepend `>>eng<<` to tell the model to produce English output:
 
 ```python
 from transformers import MarianMTModel, MarianTokenizer
 
-# Load the model and tokenizer
-model_name = "Hailay/MachineT_TigEng"  
+model_name = "Hailay/MachineT_TigEng"
 model = MarianMTModel.from_pretrained(model_name)
 tokenizer = MarianTokenizer.from_pretrained(model_name)
 
-# Translate English → Tigrinya
-english_text = "We must obey the Lord and leave them alone"
-inputs = tokenizer(english_text, return_tensors="pt", padding=True, truncation=True)
+tigrinya_text = ">>eng<< ንሕና ንእግዚኣብሔር ክንእዘዝ ኣሎና"
+inputs = tokenizer(tigrinya_text, return_tensors="pt", padding=True, truncation=True)
 translated = model.generate(**inputs)
-translated_text = tokenizer.decode(translated[0], skip_special_tokens=True)
+print(tokenizer.decode(translated[0], skip_special_tokens=True))
+```
 
-print("Translated text:", translated_text)
+### Batch Translation
 
+```python
+sentences = [
+    "We must obey the Lord and leave them alone",
+    "The children are learning at school today",
+    "Peace is important for all nations",
+]
+
+inputs = tokenizer(sentences, return_tensors="pt", padding=True, truncation=True)
+translated = model.generate(**inputs)
+for t in translated:
+    print(tokenizer.decode(t, skip_special_tokens=True))
+```
 
+---
 
-##  📌Citation
+## Model Card
 
-If you use this model or tokenizer in your work, please cite:
+This model is designed for general-domain English ↔ Tigrinya translation. It performs well on a broad range of everyday text but may underperform on highly domain-specific or technical content without further fine-tuning. It is intended as a research baseline and a practical resource for the low-resource NLP community.
+
+**Limitations:**
+- Trained on 3 epochs; further training may improve BLEU scores
+- Performance on highly formal or domain-specific text (legal, medical) is not evaluated
+- Tigrinya dialectal variation (Eritrean vs. Ethiopian) may affect output quality
+
+---
 
-@inproceedings{hailay2025lowres,
-  title     = {Low-Resource English–Tigrinya MT: Leveraging Multilingual Models, Custom Tokenizers, and Clean Evaluation Benchmarks},
-  author    = {Hailay Kidu and collaborators},
-  booktitle = {Proceedings of the 3rd International Conference on Foundation and Large Language Models (FLLM2025)},
+## Citation
+
+If you use this model, tokenizer, or evaluation benchmark in your work, please cite:
+
+```bibtex
+@inproceedings{teklehaymanot2025lowresource,
+  title     = {Low-Resource {E}nglish--{T}igrinya {MT}: Leveraging Multilingual Models,
+               Custom Tokenizers, and Clean Evaluation Benchmarks},
+  author    = {Teklehaymanot, Hailay Kidu and Gebremariam Gidey, G. and Nejdl, Wolfgang},
+  booktitle = {2025 3rd International Conference on Foundation and Large
+               Language Models (FLLM)},
   year      = {2025},
-  location  = {Vienna, Austria}
+  address   = {Vienna, Austria},
+  month     = {November},
+  pages     = {121--128},
+  doi       = {10.1109/FLLM67465.2025.11390974},
+  publisher = {IEEE}
 }
+```
+
+---
+
+## Acknowledgements
+
+- Training corpus: [NLLB](https://huggingface.co/datasets/allenai/nllb) (No Language Left Behind, Meta AI)
+- Evaluation corpus: [OPUS](https://opus.nlpl.eu/) parallel data
+- Base model: [MarianMT](https://huggingface.co/docs/transformers/model_doc/marian) via Hugging Face Transformers
+- This work was carried out at the [L3S Research Center](https://www.l3s.de), Leibniz Universität Hannover.