SourceTrace – Auditoria de Árvore de Conhecimento

SourceTrace

O SourceTrace verifica uma árvore de conhecimento gerada por IA contra as imagens de fonte originais e explica cada problema com evidências rastreáveis. O usuário nunca deve aceitar uma constatação sem verificação: cada uma informa por que é um problema, onde o material fonte está (página e citação) e no que se baseia (IDs de evidência).

Um modelo comum geralmente consegue identificar os erros. O que o SourceTrace adiciona é que o resultado é verificável: cada nó e aresta recebe um veredito, cada veredito cita evidências, categorias e níveis de risco são fixos, e a saída tem sempre o mesmo formato.

Entradas

• Imagens de fonte: PNG/JPG, uma imagem por página (ex.: slides exportados como imagens). São a única fonte de verdade. Se o usuário tiver um PPT ou PDF, peça para exportá-lo como imagens primeiro.
• Árvore de conhecimento: JSON conforme schemas/knowledge-tree.schema.json (nós com id, label, definition, kind; arestas com id, source, target, relation). Se a árvore usar outro formato ou outros nomes de relação, converta-a primeiro e informe ao usuário o que foi mapeado.

Os caminhos como scripts/…, schemas/… e references/… são relativos à pasta desta habilidade.

Saídas

Escreva todos os arquivos em uma pasta de saída, por padrão sourcetrace-output/ ao lado da árvore de conhecimento:

Arquivo	Etapa	Conteúdo
evidence-index.json	2	Cada evidência extraída das imagens (você escreve)
audit.json	4–6	Um veredito para cada nó e aresta, mais omissões (você escreve os julgamentos; o script completa)
report.md	6	O relatório legível (gerado por scripts/build_report.py; não o escreva você mesmo)

Nunca modifique a árvore de conhecimento do usuário. O SourceTrace relata e recomenda; o usuário decide.

Fluxo de trabalho

Execute as seis etapas em ordem. Não pule para julgar a árvore antes que o índice de evidências exista: auditar contra um índice, e não contra sua impressão dos slides, é o que torna as constatações rastreáveis.

1. Ingestão da fonte

python scripts/validate_input.py --tree <knowledge-tree.json> --images <pasta ou arquivos de imagens> --json

• Erros ("valid": false): pare, mostre os erros ao usuário em linguagem simples e peça para corrigir a entrada. Não audite uma árvore inválida.
• Avisos (ex.: DISCONNECTED_TREE, ISOLATED_NODE, DUPLICATE_EDGE): continue. build_report.py os coloca na seção Estrutura do relatório.
• summary.images fornece a cada imagem seu source_id e page. Use exatamente estes na etapa 2.

Em seguida, examine cada imagem e anote seu título, texto, tabelas e diagramas.

2. Extração de evidências

Construa evidence-index.json seguindo references/evidence-extraction.md. Leia esse arquivo antes de extrair; em resumo:

• Um item por título de slide, marcador, linha de tabela e relacionamento de diagrama.
• Cite o texto textualmente no idioma original. Pequenas alterações de redação são exatamente o que a auditoria deve capturar.
• Extraia tudo, incluindo tarefas de casa ou notas de leitura.
• Defina certainty honestamente; evidência low não pode rejeitar um item da árvore sozinha.

Em seguida, valide-o e corrija todos os erros antes de continuar:

python scripts/validate_evidence.py --index <saída>/evidence-index.json

3. Mapeamento do conhecimento

Trate a árvore como um conjunto de afirmações a testar, nunca como fato. Divida-a em:

• Nós: o rótulo e a definição estão corretos?
• Arestas: a relação entre os dois nós está correta? Leia arestas como fonte relation alvo.

Audite-os separadamente. Um nó pode estar correto enquanto uma aresta que o utiliza está errada (e vice-versa), e cada um recebe seu próprio veredito.

Para cada nó e aresta, liste os itens de evidência que se relacionam a ele. Pesquise todo o índice, não apenas a página que você espera: algumas afirmações são confirmadas ou contraditas apenas combinando duas páginas.

