Naamkaran documentation

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.

API reference

naamkaran.generate.generate_names(start_letter, end_letter=None, how_many=1, max_length=5, gender='M', temperature=0.5, model_fn='', vocab_fn='', max_attempts=None)

Generate name-like strings from the published model artifacts.

Parameters:

  • start_letter (str)

  • end_letter (str | None)

  • how_many (int)

  • max_length (int)

  • gender (str)

  • temperature (float)

  • model_fn (str)

  • vocab_fn (str)

  • max_attempts (int | None)

Return type:

list[str]

class naamkaran.generate.GenerateNames[source]

Generate synthetic name-like strings from the published model.

static generate(start_letter, end_letter=None, how_many=1, max_length=5, gender='M', temperature=0.5, model_fn='', vocab_fn='', max_attempts=None)[source]

Generate name-like strings from the published model artifacts.

Parameters:

  • start_letter (str)

  • end_letter (str | None)

  • how_many (int)

  • max_length (int)

  • gender (str)

  • temperature (float)

  • model_fn (str)

  • vocab_fn (str)

  • max_attempts (int | None)

Return type:

list[str]

class naamkaran.naam.Naamkaran[source]

Generates names for the given start_letter, end_letter.

static generate(start_letter, end_letter, how_many, max_length, gender, temperature, model_fn, vocab_fn, max_attempts=None)[source]

Generate name-like strings with bounded rejection sampling.

Parameters:

  • start_letter (str) – Required first character.

  • end_letter (str | None) – Optional required final character.

  • how_many (int) – Number of strings to return.

  • max_length (int) – Maximum characters per string.

  • gender (str) – Binary conditioning value from the trained model (F or M).

  • temperature (float) – Positive softmax sampling temperature.

  • model_fn (str) – Model artifact name or local override filename.

  • vocab_fn (str) – Vocabulary artifact name or local override filename.

  • max_attempts (int | None) – Maximum candidates to sample before failing. Defaults to 1,000 attempts per requested string.

Returns:

Generated name-like strings.

Raises:

  • ValueError – If a generation control is invalid or a requested character is outside the model vocabulary.

  • RuntimeError – If the requested number of strings cannot be produced within max_attempts.

Return type:

list[str]

class naamkaran.model.NameGenerator(input_size, gender_size, hidden_size, output_size, n_layers=1)[source]

A class representing the name generator model.

forward(input_seq, gender, hidden)[source]

Forward pass of the model.

init_hidden(batch_size, device)[source]

Initialize the hidden state of the LSTM.

To process arguments from the command line.

naamkaran.utils.get_args(argv, prog, description, epilog)[source]

Returns arguments from the command line.

Parameters:
Return type:

Namespace

Indices