README.md

metadata

title: Hadith Search
emoji: 📜
colorFrom: indigo
colorTo: green
sdk: docker
pinned: false
license: mit

📜 Hadith Search

Semantic search across thousands of Prophetic traditions — find the Hadith closest to your question by meaning, not just keywords.

---

What Is This?

A hybrid AI-powered search engine over a comprehensive corpus of Islamic Hadith (prophetic traditions). It combines neural semantic embeddings with classical BM25 and anchor-based retrieval to surface the most relevant traditions — even when your query uses different wording than the Hadith itself.

Each result includes the full Hadith text, its chain of narration (Isnad), topic classification, and a direct source link.

---

Demo

🔗 Live on HuggingFace Spaces →

---

How It Works

User Query (Arabic)
      │
      ▼
┌─────────────────────────────────────────────┐
│           Arabic Preprocessing              │
│  Remove tashkeel · Normalize letters        │
│  Unicode variant unification                │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│         Hybrid Search (3 signals)           │
│                                             │
│  ① Anchor     40%  — hadith entity match    │
│  ② Semantic   35%  — neural meaning match   │
│  ③ BM25       25%  — keyword precision      │
│                                             │
│  Model: paraphrase-multilingual-MiniLM-L12  │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
         Top-K ranked Hadiths
   (text · isnad · topic · source URL)

The anchor signal is weighted higher here (40%) because Hadith have strong named-entity anchors (narrators, topics, keywords) that are highly discriminative — making entity-aware matching the dominant signal.

---

Features

• Anchor-weighted hybrid — prioritizes entity matching (40%) over pure semantics
• Full Hadith metadata — text, Isnad chain, topic classification, source URL
• Arabic-native — built for Arabic queries with proper diacritic handling
• RTL Arabic UI — responsive glassmorphism design
• Fast cold start — model baked into Docker image at build time
• Cached embeddings — TTL-based in-memory cache for repeated queries

---

Tech Stack

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

---

Project Structure

├── app.py              # FastAPI entrypoint, /api/search endpoint
├── hadith_mcp.py       # Search orchestrator, RAG initialization
├── retrieval.py        # Hybrid search: BM25 + semantic + anchor
├── hf_model.py         # Thread-safe SentenceTransformer + TTL cache
├── utils.py            # Arabic text utilities (tashkeel, normalization)
├── index.html          # Frontend UI
├── assets/
│   ├── script.js       # Fetch + render result cards
│   └── style.css       # Glassmorphism RTL design
├── data/
│   ├── hadith.csv               # Hadith corpus (text, isnad, title, topic, url)
│   ├── hadith_embeddings.npy    # Pre-computed embeddings
│   ├── bm25.pkl                 # BM25 index
│   ├── faiss_anchor.index       # FAISS anchor index
│   ├── anchor_dict.pkl          # anchor → hadith row indices
│   └── unique_anchor_texts.pkl  # Ordered anchor list
└── Dockerfile

---

API

POST /api/search

// Request
{ "query": "إنما الأعمال بالنيات", "top_k": 5 }

// Response
{
  "results": [
    {
      "rank": 1,
      "title": "حديث النية",
      "text": "عَنْ عُمَرَ بْنِ الْخَطَّابِ قَالَ سَمِعْتُ رَسُولَ اللَّهِ...",
      "topic": "النية والإخلاص",
      "source_url": "https://..."
    }
  ]
}

top_k accepts 1–10.

---

Local Setup

pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 7860 --reload
# open http://localhost:7860

---

Built by

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

---

Part of a series of Islamic knowledge retrieval engines. See also: Tafsir Search · Quran Semantic Retrieval