Add impressive README with architecture, API docs, and cross-project links

README.md

@@ -1,11 +1,162 @@
 ---
 title: Hadith Search
-emoji: 🏢
+emoji: 📜
 colorFrom: indigo
-colorTo: gray
+colorTo: green
 sdk: docker
 pinned: false
 license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<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)*