Metadata-Version: 2.5
Name: pranaam
Version: 0.6.0
Summary: Predict religion from names
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: deep-learning,english,hindi,hugging-face,machine-learning,name,name-classification,nlp,predict,pytorch,religion
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: predict religion from name

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

Pranaam uses the Bihar Land Records data, including 41.87 million plot records
for 12.13 million individuals or accounts across 35,626 villages, to build
machine learning models from names. The package currently exposes binary
religion classification. The final training dataset has around 4 million unique records. To
learn how to transform the data and the models underlying the package,
check the
[notebooks](https://github.com/appeler/pranaam/tree/main/).

The production PyTorch weights, vocabularies, conversion hashes, and model card
are published in the
[gojiberries/pranaam Hugging Face repository](https://huggingface.co/gojiberries/pranaam).

The first function we are releasing with the package is
pred_rel, which predicts religion based on the name
(currently only muslim or not). (For
context, nearly 95% of India\'s population are Hindu or Muslim, with
Sikhs, Buddhists, Christians, and other groups making up the rest.) The
OOS accuracy assessed on unseen names is nearly 98% for both
[Hindi](https://github.com/appeler/pranaam/blob/main/model_training/05_train_hindi.ipynb)
and
[English](https://github.com/appeler/pranaam/blob/main/model_training/04_train_english.ipynb)
models.

Our training data is in Hindi. To build models that classify names
provided in English, we used the
[indicate](https://github.com/in-rolls/indicate) package to
transliterate our training data to English.

We are releasing this software in the hope that it enables activists and
researchers

1)  Highlight biases
2)  Fight biases
3)  Prevent biases (regress out some of these biases in models built on
    natural language corpus with person names).

## Install

We strongly recommend installing pranaam inside a Python virtual environment. (see [venv documentation](https://docs.python.org/3/library/venv.html#creating-virtual-environments))

### Standard Installation

```bash
pip install pranaam
```

### Requirements

- Python 3.11 or newer
- PyTorch, safetensors, and Hugging Face Hub support are installed automatically

The first prediction downloads the requested language model from an immutable
Hugging Face revision and verifies every file against a pinned SHA-256 digest.

## General API

1.  pranaam.pred_rel takes a list of Hindi/English names and predicts
    whether the person is Muslim or not.

## Examples

By using names in English :

    from pranaam import pranaam
    names = ["Shah Rukh Khan", "Amitabh Bachchan"]
    result = pranaam.pred_rel(names)
    print(result)

output -:

    name  pred_label  pred_prob_muslim
    0    Shah Rukh Khan      muslim              95.0
    1  Amitabh Bachchan  not-muslim              10.0

By using names in Hindi :

    from pranaam import pranaam
    names = ["शाहरुख खान", "अमिताभ बच्चन"]
    result = pranaam.pred_rel(names, lang="hin")
    print(result)

output -:

    name  pred_label  pred_prob_muslim
    0    शाहरुख खान      muslim              97.0
    1  अमिताभ बच्चन  not-muslim               5.0

## Functions

We expose one function, which takes Hindi/English text (name) and predicts a
binary religion label.

- **pranaam.pred_rel(input)**
  - What it does:
    - predicts religion based on hindi/english text (name)
  - Output
    - Returns pandas with name and label (muslim/not-muslim)

## Authors

Rajashekar Chintalapati, Aaditya Dar, and Gaurav Sood


## 🔗 Adjacent Repositories

- [appeler/naampy](https://github.com/appeler/naampy) — Infer Sociodemographic Characteristics from Names Using Indian Electoral Rolls
- [appeler/namesexdata](https://github.com/appeler/namesexdata) — Data on international first names and sex of people with that name
- [appeler/parsernaam](https://github.com/appeler/parsernaam) — AI name parsing. Predict first or last name using a DL model.
- [appeler/graphic_names](https://github.com/appeler/graphic_names) — Infer the gender of person with a particular first name using Google image search and Clarifai
- [appeler/ethnicolr2](https://github.com/appeler/ethnicolr2) — Ethnicolr implementation with new models in pytorch
## Contributor Code of Conduct

The project welcomes contributions from everyone! It depends on it. To
maintain this welcoming atmosphere and to collaborate in a fun and
productive way, we expect contributors to the project to abide by the
[Contributor Code of
Conduct](http://contributor-covenant.org/version/1/0/0/).

## License

The package is released under the [MIT
License](https://opensource.org/licenses/MIT).
