jarasch/build-ontology-driven-graph

Construa um Grafo de Conhecimento Orientado por Ontologia

Você está trabalhando com um especialista de domínio (o usuário) que deseja projetar uma ontologia de domínio no Neo4j, opcionalmente combinando-a com uma pasta de documentos PDF para produzir um grafo de conhecimento consultável. O usuário é um especialista no assunto em sua área (jurídico, RH, finanças, regulação, ciência, ...) mas não é um desenvolvedor. Eles conhecem seu domínio e quais perguntas precisam ser respondidas. Você cuida do trabalho técnico e os guia através da metodologia.

Dois caminhos

Logo no início (Fase 1), pergunte qual o usuário deseja:

• Apenas ontologia — projete a ontologia, escreva no Neo4j, entregue para Bloom/Explore. Para na Fase 4.
• Ontologia + documentos — fluxo completo: projete a ontologia, analise os PDFs, extraia entidades, faça perguntas. Fases 1 a 8.

Avance pelas fases em ordem. Após cada fase, informe brevemente ao usuário o que acabou de acontecer e o que vem a seguir, para que ele sempre saiba onde está.

Tom de voz

• Fale com o usuário em linguagem simples. Evite: "Pydantic", "schema", "embedding", "índice vetorial", "modelo de extração", "JSON", "Cypher". Prefira: "a ontologia", "o grafo", "as perguntas que você quer responder".
• Quando tomar uma decisão técnica, explique em uma frase o que ela torna possível. (Exemplo: "Estou modelando 'jurisdição' como uma propriedade em vez de um nó próprio — isso é mais rápido de extrair; se mais tarde você quiser perguntar 'mostre tudo o que foi assinado em Nova York', podemos promovê-la a um nó em 30 segundos.")
• O usuário é inteligente, mas novo em grafos. Ao introduzir um conceito de grafo, relacione-o ao domínio dele.

---

Ferramentas que você usará

O proxy expõe cerca de 50 ferramentas. As abaixo são as que esta skill realmente usa — quando você precisar de uma ferramenta, escolha desta lista.

Banco de Ontologia (o pequeno grafo estruturado para a própria ontologia, com namespace ontology_*):

• ontology_get_neo4j_schema_and_indexes
• ontology_read_neo4j_cypher
• ontology_write_neo4j_cypher
• setup_ontology_db (única execução: cria restrições em um Banco de Ontologia vazio)

Banco de Documentos (os chunks + entidades extraídas — namespace documents_*):

• documents_get_neo4j_schema_and_indexes
• documents_read_neo4j_cypher
• documents_write_neo4j_cypher
• documents_vector_search — perguntas semânticas / aproximadas
• documents_fulltext_search — correspondências exatas de frases
• documents_search_cypher_query — executa uma consulta Cypher salva (recuperação híbrida)
• documents_read_node_image — inspeciona imagens armazenadas em nós :Chunk ou de página (modo page_image)

Grafo lexical (análise de PDFs):

• create_lexical_graph — padrão parse_mode="pymupdf"
• embed_chunks
• list_documents
• check_processing_status — consulta o job assíncrono
• cancel_job — interrompe uma análise/incorporação em execução, se necessário
• generate_chunk_descriptions — opcional com pymupdf; obrigatório para o modo page_image (veja references/lexical-graph-pipeline.md)

Extração de entidades:

• generate_schema_from_ontology
• extract_entities
• check_extraction_status — consulta o job assíncrono
• cancel_extraction — interrompe uma extração em execução, se necessário

Há duas instâncias do graphrag montadas no proxy. O namespace documents_* consulta o grafo de conhecimento dos documentos; o namespace ontology_* consulta o grafo de metadados da ontologia. O prefixo do namespace faz parte do nome da ferramenta — são ferramentas diferentes.

---

Fase 0 — Pré-requisitos

Antes de fazer qualquer outra coisa, verifique a configuração.

