Parsernaam¶

Parsernaam uses two character-level LSTM classifiers to label a single token as first or last, or a multi-token string as first_last or last_first. It is useful when name fields were not collected separately and simple word-order rules are inadequate.

These labels cannot represent every naming convention. Model scores are not calibrated guarantees, and errors and population imbalance in the training records can affect predictions. Do not use the output to infer ethnicity, citizenship, religion, gender, eligibility, or identity, or as the sole input to a consequential decision.

Installation¶

pip install parsernaam

Install the optional Gradio interface with:

pip install "parsernaam[web]"

Python API¶

import pandas as pd

from parsernaam import parse_names

names = pd.DataFrame(
    {
        "full_name": [
            "Jan",
            "Nicholas Turner",
            "Nichols Richard",
            "Kim Yeon",
        ]
    },
    index=pd.Index([10, 20, 30, 40], name="row_id"),
)

result = parse_names(names, names_col="full_name")
print(result[["full_name", "parsed_name"]])

parse_names returns a copy, preserves the input index and other columns, and adds parsed_name. Each value contains the original string, one of the four model labels, and its model score. Existing parsed_name values are replaced without merge suffixes.

Invalid or blank values receive the unknown label and a score of 0.0.

Command line¶

The command-line interface uses Parquet for typed input and output:

parse_names input.parquet --output output.parquet --names-col full_name

The name column defaults to name, and the output path defaults to output.parquet.

Model artifacts¶

The two PyTorch state dictionaries and non-null string vocabulary are published at gojiberries/parsernaam. Parsernaam downloads them from an immutable Hugging Face commit and verifies their SHA-256 hashes against the packaged model_manifest.json. Set PARSERNAAM_MODEL_DIR to use an explicitly managed local copy. The Hugging Face client honors its standard authentication configuration, including HF_TOKEN.

The repository documentation describes training records derived from Indian and United States voter registrations and cites the early 2022 Florida voter registration data at Harvard Dataverse. A complete row-level training manifest is not available, so use the models for exploration rather than population claims.

Development¶

uv sync --all-groups --all-extras
make ci
make docs

Authors¶

Rajashekar Chintalapati and Gaurav Sood

License¶

Parsernaam is released under the MIT License.

API reference¶

.. py:function:: parse_names(df, names_col=’name’) :module: parsernaam.parse

Parse names.

:param df: DataFrame with names. :param names_col: Column containing the name strings.

:returns: DataFrame with parsed names

.. py:class:: ParseNames() :module: parsernaam.parse

Main API class for parsing names using machine learning models.

This class provides the primary interface for name parsing functionality, extending the base Parsernaam class with predefined model file paths. Uses LSTM neural networks to classify names as first/last or determine positional ordering in multi-word names.

.. rubric:: Example

import pandas as pd from parsernaam.parse import ParseNames df = pd.DataFrame({‘name’: [‘John Smith’, ‘Kim Yeon’]}) results = ParseNames.parse(df) parsed = results[‘parsed_name’][0] parsed[‘name’], parsed[‘type’] (‘John Smith’, ‘first_last’) parsed[‘prob’] > 0.5 True

.. py:method:: ParseNames.parse(df, names_col=’name’) :module: parsernaam.parse :classmethod:

  Parse names.

  :param df: DataFrame with names.
  :param names_col: Column containing the name strings.

  :returns: DataFrame with parsed names

.. py:class:: Parsernaam() :module: parsernaam.naam

Parse names.

.. py:class:: LSTM(input_size, hidden_size, output_size, num_layers=1) :module: parsernaam.model

LSTM neural network for name classification.

A multi-layer LSTM network with embedding layer for character-level name classification. Supports both single name classification (first/last) and positional classification (first_last/last_first).

.. py:method:: LSTM.forward(input_tensor) :module: parsernaam.model

  Forward pass through the network.

  :param input_tensor: Character indices with shape ``[batch, sequence]``.

  :returns: Log-softmax probabilities for each class [batch_size, num_classes]

.. py:module:: parsernaam.utils

To process arguments from the command line.

.. py:function:: get_args(argv, description, epilog, default_out) :module: parsernaam.utils

Parse command line arguments for the parsernaam CLI tool.

:param argv: List of command line arguments :param description: Description text for the argument parser :param epilog: Example usage text shown after help :param default_out: Default output filename

:returns: Parsed command line arguments namespace