tocayo

tocayo (sust. m.): persona que tiene el mismo nombre que otra. El falso positivo clásico de la resolución de entidades.

Entity resolution para datos latinoamericanos. Las herramientas de record linkage (Splink, Dedupe, Zingg) asumen nombres anglosajones: un nombre, un apellido, un orden fijo. En Latinoamérica, José Luis Hernández García puede aparecer como HERNANDEZ GARCIA JOSE LUIS, J.L. Hernández o Jose Hdz Garcia — y ninguna librería existente lo maneja. Esto le cuesta millones en deduplicación fallida a cada banco, retailer y dependencia de gobierno de la región.

tocayo aporta las piezas que faltan:

• 🪪 Validadores estructurales de CURP y RFC que no solo validan: extraen los campos embebidos (fecha de nacimiento, sexo, entidad) como evidencia parcial para matching.
• 🧹 Normalización canónica de nombres en español: acentos (preservando la Ñ), abreviaturas de captura (Ma. → MARÍA, Hdz → HERNÁNDEZ), limpieza de ruido.
• 👤 Parser de nombres mexicanos (en construcción): dos apellidos, partículas compuestas (De la Garza), orden incierto (APELLIDOS NOMBRES vs Nombres Apellidos), con scores de confianza por campo.
• 🔗 Comparadores para Splink 4 (en construcción): comparación consciente de estructura, fonética del español, blocking rules probadas para nombres mexicanos.

Instalación

pip install tocayo

Uso

from tocayo import normalizar, validar_curp

normalizar("  ma. del Cármen   Hdz. ")
# 'MARIA DEL CARMEN HERNANDEZ'

info = validar_curp("GARJ900101HNLRRS01")
info.valida             # True
info.fecha_nacimiento   # datetime.date(1990, 1, 1)
info.sexo               # 'H'
info.entidad            # 'NL'

Estado

Alfa temprana (0.1.0a1). La API puede cambiar. Hoja de ruta pública en los issues.

Filosofía de diseño

1. Núcleo sin dependencias. Strings entran, dataclasses salen. Los adaptadores (pandas, Splink) son extras opcionales.
2. Los tests son la especificación. Cada comportamiento documentado tiene un test.
3. Estructura antes que magia. CURP y RFC tienen estructura verificable; los nombres mexicanos tienen gramática. La explotamos antes de recurrir a modelos.

Licencia

Apache 2.0

tocayo (English)

Entity resolution building blocks for Latin American data. Record linkage tools assume Anglo naming conventions — one given name, one surname, fixed order. Latin American names have two surnames, compound particles (De la Garza), and appear in wildly inconsistent formats across systems. tocayo provides Mexican name parsing, structural validators for national identifiers (CURP, RFC) that extract embedded fields as partial matching evidence, Spanish-aware normalization, and (soon) ready-to-use Splink 4 comparators and phonetic encoding for Spanish.

Early alpha. Star the repo to follow along.