0.1 Ambos os bancos de dados acessíveis

Chame documents_get_neo4j_schema_and_indexes e ontology_get_neo4j_schema_and_indexes (em paralelo). Se algum falhar:

"Não consigo acessar o banco de dados de [Documentos / Ontologia]. As configurações da extensão do Claude Desktop devem ter credenciais para ambos — por favor, abra Configurações → Extensões → Neo4j MCP Workspace e verifique os campos URI / nome de usuário / senha. Em seguida, feche e reabra o Claude Desktop."

Pare até o usuário corrigir.

0.2 Inspecione o que já existe

Para cada banco de dados, examine o esquema que você recebeu:

Banco de Ontologia — espera-se que contenha apenas nós :Ontology, :NodeType, :PropertyDef, :RelationshipType, :AliasMap, :Alias, :Blocklist, :BlockedTerm (o esquema está documentado em references/ontology-db-schema.md).

• Vazio → chame setup_ontology_db() para criar restrições. Continue.
• Contém nós de ontologia esperados → execute scripts/validate_ontology.cypher (via ontology_read_neo4j_cypher) e diga ao usuário:

  "Encontrei uma ontologia existente chamada '[nome]' com [N] tipos de entidade. Deseja continuar com esta ou começar do zero? (Começar do zero exclui a ontologia atual — seus documentos permanecem intactos.)"

• Contém rótulos inesperados → informe ao usuário o que está lá e pergunte se deseja limpar ou usar um banco de dados diferente.

Banco de Documentos — espera-se que contenha nós :Document, :Chunk, mais entidades extraídas.

• Vazio → continue, você o preencherá na Fase 3+.
• Contém Documentos e Chunks existentes → informe ao usuário quantos, pergunte "continuar com estes ou começar do zero?"
• Contém entidades extraídas (qualquer coisa que não seja :Document ou :Chunk) → informe ao usuário o que está lá e pergunte. Provavelmente ele executou o fluxo de trabalho antes; ofereça continuar a partir daí.

Se "começar do zero" — para o Banco de Ontologia, execute uma consulta de exclusão que remova apenas o grafo da ontologia (veja o cabeçalho de scripts/validate_ontology.cypher para o padrão exato). Para o Banco de Documentos, peça confirmação ao usuário antes de excluir (isso é destrutivo).

---

Fase 1 — Defina o caminho e pergunte qual fluxo

1.1 Diga ao usuário o que está prestes a acontecer

Em uma ou duas frases curtas, explique o que esta skill faz: projetar uma ontologia de domínio no Neo4j, opcionalmente combiná-la com documentos PDF para extrair entidades e responder perguntas.

Em seguida, pergunte:

"Duas opções: (a) apenas ontologia — projetamos o modelo juntos e paramos por aí, você pode usá-lo mais tarde, ou (b) ontologia + documentos — mesmo projeto, mas também analisamos uma pasta de PDFs e extraímos entidades para que você possa fazer perguntas sobre eles. Qual você prefere?"

Se (a) apenas ontologia → pule 1.2 e 1.3, vá direto para a Fase 2.2 (entrevista). Pule a Fase 7 completamente. Pare após a Fase 4.

Se (b) ontologia + documentos → continue para 1.2.

1.2 Obtenha o caminho da pasta

Pergunte ao usuário:

"Onde estão seus PDFs? Preciso do caminho de uma pasta local no seu computador (por exemplo /Users/seunome/Documentos/contratos/). Nota: se você fez upload de PDFs no chat do Claude Desktop, não consigo acessá-los — eles estão em um ambiente isolado que não posso ver. Coloque os arquivos em uma pasta local no seu Mac e me forneça esse caminho."

Se ele colar um único arquivo PDF, peça a pasta pai. Se colar uma referência de upload, repita a explicação gentilmente.

