Skip to content

API Reference

This page provides the complete API reference for QuranKit.

Core Classes

Quran

Main entry point for accessing Qur'anic text and analysis.

Quran

Bases: BaseModel

Main interface for accessing Qur'anic text.

This class provides methods to load datasets, retrieve surahs and ayahs, and perform searches. It maintains the current dataset and edition context.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    arbitrary_types_allowed=True, extra="forbid"
)

config class-attribute instance-attribute

config = Field(default_factory=get_config)

edition_id class-attribute instance-attribute

edition_id = Field(
    default=None, description="Current text edition"
)

vocabulary property

vocabulary

Get the QuranicVocabulary analyzer for the current edition.

Provides access to root/lemma occurrence lookup, concordance, frequency lists, and vocabulary statistics.

Returns:

Name Type Description
QuranicVocabulary 'QuranicVocabulary'

The vocabulary analyzer instance.

available_editions property

available_editions

Get list of available text editions.

available_normalization_profiles property

available_normalization_profiles

Get list of available normalization profiles.

load classmethod

load(edition_id=None, config=None)

Load a Quran instance with the specified edition.

Parameters:

Name Type Description Default
edition_id str | None

Text edition to use (defaults to config default)

None
config QuranKitConfig | None

Configuration instance (uses global if not provided)

None

Returns:

Type Description
Quran

Quran instance ready for queries

Raises:

Type Description
DatasetNotFoundError

If the required dataset is not installed

UnsupportedEditionError

If the edition is not available

surah

surah(surah_number)

Get a surah by number.

Parameters:

Name Type Description Default
surah_number int

Surah number (1-114)

required

Returns:

Type Description
Surah

Surah object

Raises:

Type Description
InvalidReferenceError

If surah number is invalid

surahs

surahs()

Get all surahs in order.

ayah

ayah(surah_number, ayah_number)

Get an ayah by reference.

Parameters:

Name Type Description Default
surah_number int

Surah number (1-114)

required
ayah_number int

Ayah number within surah

required

Returns:

Type Description
Ayah

Ayah object

Raises:

Type Description
InvalidReferenceError

If reference is invalid

ayah_text

ayah_text(surah_number, ayah_number, edition_id=None)

Get the text of an ayah in a specific edition.

Parameters:

Name Type Description Default
surah_number int

Surah number

required
ayah_number int

Ayah number

required
edition_id str | None

Text edition (uses current if not specified)

None

Returns:

Type Description
AyahText

AyahText with original source text

Raises:

Type Description
InvalidReferenceError

If reference is invalid

UnsupportedEditionError

If edition is not available

ayah_texts_for_surah

ayah_texts_for_surah(surah_number, edition_id=None)

Get all ayah texts for a surah.

word_tokens

word_tokens(
    surah_number,
    ayah_number,
    edition_id=None,
    tokenization_id=None,
)

Get word tokens for an ayah.

Parameters:

Name Type Description Default
surah_number int

Surah number

required
ayah_number int

Ayah number

required
edition_id str | None

Text edition

None
tokenization_id str | None

Tokenization scheme

None

Returns:

Type Description
list[WordToken]

List of WordToken objects

lookup_root

lookup_root(root_form, limit=1000)

Look up Qur'anic occurrences by Arabic root.

Parameters:

Name Type Description Default
root_form str

Arabic root (e.g., "ر ح م" or "رحم")

required
limit int

Maximum occurrences to return

1000

Returns:

Type Description
list[dict[str, Any]]

List of occurrence dictionaries with surah, ayah, surface form, etc.

lookup_lemma

lookup_lemma(lemma_form, limit=1000)

Look up Qur'anic occurrences by lemma (citation form).

Parameters:

Name Type Description Default
lemma_form str

Arabic lemma (e.g., "رحمة", "رحمن")

required
limit int

Maximum occurrences to return

1000

Returns:

Type Description
list[dict[str, Any]]

List of occurrence dictionaries

lookup_surface

lookup_surface(surface_form, limit=1000)

Look up Qur'anic occurrences by exact surface form.

Parameters:

Name Type Description Default
surface_form str

Exact Arabic word form

required
limit int

Maximum occurrences to return

1000

Returns:

Type Description
list[dict[str, Any]]

List of occurrence dictionaries

get_vocabulary_stats

get_vocabulary_stats(
    root_form=None, lemma_form=None, surface_form=None
)

Get comprehensive vocabulary statistics.

Parameters:

Name Type Description Default
root_form str | None

Arabic root

None
lemma_form str | None

Arabic lemma

None
surface_form str | None

Exact surface form

None

Returns:

Type Description
dict[str, Any]

Dictionary with frequency, distribution, and occurrence info

get_concordance

get_concordance(
    root_form=None,
    lemma_form=None,
    surface_form=None,
    context_words=3,
    limit=100,
)

Get concordance lines for a root, lemma, or surface form.

Parameters:

Name Type Description Default
root_form str | None

Arabic root

None
lemma_form str | None

Arabic lemma

None
surface_form str | None

Exact surface form

None
context_words int

Number of words before/after to include

3
limit int

Maximum concordance lines

100

Returns:

Type Description
list[dict[str, Any]]

List of concordance line dictionaries

get_root_frequency_list

get_root_frequency_list(min_occurrences=1, limit=100)

Get frequency list of all roots in the Qur'an.

Parameters:

Name Type Description Default
min_occurrences int

Minimum occurrences to include

1
limit int

Maximum roots to return

100

Returns:

Type Description
list[dict[str, Any]]

List of root frequency dictionaries sorted by frequency

get_lemma_frequency_list

get_lemma_frequency_list(min_occurrences=1, limit=100)

Get frequency list of all lemmas in the Qur'an.

Parameters:

Name Type Description Default
min_occurrences int

Minimum occurrences to include

1
limit int

Maximum lemmas to return

100

Returns:

Type Description
list[dict[str, Any]]

List of lemma frequency dictionaries sorted by frequency

set_edition

set_edition(edition_id)

Set the current text edition.

get_normalization_profile

get_normalization_profile(profile_id)

Get a normalization profile by ID.

search

search(
    query,
    mode="diacritics_insensitive",
    edition_id=None,
    normalization_profile=None,
    limit=100,
)

