Skip to content

QuranKit

A modular, Python-first computational Qur'anic research library

PyPI version Python versions License Tests


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

pip install qurankit-core

For CLI and development tools:

pip install "qurankit-core[cli,dev,tanzil]"

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:

@software{qurankit,
  title = {QuranKit: A Computational Qur'anic Research Library},
  author = {QuranKit Contributors},
  year = {2024},
  url = {https://github.com/AdakHaddad/qurankit},
  version = {0.2.0}
}