Habilidade de Mini Contexto em Grafo

A Ideia Central

O RAG padrão redescobre o conhecimento do zero a cada consulta. Esta habilidade é diferente:

1. Camada Wiki — O LLM escreve e mantém páginas persistentes em markdown (resumos, páginas de entidades, sínteses de tópicos). As referências cruzadas já estão lá. A wiki fica mais rica a cada ingestão.
2. Camada de Grafo — Entidades e relações são extraídas uma vez e armazenadas como um grafo de conhecimento navegável. A travessia BFS responde a consultas estruturais sem reler as fontes.
3. Camada de Fonte Bruta — Documentos originais são armazenados imutavelmente com pedaços (chunks). Links de proveniência ligam cada nó e aresta do grafo ao texto exato que o suporta.

O LLM escreve; as ferramentas Python cuidam de toda a contabilidade.

Três Camadas

⚡ Início Rápido para Agentes

Uma versão completa e executável deste fluxo de trabalho está em scripts/template_agent_workflow.py — copie e adapte-a.

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

skill = ContextGraphSkill()

# ===== INGEST WITH FULL RAG + WIKI =====
# 1. Read references/ingestion.md and references/ontology.md first
# 2. Extract entities and relations (LLM reasoning step)
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. Write a wiki summary page for this 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.",
)

# ===== QUERY WITH EVIDENCE =====
result = skill.query_with_evidence("Why does the system crash?")
# Returns: {"query": ..., "subgraph": ..., "supporting_documents": [...], "evidence_chain": ...}

# ===== WIKI SEARCH (read wiki before answering) =====
pages = wiki_store.search_wiki("memory leak")
# Returns: [{slug, category, path, snippet}, ...]

Operações

Ingestão

Quando um usuário fornece um novo documento:

1. Leia references/ingestion.md — regras de extração de entidades/relações.
2. Leia references/ontology.md — regras de normalização de tipos.
3. Extraia entidades e relações usando o raciocínio do seu LLM.
4. Chame skill.ingest_with_content(...) — armazena conteúdo bruto + pedaços + nós do grafo + proveniência.
5. Escreva uma página de resumo da wiki usando wiki_store.write_page(category="summary", ...).
6. Atualize páginas de entidades — para cada entidade nova/atualizada, escreva ou atualize wiki_store.write_page(category="entity", ...).
7. Atualize páginas de tópicos se o documento tocar em um tópico de síntese existente.
8. Uma única ingestão de documento geralmente tocará em 3–10 páginas da wiki.

Consulta

Quando um usuário faz uma pergunta:

1. Verifique a wiki primeiro — wiki_store.search_wiki(query) para encontrar páginas relevantes. Leia-as.
2. Se a wiki tiver uma boa resposta, sintetize a partir das páginas da wiki (caminho rápido).
3. Se for necessária uma travessia de grafo mais profunda, chame skill.query_with_evidence(query).
4. Retorne a resposta com citações de evidências de supporting_documents.
5. Se a resposta for valiosa, arquive-a como uma nova página de tópico da wiki.

Lint

Verifique periodicamente a saúde da wiki:

from scripts.tools import wiki_store

…