# CLAUDE.md

## Project Overview

`corp-names` is a Python library for person name normalization. It strips titles/honorifics, suffixes/credentials, middle initials, and resolves nicknames to canonical forms. Contains 15,000+ name entries covering English, international, CJK, Arabic, Japanese, and Korean names.

## Commands

```bash
uv sync                  # Install dependencies
uv run pytest tests/     # Run tests
uv build                 # Build package
uv publish               # Publish to PyPI
```

## Architecture

- `src/corp_names/normalizer.py` — Core normalization pipeline
- `src/corp_names/models.py` — NormalizedName Pydantic model
- `src/corp_names/data/nicknames.json` — 15,000+ name entries (nicknames + standalone canonicals) with category metadata
- `src/corp_names/data/nicknames.py` — Loads nicknames.json, exposes NICKNAME_TO_CANONICAL, CANONICAL_NAMES, ALL_KNOWN_NAMES
- `src/corp_names/data/prefixes.py` — ~150 title/honorific strings
- `src/corp_names/data/suffixes.py` — ~600 credential/generational strings
- `src/corp_names/commands/` — Click CLI
- `src/corp_names/scripts/build_nicknames.py` — Reference script for downloading/merging public nickname datasets

## Key Design Decisions

- Name data stored in `nicknames.json` with category tracking: `common`, `international`, `archaic` for nickname mappings; `canonical`, `cjk`, `japanese`, `korean`, `arabic`, `french_compound` for standalone names.
- Nicknames mapping is curated manually for accuracy. Automated merging of public datasets produces too many false positives due to transitive chaining and bidirectional entries.
- Only short/informal names are resolved (bob → robert). Established formal names (john, james, william) are never resolved to longer variants.
- International variants resolve to English canonical forms (guillaume → william, giuseppe → joseph).
- Prefix/suffix data extracted from python-nameparser (MIT license).
