📖 مَوروث | Mawrooth — LoRA Adapter

---

📋 نظرة عامة

مَوروث هو نظام ذكاء اصطناعي لشرح الأبيات النبطية، يُخرج كل شرح بخمسة أقسام منظمة:

---

🚀 الاستخدام

1) التثبيت

!pip install -q --upgrade transformers peft bitsandbytes accelerate gradio huggingface_hub

import torch, json, re, os, shutil, tempfile
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from peft import PeftModel
from huggingface_hub import hf_hub_download

2) تحميل الملفات من HF

HF_REPO = "NorahAlobaied/Mawrooth-ALLaM-7B-LoRA"
BASE_MODEL = "humain-ai/ALLaM-7B-Instruct-preview"

for fname in ["mawrooth_styles.py", "mawrooth_utils.py", "mawrooth_app.py"]:
    path = hf_hub_download(repo_id=HF_REPO, filename=fname, force_download=True)
    shutil.copy(path, f"./{fname}")
    print(f"✅ {fname}")

3) تحميل القاموس + النموذج

DICT_PATH = hf_hub_download(repo_id=HF_REPO, filename="mawrooth_dictionary.json", force_download=True)
with open(DICT_PATH, encoding='utf-8') as f:
    DICTIONARY = json.load(f)
print(f"📚 القاموس: {len(DICTIONARY)} مصطلح")

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True, bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16, bnb_4bit_use_double_quant=True,
)
tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL, trust_remote_code=True)
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

base = AutoModelForCausalLM.from_pretrained(
    BASE_MODEL, quantization_config=bnb_config,
    device_map="auto", trust_remote_code=True,
)
model = PeftModel.from_pretrained(base, HF_REPO)
model.eval()
model.config.use_cache = True
print("✅ النموذج + LoRA جاهزان")

4) دوال الاستدلال

SYSTEM_PROMPT = """أنت خبير في الشعر النبطي السعودي، تفهم اللهجة والثقافة البدوية بعمق.

مهمتك: شرح الأبيات النبطية بدقة ووضوح.

قواعد صارمة:
1. استخدم القاموس المرجعي لشرح المفردات الصعبة.
2. لا تخترع معلومات غير موجودة في البيت أو القاموس.
3. لا تذكر أسماء أماكن/قبائل/أحداث إلا إذا وردت صراحة في البيت أو القاموس.
4. اتبع هذا الترتيب بدقة تامة:
   [المفردات] كلمة: معناها.
   [تحليل البيت] فكك البيت خطوة بخطوة.
   [السياق الثقافي] معلومة ثقافية عامة صحيحة.
   [الشرح] إعادة صياغة معنى البيت.
   [الوصف] English visual description.
5. اكتب بالعربية الفصحى فقط، ما عدا [الوصف] فبالإنجليزية.
6. إذا لم تكن متأكداً من معلومة، اكتب: "(غير مؤكد)"."""

STOPWORDS = {
    'في','من','على','إلى','مع','عن','هذا','هذه','اللي','كان',
    'ما','لا','أن','إن','هو','هي','هم','ثم','أو','و','ف','ب','ل',
    'يا','قد','كل','بعض','غير','بين','عند','اذا','لم','لن',
    'له','لها','لهم','به','بها','بهم','منه','منها','منهم',
    'هنا','هناك','الا','لكن','حتى','اليا'
}

def extract_terms(verse, dictionary, max_terms=20):
    verse_words = set(re.findall(r'\b[\u0600-\u06FF]+\b', verse))
    found = {}
    for term, meaning in dictionary.items():
        if term in STOPWORDS or len(term) < 3:
            continue
        term_base = term.replace('ال', '', 1) if term.startswith('ال') else term
        if term in verse_words or term_base in verse_words:
            found[term] = meaning
            if len(found) >= max_terms:
                break
    return found