Não tente validar o caminho com a ferramenta Bash. No Claude Desktop, seu Bash é executado em um contêiner Linux e não consegue ver caminhos do Mac. As ferramentas MCP (create_lexical_graph e as demais) são executadas no Mac e podem ver o caminho — deixe-as validá-lo. Se o caminho estiver errado, você receberá uma mensagem de erro real da ferramenta; mostre-a ao usuário e peça um caminho corrigido.

Para a v1 desta skill, apenas arquivos .pdf são suportados. Se o usuário mencionar .docx, .txt, .md, .html, etc., diga que atualmente é apenas PDF; converter para PDF é a solução alternativa por enquanto.

---

Fase 2 — Caso de uso e perguntas de competência

Esta é a fase mais importante. Toda a ontologia depende das respostas aqui.

2.1 Inicie o grafo lexical em paralelo

Pule esta etapa completamente se o usuário escolheu o caminho apenas de ontologia.

Caso contrário, antes de iniciar a entrevista, inicie a análise do PDF para que os chunks existam quando você precisar amostrar o conteúdo. Chame:

create_lexical_graph(directory_path="<a pasta>", parse_mode="pymupdf")

pymupdf é o padrão rápido e funciona para PDFs nascidos digitais (o caso comum). Ele é executado em segundo plano — a chamada retorna imediatamente com um ID de job. Enquanto ele é executado, converse com o usuário. Você verificará a qualidade da análise e incorporará os chunks na Fase 3.1 (antes que o design da ontologia precise de evidências dos chunks). Se o pymupdf produziu chunks inutilizáveis, você recorrerá ao page_image lá — veja references/lexical-graph-pipeline.md.

Se create_lexical_graph retornar um erro (caminho não encontrado, permissão negada, nenhum PDF encontrado): mostre o erro real ao usuário, peça para corrigir o caminho e tente novamente. Não tente validar o caminho com Bash.

2.2 Entreviste o usuário

Pergunte, uma ou duas de cada vez, em linguagem simples:

1. Quem usará este grafo? (Só você? Uma equipe? Seus clientes?)
2. Que tipo de trabalho ele suporta? (Pesquisar um caso, encontrar precedentes, comparar contratos, auditar fornecedores, ...)
3. Quais perguntas você gostaria de fazer a esses documentos? Peça 5 a 10 perguntas específicas nas palavras deles. Exemplos para jurídico: "Quais contratos expiram nos próximos 90 dias?", "Quem assinou acordos com a parte X?", "Quais jurisdições aparecem em nossos contratos farmacêuticos?". Guarde estas — são as perguntas de competência que orientam a ontologia.
4. O que está fora do escopo? Que tipo de pergunta você NÃO está tentando responder com este grafo?

Se ele estiver inseguro, proponha perguntas de exemplo com base no domínio descrito (contratos jurídicos, arquivos de RH, registros regulatórios, ...) e peça sua reação. Assim que a Fase 3.1 produzir chunks limpos, você pode refinar as propostas com base no conteúdo real do documento.

2.3 Mostre o que se torna possível

Depois que eles listarem suas perguntas de competência, explique brevemente (uma frase cada) que tipo de operação de grafo responde a cada uma. Isso ensina a eles para que os grafos são bons, sem jargão. Exemplo:

"'Quais contratos expiram nos próximos 90 dias' — isso é um filtro em uma propriedade dos nós de contrato, fácil. 'Quem assinou acordos com a parte X' — isso é percorrer um relacionamento, que é exatamente onde os grafos brilham em comparação com uma planilha."

Este é o primeiro momento de demonstração. Mantenha-o curto.

---

Fase 3 — Projete a ontologia

Siga a metodologia em references/ontology-design-checklist.md. Resumo das regras (leia o arquivo completo — é o coração desta skill):

