Update model card: Intended Use, Limitations, code example, BibTeX, licence/email/description fixes

README.md

@@ -1,73 +1,117 @@
 ---
 license: cc-by-2.0
 datasets:
-- mbazaNLP/NMT_Tourism_parallel_data_en_kin
 - mbazaNLP/NMT_Education_parallel_data_en_kin
 - mbazaNLP/Kinyarwanda_English_parallel_dataset
+- mbazaNLP/NMT_Tourism_parallel_data_en_kin
 language:
 - en
 - rw
 library_name: transformers
-
 pipeline_tag: translation
+tags:
+- ctranslate2
+- quantized
+- int8
+- education
 ---
-## Model Details
 
-### Model Description
+# Quantized_Nllb_Finetuned_Edu_En_Kin_8bit — English ↔ Kinyarwanda (Education, 8-bit)
 
-<!-- Provide a longer summary of what this model is. -->
+8-bit quantized machine translation model for English ↔ Kinyarwanda, specialised for
+**education-domain** content.
 
-This is a Machine Translation model, finetuned from [NLLB](https://huggingface.co/facebook/nllb-200-distilled-1.3B)-200's distilled 1.3B model, it is meant to be used in machine translation for education-related data.
+Fine-tuned from [facebook/nllb-200-distilled-1.3B](https://huggingface.co/facebook/nllb-200-distilled-1.3B)
+and quantized to int8 using [CTranslate2](https://github.com/OpenNMT/CTranslate2).
 
-- **Finetuning code repository:** the code used to finetune this model can be found [here](https://github.com/Digital-Umuganda/twb_nllb_finetuning)
+**Fine-tuning code:** [Digital-Umuganda/twb_nllb_finetuning](https://github.com/Digital-Umuganda/twb_nllb_finetuning)
 
-## Quantization details
+## Quantization
 
-The model is quantized to 8-bit precision using the Ctranslate2 library.
-```
+```bash
 pip install ctranslate2
-```
-Using the command: 
-```
-ct2-transformers-converter --model <model-dir> --quantization int8 --output_dir <output-model-dir>
+ct2-transformers-converter --model <source-model-dir> --quantization int8 --output_dir <output-dir>
 ```
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+## Usage
 
+```python
+import ctranslate2
+from transformers import NllbTokenizer
 
-## How to Get Started with the Model
+tokenizer = NllbTokenizer.from_pretrained("facebook/nllb-200-distilled-1.3B")
+translator = ctranslate2.Translator("path/to/Quantized_Nllb_Finetuned_Edu_En_Kin_8bit")
 
-Use the code below to get started with the model.
 
+def translate(text: str, src_lang: str, tgt_lang: str) -> str:
+    tokenizer.src_lang = src_lang
+    tokens = tokenizer.convert_ids_to_tokens(tokenizer.encode(text))
+    results = translator.translate_batch([tokens], target_prefix=[[tgt_lang]])
+    target_ids = tokenizer.convert_tokens_to_ids(results[0].hypotheses[0][1:])
+    return tokenizer.decode(target_ids, skip_special_tokens=True)
 
-### Training Procedure 
 
-The model was finetuned on three datasets; a [general](https://huggingface.co/datasets/mbazaNLP/Kinyarwanda_English_parallel_dataset) purpose dataset, a [tourism](https://huggingface.co/datasets/mbazaNLP/NMT_Tourism_parallel_data_en_kin), and an [education](https://huggingface.co/datasets/mbazaNLP/NMT_Education_parallel_data_en_kin) dataset.
+print(translate("Education is the key to development.", "eng_Latn", "kin_Latn"))
+print(translate("Uburezi ni urufunguzo rw'iterambere.", "kin_Latn", "eng_Latn"))
+```
 
-The model was finetuned in two phases.
+## Intended Use
 
-#### Phase one:
-- General purpose dataset
-- Education dataset
-- Tourism dataset
+**Suitable for:**
+- Education-domain English ↔ Kinyarwanda translation
+- Resource-constrained or edge deployments where model size matters
+- EdTech applications for Rwanda
 
-#### Phase two:
-- Education dataset
+**Not intended for:**
+- General-purpose or tourism translation
+- High-stakes translation without human review
 
-Other than the dataset changes between phase one, and phase two finetuning; no other hyperparameters were modified. In both cases, the model was trained on an A100 40GB GPU for two epochs.
+## Training
 
+Fine-tuned in two phases on education and general parallel data; then quantized to int8.
+See [Nllb_finetuned_education_en_kin](https://huggingface.co/mbazaNLP/Nllb_finetuned_education_en_kin)
+for full training details.
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
+Results from the full-precision base model (8-bit quantization introduces minor degradation):
 
+| Lang. Direction | BLEU  | spBLEU | chrF++ | TER   |
+|-----------------|-------|--------|--------|-------|
+| Eng → Kin       | 45.96 | 59.20  | 68.79  | 41.61 |
+| Kin → Eng       | 43.98 | 44.94  | 63.05  | 41.41 |
 
+<!-- TODO: add quantized model evaluation scores -->
 
-<!-- This should link to a Data Card if possible. -->
+## Limitations
 
+- 8-bit quantization may introduce minor accuracy degradation versus the full-precision model.
+- Domain-adapted for education content; quality may drop on out-of-domain text.
+- Outputs should be reviewed for high-stakes use cases.
 
-#### Metrics
+## Bias and Fairness
 
-Model performance was measured using BLEU, spBLEU, TER, and chrF++ metrics.
+Training data reflects written, formal educational language. Colloquial Kinyarwanda may be translated with lower quality.
 
-### Results
+## Bias and Fairness
+
+Machine translation models can reflect and amplify biases present in training data. Known limitations include:
+
+- **Domain bias:** Fine-tuned on specific domain data; performance may be lower on out-of-domain text.
+- **Cultural bias:** Idiomatic expressions, gender-neutral constructs, and culturally specific references in English may not translate accurately or naturally into Kinyarwanda.
+- **Data source bias:** Training data was sourced from specific platforms; text from other sources or registers may yield lower quality translations.
+- **Gender:** English gender-neutral pronouns may be rendered with gendered forms in Kinyarwanda based on distributional patterns in training data.
+
+Validate translation quality on domain-representative samples before deployment in high-stakes contexts (legal, medical, government communications).
+
+## Citation
+
+```bibtex
+@misc{mbazaNLP2023quantized_nllb_edu,
+  author    = {MBAZA-NLP Community},
+  title     = {Quantized {NLLB} Finetuned Education En-Kin 8bit},
+  year      = {2023},
+  url       = {https://huggingface.co/mbazaNLP/Quantized_Nllb_Finetuned_Edu_En_Kin_8bit},
+  note      = {Hugging Face model repository}
+}
+```