Search for text in the Qur'an.

Parameters:

Name Type Description Default
query str

Search query string

required
mode str

Search mode (exact_source, canonical_unicode, diacritics_insensitive, broad_orthographic)

'diacritics_insensitive'
edition_id str | None

Text edition to search

None
normalization_profile str | None

Normalization profile to use

None
limit int

Maximum number of results

100

Returns:

Type Description
list[dict[str, Any]]

List of search results with references and matched text

search_tokens

search_tokens(
    query,
    mode="diacritics_insensitive",
    edition_id=None,
    normalization_profile=None,
    limit=100,
)

Search for word tokens.

QuranKitConfig

Configuration for QuranKit behavior.

QuranKitConfig

Bases: BaseSettings

QuranKit configuration with environment variable support.

model_config class-attribute instance-attribute

model_config = SettingsConfigDict(
    env_prefix="QURANKIT_",
    case_sensitive=False,
    extra="ignore",
)

data_dir class-attribute instance-attribute

data_dir = Field(
    default=Path.home() / ".qurankit" / "data",
    description="Base directory for dataset storage",
)

default_edition class-attribute instance-attribute

default_edition = Field(
    default="tanzil-uthmani-v1",
    description="Default text edition ID",
)

cache_enabled class-attribute instance-attribute

cache_enabled = Field(
    default=True, description="Enable caching"
)

cache_dir class-attribute instance-attribute

cache_dir = Field(
    default=None, description="Cache directory"
)

default_normalization_profile class-attribute instance-attribute

default_normalization_profile = Field(
    default="diacritics-insensitive-v1",
    description="Default search normalization profile",
)

log_level class-attribute instance-attribute

log_level = Field(
    default="INFO", description="Logging level"
)

get_data_dir

get_data_dir()

Get the resolved data directory.

get_cache_dir

get_cache_dir()

Get the resolved cache directory.

Text Models

Surah

Surah

Bases: BaseModel

Represents a canonical surah.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    frozen=True, extra="forbid", str_strip_whitespace=True
)

surah_number class-attribute instance-attribute

surah_number = Field(
    ..., ge=1, le=114, description="Surah number (1-114)"
)

name_arabic class-attribute instance-attribute

name_arabic = Field(
    ..., description="Arabic name from reference source"
)

name_transliteration class-attribute instance-attribute

name_transliteration = Field(
    None, description="Transliteration for display"
)

name_translation class-attribute instance-attribute

name_translation = Field(
    None, description="Translation for display"
)

ayah_count class-attribute instance-attribute

ayah_count = Field(
    ..., gt=0, description="Number of ayahs in this surah"
)

metadata_source_id class-attribute instance-attribute

metadata_source_id = Field(
    None, description="Source of metadata"
)

validate_surah_number classmethod

validate_surah_number(v)

Ayah

Ayah

Bases: BaseModel

Represents a canonical ayah location, independent of text edition.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    frozen=True, extra="forbid", str_strip_whitespace=True
)

surah_number class-attribute instance-attribute

surah_number = Field(
    ..., ge=1, le=114, description="Surah number"
)

ayah_number class-attribute instance-attribute

ayah_number = Field(
    ..., gt=0, description="Ayah number within surah"
)

global_ayah_number class-attribute instance-attribute

global_ayah_number = Field(
    None, description="Global sequence number if adopted"
)

metadata_json class-attribute instance-attribute

metadata_json = Field(
    None, description="Additional structural metadata"
)

reference property

reference

Return the standard reference string (e.g., '2:255').

WordToken

WordToken

Bases: BaseModel

Represents a token occurrence in a particular ayah text and tokenization.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    frozen=True, extra="forbid", str_strip_whitespace=True
)

token_id class-attribute instance-attribute

token_id = Field(..., description='Stable internal ID')

edition_id class-attribute instance-attribute

edition_id = Field(..., description='Text edition')

surah_number class-attribute instance-attribute

surah_number = Field(
    ..., ge=1, le=114, description="Surah number"
)

ayah_number class-attribute instance-attribute

ayah_number = Field(..., gt=0, description='Ayah number')

tokenization_id class-attribute instance-attribute

tokenization_id = Field(
    ..., description="Segmentation scheme/version"
)

token_index class-attribute instance-attribute

token_index = Field(
    ...,
    ge=0,
    description="Position within ayah under this scheme",
)

surface_original class-attribute instance-attribute

surface_original = Field(
    ..., description="Exact token as segmented from source"
)

char_start class-attribute instance-attribute

char_start = Field(
    None,
    ge=0,
    description="Offset into source ayah text (code points)",
)

char_end class-attribute instance-attribute

char_end = Field(
    None,
    ge=0,
    description="Exclusive end offset (code points)",
)

source_record_id class-attribute instance-attribute

source_record_id = Field(
    None, description="Source token ID"
)

segmentation_notes class-attribute instance-attribute

segmentation_notes = Field(
    None, description="Notes about segmentation"
)

reference property

reference

validate_offsets classmethod

validate_offsets(v, info)

TextEdition

TextEdition

Bases: BaseModel

Represents a text source, orthographic representation, or reading edition.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    frozen=True, extra="forbid", str_strip_whitespace=True
)

edition_id class-attribute instance-attribute

edition_id = Field(
    ..., description="Internal stable identifier"
)

dataset_id class-attribute instance-attribute

dataset_id = Field(
    ..., description="Dataset providing the text"
)

name class-attribute instance-attribute

name = Field(..., description='Edition name')

script_type class-attribute instance-attribute

script_type = Field(
    ..., description="Script/orthography type"
)

reading_id class-attribute instance-attribute

reading_id = Field(
    None,
    description="Qira'ah/riwayah identifier when applicable",
)

orthography class-attribute instance-attribute

orthography = Field(None, description='Source description')

tokenization_id class-attribute instance-attribute

tokenization_id = Field(
    None, description="Tokenization scheme/version"
)

is_default class-attribute instance-attribute

is_default = Field(
    False, description="Default display edition"
)

notes class-attribute instance-attribute

notes = Field(
    None, description="Differences and known limitations"
)

Vocabulary & Lexicon

QuranicVocabulary

