1 Synesis2Neo4j: Pipeline de Grafos de Conhecimento

Versão 0.1.0

1.1 Introdução

O synesis2neo4j é o pipeline oficial de ingestão da linguagem Synesis para bancos de grafos Neo4j. Ele transforma análises qualitativas estruturadas em grafos de conhecimento navegáveis e prontos para IA (GraphRAG).

1.1.1 Diagrama de Fluxo

graph TD
    %% --- Paleta Synesis 2.0 ---
    %% Primary: #084C54 (Teal Profundo)
    %% Accent: #00BFA5 (Mint/Cyan)

    classDef files fill:#F8FAFC,stroke:#4A5568,stroke-width:1px,color:#084C54
    classDef engine fill:#fff,stroke:#084C54,stroke-width:3px,color:#084C54,font-weight:bold
    classDef data fill:#E0F7FA,stroke:#084C54,stroke-width:1px,color:#084C54
    classDef graphDb fill:#E0F7FA,stroke:#00BFA5,stroke-width:2px,color:#084C54
    classDef agent fill:#084C54,stroke:#00BFA5,stroke-width:2px,color:#fff
    classDef metrics fill:#F8FAFC,stroke:#00BFA5,stroke-width:1px,color:#084C54

    subgraph INPUT["1. Entrada: Pesquisa como Código"]
        SYN["Corpus Anotado (.syn)"]:::files
        SYNO["Ontologia (.syno)"]:::files
        SYNP["Projeto (.synp)"]:::files
        SYNT["Template (.synt)"]:::files
    end

    subgraph ENGINE["2. Synesis Engine"]
        COMPILER[/"synesis.load"/]:::engine
        VALIDATOR("Validação Semântica"):::engine
    end

    SYNP --> COMPILER
    SYN --> COMPILER
    SYNO --> COMPILER
    SYNT --> COMPILER
    COMPILER --> VALIDATOR

    subgraph STRUCTURED["3. Dados Estruturados"]
        JSON["Objeto Canônico (Rastreável)"]:::data
        SCHEMA["Schema Dinâmico (do Template)"]:::data
    end

    VALIDATOR -->|Sucesso| JSON
    SYNT -.->|Define| SCHEMA

    subgraph GRAPH["4. Grafo de Conhecimento"]
        NEO4J[("Neo4j")]:::graphDb
        NATIVE["Métricas Nativas (Cypher)"]:::graphDb
        GDS["Métricas GDS (Opcional)"]:::graphDb
        DEG["Degree Centralidade"]:::metrics
        PR["PageRank Relevância"]:::metrics
        BC["Betweenness Pontes"]:::metrics
        COM["Louvain Comunidades"]:::metrics
    end

    JSON -->|Sync| NEO4J
    SCHEMA -->|Sync| NEO4J
    NEO4J --> NATIVE
    NATIVE --> GDS
    NATIVE -.-> DEG
    GDS -.-> PR
    GDS -.-> BC
    GDS -.-> COM

    subgraph CONSUMPTION["5. Consumo Inteligente"]
        MCP["Agente MCP"]:::agent
        LLM["LLMs / Claude"]:::agent
    end

    NEO4J -->|GraphRAG| MCP
    MCP -->|GraphRAG| NEO4J
    MCP -->|Consultas| LLM
    LLM -->|Consultas| MCP

    %% Estilos dos Subgrafos
    style INPUT fill:transparent,stroke:#4A5568,stroke-width:1px,stroke-dasharray:5 5,color:#084C54
    style ENGINE fill:transparent,stroke:#4A5568,stroke-width:1px,stroke-dasharray:5 5,color:#084C54
    style STRUCTURED fill:transparent,stroke:#4A5568,stroke-width:1px,stroke-dasharray:5 5,color:#084C54
    style GRAPH fill:transparent,stroke:#4A5568,stroke-width:1px,stroke-dasharray:5 5,color:#084C54
    style CONSUMPTION fill:transparent,stroke:#4A5568,stroke-width:1px,stroke-dasharray:5 5,color:#084C54

    linkStyle default stroke:#64748B,stroke-width:1px

1.1.2 Características Principais

