OrionBelt Analytics

Analisa esquemas de bancos de dados relacionais (PostgreSQL, Snowflake e Dremio) e gera automaticamente ontologias abrangentes no formato RDF/Turtle com mapeamentos diretos para SQL.

GitHub

Experimente este MCPPatrocinado

Documentação

OrionBelt Logo

OrionBelt® Analytics

O servidor MCP baseado em ontologia para sua conveniência de Text-2-SQL.

O OrionBelt Analytics é um servidor MCP que analisa esquemas de bancos de dados relacionais e gera ontologias RDF/OWL com mapeamentos SQL incorporados. Ele fornece Texto-para-SQL com consciência de relacionamentos e prevenção automática de fan-trap, GraphRAG para descoberta inteligente de esquemas e gráficos interativos — tudo acessível por qualquer cliente de IA compatível com MCP.

O Ecossistema OrionBelt

Projeto	Propósito
OrionBelt Analytics (este)	Análise de esquemas, geração de ontologias, GraphRAG, Texto-para-SQL
OrionBelt Semantic Layer	Modelos YAML declarativos compilados em SQL específico por dialeto e sem fan-trap
OrionBelt Ontology Builder	Editor visual de ontologias OWL com raciocínio e visualização de grafos (demonstração ao vivo)
OrionBelt Chat	Interface de chat de IA para Analytics + Semantic Layer (Chainlit, múltiplos provedores de LLM)

Execute Analytics e Semantic Layer lado a lado no Claude Desktop para geração de ontologias com consciência de esquema e compilação de SQL com correção garantida.

Arquitetura

OrionBelt Analytics Architecture

8 conectores de banco de dados -- PostgreSQL, MySQL, Snowflake, ClickHouse, Dremio, BigQuery, DuckDB/MotherDuck, Databricks SQL
Geração de ontologias RDF/OWL com anotações SQL de namespace oba: e mapeamentos W3C R2RML
GraphRAG -- travessia de grafos (até 12 saltos) + embeddings vetoriais ChromaDB para descoberta semântica de esquemas
Interface de consulta SPARQL 1.1 via armazenamento RDF Oxigraph persistente
Validação OBQC -- verificações SQL determinísticas contra a ontologia (existência de tabelas/colunas, validade de junções, incompatibilidades de tipos, fan-traps)
Gráficos interativos -- gráficos Plotly com renderização MCP-UI no Claude Desktop
Suporte a múltiplos esquemas -- analise vários esquemas simultaneamente; o estado da ontologia e do GraphRAG é isolado por esquema
Persistência do espaço de trabalho -- reconecte-se ao mesmo banco de dados e restaure sua sessão anterior
Amostragem MCP -- quando o cliente conectado suporta amostragem (ex.: OrionBelt Chat), o suggest_semantic_names solicita ao LLM do host que pré-preencha sugestões de renomeação para identificadores crípticos via sampling/createMessage, reduzindo o fluxo anterior de revisar-depois-aplicar a uma única chamada de ferramenta. Clientes sem suporte a amostragem (ex.: Claude Desktop) usam silenciosamente o caminho de revisão manual

OBQC -- Verificação de Consultas Baseada em Ontologia

Um diferencial importante do OrionBelt é o OBQC (Ontology-Based Query Check), um validador SQL determinístico baseado em regras que detecta erros antes que as consultas cheguem ao banco de dados. Diferente de abordagens somente com LLM que dependem do modelo "acertar", o OBQC cruza referências de cada instrução SQL gerada com a ontologia RDF/OWL carregada para impor a correção estrutural.

O que o OBQC valida:

Verificação	O que ela detecta
Existência de tabela	Referências a tabelas que não existem no esquema
Existência de coluna	Referências a colunas ausentes em sua tabela, colunas não qualificadas ambíguas
Validade da junção	Condições de junção ausentes (produtos cartesianos), colunas de junção que não correspondem a chaves estrangeiras declaradas
Compatibilidade de tipos	Comparações WHERE/ON entre tipos incompatíveis (ex.: string vs. inteiro)
Correção da agregação	Colunas SELECT ausentes do GROUP BY quando agregações são usadas
Detecção de fan-trap	Agregações em múltiplas junções um-para-muitos que multiplicam silenciosamente os resultados

Como funciona:

generate_ontology ou load_my_ontology cria/carrega uma ontologia com anotações de namespace oba: que mapeiam classes e propriedades OWL para tabelas, colunas, tipos e chaves estrangeiras reais do banco de dados.
Quando execute_sql_query é chamado, o OBQC analisa o SQL com sqlglot e valida cada tabela, coluna, junção e agregação contra o modelo de esquema da ontologia.
Os problemas são retornados com níveis de gravidade (erro, aviso, informação) junto com os resultados da consulta, para que o LLM possa se autocorrigir antes que o usuário veja dados errados.

O OBQC é totalmente determinístico -- sem chamadas de LLM, sem raciocínio probabilístico. Ele atua como uma rede de segurança que complementa a geração de SQL do LLM com garantias estruturais rígidas. Erros bloqueiam a execução da consulta; avisos são anexados à resposta para o LLM agir. Consulte a documentação do OBQC para a referência completa de regras, comportamento de gravidade e requisitos de anotação.

Início Rápido

1. Instalação

git clone https://github.com/ralforion/orionbelt-analytics
cd orionbelt-analytics
uv sync

Requer Python 3.13+ e uv.

2. Configuração

cp .env.template .env

Edite .env com suas credenciais de banco de dados. No mínimo, defina as variáveis para um banco de dados (ex.: POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DATABASE, POSTGRES_USERNAME, POSTGRES_PASSWORD).

Consulte docs/configuration.md para todas as variáveis de ambiente, opções de transporte e solução de problemas.

3. Execução

uv run server.py

O servidor inicia em http://localhost:9000 (transporte HTTP, configurável via MCP_SERVER_PORT).

Conecte Seu Cliente de IA

Claude Desktop

Inicie o servidor e adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "OrionBelt-Analytics": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:9000/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

Claude Code

claude mcp add orionbelt-analytics http://localhost:9000/mcp

LibreChat

Defina MCP_TRANSPORT=sse em .env, reinicie o servidor e adicione a librechat.yaml:

mcpServers:
  OrionBelt-Analytics:
    url: "http://host.docker.internal:9000/sse"
    timeout: 60000
    startup: true

Outros Frameworks

O OrionBelt funciona com LangChain, OpenAI Agents SDK, CrewAI, Google ADK, Vercel AI SDK, n8n e ChatGPT Custom GPTs. Consulte docs/integrations.md para exemplos de configuração.

Ferramentas

O OrionBelt expõe 26 ferramentas MCP. Aqui está um resumo por categoria:

Conexão e Esquema

Ferramenta	Descrição
`connect_database`	Conecte-se a qualquer banco de dados suportado usando credenciais `.env`
`list_databases`	Liste os bancos de dados configurados no servidor, por nome e descrição
`list_schemas`	Liste os esquemas disponíveis no banco de dados conectado
`reset_cache`	Limpe os dados de esquema e ontologia em cache para a sessão atual
`discover_schema`	Analise a estrutura do esquema com geração automática de GraphRAG + ontologia
`get_table_details`	Obtenha informações detalhadas de colunas, chaves e restrições para uma tabela específica
`cleanup_workspace`	Exclua todos os arquivos do espaço de trabalho para a conexão atual e comece do zero

Ontologia e Semântica

Ferramenta	Descrição
`generate_ontology`	Gere ontologia RDF/OWL a partir do esquema com anotações de mapeamento SQL
`suggest_semantic_names`	Detecte abreviações e nomes crípticos para renomeação amigável aos negócios
`apply_semantic_names`	Aplique nomes e descrições semânticos sugeridos pelo LLM à ontologia
`load_my_ontology`	Carregue um arquivo de ontologia `.ttl` personalizado de uma pasta de importação
`download_artifact`	Baixe a ontologia ou o mapeamento R2RML como um arquivo Turtle

Consulta e Visualização

Ferramenta	Descrição
`sample_table_data`	Visualize dados de tabela com limite de linhas e proteção contra injeção
`execute_sql_query`	Execute SQL com validação OBQC, verificações de segurança e detecção de fan-trap
`generate_chart`	Gere gráficos Plotly (barras, linhas, dispersão, mapa de calor) com renderização MCP-UI

GraphRAG

Ferramenta	Descrição
`graphrag_search`	Pesquisa semântica + visão geral do esquema (auto-inicializada por `discover_schema`)
`graphrag_query_context`	Obtenha contexto otimizado para geração de SQL (redução de 85-95% de tokens)
`graphrag_find_join_path`	Descubra caminhos de junção entre tabelas via travessia de grafos
`reachable_from`	Tabelas com capacidade de dimensão para um grão âncora (fechamento muitos-para-um)
`measurable_from`	Tabelas com capacidade de medida para um grão âncora (fechamento um-para-muitos)
`plan_composite_query`	Recomende uma decomposição de Camada de Fatos Composta segura contra fan-trap (UNION ALL)