QuranicVocabulary

QuranicVocabulary(
    data_access=None, edition_id="tanzil-uthmani-v1"
)

Qur'anic vocabulary analyzer.

Connects dictionary/lexicon entries to actual Qur'anic occurrences using the word token and morphological analysis data in the database. Provides concordance, frequency, and distribution analysis.

Initialize vocabulary analyzer.

Parameters:

Name Type Description Default
data_access DataAccess | None

DataAccess instance (creates default if None)

None
edition_id str

Text edition to analyze

'tanzil-uthmani-v1'

data_access instance-attribute

data_access = data_access or DataAccess()

edition_id instance-attribute

edition_id = edition_id

get_occurrences_by_root

get_occurrences_by_root(root_form, limit=1000)

Get all Qur'anic occurrences of a root.

Uses QAC morphology annotations (token_analysis) linked to word tokens.

Parameters:

Name Type Description Default
root_form str

Arabic root (e.g., "ر ح م" or "رحم")

required
limit int

Maximum occurrences to return

1000

Returns:

Type Description
list[QuranicOccurrence]

List of QuranicOccurrence objects

get_occurrences_by_lemma

get_occurrences_by_lemma(lemma_form, limit=1000)

Get all Qur'anic occurrences of a lemma.

Parameters:

Name Type Description Default
lemma_form str

Arabic lemma (e.g., "رحمة", "رحمن")

required
limit int

Maximum occurrences to return

1000

Returns:

Type Description
list[QuranicOccurrence]

List of QuranicOccurrence objects

get_occurrences_by_surface

get_occurrences_by_surface(surface_form, limit=1000)

Get all Qur'anic occurrences of a surface form (exact word).

Parameters:

Name Type Description Default
surface_form str

Exact Arabic word form

required
limit int

Maximum occurrences to return

1000

Returns:

Type Description
list[QuranicOccurrence]

List of QuranicOccurrence objects

get_vocabulary_stats

get_vocabulary_stats(
    root_form=None, lemma_form=None, surface_form=None
)

Get comprehensive statistics for a root, lemma, or surface form.

Parameters:

Name Type Description Default
root_form str | None

Arabic root

None
lemma_form str | None

Arabic lemma

None
surface_form str | None

Exact surface form

None

Returns:

Type Description
VocabularyStats

VocabularyStats with frequency, distribution, etc.

get_concordance

get_concordance(
    root_form=None,
    lemma_form=None,
    surface_form=None,
    context_words=3,
    limit=100,
)

Get concordance lines for a root, lemma, or surface form.

Returns each occurrence with surrounding context words.

Parameters:

Name Type Description Default
root_form str | None

Arabic root

None
lemma_form str | None

Arabic lemma

None
surface_form str | None

Exact surface form

None
context_words int

Number of words before/after to include

3
limit int

Maximum concordance lines

100

Returns:

Type Description
list[dict[str, Any]]

List of concordance line dictionaries

get_root_frequency_list

get_root_frequency_list(min_occurrences=1, limit=100)

Get frequency list of all roots in the Qur'an (from QAC data).

Parameters:

Name Type Description Default
min_occurrences int

Minimum occurrences to include

1
limit int

Maximum roots to return

100

Returns:

Type Description
list[dict[str, Any]]

List of root frequency dictionaries sorted by frequency

get_lemma_frequency_list

get_lemma_frequency_list(min_occurrences=1, limit=100)

Get frequency list of all lemmas in the Qur'an (from QAC data).

Parameters:

Name Type Description Default
min_occurrences int

Minimum occurrences to include

1
limit int

Maximum lemmas to return

100

Returns:

Type Description
list[dict[str, Any]]

List of lemma frequency dictionaries sorted by frequency

DictionaryAdapter

DictionaryAdapter

Bases: ABC

Abstract base class for dictionary adapters.

All dictionary providers must implement this interface to integrate with QuranKit's lexicon layer. The adapter is responsible for: - Providing resource metadata (LexicalResource) - Looking up entries by root, lemma, or headword - Returning senses with definitions and provenance - Supporting Qur'anic occurrence lists when available

Implementations must preserve source attribution for every returned record and must not fabricate or infer data not present in the source.

resource_id abstractmethod property

resource_id

Unique identifier for this lexical resource (e.g., 'lane-lexicon', 'mufradat').

resource_title abstractmethod property

resource_title

Human-readable title of the lexical resource.

capabilities abstractmethod property

capabilities

Capabilities supported by this adapter.

get_resource_metadata abstractmethod

get_resource_metadata()

Get the LexicalResource metadata for this adapter.

Returns:

Type Description
LexicalResource

LexicalResource with title, author, edition, language, scope, etc.

lookup_by_root abstractmethod

lookup_by_root(root_form, limit=50)

Look up lexical entries by Arabic root.

Parameters:

Name Type Description Default
root_form str

Arabic root (e.g., "ر ح م" or "رحم")

required
limit int

Maximum number of entries to return

50

Returns:

Type Description
LexicalLookupResult

LexicalLookupResult with matching entries and senses

lookup_by_lemma abstractmethod

lookup_by_lemma(lemma_form, limit=50)

Look up lexical entries by lemma (citation form).

Parameters:

Name Type Description Default
lemma_form str

Arabic lemma (e.g., "رحمة" or "رحمن")

required
limit int

Maximum number of entries to return

50

Returns:

Type Description
LexicalLookupResult

LexicalLookupResult with matching entries and senses

lookup_by_headword abstractmethod

lookup_by_headword(headword, limit=50)

Look up lexical entries by headword (exact or prefix match).

Parameters:

Name Type Description Default
headword str

Arabic headword to search

required
limit int

Maximum number of entries to return

50

Returns:

Type Description
LexicalLookupResult

LexicalLookupResult with matching entries and senses

get_senses_for_entry abstractmethod

get_senses_for_entry(lexical_entry_id)

Get all senses for a specific lexical entry.

Parameters:

Name Type Description Default
lexical_entry_id str

Internal ID of the lexical entry

required

Returns:

Type Description
list[LexicalSense]

List of LexicalSense objects

get_quranic_occurrences

get_quranic_occurrences(root_form)

Get Qur'anic occurrences for a root (optional).

