API Reference¶

This page contains the complete API documentation for pranaam.

Main Functions¶

… py:module:: pranaam.pranaam

Entry point module for pranaam CLI.

… py:function:: main(argv: list[str] | None = None) -> int

module:

pranaam.pranaam

Main CLI entry point for religion prediction.

rtype:

:sphinx_autodoc_typehints_type:\:py\:class\:\int``

param argv:

Command line arguments, defaults to sys.argv[1:]

returns:: Exit code (0 for success, non-zero for error)

Core Classes¶

Naam Class¶

… py:module:: pranaam.naam

Main prediction module for religion classification.

… py:function:: is_english(text: str) -> bool

module:

pranaam.naam

Check if text contains only ASCII characters (English).

rtype:

:sphinx_autodoc_typehints_type:\:py\:class\:\bool``

param text:

Input text to check

returns:: True if text is ASCII-only (English), False otherwise

… py:class:: Naam()

module:

pranaam.naam

Bases: :py:class:~pranaam.base.Base

Main class for religion prediction from names.

… py:attribute:: Naam.MODELFN

module:

pranaam.naam

type:

–is-rst–:py:class:str

value:

‘model’

… py:attribute:: Naam.weights_loaded

module:

pranaam.naam

type:

–is-rst–:py:class:bool

value:

False

… py:attribute:: Naam.model

module:

pranaam.naam

type:

–is-rst–:py:class:~keras.src.models.model.Model | :py:obj:None

value:

Base Class¶

… py:module:: pranaam.base

… py:class:: Base()

module:

pranaam.base

Bases: :py:class:object

Base class for model data management and loading.

… py:attribute:: Base.MODELFN

module:

pranaam.base

type:

–is-rst–:py:class:str | :py:obj:None

value:

None

… py:method:: Base.load_model_data(file_name: str, latest: bool = False) -> ~pathlib.Path | None

module:

pranaam.base

classmethod:

Load model data, downloading if necessary.

rtype:

:sphinx_autodoc_typehints_type:\:py\:class\:\~pathlib.Path` | :py:obj:`None``

param file_name:

Name of the model file to load

param latest:

Whether to force download of latest version

returns:

Utility Functions¶

… py:module:: pranaam.utils

Utilities for downloading and extracting model files.

… py:function:: download_file(url: str, target: str, file_name: str) -> bool

module:

pranaam.utils

Download and extract a model file from the given URL.

rtype:

:sphinx_autodoc_typehints_type:\:py\:class\:\bool``

param url:

Base URL (not currently used, uses REPO_BASE_URL instead)

param target:

Target directory for extraction

param file_name:

Name of the file to download

returns:: True if download and extraction successful, False otherwise

… py:exception:: SecurityError

module:

pranaam.utils

Bases: :py:class:Exception

Raised when a security violation is detected.

Logging Configuration¶

… py:module:: pranaam.logging

Logging configuration for pranaam package.

… py:function:: get_logger(name: str | None = None) -> ~logging.Logger

module:

pranaam.logging

Get a configured logger instance.

rtype:

:sphinx_autodoc_typehints_type:\:py\:class\:\~logging.Logger``

param name:

Logger name, defaults to ‘pranaam’

returns:: Configured logger instance

Function Parameters¶

pred_rel¶

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:

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 ValueError¶: Raised when invalid parameters are provided (e.g., unsupported language).

exception FileNotFoundError¶: Raised when model files cannot be found or downloaded.

exception 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¶

SUPPORTED_LANGUAGES¶: List of supported language codes: [‘eng’, ‘hin’]

MODEL_URLS¶: Dictionary mapping model names to their download URLs

DEFAULT_CACHE_DIR¶: Default directory for caching downloaded models