Metadata-Version: 2.4
Name: tocayo
Version: 0.1.0a1
Summary: Entity resolution para nombres e identificadores latinoamericanos: parser de nombres mexicanos, validadores de CURP/RFC y comparadores para Splink.
Project-URL: Homepage, https://github.com/tocayo-labs/tocayo
Project-URL: Repository, https://github.com/tocayo-labs/tocayo
Project-URL: Issues, https://github.com/tocayo-labs/tocayo/issues
Author: Miguel Alejandro Salas Reyna
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: curp,deduplication,entity-resolution,latam,mexico,nombres,record-linkage,rfc,splink
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: Spanish
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: splink
Requires-Dist: splink>=4.0; extra == 'splink'
Description-Content-Type: text/markdown

# 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

```bash
pip install tocayo
```

## Uso

```python
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](https://github.com/tocayo-labs/tocayo/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](LICENSE)

---

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