Returns a list of occurrence records with surah, ayah, word position, and surface form. Only implemented if the source provides this data.

Parameters:

Name Type Description Default
root_form str

Arabic root

required

Returns:

Type Description
list[dict[str, Any]]

List of occurrence dictionaries

get_semantic_relations

get_semantic_relations(lexical_entry_id)

Get semantic relations for a lexical entry (optional).

Returns relations like synonyms, antonyms, hypernyms, etc. Only implemented if the source provides this data.

Parameters:

Name Type Description Default
lexical_entry_id str

Internal ID of the lexical entry

required

Returns:

Type Description
list[dict[str, Any]]

List of relation dictionaries with type, target, and evidence

get_examples

get_examples(lexical_entry_id)

Get usage examples for a lexical entry (optional).

Only implemented if the source provides examples.

Parameters:

Name Type Description Default
lexical_entry_id str

Internal ID of the lexical entry

required

Returns:

Type Description
list[str]

List of example strings

search

search(query, mode='prefix', limit=50)

General search across headwords, roots, and lemmas.

Default implementation dispatches to headword lookup. Override for more sophisticated search.

Parameters:

Name Type Description Default
query str

Search query

required
mode str

Search mode (prefix, exact, contains)

'prefix'
limit int

Maximum results

50

Returns:

Type Description
LexicalLookupResult

LexicalLookupResult

close

close()

Close any open connections or resources.

FileBasedDictionaryAdapter

FileBasedDictionaryAdapter

FileBasedDictionaryAdapter(
    resource_id,
    resource_title,
    data_path,
    source,
    capabilities=None,
)

Bases: DictionaryAdapter

Dictionary adapter that loads from local JSONL or SQLite files.

Supports loading lexical resources from structured files with proper provenance tracking. Designed for public domain or openly licensed dictionary data that users provide locally.

Initialize file-based dictionary adapter.

Parameters:

Name Type Description Default
resource_id str

Unique identifier (e.g., "lane-lexicon")

required
resource_title str

Human-readable title

required
data_path Path

Path to data file (JSONL or SQLite)

required
source Source

Source provenance object

required
capabilities AdapterCapabilities | None

Adapter capabilities (auto-detected if None)

None

resource_id property

resource_id

resource_title property

resource_title

capabilities property

capabilities

get_resource_metadata

get_resource_metadata()

lookup_by_root

lookup_by_root(root_form, limit=50)

lookup_by_lemma

lookup_by_lemma(lemma_form, limit=50)

lookup_by_headword

lookup_by_headword(headword, limit=50)

get_senses_for_entry

get_senses_for_entry(lexical_entry_id)

get_examples

get_examples(lexical_entry_id)

close

close()

DictionaryAdapterRegistry

DictionaryAdapterRegistry

DictionaryAdapterRegistry()

Registry for dictionary adapters.

Manages registration, discovery, and access to dictionary adapters.

register

register(adapter)

Register a dictionary adapter.

Parameters:

Name Type Description Default
adapter DictionaryAdapter

DictionaryAdapter instance to register

required

unregister

unregister(resource_id)

Unregister a dictionary adapter.

Parameters:

Name Type Description Default
resource_id str

Resource ID to unregister

required

Returns:

Type Description
bool

True if adapter was found and removed

get_adapter

get_adapter(resource_id)

Get an adapter by resource ID.

get_resource_metadata

get_resource_metadata(resource_id)

Get resource metadata by resource ID.

list_adapters

list_adapters()

List all registered adapter resource IDs.

list_resources

list_resources()

List all registered resource metadata.

lookup_root_across_resources

lookup_root_across_resources(
    root_form, limit=50, resource_ids=None
)

Look up a root across multiple resources.

Parameters:

Name Type Description Default
root_form str

Arabic root

required
limit int

Maximum results per resource

50
resource_ids list[str] | None

Specific resources to search (None = all)

None

Returns:

Type Description
dict[str, LexicalLookupResult]

Dict mapping resource_id to LexicalLookupResult

lookup_lemma_across_resources

lookup_lemma_across_resources(
    lemma_form, limit=50, resource_ids=None
)

Look up a lemma across multiple resources.

Parameters:

Name Type Description Default
lemma_form str

Arabic lemma

required
limit int

Maximum results per resource

50
resource_ids list[str] | None

Specific resources to search (None = all)

None

Returns:

Type Description
dict[str, LexicalLookupResult]

Dict mapping resource_id to LexicalLookupResult

close_all

close_all()

Close all registered adapters.

SearchEngine

SearchEngine

SearchEngine(data_access=None)

Search engine for Qur'anic text using SQLite FTS5.

Uses multiple indexes for different normalization profiles: - exact-source-v1: Exact text matching - diacritics-insensitive-v1: Diacritic-insensitive matching - search-broad-v1: Broad orthographic matching

Initialize search engine.

Parameters:

Name Type Description Default
data_access DataAccess | None

DataAccess instance. If None, creates one.

None

AYAH_FTS_TABLES class-attribute instance-attribute

AYAH_FTS_TABLES = {
    "exact-source-v1": (
        "ayah_text_fts_exact",
        "text_original",
    ),
    "diacritics-insensitive-v1": (
        "ayah_text_fts_diacritic_insensitive",
        "text_normalized",
    ),
    "search-broad-v1": (
        "ayah_text_fts_broad",
        "text_normalized",
    ),
    "canonical-unicode-v1": (
        "ayah_text_fts_diacritic_insensitive",
        "text_normalized",
    ),
}

TOKEN_FTS_TABLES class-attribute instance-attribute

TOKEN_FTS_TABLES = {
    "exact-source-v1": (
        "word_token_fts_exact",
        "surface_original",
    ),
    "diacritics-insensitive-v1": (
        "word_token_fts_diacritic_insensitive",
        "surface_normalized",
    ),
    "search-broad-v1": (
        "word_token_fts_broad",
        "surface_normalized",
    ),
    "canonical-unicode-v1": (
        "word_token_fts_diacritic_insensitive",
        "surface_normalized",
    ),
}

MODE_TO_RESULT_TYPE class-attribute instance-attribute

