API Reference

This section provides detailed documentation of the parsernaam API.

Core Classes

Public API and CLI entry point for parsing names.

class parsernaam.parse.ParseNames

Bases: Parsernaam

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.

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

MODEL_FN = 'models/parsernaam.pt'

MODEL_POS_FN = 'models/parsernaam_pos.pt'

VOCAB_FN = 'models/parsernaam.joblib'

classmethod parse(df)

Parse names.

Parameters:

df (DataFrame) – DataFrame with names

Returns:

DataFrame with parsed names

Return type:

DataFrame

parsernaam.parse.parse_names(df)

Parse names.

Parameters:

df (DataFrame) – DataFrame with names

Returns:

DataFrame with parsed names

Return type:

DataFrame

parsernaam.parse.main()

Main method to parse names.

Returns:

Exit code (None for success)

Return type:

int | None

Core ML inference pipeline for parsing names.

class parsernaam.naam.ParsedNameResult

Bases: TypedDict

Structure for parsed name result.

name: str

type: str

prob: float

class parsernaam.naam.VocabCache

Bases: TypedDict

Structure for vocabulary cache.

vocab: list[str]

all_letters: str

n_letters: int

class parsernaam.naam.Parsernaam

Bases: object

Parse names.

Model Architecture

LSTM model architecture used for name classification.

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

Bases: Module

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).

Parameters:

• input_size (int)

• hidden_size (int)

• output_size (int)

• num_layers (int)

forward(input)

Forward pass through the network.

Parameters:

input (Tensor) – Input tensor of character indices [batch_size, sequence_length]

Returns:

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

Return type:

Tensor

Utilities

To process arguments from the command line.

parsernaam.utils.get_args(argv, description, epilog, default_out)

Parse command line arguments for the parsernaam CLI tool.

Parameters:

• argv (list[str]) – List of command line arguments

• description (str) – Description text for the argument parser

• epilog (str) – Example usage text shown after help

• default_out (str) – Default output filename

Returns:

Parsed command line arguments namespace

Return type:

Namespace

Example

>>> from parsernaam.utils import get_args
>>> args = get_args(['input.csv', '-o', 'output.csv', '-n', 'name'],
...                 'Parse names', 'Example usage', 'out.csv')
>>> args.input
'input.csv'

Configuration

Configuration constants for parsernaam.

This module contains all the hardcoded constants used throughout the parsernaam package, including model parameters, file paths, and classification categories.

class parsernaam.config.ModelConfig

Bases: object

Model configuration constants.

Contains all the hyperparameters and settings used by the LSTM models for name parsing, including architecture parameters and file locations.

HIDDEN_SIZE

Dimension of LSTM hidden layers

Type:

Final[int]

NUM_LAYERS

Number of LSTM layers in the model

Type:

Final[int]

SEQUENCE_LENGTH

Maximum length of input name sequences

Type:

Final[int]

CATEGORIES_SINGLE

Classification labels for single names

Type:

Final[list[str]]

CATEGORIES_POSITIONAL

Classification labels for multi-word names

Type:

Final[list[str]]

MODEL_FILES

Paths to model and vocabulary files

Type:

Final[dict[str, str]]

HIDDEN_SIZE: Final[int] = 256

NUM_LAYERS: Final[int] = 2

SEQUENCE_LENGTH: Final[int] = 30

CATEGORIES_SINGLE: Final[list[str]] = ['last', 'first']

CATEGORIES_POSITIONAL: Final[list[str]] = ['last_first', 'first_last']

MODEL_FILES: Final[dict[str, str]] = {'positional': 'models/parsernaam_pos.pt', 'single': 'models/parsernaam.pt', 'vocab': 'models/parsernaam.joblib'}

Package Information

ParserNaam is a package for parsing names.

class parsernaam.ParseNames

Bases: Parsernaam

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.

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

MODEL_FN = 'models/parsernaam.pt'

MODEL_POS_FN = 'models/parsernaam_pos.pt'

VOCAB_FN = 'models/parsernaam.joblib'

classmethod parse(df)

Parse names.

Parameters:

df (DataFrame) – DataFrame with names

Returns:

DataFrame with parsed names

Return type:

DataFrame

Usage Examples

Basic parsing:

from parsernaam.parse import ParseNames
import pandas as pd

df = pd.DataFrame({"name": ["John Smith", "Jane Doe"]})
results = ParseNames.parse(df)

Model architecture:

from parsernaam.model import LSTM

# Model automatically loaded and cached
model = LSTM(input_size=100, hidden_size=128, output_size=2, num_layers=1)

Command line utilities:

from parsernaam.utils import get_args

args = get_args(
    ["input.csv", "-o", "output.csv", "-n", "name"],
    "Parse names",
    "Example usage",
    "out.csv",
)