SourceTrace

Que fait SourceTrace ?

SourceTrace vérifie un arbre de connaissances généré par IA par rapport aux images sources dont il est issu, et explique chaque problème avec des preuves traçables. L'utilisateur ne devrait jamais avoir à accepter une constatation sans preuve : chacune indique pourquoi c'est un problème, où se trouve le matériel source (page et citation), et sur quoi elle repose (identifiants de preuve).

Un modèle simple peut généralement repérer les erreurs. Ce que SourceTrace ajoute, c'est que le résultat est vérifiable : chaque nœud et arête reçoit un verdict, chaque verdict cite des preuves, les catégories et niveaux de risque sont fixes, et la sortie a toujours la même forme.

Entrées

• Images source : PNG/JPG, une image par page (par exemple, des diapositives exportées sous forme d'images). Elles sont la source unique de vérité. Si l'utilisateur a un fichier PPT ou PDF, demandez-lui de l'exporter d'abord en images.
• Arbre de connaissances : JSON suivant schemas/knowledge-tree.schema.json (nœuds avec id, label, definition, kind ; arêtes avec id, source, target, relation). Si l'arbre utilise un autre format ou d'autres noms de relations, convertissez-le d'abord et dites à l'utilisateur ce que vous avez mappé.

Les chemins ci-dessous tels que scripts/…, schemas/… et references/… sont relatifs au dossier de cette compétence.

Sorties

Écrire tous les fichiers dans un dossier de sortie, par défaut sourcetrace-output/ à côté de l'arbre de connaissances :

Fichier	Étape	Contenu
evidence-index.json	2	Chaque élément de preuve extrait des images (vous l'écrivez)
audit.json	4–6	Un verdict pour chaque nœud et arête, plus les omissions (vous écrivez les jugements ; le script le complète)
report.md	6	Le rapport lisible par l'humain (généré par scripts/build_report.py; ne l'écrivez pas vous-même)

Ne modifiez jamais l'arbre de connaissances de l'utilisateur. SourceTrace rapporte et recommande ; l'utilisateur décide.

Flux de travail

Exécutez les six étapes dans l'ordre. Ne sautez pas à l'étape de jugement de l'arbre avant que l'index des preuves n'existe : auditer par rapport à un index, plutôt que par rapport à votre impression des diapositives, est ce qui rend les constatations traçables.

1. Ingestion de la source

python scripts/validate_input.py --tree <arbre-de-connaissances.json> --images <dossier d'images ou fichiers> --json

• Erreurs ("valid": false) : arrêtez-vous, montrez les erreurs à l'utilisateur en langage clair et demandez-lui de corriger l'entrée. N'auditez pas un arbre invalide.
• Avertissements (ex. DISCONNECTED_TREE, ISOLATED_NODE, DUPLICATE_EDGE) : continuez. build_report.py les place dans la section Structure du rapport.
• summary.images donne à chaque image son source_id et sa page. Utilisez exactement ceux-ci à l'étape 2.

Examinez ensuite chaque image et notez son titre, son texte, ses tableaux et ses diagrammes.

2. Extraction des preuves

Construisez evidence-index.json en suivant references/evidence-extraction.md. Lisez ce fichier avant d'extraire ; en résumé :

• Un élément par titre de diapositive, puce, ligne de tableau et relation de diagramme.
• Citez le texte textuellement dans sa langue d'origine. De légers changements de formulation sont ce que l'audit doit détecter.
• Extrayez tout, y compris les devoirs ou notes de lecture.
• Définissez certainty honnêtement ; une preuve low ne peut pas à elle seule rejeter un élément de l'arbre.

Validez-le ensuite et corrigez chaque erreur avant de continuer :

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

3. Mappage des connaissances

Traitez l'arbre comme un ensemble d'affirmations à tester, jamais comme un fait. Divisez-le en :

• Nœuds : l'étiquette et la définition sont-elles correctes ?
• Arêtes : la relation entre les deux nœuds est-elle correcte ? Lisez les arêtes comme source relation target.

Auditez-les séparément. Un nœud peut être correct tandis qu'une arête qui l'utilise est erronée (et vice versa), et chacun reçoit son propre verdict.

Pour chaque nœud et arête, listez les éléments de preuve qui s'y rapportent. Recherchez dans tout l'index, pas seulement la page que vous attendez : certaines affirmations ne sont confirmées ou contredites qu'en combinant deux pages.

4. Audit bidirectionnel

• Arbre → source : pour chaque nœud et arête, décidez si la preuve le soutient. Chaque nœud et arête reçoit un verdict, y compris les corrects ; confirmer ce qui est juste fait partie du résultat.
• Source → arbre : parcourez l'index des preuves et trouvez le contenu significatif qu'aucun nœud ou arête ne couvre.

Suivez references/audit-rules.md pour les verdicts, ce qui compte comme significatif et les cas particuliers.

5. Détection des conflits

Classez chaque problème dans exactement une catégorie et attribuez-lui un niveau de risque. Utilisez l'ordre de décision dans references/audit-rules.md : parcourez ses questions dans l'ordre et arrêtez-vous au premier "oui". Ne choisissez pas une catégorie en fonction de ce que ressent une constatation ; l'ordre est ce qui assure la cohérence entre deux exécutions.

Catégorie	Signification
conceptual-error	La définition d'un nœud contredit la source.
incorrect-relationship	Une arête contredit la source, même si les deux nœuds sont corrects.
unsupported-expansion	Contenu non trouvé dans la source, même s'il est vrai en général.
overgeneralization	Contenu pris en charge mais étiré au-delà de ce que dit la source.
ambiguous	Trop vague ou incertain pour confirmer ou rejeter.
omission	Contenu source significatif manquant dans l'arbre.

6. Rapport d'audit

Écrivez vos jugements dans audit.json, puis laissez le script les vérifier et produire le rapport. Vous décidez ; le script compte, numérote, trie et formate. Cette séparation est ce qui permet à deux exécutions de produire le même rapport.

audit.json tel que vous l'écrivez (v0.1, schéma 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": "concept central du cours",
      "evidence": ["EV-003"], "reason": "...", "recommendation": "..." }
  ]
}

