detector-de-conflictos

¿Qué hace detector-de-conflictos?

Un skill autónomo que encuentra contradicciones en un conjunto de documentos. Cada documento se carga (ruta / texto en línea / JSON en línea), sus hechos se extraen y un motor de reglas entre documentos empareja afirmaciones por clave canónica y señala discrepancias.

FLUJO DE TRABAJO OBLIGATORIO

Inicialización de dependencias (ejecutar en el primer uso)

Antes de la primera ejecución, verifica las dependencias de ejecución de este skill:

• Núcleo: solo biblioteca estándar — no requiere instalación.
• Opcional: PyYAML (solo cuando la configuración o entrada es un .yaml; las entradas JSON funcionan solo con la biblioteca estándar).

Si falta PyYAML y la entrada es YAML, informa al usuario y pregunta si desea pip install pyyaml; instala solo después de que confirme. Nunca instales en el entorno global sin consentimiento explícito.

1. Carga la configuración YAML (config/examples/two_docs.yaml como referencia).

2. Verifica que cada documents[].value / documents[].path sea accesible.

3. python -m src.cli run --config <ruta> [--format json,csv,md].

4. Reporta el recuento de conflictos por nivel y señala al usuario

   ./conflicts/conflicts_<run_id>.*.

Cuándo usarlo

• Dos o más documentos, conjuntos de datos o tablas de hechos extraídas deben verificarse

  entre sí en busca de contradicciones.

• El usuario pide "detectar conflictos", "encontrar contradicciones", "verificar

  afirmaciones" o pregunta "¿estos documentos concuerdan?".

• Una sola afirmación (un número, un estado, un hecho nombrado) aparece en varias

  fuentes y debe compararse entre ellas.

• Una tabla de hechos extraída de documentos debe auditarse para verificar su consistencia

  interna antes de utilizarla.

Ejemplos de uso

# Validar una configuración antes de ejecutarla (rápido, sin escribir informe).

python -m src.cli validate --config config/examples/two_docs.yaml



# Listar las fuentes de documentos que resuelve una configuración.

python -m src.cli list-docs --config config/examples/two_docs.yaml



# Ejecutar una detección; elegir los formatos de salida (predeterminado: json).

python -m src.cli run --config config/examples/two_docs.yaml --format json,csv,md

Los informes se escriben en ./conflicts/conflicts_<run_id>.{json,csv,md}; el

JSON es el contrato legible por máquina.

Manejo de fallos

• Configuración inválida (validate sale con código distinto de cero) — corrige el campo

  informado y vuelve a validar; no modifiques manualmente alrededor de una violación del esquema.

• Una fuente de documento es inaccesible — la ejecución aborta indicando la

  entrada documents[] problemática; verifica la ruta o el valor en línea, reintenta.

• No se encontraron conflictos — un resultado válido y reportable (un informe vacío),

  no un error; dilo explícitamente en lugar de volver a ejecutar.

• Código de salida inesperado — reporta el mensaje textualmente; no recurras

  a comparar los documentos manualmente.

Niveles de detección

Nivel	Tipo	Severidad	Ejemplo
entity	numeric_mismatch, boolean	alta	speed = 10 vs speed = 20
clause	categorical	media	status = "active" vs status = "archived"
argument	categorical (texto)	baja	líneas de texto libre que discrepan

Limitaciones

• La extracción está orientada a clave-valor; los párrafos de texto libre solo participan en el nivel argument (comparación línea por línea).

• La normalización de unidades se basa en una tabla (unit_map); las reglas de unidades personalizadas deben proporcionarse a través de la configuración.