SourceTrace

¿Qué hace SourceTrace?

SourceTrace comprueba un árbol de conocimiento generado por IA contra las imágenes fuente de las que proviene, y explica cada problema con evidencia trazable. El usuario nunca debe aceptar un hallazgo sin fundamento: cada uno indica por qué es un problema, dónde está el material fuente (página y cita), y en qué se basa (IDs de evidencia).

Un modelo normal suele detectar los errores. Lo que SourceTrace añade es que el resultado es verificable: cada nodo y arista recibe un veredicto, cada veredicto cita evidencia, las categorías y niveles de riesgo son fijos, y la salida tiene siempre la misma estructura.

Entradas

• Imágenes fuente: PNG/JPG, una imagen por página (por ejemplo, diapositivas exportadas como imágenes). Son la única fuente de verdad. Si el usuario tiene un PPT o PDF, pídele que lo exporte primero a imágenes.
• Árbol de conocimiento: JSON que sigue schemas/knowledge-tree.schema.json (nodos con id, label, definition, kind; aristas con id, source, target, relation). Si el árbol usa otro formato u otros nombres de relación, conviértelo primero e indica al usuario qué mapeaste.

Las rutas siguientes, como scripts/…, schemas/… y references/…, son relativas a la carpeta de esta habilidad.

Salidas

Escribe todos los archivos en una carpeta de salida, por defecto sourcetrace-output/ junto al árbol de conocimiento:

Archivo	Etapa	Contenido
evidence-index.json	2	Cada pieza de evidencia extraída de las imágenes (tú la escribes)
audit.json	4–6	Un veredicto para cada nodo y arista, además de omisiones (tú escribes los juicios; el script lo completa)
report.md	6	El informe legible para humanos (generado por scripts/build_report.py; no lo escribas tú mismo)

Nunca modifiques el árbol de conocimiento del usuario. SourceTrace informa y recomienda; el usuario decide.

Flujo de trabajo

Ejecuta las seis etapas en orden. No te adelantes a juzgar el árbol antes de que exista el índice de evidencia: auditar contra un índice, y no contra tu impresión de las diapositivas, es lo que hace que los hallazgos sean trazables.

1. Ingesta de fuentes

python scripts/validate_input.py --tree <knowledge-tree.json> --images <carpeta o archivos de imágenes> --json

• Errores ("valid": false): detente, muestra los errores al usuario en lenguaje sencillo y pídele que corrija la entrada. No audites un árbol inválido.
• Advertencias (p. ej., DISCONNECTED_TREE, ISOLATED_NODE, DUPLICATE_EDGE): continúa. build_report.py las incluye en la sección de Estructura del informe.
• summary.images proporciona a cada imagen su source_id y page. Usa exactamente estos en la etapa 2.

Luego observa cada imagen y anota su título, texto, tablas y diagramas.

2. Extracción de evidencia

Construye evidence-index.json siguiendo references/evidence-extraction.md. Lee ese archivo antes de extraer; en resumen:

• Un elemento por cada título de diapositiva, viñeta, fila de tabla y relación de diagrama.
• Cita el texto textualmente en su idioma original. Los pequeños cambios de redacción son lo que la auditoría debe detectar.
• Extrae todo, incluyendo tareas o notas de lectura.
• Establece certainty con honestidad; la evidencia low no puede rechazar un elemento del árbol por sí sola.

Luego valida y corrige cada error antes de continuar:

python scripts/validate_evidence.py --index <salida>/evidence-index.json

3. Mapeo de conocimiento

Trata el árbol como un conjunto de afirmaciones que probar, nunca como un hecho. Divídelo en:

• Nodos: ¿la etiqueta y la definición son correctas?
• Aristas: ¿la relación entre los dos nodos es correcta? Lee las aristas como source relation target.

Audítalos por separado. Un nodo puede ser correcto mientras que una arista que lo usa es incorrecta (y viceversa), y cada uno recibe su propio veredicto.

Para cada nodo y arista, enumera los elementos de evidencia que le afectan. Busca en todo el índice, no solo en la página que esperas: algunas afirmaciones solo se confirman o contradicen combinando dos páginas.

4. Auditoría bidireccional

• Árbol → fuente: para cada nodo y arista, decide si la evidencia lo respalda. Cada nodo y arista recibe un veredicto, incluidos los correctos; confirmar lo que está bien es parte del resultado.
• Fuente → árbol: recorre el índice de evidencia y encuentra contenido significativo que ningún nodo o arista cubre.

Sigue references/audit-rules.md para los veredictos, qué cuenta como significativo y los casos límite.

5. Detección de conflictos

Clasifica cada problema en exactamente una categoría y asígnale un nivel de riesgo. Usa el orden de decisión en references/audit-rules.md: recorre sus preguntas en orden y detente en el primer «sí». No elijas una categoría por cómo se siente un hallazgo; el orden es lo que mantiene consistentes dos ejecuciones.

Categoría	Significado
conceptual-error	La definición de un nodo contradice la fuente.
incorrect-relationship	Una arista contradice la fuente, aunque ambos nodos sean correctos.
unsupported-expansion	Contenido no encontrado en la fuente, aunque sea cierto en general.
overgeneralization	Contenido respaldado estirado más allá de lo que dice la fuente.
ambiguous	Demasiado vago o incierto para confirmar o rechazar.
omission	Contenido significativo de la fuente que falta en el árbol.

6. Informe de auditoría

Escribe tus juicios en audit.json, luego deja que el script los revise y produzca el informe. Tú decides; el script cuenta, numera, ordena y formatea. Esa separación es lo que hace que dos ejecuciones produzcan el mismo informe.

audit.json tal como lo escribes (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": "concepto central de la clase",
      "evidence": ["EV-003"], "reason": "...", "recommendation": "..." }
  ]
}

• items: exactamente una entrada por nodo y arista del árbol.
• reason: por qué es un problema, en una o dos oraciones, citando las palabras exactas que difieren.
• recommendation: una revisión concreta que se mantenga dentro del esquema del árbol (solo valores permitidos de kind y relation).
• tier (solo omisiones): core o supporting, según se define en references/audit-rules.md.
• risk_reason: solo cuando el riesgo difiere del predeterminado.
• Omite summary, structure_warnings y finding_id; el script los calcula.

Luego ejecuta:

python scripts/build_report.py --tree <knowledge-tree.json> --index <salida>/evidence-index.json --audit <salida>/audit.json

• Errores: no se escribe nada. Corrige audit.json y vuelve a ejecutarlo hasta que tenga éxito. No evites las comprobaciones.
• Éxito: el script reescribe audit.json con summary, structure_warnings y finding_ids (F-001, F-002, … en el orden del informe), y escribe report.md junto a él. El idioma del informe sigue las diapositivas; pasa --lang zh o --lang en si el usuario pide otro.

Finaliza indicando al usuario dónde está el informe, los recuentos del resumen y los principales problemas en pocas líneas. No pegues el informe completo.

Cuando la entrada es inusual

• Imagen ilegible: extrae lo que puedas con certeza low, menciona la página en el reason de los hallazgos afectados e informa al usuario; no inventes contenido.
• El árbol cubre material no presente en las imágenes (p. ej., solo se proporcionaron algunas diapositivas): reporta esos elementos como unsupported-expansion e informa al usuario de que las páginas faltantes pueden ser la causa.
• Presentaciones o árboles muy grandes: trabaja página por página en la etapa 2 y nodo por nodo en la etapa 4, escribiendo los resultados en los archivos a medida que avanzas en lugar de mantenerlo todo en la mente.