• items : exactement une entrée par nœud et arête de l'arbre.
• reason : pourquoi c'est un problème, en une ou deux phrases, citant les mots exacts qui diffèrent.
• recommendation : une révision concrète qui reste dans le schéma de l'arbre (valeurs kind et relation autorisées uniquement).
• tier (omissions uniquement) : core ou supporting, tel que défini dans references/audit-rules.md.
• risk_reason : seulement lorsque le risque diffère de la valeur par défaut.
• Laissez de côté summary, structure_warnings et finding_id ; le script les calcule.

Exécutez ensuite :

python scripts/build_report.py --tree <arbre-de-connaissances.json> --index <sortie>/evidence-index.json --audit <sortie>/audit.json

• Erreurs : rien n'est écrit. Corrigez audit.json et réexécutez jusqu'à ce que cela réussisse. Ne contournez pas les vérifications.
• Succès : le script réécrit audit.json avec summary, structure_warnings et les finding_id (F-001, F-002, … dans l'ordre du rapport), et écrit report.md à côté. Le langage du rapport suit les diapositives ; passez --lang zh ou --lang en si l'utilisateur en demande un autre.

Terminez en indiquant à l'utilisateur où se trouve le rapport, les comptes du résumé et les principaux problèmes en quelques lignes. Ne collez pas l'intégralité du rapport.

Quand l'entrée est inhabituelle

• Image illisible : extrayez ce que vous pouvez avec une certitude low, mentionnez la page dans le reason des constatations concernées et dites-le à l'utilisateur ; n'inventez pas de contenu.
• L'arbre couvre du matériel non présent dans les images (par exemple, seules certaines diapositives ont été fournies) : signalez ces éléments comme unsupported-expansion et dites à l'utilisateur que les pages manquantes peuvent en être la cause.
• Jeux de diapositives ou arbres très volumineux : travaillez page par page à l'étape 2 et nœud par nœud à l'étape 4, en écrivant les résultats dans les fichiers au fur et à mesure plutôt que de tout garder en mémoire.