initial commit

.gitattributes

@@ -0,0 +1,55 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.lz4 filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+# Audio files - uncompressed
+*.pcm filter=lfs diff=lfs merge=lfs -text
+*.sam filter=lfs diff=lfs merge=lfs -text
+*.raw filter=lfs diff=lfs merge=lfs -text
+# Audio files - compressed
+*.aac filter=lfs diff=lfs merge=lfs -text
+*.flac filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text
+*.ogg filter=lfs diff=lfs merge=lfs -text
+*.wav filter=lfs diff=lfs merge=lfs -text
+# Image files - uncompressed
+*.bmp filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.tiff filter=lfs diff=lfs merge=lfs -text
+# Image files - compressed
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,184 @@
+---
+tags:
+- text-to-image
+- lora
+- diffusers
+- template:diffusion-lora
+widget:
+- output:
+    url: images/Capture.PNG
+  text: '-'
+base_model: QCRI/Fanar-1-9B
+instance_prompt: null
+license: apache-2.0
+---
+# Fanar-1-9B-Islamic-Inheritance-Reasoning
+
+<Gallery />
+
+## Model description 
+
+# Fanar-1-9B-Islamic-Inheritance-Reasoning
+
+## Model Description
+
+This model was developed for **SubTask 1: Islamic Inheritance Reasoning** at **QIAS 2025**, a shared task evaluating Large Language Models (LLMs) in reasoning over Islamic inheritance law.
+
+We fine-tuned the **Fanar-1-9B causal language model** using **Low-Rank Adaptation (LoRA)** and integrated it into a **Retrieval-Augmented Generation (RAG)** pipeline. The system is designed to handle the complexities of Islamic inheritance law, including:
+
+* Understanding inheritance scenarios
+* Identifying eligible heirs
+* Applying fixed-share rules (farāʾiḍ)
+* Performing precise inheritance calculations
+
+To optimize for limited hardware, the model is loaded with **4-bit NF4 quantization (bitsandbytes)** while LoRA adapters are trained in higher precision. This approach allows large-model fine-tuning with significantly reduced GPU memory requirements.
+
+By combining **domain-specific fine-tuning** with **retrieval grounding**, the model achieves strong reasoning capabilities while maintaining efficiency.
+
+---
+
+## Results
+
+* **Final accuracy:** **85.8%** on the shared task evaluation set
+* Outperforms strong baselines such as **GPT-4.5, LLaMA, Fanar (base), Mistral, and ALLaM** (evaluated in zero-shot prompting)
+* Excels in **advanced reasoning** with **97.6% accuracy**, surpassing **Gemini 2.5** and **OpenAI’s o3**
+* Demonstrates that **mid-scale Arabic LLMs**, when enhanced with retrieval and fine-tuning, can **outperform frontier models** in highly specialized domains
+
+---
+
+## Citation
+
+If you use this model, please cite:
+
+&#x60;&#x60;&#x60;bibtex
+@inproceedings{QU-NLP-QIAS2025,
+  author    &#x3D; {Mohammad AL-Smadi},
+  title     &#x3D; {QU-NLP at QIAS 2025 Shared Task: A Two-Phase LLM Fine-Tuning and Retrieval-Augmented Generation Approach for Islamic Inheritance Reasoning},
+  booktitle &#x3D; {Proceedings of The Third Arabic Natural Language Processing Conference (ArabicNLP 2025)},
+  year      &#x3D; {2025},
+  publisher &#x3D; {Association for Computational Linguistics},
+  note      &#x3D; {Suzhou, China, Nov 5--9},
+  url       &#x3D; {https:&#x2F;&#x2F;arabicnlp2025.sigarab.org&#x2F;}
+}
+&#x60;&#x60;&#x60;
+
+---
+
+## Quick Start
+
+### 1. Load Model + Adapter
+
+&#x60;&#x60;&#x60;python
+from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
+from peft import PeftModel
+import torch, re
+
+BASE_MODEL   &#x3D; &quot;QCRI&#x2F;Fanar-1-9B&quot;
+ADAPTER_REPO &#x3D; &quot;msmadi&#x2F;Fanar-1-9B-Islamic-Inheritance-Reasoning&quot;
+
+bnb &#x3D; BitsAndBytesConfig(load_in_4bit&#x3D;True, bnb_4bit_quant_type&#x3D;&quot;nf4&quot;,
+                         bnb_4bit_compute_dtype&#x3D;torch.float16)
+
+tok &#x3D; AutoTokenizer.from_pretrained(ADAPTER_REPO, trust_remote_code&#x3D;True)
+if tok.pad_token_id is None:
+    tok.pad_token &#x3D; tok.eos_token
+
+base &#x3D; AutoModelForCausalLM.from_pretrained(
+    BASE_MODEL,
+    device_map&#x3D;&quot;auto&quot;,
+    quantization_config&#x3D;bnb,
+    trust_remote_code&#x3D;True,
+    attn_implementation&#x3D;&quot;eager&quot;,
+    use_cache&#x3D;False,
+)
+model &#x3D; PeftModel.from_pretrained(base, ADAPTER_REPO).eval()
+&#x60;&#x60;&#x60;
+
+---
+
+### 2. Prompt &amp; Inference
+
+&#x60;&#x60;&#x60;python
+def format_context(docs):
+    if not docs: return &quot;&quot;
+    docs &#x3D; [str(d)[:800] for d in docs[:3]]
+    return &quot;المعلومات المرجعية من المصادر الإسلامية:\n&quot; + &quot;\n&quot;.join(f&quot;• {doc}&quot; for doc in docs) + &quot;\n\n&quot;
+
+def prepare_prompt(question, options, context_docs&#x3D;None):
+    letters &#x3D; [&#39;A&#39;,&#39;B&#39;,&#39;C&#39;,&#39;D&#39;,&#39;E&#39;,&#39;F&#39;][:len(options)]
+    opts_text &#x3D; &quot;\n&quot;.join(f&quot;{l}) {o}&quot; for l,o in zip(letters, options))
+    context &#x3D; format_context(context_docs)
+
+    system_msg &#x3D; (&quot;أنت خبير متخصص في أحكام الميراث الإسلامي والفرائض الشرعية. &quot;
+                  &quot;تجيب بدقة واختصار اعتماداً على القرآن الكريم والسنة النبوية الشريفة. &quot;
+                  &quot;اختر الإجابة الصحيحة من الخيارات المعطاة.&quot;)
+    user_msg &#x3D; f&quot;السؤال: {question}\n\nالخيارات:\n{opts_text}\n\nاختر الحرف الصحيح من ({&#39;, &#39;.join(letters)}) فقط:&quot;
+
+    messages &#x3D; [{&quot;role&quot;:&quot;system&quot;,&quot;content&quot;:system_msg}]
+    if context: messages.append({&quot;role&quot;:&quot;system&quot;,&quot;content&quot;:context})
+    messages.append({&quot;role&quot;:&quot;user&quot;,&quot;content&quot;:user_msg})
+
+    try:
+        return tok.apply_chat_template(messages, add_generation_prompt&#x3D;True, tokenize&#x3D;False)
+    except:
+        return f&quot;{context}{user_msg}\nالإجابة: &quot;
+
+def answer_mcq(question, options, context_docs&#x3D;None, max_new_tokens&#x3D;5, temperature&#x3D;0.1):
+    prompt_text &#x3D; prepare_prompt(question, options, context_docs)
+    inputs &#x3D; tok(prompt_text, return_tensors&#x3D;&quot;pt&quot;).to(model.device)
+
+    with torch.no_grad():
+        out &#x3D; model.generate(**inputs, max_new_tokens&#x3D;max_new_tokens, temperature&#x3D;temperature,
+                             do_sample&#x3D;False, pad_token_id&#x3D;tok.eos_token_id)
+
+    gen &#x3D; tok.decode(out[0][inputs[&quot;input_ids&quot;].shape[1]:], skip_special_tokens&#x3D;True)
+    match &#x3D; re.findall(r&quot;\b([A-F])\b&quot;, gen.upper())
+    return (match[0] if match else gen.strip()), gen
+&#x60;&#x60;&#x60;
+
+---
+
+### 3. Example
+
+&#x60;&#x60;&#x60;python
+question &#x3D; &quot;توفيت امرأة وتركت: زوج، بنت، وأخ شقيق. كيف تُقسَّم التركة؟&quot;
+options &#x3D; [
+    &quot;الزوج 1&#x2F;2، البنت النصف، ولا شيء للأخ&quot;,
+    &quot;الزوج 1&#x2F;4، البنت النصف، والأخ الباقي&quot;,
+    &quot;الزوج 1&#x2F;2، البنت 1&#x2F;3، والأخ الباقي&quot;,
+    &quot;الزوج 1&#x2F;4، البنت 2&#x2F;3، والأخ الباقي&quot;,
+]
+
+# Without RAG
+letter, raw &#x3D; answer_mcq(question, options)
+print(&quot;Model answer:&quot;, letter)
+print(&quot;Raw generation:&quot;, raw)
+
+# With RAG context
+retrieved &#x3D; [
+    &quot;للزوج النصف إذا لم يوجد فرع وارث. للبنت النصف إذا كانت منفردة. &quot;
+    &quot;إذا استوفيت الفروض فلا يبقى شيء للإخوة الأشقاء.&quot;
+]
+letter_rag, raw_rag &#x3D; answer_mcq(question, options, context_docs&#x3D;retrieved)
+print(&quot;RAG answer:&quot;, letter_rag)
+print(&quot;RAG raw generation:&quot;, raw_rag)
+&#x60;&#x60;&#x60;
+
+---
+
+## Notes
+
+* **RAG mode** (retrieving Islamic law references into context) yields the best performance.
+* Keep &#x60;max_new_tokens&#x60; small (3–8) to bias the model toward answering with a single letter.
+* If you publish a **merged checkpoint** (LoRA fused into base), the same functions work — just load the merged model instead of base+adapter.
+
+---
+
+
+
+
+
+## Download model
+
+
+[Download](/msmadi/Fanar-1-9B-Islamic-Inheritance-Reasoning/tree/main) them in the Files & versions tab.