Recurso Descrição
Zero-IO Compila em memória via synesis.load(), sem arquivos intermediários
Universal Lê o Template (.synt) e cria estrutura do grafo dinamicamente
Métricas Automáticas Calcula métricas nativas (Cypher) e avançadas (GDS)
Rastreabilidade Mantém metadados de origem em todos os nós e arestas
Atomicidade Sincronização via transação única

1.1.3 Casos de Uso

  • Pesquisa Qualitativa: Visualizar e navegar redes de conceitos
  • Análise Bibliométrica: Mapear relações entre fatores em literatura
  • GraphRAG: Alimentar agentes de IA com conhecimento estruturado
  • Data Science: Aplicar algoritmos de rede (PageRank, Louvain, Betweenness)

1.2 Pré-requisitos

1.2.1 Software Necessário

Software Versão Link
Python 3.11+ python.org
Neo4j 5.x Neo4j Download

1.2.2 Opções de Instalação do Neo4j

1.2.2.1 Neo4j Desktop (Recomendado para desenvolvimento)

Interface gráfica completa para gerenciar múltiplos bancos locais.

  1. Baixe em: neo4j.com/download
  2. Instale e crie um novo projeto
  3. Adicione um banco de dados local (DBMS)
  4. Inicie o banco e anote a senha

1.2.2.2 Neo4j Community Server

Para servidores ou ambientes headless.

# Docker (mais simples)
docker run -d \
    --name neo4j \
    -p 7474:7474 -p 7687:7687 \
    -e NEO4J_AUTH=neo4j/sua_senha_segura \
    neo4j:5

1.2.2.3 Neo4j Aura (Cloud)

Banco gerenciado na nuvem, ideal para produção.

  1. Acesse: console.neo4j.io
  2. Crie uma instância Free ou Professional
  3. Copie as credenciais de conexão

1.3 Instalação

1.3.1 Requisitos Python

pip install synesis neo4j rich tomli

1.3.2 Clonar o Repositório

git clone https://github.com/synesis-lang/synesis2neo4j.git
cd synesis2neo4j

1.3.3 Verificar Instalação

python synesis2neo4j.py --version
# synesis2neo4j 0.1.0

1.3.4 Plugin GDS (Opcional)

Para métricas avançadas (PageRank, Betweenness, Louvain), instale o Neo4j Graph Data Science:

Neo4j Desktop: 1. Abra seu projeto 2. Clique em “Plugins” no painel do banco 3. Instale “Graph Data Science Library”

Neo4j Server:

# Baixe o JAR correspondente à sua versão
# Copie para a pasta plugins/ do Neo4j
# Reinicie o servidor

1.4 Configuração

1.4.1 Arquivo config.toml

Crie um arquivo config.toml na raiz do projeto:

[neo4j]
uri = "bolt://localhost:7687"
user = "neo4j"
password = "sua_senha_secreta"
database = "neo4j"  # Opcional, default é 'neo4j'

1.4.2 Parâmetros de Configuração

