Metadata-Version: 2.4
Name: nameprediction
Version: 0.1.1
Summary: Predict gender, country, and region from names using a byte-level transformer.
Author: Name Prediction Contributors
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/tomthe/nameprediction
Project-URL: Repository, https://github.com/tomthe/nameprediction
Project-URL: Issues, https://github.com/tomthe/nameprediction/issues
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
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()
```

The same flow is available from the CLI:

```bash
nameprediction-download-model
```

By default this downloads from `romor/nameprediction` and fetches `name_gender_country_model_v14.pth`.

You can override the source explicitly if needed:

```python
model_path = download_model(repo_id="romor/nameprediction")
```

Direct model URLs also work:

```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()
```

If you already downloaded the model and want to point at a specific local path, use:

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

## 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"])
```

## Predict DataFrames

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

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

predicted = predict_dataframe(
   df,
   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.
- The default published model source is `romor/nameprediction` with filename `name_gender_country_model_v14.pth`.
- You can override the default model source with `repo_id=...`, `filename=...`, or the environment variables `NAMEPREDICTION_HF_REPO_ID`, `NAMEPREDICTION_MODEL_FILENAME`, and `NAMEPREDICTION_MODEL_REVISION`.

## 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`.
