Metadata-Version: 2.4
Name: nameprediction
Version: 0.1.0
Summary: Predict gender, country, and region from names using a byte-level transformer.
Author: Name Prediction Contributors
License-Expression: MIT
Keywords: names,gender,country,region,pytorch,inference
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: huggingface_hub<2,>=0.24
Requires-Dist: numpy<3,>=1.23
Requires-Dist: pandas<3,>=1.5
Requires-Dist: scikit-learn<2,>=1.2
Requires-Dist: torch<3,>=2.0
Requires-Dist: tqdm<5,>=4.64
Provides-Extra: build
Requires-Dist: build<2,>=1.2; extra == "build"
Requires-Dist: twine<7,>=5; extra == "build"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"

# nameprediction

`nameprediction` is a Python package for predicting gender, country, and region from personal names using a byte-level transformer.

The repository contains both:

- the reusable inference package under `src/nameprediction`
- the original training and local inference scripts used to produce checkpoints

## Install

For local development:

```bash
pip install -e .
```

For users after publication:

```bash
pip install nameprediction
```

## Quick Start

### 1. Download a model from Hugging Face

```python
from nameprediction import download_model

model_path = download_model(
   repo_id="romor/nameprediction",
   filename="name_gender_country_model_v14.pth",
)
```

The same flow is available from the CLI:

```bash
nameprediction-download-model --repo-id romor/nameprediction --filename name_gender_country_model_v14.pth
```

Direct model URLs still work for backward compatibility:

```python
model_path = download_model("https://example.com/name_gender_country_model_v14.pth")
```

### 2. Load the predictor

```python
from nameprediction import NamePredictor

predictor = NamePredictor.from_pretrained(model_path=model_path)
```

If you want the package to download from Hugging Face directly while loading, use:

```python
predictor = NamePredictor.from_pretrained(
   repo_id="YOUR_HF_USER_OR_ORG/nameprediction-model",
   filename="name_gender_country_model_v14.pth",
)
```

## Predict Single Names

```python
result = predictor.predict_name("Ada Lovelace")
print(result)
print(result.to_dict())
```

`predict_name` returns a `NamePrediction` dataclass with these fields:

- `name`
- `predicted_gender`
- `f_prob`
- `predicted_country`
- `predicted_country_confidence`
- `predicted_region`
- `predicted_region_confidence`

## Predict Lists Of Names

```python
results = predictor.predict_names([
   "Ada Lovelace",
   "Alan Turing",
   "Grace Hopper",
])
```

You can also use the convenience function:

```python
from nameprediction import predict_names

results = predict_names(
   ["Ada Lovelace", "Alan Turing"],
   repo_id="YOUR_HF_USER_OR_ORG/nameprediction-model",
   filename="name_gender_country_model_v14.pth",
)
```

## Predict DataFrames

```python
import pandas as pd
from nameprediction import predict_dataframe

df = pd.DataFrame({"name": ["Ada Lovelace", "Alan Turing"]})

predicted = predict_dataframe(
   df,
   repo_id="YOUR_HF_USER_OR_ORG/nameprediction-model",
   filename="name_gender_country_model_v14.pth",
   name_col="name",
   column_suffix="_v15",
)
```

This appends:

- `predicted_gender_v15`
- `f_prob_v15`
- `predicted_country_v15`
- `predicted_country_confidence_v15`
- `predicted_region_v15`
- `predicted_region_confidence_v15`

## Package Notes

- The package derives model architecture settings such as `embed_dim`, `num_heads`, `num_layers`, and `max_len` from the checkpoint when available.
- Label encoders are bundled with the package and validated against the checkpoint class counts at load time.
- If no default Hugging Face repo is configured, callers must pass `repo_id` explicitly or set the environment variable `NAMEPREDICTION_HF_REPO_ID`.

## Repository Layout

- `src/nameprediction`: package code intended for PyPI users
- `train.py`: original training script
- `inference.py`: legacy local inference helper script
- `config.yaml`: local training and inference configuration

## Publishing

Maintainer instructions for PyPI and Hugging Face are in `PUBLISHING.md`.
