Metadata-Version: 2.5
Name: qurankit-core
Version: 0.1.0
Summary: A modular, Python-first computational Qur'anic research library
Project-URL: Homepage, https://github.com/AdakHaddad/qurankit
Project-URL: Repository, https://github.com/AdakHaddad/qurankit
Project-URL: Issues, https://github.com/AdakHaddad/qurankit/issues
Project-URL: Documentation, https://github.com/AdakHaddad/qurankit/tree/main/docs
Author-email: QuranKit Contributors <muqtada@example.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.12
Requires-Dist: pydantic-settings>=2.5
Requires-Dist: pydantic>=2.10
Provides-Extra: cli
Requires-Dist: click>=8.1; extra == 'cli'
Requires-Dist: rich>=3.10; extra == 'cli'
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Requires-Dist: types-requests>=2.32; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: tanzil
Requires-Dist: requests>=2.32; extra == 'tanzil'
Description-Content-Type: text/markdown

# QuranKit

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

QuranKit provides reusable Python tools for accessing and navigating Qur'anic text, searching surahs, ayahs, and words, exploring Arabic words, roots, lemmas, and morphology when sourced annotation is available, analyzing repeated expressions and relationships between ayahs, and performing reproducible computational and statistical research.

## Status

This project is in **early pre-alpha** development. The API is not stable and may change significantly.

## Features (Planned)

- **Qur'anic text access** — Preserve original source text with explicit edition identification
- **Arabic text processing** — Unicode-aware normalization profiles for search and analysis
- **Lexicon and morphology** — Root, lemma, and morphological analysis from sourced annotations
- **Search infrastructure** — Exact, phrase, token, and word occurrence search
- **Mutashabihat analysis** — Repeated phrase detection and textual relationship exploration
- **Computational research** — Reproducible frequency, distribution, and co-occurrence analysis
- **Dataset governance** — Provenance, licensing, and version tracking for all external data

## Installation

```bash
pip install qurankit
```

For development with optional dependencies:

```bash
pip install qurankit[dev,tanzil,cli]
```

## Quick Start

```python
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}")
```

## Documentation

- [Project Plan](plan.md)
- [Data Model](docs/data-model.md)
- [Arabic Text Standard](docs/arabic-text-standard.md)
- [Dataset Evaluation](docs/datasets.md)
- [Development Instructions](AGENTS.md)

## Principles

1. **Preserve originals** — Never overwrite source Arabic text with normalized text
2. **Source traceability** — Every annotation retains source, version, license, and attribution
3. **Separate evidence from inference** — Distinguish source text, deterministic results, computational suggestions, and scholarly interpretation
4. **Reproducibility** — Record dataset versions, algorithm versions, and normalization profiles
5. **Offline-capable** — Core workflows work without hosted services after data installation
6. **Provider-neutral** — No dependency on a particular LLM, cloud provider, or external API

## License

MIT License — see [LICENSE](LICENSE) for details.

Third-party datasets have their own licenses. See [docs/datasets.md](docs/datasets.md) for details.