MODE_TO_RESULT_TYPE = {
    SearchMode.EXACT_SOURCE: SearchResultType.EXACT_SOURCE_MATCH,
    SearchMode.CANONICAL_UNICODE: SearchResultType.UNICODE_NORMALIZED_MATCH,
    SearchMode.DIACRITICS_INSENSITIVE: SearchResultType.DIACRITIC_INSENSITIVE_MATCH,
    SearchMode.BROAD_ORTHOGRAPHIC: SearchResultType.BROAD_ORTHOGRAPHIC_MATCH,
    SearchMode.TOKEN_SEQUENCE: SearchResultType.TOKEN_SEQUENCE_MATCH,
    SearchMode.LEMMA: SearchResultType.LEMMA_MATCH,
    SearchMode.ROOT: SearchResultType.ROOT_MATCH,
    SearchMode.FUZZY: SearchResultType.FUZZY_CANDIDATE,
    SearchMode.SEMANTIC: SearchResultType.SEMANTIC_CANDIDATE,
}

MODE_TO_PROFILE class-attribute instance-attribute

MODE_TO_PROFILE = {
    SearchMode.EXACT_SOURCE: "exact-source-v1",
    SearchMode.CANONICAL_UNICODE: "canonical-unicode-v1",
    SearchMode.DIACRITICS_INSENSITIVE: "diacritics-insensitive-v1",
    SearchMode.BROAD_ORTHOGRAPHIC: "search-broad-v1",
    SearchMode.TOKEN_SEQUENCE: "diacritics-insensitive-v1",
    SearchMode.LEMMA: "diacritics-insensitive-v1",
    SearchMode.ROOT: "diacritics-insensitive-v1",
    SearchMode.FUZZY: "search-broad-v1",
    SearchMode.SEMANTIC: "search-broad-v1",
}

data_access instance-attribute

data_access = data_access or DataAccess()

db instance-attribute

db = self.data_access.db

search

search(
    query,
    mode=SearchMode.DIACRITICS_INSENSITIVE,
    edition_id=None,
    normalization_profile=None,
    limit=100,
    offset=0,
)

Search for text in the Qur'an.

Parameters:

Name Type Description Default
query str

Search query string

required
mode SearchMode

Search mode

DIACRITICS_INSENSITIVE
edition_id str | None

Text edition to search (uses default if not specified)

None
normalization_profile str | None

Normalization profile (uses mode default if not specified)

None
limit int

Maximum number of results

100
offset int

Offset for pagination

0

Returns:

Type Description
list[SearchResult]

List of SearchResult objects

search_tokens

search_tokens(
    query,
    mode=SearchMode.DIACRITICS_INSENSITIVE,
    edition_id=None,
    normalization_profile=None,
    limit=100,
    offset=0,
)

Search for word tokens.

Parameters:

Name Type Description Default
query str

Search query string

required
mode SearchMode

Search mode

DIACRITICS_INSENSITIVE
edition_id str | None

Text edition to search

None
normalization_profile str | None

Normalization profile

None
limit int

Maximum number of results

100
offset int

Offset for pagination

0

Returns:

Type Description
list[SearchResult]

List of SearchResult objects for token matches

search_exact

search_exact(query, edition_id=None, limit=100)

Exact source text search.

search_diacritic_insensitive

search_diacritic_insensitive(
    query, edition_id=None, limit=100
)

Diacritic-insensitive search.

search_broad

search_broad(query, edition_id=None, limit=100)

Broad orthographic search.

NormalizationEngine

NormalizationEngine

NormalizationEngine()

Engine for applying normalization profiles to Arabic text.

Each profile is a documented, versioned transformation that can be applied to queries or indexed text for search.

register

register(profile)

Register a normalization profile.

get_profile

get_profile(profile_id)

Get a normalization profile by ID.

list_profiles

list_profiles()

List all registered profiles.

normalize

normalize(text, profile_id, return_mappings=False)

Normalize text using a named profile.

Parameters:

Name Type Description Default
text str

Input text to normalize

required
profile_id str

Profile identifier

required
return_mappings bool

Whether to return character mappings

False

Returns:

Type Description
NormalizationResult

NormalizationResult with original and normalized text

NormalizationProfile

NormalizationProfile

Bases: BaseModel

Defines a named and versioned text transformation.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    frozen=True, extra="forbid", str_strip_whitespace=True
)

profile_id class-attribute instance-attribute

profile_id = Field(
    ...,
    description="Unique profile identifier (e.g., 'search-v1')",
)

name class-attribute instance-attribute

name = Field(..., description='Human-readable name')

version class-attribute instance-attribute

version = Field(..., description='Profile version')

description class-attribute instance-attribute

description = Field(..., description='Intended use')

rules_json class-attribute instance-attribute

rules_json = Field(
    ..., description="Explicit transformations and options"
)

implementation_version class-attribute instance-attribute

implementation_version = Field(
    ..., description="Code version"
)

created_at class-attribute instance-attribute

created_at = Field(
    default_factory=datetime.utcnow,
    description="Creation timestamp",
)

Mutashabihat

MutashabihatEngine

MutashabihatEngine

MutashabihatEngine(
    data_access=None,
    default_normalization="diacritics-insensitive-v1",
)

Engine for finding repeated and similar phrases in the Qur'an.

Supports: - Exact phrase matching (deterministic) - Exact n-gram matching (deterministic) - Normalized exact matching (diacritic-insensitive, etc.) - Near-duplicate detection (computational suggestion) - Shared root/lemma analysis (when morphology data available) - Similar openings/endings (deterministic) - Recurring expressions (deterministic)

Initialize mutashabihat engine.

Parameters:

Name Type Description Default
data_access DataAccess | None

DataAccess instance for database queries

None
default_normalization str

Default normalization profile for matches

'diacritics-insensitive-v1'

data_access instance-attribute

data_access = data_access or DataAccess()

default_normalization instance-attribute

default_normalization = default_normalization

find_exact_phrase

find_exact_phrase(
    reference, edition_id="tanzil-uthmani-v1", min_length=2
)

Find exact phrase matches for a given ayah.

Parameters:

Name Type Description Default
reference str

Ayah reference (e.g., "2:255")

required
edition_id str

Text edition to search

'tanzil-uthmani-v1'
min_length int

