API Reference

This page contains the complete API documentation for pranaam.

Main Functions

Entry point module for pranaam CLI.

pranaam.pranaam.main(argv: list[str] | None = None) → int[source]

Main CLI entry point for religion prediction.

Parameters:: argv – Command line arguments, defaults to sys.argv[1:]
Returns:: Exit code (0 for success, non-zero for error)

Core Classes

Naam Class

Main prediction module for religion classification.

pranaam.naam.is_english(text: str) → bool[source]

Check if text contains only ASCII characters (English).

Parameters:: text – Input text to check
Returns:: True if text is ASCII-only (English), False otherwise

class pranaam.naam.Naam[source]

Bases: Base

Main class for religion prediction from names.

MODELFN: str = 'model'

weights_loaded: bool = False

model: Model | None = None

model_path: str | None = None

classes: list[str] = ['not-muslim', 'muslim']

cur_lang: str = 'eng'

model_name: str = 'eng_and_hindi_models_v1'

classmethod pred_rel(names: str | list[str] | Series, lang: str = 'eng', latest: bool = False) → DataFrame[source]

Predict religion based on name(s).

Parameters:

names – Single name string, list of names, or pandas Series of names
lang – Language of input (‘eng’ for English, ‘hin’ for Hindi)
latest – Whether to download latest model version

Returns:

name, pred_label, pred_prob_muslim

Return type:

DataFrame with columns

Raises:

ValueError – If invalid language specified
RuntimeError – If model loading fails or TensorFlow not available

Base Class

class pranaam.base.Base[source]

Bases: object

Base class for model data management and loading.

MODELFN: str | None = None

classmethod load_model_data(file_name: str, latest: bool = False) → str | None[source]

Load model data, downloading if necessary.

Parameters:

file_name – Name of the model file to load
latest – Whether to force download of latest version

Returns:

Path to the model directory, or None if loading failed

Utility Functions

Utilities for downloading and extracting model files.

pranaam.utils.download_file(url: str, target: str, file_name: str) → bool[source]

Download and extract a model file from the given URL.

Parameters:

url – Base URL (not currently used, uses REPO_BASE_URL instead)
target – Target directory for extraction
file_name – Name of the file to download

Returns:

True if download and extraction successful, False otherwise

Logging Configuration

Logging configuration for pranaam package.

pranaam.logging.get_logger(name: str | None = None) → Logger[source]

Get a configured logger instance.

Parameters:: name – Logger name, defaults to ‘pranaam’
Returns:: Configured logger instance

Function Parameters

pred_rel

pranaam.logging.pred_rel(input, lang='eng', latest=False)

Predict religion (Muslim/not-Muslim) from names.

Parameters:

input (str, list of str, or pandas.Series) – Name(s) to predict religion for
lang (str, optional) – Language of the input names (“eng” for English, “hin” for Hindi)
latest (bool, optional) – Whether to download the latest model if available

Returns:

DataFrame with columns [‘name’, ‘pred_label’, ‘pred_prob_muslim’]

Return type:

pandas.DataFrame

Raises:

ValueError – If invalid language is specified
FileNotFoundError – If model files cannot be found or downloaded

Examples:

# Single name
result = pred_rel("Shah Rukh Khan")

# Multiple names
result = pred_rel(["Shah Rukh Khan", "Amitabh Bachchan"], lang="eng")

# Hindi names
result = pred_rel(["शाहरुख खान"], lang="hin")

# Pandas Series
import pandas as pd
df = pd.DataFrame({"names": ["Shah Rukh Khan", "Amitabh Bachchan"]})
result = pred_rel(df["names"])

Return Values

The pred_rel function returns a pandas DataFrame with the following structure:

Output DataFrame Columns
Column	Type	Description
name	str	Original input name
pred_label	str	Predicted religion (‘muslim’ or ‘not-muslim’)
pred_prob_muslim	float	Probability score (0-100) that person is Muslim

Model Information

The package uses two TensorFlow models:

English Model: Trained on transliterated names from Hindi to English
Hindi Model: Trained on original Hindi names from Bihar Land Records

Both models:

Use SavedModel format (TensorFlow 2.14.1 compatible)
Achieve 98% out-of-sample accuracy
Are automatically downloaded and cached (306MB total)
Use character-level and n-gram features

Exception Handling

Common exceptions that may be raised:

exception pranaam.logging.ValueError: Raised when invalid parameters are provided (e.g., unsupported language).

exception pranaam.logging.FileNotFoundError: Raised when model files cannot be found or downloaded.

exception pranaam.logging.ImportError: Raised when required dependencies are missing.

Type Hints

The package includes comprehensive type annotations for all public functions:

from typing import Union, List
import pandas as pd

def pred_rel(
    input: Union[str, List[str], pd.Series],
    lang: str = "eng",
    latest: bool = False
) -> pd.DataFrame:
    ...

Constants

pranaam.logging.SUPPORTED_LANGUAGES: List of supported language codes: [‘eng’, ‘hin’]

pranaam.logging.MODEL_URLS: Dictionary mapping model names to their download URLs

pranaam.logging.DEFAULT_CACHE_DIR: Default directory for caching downloaded models