naamkaran 0.3.0

naamkaran: generative model for names

Naamkaran is a character-level LSTM that generates synthetic name-like strings. It was trained on names from early 2022 Florida voter registration data.

Use the outputs for demonstrations, testing, and exploratory applications. They are not verified personal names or representative population samples. The model can reproduce spelling patterns, imbalance, errors, and social biases in the training data. Its binary gender conditioning does not represent the full range of gender identities. Do not use its outputs to infer identity, ethnicity, citizenship, eligibility, or another sensitive attribute.

Gradio App.

Naamkaran on HF

Installation

Naamkaran can be installed from PyPI using pip:

pip install naamkaran

For development with all tools:

uv sync --all-groups --all-extras

For web applications (Gradio/Flask):

pip install "naamkaran[web]"

General API

The general API for naamkaran is as follows:

# naamkaran is the package name
from naamkaran.generate import generate_names

# generate_names is the function that generates names

positional arguments:
  start_letter  The letter to start the name with (default: "a")

optional arguments:
    end_letter  The letter to end the name with (default: None)
    how_many    The number of names to generate (default: 1)
    max_length  The maximum length of the name (default: 5)
    gender      The gender of the name (default: "M")
    temperature The temperature of the model (default: 0.5)
    max_attempts Maximum candidates to sample before failing

# generate 10 names starting with 'A'
generate_names('A', how_many=10)
['Allis', 'Alber', 'Aderi', 'Albri', 'Alawa',
'Arver', 'Agnee', 'Anous', 'Areyd', 'Adria']


# generate 10 names starting with 'B' and ending with 'n'
generate_names('B', end_letter='n', how_many=10)
['Brian', 'Beran', 'Burin', 'Bahan', 'Balin',
'Bounn', 'Baran', 'Balan', 'Belin', 'Brion']

# generate 5 names starting with 'B' and ending with 'n' with a maximum length of 4
generate_names('B', end_letter='n', how_many=5, max_length=4)
['Bern', 'Bren', 'Bran', 'Bonn', 'Brun']

# generate 10 names starting with 'D' and ending with 'd' with a maximum length of 6
# and a temperature of 0.5
generate_names('D', end_letter='d', how_many=5, max_length=6, temperature=0.5)
['Derayd', 'Davind', 'Deland', 'Denild', 'David']

# generate 10 female names starting with 'A' and ending with 'e' with a maximum length of 5
# and a temperature of 0.5
generate_names('A', end_letter='e', how_many=10, max_length=5, gender="F", temperature=0.5)
['Annhe', 'Annie', 'Altre', 'Anne', 'Ashle',
'Arine', 'Anice', 'Andre', 'Anale', 'Allie']

Data

The model is trained on names from the Florida Voter Registration Data from early 2022. The data are available on the Harvard Dataverse

The trained model and vocabulary are published at gojiberries/naamkaran. Naamkaran downloads the artifacts from an immutable Hugging Face commit on first use and verifies their SHA-256 hashes against the packaged model_manifest.json. Set NAAMKARAN_MODEL_DIR to use an explicitly managed local copy. The Hugging Face client honors its standard authentication configuration, including HF_TOKEN.

Authors

Rajashekar Chintalapati and Gaurav Sood

Contributing

Contributions are welcome. Please open an issue if you find a bug or have a feature request.

License

The package is released under the MIT License.