Extension Development Guide¶
This guide explains how to create custom adapters for QuranKit to integrate external scholarly resources: tafsir, hadith, qira'at, tajwid, and waqf/ibtida.
Overview¶
QuranKit uses a provider-neutral adapter pattern for extensions. This means:
- Core QuranKit code knows only about abstract interfaces
- External resources are integrated via concrete adapter implementations
- Adapters can be swapped without changing application code
- Multiple adapters of the same type can be registered simultaneously
Adapter Architecture¶
┌─────────────────────────────────────────────────────────────┐
│ Quran Class │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ tafsir │ │ hadith │ │ qiraat │ │ tajwid │ │
│ │ Registry │ │ Registry │ │ Registry │ │ Registry │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└───────┼─────────────┼─────────────┼─────────────┼──────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ Adapter Registries │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ TafsirAdapter│ │HadithAdapter │ │QiraatAdapter │ ... │
│ │ Registry │ │ Registry │ │ Registry │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
└─────────┼────────────────┼────────────────┼────────────────┘
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ Adapter 1 │ │ Adapter 1 │ │ Adapter 1 │
│ (File) │ │ (File) │ │ (File) │
│ │ │ │ │ │
│ Adapter 2 │ │ Adapter 2 │ │ Adapter 2 │
│ (API) │ │ (API) │ │ (API) │
└───────────┘ └───────────┘ └───────────┘
Creating a New Adapter¶
1. Define Data Models¶
Create Pydantic models for your data in the appropriate adapter module:
# In qurankit/adapters/my_extension.py
from pydantic import BaseModel, ConfigDict
class MyResource(BaseModel):
model_config = ConfigDict(extra="forbid")
resource_id: str
title: str
# ... other fields
2. Create the Abstract Adapter¶
Extend the base Adapter class:
from qurankit.adapters.base import Adapter, AdapterMetadata, AdapterRegistry
from qurankit.adapters.my_extension import MyResource
class MyExtensionAdapter(Adapter[MyResource]):
@property
@abstractmethod
def metadata(self) -> AdapterMetadata:
return AdapterMetadata(
adapter_id="my_extension",
name="My Extension Adapter",
source_id="my_source",
version="1.0.0",
license="MIT",
redistribution_status="allowed",
)
@abstractmethod
def load(self) -> None:
"""Load and index your data."""
...
@abstractmethod
def is_loaded(self) -> bool:
return self._loaded
# Add domain-specific methods
@abstractmethod
def get_resource(self, id: str) -> MyResource | None:
...
3. Create Registry¶
class MyExtensionAdapterRegistry(AdapterRegistry):
def register(self, adapter: MyExtensionAdapter) -> None:
if not isinstance(adapter, MyExtensionAdapter):
raise TypeError("Adapter must be a MyExtensionAdapter")
super().register(adapter)
# Proxy methods to first loaded adapter
def get_resource(self, id: str) -> MyResource | None:
adapter = self.get_first_loaded()
if adapter:
return adapter.get_resource(id)
return None
4. Implement File-Based Adapter¶
import json
from pathlib import Path
from qurankit.adapters.my_extension import MyExtensionAdapter, MyResource
class FileBasedMyExtensionAdapter(MyExtensionAdapter):
def __init__(self, data_path: str | None = None):
super().__init__(data_path)
self._resources: dict[str, MyResource] = {}
@property
def metadata(self) -> AdapterMetadata:
return AdapterMetadata(
adapter_id="file_my_extension",
name="File-based My Extension Adapter",
source_id="local_files",
version="0.1.0",
license="MIT",
redistribution_status="allowed",
)
def load(self) -> None:
if self._loaded:
return
if not self.data_path:
# Try default paths
default_paths = [Path("data/my_extension"), ...]
for path in default_paths:
if path.exists():
self.data_path = str(path)
break
if not self.data_path:
raise FileNotFoundError("No data path found")
# Load JSONL files
for jsonl_file in Path(self.data_path).glob("*.jsonl"):
with open(jsonl_file, encoding="utf-8") as f:
for line in f:
data = json.loads(line.strip())
resource = MyResource(**data)
self._resources[resource.resource_id] = resource
self._loaded = True
def get_resource(self, id: str) -> MyResource | None:
self.load()
return self._resources.get(id)
5. Register with Quran Class¶
In src/qurankit/core/quran.py, add a lazy-loaded property:
@property
def my_extension(self) -> Any:
if self._my_extension_registry is None:
from qurankit.adapters import MyExtensionAdapterRegistry
from qurankit.adapters.my_extension_impl import FileBasedMyExtensionAdapter
self._my_extension_registry = MyExtensionAdapterRegistry()
adapter = FileBasedMyExtensionAdapter(data_path="data/my_extension")
self._my_extension_registry.register(adapter)
return self._my_extension_registry
Data Format Guidelines¶
JSONL Format¶
All file-based adapters expect JSON Lines format (one JSON object per line):
{"resource_id": "example_1", "title": "Example", "text": "Content..."}
{"resource_id": "example_2", "title": "Another", "text": "More content..."}
Required Fields¶
Every entry should include:
- Unique identifier (resource_id, entry_id, hadith_id, etc.)
- Source/reference identifier
- Original text (text_original)
- Optional normalized text (text_normalized)
- Language code (ISO 639-1, e.g., "ar", "en")
- Optional metadata as JSON object
Example: Tafsir Entry¶
{
"entry_id": "ibn_kathir_2_255",
"source_id": "ibn_kathir",
"surah_number": 2,
"ayah_start": 255,
"ayah_end": 255,
"text_original": "قول الله تعالى: {اللَّهُ لَا إِلَٰهَ إِلَّا هُوَ الْحَيُّ الْقَيُّومُ}...",
"text_normalized": "قول الله تعالى: الله لا إله إلا هو الحي القيوم...",
"language": "ar",
"metadata_json": {"category": "divine_names", "topic": "ayat_al_kursi"}
}
Provenance and Licensing¶
Critical: Every adapter must document:
- Source metadata - Title, author, edition, publication details
- License - Exact license name and URL
- Redistribution status - "allowed", "restricted", or "unknown"
- Retrieval date - When the data was obtained
- Checksum - SHA-256 of source files when possible
# In your adapter's list_sources() or get_collection()
def list_sources(self) -> list[MySource]:
return [
MySource(
source_id="my_source",
title="My Source Title",
author="Author Name",
license="CC-BY-4.0",
license_url="https://creativecommons.org/licenses/by/4.0/",
redistribution_status="allowed",
# ...
)
]
Testing Adapters¶
Create tests in tests/unit/test_adapters.py:
def test_my_extension_adapter():
adapter = FileBasedMyExtensionAdapter(data_path="tests/fixtures/my_extension")
adapter.load()
assert adapter.is_loaded()
resource = adapter.get_resource("test_1")
assert resource is not None
assert resource.text_original == "Expected text"
Adding MCP Tools¶
To expose your adapter via MCP:
- Add tool functions to
src/qurankit/mcp/server.py - Follow the existing pattern for tool definitions
- Include comprehensive docstrings for the MCP schema
@server.tool()
async def get_my_extension(
resource_id: str,
) -> dict[str, Any] | None:
"""Get a resource from my extension.
Args:
resource_id: The resource identifier.
Returns:
Resource data or None if not found.
"""
quran = Quran.load()
resource = quran.my_extension.get_resource(resource_id)
if not resource:
return None
return {
"resource_id": resource.resource_id,
"title": resource.title,
"text": resource.text_original,
}
Best Practices¶
- Never fabricate data - Only return what's in your sources
- Preserve uncertainty - Include confidence scores when applicable
- Attribute sources - Every result must trace to a documented source
- Handle missing data gracefully - Return empty lists, not errors
- Use lazy loading - Load data only when first accessed
- Support multiple sources - Registry pattern allows multiple adapters
- Document normalization - If you normalize text, document the rules
Example: Complete Tafsir Adapter¶
See src/qurankit/adapters/tafsir.py (interface) and src/qurankit/adapters/tafsir_impl.py (implementation) for a complete working example.
Directory Structure for New Extensions¶
qurankit/
├── adapters/
│ ├── my_extension.py # Abstract interface + models + registry
│ ├── my_extension_impl.py # File-based implementation
│ └── __init__.py # Export new classes
├── data/
│ └── my_extension/ # JSONL data files
│ └── sample_data.jsonl
└── tests/
├── unit/
│ └── test_my_extension.py
└── fixtures/
└── my_extension/
└── sample_data.jsonl
Distribution¶
For redistributable data:
- Include in data/ directory
- Document in docs/datasets.md
For restricted data: - Implement adapter with configurable data path - Document manual download instructions - Never bundle copyrighted data without permission