Upload folder using huggingface_hub

app/prompts.py

@@ -20,13 +20,17 @@ TASK_INSTRUCTIONS: Dict[str, str] = {
         "The user asks about a Quranic verse — by partial text, topic, or meaning. Steps:\n"
         "1. Identify the matching verse(s) from the RETRIEVED RESULTS.\n"
         "2. Quote the Arabic verse text EXACTLY from the results.\n"
-        "3. Provide the full reference: Surah name (Arabic & English), number, and Ayah number.\n"
+        "3. Provide the full reference using ONLY the [REF] metadata from the results:\n"
+        "   Surah name (Arabic & English), Surah number, and Ayah number.\n"
+        "   CRITICAL: You MUST copy the Surah name AND Ayah number from the [REF] line.\n"
+        "   NEVER guess or recall a reference from memory — use ONLY what appears in the results.\n"
         "4. Provide the English translation EXACTLY as given in the results.\n"
         "5. If the user searched by partial text, confirm the full verse found.\n"
         "6. Provide Tafsir: explain the meaning, context, and significance.\n"
         "7. If related verses appear in the results, draw connections.\n"
         "8. Answer the user's specific question directly.\n"
-        "9. Do NOT reference verses that are not in the results."
+        "9. Do NOT reference verses that are not in the results.\n"
+        "10. If you cannot find a matching verse in the results, say so clearly."
     ),
     "hadith": (
         "The user asks about a Hadith — by partial text, topic, or meaning. Steps:\n"
@@ -104,10 +108,14 @@ For EVERY supporting evidence, use this exact format:
 ABSOLUTE RULES:
 • Use ONLY content from the Islamic Context block. Zero outside knowledge.
 • Copy Arabic text and translations VERBATIM from context. Never paraphrase.
+• REFERENCE RULE (CRITICAL): For Quran verses, ALWAYS copy the Surah name and Ayah number
+  from the [REF] line in the context. NEVER recall or guess references from memory.
+  Wrong references are worse than no references.
 • If a specific Hadith/verse is NOT in context → respond with:
     "هذا الحديث/الآية غير موجود في قاعدة البيانات." (Arabic)
     or "This Hadith/verse is not in the available dataset." (English)
 • Never invent or guess content.
+• Never attribute a verse to a Surah unless the [REF] metadata explicitly says so.
 
 LANGUAGE RULE (CRITICAL — MUST FOLLOW):
 • You MUST answer in the SAME language as the user's question.

app/search.py

@@ -319,9 +319,19 @@ def build_context(results: list) -> str:
         item_type = "Quranic Verse" if r.get("type") == "quran" else "Hadith"
         grade_str = f" [Grade: {r.get('grade')}]" if r.get("grade") else ""
 
-        lines.append(
+        block = (
             f"[{i}] 📌 {item_type}{grade_str} | {source} | score: {r.get('_score', 0):.3f}\n"
             f"    Arabic : {r.get('arabic', '')}\n"
             f"    English: {r.get('english', '')}"
         )
+
+        # Add explicit structured metadata for Quran verses
+        if r.get("type") == "quran":
+            block += (
+                f"\n    [REF] Surah: {r.get('surah_name_ar', '')} ({r.get('surah_name_en', '')}) "
+                f"| Surah Number: {r.get('surah_number', '')} "
+                f"| Ayah: {r.get('verse_number', '')}"
+            )
+
+        lines.append(block)
     return "\n\n".join(lines)

app/state.py

@@ -33,6 +33,121 @@ logger = logging.getLogger("qmodel.state")
 # POST-GENERATION HALLUCINATION CHECK
 # ═══════════════════════════════════════════════════════════════════════
 _QUOTE_RE = re.compile(r"❝\s*(.+?)\s*❞", re.DOTALL)
+_SURAH_REF_AR = re.compile(
+    r"(?:سورة|سوره)\s+([\u0600-\u06FF\u0750-\u077F\s]+?)[\s,،]*"
+    r"(?:الآية|آية|الايه|ايه)?\s*(\d+)",
+)
+_SURAH_REF_EN = re.compile(
+    r"(?:surah|sura)\s+([A-Za-z\-' ]+?)[\s,]*"
+    r"(?:ayah|verse|ayat)?\s*(\d+)",
+    re.I,
+)
+_SURAH_NUM_REF = re.compile(r"\b(\d{1,3})\s*:\s*(\d{1,3})\b")
+
+
+def _build_valid_refs(results: list) -> set:
+    """Build a set of valid (surah_number, verse_number) tuples from results."""
+    refs = set()
+    for r in results:
+        if r.get("type") == "quran":
+            sn = r.get("surah_number")
+            vn = r.get("verse_number")
+            if sn and vn:
+                refs.add((int(sn), int(vn)))
+    return refs
+
+
+def _build_surah_name_map(results: list) -> dict:
+    """Build a map from normalized surah names to surah numbers."""
+    name_map = {}
+    for r in results:
+        if r.get("type") == "quran":
+            sn = r.get("surah_number")
+            if sn:
+                sn = int(sn)
+                for field in ("surah_name_ar", "surah_name_en", "surah_name_transliteration"):
+                    name = r.get(field, "").strip().lower()
+                    name = re.sub(r"^(ال|al[\-\s']*)", "", name).strip()
+                    if name:
+                        name_map[name] = sn
+    return name_map
+
+
+def _verify_references(answer: str, results: list) -> str:
+    """Check that surah/verse references in the answer match retrieved results.
+
+    Replaces hallucinated references with corrected ones or warnings.
+    """
+    valid_refs = _build_valid_refs(results)
+    if not valid_refs:
+        return answer  # No quran results — nothing to verify
+
+    name_map = _build_surah_name_map(results)
+
+    # Check numeric references like "16:53"
+    def _check_num_ref(m: re.Match) -> str:
+        sn, vn = int(m.group(1)), int(m.group(2))
+        if (sn, vn) in valid_refs:
+            return m.group(0)
+        # Check if any valid ref exists — if so, the LLM hallucinated a different ref
+        logger.warning("Hallucinated reference: %d:%d not in sources", sn, vn)
+        # Find closest valid reference to suggest
+        if len(valid_refs) == 1:
+            correct = next(iter(valid_refs))
+            return f"{correct[0]}:{correct[1]}"
+        return m.group(0)  # Multiple refs — can't auto-correct
+
+    answer = _SURAH_NUM_REF.sub(_check_num_ref, answer)
+
+    # Check Arabic surah name references like "سورة إبراهيم، الآية 7"
+    def _check_ar_ref(m: re.Match) -> str:
+        raw_name = m.group(1).strip()
+        verse_num = int(m.group(2))
+        name_norm = re.sub(r"^(ال)", "", raw_name).strip().lower()
+
+        matched_sn = name_map.get(name_norm)
+        if matched_sn and (matched_sn, verse_num) in valid_refs:
+            return m.group(0)  # Valid reference
+
+        # Check if the combined reference is wrong
+        for (sn, vn) in valid_refs:
+            # Find the correct surah name for this ref
+            for r in results:
+                if r.get("type") == "quran" and int(r.get("surah_number", 0)) == sn and int(r.get("verse_number", 0)) == vn:
+                    correct_name = r.get("surah_name_ar", "")
+                    logger.warning(
+                        "Hallucinated reference: سورة %s آية %d -> correcting to سورة %s آية %d",
+                        raw_name, verse_num, correct_name, vn,
+                    )
+                    return f"سورة {correct_name}، الآية {vn}"
+        return m.group(0)
+
+    answer = _SURAH_REF_AR.sub(_check_ar_ref, answer)
+
+    # Check English surah name references
+    def _check_en_ref(m: re.Match) -> str:
+        raw_name = m.group(1).strip()
+        verse_num = int(m.group(2))
+        name_norm = re.sub(r"^(al[\-\s']*)", "", raw_name, flags=re.I).strip().lower()
+
+        matched_sn = name_map.get(name_norm)
+        if matched_sn and (matched_sn, verse_num) in valid_refs:
+            return m.group(0)
+
+        for (sn, vn) in valid_refs:
+            for r in results:
+                if r.get("type") == "quran" and int(r.get("surah_number", 0)) == sn and int(r.get("verse_number", 0)) == vn:
+                    correct_name = r.get("surah_name_en", "")
+                    logger.warning(
+                        "Hallucinated reference: Surah %s verse %d -> correcting to Surah %s verse %d",
+                        raw_name, verse_num, correct_name, vn,
+                    )
+                    return f"Surah {correct_name}, verse {vn}"
+        return m.group(0)
+
+    answer = _SURAH_REF_EN.sub(_check_en_ref, answer)
+
+    return answer
 
 
 def _verify_citations(answer: str, results: list) -> str:
@@ -273,8 +388,9 @@ async def run_rag_pipeline(
         logger.error("LLM call failed: %s", exc)
         raise HTTPException(status_code=502, detail="LLM service unavailable")
 
-    # 7. Post-generation hallucination check — verify quoted text exists in sources
+    # 7. Post-generation hallucination check
     answer = _verify_citations(answer, results)
+    answer = _verify_references(answer, results)
 
     latency = int((time.perf_counter() - t0) * 1000)
     logger.info(