• Portão de inclusão: uma entidade, propriedade ou relacionamento é incluído apenas se (a) pelo menos uma pergunta de competência o exigir E (b) os documentos realmente contiverem evidência dele.
• Fundamentação de nível superior: escolha um pequeno conjunto de tipos de nível superior mutuamente exclusivos (ex.: Pessoa / Organização / Documento / Evento / Local). Coloque cada entidade sob exatamente um. Isso evita confusão posterior.
• Profundidade máxima 3: taxonomias profundas são hostis à extração. Prefira propriedades a subclasses.
• Definições aristotélicas: toda entidade recebe uma. "Um Contrato é um Documento que vincula partes a obrigações." Isso força clareza.

Para o caminho apenas de ontologia: pule 3.1 (sem chunks para verificar) e 3.2 (sem documentos para amostrar). Vá direto para 3.3.

3.1 Verifique a qualidade da análise, depois incorpore os chunks

Antes de usar os chunks como evidência para o design da ontologia, confirme que a análise do grafo lexical foi bem.

Primeiro, certifique-se de que o job terminou:

check_processing_status()

Aguarde até que o status seja completed. Em seguida, amostre os chunks:

// via documents_read_neo4j_cypher
MATCH (c:Chunk)
WITH c, rand() AS r ORDER BY r LIMIT 10
RETURN c.text

Observe a saída para:

• Chunks vazios ou quase vazios (alguns caracteres de espaço em branco) → pymupdf não obteve nada
• Ordem de colunas embaralhada (texto lê em ziguezague pela página) → layout de múltiplas colunas mal interpretado
• Caracteres distorcidos / não texto → provavelmente um PDF escaneado que o pymupdf não consegue ler

Se algum desses ocorrer, recorra totalmente ao modo page_image — veja references/lexical-graph-pipeline.md para o procedimento (exclua o grafo lexical via Cypher, execute novamente create_lexical_graph com parse_mode="page_image", depois generate_chunk_descriptions antes de embed_chunks). Informe brevemente ao usuário o que viu e que está mudando de modo; isso leva alguns minutos.

Se os chunks parecerem limpos, incorpore-os:

embed_chunks()

Isso é rápido e é executado em segundo plano. Em seguida, verifique se as incorporações realmente foram aplicadas:

// via documents_read_neo4j_cypher
MATCH (c:Chunk)
RETURN count(c) AS total, count(c.embedding) AS embedded

Se embedded < total, a incorporação está incompleta. Execute embed_chunks() novamente e verifique outra vez. Não prossiga até que embedded == total (ou a pesquisa vetorial falhará na Fase 8).

generate_chunk_descriptions é opcional no modo pymupdf. Execute-o apenas se o usuário esperar que a pesquisa vetorial também encontre imagens / tabelas / gráficos — isso adiciona tempo, mas permite que a incorporação cubra o conteúdo visual.

3.2 Amostre os chunks em busca de evidências

Agora use os chunks (verificados) para encontrar candidatos concretos a entidades:

// via documents_read_neo4j_cypher
MATCH (c:Chunk) RETURN c.text LIMIT 20

Não invente entidades que os documentos não suportam.

3.3 Proponha, depois escreva no Banco de Ontologia

Para cada tipo de entidade:

1. Proponha ao usuário: "Vejo Contrato, Parte e Jurisdição em seus documentos. Eu modelaria estes como: Contrato (entidade), Parte (entidade), Jurisdição (propriedade de Contrato). A justificativa: [uma frase]. OK?"
2. Após a confirmação, escreva no Banco de Ontologia via ontology_write_neo4j_cypher. Use MERGE (idempotente) seguindo o contrato em references/ontology-db-schema.md. Pontos críticos: todo :NodeType precisa de exatamente uma :PropertyDef com is_key=true. Nomes de propriedade usam camelCase. Nomes de tipos de relacionamento usam SCREAMING_SNAKE_CASE.

Momento de demonstração: quando o usuário contestar a decisão entre entidade e propriedade, explique a compensação. "Se tornarmos jurisdição uma entidade, podemos perguntar 'mostre todos os contratos nesta jurisdição agrupados por ano' facilmente. Como propriedade, isso ainda é possível, mas um pouco mais lento. Para 50 contratos não importa; para 50.000 pode fazer diferença."

