Update README.md

README.md

@@ -1,3 +1,107 @@
+---
+license: mit
+language:
+- ar
+pipeline_tag: text-generation
+tags:
+- Arabic_Dialectal_Lemmatization
 ---
-license: mit
----
+# EGY-S2S-lemmatizer
+# Model Description
+
+The model is developed for Arabic dialect lemmatization, focusing on Egyptian (EGY) Arabic. It follows a sequence-to-sequence formulation of lemmatization, where the model generates the lemma of a given word knowing 2 words before and 2 words after the current word rather than treating lemmas as fixed classification labels.
+
+
+The model is evaluated using lemma accuracy as the main metric, with an additional normalized lemma accuracy metric that accounts for orthographic and diacritic variation. The full methodology, training setup, hyperparameters, and evaluation results are described in our paper [“Lemmatizing Dialectal Arabic with Sequence-to-Sequence Models”](https://aclanthology.org/2025.arabicnlp-main.10/)
+
+# Standalone Usage
+
+
+The model can also be used independently without the full lemmatization workflow on the GitHub repository (https://github.com/CAMeL-Lab/seq2seq-arabic-dialect-lemmatization). In this case, the input should contain the target word surrounded by the special token `<target>`, with up to two words before and two words after the target word.
+
+```python
+import re
+import math
+import pandas as pd
+import torch
+from tqdm import tqdm
+from transformers import T5Tokenizer, T5ForConditionalGeneration
+
+DIALECT_MODELS = {
+    "egy": "CAMeL-Lab/EGY-S2S-lemmatizer",
+}
+
+def load_model(s2s_dialect: str):
+    model_name = DIALECT_MODELS[s2s_dialect]
+    tokenizer = T5Tokenizer.from_pretrained(model_name, use_fast=True, legacy=False)
+    model = T5ForConditionalGeneration.from_pretrained(model_name)
+
+    tokenizer.add_special_tokens({"additional_special_tokens": ["<target>"]})
+    model.resize_token_embeddings(len(tokenizer))
+
+    return tokenizer, model
+
+def extract_target_word(text: str) -> str:
+    match = re.search(r"<target>(.*?)<target>", str(text))
+    return match.group(1).strip() if match else ""
+
+def predict(tokenizer, model, texts: list[str], device=None, batch_size: int = 16) -> list[str]:
+    if device is None:
+        device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+    model.to(device).eval()
+    all_preds = []
+    total_batches = math.ceil(len(texts) / batch_size)
+
+    for i in tqdm(range(0, len(texts), batch_size), total=total_batches, desc="Predicting"):
+        batch = texts[i:i + batch_size]
+
+        enc = tokenizer(
+            batch,
+            return_tensors="pt",
+            padding=True,
+            truncation=True,
+            max_length=64
+        )
+        enc = {k: v.to(device) for k, v in enc.items()}
+
+        with torch.no_grad():
+            out = model.generate(
+                **enc,
+                max_length=50,
+                num_beams=1,
+                do_sample=False
+            )
+
+        all_preds.extend(tokenizer.batch_decode(out, skip_special_tokens=True))
+
+    return all_preds
+
+# Example:
+# df should contain an input_text column with the target word marked using <target>
+# Example input: "أنا عايز <target>أروح<target> البيت دلوقتي"
+
+df["word"] = df["input_text"].apply(extract_target_word)
+
+tokenizer, model = load_model("egy")
+df["predicted_lex"] = predict(tokenizer, model, df["input_text"].tolist())
+```
+
+
+## 📖 Citation
+
+
+
+If you use this model in your research, please cite the following paper:
+
+```bibtex
+@inproceedings{saeed-habash-2025-lemmatizing,
+    title = {Lemmatizing Dialectal Arabic with Sequence-to-Sequence Models},
+    author = {Saeed, Mostafa and Habash, Nizar},
+    booktitle = {Proceedings of the Third Arabic Natural Language Processing Conference},
+    year = {2025},
+    address = {Suzhou, China},
+    url = {https://aclanthology.org/2025.arabicnlp-main.10/}
+}
+```
+