def build_prompt(verse):
    verse_clean = verse.replace('اشرح هذا البيت:', '').strip()
    terms = extract_terms(verse_clean, DICTIONARY)
    context = "\n".join([f"- {k}: {v}" for k, v in terms.items()]) if terms else "(لا توجد مصطلحات نبطية صعبة في هذا البيت)"
    return f"""[القاموس المرجعي]
{context}

[المهمة]
اشرح هذا البيت: {verse_clean}

[التعليمات]
- ارجع للقاموس أعلاه لشرح المفردات.
- لا تخترع معلومات.
- اتبع الصيغة: [المفردات] [تحليل البيت] [السياق الثقافي] [الشرح] [الوصف]"""

def explain_verse(verse, max_tokens=500):
    if not verse or not verse.strip():
        return "⚠️ الرجاء إدخال بيت شعري"

    user_prompt = build_prompt(verse)
    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": user_prompt},
    ]
    prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    inputs = tokenizer(prompt, return_tensors="pt", truncation=True, max_length=2048).to("cuda")

    with torch.no_grad():
        outputs = model.generate(
            **inputs, max_new_tokens=max_tokens,
            temperature=0.3, top_p=0.9, repetition_penalty=1.15,
            do_sample=True,
            pad_token_id=tokenizer.pad_token_id,
            eos_token_id=tokenizer.eos_token_id,
        )
    return tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True).strip()

print("✅ كل الدوال جاهزة")

5) التحقق من التوكن

from google.colab import userdata

try:
    token = userdata.get('HF_TOKEN')
    if token and token.startswith('hf_'):
        print(f"✅ التوكن يعمل — الطول: {len(token)} حرفًا")
        print(f"   بداية التوكن: {token[:10]}...")
    else:
        print("❌ التوكن فارغ أو غير صالح")
except Exception as e:
    print(f"❌ خطأ: {e}")
    print("\n🔧 تحقق من:")
    print("   1. الاسم مكتوب 'HF_TOKEN' بالضبط")
    print("   2. Notebook access مفعّل")

6) تشغيل الواجهة

import urllib.parse
import mawrooth_utils
mawrooth_utils.urllib = urllib

with open('mawrooth_app.py', 'r', encoding='utf-8') as f:
    _app_code = f.read()

exec(compile(_app_code, 'mawrooth_app.py', 'exec'), globals())

ميزات الواجهة

• 📖 عرض البطاقات: الشرح الرئيسي + مفردات + سياق ثقافي
• 🎨 توليد صور تلقائي: من [الوصف] الإنجليزي عبر Pollinations
• 📋 زر النسخ: ينسخ الشرح منسّقًا وجاهزًا للمشاركة
• 🔄 زر الإعادة: يعيد توليد الشرح بنتيجة مختلفة
• 🗑️ زر المسح: يُفرِّغ الحقول لبيت جديد
• 💡 6 أمثلة جاهزة: للنقر السريع

---

الملفات

---

📊 تفاصيل التدريب

• النموذج الأساسي: humain-ai/ALLaM-7B-Instruct-preview
• التقنية: QLoRA (4-bit)
• رتبة LoRA(r): 16
• lora_alpha: 32
• lora_dropout: 0.05
• الطبقات المستهدفة: q_proj, k_proj, v_proj, o_proj
• عدد الأمثلة: 586 | 527 تدريب | 59 تحقق
• عدد الخطوات: 80
• Token Accuracy: 85.75%
• Train Loss: 0.716
• Validation Loss: 0.711
• حجم LoRA: 65 MB
• لا يوجد Overfitting: eval_loss (0.711) ≈ train_loss (0.716)

---

🏗️ البنية التقنية

[بيت نبطي]
    ↓
[extract_terms] ← استخراج المصطلحات من القاموس
    ↓
[build_prompt] ← تكوين prompt مع القاموس المُصفّى
    ↓
[ALLaM-7B (4-bit)] + [Mawrooth LoRA (fp16)]
    ↓
[5 أقسام]: مفردات، تحليل، سياق، شرح، وصف

