ameer4wisam/iraqi_words_finetuning

Iraqi Words

A manually compiled Iraqi Arabic dialect lexicon (930 terms, 50 categories) with a dependency-free BM25 retriever and a fine-tuning data generator built on top of it.

Why this exists

Iraqi Arabic is under-represented in NLP relative to Modern Standard Arabic (MSA) and higher-resource dialects such as Egyptian or Levantine. Lexical resources that map Iraqi terms to their MSA meanings — the kind needed to ground retrieval or instruction-tuning for dialect understanding — are scarce. This repository provides one such resource, along with tooling to search it and to turn it into fine-tuning data.

What's in this repository

• —`word.json` — the lexicon: 930 Iraqi Arabic terms across 50 categories, each with an MSA gloss.
• —`lexicon.jsonl` — the same 930 terms flattened to one {word, meaning, category} record per line. This is what the Hugging Face dataset viewer loads; word.json keeps the nested-by-category structure the code in rag/ and fine_tuning/ reads.
• —`rag/` — a BM25 retriever over the lexicon with no external dependencies (pure Python standard library), plus prepare_rag.py to build the document index. This is a genuine practical advantage if you want to embed dialect lookup into a service without pulling in a search or vector-DB dependency.
• —`fine_tuning/` — prepare_finetuning.py, which generates chat- and Alpaca-format training data from the lexicon (word↔meaning pairs and category-based questions only — no dialogues), and train.py, a LoRA fine-tuning script.
• —`train.json` — a hand-written seed of 270 Iraqi Q/A examples with Question, Answer, Topic, Formality, Dialect, Date fields.
• —`train.jsonl` — the generated instruction-tuning set: 10,000 examples across 90 topics, built by scripts/build_train_jsonl.py from three sources — the 270-example seed, the 930-term lexicon, and hand-written topic banks. Unlike fine_tuning/, this set is not lexicon-only: it covers geography, food, health, work, history, and a sales-agent behaviour set (see below). Regenerate with python scripts/build_train_jsonl.py; do not edit it by hand.
• —`scripts/build_train_jsonl.py` — the generator that produces train.jsonl. It is the single source of truth for that file.
• —`llm_iraqi_best_learning.ipynb` — a Colab notebook that clones this repository and fine-tunes Gemma on train.jsonl with LoRA, mixing in ~15% general instruction data (Aya) to limit catastrophic forgetting. It also contains the evaluation cells described under Fine-tuning data.
• —`gemma_iraqi_merge_fixed.ipynb` — merges a trained LoRA adapter into the base model to produce standalone weights.

Data schema

word.json is a list of category objects, each holding a list of word/meaning pairs:

{
  "category": "التحية",
  "items": [
    { "word": "هلا", "meaning": "أهلاً" },
    { "word": "شلونك", "meaning": "كيف حالك؟" },
    { "word": "شخبارك", "meaning": "ما أخبارك؟" }
  ]
}