Minimum phrase length in words

2

Returns:

Type Description
MutashabihatResult

MutashabihatResult with exact phrase matches

find_exact_ngrams

find_exact_ngrams(
    edition_id="tanzil-uthmani-v1", n=3, min_occurrences=2
)

Find all exact n-grams that occur at least min_occurrences times.

Parameters:

Name Type Description Default
edition_id str

Text edition to search

'tanzil-uthmani-v1'
n int

N-gram size (number of words)

3
min_occurrences int

Minimum occurrences to report

2

Returns:

Type Description
list[PhraseMatch]

List of PhraseMatch for recurring n-grams

find_normalized_matches

find_normalized_matches(
    reference,
    edition_id="tanzil-uthmani-v1",
    normalization_profile="diacritics-insensitive-v1",
    min_words=2,
)

Find matches using normalized text comparison.

Parameters:

Name Type Description Default
reference str

Ayah reference (e.g., "2:255")

required
edition_id str

Text edition to search

'tanzil-uthmani-v1'
normalization_profile str

Normalization profile to use

'diacritics-insensitive-v1'
min_words int

Minimum matching word count

2

Returns:

Type Description
MutashabihatResult

MutashabihatResult with normalized matches

find_near_duplicates

find_near_duplicates(
    reference,
    edition_id="tanzil-uthmani-v1",
    threshold=0.7,
    normalization_profile="search-broad-v1",
)

Find near-duplicate phrases using token-based similarity.

Parameters:

Name Type Description Default
reference str

Ayah reference (e.g., "2:255")

required
edition_id str

Text edition to search

'tanzil-uthmani-v1'
threshold float

Minimum Jaccard similarity (0.0-1.0)

0.7
normalization_profile str

Normalization profile for comparison

'search-broad-v1'

Returns:

Type Description
MutashabihatResult

MutashabihatResult with near-duplicate matches

find_similar_openings

find_similar_openings(
    edition_id="tanzil-uthmani-v1",
    prefix_length=3,
    min_occurrences=2,
)

Find ayahs with similar opening phrases.

Parameters:

Name Type Description Default
edition_id str

Text edition to search

'tanzil-uthmani-v1'
prefix_length int

Number of words to compare at start

3
min_occurrences int

Minimum occurrences to report

2

Returns:

Type Description
list[PhraseMatch]

List of PhraseMatch for similar openings

find_similar_endings

find_similar_endings(
    edition_id="tanzil-uthmani-v1",
    suffix_length=3,
    min_occurrences=2,
)

Find ayahs with similar ending phrases.

Parameters:

Name Type Description Default
edition_id str

Text edition to search

'tanzil-uthmani-v1'
suffix_length int

Number of words to compare at end

3
min_occurrences int

Minimum occurrences to report

2

Returns:

Type Description
list[PhraseMatch]

List of PhraseMatch for similar endings

find_recurring_expressions

find_recurring_expressions(
    edition_id="tanzil-uthmani-v1",
    min_length=3,
    min_occurrences=3,
)

Find recurring expressions (exact phrases) across the corpus.

Parameters:

Name Type Description Default
edition_id str

Text edition to search

'tanzil-uthmani-v1'
min_length int

Minimum phrase length in words

3
min_occurrences int

Minimum occurrences to report

3

Returns:

Type Description
list[PhraseMatch]

List of PhraseMatch for recurring expressions

Reports

ComparisonReport

ComparisonReport dataclass

ComparisonReport(
    query_reference,
    query_text,
    edition_id,
    method,
    normalization_profile=None,
    total_matches=0,
    matches_by_category=dict(),
    matches_by_method=dict(),
    unique_surahs_matched=list(),
    unique_ayahs_matched=list(),
    score_stats=dict(),
    parameters=dict(),
)

Structured report for mutashabihat comparison.

query_reference instance-attribute

query_reference

query_text instance-attribute

query_text

edition_id instance-attribute

edition_id

method instance-attribute

method

normalization_profile class-attribute instance-attribute

normalization_profile = None

total_matches class-attribute instance-attribute

total_matches = 0

matches_by_category class-attribute instance-attribute

matches_by_category = field(default_factory=dict)

matches_by_method class-attribute instance-attribute

matches_by_method = field(default_factory=dict)

unique_surahs_matched class-attribute instance-attribute

unique_surahs_matched = field(default_factory=list)

unique_ayahs_matched class-attribute instance-attribute

unique_ayahs_matched = field(default_factory=list)

score_stats class-attribute instance-attribute

score_stats = field(default_factory=dict)

parameters class-attribute instance-attribute

parameters = field(default_factory=dict)

to_dict

to_dict()

Dataset Management

DatasetRegistry

DatasetRegistry

Bases: BaseModel

Registry for managing installed datasets.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    arbitrary_types_allowed=True, extra="forbid"
)

data_dir class-attribute instance-attribute

data_dir = Field(
    default_factory=lambda: get_config().get_data_dir()
)

load

load()

Load all manifests from the data directory.

register

register(manifest)

Register a dataset manifest.

get

get(dataset_id)

Get a dataset manifest by ID.

get_dataset

get_dataset(dataset_id)

Get a dataset by ID.

get_source

get_source(dataset_id)

Get the source for a dataset.

list_datasets

list_datasets()

List all registered datasets.

list_manifests

list_manifests()

List all registered manifests.

is_installed

is_installed(dataset_id)

Check if a dataset is installed.

unregister

unregister(dataset_id)

Unregister a dataset (removes manifest only, not data files).

verify_checksums

verify_checksums(dataset_id)

Verify checksums for all files in a dataset.

ManifestManager

ManifestManager

Bases: BaseModel

Manager for creating and validating dataset manifests.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    arbitrary_types_allowed=True, extra="forbid"
)

create_manifest

create_manifest(
    dataset, source, source_files, validation_report=None
)

Create a complete dataset manifest with file checksums.

Parameters:

Name Type Description Default
dataset Dataset

Dataset metadata

required
source Source

Source information

required
source_files list[Path]

List of source file paths

required
validation_report dict[str, Any] | None

Optional validation results

None

Returns:

Type Description
DatasetManifest

Complete DatasetManifest

save_manifest

