Skill Mini Graphe de Contexte

L'Idée Centrale

Le RAG standard redécouvre les connaissances à partir de zéro à chaque requête. Ce skill est différent :

1. Couche wiki — L'LLM écrit et maintient des pages markdown persistantes (résumés, pages d'entités, synthèses thématiques). Les renvois croisés sont déjà présents. Le wiki s'enrichit à chaque ingestion.
2. Couche graphe — Les entités et relations sont extraites une fois et stockées comme un graphe de connaissances navigable. La traversée BFS répond aux requêtes structurelles sans relire les sources.
3. Couche source brute — Les documents originaux sont stockés immuablement avec des chunks. Les liens de provenance relient chaque nœud et arête du graphe au texte exact qui les justifie.

L'LLM écrit ; les outils Python gèrent toute la comptabilité.

Trois Couches

⚡ Démarrage Rapide pour les Agents

from scripts.contextgraph import ContextGraphSkill
from scripts.tools import wiki_store

skill = ContextGraphSkill()

# ===== INGESTION AVEC RAG COMPLET + WIKI =====
# 1. Lisez d'abord references/ingestion.md et references/ontology.md
# 2. Extrayez entités et relations (étape de raisonnement LLM)
entities = [
    {"name": "memory leak",   "type": "issue",  "supporting_text": "memory leaks cause crashes"},
    {"name": "system crash",  "type": "issue",  "supporting_text": "system crashes due to memory leaks"},
]
relations = [
    {"source": "memory leak", "target": "system crash", "type": "causes",
     "confidence": 1.0, "supporting_text": "System crashes due to memory leaks."},
]

result = skill.ingest_with_content(
    doc_id="doc_001",
    title="System Crash Analysis",
    source="/docs/incident_report.pdf",
    raw_content="System crashes due to memory leaks. Memory leaks occur when objects are not released.",
    entities=entities,
    relations=relations,
)
# result = {"doc_id": "doc_001", "chunk_count": 1, "nodes_added": 2, "edges_added": 1}

# 3. Écrivez une page de résumé wiki pour ce document
wiki_store.write_page(
    category="summary",
    title="System Crash Analysis Summary",
    content="""---
title: System Crash Analysis
source_document: doc_001
tags: [summary, incident]
---

# System Crash Analysis

**Source:** incident_report.pdf

## Key Claims

- [[memory-leak]] causes [[system-crash]] (confidence: 1.0)

## Entities

- [[memory-leak]] (issue)
- [[system-crash]] (issue)
""",
    summary="Incident report: memory leaks cause system crashes.",
)

# ===== REQUÊTE AVEC PREUVES =====
result = skill.query_with_evidence("Why does the system crash?")
# Returns: {"query": ..., "subgraph": ..., "supporting_documents": [...], "evidence_chain": ...}

# ===== RECHERCHE WIKI (lire le wiki avant de répondre) =====
pages = wiki_store.search_wiki("memory leak")
# Returns: [{slug, category, path, snippet}, ...]

Opérations

Ingestion

Quand un utilisateur fournit un nouveau document :

1. Lisez references/ingestion.md — règles d'extraction d'entités/relations.
2. Lisez references/ontology.md — règles de normalisation des types.
3. Extrayez les entités et relations via votre raisonnement LLM.
4. Appelez skill.ingest_with_content(...) — stocke le contenu brut + chunks + nœuds de graphe + provenance.
5. Écrivez une page de résumé wiki avec wiki_store.write_page(category="summary", ...).
6. Mettez à jour les pages d'entités — pour chaque entité nouvelle/mise à jour, écrivez ou mettez à jour wiki_store.write_page(category="entity", ...).
7. Mettez à jour les pages thématiques si le document touche un sujet de synthèse existant.
8. Une ingestion de document unique touchera généralement 3–10 pages wiki.

Requête

Quand un utilisateur pose une question :

1. Vérifiez d'abord le wiki — wiki_store.search_wiki(query) pour trouver les pages pertinentes. Lisez-les.
2. Si le wiki a une bonne réponse, synthétisez à partir des pages wiki (chemin rapide).
3. Si une traversée de graphe plus profonde est nécessaire, appelez skill.query_with_evidence(query).
4. Retournez la réponse avec des citations de preuves provenant de supporting_documents.
5. Si la réponse est précieuse, renvoyez-la comme une nouvelle page de sujet wiki.

Lint

Vérifiez périodiquement la santé du wiki :

from scripts.tools import wiki_store
issues = wiki_store.lint_wiki()
# Returns: {orphan_pages, missing_pages, broken_wikilinks, isolated_pages}

Demandez à l'LLM d'examiner et corriger : liens cassés, pages orphelines, affirmations obsolètes, renvois croisés manquants. Voir references/lint.md pour le workflow lint complet.

Contraintes d'Ingestion

• ❌ Ne HALLUCINEZ PAS d'entités absentes du texte
• ❌ N'AJOUTEZ PAS de relations sans preuve textuelle explicite
• ❌ N'AJOUTEZ PAS d'arêtes avec confiance < 0,6
• ✅ Fournissez supporting_text pour chaque entité et relation — cela active la provenance
• ✅ Écrivez une page de résumé wiki pour chaque document ingéré
• ✅ Mettez à jour les pages d'entités existantes quand de nouvelles infos arrivent
• ✅ Signalez les contradictions dans les pages wiki quand les nouvelles données contredisent les anciennes affirmations

Contraintes de Récupération

• 🔒 La profondeur de traversée NE DOIT PAS dépasser 2 (config: MAX_GRAPH_DEPTH)
• 🔒 Uniquement les arêtes avec confiance ≥ 0,6 (config: MIN_CONFIDENCE)
• 🔒 Maximum 50 nœuds retournés (config: MAX_NODES)
• ❌ Ne FABRIQUEZ PAS de nœuds ou arêtes absents du graphe

Référence API Python Complète

Philosophie de Conception

« Le wiki est un artefact persistant et composé. Les renvois croisés sont déjà là. La synthèse reflète déjà tout ce que vous avez lu. » — Karpathy

L'humain curate les sources et pose les questions. L'LLM écrit le wiki, extrait le graphe, et répond avec des citations. Python gère toute la comptabilité.