Detector de Conflitos entre Documentos

detector-de-conflitos

Um skill auto-suficiente que encontra **contradições em um conjunto de

documentos**. Cada documento é carregado (caminho / texto inline / JSON inline),

seus fatos são extraídos e um motor de regras cross-documento pareia afirmações por

chave canônica e sinaliza discrepâncias.

WORKFLOW OBRIGATÓRIO

Bootstrap de dependências (executar na primeira utilização)

Antes da primeira execução, verifique as dependências de runtime para este skill:

• Core: biblioteca padrão pura — nenhuma instalação necessária.
• Opcional: PyYAML (apenas quando a configuração / entrada é um .yaml; entradas JSON funcionam apenas com a biblioteca padrão).

Se PyYAML estiver ausente e a entrada for YAML, avise o usuário e pergunte se deseja pip install pyyaml; instale apenas após a confirmação. Nunca instale no ambiente global sem consentimento explícito.

1. Carregue a configuração YAML (config/examples/two_docs.yaml como referência).

2. Verifique se cada documents[].value / documents[].path está acessível.

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

4. Reporte a contagem de conflitos por nível e aponte o usuário para

   ./conflicts/conflicts_<run_id>.*.

Quando usar

• Dois ou mais documentos, conjuntos de dados ou tabelas de fatos extraídos devem ser verificados quanto a contradições.
• O usuário pede para "detectar conflitos", "encontrar contradições", "verificar consistência" ou pergunta "esses documentos concordam?".
• Uma única afirmação (um número, um status, um fato nomeado) aparece em várias fontes e deve ser comparada entre elas.
• Uma tabela de fatos extraída de documentos deve ser auditada quanto à consistência interna antes de ser utilizada.

Exemplos de uso

# Validar uma configuração antes de executá-la (rápido, sem relatório).

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



# Listar as fontes de documentos que uma configuração resolve.

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



# Executar uma detecção; escolher os formatos de saída (padrão: json).

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

Relatórios são escritos em ./conflicts/conflicts_<run_id>.{json,csv,md}; o

JSON é o contrato legível por máquina.

Tratamento de falhas

• Configuração inválida (validate sai com código não zero) - corrija o campo reportado e revalide; não edite manualmente ao redor de uma violação de esquema.
• Fonte de documento inacessível - a execução aborta nomeando a entrada documents[] ofensiva; verifique o caminho ou valor inline e tente novamente.
• Nenhum conflito encontrado - um resultado válido e relatável (um relatório vazio), não um erro; diga isso explicitamente em vez de executar novamente.
• Código de saída inesperado - reporte a mensagem literalmente; não recorra a comparar os documentos manualmente.

Níveis de detecção

Nível	Tipo	Gravidade	Exemplo
entidade	numeric_mismatch, boolean	alta	speed = 10 vs speed = 20
cláusula	categórico	média	status = "active" vs status = "archived"
argumento	categórico (texto)	baixa	linhas de texto livre que discordam

Limitações

• A extração é orientada a pares chave-valor; parágrafos de texto livre só participam no nível de argumento (comparação linha a linha).
• A normalização de unidades é orientada por tabela (unit_map); regras de unidade personalizadas devem ser fornecidas via configuração.