3.4 Valide após cada lote

Depois de adicionar um lote de nós/relacionamentos à ontologia, execute o validador:

ontology_read_neo4j_cypher(query=<conteúdo de scripts/validate_ontology.cypher>)

Ele retorna uma lista de problemas. Se houver algum, corrija-os antes de prosseguir. Esta é sua rede de segurança contra desvio de esquema.

Quando a ontologia for validada, passe para a Fase 4.

---

Fase 4 — Persista e confirme

4.1 Escreva a ontologia final

Execute uma consulta Cypher para garantir que todos os nós e relacionamentos da ontologia estejam no banco de dados. Use MERGE para evitar duplicatas.

4.2 Valide novamente

Repita a validação da Fase 3.4.

4.3 Mostre ao usuário

Use ontology_read_neo4j_cypher para buscar um resumo da ontologia e mostre-o ao usuário em linguagem simples:

"Sua ontologia contém:

• [N] tipos de entidade, incluindo [lista]
• [M] tipos de relacionamento, incluindo [lista]
• Você pode [ação que o grafo agora suporta]"

Pergunte se parece correto.

4.4 Se apenas ontologia — finalize

Se o usuário escolheu o caminho apenas de ontologia, este é o ponto final. Diga:

"A ontologia está pronta no Neo4j. Você pode abri-la no Neo4j Bloom ou no Neo4j Browser para explorar. Links e instruções: [forneça orientação]."

Pare aqui.

---

Fase 5 — Gere o esquema de extração (apenas para o caminho de documentos)

Pule esta fase se o caminho for apenas de ontologia.

Chame:

generate_schema_from_ontology()

Isso traduz a ontologia (nós e relacionamentos) em um esquema que o extrator de entidades entende.

Verifique se foi bem-sucedido. Se falhar, provavelmente é porque a ontologia está incompleta ou viola as regras (por exemplo, um :NodeType sem :PropertyDef com is_key=true). Corrija e tente novamente.

---

Fase 6 — Extraia entidades (apenas para o caminho de documentos)

Pule esta fase se o caminho for apenas de ontologia.

Chame:

extract_entities()

Isso é um job assíncrono. Acompanhe com check_extraction_status().

Enquanto espera (alguns minutos), você pode conversar com o usuário sobre o que está acontecendo em segundo plano: "O extrator está percorrendo seus documentos, identificando instâncias de Contrato, Parte, etc., e conectando-as aos chunks."

Se a extração falhar, verifique os logs (se disponíveis) e corrija. Causas comuns: ontologia muito grande para o modelo de extração, chunks muito grandes.

---

Fase 7 — Valide a extração (apenas para o caminho de documentos)

Pule esta fase se o caminho for apenas de ontologia.

Após a extração ser concluída, verifique a qualidade:

// via documents_read_neo4j_cypher
// Conte entidades extraídas por tipo
MATCH (n) WHERE n:Document OR n:Chunk
RETURN labels(n) AS tipo, count(*) AS total

Mostre ao usuário um resumo: "Encontrei [N] instâncias de Contrato, [M] instâncias de Parte, ..."

Pergunte: "Isso parece razoável?"

Se o usuário disser que está faltando algo, você pode tentar reextrair com parâmetros ajustados (se disponível) ou adicionar manualmente algumas entidades (caso raro).

---

Fase 8 — Pergunte e refine (apenas para o caminho de documentos)

Pule esta fase se o caminho for apenas de ontologia.

8.1 Demonstre as perguntas de competência

Pegue as perguntas que o usuário forneceu na Fase 2. Para cada uma, mostre como o grafo pode respondê-la:

• Se for uma consulta direta (contagem, filtro, agregação), escreva uma consulta Cypher e execute-a via documents_read_neo4j_cypher.
• Se for uma pergunta semântica (