Update comprehensive Model Card (Arabic & English)

README.md

@@ -1,59 +1,111 @@
 ---
-base_model: unsloth/deepseek-r1-distill-qwen-14b-unsloth-bnb-4bit
-library_name: transformers
-model_name: Faqih-R1-14B-Islamic-AI
+language:
+- ar
+- en
+license: apache-2.0
 tags:
-- generated_from_trainer
-- sft
-- trl
-- unsloth
-licence: license
+- islamic-ai
+- fiqh
+- comparative-fiqh
+- tafsir
+- hadith
+- deepseek-r1
+- qwen2.5
+- reasoning
+- safetensors
+pipeline_tag: text-generation
+base_model: deepseek-ai/DeepSeek-R1-Distill-Qwen-14B
+datasets:
+- hozifa1/faqih_sft_dataset
 ---
 
-# Model Card for Faqih-R1-14B-Islamic-AI
+# 🕋 Faqih-R1-14B: The Islamic Jurisprudence & Scholarly AI
+### الفقيه الذكي (Faqih-R1): نموذج الذكاء الاصطناعي الموسوعي للفقه المقارن وعلوم الشريعة
 
-This model is a fine-tuned version of [unsloth/deepseek-r1-distill-qwen-14b-unsloth-bnb-4bit](https://huggingface.co/unsloth/deepseek-r1-distill-qwen-14b-unsloth-bnb-4bit).
-It has been trained using [TRL](https://github.com/huggingface/trl).
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hozifa460/islamic-content/main/assets/banner.png" alt="Faqih-R1 Banner" width="100%" onerror="this.style.display='none'"/>
+</p>
 
-## Quick start
+<p align="center">
+  <b>Faqih-R1-14B</b> هو نموذج ذكاء اصطناعي رائد متخصص في <b>الفقه المقارن، علوم القرآن، وتخريج الأحاديث النبوية</b> وفق منهج أهل السنة والجماعة. يجمع بين قوة التفكير والاستدلال العميق لمعمارية <b>DeepSeek-R1-Distill-Qwen-14B</b>، والأمانة العلمية في استعراض أقوال المذاهب الأربعة مع أدلتها.
+</p>
+
+---
+
+## ✨ المميزات والقدرات الفقهية (Key Capabilities)
+
+* 📚 **الفقه المقارن المعتمد:** تحرير أقوال أئمة المذاهب الأربعة (الحنفية، المالكية، الشافعية، الحنابلة) مع أدلتهم من الكتاب والسنة.
+* 🧠 **الاستدلال والتفكير العميق (`<think>`):** يحلل المسألة الفقهية ويفكك محل النزاع خطوة بخطوة قبل صياغة الجواب.
+* 📜 **تخريج وشرح الأحاديث:** الاستدلال بالأحاديث الصحيحة مع بيان درجتها وحكم المحدثين والفوائد الفقهية.
+* 📖 **التفسير الموضوعي:** ربط الأحكام بالآيات القرآنية بالرسم العثماني وبيان أسباب النزول والمقاصد.
+* 🤲 **الأذكار والأدعية المحققة:** إيراد الأدعية المأثورة بنصوصها وضبطها وتخريجها.
+* 🛡️ **التأدب الفقهي والأمان:** الامتناع عن الإفتاء بغير علم في النوازل المعقدة والتحويل إلى دور الإفتاء المعتمدة.
+
+---
+
+## ⚡ التشغيل والاستخدام (Quickstart with Python & Transformers)
 
 ```python
-from transformers import pipeline
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer, TextStreamer
 
-question = "If you had a time machine, but could only go to the past or the future once and never return, which would you choose and why?"
-generator = pipeline("text-generation", model="hozifa1/Faqih-R1-14B-Islamic-AI", device="cuda")
-output = generator([{"role": "user", "content": question}], max_new_tokens=128, return_full_text=False)[0]
-print(output["generated_text"])
-```
+MODEL_ID = "hozifa1/Faqih-R1-14B-Islamic-AI"
+
+tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
+model = AutoModelForCausalLM.from_pretrained(
+    MODEL_ID,
+    torch_dtype=torch.bfloat16,
+    device_map="auto"
+)
 
-## Training procedure
+SYSTEM_PROMPT = (
+    "أنت الفقيه المحقق (Faqih-R1)، نموذج ذكاء اصطناعي إسلامي موسوعي متخصص في الفقه المقارن "
+    "والعلوم الشرعية وفق منهج أهل السنة والجماعة. فصّل الأدلة من الكتاب والسنة وأقوال المذاهب الأربعة."
+)
 
- 
+question = "ما حكم تارك الصلاة تكاسلاً عند المذاهب الأربعة مع تفصيل الأدلة والترجيح؟"
+prompt = f"<|im_start|>system\n{SYSTEM_PROMPT}<|im_end|>\n<|im_start|>user\n{question}<|im_end|>\n<|im_start|>assistant\n<think>\n"
 
+inputs = tokenizer(prompt, return_tensors="pt").to("cuda")
+streamer = TextStreamer(tokenizer, skip_prompt=False)
 
-This model was trained with SFT.
+with torch.no_grad():
+    output = model.generate(
+        **inputs,
+        streamer=streamer,
+        max_new_tokens=2048,
+        temperature=0.6,
+        top_p=0.95,
+        do_sample=True,
+    )
+```
 
-### Framework versions
+---
 
-- TRL: 0.24.0
-- Transformers: 5.5.0
-- Pytorch: 2.11.0
-- Datasets: 4.3.0
-- Tokenizers: 0.22.2
+## 🏎️ التشغيل السريع عبر vLLM (High-Throughput Inference)
 
-## Citations
+```bash
+vllm serve hozifa1/Faqih-R1-14B-Islamic-AI \
+    --tensor-parallel-size 1 \
+    --dtype bfloat16 \
+    --max-model-len 8192
+```
+
+---
 
+## 📦 النسخ المكممة المتاحة (GGUF Quantizations)
+للتشغيل على الأجهزة الشخصية وتطبيقات LM Studio و Ollama، يرجى زيارة المستودع المخصص:
+👉 **[`hozifa1/Faqih-R1-14B-GGUF`](https://huggingface.co/hozifa1/Faqih-R1-14B-GGUF)**
 
+---
+
+## 📊 بيانات التدريب (Training Data)
+تم تدريب النموذج بالاعتماد على داتا سيت **Faqih Gold SFT v2**:
+👉 **[`hozifa1/faqih_sft_dataset`](https://huggingface.co/datasets/hozifa1/faqih_sft_dataset)**
+
+---
 
-Cite TRL as:
-    
-```bibtex
-@misc{vonwerra2022trl,
-	title        = {{TRL: Transformer Reinforcement Learning}},
-	author       = {Leandro von Werra and Younes Belkada and Lewis Tunstall and Edward Beeching and Tristan Thrush and Nathan Lambert and Shengyi Huang and Kashif Rasul and Quentin Gallou{\'e}dec},
-	year         = 2020,
-	journal      = {GitHub repository},
-	publisher    = {GitHub},
-	howpublished = {\url{https://github.com/huggingface/trl}}
-}
-```
+## ⚖️ إخلاء مسؤولية وضوابط الاستخدام (Fiqh & Ethical Disclaimer)
+1. هذا النموذج مخصص لأغراض **البحث العلمي، المدارسة الفقهية، والمساعدة الاستدلالية**.
+2. لا يُعتبر بديلاً عن الفتوى القضائية الرسمية في قضايا الأحوال الشخصية، الجنايات، والنزاعات المالية المعقدة.
+3. نلتزم بمنهج أهل السنة والجماعة، ولا نتحمل مسؤولية أي سوء استخدام خارج الأطر الشرعية المعتبرة.