Parâmetro Tipo Obrigatório Descrição
uri str Sim URI de conexão (bolt:// ou neo4j://)
user str Sim Usuário do banco
password str Sim Senha do banco
database str Não Nome do banco (default: neo4j)

1.4.3 Exemplos de URI

Ambiente URI
Local (Desktop/Docker) bolt://localhost:7687
Neo4j Aura neo4j+s://xxxx.databases.neo4j.io
Servidor remoto bolt://192.168.1.100:7687

1.5 Uso

1.5.1 Comando Básico

python synesis2neo4j.py --project ./meu_projeto/analise.synp

1.5.2 Opções de Linha de Comando

Opção Descrição
--project Caminho para o arquivo .synp (obrigatório)
--config Arquivo de configuração (default: config.toml)
--version, -v Exibe versão do script

1.5.3 Exemplo Completo

# Com configuração padrão
python synesis2neo4j.py --project ./pesquisa/bibliometria.synp

# Com configuração customizada
python synesis2neo4j.py --project ./analise.synp --config producao.toml

1.6 Fluxo de Execução

O pipeline executa as seguintes etapas em sequência:

1.6.1 1. Compilação (In-Memory)

[>] Starting Synesis compiler at: ./projeto.synp
[+] Compilation OK. 150 items processed.

O compilador Synesis valida sintaxe e semântica. Erros interrompem o processo sem tocar no banco.

1.6.2 2. Carregamento de Configuração

[>] Loading Configuration
[+] Loading Configuration completed.

Lê credenciais do config.toml.

1.6.3 3. Criação/Verificação do Banco

[>] Target database: meu-projeto
[>] Checking/Creating Database
[+] Database already exists: meu-projeto

Cria banco automaticamente se não existir (requer Neo4j Enterprise/Aura).

1.6.4 4. Sincronização do Grafo

[>] Synchronizing Graph (Transactional)
[+] Synchronizing Graph (Transactional) completed.

Limpa banco anterior e injeta novos dados em transação atômica.

1.6.5 5. Métricas Nativas

[>] Calculating Native Metrics
[+] Calculating Native Metrics completed.

Calcula degree, mention_count, source_count via Cypher puro.

1.6.6 6. Métricas GDS (se disponível)

[>] GDS graph strategy: RELATES_TO
[>] GDS projection: 45 nodes, 120 relationships
[+] PageRank calculated
[+] Betweenness calculated
[+] Communities (Louvain) calculated

Se o plugin GDS não estiver instalado, exibe aviso e continua:

[!] GDS not installed. Install the Graph Data Science plugin for
    advanced metrics (PageRank, Betweenness, Communities).

1.7 Modelagem de Dados

1.7.1 Template → Grafo

O pipeline traduz automaticamente os tipos de campo do Template para estruturas no grafo:

Tipo no Template Elemento no Grafo Relação Criada
CODE Nó Conceito (label dinâmico) MENTIONS (Item → Conceito)
TOPIC Nó Taxonomia GROUPED_BY
ASPECT Nó Taxonomia QUALIFIED_BY
DIMENSION Nó Taxonomia BELONGS_TO
CHAIN Relação Explícita RELATES_TO
TEXT / MEMO Propriedade —
ENUMERATED Propriedade —

1.7.2 Nós Base

Nó Descrição Propriedades Principais
Source Fonte bibliográfica bibtex, title, author, year, doi
Item Unidade de citação item_id, citation, description

1.7.3 Relações Principais

Relação Origem Destino Descrição
FROM_SOURCE Item Source Rastreabilidade da citação
MENTIONS Item Conceito Citação menciona conceito
GROUPED_BY Conceito Topic Classificação temática
QUALIFIED_BY Conceito Aspect Qualificação dimensional
BELONGS_TO Conceito Dimension Agregação de alto nível
RELATES_TO Conceito Conceito Relação explícita (CHAIN)
IS_LINKED_TO Topic Topic Co-taxonomia ponderada
MAPPED_TO_ASPECT Topic Aspect Mapeamento entre taxonomias
MAPPED_TO_DIMENSION Topic Dimension Mapeamento entre taxonomias

1.8 Métricas de Grafo

1.8.1 Métricas Nativas (Sempre Disponíveis)

Calculadas via Cypher puro, sem dependências externas.

1.8.1.1 Nós de Conceito

Métrica Descrição Uso Analítico
degree Grau total (in + out) Conectividade geral
in_degree Relações recebidas Conceitos que referenciam este
out_degree Relações emitidas Conceitos referenciados por este
mention_count Citações que mencionam Frequência nos dados primários
source_count Fontes distintas Dispersão/generalização

1.8.1.2 Nós de Taxonomia

Métrica Descrição Uso Analítico
concept_count Conceitos classificados Abrangência da categoria
weighted_degree Soma dos pesos IS_LINKED_TO Força das relações inter-taxonomia
aspect_diversity Aspectos distintos Diversidade qualitativa
dimension_diversity Dimensões distintas Dispersão dimensional

1.8.1.3 Nós de Source

Métrica Descrição Uso Analítico
item_count Citações extraídas Volume de dados da fonte
concept_count Conceitos mencionados Riqueza conceitual

1.8.2 Métricas GDS (Requer Plugin)

Métrica Algoritmo Descrição
pagerank PageRank Relevância baseada em conexões
betweenness Betweenness Centrality Papel de “ponte” entre clusters
community Louvain Detecção de comunidades temáticas

1.8.2.1 Estratégias de Projeção

Estratégia Quando Usada Descrição
RELATES_TO Templates com CHAIN Usa relações explícitas
CO_TAXONOMY Templates com CODE + TOPIC Conecta via taxonomia compartilhada
CO_CITATION Fallback Conecta via co-ocorrência em fontes

1.9 Consultas Cypher

1.9.1 Conceitos Mais Centrais

MATCH (c:Concept)
WHERE c.pagerank IS NOT NULL
RETURN c.name, c.pagerank, c.mention_count, c.community
ORDER BY c.pagerank DESC
LIMIT 10

1.9.2 Comunidades Temáticas

MATCH (c:Concept)
WHERE c.community = 1
RETURN c.name, c.pagerank, c.degree
ORDER BY c.pagerank DESC

1.9.3 Rede de Relações

MATCH (s:Concept)-[r:RELATES_TO]->(t:Concept)
RETURN s.name AS source, r.type AS relation, t.name AS target
ORDER BY s.name

1.9.4 Rastreabilidade Completa

MATCH (i:Item)-[:MENTIONS]->(c:Concept)
MATCH (i)-[:FROM_SOURCE]->(s:Source)
WHERE c.name = "Cost"
RETURN s.title, i.citation, c.name

1.9.5 Tópicos Interconectados

MATCH (t1:Topic)-[r:IS_LINKED_TO]->(t2:Topic)
RETURN t1.name, t2.name, r.strength
ORDER BY r.strength DESC
LIMIT 20

1.10 Integração com Agentes MCP

1.10.1 O que é MCP?

O Model Context Protocol (MCP) permite que LLMs (como Claude) interajam com fontes de dados externas. Com o servidor MCP Neo4j, Claude pode consultar seu grafo diretamente.

1.10.2 Instalação do Claude Desktop

  1. Baixe em: claude.ai/download
  2. Instale e faça login com sua conta Anthropic
  3. Configure o servidor MCP (próxima seção)

1.10.3 Configuração do Servidor MCP

Instale o gerenciador de pacotes uv:

pip install uv

Edite o arquivo claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "synesis-neo4j": {
      "command": "uvx",
      "args": ["mcp-neo4j-cypher@0.5.2", "--read-only"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "sua_senha",
        "NEO4J_DATABASE": "nome_do_banco"
      }
    }
  }
}

