QuranKit¶
A modular, Python-first computational Qur'anic research library
QuranKit provides reusable Python tools for:
- Accessing and navigating Qur'anic text — Preserve original source text with explicit edition identification
- Searching surahs, ayahs, and words — Exact, phrase, token, and word occurrence search
- Exploring Arabic words, roots, lemmas, and morphology — When sourced annotation is available
- Analyzing repeated expressions and relationships between ayahs — Mutashabihat detection
- Performing reproducible computational and statistical research — Frequency, distribution, co-occurrence
- Connecting optional linguistic and scholarly resources — Via provider-neutral adapter interfaces
- Providing tools that AI agents can call — Through MCP (Model Context Protocol) integration
Quick Install¶
For CLI and development tools:
Quick Start¶
from qurankit import Quran
# Load a Quran instance (requires a dataset to be installed)
quran = Quran.load()
# Access surahs and ayahs
surah = quran.surah(1) # Al-Fatihah
ayah = quran.ayah(1, 1) # 1:1
print(f"Surah: {surah.name_arabic}")
print(f"Ayah: {ayah.text_original}")
# Iterate through surah
for ayah in quran.surah(1).ayahs:
print(f"{ayah.reference}: {ayah.text_original}")
# Search
results = quran.search("بسم الله", mode="broad")
for result in results:
print(f"{result.reference}: {result.text}")
# Vocabulary analysis (requires QAC morphology data)
vocab = quran.vocabulary
print(vocab.lookup_root("ر ح م"))
print(vocab.get_root_frequency_list(limit=10))
Key Principles¶
| Principle | Description |
|---|---|
| Preserve originals | Never overwrite source Arabic text with normalized text |
| Source traceability | Every annotation retains source, version, license, and attribution |
| Separate evidence from inference | Distinguish source text, deterministic results, computational suggestions, and scholarly interpretation |
| Reproducibility | Record dataset versions, algorithm versions, and normalization profiles |
| Offline-capable | Core workflows work without hosted services after data installation |
| Provider-neutral | No dependency on a particular LLM, cloud provider, or external API |
Documentation¶
Project Status¶
| Component | Status |
|---|---|
| Core text access | ✅ v0.1.0 |
| Search & normalization | ✅ v0.1.0 |
| Dataset management | ✅ v0.1.0 |
| Tanzil provider | ✅ v0.1.0 |
| QAC morphology provider | ✅ v0.1.0 |
| Lexicon adapter interface | ✅ v0.2.0 |
| QuranicVocabulary analyzer | ✅ v0.2.0 |
| Mutashabihat engine | ✅ v0.2.0 |
| CLI tools | ✅ v0.2.0 |
| MCP server (read-only) | ✅ v0.2.0 |
| Tafsir/Hadith/Qira'at adapters | 🔄 Planned v0.3.0 |
License¶
MIT License — see LICENSE for details.
Third-party datasets have their own licenses. See Dataset Evaluation for details.
Citation¶
If you use QuranKit in your research, please cite: