API reference

Search and resolve personal names in text corpora.

search_names.augment_names(input_file, prefix_column='seat', name_column='FirstName', output_file='augmented_clean_names.csv', prefix_file=None, nickname_file=None)

Write a copy of the input with deterministic prefix/nickname columns.

Parameters:

• input_file (str | Path)

• prefix_column (str)

• name_column (str)

• output_file (str | Path)

• prefix_file (str | Path | None)

• nickname_file (str | Path | None)

Return type:

int

search_names.clean_names(input_file, output_file='clean_names.csv', name_column='Name', keep_duplicates=False)

Parse names, preserve source columns, and write normalized CSV records.

Parameters:

• input_file (str | Path)

• output_file (str | Path)

• name_column (str)

• keep_duplicates (bool)

Return type:

list[dict[str, str]]

search_names.get_logger(name=None)

Get a logger instance.

Parameters:

name (str | None) – Optional logger name. If None, returns the main package logger.

Returns:

Logger instance

Return type:

Logger

search_names.merge_results(input_files, output_file='merged_search_results.csv')

Concatenate compatible CSV files and return the number of data rows.

Parameters:

• input_files (list[str | Path])

• output_file (str | Path)

Return type:

int

search_names.preprocess(input_file, patterns=('FirstName LastName', 'NickName LastName', 'Prefix LastName'), output_file='deduped_augmented_clean_names.csv', edit_length_thresholds=(), drop_patterns=None)

Build long-form patterns and remove ambiguous near-duplicates.

Parameters:

• input_file (str | Path)

• patterns (tuple[str, ...] | list[str])

• output_file (str | Path)

• edit_length_thresholds (tuple[int, ...] | list[int])

• drop_patterns (set[str] | list[str] | None)

Return type:

int

search_names.search_names(corpus_file, names, output_file='search_results.csv', *, text_column='text', input_columns=('uniqid', 'text'), max_results=20, fuzzy_rules=None, processes=4, chunk_size=1000)

Search every corpus row and write a stable, wide result table.

Parameters:

• corpus_file (str | Path)

• names (list[tuple[str, str]])

• output_file (str | Path)

• text_column (str)

• input_columns (tuple[str, ...])

• max_results (int)

• fuzzy_rules (list[tuple[int, int]] | None)

• processes (int)

• chunk_size (int)

Return type:

dict[str, int]

search_names.setup_logging(level='INFO', rich_tracebacks=True, show_time=True, show_path=False)

Set up logging with rich formatting.

Parameters:

• level (str) – Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

• rich_tracebacks (bool) – Whether to use rich formatted tracebacks

• show_time (bool) – Whether to show timestamps

• show_path (bool) – Whether to show file paths in logs

Returns:

Configured logger instance

Return type:

Logger

search_names.split_text_corpus(input_file, output_pattern='{basename}_{chunk_id:04d}.csv', chunk_size=1000)

Split a CSV file and return the number of chunks written.

Parameters:

• input_file (str | Path)

• output_pattern (str)

• chunk_size (int)

Return type:

int

Correct, deterministic exact and fuzzy name matching.

class search_names.engines.SearchEngine(names, fuzzy_rules=None)

Compile name patterns once and search many documents.

Parameters:

• names (list[tuple[str, str]])

• fuzzy_rules (list[tuple[int, int]] | None)

search(text, max_results=20)

Return up to max_results matches in stable pattern order.

Parameters:

• text (str)

• max_results (int)

Return type:

list[dict[str, Any]]

Enhanced name parser with support for both HumanName and parsernaam.

class search_names.enhanced_name_parser.ParsedName(original, first_name=None, middle_name=None, last_name=None, title=None, suffix=None, nickname=None, model_score=None, parser_used='humanname')

Unified parsed name representation.

Parameters:

• original (str)

• first_name (str | None)

• middle_name (str | None)

• last_name (str | None)

• title (str | None)

• suffix (str | None)

• nickname (str | None)

• model_score (float | None)

• parser_used (str)

full_name()

Get full name from components.

Return type:

str

to_dict()

Convert to dictionary.

Return type:

dict[str, Any]

class search_names.enhanced_name_parser.NameParser(parser_type='auto', batch_size=100, ml_threshold=0.8)

Enhanced name parser with multiple backend support.

Parameters:

• parser_type (Literal['auto', 'humanname', 'parsernaam'])

• batch_size (int)

• ml_threshold (float)

parse_with_humanname(name)

Parse name using HumanName.

Parameters:

name (str)

Return type:

ParsedName

parse_with_parsernaam(names)

Parse names using parsernaam (batch processing).

Parameters:

names (list[str])

Return type:

list[ParsedName]

is_indian_name(name)

Check if name appears to be Indian.

Parameters:

name (str)

Return type:

bool

parse(name: str) → ParsedName

parse(name: list[str]) → list[ParsedName]

Parse one or more names.

Parameters:

name (str | list[str]) – Single name string or list of names

Returns:

ParsedName or list of ParsedName objects

Return type:

ParsedName | list[ParsedName]

parse_dataframe(df, name_column='name', add_components=True)

Parse names in a DataFrame.

Parameters:

• df (DataFrame) – Input DataFrame

• name_column (str) – Column containing names

• add_components (bool) – Whether to add parsed components as new columns

Returns:

DataFrame with parsed names

Raises:

• TypeError – If the name column contains non-string values.

• ValueError – If the requested name column does not exist.

Return type:

DataFrame

search_names.enhanced_name_parser.parse_names(names, parser_type='auto', name_column='name')

Convenience function to parse names.

Parameters:

• names (str | list[str] | DataFrame) – Single name, list of names, or DataFrame

• parser_type (Literal['auto', 'humanname', 'parsernaam']) – “humanname”, “parsernaam”, or “auto”

• name_column (str) – Column name if input is DataFrame

Returns:

Parsed results in same format as input

Return type:

ParsedName | list[ParsedName] | DataFrame

search_names.enhanced_name_parser.compare_parsers(name)

Compare results from different parsers.

Parameters:

name (str) – Name to parse

Returns:

Dictionary with results from each parser

Return type:

dict[str, ParsedName]

Optional spaCy recognition and Sentence Transformer name linking.

exception search_names.nlp_engine.NLPEngineError

Exception raised for NLP engine related errors.

class search_names.nlp_engine.SpacyNER(model_name='en_core_web_sm', disable_components=None)

spaCy-based Named Entity Recognition for person detection.

Parameters:

• model_name (str)

• disable_components (list[str] | None)

extract_entities(text, entity_types=None)

Extract named entities from text.

Parameters:

• text (str) – Input text

• entity_types (set[str] | None) – Set of entity types to extract (default: {“PERSON”})

Returns:

List of entity mentions

Raises:

NLPEngineError – If the spaCy model is unavailable or processing fails.

Return type:

list[EntityMention]

extract_person_entities(text, min_length=2)

Extract person entities specifically.

Parameters:

• text (str) – Input text

• min_length (int) – Minimum length of person names to extract

Returns:

List of person entity mentions

Raises:

ValueError – If min_length is less than one.

Return type:

list[EntityMention]

is_person_context(text, start, end, context_window=50)

Check if a mention appears in a person context.

Parameters:

• text (str) – Full text

• start (int) – Start position of mention

• end (int) – End position of mention

• context_window (int) – Characters before/after to check

Returns:

True if mention appears in person context

Return type:

bool

class search_names.nlp_engine.SemanticSimilarity(model_name='sentence-transformers/all-MiniLM-L6-v2', revision=None, local_files_only=False)

Semantic similarity matching using sentence transformers.

Parameters:

• model_name (str)

• revision (str | None)

• local_files_only (bool)

compute_similarity(text1, text2)

Compute semantic similarity between two texts.

Parameters:

• text1 (str) – First text

• text2 (str) – Second text

Returns:

Cosine similarity score between -1 and 1.

Raises:

NLPEngineError – If the model is unavailable or encoding fails.

Return type:

float

find_similar_names(target_name, candidate_names, threshold=0.8)

Find names similar to target name.

Parameters:

• target_name (str) – Name to match against

• candidate_names (list[str]) – List of candidate names

• threshold (float) – Minimum similarity threshold

Returns:

List of (name, similarity_score) tuples above threshold

Raises:

• NLPEngineError – If the sentence-transformer model is unavailable.

• ValueError – If threshold is outside the valid cosine range.

Return type:

list[tuple[str, float]]

class search_names.nlp_engine.EntityLinker(knowledge_base, semantic_model=None)

Simple entity linking using string matching and semantic similarity.

Parameters:

• knowledge_base (dict[str, dict[str, Any]])

• semantic_model (SemanticSimilarity | None)

link_entity(mention, similarity_threshold=0.8)

Link entity mention to knowledge base.

Parameters:

• mention (EntityMention) – Entity mention to link

• similarity_threshold (float) – Threshold for semantic similarity matching

Returns:

Entity linking result

Raises:

ValueError – If similarity_threshold is outside the cosine range.

Return type:

EntityLinkingResult

class search_names.nlp_engine.NLPEngine(spacy_model='en_core_web_sm', similarity_model='sentence-transformers/all-MiniLM-L6-v2', similarity_revision=None, knowledge_base=None, enable_ner=True, enable_similarity=False, enable_linking=False)

Main NLP engine combining all components.

Parameters:

• spacy_model (str)

• similarity_model (str)

• similarity_revision (str | None)

• knowledge_base (dict[str, dict[str, Any]] | None)

• enable_ner (bool)

• enable_similarity (bool)

• enable_linking (bool)

process_text(text, extract_entities=True, link_entities=False, min_name_length=2, similarity_threshold=0.8)

Process text with all available NLP components.

Parameters:

• text (str) – Input text

• extract_entities (bool) – Whether to extract entities

• link_entities (bool) – Whether to link entities

• min_name_length (int) – Minimum name length for entity extraction

• similarity_threshold (float) – Threshold for entity linking

Returns:

Dictionary with processing results

Raises:

• NLPEngineError – If a requested component was not enabled.

• ValueError – If linking is requested without entity extraction.

Return type:

dict[str, Any]

enhance_name_search(search_names, text_corpus, context_window=100)

Enhance name search with NLP context analysis.

Parameters:

• search_names (list[str]) – Names to search for

• text_corpus (str) – Text to search in

• context_window (int) – Context window around matches

Returns:

Enhanced search results with context analysis

Raises:

ValueError – If a name is blank or context_window is negative.

Return type:

list[dict[str, Any]]

Validated result types used by the NLP components.

class search_names.models.EntityMention(*, text, label, start, end)

A named-entity span returned by spaCy.

Parameters:

• text (str)

• label (str)

• start (int)

• end (int)

validate_positions()

Require a nonempty, forward character span.

Return type:

EntityMention

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class search_names.models.EntityLinkingResult(*, mention, linked_entity_id=None, linked_entity_name=None, match_method=None, score=None, alternative_entities=<factory>)

The canonical entity selected for one mention, if any.

Parameters:

• mention (EntityMention)

• linked_entity_id (str | None)

• linked_entity_name (str | None)

• match_method (Literal['exact', 'normalized', 'semantic'] | None)

• score (float | None)

• alternative_entities (list[dict[str, Any]])

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Four-stage workflow for name processing.

This module provides a systematic 4-step pipeline for processing names:

Step 1: Clean - Parse and standardize raw names Step 2: Augment - Add supplementary data (nicknames, prefixes) Step 3: Preprocess - Create search patterns and deduplicate Step 4: Search - Execute deterministic exact or fuzzy search

Each step builds on the previous one, creating a complete name processing workflow.

search_names.pipeline.augment_names(input_file, prefix_column='seat', name_column='FirstName', output_file='augmented_clean_names.csv', prefix_file=None, nickname_file=None)

Write a copy of the input with deterministic prefix/nickname columns.

Parameters:

• input_file (str | Path)

• prefix_column (str)

• name_column (str)

• output_file (str | Path)

• prefix_file (str | Path | None)

• nickname_file (str | Path | None)

Return type:

int

search_names.pipeline.clean_names(input_file, output_file='clean_names.csv', name_column='Name', keep_duplicates=False)

Parse names, preserve source columns, and write normalized CSV records.

Parameters:

• input_file (str | Path)

• output_file (str | Path)

• name_column (str)

• keep_duplicates (bool)

Return type:

list[dict[str, str]]

search_names.pipeline.preprocess_names(input_file, patterns=('FirstName LastName', 'NickName LastName', 'Prefix LastName'), output_file='deduped_augmented_clean_names.csv', edit_length_thresholds=(), drop_patterns=None)

Build long-form patterns and remove ambiguous near-duplicates.

Parameters:

• input_file (str | Path)

• patterns (tuple[str, ...] | list[str])

• output_file (str | Path)

• edit_length_thresholds (tuple[int, ...] | list[int])

• drop_patterns (set[str] | list[str] | None)

Return type:

int

search_names.pipeline.search_names(corpus_file, names, output_file='search_results.csv', *, text_column='text', input_columns=('uniqid', 'text'), max_results=20, fuzzy_rules=None, processes=4, chunk_size=1000)

Search every corpus row and write a stable, wide result table.

Parameters:

• corpus_file (str | Path)

• names (list[tuple[str, str]])

• output_file (str | Path)

• text_column (str)

• input_columns (tuple[str, ...])

• max_results (int)

• fuzzy_rules (list[tuple[int, int]] | None)

• processes (int)

• chunk_size (int)

Return type:

dict[str, int]