README.md

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

<div align="center">

# 📜 Hadith Search

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

[![HuggingFace Space](https://img.shields.io/badge/🤗%20HuggingFace-Live%20Demo-yellow?style=for-the-badge)](https://huggingface.co/spaces/NightPrince/Hadith_Search)
[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
[![Python 3.10](https://img.shields.io/badge/Python-3.10-blue?style=for-the-badge&logo=python)](https://python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-teal?style=for-the-badge&logo=fastapi)](https://fastapi.tiangolo.com)

</div>

---

## 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 →](https://huggingface.co/spaces/NightPrince/Hadith_Search)**

---

## 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`

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

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

`top_k` accepts 1–10.

---

## Local Setup

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

---

## Built by

**يحيى النوساني** — [HuggingFace](https://huggingface.co/NightPrince)

---

*Part of a series of Islamic knowledge retrieval engines. See also: [Tafsir Search](https://github.com/NightPrinceY/Tafsir_Search) · [Quran Semantic Retrieval](https://github.com/NightPrinceY/Quran-Semantic-Retrieval)*