save_manifest(manifest, output_path)

Save a manifest to a JSON file.

load_manifest

load_manifest(manifest_path)

Load a manifest from a JSON file.

create_tanzil_manifest staticmethod

create_tanzil_manifest(
    version="1.1",
    retrieved_at=None,
    text_file=None,
    metadata_file=None,
)

Create a manifest for the Tanzil Quran text dataset.

DatasetValidator

DatasetValidator

DatasetValidator()

Validates dataset integrity and consistency.

EXPECTED_AYAH_COUNTS class-attribute instance-attribute

EXPECTED_AYAH_COUNTS = {
    1: 7,
    2: 286,
    3: 200,
    4: 176,
    5: 120,
    6: 165,
    7: 206,
    8: 75,
    9: 129,
    10: 109,
    11: 123,
    12: 111,
    13: 43,
    14: 52,
    15: 99,
    16: 128,
    17: 111,
    18: 110,
    19: 98,
    20: 135,
    21: 112,
    22: 78,
    23: 118,
    24: 64,
    25: 77,
    26: 227,
    27: 93,
    28: 88,
    29: 69,
    30: 60,
    31: 34,
    32: 30,
    33: 73,
    34: 54,
    35: 45,
    36: 83,
    37: 182,
    38: 88,
    39: 75,
    40: 85,
    41: 54,
    42: 53,
    43: 89,
    44: 59,
    45: 37,
    46: 35,
    47: 38,
    48: 29,
    49: 18,
    50: 45,
    51: 60,
    52: 49,
    53: 62,
    54: 55,
    55: 78,
    56: 96,
    57: 29,
    58: 22,
    59: 24,
    60: 13,
    61: 14,
    62: 11,
    63: 11,
    64: 18,
    65: 12,
    66: 12,
    67: 30,
    68: 52,
    69: 52,
    70: 44,
    71: 28,
    72: 28,
    73: 20,
    74: 56,
    75: 40,
    76: 31,
    77: 50,
    78: 40,
    79: 46,
    80: 42,
    81: 29,
    82: 19,
    83: 36,
    84: 25,
    85: 22,
    86: 17,
    87: 19,
    88: 26,
    89: 30,
    90: 20,
    91: 15,
    92: 21,
    93: 11,
    94: 8,
    95: 8,
    96: 19,
    97: 5,
    98: 8,
    99: 8,
    100: 11,
    101: 11,
    102: 8,
    103: 3,
    104: 9,
    105: 5,
    106: 4,
    107: 7,
    108: 3,
    109: 6,
    110: 3,
    111: 5,
    112: 4,
    113: 5,
    114: 6,
}

issues instance-attribute

issues = []

validate_manifest

validate_manifest(manifest)

Validate a dataset manifest.

validate_surah_structure

validate_surah_structure(surahs)

Validate surah structure against expected counts.

validate_ayah_texts

validate_ayah_texts(ayah_texts, edition_id)

Validate ayah text records.

has_errors

has_errors()

Check if any errors were found.

get_errors

get_errors()

Get all error-level issues.

get_warnings

get_warnings()

Get all warning-level issues.

raise_if_errors

raise_if_errors()

Raise ValidationError if any errors were found.

Provenance Models

DatasetManifest

DatasetManifest

Bases: BaseModel

Complete manifest for a dataset including source and validation info.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    frozen=True, extra="forbid", str_strip_whitespace=True
)

dataset instance-attribute

dataset

source instance-attribute

source

files class-attribute instance-attribute

files = Field(
    default_factory=list, description="Source file metadata"
)

validation_report class-attribute instance-attribute

validation_report = Field(
    None, description="Validation results"
)

created_at class-attribute instance-attribute

created_at = Field(
    default_factory=datetime.utcnow,
    description="Manifest creation time",
)

Dataset

Dataset

Bases: BaseModel

Represents an importable, versioned data release.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    frozen=True, extra="forbid", str_strip_whitespace=True
)

dataset_id class-attribute instance-attribute

dataset_id = Field(..., description='Stable dataset name')

version class-attribute instance-attribute

version = Field(..., description='Source release/version')

source_id class-attribute instance-attribute

source_id = Field(..., description='Originating source ID')

name class-attribute instance-attribute

name = Field(..., description='Display name')

description class-attribute instance-attribute

description = Field(
    ..., description="Contents and intended use"
)

license_id class-attribute instance-attribute

license_id = Field(
    None,
    description="SPDX identifier or documented custom license",
)

license_url class-attribute instance-attribute

license_url = Field(None, description='License text URL')

redistribution_status class-attribute instance-attribute

redistribution_status = Field(
    default=RedistributionStatus.UNKNOWN,
    description="Redistribution permission status",
)

retrieved_at class-attribute instance-attribute

retrieved_at = Field(
    None, description="Retrieval timestamp"
)

checksum_algorithm class-attribute instance-attribute

checksum_algorithm = Field(
    None, description="Checksum algorithm (e.g., sha256)"
)

checksum class-attribute instance-attribute

checksum = Field(
    None, description="Checksum of source artifact"
)

schema_version class-attribute instance-attribute

schema_version = Field(
    ..., description="Import schema version"
)

language class-attribute instance-attribute

language = Field(
    None, description="BCP 47 or documented language code"
)

metadata_json class-attribute instance-attribute

metadata_json = Field(
    None, description="Additional source metadata"
)

Source

Source

Bases: BaseModel

Represents the bibliographic or digital origin of a dataset.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    frozen=True, extra="forbid", str_strip_whitespace=True
)

source_id class-attribute instance-attribute

source_id = Field(..., description='Internal stable ID')

title class-attribute instance-attribute

title = Field(..., description='Source title')

creator class-attribute instance-attribute

creator = Field(
    None, description="Author, organization, or maintainer"
)

source_type class-attribute instance-attribute

source_type = Field(..., description='Type of source')

url class-attribute instance-attribute

url = Field(None, description='Source location')

persistent_id class-attribute instance-attribute

persistent_id = Field(
    None, description="DOI or other persistent identifier"
)

publisher class-attribute instance-attribute

publisher = Field(
    None, description="Publisher or issuing body"
)

publication_year class-attribute instance-attribute