1.10.4 Exemplos de Perguntas para Claude

Pergunta O que Retorna
“Quais conceitos têm maior PageRank?” Top conceitos por relevância
“Mostre as fontes que mencionam ‘Acceptance’” Rastreabilidade Item → Source
“Quais conceitos pertencem à comunidade 1?” Análise de clusters
“Compare as métricas dos principais conceitos” Tabela comparativa
“Qual a estrutura do grafo?” Schema e contagens

1.11 Tratamento de Erros

1.11.1 Erros de Compilação

[x] Compiling Project (In-Memory) failed: ...

┌─────────────────────────────────┐
│ Compilation Diagnostics         │
├─────────────────────────────────┤
│ error: sample.syn:15:8          │
│ Undefined reference '@missing'  │
└─────────────────────────────────┘

O banco não é modificado se houver erros de compilação.

1.11.2 Erros de Conexão

[x] [connection] Failed to connect to Neo4j
    Details: Unable to retrieve routing information

Verifique: - Neo4j está em execução - URI e credenciais estão corretos - Firewall permite conexão na porta 7687

1.11.3 Erros de Sincronização

[x] [sync] Synchronization failed
    Details: Transaction timeout

Para grafos muito grandes, considere aumentar o timeout do Neo4j.

1.12 Estrutura do Projeto

synesis2neo4j/
├── synesis2neo4j.py      # Script principal
├── config.toml           # Configuração (criar)
├── README.md             # Documentação em inglês
├── README.pt.md          # Documentação em português
└── mcp/
    ├── SETUP.md          # Guia de configuração MCP
    ├── QUERIES_REFERENCE.md  # Referência de queries
    └── claude_desktop_config.template.json

1.13 Referência Rápida

1.13.1 Instalação

pip install synesis neo4j rich tomli
git clone https://github.com/synesis-lang/synesis2neo4j.git

1.13.2 Configuração

# config.toml
[neo4j]
uri = "bolt://localhost:7687"
user = "neo4j"
password = "senha"

1.13.3 Execução

python synesis2neo4j.py --project ./projeto.synp

1.13.4 Verificação no Neo4j Browser

// Contar nós
MATCH (n) RETURN labels(n)[0] AS label, count(*) AS count

// Ver métricas
MATCH (c:Concept) RETURN c.name, c.pagerank, c.community LIMIT 10