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
¶
edition_id
class-attribute
instance-attribute
¶
vocabulary
property
¶
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_normalization_profiles
property
¶
Get list of available normalization profiles.
load
classmethod
¶
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 ¶
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 |
ayah ¶
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 ¶
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 ¶
Get all ayah texts for a surah.
word_tokens ¶
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 ¶
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 ¶
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 ¶
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 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 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 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 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 |
get_normalization_profile ¶
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
¶
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
¶
cache_enabled
class-attribute
instance-attribute
¶
cache_dir
class-attribute
instance-attribute
¶
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
¶
Text Models¶
Surah¶
Surah ¶
Bases: BaseModel
Represents a canonical surah.
model_config
class-attribute
instance-attribute
¶
surah_number
class-attribute
instance-attribute
¶
name_arabic
class-attribute
instance-attribute
¶
name_transliteration
class-attribute
instance-attribute
¶
name_translation
class-attribute
instance-attribute
¶
ayah_count
class-attribute
instance-attribute
¶
metadata_source_id
class-attribute
instance-attribute
¶
Ayah¶
Ayah ¶
Bases: BaseModel
Represents a canonical ayah location, independent of text edition.
WordToken¶
WordToken ¶
Bases: BaseModel
Represents a token occurrence in a particular ayah text and tokenization.
model_config
class-attribute
instance-attribute
¶
token_id
class-attribute
instance-attribute
¶
surah_number
class-attribute
instance-attribute
¶
ayah_number
class-attribute
instance-attribute
¶
tokenization_id
class-attribute
instance-attribute
¶
token_index
class-attribute
instance-attribute
¶
surface_original
class-attribute
instance-attribute
¶
char_start
class-attribute
instance-attribute
¶
char_end
class-attribute
instance-attribute
¶
source_record_id
class-attribute
instance-attribute
¶
segmentation_notes
class-attribute
instance-attribute
¶
TextEdition¶
TextEdition ¶
Bases: BaseModel
Represents a text source, orthographic representation, or reading edition.
model_config
class-attribute
instance-attribute
¶
edition_id
class-attribute
instance-attribute
¶
dataset_id
class-attribute
instance-attribute
¶
script_type
class-attribute
instance-attribute
¶
reading_id
class-attribute
instance-attribute
¶
orthography
class-attribute
instance-attribute
¶
tokenization_id
class-attribute
instance-attribute
¶
is_default
class-attribute
instance-attribute
¶
notes
class-attribute
instance-attribute
¶
Vocabulary & Lexicon¶
QuranicVocabulary¶
QuranicVocabulary ¶
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'
|
get_occurrences_by_root ¶
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 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 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 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 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 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 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
¶
Unique identifier for this lexical resource (e.g., 'lane-lexicon', 'mufradat').
resource_title
abstractmethod
property
¶
Human-readable title of the lexical resource.
get_resource_metadata
abstractmethod
¶
Get the LexicalResource metadata for this adapter.
Returns:
| Type | Description |
|---|---|
LexicalResource
|
LexicalResource with title, author, edition, language, scope, etc. |
lookup_by_root
abstractmethod
¶
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
¶
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
¶
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 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 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 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 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 ¶
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 |
FileBasedDictionaryAdapter¶
FileBasedDictionaryAdapter ¶
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
|
DictionaryAdapterRegistry¶
DictionaryAdapterRegistry ¶
Registry for dictionary adapters.
Manages registration, discovery, and access to dictionary adapters.
register ¶
Register a dictionary adapter.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adapter
|
DictionaryAdapter
|
DictionaryAdapter instance to register |
required |
unregister ¶
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 |
lookup_root_across_resources ¶
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 ¶
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 |
Search¶
SearchEngine¶
SearchEngine ¶
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",
}
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_diacritic_insensitive ¶
Diacritic-insensitive search.
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.
normalize ¶
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
¶
profile_id
class-attribute
instance-attribute
¶
description
class-attribute
instance-attribute
¶
rules_json
class-attribute
instance-attribute
¶
implementation_version
class-attribute
instance-attribute
¶
created_at
class-attribute
instance-attribute
¶
Mutashabihat¶
MutashabihatEngine¶
MutashabihatEngine ¶
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'
|
find_exact_phrase ¶
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 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 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 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 (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(),
)
Dataset Management¶
DatasetRegistry¶
DatasetRegistry ¶
ManifestManager¶
ManifestManager ¶
Bases: BaseModel
Manager for creating and validating dataset manifests.
model_config
class-attribute
instance-attribute
¶
create_manifest ¶
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 |
create_tanzil_manifest
staticmethod
¶
Create a manifest for the Tanzil Quran text dataset.
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,
}
validate_surah_structure ¶
Validate surah structure against expected counts.
Provenance Models¶
DatasetManifest¶
DatasetManifest ¶
Dataset¶
Dataset ¶
Bases: BaseModel
Represents an importable, versioned data release.
model_config
class-attribute
instance-attribute
¶
dataset_id
class-attribute
instance-attribute
¶
version
class-attribute
instance-attribute
¶
source_id
class-attribute
instance-attribute
¶
description
class-attribute
instance-attribute
¶
license_id
class-attribute
instance-attribute
¶
license_url
class-attribute
instance-attribute
¶
redistribution_status
class-attribute
instance-attribute
¶
redistribution_status = Field(
default=RedistributionStatus.UNKNOWN,
description="Redistribution permission status",
)
retrieved_at
class-attribute
instance-attribute
¶
checksum_algorithm
class-attribute
instance-attribute
¶
checksum
class-attribute
instance-attribute
¶
schema_version
class-attribute
instance-attribute
¶
language
class-attribute
instance-attribute
¶
metadata_json
class-attribute
instance-attribute
¶
Source¶
Source ¶
Bases: BaseModel
Represents the bibliographic or digital origin of a dataset.
model_config
class-attribute
instance-attribute
¶
source_id
class-attribute
instance-attribute
¶
creator
class-attribute
instance-attribute
¶
source_type
class-attribute
instance-attribute
¶
persistent_id
class-attribute
instance-attribute
¶
publisher
class-attribute
instance-attribute
¶
publication_year
class-attribute
instance-attribute
¶
notes
class-attribute
instance-attribute
¶
Providers¶
TanzilProvider¶
TanzilProvider ¶
Bases: BaseModel
Provider for Tanzil Quran text and metadata.
model_config
class-attribute
instance-attribute
¶
data_dir
class-attribute
instance-attribute
¶
download ¶
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 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 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 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 a TextEdition for the imported Tanzil text.
QACProvider¶
QACProvider ¶
Bases: BaseModel
Provider for QAC morphology and syntax annotations.
model_config
class-attribute
instance-attribute
¶
data_dir
class-attribute
instance-attribute
¶
download ¶
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 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 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 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 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 ¶
InvalidReferenceError¶
InvalidReferenceError ¶
UnsupportedEditionError¶
UnsupportedEditionError ¶
MissingAnnotationError¶
MissingAnnotationError ¶
Bases: QuranKitError
Raised when a requested annotation is not available for the current dataset.
ValidationError¶
ValidationError ¶
ProvenanceError¶
ProvenanceError ¶
ChecksumMismatchError¶
ChecksumMismatchError ¶
Bases: QuranKitError
Raised when a source file checksum does not match the expected value.