4. Auditoria bidirecional

• Árvore → fonte: para cada nó e aresta, decida se a evidência o suporta. Cada nó e aresta recebe um veredito, incluindo os corretos; confirmar o que está certo faz parte do resultado.
• Fonte → árvore: percorra o índice de evidências e encontre conteúdo significativo que nenhum nó ou aresta cobre.

Siga references/audit-rules.md para vereditos, o que conta como significativo e os casos extremos.

5. Detecção de conflitos

Classifique cada problema em exatamente uma categoria e atribua um nível de risco. Use a ordem de decisão em references/audit-rules.md: percorra suas perguntas em ordem e pare no primeiro "sim". Não escolha uma categoria com base em como uma constatação parece; a ordem é o que mantém duas execuções consistentes.

Categoria	Significado
conceptual-error	A definição de um nó contradiz a fonte.
incorrect-relationship	Uma aresta contradiz a fonte, mesmo que ambos os nós estejam corretos.
unsupported-expansion	Conteúdo não encontrado na fonte, mesmo que verdadeiro em geral.
overgeneralization	Conteúdo suportado esticado além do que a fonte diz.
ambiguous	Muito vago ou incerto para confirmar ou rejeitar.
omission	Conteúdo significativo da fonte ausente na árvore.

6. Relatório de auditoria

Escreva seus julgamentos em audit.json, então deixe o script verificá-los e produzir o relatório. Você decide; o script conta, numera, ordena e formata. Essa divisão é o que faz duas execuções produzirem o mesmo relatório.

audit.json como você o escreve (v0.1, esquema schemas/audit.schema.json):

{
  "schema_version": "0.1",
  "items": [
    { "target": "N001", "verdict": "supported", "evidence": ["EV-002"] },
    { "target": "N002", "verdict": "finding", "evidence": ["EV-008"],
      "category": "conceptual-error", "risk": "high",
      "reason": "...", "recommendation": "..." }
  ],
  "omissions": [
    { "category": "omission", "tier": "core", "risk": "medium", "evidence": ["EV-016"],
      "reason": "...", "recommendation": "..." },
    { "category": "omission", "tier": "core", "risk": "high", "risk_reason": "conceito central da aula",
      "evidence": ["EV-003"], "reason": "...", "recommendation": "..." }
  ]
}

• items: exatamente uma entrada por nó e aresta da árvore.
• reason: por que é um problema, em uma ou duas frases, citando as palavras exatas que diferem.
• recommendation: uma revisão concreta que permaneça dentro do esquema da árvore (apenas valores permitidos de kind e relation).
• tier (apenas omissões): core ou supporting, conforme definido em references/audit-rules.md.
• risk_reason: apenas quando o risco difere do padrão.
• Deixe de fora summary, structure_warnings e finding_id; o script os calcula.

Em seguida, execute:

python scripts/build_report.py --tree <knowledge-tree.json> --index <saída>/evidence-index.json --audit <saída>/audit.json

• Erros: nada é escrito. Corrija audit.json e execute novamente até que tenha sucesso. Não contorne as verificações.
• Sucesso: o script reescreve audit.json com summary, structure_warnings e finding_ids (F-001, F-002, … na ordem do relatório), e escreve report.md ao lado. O idioma do relatório segue os slides; passe --lang zh ou --lang en se o usuário solicitar outro.

Finalize informando ao usuário onde está o relatório, as contagens do resumo e os principais problemas em algumas linhas. Não cole o relatório inteiro.

Quando a entrada é incomum

• Imagem ilegível: extraia o que puder com certeza low, mencione a página no reason das constatações afetadas e informe o usuário; não invente conteúdo.
• A árvore cobre material não presente nas imagens (ex.: apenas alguns slides foram fornecidos): relate esses itens como unsupported-expansion e informe ao usuário que páginas ausentes podem ser a causa.
• Conjuntos muito grandes de slides ou árvores: trabalhe página por página na etapa 2 e nó por nó na etapa 4, escrevendo os resultados nos arquivos à medida que avança, em vez de manter tudo na mente.