publication_year = Field(
    None, description="Publication year"
)

notes class-attribute instance-attribute

notes = Field(
    None, description="Bibliographic or evaluation notes"
)

Providers

TanzilProvider

TanzilProvider

Bases: BaseModel

Provider for Tanzil Quran text and metadata.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    arbitrary_types_allowed=True, extra="forbid"
)

config class-attribute instance-attribute

config = Field(default_factory=TanzilConfig)

data_dir class-attribute instance-attribute

data_dir = Field(
    default_factory=lambda: (
        get_config().get_data_dir() / "tanzil"
    )
)

download

download(force=False)

Download Tanzil dataset files.

Parameters:

Name Type Description Default
force bool

Force re-download even if files exist

False

Returns:

Type Description
list[Path]

List of downloaded file paths

import_text

import_text(xml_path, edition_id='tanzil-uthmani-v1')

Import Tanzil Quran text from XML.

Parameters:

Name Type Description Default
xml_path Path

Path to quran.xml file

required
edition_id str

Edition identifier for the imported text

'tanzil-uthmani-v1'

Returns:

Type Description
DatasetManifest

DatasetManifest for the imported dataset

import_metadata

import_metadata(xml_path)

Import Tanzil metadata (juz, hizb, page, etc.).

Parameters:

Name Type Description Default
xml_path Path

Path to metadata.xml file

required

Returns:

Type Description
list[AyahMetadata]

List of AyahMetadata objects

import_into_database

import_into_database(
    xml_path,
    metadata_path=None,
    edition_id="tanzil-uthmani-v1",
    data_access=None,
)

Import Tanzil text and metadata directly into the database.

Parameters:

Name Type Description Default
xml_path Path

Path to quran.xml

required
metadata_path Path | None

Optional path to metadata.xml

None
edition_id str

Edition identifier

'tanzil-uthmani-v1'
data_access DataAccess | None

Optional DataAccess instance for testing

None

Returns:

Type Description
DatasetManifest

DatasetManifest for the imported dataset

validate_import

validate_import(manifest)

Validate an imported dataset.

Parameters:

Name Type Description Default
manifest DatasetManifest

Dataset manifest to validate

required

Raises:

Type Description
ValidationError

If validation fails

create_edition

create_edition(edition_id='tanzil-uthmani-v1')

Create a TextEdition for the imported Tanzil text.

QACProvider

QACProvider

Bases: BaseModel

Provider for QAC morphology and syntax annotations.

model_config class-attribute instance-attribute

model_config = ConfigDict(
    arbitrary_types_allowed=True, extra="forbid"
)

config class-attribute instance-attribute

config = Field(default_factory=QACConfig)

data_dir class-attribute instance-attribute

data_dir = Field(
    default_factory=lambda: (
        get_config().get_data_dir() / "qac"
    )
)

download

download(force=False)

Download QAC dataset files.

Parameters:

Name Type Description Default
force bool

Force re-download even if files exist

False

Returns:

Type Description
list[Path]

List of downloaded file paths

parse_morphology_xml

parse_morphology_xml(xml_path)

Parse QAC morphology XML file.

Parameters:

Name Type Description Default
xml_path Path

Path to morphology XML file

required

Returns:

Type Description
list[QACWordData]

List of QACWordData objects

import_morphology

import_morphology(
    xml_path,
    edition_id="tanzil-uthmani-v1",
    data_access=None,
)

Import QAC morphology annotations into the database.

Parameters:

Name Type Description Default
xml_path Path

Path to morphology XML file

required
edition_id str

Text edition ID that the tokens belong to

'tanzil-uthmani-v1'
data_access DataAccess | None

Optional DataAccess instance for testing

None

Returns:

Type Description
DatasetManifest

DatasetManifest for the imported dataset

validate_import

validate_import(manifest)

Validate an imported dataset.

Parameters:

Name Type Description Default
manifest DatasetManifest

Dataset manifest to validate

required

Raises:

Type Description
ValidationError

If validation fails

get_morphology_stats

get_morphology_stats(edition_id='tanzil-uthmani-v1')

Get statistics about imported QAC morphology data.

Parameters:

Name Type Description Default
edition_id str

Text edition ID

'tanzil-uthmani-v1'

Returns:

Type Description
dict[str, Any]

Dictionary with statistics

Exceptions

QuranKitError

QuranKitError

Bases: Exception

Base exception for QuranKit errors.

DatasetNotFoundError

DatasetNotFoundError

DatasetNotFoundError(dataset_id, message=None)

Bases: QuranKitError

Raised when a required dataset is not found or not installed.

dataset_id instance-attribute

dataset_id = dataset_id

InvalidReferenceError

InvalidReferenceError

InvalidReferenceError(reference, message=None)

Bases: QuranKitError

Raised when a Qur'anic reference (surah:ayah) is invalid.

reference instance-attribute

reference = reference

UnsupportedEditionError

UnsupportedEditionError

UnsupportedEditionError(edition_id, message=None)

Bases: QuranKitError

Raised when a text edition is not supported or not available.

edition_id instance-attribute

edition_id = edition_id

MissingAnnotationError

MissingAnnotationError

MissingAnnotationError(
    annotation_type, reference, message=None
)

Bases: QuranKitError

Raised when a requested annotation is not available for the current dataset.

annotation_type instance-attribute

annotation_type = annotation_type

reference instance-attribute

reference = reference

ValidationError

ValidationError

ValidationError(errors, message=None)

Bases: QuranKitError

Raised when data validation fails.

errors instance-attribute

errors = errors

ProvenanceError

ProvenanceError

ProvenanceError(dataset_id, message=None)

Bases: QuranKitError

Raised when provenance or licensing requirements are not met.

dataset_id instance-attribute

dataset_id = dataset_id

ChecksumMismatchError

ChecksumMismatchError

ChecksumMismatchError(file_path, expected, actual)

Bases: QuranKitError

Raised when a source file checksum does not match the expected value.

file_path instance-attribute

file_path = file_path

expected instance-attribute

expected = expected

actual instance-attribute

actual = actual

StorageError

StorageError

StorageError(message, operation=None)

Bases: QuranKitError

Raised when a storage operation fails.

operation instance-attribute

operation = operation