Metadata-Version: 2.5
Name: pranaam
Version: 0.7.0
Summary: Calibrated name-pattern estimates for aggregate research
Project-URL: Homepage, https://github.com/appeler/pranaam
Project-URL: Repository, https://github.com/appeler/pranaam
Project-URL: Bug Tracker, https://github.com/appeler/pranaam/issues
Author: Aaditya Dar
Author-email: Rajashekar Chintalapati <rajshekar.ch@gmail.com>, Gaurav Sood <gsood07@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: aggregate-research,calibration,deep-learning,english,hindi,hugging-face,machine-learning,name-classification,name-pattern,nlp,pytorch
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Natural Language :: Hindi
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.11
Requires-Dist: huggingface-hub>=1.0
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: rich>=13.0.0
Requires-Dist: safetensors>=0.5
Requires-Dist: torch>=2.7
Provides-Extra: streamlit
Requires-Dist: streamlit>=1.20; extra == 'streamlit'
Description-Content-Type: text/markdown

# Pranaam

[![CI](https://github.com/appeler/pranaam/actions/workflows/ci.yml/badge.svg)](https://github.com/appeler/pranaam/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/pranaam.svg)](https://pypi.org/project/pranaam/)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://appeler.github.io/pranaam/)
[![Downloads](https://static.pepy.tech/badge/pranaam)](https://pepy.tech/project/pranaam)

Pranaam returns calibrated estimates of whether an English- or Hindi-script
name follows patterns associated with Muslim or non-Muslim names in its
training data. It does not observe or establish a person's religion.

Pranaam is for validated aggregate research. **Do not use it to label
individuals, make consequential decisions, determine eligibility, target
people, or replace self-identified information.**

Model v3 uses compact byte-level PyTorch models. Unlike the v1 and v2
whole-word model, it retains local character order, represents every UTF-8
input without an unknown-word token, does not average padded embeddings into
each representation, and learns spelling fragments that generalize to unseen names.

The historical v1 model was trained on complete recorded name strings. Model
v2 migrated those same weights to newer serialization and runtime formats; it
was not a new training run. Both versions nevertheless averaged whole-word
embeddings, so accepting a full name did not preserve word order.

## Install

```bash
pip install pranaam
```

Python 3.11 or newer is required. The first prediction downloads small,
checksum-verified `safetensors` artifacts from an immutable revision of
[`gojiberries/pranaam`](https://huggingface.co/gojiberries/pranaam).

## Use

```python
from pranaam import pred_rel

result = pred_rel(
    ["Shah Rukh Khan", "Amitabh Bachchan", "محمد خان"],
    lang="eng",
)
print(result)
```

`pred_rel` accepts one name, a list of names, or a pandas Series. Use
`lang="hin"` for Devanagari names.

The returned columns are:

| Column | Meaning |
|---|---|
| `name` | Original input |
| `name_pattern_estimate` | `muslim-associated`, `not-muslim-associated`, or `uncertain` |
| `muslim_score` | Platt-calibrated score from 0 to 1; missing for unsupported scripts |
| `abstained` | Whether Pranaam declined to return an associated pattern |
| `abstention_reason` | `uncertain-score`, `unsupported-script`, or missing |
| `script_supported` | Whether every input letter is supported by the selected model |
| `model_version` | Model-family version |
| `model_revision` | Immutable Hugging Face commit used for inference |

The default confidence threshold is 0.8: scores strictly between 0.2 and 0.8
abstain. The English model supports Latin letters and the Hindi model supports
Devanagari letters. Selecting the wrong model therefore produces an explicit
unsupported-script abstention rather than a fabricated score.

The command-line interface exposes the same result:

```bash
pranaam --input "Shah Rukh Khan" --lang eng
```

## Evaluation

### Pranaam v0.6.0 audit

On all 92,897 directly labeled SEPRI household heads, v0.6.0 achieved:

- Accuracy: **96.43%**
- Muslim precision: **87.49%**
- Muslim recall: **73.74%**
- Muslim F1: **0.800**
- Recall on names not overlapping the translated land corpus: **69.10%**

The last measure uses exact normalized-name overlap. This external audit showed
why overall accuracy and the old random-row notebook results were insufficient:
the model missed more Muslim names when names were not represented in the land
corpus.

### Model v3

The released v2 and new v3 English pipelines were compared on the same
18,133-row SEPRI evaluation partition. Normalized names do not cross training,
validation, calibration, and evaluation partitions.

| Model | Accuracy | Muslim precision | Muslim recall | Muslim F1 | Brier | 10-bin ECE |
|---|---:|---:|---:|---:|---:|---:|
| v2 (Pranaam 0.6.0) | 96.51% | 87.75% | 74.14% | 0.804 | 0.0357 | 0.0395 |
| v3 | 97.46% | 90.29% | 82.49% | 0.862 | 0.0205 | 0.0052 |

With the default abstention rule, English v3 covers 96.54% of evaluation rows and is
98.54% accurate on retained estimates. Hindi v3 was evaluated on a disjoint
152,390-name grouped land-record test partition: Muslim precision 94.30%,
recall 93.05%, F1 0.937, and Brier score 0.0116. The Hindi result is an
in-source evaluation and should not be interpreted as national performance.

A paired audit also recalibrated v2 on v3's 13,665-row calibration partition.
Against that stronger baseline, v3 improved accuracy by 1.19 percentage points
(95% name-cluster bootstrap interval: 0.95 to 1.43), Muslim recall by 15.62
points (13.55 to 17.75), Muslim F1 by 0.086 (0.071 to 0.103), and Brier score by
0.0122 (0.0106 to 0.0139). Muslim precision was 2.04 points lower (-3.44 to
-0.67) because recalibrated v2 used a more conservative operating point. On
2,737 rows for which every word was outside v2's vocabulary, recall rose from
0% to 63.85%.

These results support v3 on the available SEPRI population, not universal
superiority. The v3 pipeline changes architecture, training data, and
calibration together, so this comparison does not identify the architecture's
effect alone. The evaluation partition was held out from parameter fitting and
calibration but was inspected during architecture development; it is therefore
developmental evidence rather than a pristine confirmatory test. See the
reproducible [paired audit](scripts/adhoc/compare_model_v2_v3.py) and its
[aggregate report](scripts/adhoc/v2_v3_comparison.json).

## Data and limitations

The models combine Bihar land-record names carrying caste/community-derived
silver labels with authorized SEPRI household-head data for the English model.
Conflicting labels for the same normalized land name are removed. SEPRI names
are assigned to deterministic, non-overlapping train, validation, calibration,
and test partitions.

Names are imperfect and culturally contingent proxies. Recorded caste,
household religion, transliteration, OCR, geography, gender, and time can all
introduce systematic error. Scores may be poorly calibrated outside the
evaluated populations. Validation against self-identified information at the
appropriate aggregate level remains the user's responsibility.

Raw personal names are not published with the package or model. Hugging Face
contains only weights, non-identifying training reports, metadata, and the
model card.

## Development

```bash
uv sync --all-groups
make ci
make docs
uv build
```

The reproducible v3 entry point is [`training/train_v3.py`](training/train_v3.py).
It reads authorized local source data and writes only weights and aggregate
reports.

## Authors

Rajashekar Chintalapati, Aaditya Dar, and Gaurav Sood.

## License

The package is released under the [MIT License](LICENSE). The responsible-use
requirements above describe the supported scope of the model.