word is the Iraqi dialect term; meaning is its Modern Standard Arabic gloss (sometimes a short explanatory phrase rather than a single word, where a literal MSA equivalent doesn't exist).

Categories

50 categories, 930 terms total. Verified by counting word.json directly:

Usage

Rebuild the RAG document index after any edit to word.json:

python rag/prepare_rag.py

Search from the command line:

python -m rag.retriever "شنو معنى شلونك؟"

Or import the retriever directly:

from rag import search
results = search("شنو معنى شلونك؟", top_k=5)
# each result: {"score", "id", "type", "word", "meaning", "category", "text"}

Regenerate fine-tuning data from the lexicon (deterministic, seed=42):

python fine_tuning/prepare_finetuning.py

Run LoRA fine-tuning (requires a GPU; installs torch, transformers, datasets, peft, trl, accelerate from fine_tuning/requirements.txt):

pip install -r fine_tuning/requirements.txt
python fine_tuning/train.py --model Qwen/Qwen2.5-1.5B-Instruct --epochs 3

The adapter is saved to fine_tuning/output/. To train on Gemma via Colab instead, use llm_iraqi_best_learning.ipynb, which clones this repository and trains on train.jsonl.

Fine-tuning data

There are two independent training sets in this repository. They are not interchangeable:

train.jsonl — the 10,000-example set

Each line carries the same fields as the seed:

{
  "Question": "شكد سعر الثلاجة؟",
  "Answer": "الثلاجة 14 قدم بـ 460,000 دينار.",
  "Topic": "Market",
  "Formality": "Casual",
  "Dialect": "Iraqi Arabic",
  "Date": "2025-01-15T00:00:00"
}

The generator enforces two invariants that matter for training quality: every Question is unique (10,000/10,000), and answers keep a high density of Iraqi dialect markers (شنو, شلون, هسه, ماكو, زين, هواي, عيني, چان, …) — 83% of answers contain at least one. Earlier revisions of the lexicon templates explained Iraqi in MSA instead of speaking it, which trained the model to gloss the dialect rather than use it.

Agent-behaviour subset

690 examples target behaviours a retail assistant needs and that generic dialect data does not teach. These exist because an evaluation harness in the notebook measured each one and found the base data taught nothing about them — in one case it taught the opposite (a row answered a warranty question with an invented duration, and the model reproduced that).

• —Deferral — questions whose answer is not in the catalogue (warranty, delivery time, country of origin) are answered with اتأكدلك وأرد عليك and no invented number, including when the question itself supplies a candidate ("ضمان شكد سنة؟").
• —Brand refusal — a product from a brand not stocked is refused by name, without inventing a price and without silently substituting a stocked brand.
• —Deferred arithmetic — totals are never computed in prose; the reply is لحظة أحسبلك اياه and a deterministic engine does the maths.
• —Order capture — missing fields are requested one at a time, never fabricated, and the [ORDER_READY] marker is emitted on its own final line only after explicit confirmation.
• —Tool calls — status queries emit a bare [TOOL_CALL]{"tool": ..., "args": {...}}[/TOOL_CALL] line, and an empty tool result produces an explicit denial rather than a hallucinated order status.
• —Order extraction — a colloquial request becomes strict JSON ({"items": [{"name", "qty"}], "install"}) with out-of-catalogue items dropped.

Because these answers are structurally exact, the generator excludes them from its paraphrase pass: prefixing والله to a JSON payload or a [TOOL_CALL] line would break it.

fine_tuning/train_chat.jsonl — the lexicon-only set

prepare_finetuning.py generates 1,559 examples from the lexicon only — word↔meaning pairs and category-based questions. It contains no dialogues. Output is written in two formats:

Chat format (train_chat.jsonl):

{
  "messages": [
    { "role": "system", "content": "أنت مساعد متخصص باللهجة العراقية، تشرح معاني الكلمات والمصطلحات العراقية وتترجم بينها وبين العربية الفصحى." },
    { "role": "user", "content": "كيف يقال «رأس» بالعراقي؟" },
    { "role": "assistant", "content": "باللهجة العراقية تكدر تكول: «راس»." }
  ]
}

Alpaca format (train_alpaca.jsonl):

{
  "instruction": "كيف يقال «رأس» بالعراقي؟",
  "input": "",
  "output": "باللهجة العراقية تكدر تكول: «راس»."
}

Sourcing

The lexicon was manually compiled by the author and cross-referenced against ar.mo3jam.com/dialect/Iraqi for verification. It was not scraped or extracted from that source. Entries identified as Gulf or Levantine rather than Iraqi were removed during manual review, and duplicates were eliminated so each term appears once.

Limitations

• —The lexicon was manually compiled and reviewed, not extracted from a corpus or frequency-ranked against real usage.
• —Terms were compiled and reviewed by a single native speaker; no inter-annotator agreement was measured, and inclusion decisions reflect one reviewer's judgment of what constitutes Iraqi rather than neighbouring dialectal usage.
• —Coverage is skewed toward Baghdadi usage; other Iraqi regional varieties are under-represented.
• —Single-gloss entries cannot capture polysemy or register variation — many terms have context-dependent meanings not reflected here.
• —No evaluation has been done of whether fine-tuning on this data improves dialect performance on any held-out benchmark.

License

This repository contains both code and data, licensed separately:

• —Code (rag/, fine_tuning/*.py, notebooks) — MIT
• —Data (word.json and any data generated from it) — CC BY 4.0

See LICENSE and LICENSE-DATA for full text.

Citation

@misc{iraqi_words_2026,
  title  = {Iraqi Words: A Lexical Resource for Iraqi Arabic Dialect NLP},
  author = {Abdulsattar, Ameer Wisam},
  year   = {2026},
  url    = {https://github.com/ameer20042005/iraqi_words_finetuning}
}

Links

• —GitHub: github.com/ameer20042005
• —Hugging Face: huggingface.co/ameer4wisam

كلمات عراقية

قاموس مصطلحات عراقية مُجمَّع يدوياً (930 مصطلحاً، 50 فئة) مع محرّك استرجاع BM25 بدون أي اعتمادية خارجية، وأداة لتوليد بيانات التدريب (Fine-Tuning) من القاموس.

لماذا يوجد هذا المشروع

اللهجة العراقية ممثّلة تمثيلاً ضعيفاً في معالجة اللغة الطبيعية مقارنة بالعربية الفصحى وباللهجات ذات الموارد الأكبر مثل المصرية أو الشامية. الموارد المعجمية التي تربط المصطلحات العراقية بمعانيها بالفصحى — وهي النوع اللازم لتأسيس الاسترجاع أو الضبط الدقيق (Fine-Tuning) لفهم اللهجة — نادرة. يقدّم هذا المستودع مورداً من هذا النوع، مع أدوات للبحث فيه وتحويله إلى بيانات تدريب.

محتويات المستودع

• —`word.json` — القاموس: 930 مصطلحاً عراقياً موزعة على 50 فئة، كل مصطلح مع معناه بالفصحى.
• —`lexicon.jsonl` — نفس المصطلحات الـ930 بصيغة مسطّحة، سجل واحد {word, meaning, category} في كل سطر. هذا ما يقرأه عارض البيانات في Hugging Face، أما word.json فيحافظ على التنظيم حسب الفئات الذي يقرأه الكود في rag/ وfine_tuning/.
• —`rag/` — محرّك استرجاع BM25 فوق القاموس بدون أي اعتمادية خارجية (مكتبة بايثون القياسية فقط)، إضافة إلى prepare_rag.py لبناء فهرس الوثائق. هذه ميزة عملية حقيقية إذا أردت دمج البحث اللهجي بخدمة دون إضافة اعتمادية بحث أو قاعدة بيانات متجهية.
• —`fine_tuning/` — prepare_finetuning.py الذي يولّد بيانات تدريب بصيغتي chat وAlpaca من القاموس فقط (كلمة↔معنى وأسئلة حسب الفئة — بدون أي محادثات)، وtrain.py سكربت تدريب LoRA.
• —`train.json` — بذرة مكتوبة يدوياً فيها 270 مثال سؤال/جواب عراقي، بحقول Question وAnswer وTopic وFormality وDialect وDate.
• —`train.jsonl` — مجموعة التدريب المولّدة: 10,000 مثال على 90 موضوعاً، يبنيها scripts/build_train_jsonl.py من ثلاثة مصادر — البذرة (270)، القاموس (930 مصطلحاً)، وبنوك مواضيع مكتوبة يدوياً. بخلاف fine_tuning/ هي مو مقتصرة على القاموس: تغطي الجغرافيا والأكل والصحة والشغل والتاريخ ومجموعة سلوك وكيل مبيعات (شوف تحت). أعد توليدها بـpython scripts/build_train_jsonl.py ولا تعدّلها بالإيد.
• —`scripts/build_train_jsonl.py` — المولّد الذي ينتج train.jsonl، وهو المصدر الوحيد للحقيقة لذاك الملف.
• —`llm_iraqi_best_learning.ipynb` — دفتر Colab يستنسخ هذا المستودع ويدرّب Gemma على train.jsonl بـLoRA، ويخلط ~15% بيانات تعليمات عامة (Aya) للحد من النسيان الكارثي. وفيه كذلك خلايا التقييم الموصوفة بقسم بيانات التدريب.
• —`gemma_iraqi_merge_fixed.ipynb` — يدمج محوّل LoRA المدرَّب بالنموذج الأساسي لإنتاج أوزان مستقلة.

صيغة البيانات

word.json قائمة من كائنات الفئات، كل كائن يحتوي قائمة أزواج word/meaning:

{
  "category": "التحية",
  "items": [
    { "word": "هلا", "meaning": "أهلاً" },
    { "word": "شلونك", "meaning": "كيف حالك؟" },
    { "word": "شخبارك", "meaning": "ما أخبارك؟" }
  ]
}

word هو المصطلح باللهجة العراقية؛ meaning معناه بالعربية الفصحى (أحياناً عبارة توضيحية قصيرة بدل كلمة واحدة، حين لا يوجد مقابل حرفي بالفصحى).

الفئات

50 فئة، 930 مصطلحاً بالمجموع. محسوبة مباشرة من word.json:

الاستخدام

إعادة بناء فهرس وثائق RAG بعد أي تعديل على word.json:

python rag/prepare_rag.py

البحث من سطر الأوامر:

python -m rag.retriever "شنو معنى شلونك؟"

أو الاستيراد المباشر:

from rag import search
results = search("شنو معنى شلونك؟", top_k=5)
# كل نتيجة: {"score", "id", "type", "word", "meaning", "category", "text"}

إعادة توليد بيانات التدريب من القاموس (حتمي، seed=42):

python fine_tuning/prepare_finetuning.py

تشغيل تدريب LoRA (يحتاج GPU؛ يثبّت torch، transformers، datasets، peft، trl، accelerate من fine_tuning/requirements.txt):

pip install -r fine_tuning/requirements.txt
python fine_tuning/train.py --model Qwen/Qwen2.5-1.5B-Instruct --epochs 3

يُحفظ المحوّل (Adapter) في fine_tuning/output/. للتدريب على Gemma عبر Colab، استخدم llm_iraqi_best_learning.ipynb الذي يستنسخ هذا المستودع ويدرّب على train.jsonl.

بيانات التدريب

بالمستودع مجموعتا تدريب مستقلتان، ومو بدائل لبعض:

train.jsonl — مجموعة الـ10,000

كل سطر يحمل نفس حقول البذرة:

{
  "Question": "شكد سعر الثلاجة؟",
  "Answer": "الثلاجة 14 قدم بـ 460,000 دينار.",
  "Topic": "Market",
  "Formality": "Casual",
  "Dialect": "Iraqi Arabic",
  "Date": "2025-01-15T00:00:00"
}

المولّد يفرض شرطين مهمين لجودة التدريب: كل Question فريد (10,000/10,000)، والأجوبة تحافظ على كثافة عالية من مؤشرات اللهجة العراقية (شنو، شلون، هسه، ماكو، زين، هواي، عيني، چان…) — 83% من الأجوبة فيها مؤشر واحد على الأقل. بنسخ سابقة چانت قوالب القاموس تشرح العراقي بالفصحى بدل ما تحچيه، وهذا درّب النموذج يفسّر اللهجة بدل ما يستخدمها.

مجموعة سلوك الوكيل

690 مثالاً تستهدف سلوكيات يحتاجها مساعد مبيعات وما تعلّمها بيانات اللهجة العامة. وجودها مبني على قياس بالدفتر فحص كل سلوك ولگى إن البيانات الأساسية ما تعلّم عنها شي — وبحالة وحدة چانت تعلّم العكس (صف يجاوب سؤال ضمان بمدة مخترعة، والنموذج كرر نفس السلوك).

• —الإحالة — الأسئلة اللي جوابها مو بالكتالوج (الضمان، وقت التوصيل، بلد المنشأ) تنجاوب بـاتأكدلك وأرد عليك وبلا أي رقم مخترع، حتى لو السؤال نفسه يلقّن رقماً («ضمان شكد سنة؟»).
• —رفض البراند — المنتج من ماركة مو متوفرة ينرفض باسمها، بلا اختراع سعر وبلا استبدالها بصمت بماركة موجودة.
• —تأجيل الحساب — الاجماليات ما تنحسب بالنص أبداً؛ الرد لحظة أحسبلك اياه ومحرك حتمي يسوي الحساب.
• —تسجيل الطلب — الحقول الناقصة تُطلب وحدة وحدة، وما تنخترع أبداً، وعلامة [ORDER_READY] تنكتب بسطر مستقل بالنهاية وبعد التأكيد الصريح حصراً.
• —استدعاء الأدوات — استعلام الحالة يطلع سطر [TOOL_CALL]{"tool": ..., "args": {...}}[/TOOL_CALL] نظيف، والنتيجة الفارغة تنتج نفياً صريحاً بدل حالة طلب مهلوسة.
• —استخراج الطلب — الطلب بالعامية يتحول JSON صارم ({"items": [{"name", "qty"}], "install"}) ويُسقَط منه أي منتج مو بالكتالوج.

ولأن هذي الأجوبة دقيقة بنيوياً، المولّد يستثنيها من مرحلة إعادة الصياغة: إضافة والله قبل حمولة JSON أو سطر [TOOL_CALL] تكسرها.

fine_tuning/train_chat.jsonl — مجموعة القاموس فقط

يولّد prepare_finetuning.py 1,559 مثالاً من القاموس فقط — أزواج كلمة↔معنى وأسئلة حسب الفئة. بدون أي محادثات. المخرجات بصيغتين:

صيغة المحادثة (train_chat.jsonl):

{
  "messages": [
    { "role": "system", "content": "أنت مساعد متخصص باللهجة العراقية، تشرح معاني الكلمات والمصطلحات العراقية وتترجم بينها وبين العربية الفصحى." },
    { "role": "user", "content": "كيف يقال «رأس» بالعراقي؟" },
    { "role": "assistant", "content": "باللهجة العراقية تكدر تكول: «راس»." }
  ]
}

صيغة Alpaca (train_alpaca.jsonl):

{
  "instruction": "كيف يقال «رأس» بالعراقي؟",
  "input": "",
  "output": "باللهجة العراقية تكدر تكول: «راس»."
}

المصدر

القاموس مُجمَّع يدوياً من قِبل المؤلف ومُراجَع بالمقارنة مع ar.mo3jam.com/dialect/Iraqi للتحقق. لم يُسحب أو يُستخرج من ذلك المصدر. المصطلحات التي تبيّن أنها خليجية أو شامية وليست عراقية أُزيلت أثناء المراجعة اليدوية، وأُزيلت التكرارات بحيث يظهر كل مصطلح مرة واحدة.

الحدود

• —القاموس مُجمَّع ومُراجَع يدوياً، وليس مستخرجاً من مدوّنة نصية أو مرتّباً حسب تكرار الاستخدام الفعلي.
• —المصطلحات جُمعت وروجعت من قِبل متحدث أصلي واحد؛ لم يُقَس اتفاق بين مراجعين متعددين، وقرارات الإدراج تعكس حكم مراجع واحد لما يُعتبر عراقياً مقابل لهجات مجاورة.
• —التغطية مائلة نحو الاستخدام البغدادي؛ اللهجات العراقية الإقليمية الأخرى ممثَّلة تمثيلاً أضعف.
• —المدخلات ذات المعنى الواحد لا تعكس تعدد المعاني أو فروق السجل اللغوي — كثير من المصطلحات لها معانٍ تعتمد على السياق لم تُذكر هنا.
• —لم يُجرَ أي تقييم لمعرفة ما إذا كان الضبط الدقيق (Fine-Tuning) على هذي البيانات يحسّن أداء النموذج باللهجة العراقية على أي معيار قياس مستقل.

الترخيص

يحتوي هذا المستودع على كود وبيانات، مرخّصة بشكل منفصل:

• —الكود (rag/، fine_tuning/*.py، الدفاتر) — MIT
• —البيانات (word.json وأي بيانات مولّدة منه) — CC BY 4.0

راجع LICENSE وLICENSE-DATA للنص الكامل.

الاستشهاد

@misc{iraqi_words_2026,
  title  = {Iraqi Words: A Lexical Resource for Iraqi Arabic Dialect NLP},
  author = {Abdulsattar, Ameer Wisam},
  year   = {2026},
  url    = {https://github.com/ameer20042005/iraqi_words_finetuning}
}

روابط

• —GitHub: github.com/ameer20042005
• —Hugging Face: huggingface.co/ameer4wisam