Apppublic

NightPrince/Quran-Semantic-Retrieval

sourceHugging Facemitupdated 7mo agoView on Hugging Face

0likes

App README

📖 Quran Semantic Retrieval

Find the Quranic Ayah that speaks to your question — powered by AI search across 7 classical Tafsir books.

![HuggingFace Space](https://huggingface.co/spaces/NightPrince/Quran-Semantic-Retrieval) ![License: MIT](LICENSE) ![Python 3.10](https://python.org) ![FastAPI](https://fastapi.tiangolo.com)

</div>

What Is This?

This engine answers a deceptively simple question: "Which Ayah of the Quran is most relevant to what I'm asking about?"

Instead of keyword-matching directly against Quranic text, it searches semantically through 7 major classical Tafsir (exegesis) books. Scholars have already explained every verse in depth — so matching your question against their explanations is far more semantically rich than matching against the verses alone.

The top-N most relevant Tafsir passages are found, their verse references are extracted, and the actual Ayah text is returned from a local copy of the Quran.

The Tafsir is the search index. The Ayah is the answer.

Demo

🔗 [Live on HuggingFace Spaces →](https://huggingface.co/spaces/NightPrince/Quran-Semantic-Retrieval)

Type any question or concept in Arabic — the engine finds and displays the most semantically related Quranic verse(s).

How It Works

User Query (Arabic)
      │
      ▼
┌─────────────────────────────────────────────┐
│           Arabic Preprocessing              │
│  Remove tashkeel · Normalize letters        │
│  Strip domain stopwords                     │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│         Hybrid Search (3 signals)           │
│                                             │
│  ① BM25       50%  — keyword precision      │
│  ② Semantic   35%  — neural meaning match   │
│  ③ Anchor     15%  — verse-ref boosting     │
│                                             │
│  Corpus: ~32,000 Tafsir passages            │
│  Model: paraphrase-multilingual-MiniLM-L12  │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
        Top-N unique verse keys
        (deduplicated across books)
                  │
                  ▼
┌─────────────────────────────────────────────┐
│         quran-simple.xml lookup             │
│   verse_key "3:135" → Ayah Arabic text      │
└─────────────────────────────────────────────┘
                  │
                  ▼
        Ayah text returned to user

Features

—Semantic search — understands meaning, not just keywords
—Hybrid retrieval — BM25 + FAISS + verse-anchor scoring combined
—Top-N results — user selects 1–5 Ayahs per query
—7 Tafsir sources — from easy (الميسر) to classical (الطبري)
—Pure Quranic output — only the Ayah is shown, never the Tafsir text
—RTL Arabic UI — clean glassmorphism design, fully right-to-left
—Fast cold start — embedding model baked into Docker image at build time

Tafsir Sources

Difficulty	Book
⭐ Easy	تفسير الميسر · تفسير السعدي
⭐⭐ Medium	تفسير الجلالين · تفسير ابن كثير
⭐⭐⭐ Advanced	تفسير البغوي · تفسير القرطبي
⭐⭐⭐⭐ Classical	تفسير الطبري

Tech Stack

Layer	Technology
Backend	FastAPI + Uvicorn
Embeddings	`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`
Vector Search	FAISS (CPU)
Keyword Search	BM25 (`rank-bm25`)
Quran Text	Tanzil Project XML (v1.1)
Frontend	Vanilla HTML/CSS/JS — RTL Arabic
Deployment	Docker on HuggingFace Spaces

Project Structure

├── app.py                  # FastAPI entrypoint, /api/search endpoint
├── tafsir_mcp.py           # Search orchestrator, XML loader, Ayah resolver
├── retrieval.py            # Hybrid search algorithm (BM25 + semantic + anchor)
├── hf_model.py             # Thread-safe SentenceTransformer with TTL cache
├── utils.py                # Arabic text utilities (tashkeel, normalization)
├── index.html              # Frontend UI
├── assets/
│   ├── script.js           # Fetch + render Ayah cards
│   └── style.css           # Glassmorphism RTL design
├── data/
│   ├── tafsir.csv          # ~32k Tafsir passages (7 books)
│   ├── tafsir_embeddings.npy
│   ├── bm25.pkl
│   ├── faiss_anchor.index
│   ├── anchor_dict.pkl
│   ├── unique_anchor_texts.pkl
│   └── quran-simple.xml    # Tanzil Quran text
└── Dockerfile

API

`POST /api/search`

json

// Request
{ "query": "الصبر على البلاء", "top_k": 3 }

// Response
{
  "results": [
    { "ayah_text": "وَلَنَبْلُوَنَّكُم بِشَيْءٍ مِّنَ الْخَوْفِ...", "verse_key": "2:155" },
    { "ayah_text": "إِنَّمَا يُوَفَّى الصَّابِرُونَ أَجْرَهُم...", "verse_key": "39:10" },
    { "ayah_text": "يَا أَيُّهَا الَّذِينَ آمَنُوا اسْتَعِينُوا...", "verse_key": "2:153" }
  ]
}

top_k accepts 1–5. The engine searches a pool of top_k × 7 candidates internally, then returns the top-N results with unique verse keys.

Local Setup

bash

# Install dependencies
pip install -r requirements.txt

# Run
uvicorn app:app --host 0.0.0.0 --port 7860 --reload

# Open
http://localhost:7860

Built by

يحيى النوساني — HuggingFace

Quran text sourced from the [Tanzil Project](https://tanzil.net) under Creative Commons Attribution 3.0.