API Reference

This page contains the complete API documentation for pranaam.

Main Functions

Entry point for Pranaam name-pattern estimation.

pranaam.pranaam.main(argv=None)

Run name-pattern estimation from the command line.

Parameters:

argv (list[str] | None) – Command line arguments, defaults to sys.argv[1:]

Returns:

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

Return type:

int

Raises:

SystemExit – For help and argument parsing errors

Core Classes

Naam Class

Public interface for calibrated name-pattern estimation.

pranaam.naam.is_english(text)

Return whether text contains only ASCII characters.

Parameters:

text (str)

Return type:

bool

class pranaam.naam.Naam

Bases: Base

Estimate binary name patterns for English or Hindi names.

classmethod estimate_muslim_name_pattern(data, name_column=None, *, lang='eng', prior=None, uncertainty_level=None, mc_iterations=64, refresh_pinned=False)

Estimate how far a name follows Muslim-associated naming patterns.

The score is a calibrated probability on a 0 to 1 scale. Pranaam does not return a label: for a binary target the score carries the whole distribution, and the cutoff that would turn it into a decision depends on the caller’s costs, not on this package.

Parameters:

• data (DataFrame | Series | list[str | None] | str) – DataFrame of inputs, or a name string, list, or Series.

• name_column (str | None) – Column holding names for DataFrame input.

• lang (Literal['eng', 'hin']) – eng for the English model or hin for the Hindi model.

• prior (float | None) – Share of the target population expected to carry Muslim-associated names. When given, scores are reweighted from the model’s reference base rate to this one.

• uncertainty_level (float | None) – Central interval to report from Monte Carlo dropout, such as 0.9. Omit for point estimates only.

• mc_iterations (int) – Dropout samples drawn when uncertainty_level is requested.

• refresh_pinned (bool) – Reload and verify the immutable model artifacts. Hub artifacts are redownloaded. Files under PRANAAM_MODEL_DIR are reread without network access.

Returns:

A copy of the input with the calibrated score, the contract’s metadata columns, and, when requested, Monte Carlo summaries.

Raises:

• ValueError – If an argument is outside its documented domain.

• RuntimeError – If model loading or inference fails.

Return type:

DataFrame

Base Class

Shared access to versioned model artifacts.

class pranaam.base.Base

Bases: object

Base class for loading files from the pinned model release.

classmethod load_model_data(file_name, refresh_pinned=False)

Return a verified path, optionally refreshing its pinned source.

Parameters:

• file_name (str)

• refresh_pinned (bool)

Return type:

Path

Utility Functions

Verified access to the immutable model release on Hugging Face.

exception pranaam.utils.ModelDownloadError

Bases: RuntimeError

Raised when a required model artifact cannot be obtained.

exception pranaam.utils.ModelIntegrityError

Bases: RuntimeError

Raised when model bytes do not match the pinned release manifest.

pranaam.utils.file_sha256(path)

Return the SHA-256 digest of a file without loading it into memory.

Parameters:

path (Path)

Return type:

str

pranaam.utils.download_model_file(filename, *, force_download=False, local_files_only=False)

Resolve and verify one file from the pinned Hugging Face revision.

Set PRANAAM_MODEL_DIR to a directory with the published repository layout to run from an explicitly managed local mirror. force_download redownloads Hub files, but local mirror files are always read in place.

Parameters:

• filename (str)

• force_download (bool)

• local_files_only (bool)

Return type:

Path

Logging Configuration

Logging configuration for pranaam package.

pranaam.logging.get_logger(name=None)

Get a configured logger instance.

Parameters:

name (str | None) – Logger name, defaults to ‘pranaam’

Returns:

Configured logger instance

Return type:

logging.Logger