---

📚 القاموس النبطي

· الحجم: 1,328 مصطلح متخصص · يشمل: مفردات نبطية، أسماء نجوم، أدوات قهوة، أسماء إبل، ظواهر جوية، مواقع جغرافية · متوفر في: NorahAlobaied/Mawrooth-ALLaM-7B باسم mawrooth_dictionary.json

📖 مصادر بيانات المعجم (Lexicon Methodology)

بُني معجم المفردات عبر مراحل منظمة:

1. المصادر المرجعية:

· أمهات معاجم الألفاظ الشعبية والنبطية المعروفة. · سياقات المفردات في دواوين القصائد التراثية المتداولة. · المراجعة الشفهية من المهتمين بالتراث النبطي.

2. المعالجة والهندسة:

· استخراج المفردات: استخلاص الكلمات الغريبة/التراثية من النصوص. · التنقيب: تطبيق NLP لضبط جذور الكلمات وتصنيفها. · المراجعة البشرية: تحقق الفريق يدويًا من كل معنى. · التصنيف السياقي: تنظيم المفردات في مجالات (طبيعة، قهوة، إبل، مشاعر).

3. التحقق النهائي: مراجعة كل مصطلح واستبعاد غير الموثوق.

---

🎓 أمثلة على المخرجات

مثال 1

البيت: مع صحصح كنه قفا الترس مقلوب

المخرجات:

[المفردات] صحصح: الأرض المستوية الواسعة. قفا: ظهر الشيء. الترس: الدرع. مقلوب: معكوس.

[تحليل البيت] الصحراء الواسعة الممتدة كأنها ظهر درع مقلوب، الاستواء التام بلا معالم.

[السياق الثقافي] تشبيه الصحراء بظهر الدرع يعكس دقة الوصف البدوي للفراغ الواسع.

[الشرح] صحراء ممتدة ومسطحة لدرجة أنها تشبه ظهر درع مقلوب، لا نهاية لها ولا معالم.

[الوصف] A vast, flat desert plain stretching endlessly, smooth like the back of an upturned shield. (Cinematic lighting, traditional Arabian concept art, atmospheric, muted desert palette, ultra-detailed)

مثال 2

البيت: ياما حلا الفنجال مع سيحة البال

المخرجات:

[المفردات] حلا: جمال وحلاوة. الفنجال: فنجان القهوة العربية. سيحة البال: سعة الصدر والراحة النفسية.

[تحليل البيت] الفنجال هو فنجان القهوة العربية، وسيحة البال تعني الراحة النفسية وسعة الصدر، والمعنى أن شرب القهوة مع راحة البال أجمل شيء.

[السياق الثقافي] شرب القهوة مع الأهل والأصدقاء من أبرز مظاهر الكرم والضيافة عند البدو، وهي رمز للألفة والمودة بين الناس.

[الشرح] إن شرب القهوة مع راحة البال أجمل شيء.

[الوصف] A Bedouin pouring a cup of coffee for his guest, both smiling and enjoying the moment together in a cozy tent under a starry night sky. (Cinematic lighting, traditional Arabian concept art, digital painting, atmospheric, muted desert palette)

---

✒️ الاقتباس

@misc{mawrooth2026,
  title={Mawrooth: Arabic Nabati Poetry Explainer},
  author={Mawrooth Team},
  for={Arabthon 2026},
  year={2026},
  publisher={Hugging Face},
  howpublished={\url{https://huggingface.co/NorahAlobaied/Mawrooth-ALLaM-7B-LoRA}}
}

---

🔗 روابط ذات صلة

• 📊 مجموعة البيانات: NorahAlobaied/Mawrooth-Nabati-Dataset
• 🤖 النموذج الأساسي: humain-ai/ALLaM-7B-Instruct-preview

---

📧 التواصل

للاستفسارات: nourahalobaeid@gmail.com

---

صُنع بـ ❤️ للتراث السعودي