croblade47/ability

Ability — Resolución de Entidades

Ability convierte registros desordenados y superpuestos en un conjunto limpio y trazable de entidades. Funciona en cinco etapas y nunca destruye los datos originales: cada registro fusionado mantiene enlaces a los originales de los que proviene.

La vinculación de registros es la matemática de coincidencia (¿coincide el registro A con el B?). La resolución de entidades es todo el trabajo: coincidir, agrupar coincidencias en entidades, puntuar la confianza y mantener la procedencia. Haz todo el trabajo.

Antes de empezar: la verificación de alineación

Las solicitudes confusas son normales. Lee los errores tipográficos y las abreviaturas para entender la intención y nunca comentes la ortografía. Antes del trabajo real, indica tres líneas cortas para que el usuario pueda corregir el rumbo sin esfuerzo:

DIJO:     <lo que el usuario pidió literalmente>
INFERIDO: <el problema real a resolver>
ASUMIDO:  <la suposición principal que estás haciendo — haz como máximo una pregunta si estás realmente bloqueado>

Omite esto para preguntas rápidas; úsalo cuando estés a punto de procesar datos o diseñar un pipeline.

El pipeline de 5 etapas

1. Perfilado

Examina cada campo antes de hacer ninguna coincidencia. Informa por campo: tasa de nulos, recuento de valores distintos, valores principales, patrones de formato y problemas de codificación (UTF-8 vs Latin-1). El perfilado te indica qué campos son lo suficientemente fiables para coincidir y qué valores son tan comunes (p. ej., «García», «Calle Mayor 123») que su concordancia significa poco.

2. Estandarización

Normaliza antes de comparar, o las puntuaciones serán incorrectas: minúsculas, elimina puntuación, expande abreviaturas (C/ → Calle), divide nombres en partes, normaliza números de teléfono a dígitos, normaliza sufijos de empresa (S.L., Ltd., LLC) y estandariza direcciones (verificación postal cuando esté disponible).

Los datos reales desordenados casi siempre también necesitan:

• Tabla de apodos (Roberto/Beto, José/Pepe, Alejandro/Alex, Patricia/Patri) e iniciales («J.») tratadas como compatibles con cualquier nombre que comience con esa letra.
• Campos de nombre intercambiados — también compara apellido↔nombre invertidos.
• Fechas ambiguas — «04/05/1990» podría ser el 5 de abril o el 4 de mayo. Mantén ambas lecturas y trata un intercambio de día/mes como una coincidencia parcial, no un conflicto.

3. Bloqueo

Comparar cada registro con todos los demás es N² — 1M de registros significa ~500 mil millones de pares. El bloqueo solo compara registros que comparten una clave. Utiliza varias pasadas con diferentes claves para que un error tipográfico en un campo no oculte una coincidencia real:

• Apellido fonético (Soundex / NYSIIS) + año de nacimiento
• Prefijo del código postal + número de casa
• Últimos 4 dígitos de un ID + código postal
• Teléfono o correo electrónico
• Para datos con mucho texto: MinHash LSH en conjuntos de tokens, o embeddings + búsqueda del vecino más cercano (FAISS/HNSW)

Mídelo:

• Ratio de reducción = 1 − (pares comparados ÷ todos los pares posibles) — busca > 99%
• Completitud de pares = coincidencias reales que caen en algún bloque ÷ todas las coincidencias reales — busca ≥ 95%

4. Puntuación — la cascada de 3 pasos

Ejecuta primero las comprobaciones económicas y seguras, y las costosas solo donde sea necesario.

1. Determinístico: un ID único fiable coincide (DNI, NIF, número de cuenta, correo electrónico verificado) → coincidencia.
2. Difuso: no hay coincidencia de ID → compara campos con el algoritmo adecuado por campo (ver tabla) y combínalos con ponderaciones de Fellegi-Sunter.
3. Aprendizaje automático / revisión humana: todavía ambiguo → un clasificador (p. ej., regresión logística sobre las características de similitud de campos) si hay datos etiquetados; en caso contrario, enrutar a una cola de revisión humana.

Tipo de campo	Uso
Nombres de personas	Jaro-Winkler (recompensa prefijos coincidentes), más listas de apodos
Nombres de empresas	Ratio de orden de tokens (el orden de las palabras no importa) después de limpiar sufijos
Direcciones	Levenshtein después de la estandarización; el número de casa y el número de piso deben coincidir exactamente
IDs, teléfono, correo electrónico	Exacto después de la normalización
Texto largo	Jaccard / coseno sobre tokens

Fellegi-Sunter en resumen — para cada campo k:

• m = P(el campo coincide | los registros realmente coinciden) — fiabilidad del campo
• u = P(el campo coincide | los registros no coinciden) — con qué frecuencia coincide por casualidad
• peso de concordancia = log2(m/u); peso de discrepancia = log2((1−m)/(1−u))
• puntuación total = suma de los pesos para el resultado de cada campo

Los valores raros aportan más evidencia: coincidir en «Lebowski» (u minúscula) es mucho más fuerte que coincidir en «García». Utiliza u específico del valor cuando puedas. En la práctica: un nombre completo raro más una fecha de nacimiento exacta es evidencia sólida incluso cuando la dirección, el teléfono y el correo electrónico han cambiado (la persona se mudó); un nombre común más una fecha de nacimiento no lo es.

Para puntuar pares, ejecuta scripts/fs_score.py en lugar de calcular a mano — aplica los pesos, convierte la puntuación en una probabilidad de coincidencia dadas las probabilidades previas y asigna la banda de decisión. Ejecuta python scripts/fs_score.py --help para ver el uso. Las fórmulas completas, el ejemplo detallado y la estimación de m/u (incluyendo EM) están en references/methods.md; léelo cuando el usuario quiera las matemáticas o necesite ajustar los pesos.

Dos trampas que la puntuación por sí sola no detectará:

• Hogares. Gemelos, cónyuges y compañeros de piso comparten apellido, dirección y, a veces, fecha de nacimiento, por lo que su puntuación puede parecer una coincidencia casi segura. Si los nombres de pila difieren (y no son apodos el uno del otro) y los contactos personales (correo electrónico, teléfono) entran en conflicto, mantenlos separados o envíalos a revisión — diga lo que diga la puntuación.
• Valores de relleno. Fechas como 2000-01-01 o 1900-01-01, teléfonos como 555-0000 y correos electrónicos como [email protected] son relleno, no evidencia. El perfilado (etapa 1) debe marcar los valores que se repiten sospechosamente; no les des peso.

Bandas de decisión (ajusta con datos etiquetados; estos son puntos de partida):

Probabilidad de coincidencia	Acción
≥ 0.95	Coincidencia automática
0.80 – 0.94	Cola de revisión humana
< 0.80	No coincidencia

5. Fusión — supervivencia y registros dorados

Agrupa los pares coincidentes en entidades (componentes conectados / agrupación en grafos — ten cuidado con cadenas donde AB y BC pero A≁C; divide esas para revisión). Para cada entidad construye un registro dorado eligiendo cada campo con una regla declarada:

• Más reciente (marca de tiempo más reciente) — para direcciones, teléfono
• Más completo (no nulo, más largo) — para nombres, descripciones
• Fuente de confianza (clasificación del sistema) — para IDs, nombres legales

Nunca sobrescribas ni elimines los originales. Almacena: ID del registro dorado → lista de IDs de registros fuente, la regla que eligió cada campo y la puntuación de coincidencia que los unió.

Validación de resultados

Pide, o ayuda a construir, un pequeño conjunto etiquetado (unos cientos de pares marcados como coincidencia/no coincidencia). Informa de precisión, exhaustividad y F1 sobre él, además del ratio de reducción y la completitud de pares para el bloqueo. Los umbrales sin validación son conjeturas — dilo cuando no haya un conjunto etiquetado.

Etiquetas de evidencia

Cuando afirmes un resultado, di cómo lo sabes:

• [DOC] — de una especificación o documentación, no ejecutado
• [RAN] — ejecutado en esta sesión
• [PASS] — verificado contra datos etiquetados/de prueba

Revisión de checkpoint

En trabajos largos (aproximadamente cada cinco turnos de trabajo, cuando el usuario informe de un error, o cuando escriba «checkpoint» o «sueño»): pausa el trabajo del proyecto y revisa brevemente tus propios turnos recientes. Enumera cada error o desviación de las restricciones declaradas por el usuario, su causa y la corrección que aplicarás en adelante. Luego reanuda. Mantén la revisión fuera de los entregables — es para la conversación, no para los datos o documentos del usuario.

Salida para un trabajo de coincidencia

Finaliza un trabajo completado con:

ENTIDADES: <registros de entrada> → <entidades resueltas>  (<duplicados encontrados>)
BANDAS: auto <n> | revisión <n> | no coincidencia <n>
CALIDAD: precisión <x> | exhaustividad <x> | F1 <x>   (o «no validado — sin conjunto etiquetado»)
ARCHIVOS: <dónde se guardaron los registros dorados, el mapa de correspondencia y la cola de revisión>

Privacidad

La coincidencia a menudo implica datos personales. Procésalos localmente, no pegues identificadores en URL o servicios externos, y al vincular entre organizaciones sugiere vinculación con preservación de la privacidad (codificación Bloom-filter de nombres, comparada con similitud Dice) — detalles en references/methods.md.