SPARQL e RDF

Ferramenta	Descrição
`store_ontology_in_rdf`	Persista a ontologia no Oxigraph para acesso SPARQL
`query_sparql`	Execute consultas SPARQL (SELECT, ASK, CONSTRUCT — detecção automática)
`add_rdf_knowledge`	Adicione triplas de metadados personalizadas ao armazenamento RDF

Modelos Semânticos

Ferramenta	Descrição
`save_semantic_model`	Salve um modelo semântico (ex.: OBML YAML) no espaço de trabalho
`get_semantic_model`	Recupere um modelo semântico armazenado pelo nome
`list_semantic_models`	Liste todos os modelos semânticos armazenados para a conexão atual

Para detalhes completos de parâmetros, valores de retorno e exemplos, consulte docs/tools-reference.md.

Fluxos de Trabalho Típicos

Sessão de análise completa:

connect_database("postgresql") -> discover_schema("public") -> generate_ontology() -> execute_sql_query(...)

Exploração rápida de dados:

connect_database("duckdb") -> list_schemas() -> sample_table_data("events")

Consulta com visualização:

execute_sql_query(query) -> generate_chart(data, "bar", ...)

execute_sql_query executa validação OBQC, verificações de segurança e detecção de fan-trap antes de executar — nenhuma etapa de validação separada é necessária.

Retomar uma sessão anterior (restaura automaticamente o espaço de trabalho):

connect_database("postgresql") -> execute_sql_query(...)

Desenvolvimento

uv sync instala tudo; uv run pytest, black/isort/ruff e o modo estrito mypy são os portões. O Guia de desenvolvimento contém a configuração completa, a estrutura do projeto e a lista de verificação para contribuições.

Uma coisa que vale a pena saber antes de abrir um arquivo de workflow: cada GitHub Action é fixada em um SHA de commit de 40 caracteres com um comentário # vX.Y.Z, que é o motivo de estarem cheios de hexadecimais. Uma tag git é um rótulo móvel, então actions/checkout@v7 executa qualquer commit para o qual esse rótulo aponta quando o job inicia; um SHA não pode se mover. Os comentários nomeiam versões de patch exatas em vez de # v7, porque uma tag principal se move a cada lançamento upstream. ./scripts/check-action-pins.sh resolve cada tag upstream e falha quando o commit que ela nomeia não é o fixado — que é a única coisa que distingue um bump real de um hash silenciosamente trocado por um proveniente de um fork. Ele roda como o job pins em cada pull request e como o primeiro passo de ambos os workflows de publicação; --offline pula as consultas upstream e verifica apenas o SHA e o formato do comentário.

Documentação

Documento	Conteúdo
Referência de Ferramentas	Documentação completa de parâmetros, valores de retorno e exemplos de uso
Configuração	Variáveis de ambiente, configuração de transporte, solução de problemas
GraphRAG	Inteligência de esquema baseada em grafos e fluxo de trabalho OBML
Visão Geral do OBQC	Explicação breve de como o OBQC funciona dentro do OrionBelt Analytics
OBQC	Regras de validação, níveis de severidade, comportamento de bloqueio, requisitos de anotação
Prevenção de Fan-Trap	O problema do fan-trap, detecção e padrões SQL seguros
Integrações	LangChain, OpenAI, CrewAI, Google ADK, Vercel, n8n, ChatGPT
Desenvolvimento	Estrutura do projeto, testes, contribuição

Licença

Licenciado sob a Business Source License 1.1. O Trabalho Licenciado será convertido para a Apache License 2.0 em 2030-03-16.

Ao contribuir para este projeto, você concorda com o Contrato de Licença de Contribuidor.

Para consultas de licenciamento comercial, entre em contato: licensing@ralforion.com

Software de terceiros

OrionBelt Analytics é construído sobre código aberto. THIRD_PARTY_NOTICES.md lista cada dependência incluída com sua licença e destaca as poucas que carregam obrigações além da atribuição (o LGPL do psycopg2, os dados CC-BY-SA do wordfreq, os componentes MPL-2.0).

A imagem Docker redistribui esses pacotes, então ela inclui os textos de licença verbatim em /app/licenses/THIRD_PARTY_LICENSES.txt, junto com os arquivos de direitos autorais do Debian em /usr/share/doc/. A wheel do PyPI não inclui nada de terceiros — ela declara suas dependências e o instalador as busca no PyPI.