# CLAUDE.md

## Project Overview

`corp-names` is a Python library for person and company name normalization. It strips titles/honorifics, suffixes/credentials, middle initials, and resolves nicknames to canonical forms. Contains 15,000+ person name entries and 1,000+ company legal suffixes across 200+ jurisdictions.

## 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` — Person name normalization pipeline
- `src/corp_names/company_normalizer.py` — Company name normalization pipeline
- `src/corp_names/models.py` — NormalizedName and NormalizedCompany Pydantic models
- `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/company_suffixes.json` — 1,000+ company legal suffixes with type and jurisdiction metadata
- `src/corp_names/data/company_suffixes.py` — Loads company_suffixes.json, exposes COMPANY_SUFFIXES, COMPANY_SUFFIX_SET
- `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 (normalize, normalize-company)
- `src/corp_names/scripts/build_nicknames.py` — Reference script for downloading/merging public nickname datasets
- `src/corp_names/scripts/build_company_suffixes.py` — Reference script for extracting company suffixes from cleanco + GLEIF ELF

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