Upload 8 files

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* 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
+hadith.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,16 @@
+---
+title: Islamic Content Verifier
+emoji: 🕌
+colorFrom: blue
+colorTo: green
+sdk: static
+app_file: index.html
+pinned: false
+license: mit
+short_description: Verify Quran and Hadith quotations with evidence
+---
+
+# Islamic Content Verifier
+
+Verify Quranic and Hadith quotations with evidence. The verification code runs entirely in your browser
+(Python via Pyodide); no text is sent to a server. Source code and documentation: see the GitHub repository.

app.py

@@ -0,0 +1,420 @@
+"""Islamic Content Verifier: Gradio interface around the verification pipeline in ``verifier.py``.
+
+Run locally with ``python app.py``. The rendering helpers are plain functions that return HTML, so they can be
+tested without Gradio; Gradio is imported only when the interface is built.
+"""
+from __future__ import annotations
+
+import html
+import json
+import logging
+import os
+import threading
+from pathlib import Path
+from typing import List, Optional
+
+from verifier import MAX_INPUT_CHARS, IslamicContentVerifier
+
+logger = logging.getLogger(__name__)
+
+EXAMPLES_PATH = Path(__file__).resolve().parent / "demo" / "examples.json"
+DEFAULT_MODEL_DIR = Path(__file__).resolve().parent / "models" / "span_detector"
+
+# --------------------------------------------------------------------------------------------------------------
+# Pipeline access
+# --------------------------------------------------------------------------------------------------------------
+_pipeline: Optional[IslamicContentVerifier] = None
+_pipeline_lock = threading.Lock()
+
+
+def get_pipeline() -> IslamicContentVerifier:
+    """Create the pipeline once (the corpus index builds in a few seconds) and reuse it for every request."""
+    global _pipeline
+    with _pipeline_lock:
+        if _pipeline is None:
+            model_dir = os.environ.get("ICV_DETECTOR_MODEL") or (str(DEFAULT_MODEL_DIR) if DEFAULT_MODEL_DIR.is_dir() else None)
+            # With a trained model folder the BERT detector is used; if it cannot be loaded the rules detector takes over.
+            _pipeline = IslamicContentVerifier(detector="auto" if model_dir else "rules", model_dir=model_dir)
+        return _pipeline
+
+
+def load_examples(path: Path = EXAMPLES_PATH) -> List[dict]:
+    try:
+        with open(path, encoding="utf-8") as handle:
+            return json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        logger.exception("Could not load demo examples from %s", path)
+        return []
+
+
+# --------------------------------------------------------------------------------------------------------------
+# HTML rendering
+# --------------------------------------------------------------------------------------------------------------
+_e = html.escape
+
+GROUP_LABEL = {
+    "verified": ("موثّق", "Verified"),
+    "mismatch": ("غير مطابق", "Mismatch"),
+    "review": ("يحتاج مراجعة بشرية", "Needs Human Review"),
+}
+TYPE_LABEL = {"Ayah": ("آية قرآنية", "Quran"), "Hadith": ("حديث نبوي", "Hadith")}
+INDICATORS = [
+    ("composite", "الدرجة المركبة", "Composite score"),
+    ("coverage", "تغطية الكلمات", "Word coverage"),
+    ("lcs_ratio", "التسلسل النصي", "Sequence (LCS)"),
+    ("token_overlap", "تداخل الكلمات", "Token overlap"),
+    ("edit_sim", "تشابه الأحرف", "Character similarity"),
+    ("diacritic_sim", "مع التشكيل", "With diacritics"),
+]
+
+
+def _pct(value: float) -> str:
+    return f"{round(value * 100)}%"
+
+
+def _source_label(source: dict) -> str:
+    if source["type"] == "Quran":
+        start = source.get("ayah", source.get("ayah_start"))
+        end = source.get("ayah_end", start)
+        verses = f"{start}" if start == end else f"{start}–{end}"
+        return f"سورة {source['surah_name']} — الآية {verses}"
+    return f"حديث رقم {source['hadithID']} — {source['title']}"
+
+
+def _truncate(text: str, limit: int) -> str:
+    return text if len(text) <= limit else text[:limit].rstrip() + " …"
+
+
+def _diff_html(comparison: dict) -> str:
+    """Word-level diff: green = words only in the source, red = words only in the quotation."""
+    parts = []
+    for op in comparison["word_diff"]:
+        if op["op"] == "equal":
+            parts.append(f'<span class="w-eq">{_e(op["span"])}</span>')
+        else:
+            if op["span"]:
+                parts.append(f'<span class="w-extra" title="في الاقتباس فقط · only in the quotation">{_e(op["span"])}</span>')
+            if op["source"]:
+                parts.append(f'<span class="w-missing" title="في المصدر فقط · only in the source">{_e(op["source"])}</span>')
+    return " ".join(parts)
+
+
+def _indicator_table(signals: Optional[dict]) -> str:
+    if not signals:
+        return ""
+    rows = []
+    for key, ar, en in INDICATORS:
+        value = float(signals.get(key, 0.0))
+        rows.append(
+            f'<div class="ind"><div class="ind-name">{ar}<small>{en}</small></div>'
+            f'<div class="bar"><span style="width:{_pct(value)}"></span></div><div class="ind-val">{_pct(value)}</div></div>'
+        )
+    substring = "نعم · Yes" if signals.get("is_substring") else "لا · No"
+    rows.append(f'<div class="ind"><div class="ind-name">احتواء كامل<small>Contained in source</small></div><div class="ind-val wide">{substring}</div></div>')
+    return '<div class="indicators">' + "".join(rows) + "</div>"
+
+
+def _evidence_panel(span: dict) -> str:
+    evidence, verification = span["evidence"], span["verification"]
+    blocks = [
+        f'<div class="ev-row"><b>الاقتباس المكتشف · Detected quotation</b><p class="quote">{_e(span["text"])}</p></div>',
+        f'<div class="ev-row"><b>النوع · Type</b><p>{TYPE_LABEL[span["type"]][0]} · {TYPE_LABEL[span["type"]][1]}</p></div>',
+    ]
+    if evidence:
+        comparison = evidence["comparison"]
+        blocks += [
+            f'<div class="ev-row"><b>المصدر المرشح · Candidate source</b><p>{_e(_source_label(evidence["source"]))}</p></div>',
+            f'<div class="ev-row"><b>نص المصدر الأصلي · Original source text</b><p class="quote">{_e(comparison["source_excerpt"])}</p></div>',
+            f'<div class="ev-row"><b>المقارنة · Comparison</b><p class="diff">{_diff_html(comparison)}</p>'
+            f'<p class="legend"><span class="w-extra">في الاقتباس فقط</span> <span class="w-missing">في المصدر فقط</span> '
+            f'· تشابه الكلمات {_pct(comparison["word_similarity"])}</p></div>',
+            f'<div class="ev-row"><b>مؤشرات التحقق · Similarity indicators</b>{_indicator_table(evidence.get("signals"))}</div>',
+        ]
+    else:
+        blocks.append('<div class="ev-row"><b>المصدر · Source</b><p>لم يُسترجع أي مصدر مرشح · No candidate source was retrieved.</p></div>')
+    blocks += [
+        f'<div class="ev-row"><b>الثقة · Confidence</b><p>{_pct(verification["confidence"])}</p>'
+        f'<p class="legend en">verdict: {_e(verification["verdict"])} · method: {_e(verification["method"])} · '
+        f'candidates checked: {verification["n_candidates"]}</p></div>',
+        f'<div class="ev-row"><b>القرار · Decision</b><p>{_e(span["status_ar"])}<br><span class="en">{_e(span["status_en"])}</span></p></div>',
+        f'<div class="ev-row"><b>سبب القرار · Decision reason</b><p class="en">{_e(span["reason"])}</p></div>',
+    ]
+    return "".join(blocks)
+
+
+def _card(span: dict) -> str:
+    group = span["group"]
+    ar_label, en_label = GROUP_LABEL[group]
+    type_ar, type_en = TYPE_LABEL[span["type"]]
+    evidence = span["evidence"]
+    confidence = span["verification"]["confidence"]
+
+    source_html = comparison_html = ""
+    if evidence:
+        comparison = evidence["comparison"]
+        source_html = (
+            f'<div class="field"><label>المصدر المرشح · Candidate source</label><p>{_e(_source_label(evidence["source"]))}</p></div>'
+            f'<div class="field"><label>نص المصدر الأصلي · Original source text</label>'
+            f'<p class="quote small">{_e(_truncate(comparison["source_excerpt"], 360))}</p></div>'
+        )
+        comparison_html = (
+            f'<div class="field"><label>المقارنة · Comparison</label><p class="diff">{_diff_html(comparison)}</p></div>'
+        )
+    else:
+        source_html = '<div class="field"><label>المصدر المرشح · Candidate source</label><p>لا يوجد · None found</p></div>'
+
+    action = ""
+    correction, suggestion = span["correction"], span["suggestion"]
+    if correction:
+        action = (
+            '<div class="action ok"><b>تصحيح مدعوم بالمصدر · Source-backed correction</b>'
+            f'<p class="quote">{_e(correction["display_text"])}</p>'
+            f'<p class="legend">{_e(_source_label({"type": "Quran", **correction["source"]}) if correction["source"]["type"] == "Quran" else _source_label(correction["source"]))}'
+            f' · قوة المطابقة {_pct(correction["match_strength"])}</p></div>'
+        )
+    elif group == "review":
+        closest = ""
+        if suggestion:
+            src = suggestion["source"]
+            label = _source_label({"type": "Quran", **src}) if src["type"] == "Quran" else _source_label(src)
+            closest = (f'<p class="legend">أقرب مصدر وُجد للمراجِع (ليس تصحيحًا آليًا) · Closest source for the reviewer (not an automatic correction): '
+                       f'{_e(label)}</p><p class="quote small">{_e(_truncate(suggestion["display_text"], 360))}</p>')
+        action = (
+            '<div class="action warn"><b>الأدلة غير كافية للتصحيح الآلي.</b> يُوصى بالمراجعة البشرية.'
+            '<p class="en">Insufficient evidence for automatic correction. Human review is recommended.</p>' + closest + "</div>"
+        )
+    elif span["status"] == "UNSUPPORTED":
+        action = (
+            '<div class="action bad"><b>لا يوجد مصدر مطابق في المراجع المتاحة للنظام.</b> لم يُقترح أي نص بديل.'
+            '<p class="en">No matching source in the corpus. No replacement text is proposed.</p></div>'
+        )
+
+    return f"""
+<div class="qcard {group}">
+  <div class="qhead">
+    <span class="idx">{span["id"]}</span>
+    <span class="badge type">{type_ar} · {type_en}</span>
+    <span class="badge st {group}">{ar_label} · {en_label}</span>
+    <span class="conf">الثقة · Confidence <b>{_pct(confidence)}</b></span>
+  </div>
+  <div class="field"><label>الاقتباس المكتشف · Detected quotation</label><p class="quote">{_e(span["text"])}</p></div>
+  {source_html}
+  {comparison_html}
+  <div class="field"><label>القرار · Decision</label><p>{_e(span["status_ar"])}<br><span class="en">{_e(span["status_en"])}</span></p></div>
+  {action}
+  <details class="evidence"><summary>عرض الدليل · View Evidence</summary><div class="ev-body">{_evidence_panel(span)}</div></details>
+</div>"""
+
+
+def _summary(summary: dict) -> str:
+    tiles = [
+        (summary["n_spans"], "إجمالي الاقتباسات", "Total quotations", ""),
+        (summary["n_ayah"], "آيات قرآنية", "Quranic", ""),
+        (summary["n_hadith"], "أحاديث", "Hadith", ""),
+        (summary["VERIFIED"], "موثّق", "Verified", "verified"),
+        (summary["CORRECTED"] + summary["UNSUPPORTED"], "غير مطابق", "Mismatch", "mismatch"),
+        (summary["HUMAN_REVIEW"], "يحتاج مراجعة بشرية", "Needs Human Review", "review"),
+    ]
+    return '<div class="summary">' + "".join(
+        f'<div class="tile {cls}{" zero" if value == 0 and cls else ""}"><b>{value}</b><span>{ar}</span><small>{en}</small></div>'
+        for value, ar, en, cls in tiles
+    ) + "</div>"
+
+
+def _highlighted_text(result: dict) -> str:
+    text, pieces, cursor = result["input_text"], [], 0
+    for span in result["spans"]:
+        pieces.append(_e(text[cursor:span["start"]]))
+        pieces.append(f'<mark class="{span["group"]}" title="{_e(span["status_en"])}">{_e(text[span["start"]:span["end"]])}</mark>')
+        cursor = span["end"]
+    pieces.append(_e(text[cursor:]))
+    legend = (
+        '<div class="hl-legend"><mark class="verified">موثّق · Verified</mark><mark class="mismatch">غير مطابق · Mismatch</mark>'
+        '<mark class="review">مراجعة بشرية · Review</mark></div>'
+    )
+    return (
+        '<div class="highlight"><label>النص مع الاقتباسات المكتشفة · Text with detected quotations</label><p>'
+        + "".join(pieces) + "</p>" + legend + "</div>"
+    )
+
+
+def render_results(result: dict) -> str:
+    """HTML report for a pipeline result."""
+    if not result["spans"]:
+        return (
+            '<div class="notice">لم يُعثر على اقتباسات قرآنية أو حديثية في هذا النص. '
+            '<span class="en">No Quranic or Hadith quotations were detected. Quotations are currently detected when they are '
+            'enclosed in quotation marks or brackets and introduced by a typical phrase (see Limitations).</span></div>'
+        )
+    names = {"RuleDetector": ("القواعد", "Rule-based"), "BertDetector": ("نموذج BERT", "BERT model")}
+    ar, en = names.get(result["detector"], (result["detector"], result["detector"]))
+    chip = f'<div class="det-chip">الكاشف · Detector: <b>{ar} · {en}</b></div>'
+    return chip + _summary(result["summary"]) + _highlighted_text(result) + "".join(_card(s) for s in result["spans"])
+
+
+def render_message(message_ar: str, message_en: str, kind: str = "info") -> str:
+    return f'<div class="notice {kind}">{_e(message_ar)}<span class="en">{_e(message_en)}</span></div>'
+
+
+def verify_text(text: str) -> str:
+    """Gradio handler: validate the input, run the pipeline and return HTML (never raises)."""
+    if not text or not text.strip():
+        return render_message("الرجاء إدخال نص للتحقق منه.", "Please enter a text to verify.", "warn")
+    try:
+        return render_results(get_pipeline().analyze(text))
+    except ValueError:
+        return render_message(
+            f"النص طويل جدًا (الحد الأقصى {MAX_INPUT_CHARS} حرف).", f"The text is too long (maximum {MAX_INPUT_CHARS} characters).", "warn"
+        )
+    except Exception:
+        logger.exception("Verification failed")
+        return render_message("حدث خطأ غير متوقع أثناء التحقق.", "An unexpected error occurred during verification.", "bad")
+
+
+# --------------------------------------------------------------------------------------------------------------
+# Interface
+# --------------------------------------------------------------------------------------------------------------
+_PATTERN = (
+    "url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='80' height='80' viewBox='0 0 80 80'%3E"
+    "%3Cg fill='none' stroke='%2322d3ee' stroke-opacity='0.07' stroke-width='1'%3E"
+    "%3Crect x='20' y='20' width='40' height='40'/%3E%3Crect x='20' y='20' width='40' height='40' transform='rotate(45 40 40)'/%3E"
+    "%3C/g%3E%3C/svg%3E\")"
+)
+
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Cairo:wght@400;600;700&family=Amiri:wght@400;700&display=swap');
+.gradio-container {
+  --body-background-fill:#0a1128; --block-background-fill:#101a38; --block-border-color:#1e2d57;
+  --input-background-fill:#0d1631; --body-text-color:#e8eefc; --block-label-text-color:#9fb3da;
+  --button-primary-background-fill:#14b8a6; --button-primary-background-fill-hover:#22d3ee; --button-primary-text-color:#04202a;
+  --button-secondary-background-fill:#16244a; --button-secondary-text-color:#e8eefc; --button-secondary-border-color:#2a3d73;
+  background:#0a1128 PATTERN; font-family:'Cairo','Segoe UI',Tahoma,sans-serif; max-width:1080px !important; color:#e8eefc;
+}
+.hero { text-align:center; padding:34px 12px 18px; direction:rtl; }
+.hero .eyebrow { color:#22d3ee; letter-spacing:.14em; font-size:.8rem; text-transform:uppercase; }
+.hero h1 { font-size:2.3rem; margin:.3rem 0 .1rem; color:#fff; }
+.hero h2 { font-size:1.05rem; font-weight:400; color:#9fb3da; margin:0 0 .9rem; direction:ltr; }
+.hero p { max-width:760px; margin:.3rem auto; color:#c7d4f0; line-height:1.9; }
+.hero .en { direction:ltr; color:#8ea3cf; font-size:.92rem; }
+.input-area textarea { direction:rtl; text-align:right; font-family:'Amiri','Cairo',serif !important; font-size:1.2rem !important; line-height:2 !important; }
+.btn-row button { font-weight:700 !important; border-radius:12px !important; }
+.disclaimer { font-size:.82rem; color:#8ea3cf; text-align:center; padding:12px 8px; direction:rtl; line-height:1.8; }
+.disclaimer .en { display:block; direction:ltr; }
+.results { direction:rtl; text-align:right; }
+.results .en, .notice .en { display:block; direction:ltr; text-align:left; color:#8ea3cf; font-size:.88rem; font-weight:400; }
+.summary { display:grid; grid-template-columns:repeat(auto-fit,minmax(130px,1fr)); gap:10px; margin:6px 0 14px; }
+.tile { background:#101a38; border:1px solid #1e2d57; border-radius:14px; padding:12px; text-align:center; }
+.tile b { display:block; font-size:1.8rem; color:#fff; } .tile span { display:block; font-size:.9rem; } .tile small { color:#8ea3cf; }
+.tile.verified { border-color:#14b8a6; } .tile.verified b { color:#2dd4bf; }
+.tile.mismatch { border-color:#f43f5e; } .tile.mismatch b { color:#fb7185; }
+.tile.review { border-color:#f59e0b; } .tile.review b { color:#fbbf24; }
+.highlight { background:#0d1631; border:1px solid #1e2d57; border-radius:14px; padding:14px 16px; margin-bottom:14px; }
+.highlight label, .field label { display:block; color:#7e93c0; font-size:.78rem; margin-bottom:4px; }
+.highlight p { font-family:'Amiri','Cairo',serif; font-size:1.15rem; line-height:2.1; margin:0; white-space:pre-wrap; }
+mark { color:#fff; border-radius:6px; padding:1px 4px; }
+mark.verified { background:rgba(20,184,166,.35); } mark.mismatch { background:rgba(244,63,94,.35); } mark.review { background:rgba(245,158,11,.35); }
+.qcard { background:#101a38; border:1px solid #1e2d57; border-inline-start:5px solid #3b4b7a; border-radius:16px; padding:16px 18px; margin:12px 0; }
+.qcard.verified { border-inline-start-color:#14b8a6; } .qcard.mismatch { border-inline-start-color:#f43f5e; } .qcard.review { border-inline-start-color:#f59e0b; }
+.qhead { display:flex; flex-wrap:wrap; gap:8px; align-items:center; margin-bottom:10px; }
+.idx { background:#1b2a55; border-radius:50%; width:28px; height:28px; display:inline-flex; align-items:center; justify-content:center; font-weight:700; }
+.badge { padding:3px 12px; border-radius:999px; font-size:.82rem; background:#16244a; border:1px solid #2a3d73; }
+.badge.st.verified { background:rgba(20,184,166,.18); border-color:#14b8a6; color:#5eead4; }
+.badge.st.mismatch { background:rgba(244,63,94,.16); border-color:#f43f5e; color:#fda4af; }
+.badge.st.review { background:rgba(245,158,11,.16); border-color:#f59e0b; color:#fcd34d; }
+.conf { margin-inline-start:auto; color:#9fb3da; font-size:.88rem; } .conf b { color:#22d3ee; }
+.field { margin:8px 0; } .field p { margin:0; line-height:1.8; }
+.quote { font-family:'Amiri','Cairo',serif; font-size:1.2rem; line-height:2.1; color:#fff; } .quote.small { font-size:1.05rem; color:#d6e0f7; }
+.diff { font-family:'Amiri','Cairo',serif; font-size:1.1rem; line-height:2.1; }
+.w-extra { background:rgba(244,63,94,.25); border-radius:4px; padding:0 3px; text-decoration:line-through; }
+.w-missing { background:rgba(20,184,166,.28); border-radius:4px; padding:0 3px; }
+.legend { color:#8ea3cf; font-size:.82rem; margin:4px 0 0; } .legend .w-extra { text-decoration:none; }
+.tile.zero { opacity:.5; }
+.det-chip { text-align:center; color:#8ea3cf; font-size:.82rem; margin:2px 0 8px; } .det-chip b { color:#22d3ee; font-weight:600; }
+.hl-legend { display:flex; flex-wrap:wrap; gap:8px; margin-top:10px; font-size:.78rem; } .hl-legend mark { padding:2px 10px; }
+.flow { display:flex; flex-wrap:wrap; justify-content:center; align-items:center; gap:8px; margin:16px 0 4px; direction:rtl; }
+.flow span { background:#101a38; border:1px solid #1e2d57; border-radius:999px; padding:5px 14px; font-size:.85rem; color:#cfe0ff; }
+.flow span small { color:#7e93c0; margin-inline-start:6px; direction:ltr; display:inline-block; }
+.flow i { color:#22d3ee; font-style:normal; }
+.hero .mark { width:52px; height:52px; margin:0 auto 6px; display:block; }
+.hero h1 { background:linear-gradient(90deg,#fff,#a5f3fc); -webkit-background-clip:text; background-clip:text; color:transparent; }
+.action { border-radius:12px; padding:10px 14px; margin-top:10px; line-height:1.8; }
+.action.ok { background:rgba(20,184,166,.12); border:1px solid #14b8a6; }
+.action.warn { background:rgba(245,158,11,.12); border:1px solid #f59e0b; }
+.action.bad { background:rgba(244,63,94,.12); border:1px solid #f43f5e; }
+.evidence { margin-top:12px; border-top:1px dashed #2a3d73; padding-top:8px; }
+.evidence summary { cursor:pointer; color:#22d3ee; font-weight:700; }
+.ev-row { margin:10px 0; } .ev-row b { color:#9fb3da; font-size:.85rem; } .ev-row p { margin:2px 0; }
+.indicators { display:grid; gap:6px; margin-top:6px; }
+.ind { display:grid; grid-template-columns:150px 1fr 48px; gap:10px; align-items:center; font-size:.85rem; }
+.ind-name small { display:block; color:#7e93c0; font-size:.72rem; direction:ltr; text-align:right; }
+.bar { background:#0d1631; border-radius:999px; height:8px; overflow:hidden; } .bar span { display:block; height:100%; background:linear-gradient(90deg,#14b8a6,#22d3ee); }
+.ind-val { text-align:left; direction:ltr; color:#cfe0ff; } .ind-val.wide { grid-column:2 / span 2; text-align:right; }
+.notice { background:#101a38; border:1px solid #1e2d57; border-radius:14px; padding:16px; direction:rtl; line-height:1.9; }
+.notice.warn { border-color:#f59e0b; } .notice.bad { border-color:#f43f5e; }
+@media (max-width:640px){ .hero h1{font-size:1.7rem;} .ind{grid-template-columns:110px 1fr 40px;} }
+""".replace("PATTERN", _PATTERN)
+
+HERO = """
+<div class="hero">
+  <svg class="mark" viewBox="0 0 52 52" fill="none" stroke="#22d3ee" stroke-width="1.6" aria-hidden="true">
+    <rect x="11" y="11" width="30" height="30"/><rect x="11" y="11" width="30" height="30" transform="rotate(45 26 26)"/>
+    <circle cx="26" cy="26" r="6" fill="#14b8a6" stroke="none"/></svg>
+  <div class="eyebrow">Islamic Content Verifier</div>
+  <h1>مُدقِّق المحتوى الإسلامي</h1>
+  <h2>Verify Quranic and Hadith quotations with evidence.</h2>
+  <p>الصق نصًا ولّده نموذج لغوي، وسيكتشف النظام الآيات والأحاديث الواردة فيه، ويسترجع نصوصها من المصادر، ويقارنها كلمةً بكلمة،
+     ثم يعرض الدليل. وإذا لم تكفِ الأدلة فلن يختلق تصحيحًا، بل يحيل الحالة إلى المراجعة البشرية.</p>
+  <p class="en">Paste text generated by a language model. The system detects Quran and Hadith quotations, retrieves the source texts,
+     compares them word by word and shows the evidence. When evidence is insufficient it never invents a correction: it recommends human review.</p>
+  <div class="flow"><span>كشف<small>Detect</small></span><i>←</i><span>استرجاع<small>Retrieve</small></span><i>←</i>
+    <span>تحقق<small>Verify</small></span><i>←</i><span>دليل<small>Evidence</small></span><i>←</i><span>قرار<small>Decide</small></span></div>
+</div>
+"""
+
+DISCLAIMER = """
+<div class="disclaimer">أداة مساعدة للتدقيق النصي وليست فتوى ولا بديلًا عن المراجعة المتخصصة. النتائج مبنية على مراجع القرآن والكتب الستة المضمّنة فقط.
+<span class="en">A text-verification aid, not a religious ruling and not a substitute for expert review. Results rely only on the bundled Quran and Six Books corpora.</span></div>
+"""
+
+PLACEHOLDER = "الصق هنا الرد الذي ولّده النموذج اللغوي، ويفضَّل أن تكون الاقتباسات بين علامات تنصيص بعد عبارة مثل «قال الله تعالى» أو «قال رسول الله ﷺ»…"
+
+
+def build_interface():
+    import gradio as gr
+
+    examples = load_examples()
+
+    def next_example(index: int):
+        if not examples:
+            return "", 0
+        return examples[index % len(examples)]["text"], (index + 1) % len(examples)
+
+    with gr.Blocks(title="Islamic Content Verifier", css=CSS, theme=gr.themes.Base(primary_hue="teal", neutral_hue="slate")) as demo:
+        gr.HTML(HERO)
+        example_index = gr.State(0)
+        text_input = gr.Textbox(
+            label="النص المراد التحقق منه · Text to verify", lines=9, max_lines=24, placeholder=PLACEHOLDER,
+            rtl=True, elem_classes="input-area",
+        )
+        with gr.Row(elem_classes="btn-row"):
+            verify_button = gr.Button("تحقق من النص · Verify Text", variant="primary", scale=3)
+            example_button = gr.Button("جرّب مثالًا · Try an Example", variant="secondary", scale=2)
+        results = gr.HTML(elem_classes="results")
+        gr.HTML(DISCLAIMER)
+
+        verify_button.click(verify_text, inputs=text_input, outputs=results)
+        text_input.submit(verify_text, inputs=text_input, outputs=results)
+        example_button.click(next_example, inputs=example_index, outputs=[text_input, example_index]).then(
+            verify_text, inputs=text_input, outputs=results
+        )
+    return demo
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+    get_pipeline()   # build the index before serving the first request
+    build_interface().queue().launch(share=os.environ.get("ICV_SHARE") == "1")   # ICV_SHARE=1 -> temporary public link (e.g. on Colab)
+
+
+if __name__ == "__main__":
+    main()

examples.json

@@ -0,0 +1,107 @@
+[
+  {
+    "id": "correct_ayah",
+    "title_ar": "آية صحيحة",
+    "title_en": "Correct Quranic quotation",
+    "scenario": "correct",
+    "text": "يقول الله تعالى: \"يَا أَيُّهَا الَّذِينَ آمَنُوا اسْتَعِينُوا بِالصَّبْرِ وَالصَّلَاةِ ۚ إِنَّ اللَّهَ مَعَ الصَّابِرِينَ\". وهذه الآية تدل على معية الله للصابرين.",
+    "built_from": [
+      "Quran البقرة 2:153"
+    ],
+    "observed_statuses": [
+      "VERIFIED"
+    ]
+  },
+  {
+    "id": "correct_hadith",
+    "title_ar": "حديث صحيح",
+    "title_en": "Correct Hadith quotation",
+    "scenario": "correct",
+    "text": "وقال رسول الله صلى الله عليه وسلم: \"إِنَّمَا الْأَعْمَالُ بِالنِّيَّاتِ ، وَإِنَّمَا لِكُلِّ امْرِئٍ مَا نَوَى ، فَمَنْ كَانَتْ هِجْرَتُهُ إِلَى دُنْيَا يُصِيبُهَا ، أَوْ إِلَى امْرَأَةٍ يَنْكِحُهَا ، فَهِجْرَتُهُ إِلَى مَا هَاجَرَ إِلَيْهِ\". ويستفاد منه أهمية النية في الأعمال.",
+    "built_from": [
+      "Hadith #5"
+    ],
+    "observed_statuses": [
+      "VERIFIED"
+    ]
+  },
+  {
+    "id": "modified_missing_word",
+    "title_ar": "آية ناقصة كلمة",
+    "title_en": "Quranic quotation with one word removed",
+    "scenario": "modified",
+    "text": "قال الله تعالى: \"يَا أَيُّهَا آمَنُوا اسْتَعِينُوا بِالصَّبْرِ وَالصَّلَاةِ ۚ إِنَّ اللَّهَ مَعَ الصَّابِرِينَ\".",
+    "built_from": [
+      "Quran 2:153 (word 3 removed)"
+    ],
+    "observed_statuses": [
+      "HUMAN_REVIEW"
+    ]
+  },
+  {
+    "id": "modified_replaced_word",
+    "title_ar": "آية بكلمة مستبدلة",
+    "title_en": "Quranic quotation with one word replaced",
+    "scenario": "modified",
+    "text": "قال تعالى: \"يَا أَيُّهَا الَّذِينَ إِلَـٰهَ اسْتَعِينُوا بِالصَّبْرِ وَالصَّلَاةِ ۚ إِنَّ اللَّهَ مَعَ الصَّابِرِينَ\"",
+    "built_from": [
+      "Quran 2:153 (word 4 replaced by a word from 2:255)"
+    ],
+    "observed_statuses": [
+      "CORRECTED"
+    ]
+  },
+  {
+    "id": "partial_ayah",
+    "title_ar": "اقتباس جزئي من آية",
+    "title_en": "Exact partial quotation of a longer ayah",
+    "scenario": "partial",
+    "text": "قال الله تعالى: \"۞ وَقَضَىٰ رَبُّكَ أَلَّا تَعْبُدُوا إِلَّا\".",
+    "built_from": [
+      "Quran 17:23 (first six words)"
+    ],
+    "observed_statuses": [
+      "VERIFIED"
+    ]
+  },
+  {
+    "id": "uncertain_hadith",
+    "title_ar": "حديث مركّب من حديثين",
+    "title_en": "Hadith assembled from halves of two different Hadith",
+    "scenario": "uncertain",
+    "text": "روى البخاري أن النبي صلى الله عليه وسلم قال: \"إِنَّمَا الْأَعْمَالُ بِالنِّيَّاتِ ، وَإِنَّمَا لِكُلِّ امْرِئٍ مَا نَوَى ، فَمَنْ كَانَتْ هِجْرَتُهُ أَهْلَ الْأَرْضِ يَرْحَمْكُمْ مَنْ فِي السَّمَاءِ\".",
+    "built_from": [
+      "Hadith #5 (first half)",
+      "Hadith #95766 (second half)"
+    ],
+    "observed_statuses": [
+      "HUMAN_REVIEW"
+    ]
+  },
+  {
+    "id": "no_quotation",
+    "title_ar": "نص بلا اقتباسات",
+    "title_en": "Text without any quotation",
+    "scenario": "none",
+    "text": "الصبر من أهم الصفات التي ينبغي أن يتحلى بها الإنسان في حياته، ويساعده على مواجهة المصاعب بثبات وهدوء.",
+    "built_from": [],
+    "observed_statuses": []
+  },
+  {
+    "id": "mixed_response",
+    "title_ar": "رد مختلط",
+    "title_en": "Mixed response: correct ayah, correct Hadith, modified ayah",
+    "scenario": "mixed",
+    "text": "بخصوص بر الوالدين، قال الله تعالى: \"۞ وَقَضَىٰ رَبُّكَ أَلَّا تَعْبُدُوا إِلَّا إِيَّاهُ وَبِالْوَالِدَيْنِ إِحْسَانًا ۚ إِمَّا يَبْلُغَنَّ عِنْدَكَ الْكِبَرَ أَحَدُهُمَا أَوْ كِلَاهُمَا فَلَا تَقُلْ لَهُمَا أُفٍّ وَلَا تَنْهَرْهُمَا وَقُلْ لَهُمَا قَوْلًا كَرِيمًا\". وقال رسول الله صلى الله عليه وسلم: \"الرَّاحِمُونَ يَرْحَمُهُمُ الرَّحْمَنُ ، ارْحَمُوا أَهْلَ الْأَرْضِ يَرْحَمْكُمْ مَنْ فِي السَّمَاءِ\". وقال سبحانه: \"يَا أَيُّهَا آمَنُوا اسْتَعِينُوا بِالصَّبْرِ وَالصَّلَاةِ ۚ إِنَّ اللَّهَ مَعَ الصَّابِرِينَ\". وهذا من مكارم الأخلاق.",
+    "built_from": [
+      "Quran 17:23",
+      "Hadith #95766",
+      "Quran 2:153 (word 3 removed)"
+    ],
+    "observed_statuses": [
+      "VERIFIED",
+      "VERIFIED",
+      "HUMAN_REVIEW"
+    ]
+  }
+]

hadith.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f1f514d7a2de2d4179d9588a861cedf07e81630886444f37d0c08c2cc777075a
+size 48498788

index.html

@@ -0,0 +1,264 @@
+<!doctype html>
+<html lang="ar" dir="rtl">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Islamic Content Verifier</title>
+<style>
+@import url('https://fonts.googleapis.com/css2?family=Cairo:wght@400;600;700&family=Amiri:wght@400;700&display=swap');
+.gradio-container {
+  --body-background-fill:#0a1128; --block-background-fill:#101a38; --block-border-color:#1e2d57;
+  --input-background-fill:#0d1631; --body-text-color:#e8eefc; --block-label-text-color:#9fb3da;
+  --button-primary-background-fill:#14b8a6; --button-primary-background-fill-hover:#22d3ee; --button-primary-text-color:#04202a;
+  --button-secondary-background-fill:#16244a; --button-secondary-text-color:#e8eefc; --button-secondary-border-color:#2a3d73;
+  background:#0a1128 url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='80' height='80' viewBox='0 0 80 80'%3E%3Cg fill='none' stroke='%2322d3ee' stroke-opacity='0.07' stroke-width='1'%3E%3Crect x='20' y='20' width='40' height='40'/%3E%3Crect x='20' y='20' width='40' height='40' transform='rotate(45 40 40)'/%3E%3C/g%3E%3C/svg%3E"); font-family:'Cairo','Segoe UI',Tahoma,sans-serif; max-width:1080px !important; color:#e8eefc;
+}
+.hero { text-align:center; padding:34px 12px 18px; direction:rtl; }
+.hero .eyebrow { color:#22d3ee; letter-spacing:.14em; font-size:.8rem; text-transform:uppercase; }
+.hero h1 { font-size:2.3rem; margin:.3rem 0 .1rem; color:#fff; }
+.hero h2 { font-size:1.05rem; font-weight:400; color:#9fb3da; margin:0 0 .9rem; direction:ltr; }
+.hero p { max-width:760px; margin:.3rem auto; color:#c7d4f0; line-height:1.9; }
+.hero .en { direction:ltr; color:#8ea3cf; font-size:.92rem; }
+.input-area textarea { direction:rtl; text-align:right; font-family:'Amiri','Cairo',serif !important; font-size:1.2rem !important; line-height:2 !important; }
+.btn-row button { font-weight:700 !important; border-radius:12px !important; }
+.disclaimer { font-size:.82rem; color:#8ea3cf; text-align:center; padding:12px 8px; direction:rtl; line-height:1.8; }
+.disclaimer .en { display:block; direction:ltr; }
+.results { direction:rtl; text-align:right; }
+.results .en, .notice .en { display:block; direction:ltr; text-align:left; color:#8ea3cf; font-size:.88rem; font-weight:400; }
+.summary { display:grid; grid-template-columns:repeat(auto-fit,minmax(130px,1fr)); gap:10px; margin:6px 0 14px; }
+.tile { background:#101a38; border:1px solid #1e2d57; border-radius:14px; padding:12px; text-align:center; }
+.tile b { display:block; font-size:1.8rem; color:#fff; } .tile span { display:block; font-size:.9rem; } .tile small { color:#8ea3cf; }
+.tile.verified { border-color:#14b8a6; } .tile.verified b { color:#2dd4bf; }
+.tile.mismatch { border-color:#f43f5e; } .tile.mismatch b { color:#fb7185; }
+.tile.review { border-color:#f59e0b; } .tile.review b { color:#fbbf24; }
+.highlight { background:#0d1631; border:1px solid #1e2d57; border-radius:14px; padding:14px 16px; margin-bottom:14px; }
+.highlight label, .field label { display:block; color:#7e93c0; font-size:.78rem; margin-bottom:4px; }
+.highlight p { font-family:'Amiri','Cairo',serif; font-size:1.15rem; line-height:2.1; margin:0; white-space:pre-wrap; }
+mark { color:#fff; border-radius:6px; padding:1px 4px; }
+mark.verified { background:rgba(20,184,166,.35); } mark.mismatch { background:rgba(244,63,94,.35); } mark.review { background:rgba(245,158,11,.35); }
+.qcard { background:#101a38; border:1px solid #1e2d57; border-inline-start:5px solid #3b4b7a; border-radius:16px; padding:16px 18px; margin:12px 0; }
+.qcard.verified { border-inline-start-color:#14b8a6; } .qcard.mismatch { border-inline-start-color:#f43f5e; } .qcard.review { border-inline-start-color:#f59e0b; }
+.qhead { display:flex; flex-wrap:wrap; gap:8px; align-items:center; margin-bottom:10px; }
+.idx { background:#1b2a55; border-radius:50%; width:28px; height:28px; display:inline-flex; align-items:center; justify-content:center; font-weight:700; }
+.badge { padding:3px 12px; border-radius:999px; font-size:.82rem; background:#16244a; border:1px solid #2a3d73; }
+.badge.st.verified { background:rgba(20,184,166,.18); border-color:#14b8a6; color:#5eead4; }
+.badge.st.mismatch { background:rgba(244,63,94,.16); border-color:#f43f5e; color:#fda4af; }
+.badge.st.review { background:rgba(245,158,11,.16); border-color:#f59e0b; color:#fcd34d; }
+.conf { margin-inline-start:auto; color:#9fb3da; font-size:.88rem; } .conf b { color:#22d3ee; }
+.field { margin:8px 0; } .field p { margin:0; line-height:1.8; }
+.quote { font-family:'Amiri','Cairo',serif; font-size:1.2rem; line-height:2.1; color:#fff; } .quote.small { font-size:1.05rem; color:#d6e0f7; }
+.diff { font-family:'Amiri','Cairo',serif; font-size:1.1rem; line-height:2.1; }
+.w-extra { background:rgba(244,63,94,.25); border-radius:4px; padding:0 3px; text-decoration:line-through; }
+.w-missing { background:rgba(20,184,166,.28); border-radius:4px; padding:0 3px; }
+.legend { color:#8ea3cf; font-size:.82rem; margin:4px 0 0; } .legend .w-extra { text-decoration:none; }
+.tile.zero { opacity:.5; }
+.det-chip { text-align:center; color:#8ea3cf; font-size:.82rem; margin:2px 0 8px; } .det-chip b { color:#22d3ee; font-weight:600; }
+.hl-legend { display:flex; flex-wrap:wrap; gap:8px; margin-top:10px; font-size:.78rem; } .hl-legend mark { padding:2px 10px; }
+.flow { display:flex; flex-wrap:wrap; justify-content:center; align-items:center; gap:8px; margin:16px 0 4px; direction:rtl; }
+.flow span { background:#101a38; border:1px solid #1e2d57; border-radius:999px; padding:5px 14px; font-size:.85rem; color:#cfe0ff; }
+.flow span small { color:#7e93c0; margin-inline-start:6px; direction:ltr; display:inline-block; }
+.flow i { color:#22d3ee; font-style:normal; }
+.hero .mark { width:52px; height:52px; margin:0 auto 6px; display:block; }
+.hero h1 { background:linear-gradient(90deg,#fff,#a5f3fc); -webkit-background-clip:text; background-clip:text; color:transparent; }
+.action { border-radius:12px; padding:10px 14px; margin-top:10px; line-height:1.8; }
+.action.ok { background:rgba(20,184,166,.12); border:1px solid #14b8a6; }
+.action.warn { background:rgba(245,158,11,.12); border:1px solid #f59e0b; }
+.action.bad { background:rgba(244,63,94,.12); border:1px solid #f43f5e; }
+.evidence { margin-top:12px; border-top:1px dashed #2a3d73; padding-top:8px; }
+.evidence summary { cursor:pointer; color:#22d3ee; font-weight:700; }
+.ev-row { margin:10px 0; } .ev-row b { color:#9fb3da; font-size:.85rem; } .ev-row p { margin:2px 0; }
+.indicators { display:grid; gap:6px; margin-top:6px; }
+.ind { display:grid; grid-template-columns:150px 1fr 48px; gap:10px; align-items:center; font-size:.85rem; }
+.ind-name small { display:block; color:#7e93c0; font-size:.72rem; direction:ltr; text-align:right; }
+.bar { background:#0d1631; border-radius:999px; height:8px; overflow:hidden; } .bar span { display:block; height:100%; background:linear-gradient(90deg,#14b8a6,#22d3ee); }
+.ind-val { text-align:left; direction:ltr; color:#cfe0ff; } .ind-val.wide { grid-column:2 / span 2; text-align:right; }
+.notice { background:#101a38; border:1px solid #1e2d57; border-radius:14px; padding:16px; direction:rtl; line-height:1.9; }
+.notice.warn { border-color:#f59e0b; } .notice.bad { border-color:#f43f5e; }
+@media (max-width:640px){ .hero h1{font-size:1.7rem;} .ind{grid-template-columns:110px 1fr 40px;} }
+
+html,body{margin:0;background:#0a1128;}
+.gradio-container{min-height:100vh;box-sizing:border-box;padding:8px 16px 24px;margin:0 auto;}
+.input-area textarea{width:100%;box-sizing:border-box;min-height:220px;background:#0d1631;color:#e8eefc;border:1px solid #1e2d57;border-radius:14px;padding:14px;resize:vertical;outline:none;}
+.input-area textarea:focus{border-color:#22d3ee;}
+.input-area label{display:block;color:#9fb3da;font-size:.85rem;margin:0 0 6px;direction:rtl;text-align:right;}
+.btn-row{display:flex;gap:12px;margin:12px 0 18px;flex-wrap:wrap;}
+.btn-row button{flex:1 1 220px;border:0;border-radius:12px;padding:13px 18px;font-size:1rem;font-weight:700;cursor:pointer;font-family:inherit;}
+#verify{background:#14b8a6;color:#04202a;} #verify:hover{background:#22d3ee;}
+#example{background:#16244a;color:#e8eefc;border:1px solid #2a3d73;} #example:hover{border-color:#22d3ee;}
+.btn-row button:disabled{opacity:.45;cursor:not-allowed;}
+#status{direction:rtl;text-align:center;color:#9fb3da;font-size:.92rem;margin:0 0 10px;min-height:1.4em;}
+#status .en{display:block;direction:ltr;color:#7e93c0;font-size:.82rem;}
+.spinner{display:inline-block;width:14px;height:14px;border:2px solid #2a3d73;border-top-color:#22d3ee;border-radius:50%;animation:spin 1s linear infinite;vertical-align:middle;margin-inline-end:8px;}
+@keyframes spin{to{transform:rotate(360deg)}}
+</style>
+</head>
+<body>
+<div class="gradio-container">
+
+<div class="hero">
+  <svg class="mark" viewBox="0 0 52 52" fill="none" stroke="#22d3ee" stroke-width="1.6" aria-hidden="true">
+    <rect x="11" y="11" width="30" height="30"/><rect x="11" y="11" width="30" height="30" transform="rotate(45 26 26)"/>
+    <circle cx="26" cy="26" r="6" fill="#14b8a6" stroke="none"/></svg>
+  <div class="eyebrow">Islamic Content Verifier</div>
+  <h1>مُدقِّق المحتوى الإسلامي</h1>
+  <h2>Verify Quranic and Hadith quotations with evidence.</h2>
+  <p>الصق نصًا ولّده نموذج لغوي، وسيكتشف النظام الآيات والأحاديث الواردة فيه، ويسترجع نصوصها من المصادر، ويقارنها كلمةً بكلمة،
+     ثم يعرض الدليل. وإذا لم تكفِ الأدلة فلن يختلق تصحيحًا، بل يحيل الحالة إلى المراجعة البشرية.</p>
+  <p class="en">Paste text generated by a language model. The system detects Quran and Hadith quotations, retrieves the source texts,
+     compares them word by word and shows the evidence. When evidence is insufficient it never invents a correction: it recommends human review.</p>
+  <div class="flow"><span>كشف<small>Detect</small></span><i>←</i><span>استرجاع<small>Retrieve</small></span><i>←</i>
+    <span>تح��ق<small>Verify</small></span><i>←</i><span>دليل<small>Evidence</small></span><i>←</i><span>قرار<small>Decide</small></span></div>
+</div>
+
+<div class="input-area">
+  <label for="text">النص المراد التحقق منه · Text to verify</label>
+  <textarea id="text" dir="rtl" placeholder="الصق هنا الرد الذي ولّده النموذج اللغوي، ويفضَّل أن تكون الاقتباسات بين علامات تنصيص بعد عبارة مثل «قال الله تعالى» أو «قال رسول الله ﷺ»…"></textarea>
+</div>
+<div class="btn-row">
+  <button id="verify" disabled>تحقق من النص · Verify Text</button>
+  <button id="example" disabled>جرّب مثالًا · Try an Example</button>
+</div>
+<div id="status"></div>
+<div id="results" class="results"></div>
+
+<div class="disclaimer">أداة مساعدة للتدقيق النصي وليست فتوى ولا بديلًا عن المراجعة المتخصصة. النتائج مبنية على مراجع القرآن والكتب الستة المضمّنة فقط.
+<span class="en">A text-verification aid, not a religious ruling and not a substitute for expert review. Results rely only on the bundled Quran and Six Books corpora.</span></div>
+
+</div>
+<script type="text/plain" id="worker-src">
+// Runs Pyodide and the verification code off the main thread so the page stays responsive while the index builds.
+let verify = null;
+const post = (message) => self.postMessage(message);
+const status = (ar, en) => post({ type: "status", ar, en });
+
+async function fetchBytes(url, onProgress) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error("Could not download " + url + " (" + response.status + ")");
+  const total = Number(response.headers.get("Content-Length")) || 0;
+  if (!response.body || !onProgress) return new Uint8Array(await response.arrayBuffer());
+  const reader = response.body.getReader(), chunks = []; let received = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value); received += value.length; onProgress(received, total);
+  }
+  const bytes = new Uint8Array(received); let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
+  return bytes;
+}
+
+// Accept both layouts: files inside data/ and demo/ folders, or uploaded flat next to index.html.
+async function fetchAny(names, base, onProgress) {
+  let lastError = null;
+  for (const name of names) {
+    for (const path of [name, name.split("/").pop()]) {
+      try { return await fetchBytes(new URL(path, base).href, onProgress); } catch (error) { lastError = error; }
+    }
+  }
+  throw lastError;
+}
+
+async function boot(message) {
+  const url = (file) => new URL(file, message.base).href;
+  status("جارٍ تحميل بيئة بايثون…", "Loading the Python runtime…");
+  importScripts("https://cdn.jsdelivr.net/pyodide/v" + message.pyodideVersion + "/full/pyodide.js");
+  const pyodide = await loadPyodide();
+
+  status("جارٍ تحميل الكود والمراجع…", "Downloading code and corpora…");
+  for (const dir of ["/app", "/app/data", "/app/demo"]) pyodide.FS.mkdir(dir);
+  for (const file of message.files) pyodide.FS.writeFile("/app/" + file, await fetchAny([file], message.base));
+  const hadith = await fetchAny(["data/hadith.json.gz", "data/hadith.json"], message.base, (got, total) => {
+    const mb = (got / 1048576).toFixed(1), of = total ? " / " + (total / 1048576).toFixed(1) : "";
+    status("جارٍ تحميل كتب الحديث… " + mb + of + " MB", "Downloading the Hadith corpus… " + mb + of + " MB");
+  });
+  const isGzip = hadith[0] === 0x1f && hadith[1] === 0x8b;   // the file may be the compressed or the plain JSON copy
+  pyodide.FS.writeFile(isGzip ? "/app/data/hadith.json.gz" : "/app/data/hadith.json", hadith);
+  const examples = JSON.parse(new TextDecoder().decode(pyodide.FS.readFile("/app/demo/examples.json")));
+
+  status("جارٍ بناء فهرس المصادر (مرة واحدة، قد يستغرق دقيقة)…", "Building the source index (once, may take up to a minute)…");
+  pyodide.runPython("import sys; sys.path.insert(0, '/app')");
+  pyodide.runPython("from app import get_pipeline, verify_text; get_pipeline()");
+  verify = pyodide.globals.get("verify_text");
+  post({ type: "ready", examples });
+}
+
+self.onmessage = async (event) => {
+  const message = event.data;
+  if (message.type === "boot") {
+    try { await boot(message); }
+    catch (error) { post({ type: "error", message: String((error && error.message) || error) }); }
+  } else if (message.type === "verify") {
+    try { post({ type: "result", id: message.id, html: verify(message.text) }); }
+    catch (error) { post({ type: "result", id: message.id, html: null }); }
+  }
+};
+</script>
+<script>
+const PYODIDE_VERSION = "0.26.4";
+const PYTHON_FILES = ["app.py", "verifier.py", "retrieval.py"];
+const $ = (id) => document.getElementById(id);
+let examples = [], exampleIndex = 0, nextId = 0, worker = null;
+const pending = new Map();
+
+function setStatus(ar, en, busy = true) {
+  $("status").innerHTML = (busy ? '<span class="spinner"></span>' : "") + ar + '<span class="en">' + en + "</span>";
+}
+
+function fail(message) {
+  console.error(message);
+  setStatus("تعذّر تشغيل النظام. جرّب متصفح كمبيوتر حديثًا ثم أعد تحميل الصفحة.",
+            "The verifier could not start (" + message + "). Try a modern desktop browser and reload the page.", false);
+}
+
+function ask(text) {
+  return new Promise((resolve) => {
+    const id = ++nextId;
+    pending.set(id, resolve);
+    worker.postMessage({ type: "verify", id, text });
+  });
+}
+
+async function run() {
+  if (!worker) return;
+  $("verify").disabled = $("example").disabled = true;
+  setStatus("جارٍ التحقق…", "Verifying…");
+  const html = await ask($("text").value);
+  $("results").innerHTML = html !== null ? html
+    : '<div class="notice bad">حدث خطأ غير متوقع.<span class="en">An unexpected error occurred.</span></div>';
+  setStatus("", "", false);
+  $("verify").disabled = $("example").disabled = false;
+}
+
+function start() {
+  try {
+    const source = $("worker-src").textContent;
+    worker = new Worker(URL.createObjectURL(new Blob([source], { type: "text/javascript" })));
+  } catch (error) { return fail(error.message); }
+  worker.onerror = (event) => fail(event.message || "worker error");
+  worker.onmessage = (event) => {
+    const message = event.data;
+    if (message.type === "status") setStatus(message.ar, message.en);
+    else if (message.type === "error") fail(message.message);
+    else if (message.type === "result") { const resolve = pending.get(message.id); pending.delete(message.id); resolve(message.html); }
+    else if (message.type === "ready") {
+      examples = message.examples;
+      $("verify").disabled = $("example").disabled = false;
+      setStatus("جاهز. الكود يعمل داخل متصفحك ولا يُرسل النص إلى أي خادم.",
+                "Ready. The code runs in your browser; your text is not sent to any server.", false);
+    }
+  };
+  worker.postMessage({ type: "boot", base: location.href, pyodideVersion: PYODIDE_VERSION,
+                       files: PYTHON_FILES.concat(["demo/examples.json", "data/quran.json"]) });
+}
+
+$("verify").addEventListener("click", run);
+$("example").addEventListener("click", () => {
+  if (!examples.length) return;
+  $("text").value = examples[exampleIndex % examples.length].text;
+  exampleIndex += 1;
+  run();
+});
+start();
+</script>
+</body>
+</html>

retrieval.py

@@ -0,0 +1,274 @@
+"""Arabic text normalisation and source retrieval over the Quran and Hadith corpora.
+
+The retriever is the single shared index used by both verification and correction. It was extracted from the
+IslamicEval 2025 research notebook (``research/IslamicEval_Unified.ipynb``) and keeps its retrieval logic:
+
+* Quran: word-vote retrieval of single ayahs (coverage / precision F1) plus IDF-weighted seeds for
+  multi-ayah window search.
+* Hadith: IDF word-vote recall followed by a character 4-gram cosine re-rank.
+"""
+from __future__ import annotations
+
+import gzip
+import json
+import logging
+import math
+import os
+import re
+import unicodedata
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Sequence, Tuple
+
+logger = logging.getLogger(__name__)
+
+BASE_DIR = Path(__file__).resolve().parent
+DEFAULT_QURAN_PATH = BASE_DIR / "data" / "quran.json"
+DEFAULT_HADITH_PATH = BASE_DIR / "data" / "hadith.json"
+
+# --------------------------------------------------------------------------------------------------------------
+# Arabic normalisation
+# --------------------------------------------------------------------------------------------------------------
+_DIACRITICS = re.compile(
+    r"[\u0610-\u061A\u064B-\u065F\u0670\u06D6-\u06DC\u06DF-\u06E4\u06E7\u06E8\u06EA-\u06ED\u0640]"
+)
+_PUNCTUATION = re.compile(r"[،؛؟!،.,:;'\"()\[\]{}<>«»\-_/\\|@#$%^&*+=~`]")
+_MULTI_SPACE = re.compile(r"\s+")
+_ALEF_VARIANTS = re.compile(r"[أإآٱ]")
+_MATCH_DIACRITICS = re.compile(r"[\u0610-\u061A\u064B-\u065F\u0670\u06D6-\u06DC\u06DF-\u06E8\u06EA-\u06ED\u0640]")
+
+STOPWORDS = frozenset(
+    """من في على ان أن إن الى إلى عن مع ما لا لم لن قد و ثم أو او هو هي هم انت أنتم كان كانت يكون تكون قال قالت
+هذا هذه ذلك تلك الذي التي الذين اللاتي اللائي كل بعض غير عند بين حتى إذا اذا لو لكن بل يا أيها ايها""".split()
+)
+
+
+def normalize_strict(text: Optional[str]) -> str:
+    """Remove diacritics, unify alef variants and strip punctuation (keeps ta marbuta / alef maqsura)."""
+    if not text:
+        return ""
+    text = unicodedata.normalize("NFC", text)
+    text = _DIACRITICS.sub("", text)
+    text = _ALEF_VARIANTS.sub("ا", text)
+    text = _PUNCTUATION.sub(" ", text)
+    return _MULTI_SPACE.sub(" ", text).strip()
+
+
+def normalize_lenient(text: Optional[str]) -> str:
+    """Strict normalisation plus ta-marbuta/ha and alef-maqsura/ya folding (used for Hadith, whose spelling varies)."""
+    return normalize_strict(text).replace("ة", "ه").replace("ى", "ي")
+
+
+def normalize_for_matching(text: Optional[str]) -> str:
+    """Aggressive normalisation used for window matching: keeps only Arabic letters and single spaces."""
+    if not text:
+        return ""
+    text = _MATCH_DIACRITICS.sub("", text)
+    for src, dst in (("أ", "ا"), ("إ", "ا"), ("آ", "ا"), ("ٱ", "ا"), ("ؤ", "و"), ("ئ", "ي"), ("ة", "ه"), ("ى", "ي")):
+        text = text.replace(src, dst)
+    text = re.sub(r"[^\u0600-\u06FF\s]", " ", text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def tokenize(text: str) -> List[str]:
+    return [token for token in text.split() if token]
+
+
+def content_words(tokens: Iterable[str]) -> List[str]:
+    """Drop stop-words and single-letter tokens."""
+    return [t for t in tokens if t not in STOPWORDS and len(t) > 1]
+
+
+def _char_ngrams(text: str, n: int = 4) -> set:
+    return {text[i : i + n] for i in range(len(text) - n + 1)}
+
+
+# --------------------------------------------------------------------------------------------------------------
+# Retriever
+# --------------------------------------------------------------------------------------------------------------
+class CorpusError(RuntimeError):
+    """Raised when a corpus file is missing or malformed."""
+
+
+class SourceRetriever:
+    """In-memory index over ``quran.json`` and ``hadith.json`` (builds in a few seconds)."""
+
+    def __init__(
+        self,
+        quran_path: os.PathLike = DEFAULT_QURAN_PATH,
+        hadith_path: os.PathLike = DEFAULT_HADITH_PATH,
+    ) -> None:
+        quran_path, hadith_path = Path(quran_path), Path(hadith_path)
+        gzipped = hadith_path.with_name(hadith_path.name + ".gz")
+        if not hadith_path.is_file() and gzipped.is_file():   # compressed copy used by the in-browser deployment
+            hadith_path = gzipped
+        for path in (quran_path, hadith_path):
+            if not path.is_file():
+                raise CorpusError(f"Corpus file not found: {path}")
+
+        self.__dict__.update(self._build(quran_path, hadith_path))
+
+        n_ayahs, n_hadith = len(self.quran), len(self.hadith)
+        self.quran_idf = {w: math.log((n_ayahs + 1) / (len(d) + 1)) + 1 for w, d in self.q_content_index.items()}
+        self.hadith_idf = {w: math.log((n_hadith + 1) / (len(d) + 1)) + 1 for w, d in self.h_content_index.items()}
+        logger.info("Retriever ready: %d ayahs, %d hadith records", n_ayahs, n_hadith)
+
+    # ---- construction ---------------------------------------------------------------------------------------
+    @staticmethod
+    def _read_json(path: Path) -> list:
+        try:
+            opener = gzip.open if path.suffix == ".gz" else open
+            with opener(path, "rt", encoding="utf-8") as handle:
+                data = json.load(handle)
+        except (OSError, json.JSONDecodeError) as exc:
+            raise CorpusError(f"Cannot read corpus file {path}: {exc}") from exc
+        if not isinstance(data, list):
+            raise CorpusError(f"Unexpected corpus format in {path}: expected a JSON list")
+        return data
+
+    def _build(self, quran_path: Path, hadith_path: Path) -> dict:
+        quran: List[dict] = []
+        q_norm_match: List[str] = []
+        q_all_index: Dict[str, List[int]] = defaultdict(list)
+        q_content_index: Dict[str, List[int]] = defaultdict(list)
+        q_word_count: List[int] = []
+        by_surah: Dict[int, Dict[int, int]] = defaultdict(dict)
+
+        for entry in self._read_json(quran_path):
+            text = (entry.get("ayah_text") or "").strip()
+            if not text:
+                continue
+            idx = len(quran)
+            quran.append(
+                {
+                    "surah_id": entry.get("surah_id"),
+                    "surah_name": entry.get("surah_name", ""),
+                    "ayah_id": entry.get("ayah_id"),
+                    "text": text,
+                }
+            )
+            by_surah[entry.get("surah_id")][entry.get("ayah_id")] = idx
+            q_norm_match.append(normalize_for_matching(text))
+            tokens = tokenize(normalize_strict(text))
+            q_word_count.append(len(tokens))
+            for word in set(tokens):
+                q_all_index[word].append(idx)
+            for word in set(content_words(q_norm_match[-1].split())):
+                q_content_index[word].append(idx)
+
+        hadith: List[dict] = []
+        h_content_index: Dict[str, List[int]] = defaultdict(list)
+        for entry in self._read_json(hadith_path):
+            if not entry:
+                continue
+            matn = (entry.get("Matn") or "").strip() or None
+            full = (entry.get("hadithTxt") or "").strip() or None
+            if not (matn or full):
+                continue
+            record = {
+                "hadithID": entry.get("hadithID"),
+                "book": entry.get("BookID"),
+                "title": entry.get("title"),
+                "matn": matn,
+                "full": full,
+                "norm_matn": normalize_for_matching(matn) if matn else None,
+                "norm_full": normalize_for_matching(full) if full else None,
+            }
+            idx = len(hadith)
+            hadith.append(record)
+            words = set()
+            for key in ("norm_matn", "norm_full"):
+                if record[key]:
+                    words |= set(content_words(record[key].split()))
+            for word in words:
+                h_content_index[word].append(idx)
+
+        return {
+            "quran": quran,
+            "quran_by_surah": dict(by_surah),
+            "q_norm_match": q_norm_match,
+            "q_all_index": dict(q_all_index),
+            "q_content_index": dict(q_content_index),
+            "q_word_count": q_word_count,
+            "hadith": hadith,
+            "h_content_index": dict(h_content_index),
+        }
+
+    # ---- Quran ----------------------------------------------------------------------------------------------
+    def search_quran_ayahs(self, query: str, top_k: int = 25, extra_seeds: int = 10) -> List[dict]:
+        """Single-ayah candidates ranked by the F1 of query coverage and ayah precision.
+
+        The F1 ranking favours short ayahs, so a fragment of a long ayah can be missed; the top IDF-voted ayahs
+        (rare-word matches) are appended as extra candidates to recover those partial quotations."""
+        query_words = tokenize(normalize_strict(query))
+        if not query_words:
+            return []
+        votes: Dict[int, int] = defaultdict(int)
+        for word in query_words:
+            for idx in self.q_all_index.get(word, ()):
+                votes[idx] += 1
+        scored: List[Tuple[int, float]] = []
+        for idx, vote in votes.items():
+            coverage = vote / len(query_words)
+            precision = vote / self.q_word_count[idx] if self.q_word_count[idx] else 0.0
+            f1 = 2 * coverage * precision / (coverage + precision) if coverage + precision > 0 else 0.0
+            scored.append((idx, f1))
+        scored.sort(key=lambda item: item[1], reverse=True)
+        ranked = [idx for idx, _ in scored[:top_k]]
+        scores = dict(scored)
+        seeds = self.quran_seed_ayahs(content_words(normalize_for_matching(query).split()), extra_seeds)
+        ranked += [idx for idx in seeds if idx not in set(ranked)]
+        results = []
+        for idx in ranked:
+            candidate = dict(self.quran[idx])
+            candidate.update(type="Quran", retrieval_score=scores.get(idx, 0.0))
+            results.append(candidate)
+        return results
+
+    def quran_seed_ayahs(self, query_words: Sequence[str], top_k: int = 25) -> List[int]:
+        """IDF-voted ayah indices used to seed the multi-ayah window search."""
+        return [idx for idx, _ in self.vote(self.q_content_index, self.quran_idf, query_words, top_k)]
+
+    # ---- Hadith ---------------------------------------------------------------------------------------------
+    def search_hadith(self, query: str, top_k: int = 15, pool: int = 40) -> List[dict]:
+        """IDF word-vote recall, then re-rank by character 4-gram cosine similarity."""
+        words = content_words(normalize_for_matching(query).split())
+        if not words:
+            return []
+        query_grams = _char_ngrams(normalize_lenient(query))
+        results = []
+        for idx, _ in self.vote(self.h_content_index, self.hadith_idf, words, pool):
+            record = self.hadith[idx]
+            text = record["matn"] or record["full"]
+            doc_grams = _char_ngrams(normalize_lenient(text))
+            cosine = (
+                len(query_grams & doc_grams) / ((len(query_grams) * len(doc_grams)) ** 0.5)
+                if query_grams and doc_grams
+                else 0.0
+            )
+            results.append(
+                {
+                    "type": "Hadith",
+                    "idx": idx,
+                    "hadithID": record["hadithID"],
+                    "book": record["book"],
+                    "title": record["title"],
+                    "text": text,
+                    "has_matn": bool(record["matn"]),
+                    "retrieval_score": cosine,
+                }
+            )
+        results.sort(key=lambda c: c["retrieval_score"], reverse=True)
+        return results[:top_k]
+
+    # ---- shared ---------------------------------------------------------------------------------------------
+    @staticmethod
+    def vote(index: Dict[str, List[int]], idf: Dict[str, float], words: Iterable[str], top_k: int) -> List[Tuple[int, float]]:
+        scores: Counter = Counter()
+        for word in set(words):
+            weight = idf.get(word, 0.0)
+            if weight <= 0:
+                continue
+            for doc in index.get(word, ()):
+                scores[doc] += weight
+        return scores.most_common(top_k)

verifier.py

@@ -0,0 +1,933 @@
+"""Quotation detection, evidence-based verification and source-backed correction for Quran and Hadith.
+
+This module consolidates the logic of the IslamicEval 2025 research notebook
+(``research/IslamicEval_Unified.ipynb``) into one pipeline:
+
+    input text -> detection (1A) -> source retrieval -> verification (1B) -> evidence
+               -> strong evidence  : source-backed correction (1C)
+               -> weak / ambiguous : human review
+               -> no source found  : reported as unsupported, never "fixed"
+
+Safety rule: a correction is only ever the exact text of a retrieved source. Nothing is generated.
+"""
+from __future__ import annotations
+
+import difflib
+import logging
+import re
+import time
+import unicodedata
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Sequence
+
+from retrieval import (
+    SourceRetriever,
+    content_words,
+    normalize_for_matching,
+    normalize_lenient,
+    normalize_strict,
+    tokenize,
+)
+
+try:  # optional accelerator; identical formula (1 - distance / max_len)
+    from rapidfuzz.distance import Levenshtein as _RapidLevenshtein
+except ImportError:  # pragma: no cover
+    _RapidLevenshtein = None
+
+logger = logging.getLogger(__name__)
+
+MAX_INPUT_CHARS = 20_000
+
+# --------------------------------------------------------------------------------------------------------------
+# Configuration (all tunable numbers live here)
+# --------------------------------------------------------------------------------------------------------------
+@dataclass
+class VerifierConfig:
+    """Thresholds calibrated in Subtask 1B of the research notebook."""
+
+    quran_correct_threshold: float = 0.94
+    quran_uncertain_low: float = 0.45
+    quran_min_coverage: float = 0.40
+    hadith_correct_threshold: float = 0.79
+    hadith_uncertain_low: float = 0.30
+    hadith_min_coverage: float = 0.70
+    quran_top_k: int = 25
+    hadith_top_k: int = 15
+    hadith_retrieval_guard: float = 0.20
+
+
+@dataclass
+class CorrectorConfig:
+    """Correction is proposed only when match strength >= ``*_strong``; between ``*_low`` and ``*_strong`` the
+    case goes to human review. Hadith is never auto-corrected (``hadith_strong`` > 1), by design: the exact
+    fragment boundaries of a Hadith quotation cannot be reproduced reliably."""
+
+    max_window: int = 8
+    hadith_top_k: int = 40
+    quran_strong: float = 0.65
+    min_full_ratio: float = 0.40
+    quran_low: float = 0.55
+    hadith_strong: float = 1.01
+    hadith_low: float = 0.45
+
+
+@dataclass
+class PipelineConfig:
+    verifier: VerifierConfig = field(default_factory=VerifierConfig)
+    corrector: CorrectorConfig = field(default_factory=CorrectorConfig)
+    min_detection_conf: float = 0.60       # detector confidence below this -> human review
+    verified_min_conf: float = 0.75        # "Correct" verdicts weaker than this -> human review
+    unsupported_min_conf: float = 0.70     # "Incorrect + no source" needs this confidence to abstain confidently
+    unsupported_strength: float = 0.35     # ...or the best source match is this weak (nothing similar exists)
+
+
+# --------------------------------------------------------------------------------------------------------------
+# Similarity signals (Subtask 1B)
+# --------------------------------------------------------------------------------------------------------------
+def _lcs_length(a: Sequence[str], b: Sequence[str]) -> int:
+    m, n = len(a), len(b)
+    if m == 0 or n == 0:
+        return 0
+    if m < n:
+        a, b, m, n = b, a, n, m
+    prev = [0] * (n + 1)
+    for i in range(m):
+        curr = [0] * (n + 1)
+        for j in range(n):
+            curr[j + 1] = prev[j] + 1 if a[i] == b[j] else max(curr[j], prev[j + 1])
+        prev = curr
+    return prev[n]
+
+
+def _edit_similarity(a: str, b: str, max_len: int = 600) -> float:
+    """Normalised Levenshtein similarity in [0, 1] on the first ``max_len`` characters."""
+    a, b = a[:max_len], b[:max_len]
+    if a == b:
+        return 1.0
+    if not a or not b:
+        return 0.0
+    if _RapidLevenshtein is not None:
+        return float(_RapidLevenshtein.normalized_similarity(a, b))
+    prev = list(range(len(b) + 1))
+    for i, ca in enumerate(a):
+        curr = [i + 1]
+        for j, cb in enumerate(b):
+            curr.append(min(curr[j] + 1, prev[j + 1] + 1, prev[j] + (ca != cb)))
+        prev = curr
+    return 1.0 - prev[-1] / max(len(a), len(b))
+
+
+def _light_normalize(text: str) -> str:
+    """Keeps diacritics (so diacritic changes lower the score) but drops punctuation and tatweel."""
+    text = unicodedata.normalize("NFC", text)
+    text = re.sub(r"[،؛؟!.,:;'\"()\[\]{}<>«»\-_/\\|@#$%^&*+=~`\u0640]", " ", text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def compute_signals(claim: str, candidate: str, content_type: str = "Ayah") -> Dict[str, float]:
+    """Word-, character- and sequence-level similarity indicators between a quotation and a candidate source."""
+    is_quran = content_type == "Ayah"
+    normalize = normalize_strict if is_quran else normalize_lenient
+    norm_claim, norm_cand = normalize(claim), normalize(candidate)
+
+    claim_set, cand_set = set(tokenize(norm_claim)), set(tokenize(norm_cand))
+    if claim_set and cand_set:
+        shared = claim_set & cand_set
+        token_overlap = len(shared) / len(claim_set | cand_set)
+        coverage = len(shared) / len(claim_set)
+    else:
+        token_overlap = coverage = 0.0
+
+    claim_tokens, cand_tokens = tokenize(norm_claim), tokenize(norm_cand)
+    lcs_ratio = _lcs_length(claim_tokens, cand_tokens) / len(claim_tokens) if claim_tokens else 0.0
+    edit_sim = _edit_similarity(norm_claim, norm_cand)
+
+    claim_chars, cand_chars = set(norm_claim.replace(" ", "")), set(norm_cand.replace(" ", ""))
+    char_overlap = len(claim_chars & cand_chars) / len(claim_chars | cand_chars) if (claim_chars or cand_chars) else 0.0
+
+    claim_flat, cand_flat = norm_claim.replace(" ", ""), norm_cand.replace(" ", "")
+    is_substring = int(bool(claim_flat) and bool(cand_flat) and (claim_flat in cand_flat or cand_flat in claim_flat))
+
+    diacritic_sim = (
+        _edit_similarity(_light_normalize(claim), _light_normalize(candidate), max_len=800) if is_quran else edit_sim
+    )
+    short = len(claim_tokens) < 4
+
+    if is_quran:
+        w = (
+            dict(coverage=0.35, diacritic_sim=0.30, lcs_ratio=0.15, token_overlap=0.10, char_overlap=0.05, edit_sim=0.05)
+            if short
+            else dict(coverage=0.25, diacritic_sim=0.30, lcs_ratio=0.20, token_overlap=0.10, char_overlap=0.05, edit_sim=0.10)
+        )
+        composite = (
+            w["coverage"] * coverage + w["diacritic_sim"] * diacritic_sim + w["lcs_ratio"] * lcs_ratio
+            + w["token_overlap"] * token_overlap + w["char_overlap"] * char_overlap + w["edit_sim"] * edit_sim
+        )
+        if is_substring and diacritic_sim >= 0.60:
+            composite = max(composite, 0.88)
+        elif is_substring:
+            composite = max(composite, 0.75)
+    else:
+        w = (
+            dict(coverage=0.40, lcs_ratio=0.20, token_overlap=0.20, char_overlap=0.10, edit_sim=0.10)
+            if short
+            else dict(coverage=0.30, lcs_ratio=0.28, token_overlap=0.18, char_overlap=0.12, edit_sim=0.12)
+        )
+        composite = (
+            w["coverage"] * coverage + w["lcs_ratio"] * lcs_ratio + w["token_overlap"] * token_overlap
+            + w["char_overlap"] * char_overlap + w["edit_sim"] * edit_sim
+        )
+        if is_substring:
+            composite = max(composite, 0.82)
+
+    return {
+        "token_overlap": round(token_overlap, 4),
+        "coverage": round(coverage, 4),
+        "lcs_ratio": round(lcs_ratio, 4),
+        "edit_sim": round(edit_sim, 4),
+        "diacritic_sim": round(diacritic_sim, 4),
+        "char_overlap": round(char_overlap, 4),
+        "is_substring": is_substring,
+        "composite": round(composite, 4),
+    }
+
+
+def best_match_score(claim: str, candidates: List[dict], content_type: str = "Ayah"):
+    """Return ``(score, candidate_with_signals)`` for the best-scoring candidate."""
+    best_score, best_candidate = 0.0, None
+    for candidate in candidates:
+        signals = compute_signals(claim, candidate.get("text", ""), content_type)
+        if signals["composite"] > best_score:
+            best_score, best_candidate = signals["composite"], {**candidate, "signals": signals}
+    return best_score, best_candidate
+
+
+# --------------------------------------------------------------------------------------------------------------
+# Detection (Subtask 1A)
+# --------------------------------------------------------------------------------------------------------------
+@dataclass
+class DetectedSpan:
+    start: int
+    end: int                        # exclusive
+    label: str                      # 'Ayah' | 'Hadith'
+    confidence: Optional[float]     # None for the rule backend
+    source: str                     # 'bert' | 'rules' | 'given'
+    text: str = ""
+
+
+QUOTE_CHARS = " \t\r\n\"“”«»﴿﴾{}()[]"
+
+
+def trim_span(text: str, start: int, end: int):
+    """Drop whitespace and quotation marks at both edges (gold spans exclude the quote marks)."""
+    while start < end and text[start] in QUOTE_CHARS:
+        start += 1
+    while end > start and text[end - 1] in QUOTE_CHARS + ".،,؛:":
+        end -= 1
+    return start, end
+
+
+AYAH_TRIGGERS = [
+    "قال الله", "قوله تعالى", "قال تعالى", "يقول الله", "يقول تعالى", "قال سبحانه", "قوله سبحانه", "في كتابه",
+    "سورة", "الآية", "الاية", "الآيات", "القرآن", "القران", "كتاب الله", "عز وجل", "جل جلاله", "فقال تعالى",
+    "ذكر الله", "﴿",
+]
+HADITH_TRIGGERS = [
+    "رسول الله", "النبي", "صلى الله عليه وسلم", "ﷺ", "عليه الصلاة والسلام", "حديث", "رواه", "روى", "متفق عليه",
+    "الحديث", "فقال", "قال ص", "صلى الله عليه", "وسلم",
+]
+_FORMULA_WORDS = {
+    normalize_for_matching(w)
+    for w in "قال قالت رسول الله صلى عليه وسلم النبي تعالى سبحانه عز وجل فقال يقول الكريم الشريف الحديث الآية روى رواه عن أن أنه البخاري ومسلم".split()
+}
+_BRACKET_PAIRS = [("“", "”"), ("«", "»"), ("﴿", "﴾"), ("{", "}"), ("(", ")"), ("[", "]")]
+
+
+class RuleDetector:
+    """Quotation-mark and trigger-phrase detector with an optional corpus lookup (no training, no GPU)."""
+
+    def __init__(self, retriever: Optional[SourceRetriever] = None, min_words: int = 3, context_chars: int = 110,
+                 min_corpus_cov: float = 0.6) -> None:
+        self.kb, self.min_words, self.context_chars, self.min_corpus_cov = retriever, min_words, context_chars, min_corpus_cov
+
+    @staticmethod
+    def _segments(text: str):
+        segments = []
+        quote_positions = [m.start() for m in re.finditer('"', text)]
+        if len(quote_positions) % 2 == 0:
+            pairs = zip(quote_positions[0::2], quote_positions[1::2])   # opening/closing pairs
+        else:   # a stray quote: fall back to every consecutive pair
+            pairs = zip(quote_positions, quote_positions[1:])
+        for a, b in pairs:
+            segments.append((a + 1, b))
+        for opener, closer in _BRACKET_PAIRS:
+            for m in re.finditer(re.escape(opener) + r"(.*?)" + re.escape(closer), text, re.S):
+                segments.append((m.start(1), m.end(1)))
+        return segments
+
+    @staticmethod
+    def _trigger_type(context: str) -> Optional[str]:
+        best_end, best_label = -1, None
+        for label, triggers in (("Ayah", AYAH_TRIGGERS), ("Hadith", HADITH_TRIGGERS)):
+            for trigger in triggers:
+                pos = context.rfind(trigger)
+                if pos >= 0 and pos + len(trigger) > best_end:
+                    best_end, best_label = pos + len(trigger), label
+        return best_label
+
+    def _corpus_coverage(self, span: str):
+        """Highest word coverage of the span by any top Quran ayah / Hadith candidate."""
+        if self.kb is None:
+            return 0.0, 0.0
+        quran_words = set(tokenize(normalize_strict(span)))
+        if not quran_words:
+            return 0.0, 0.0
+        quran_cov = max(
+            (len(quran_words & set(tokenize(normalize_strict(c["text"])))) / len(quran_words)
+             for c in self.kb.search_quran_ayahs(span, top_k=5)),
+            default=0.0,
+        )
+        hadith_words = set(tokenize(normalize_lenient(span)))
+        hadith_cov = max(
+            (len(hadith_words & set(tokenize(normalize_lenient(c["text"])))) / len(hadith_words)
+             for c in self.kb.search_hadith(span, top_k=5)),
+            default=0.0,
+        ) if hadith_words else 0.0
+        return quran_cov, hadith_cov
+
+    def detect(self, text: str) -> List[DetectedSpan]:
+        candidates = []
+        for start, end in self._segments(text):
+            start, end = trim_span(text, start, end)
+            if end <= start:
+                continue
+            inner = text[start:end]
+            words = [w for w in normalize_for_matching(inner).split() if w]
+            if len(words) < self.min_words or len(inner) > 3000:
+                continue
+            if sum(w in _FORMULA_WORDS for w in words) / len(words) >= 0.6:
+                continue
+            trigger = self._trigger_type(text[max(0, start - self.context_chars):start])
+            quran_cov, hadith_cov = self._corpus_coverage(inner)
+            label = None
+            if trigger:
+                label = trigger
+                other, mine = (hadith_cov, quran_cov) if trigger == "Ayah" else (quran_cov, hadith_cov)
+                if other >= 0.8 and mine < 0.5:
+                    label = "Hadith" if trigger == "Ayah" else "Ayah"
+            elif max(quran_cov, hadith_cov) >= self.min_corpus_cov and len(words) >= 4:
+                label = "Ayah" if quran_cov >= hadith_cov else "Hadith"
+            if label is None:
+                continue
+            candidates.append((bool(trigger), max(quran_cov, hadith_cov), end - start, start, end, label))
+
+        candidates.sort(key=lambda c: (c[0], c[1], c[2]), reverse=True)   # trigger first, then corpus match, then length
+        taken = []
+        for _, _, _, start, end, label in candidates:
+            if all(end <= t_start or start >= t_end for t_start, t_end, _ in taken):
+                taken.append((start, end, label))
+        taken.sort()
+        return [DetectedSpan(s, e, label, None, "rules", text[s:e]) for s, e, label in taken]
+
+
+LABEL2ID = {"O": 0, "B-Ayah": 1, "I-Ayah": 2, "B-Hadith": 3, "I-Hadith": 4}
+ID2LABEL = {v: k for k, v in LABEL2ID.items()}
+
+
+def _token_labels_to_char_spans(offsets, token_labels):
+    spans, current = [], None
+    for (start, end), label_id in zip(offsets, token_labels):
+        if label_id == -100:
+            continue
+        name = ID2LABEL[label_id]
+        if name == "O":
+            if current is not None:
+                spans.append(current)
+                current = None
+            continue
+        prefix, entity = name.split("-")
+        if prefix == "B" or current is None or current["label"] != entity:
+            if current is not None:
+                spans.append(current)
+            current = {"label": entity, "start": start, "end": end}
+        else:
+            current["end"] = end
+    if current is not None:
+        spans.append(current)
+    return spans
+
+
+def _merge_adjacent_spans(spans, max_gap: int = 1):
+    if not spans:
+        return []
+    spans = sorted(spans, key=lambda s: s["start"])
+    merged = [dict(spans[0])]
+    for span in spans[1:]:
+        last = merged[-1]
+        if span["label"] == last["label"] and 0 <= span["start"] - last["end"] <= max_gap:
+            last["end"] = max(last["end"], span["end"])
+        else:
+            merged.append(dict(span))
+    return merged
+
+
+class BertDetector:
+    """Fine-tuned token classifier (BIO tags, sliding window). Requires ``torch`` and ``transformers`` plus a
+    trained model directory; training code lives in the research notebook."""
+
+    def __init__(self, model_dir: str, device: Optional[str] = None, max_length: int = 512, stride: int = 256) -> None:
+        import torch
+        from transformers import AutoModelForTokenClassification, AutoTokenizer
+
+        self.torch = torch
+        self.device = torch.device(device or ("cuda" if torch.cuda.is_available() else "cpu"))
+        self.tokenizer = AutoTokenizer.from_pretrained(model_dir)
+        self.model = AutoModelForTokenClassification.from_pretrained(model_dir).to(self.device).eval()
+        self.max_length, self.stride = max_length, stride
+
+    def detect(self, text: str) -> List[DetectedSpan]:
+        torch = self.torch
+        if not text.strip():
+            return []
+        encoded = self.tokenizer(text, return_offsets_mapping=True, truncation=False, return_tensors="pt")
+        ids = encoded["input_ids"][0]
+        offsets = encoded["offset_mapping"][0].tolist()
+        total, n_labels = len(ids), len(LABEL2ID)
+        logits_sum, counts = torch.zeros(total, n_labels), torch.zeros(total)
+        start = 0
+        with torch.no_grad():
+            while start < total:
+                end = min(start + self.max_length, total)
+                window = ids[start:end].unsqueeze(0).to(self.device)
+                logits = self.model(input_ids=window, attention_mask=torch.ones_like(window)).logits[0].cpu()
+                logits_sum[start:end] += logits
+                counts[start:end] += 1
+                if end == total:
+                    break
+                start += self.stride
+        logits_sum /= counts.unsqueeze(1).clamp(min=1)
+        probs = torch.softmax(logits_sum, dim=-1)
+        predictions = torch.argmax(logits_sum, dim=-1).tolist()
+        predictions = [(-100 if a == b else p) for p, (a, b) in zip(predictions, offsets)]   # skip special tokens
+        spans = _merge_adjacent_spans(_token_labels_to_char_spans(offsets, predictions), max_gap=1)
+
+        detected = []
+        for span in spans:
+            start_c, end_c = trim_span(text, span["start"], span["end"])
+            if end_c <= start_c:
+                continue
+            token_idx = [i for i, (x, y) in enumerate(offsets) if y > x and x >= span["start"] and y <= span["end"]]
+            label = "Ayah" if span["label"] == "Ayah" else "Hadith"
+            tag_ids = [LABEL2ID[f"B-{label}"], LABEL2ID[f"I-{label}"]]
+            confidence = float(sum(probs[i, tag_ids].sum() for i in token_idx) / len(token_idx)) if token_idx else None
+            detected.append(DetectedSpan(start_c, end_c, label, confidence, "bert", text[start_c:end_c]))
+        return detected
+
+
+def build_detector(kind: str = "rules", retriever: Optional[SourceRetriever] = None, model_dir: Optional[str] = None,
+                   rules_use_corpus: bool = False):
+    """``kind``: 'rules' | 'bert' | 'auto' (BERT if a model directory loads, otherwise rules)."""
+    if kind == "rules":
+        return RuleDetector(retriever if rules_use_corpus else None)
+    if kind == "bert":
+        return BertDetector(model_dir)
+    if model_dir:
+        try:
+            return BertDetector(model_dir)
+        except Exception as exc:
+            logger.warning("Could not load BERT detector from %s (%s); using rule-based detector", model_dir, exc)
+    return RuleDetector(retriever if rules_use_corpus else None)
+
+
+# --------------------------------------------------------------------------------------------------------------
+# Verification (Subtask 1B)
+# --------------------------------------------------------------------------------------------------------------
+@dataclass
+class Verification:
+    verdict: str                         # 'Correct' | 'Incorrect'
+    confidence: float
+    best_score: float
+    method: str
+    source: Optional[dict] = None        # best matching source record (with 'signals')
+    n_candidates: int = 0
+    retrieval_top: float = 0.0
+
+
+class Verifier:
+    """Compares a quotation with retrieved candidates and returns a verdict with its supporting evidence."""
+
+    def __init__(self, retriever: SourceRetriever, config: Optional[VerifierConfig] = None) -> None:
+        self.kb = retriever
+        self.cfg = config or VerifierConfig()
+
+    def verify(self, span_text: str, content_type: str) -> Verification:
+        if not span_text or not span_text.strip():
+            return self._result("Incorrect", 0.95, 0.0, None, 0, "empty_span")
+        if content_type == "Ayah":
+            return self._verify_quran(span_text)
+        if content_type == "Hadith":
+            return self._verify_hadith(span_text)
+        return self._result("Incorrect", 0.5, 0.0, None, 0, "unknown_type")
+
+    def _verify_quran(self, span: str) -> Verification:
+        cfg = self.cfg
+        candidates = self.kb.search_quran_ayahs(span, top_k=cfg.quran_top_k)
+        if not candidates:
+            return self._result("Incorrect", 0.8, 0.0, None, 0, "no_candidates")
+        score, best = best_match_score(span, candidates, "Ayah")
+        signals = best.get("signals", {}) if best else {}
+        coverage, is_substring = signals.get("coverage", 0.0), signals.get("is_substring", 0)
+        n = len(candidates)
+
+        if is_substring and coverage >= cfg.quran_min_coverage:
+            return self._result("Correct", min(0.98, 0.85 + score * 0.15), score, best, n, "substring_match")
+        if score >= cfg.quran_correct_threshold and coverage >= cfg.quran_min_coverage:
+            return self._result("Correct", min(0.95, 0.70 + score * 0.25), score, best, n, "threshold_pass")
+        if score <= cfg.quran_uncertain_low:
+            return self._result("Incorrect", min(0.95, 0.70 + (1 - score) * 0.25), score, best, n, "threshold_fail")
+
+        strong = sum(
+            1 for cand in candidates[:10]
+            if (s := compute_signals(span, cand.get("text", ""), "Ayah"))["coverage"] >= 0.80 and s["lcs_ratio"] >= 0.75
+        )
+        if strong >= 2:
+            return self._result("Correct", 0.60 + min(0.20, strong * 0.05), score, best, n, "borderline_multi_cov")
+        return self._result("Incorrect", 0.58, score, best, n, "borderline_default")
+
+    def _verify_hadith(self, span: str) -> Verification:
+        cfg = self.cfg
+        candidates = self.kb.search_hadith(span, top_k=cfg.hadith_top_k)
+        if not candidates:
+            return self._result("Incorrect", 0.75, 0.0, None, 0, "no_candidates")
+        top_retrieval = candidates[0].get("retrieval_score", 0.0)
+        score, best = best_match_score(span, candidates, "Hadith")
+        signals = best.get("signals", {}) if best else {}
+        coverage, is_substring = signals.get("coverage", 0.0), signals.get("is_substring", 0)
+        n = len(candidates)
+
+        if is_substring and coverage >= cfg.hadith_min_coverage and top_retrieval >= cfg.hadith_retrieval_guard:
+            return self._result("Correct", min(0.97, 0.80 + score * 0.17), score, best, n, "substring_match", top_retrieval)
+        if score >= cfg.hadith_correct_threshold and coverage >= cfg.hadith_min_coverage:
+            return self._result("Correct", min(0.92, 0.65 + score * 0.27), score, best, n, "threshold_pass", top_retrieval)
+        if score <= cfg.hadith_uncertain_low:
+            return self._result("Incorrect", min(0.90, 0.65 + (1 - score) * 0.25), score, best, n, "threshold_fail", top_retrieval)
+
+        moderate = sum(
+            1 for cand in candidates[:8]
+            if (s := compute_signals(span, cand.get("text", ""), "Hadith"))["coverage"] >= 0.65 and s["lcs_ratio"] >= 0.55
+        )
+        if moderate >= 2 and top_retrieval >= 0.30:
+            return self._result("Correct", 0.58 + min(0.22, moderate * 0.06), score, best, n, "borderline_multi_cov", top_retrieval)
+        if top_retrieval < 0.25 or score < 0.45:
+            return self._result("Incorrect", 0.60, score, best, n, "borderline_low_retrieval", top_retrieval)
+        return self._result("Incorrect", 0.55, score, best, n, "borderline_default", top_retrieval)
+
+    @staticmethod
+    def _result(verdict, confidence, score, best, n_candidates, method, top_retrieval=0.0) -> Verification:
+        return Verification(verdict, round(confidence, 4), round(score, 4), method, best, n_candidates, round(top_retrieval, 4))
+
+
+_MARKER = re.compile(r"^\(\d+\)$")
+
+
+def compare(span_text: str, source_text: str) -> dict:
+    """Word-level comparison between the quotation and the source (the 'evidence' view)."""
+    span_words = span_text.split()
+    source_words = [w for w in source_text.split() if not _MARKER.match(w)]
+    span_norm = [normalize_for_matching(w) for w in span_words]
+    source_norm = [normalize_for_matching(w) for w in source_words]
+    matcher = difflib.SequenceMatcher(None, span_norm, source_norm, autojunk=False)
+    blocks = [b for b in matcher.get_matching_blocks() if b.size > 0]
+    if blocks and len(source_words) > 2 * len(span_words) + 10:   # long source (e.g. Hadith with chain): keep matched region
+        lo, hi = max(0, blocks[0].b - 3), min(len(source_words), blocks[-1].b + blocks[-1].size + 3)
+        source_words, source_norm = source_words[lo:hi], source_norm[lo:hi]
+        matcher = difflib.SequenceMatcher(None, span_norm, source_norm, autojunk=False)
+    operations, missing, extra = [], [], []
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        operations.append({"op": tag, "span": " ".join(span_words[i1:i2]), "source": " ".join(source_words[j1:j2])})
+        if tag in ("delete", "replace"):
+            extra += span_words[i1:i2]
+        if tag in ("insert", "replace"):
+            missing += source_words[j1:j2]
+    return {
+        "word_similarity": round(matcher.ratio(), 3),
+        "word_diff": operations,
+        "missing_from_span": missing,
+        "extra_in_span": extra,
+        "source_excerpt": " ".join(source_words),
+    }
+
+
+# --------------------------------------------------------------------------------------------------------------
+# Idgham rendering (published mushaf convention used by the Subtask 1C gold corrections)
+# --------------------------------------------------------------------------------------------------------------
+_SUKUN, _SHADDA, _FATHATAN = "\u0652", "\u0651", "\u064B"
+_TANWEEN = set("\u064B\u064C\u064D")
+_IDGHAM_AFTER_NOON = set("نمرل")
+_IDGHAM_AFTER_LAM = set("لر")
+_DIACRITIC_CHARS = set(
+    "\u0610\u0611\u0612\u0613\u0614\u0615\u0616\u0617\u0618\u0619\u061A"
+    "\u064B\u064C\u064D\u064E\u064F\u0650\u0651\u0652\u0670"
+    "\u06D6\u06D7\u06D8\u06D9\u06DA\u06DB\u06DC\u06DF\u06E0\u06E1\u06E2\u06E3\u06E4"
+    "\u06E7\u06E8\u06EA\u06EB\u06EC\u06ED"
+)
+
+
+def _base_letters(word: str) -> str:
+    return "".join(c for c in word if c not in _DIACRITIC_CHARS)
+
+
+def _insert_shadda(word: str) -> str:
+    return word if not word else word[0] + _SHADDA + word[1:]
+
+
+def _ends_with_tanween(word: str) -> bool:
+    if not word:
+        return False
+    if word[-1] in _TANWEEN:
+        return True
+    return len(word) >= 2 and word[-1] in "اى" and word[-2] == _FATHATAN
+
+
+def apply_idgham(text: str, extended: bool = True) -> str:
+    """Convert the flat Quran text into the mushaf rendering that marks assimilation with a shadda.
+
+    Covers noon sakinah / tanween before ن م ر ل, meem sakinah before م and lam sakinah before ل ر, also across
+    ayah-number markers such as ``(20)``. The و / ي cases are excluded on purpose because the mushaf convention
+    is inconsistent there."""
+    words = text.split(" ")
+    noon_set = _IDGHAM_AFTER_NOON if extended else set("نم")
+    i = 0
+    while i < len(words):
+        word = words[i]
+        if _MARKER.match(word) or not word:
+            i += 1
+            continue
+        j = i + 1
+        while j < len(words) and _MARKER.match(words[j]):
+            j += 1
+        if j < len(words):
+            base = _base_letters(words[j])
+            first = base[0] if base else ""
+            if word.endswith("\u0646" + _SUKUN) and first in noon_set:
+                words[i], words[j] = word[:-1], _insert_shadda(words[j])
+            elif _ends_with_tanween(word) and first in noon_set:
+                words[j] = _insert_shadda(words[j])
+            elif word.endswith("\u0645" + _SUKUN) and first == "\u0645":
+                words[i], words[j] = word[:-1], _insert_shadda(words[j])
+            elif extended and word.endswith("\u0644" + _SUKUN) and first in _IDGHAM_AFTER_LAM:
+                words[i], words[j] = word[:-1], _insert_shadda(words[j])
+        i += 1
+    return " ".join(words)
+
+
+# --------------------------------------------------------------------------------------------------------------
+# Correction (Subtask 1C): locate the true ayah window / Hadith record and return its exact text
+# --------------------------------------------------------------------------------------------------------------
+@dataclass
+class CorrectionMatch:
+    kind: str                  # 'Ayah' | 'Hadith'
+    strength: float            # coverage (Quran) / symmetric containment (Hadith)
+    full_ratio: float
+    text: str                  # proposed correction in the official 1C format (idgham + '(n)' ayah markers)
+    source: dict               # reference metadata
+    display: str = ""          # clean human-readable version
+
+
+class Corrector:
+    def __init__(self, retriever: SourceRetriever, config: Optional[CorrectorConfig] = None) -> None:
+        self.kb = retriever
+        self.cfg = config or CorrectorConfig()
+
+    def match(self, span_text: str, content_type: str) -> Optional[CorrectionMatch]:
+        return self.match_quran(span_text) if content_type == "Ayah" else self.match_hadith(span_text)
+
+    def match_quran(self, query_text: str) -> Optional[CorrectionMatch]:
+        kb = self.kb
+        query_norm = normalize_for_matching(query_text)
+        query_words = content_words(query_norm.split())
+        if not query_words:
+            return None
+        query_len = len(query_norm)
+        memo: Dict[tuple, tuple] = {}
+        best = None   # (key, coverage, ratio, surah, start, end)
+        for seed in kb.quran_seed_ayahs(query_words, top_k=25):
+            surah, ayah = kb.quran[seed]["surah_id"], kb.quran[seed]["ayah_id"]
+            ayahs = kb.quran_by_surah[surah]
+            min_ayah, max_ayah = min(ayahs), max(ayahs)
+            for offset in range(3):
+                start = ayah - offset
+                if start < min_ayah:
+                    continue
+                window_len = -1
+                for length in range(1, self.cfg.max_window + 1):
+                    end = start + length - 1
+                    if end > max_ayah:
+                        break
+                    window_len += len(kb.q_norm_match[ayahs[end]]) + 1
+                    len_diff = abs(window_len - query_len)
+                    upper_bound = min(1.0, window_len / max(query_len, 1))
+                    if best is not None:   # exact-result pruning
+                        best_cov, best_neg = best[0][0], best[0][1]
+                        if upper_bound < best_cov or (upper_bound == best_cov and -len_diff < best_neg):
+                            continue
+                    key_pos = (surah, start, end)
+                    if key_pos in memo:
+                        continue
+                    window = " ".join(kb.q_norm_match[ayahs[a]] for a in range(start, end + 1))
+                    matcher = difflib.SequenceMatcher(None, query_norm, window, autojunk=False)
+                    matched = sum(b.size for b in matcher.get_matching_blocks() if b.size >= 4)
+                    coverage = matched / max(query_len, 1)
+                    key = (coverage, -len_diff, matcher.ratio())
+                    memo[key_pos] = key
+                    if best is None or key > best[0]:
+                        best = (key, coverage, key[2], surah, start, end)
+        if best is None:
+            return None
+        _, coverage, ratio, surah, start, end = best
+        display = " ".join(kb.quran[kb.quran_by_surah[surah][a]]["text"] for a in range(start, end + 1))
+        return CorrectionMatch(
+            "Ayah", coverage, ratio, self._ayah_text(surah, start, end),
+            {"type": "Quran", "surah_id": surah, "surah_name": kb.quran[kb.quran_by_surah[surah][start]]["surah_name"],
+             "ayah_start": start, "ayah_end": end},
+            display,
+        )
+
+    def _ayah_text(self, surah: int, start: int, end: int) -> str:
+        kb, multi = self.kb, end > start
+        parts = []
+        for a in range(start, end + 1):
+            text = kb.quran[kb.quran_by_surah[surah][a]]["text"]
+            parts.append(f"{text} ({a})" if multi else text)
+        return apply_idgham(" ".join(parts)).replace("\u0640", "")
+
+    def match_hadith(self, query_text: str) -> Optional[CorrectionMatch]:
+        kb = self.kb
+        query_norm = normalize_for_matching(query_text)
+        query_words = content_words(query_norm.split())
+        if not query_words:
+            return None
+        query_len = len(query_norm)
+        best = None   # (key, idx, field, coverage, candidate_coverage, ratio)
+        for idx, _ in kb.vote(kb.h_content_index, kb.hadith_idf, query_words, self.cfg.hadith_top_k):
+            record = kb.hadith[idx]
+            for field_name in ("norm_matn", "norm_full"):
+                text = record[field_name]
+                if not text:
+                    continue
+                upper_bound = min(1.0, query_len / max(len(text), 1))
+                if best is not None and upper_bound < best[0][0]:
+                    continue
+                matcher = difflib.SequenceMatcher(None, query_norm, text, autojunk=False)
+                matched = sum(b.size for b in matcher.get_matching_blocks() if b.size >= 4)
+                coverage, candidate_cov = matched / max(query_len, 1), matched / max(len(text), 1)
+                key = (min(coverage, candidate_cov), matcher.ratio())
+                if best is None or key > best[0]:
+                    best = (key, idx, field_name, coverage, candidate_cov, key[1])
+        if best is None:
+            return None
+        key, idx, field_name, _, _, ratio = best
+        record = kb.hadith[idx]
+        text = (record["matn"] if field_name == "norm_matn" else record["full"]).strip()
+        return CorrectionMatch(
+            "Hadith", key[0], ratio, text,
+            {"type": "Hadith", "hadithID": record["hadithID"], "book": record["book"], "title": record["title"],
+             "field": "matn" if field_name == "norm_matn" else "full_text"},
+            text,
+        )
+
+    def is_exact_ayah(self, span_text: str) -> bool:
+        """True if the quote (diacritics-insensitive) is a contiguous piece of 1-5 consecutive ayahs."""
+        kb, query_norm = self.kb, normalize_for_matching(span_text)
+        if not query_norm:
+            return False
+        for seed in kb.quran_seed_ayahs(content_words(query_norm.split()), 25):
+            ayah = kb.quran[seed]
+            ayahs = kb.quran_by_surah[ayah["surah_id"]]
+            for offset in range(4):
+                start = ayah["ayah_id"] - offset
+                for length in range(1, 6):
+                    ids = [ayahs.get(x) for x in range(start, start + length)]
+                    if None in ids:
+                        break
+                    if query_norm in " ".join(kb.q_norm_match[i] for i in ids):
+                        return True
+        return False
+
+
+# --------------------------------------------------------------------------------------------------------------
+# End-to-end pipeline
+# --------------------------------------------------------------------------------------------------------------
+STATUS_INFO = {
+    "VERIFIED": {"ar": "موثّق — النص مطابق للمصدر", "en": "Verified — matches the source", "group": "verified"},
+    "CORRECTED": {"ar": "مُصحَّح — دليل قوي على نص المصدر", "en": "Mismatch — source-backed correction available", "group": "mismatch"},
+    "UNSUPPORTED": {"ar": "غير مدعوم — لا يوجد مصدر مطابق في المراجع", "en": "Mismatch — no matching source in the corpus", "group": "mismatch"},
+    "HUMAN_REVIEW": {"ar": "مراجعة بشرية — الدليل غير كافٍ", "en": "Needs human review — insufficient evidence", "group": "review"},
+}
+
+
+class IslamicContentVerifier:
+    """Detect quotations, verify them against the corpora and decide: verified, corrected, unsupported or review."""
+
+    def __init__(self, retriever: Optional[SourceRetriever] = None, detector: str = "rules",
+                 model_dir: Optional[str] = None, config: Optional[PipelineConfig] = None) -> None:
+        self.cfg = config or PipelineConfig()
+        self.retriever = retriever or SourceRetriever()
+        self.verifier = Verifier(self.retriever, self.cfg.verifier)
+        self.corrector = Corrector(self.retriever, self.cfg.corrector)
+        self.detector = build_detector(detector, self.retriever, model_dir)
+        self.detector_name = type(self.detector).__name__
+
+    # ---- public API -----------------------------------------------------------------------------------------
+    def analyze(self, text: str) -> dict:
+        """Run the full pipeline on a generated text."""
+        text = self._validate(text)
+        started = time.time()
+        spans = self.detector.detect(text) if text.strip() else []
+        detect_seconds = time.time() - started
+        result = self._analyze_spans(text, spans)
+        result["timings"] = {"detect_s": round(detect_seconds, 3), "total_s": round(time.time() - started, 3)}
+        return result
+
+    def analyze_spans(self, text: str, spans: List[dict]) -> dict:
+        """Skip detection and use given spans ``[{label, start, end}]`` (evaluation / oracle mode)."""
+        given = [DetectedSpan(s["start"], s["end"], s["label"], None, "given", text[s["start"]:s["end"]]) for s in spans]
+        return self._analyze_spans(self._validate(text), given)
+
+    # ---- internals ------------------------------------------------------------------------------------------
+    @staticmethod
+    def _validate(text: str) -> str:
+        if not isinstance(text, str):
+            raise TypeError("Input text must be a string")
+        if len(text) > MAX_INPUT_CHARS:
+            raise ValueError(f"Input is too long ({len(text)} characters); the limit is {MAX_INPUT_CHARS}")
+        return text
+
+    def _analyze_spans(self, text: str, spans: List[DetectedSpan]) -> dict:
+        reports = [self._process_span(i + 1, span) for i, span in enumerate(sorted(spans, key=lambda s: s.start))]
+        counts = {status: 0 for status in STATUS_INFO}
+        for report in reports:
+            counts[report["status"]] += 1
+        return {
+            "input_text": text,
+            "detector": self.detector_name,
+            "spans": reports,
+            "corrected_text": self._apply_corrections(text, reports),
+            "summary": {
+                "n_spans": len(reports),
+                "n_ayah": sum(r["type"] == "Ayah" for r in reports),
+                "n_hadith": sum(r["type"] == "Hadith" for r in reports),
+                **counts,
+                "needs_human_review": counts["HUMAN_REVIEW"] > 0,
+            },
+        }
+
+    def _process_span(self, index: int, span: DetectedSpan) -> dict:
+        try:
+            return self._decide(index, span)
+        except Exception:   # a single failing quotation must not break the whole report
+            logger.exception("Failed to process span %d", index)
+            report = self._empty_report(index, span)
+            self._finalize(report, "HUMAN_REVIEW", "internal_error: this quotation could not be processed automatically")
+            return report
+
+    @staticmethod
+    def _empty_report(index: int, span: DetectedSpan) -> dict:
+        return {
+            "id": index, "type": span.label, "start": span.start, "end": span.end, "text": span.text,
+            "detection": {"backend": span.source, "confidence": None if span.confidence is None else round(span.confidence, 4)},
+            "verification": {"verdict": "Incorrect", "confidence": 0.0, "score": 0.0, "method": "error", "n_candidates": 0},
+            "evidence": None, "correction": None, "suggestion": None,
+        }
+
+    @staticmethod
+    def _finalize(report: dict, status: str, reason: str) -> None:
+        info = STATUS_INFO[status]
+        report.update(status=status, status_ar=info["ar"], status_en=info["en"], group=info["group"], reason=reason)
+
+    def _decide(self, index: int, span: DetectedSpan) -> dict:
+        cfg, corr_cfg = self.cfg, self.cfg.corrector
+        verification = self.verifier.verify(span.text, span.label)
+        report = self._empty_report(index, span)
+        report["verification"] = {
+            "verdict": verification.verdict, "confidence": verification.confidence, "score": verification.best_score,
+            "method": verification.method, "n_candidates": verification.n_candidates,
+        }
+        report["evidence"] = self._evidence(span, verification)
+
+        def proposal(match: Optional[CorrectionMatch]) -> Optional[dict]:
+            if match is None:
+                return None
+            return {
+                "text": match.text, "display_text": match.display, "source": match.source,
+                "match_strength": round(match.strength, 4), "full_ratio": round(match.full_ratio, 4),
+                "comparison": compare(span.text, match.display),
+            }
+
+        if verification.verdict == "Correct":
+            exact = self.corrector.is_exact_ayah(span.text) if span.label == "Ayah" else None
+            report["verification"]["exact_match"] = exact
+            if verification.method.startswith("borderline") or verification.confidence < cfg.verified_min_conf:
+                status, reason = "HUMAN_REVIEW", "weak_verification: matched a source but with low confidence"
+            elif exact is False:
+                status = "HUMAN_REVIEW"
+                reason = "near_match: the quote is close to a source ayah but NOT identical (words missing, added or changed)"
+                report["suggestion"] = proposal(self.corrector.match(span.text, span.label))
+            else:
+                status, reason = "VERIFIED", f"matched source ({verification.method})"
+        else:
+            match = self.corrector.match(span.text, span.label)
+            strong, low = (corr_cfg.quran_strong, corr_cfg.quran_low) if span.label == "Ayah" else (corr_cfg.hadith_strong, corr_cfg.hadith_low)
+            candidate = proposal(match)
+            if match is None or match.strength < low:
+                confident_abstain = verification.confidence >= cfg.unsupported_min_conf and not verification.method.startswith("borderline")
+                if match is None or match.strength < cfg.unsupported_strength or confident_abstain:
+                    status, reason = "UNSUPPORTED", "no source in the corpus matches this quotation"
+                else:
+                    status, reason = "HUMAN_REVIEW", "insufficient_evidence: no clear source and low verification confidence"
+                    report["suggestion"] = candidate
+            elif match.strength >= strong and match.full_ratio >= corr_cfg.min_full_ratio:
+                status = "CORRECTED"
+                reason = f"strong match to {self.describe_source(match.source)} (strength {match.strength:.2f})"
+                report["correction"] = {**candidate, "applied": True}
+            else:
+                status = "HUMAN_REVIEW"
+                reason = (f"candidate source found ({self.describe_source(match.source)}, strength {match.strength:.2f}) "
+                          "but evidence is not strong enough for automatic correction")
+                report["suggestion"] = candidate
+
+        if span.confidence is not None and span.confidence < cfg.min_detection_conf and status != "HUMAN_REVIEW":
+            reason = f"low detection confidence ({span.confidence:.2f}); was {status}: {reason}"
+            status = "HUMAN_REVIEW"
+            if report["correction"]:
+                report["suggestion"], report["correction"] = {**report["correction"], "applied": False}, None
+
+        self._finalize(report, status, reason)
+        return report
+
+    @staticmethod
+    def _evidence(span: DetectedSpan, verification: Verification) -> Optional[dict]:
+        source = verification.source
+        if not source:
+            return None
+        if span.label == "Ayah":
+            reference = {"type": "Quran", "surah_id": source["surah_id"], "surah_name": source["surah_name"], "ayah": source["ayah_id"]}
+        else:
+            reference = {"type": "Hadith", "hadithID": source["hadithID"], "book": source["book"], "title": source["title"]}
+        return {"source": reference, "signals": source.get("signals"), "comparison": compare(span.text, source["text"])}
+
+    @staticmethod
+    def describe_source(source: dict) -> str:
+        """Human-readable reference, e.g. ``Quran الفاتحة 1-3`` or ``Hadith #123``."""
+        if source["type"] == "Quran":
+            start, end = source["ayah_start"], source["ayah_end"]
+            return f"Quran {source['surah_name']} {start}" + (f"-{end}" if end != start else "")
+        return f"Hadith #{source['hadithID']}"
+
+    @staticmethod
+    def _apply_corrections(text: str, reports: List[dict]) -> str:
+        out = text
+        for report in sorted(reports, key=lambda r: r["start"], reverse=True):
+            if report["status"] == "CORRECTED" and report["correction"] and report["correction"].get("applied"):
+                out = out[: report["start"]] + report["correction"]["display_text"] + out[report["end"]:]
+        return out