schemabrain

Pare de dar strings de conexão brutas de banco de dados para agentes de IA.

Dê a eles o SchemaBrain — uma camada de confiança e inteligência somente-leitura onde o agente nunca escreve SQL, PII é recusada antes de a consulta ser executada, e cada chamada é registrada em um log de auditoria à prova de adulteração.

Funciona com Claude Desktop · Claude Code · Cursor · Windsurf · qualquer host MCP

O SchemaBrain compila toda consulta a partir de definições que você controla — não existe caminho de um prompt até SQL bruto no seu banco de dados.

Três garantias que eliminam a lacuna de confiança entre agentes de IA e seu banco de dados:

• Somente-leitura por arquitetura — doze ferramentas MCP, nenhuma das quais pode escrever. Sem ferramenta execute(), sem ferramenta query(), sem caminho de prompt de agente até uma escrita no seu banco de dados.
• Recusa com ciência de PII na recuperação — tags de PII se propagam do esquema físico através de joins e métricas. Se uma consulta toca uma categoria bloqueada, o SchemaBrain recusa antes de o banco de dados ser consultado.
• Cadeia de auditoria criptográfica — toda chamada, recusa e recuperação é registrada em um log somente-acréscimo com hash SHA256 (melhor esforço: uma configuração de disco cheio ou sem writer registra um aviso e continua em vez de falhar a consulta). audit verify sai com código não-zero se qualquer linha passada foi reescrita.

Veja em ação — peça algo que o esquema não pode responder, e ele recusa em vez de inventar um join:

Você: calcule o volume de uso por faixa de plano

SchemaBrain → agente: { "kind": "unreachable_entity", "recovery": { "suggested_tool": "resolve_join" } } — não há plan_id em eventos de uso, então ele não vai inventar um.

Claude: Não posso inventar esse join — aqui está receita contratada por faixa de plano no lugar, que resolve de verdade. ✓

→ Sessão completa, com o SQL e os resultados

Veja rodando — um esquema Postgres ao vivo se torna um grafo de conhecimento governado, o firewall calcula a métrica segura e recusa os vazamentos, e cada chamada é registrada em um log de auditoria à prova de adulteração. Sem agente, sem chave de API:

---

uvx schemabrain init
# then: Cmd+Q Claude Desktop, relaunch, and ask: "list the entities SchemaBrain knows about"
# prefer a persistent install? pipx install schemabrain (or) pip install schemabrain

Custo: $0 para rodar a demo inclusa (pacote pré-curado, sem chave de API) · ~$0,03 para indexar via LLM um esquema novo de 84 colunas · $0 para reindexar esquemas inalterados. Detalhes em Sessão de exemplo.

Status: 0.6.0 (beta). Postgres suportado hoje (o armazenamento local em si é SQLite). Conectores de origem SQLite / Snowflake / BigQuery / MySQL no roadmap.

---

Conteúdo

Leia a seguir com base no que você precisa:

Objetivo	Onde ir
Experimente com o fixture incluso	Início rápido
Entenda as garantias de segurança	Garantias de segurança
Configure seu cliente MCP	Claude Desktop · Claude Code · Cursor · Windsurf · Cline · ChatGPT (roadmap)
Integre ao seu próprio loop de agente	docs/setup/manual.md
Construa uma camada semântica	docs/semantic-layer.md
Rode em produção (auditoria, drift, Docker)	docs/operations.md
Observe o agente (tail, log de auditoria, OTel)	docs/observability.md
Compare com Querybear / MCP Postgres de referência da Anthropic	vs Querybear · vs referência Anthropic
Compare com Vanna / Atlan / dbt-mcp / WrenAI	docs/landscape.md

---

Início rápido

Só quer ver o que faz? uvx schemabrain demo — um comando, zero prompts. Constrói a camada SaaS de exemplo e depois permite abrir o dashboard ou rodar uma demonstração de firewall no terminal. Sem chave de API, e sem Docker para os caminhos de dashboard / demonstração. As etapas abaixo são para conectar o SchemaBrain ao seu próprio agente contra seu próprio banco de dados.

Três etapas de uvx schemabrain init até uma integração funcional com Claude Desktop. Se você colar sua própria URL Postgres — sem necessidade de Docker, ~30s. Pressione Enter para a demo inclusa e init invoca Docker + baixa um modelo de embeddings de ~67 MB na primeira vez; ~45s depois de cacheado.

1. Instale

uvx schemabrain init        # zero-install: runs the wizard in one shot
# or install persistently first:
pipx install schemabrain    # (or) pip install schemabrain
schemabrain --version

Instalação a partir do código fonte (git clone + uv sync --extra dev) está documentada em docs/setup.md.

2. Rode o assistente de ativação

schemabrain init

init é um assistente de sete etapas que leva você de "tenho um banco de dados Postgres" a "Claude Desktop consegue responder perguntas sobre ele" em um único comando. Na primeira execução, ele pede o que precisa:

• Uma URL Postgres — cole sua própria string de conexão, ou pressione Enter para subir um container Postgres demo local com o fixture SaaS incluso (o Docker é invocado automaticamente; idempotente em execuções repetidas).
• Uma ANTHROPIC_API_KEY — opcional. Pule e o assistente ainda assim configura o Claude Desktop. No caminho demo, entidades + métricas + joins são pré-curados de um pacote YAML incluso — a camada semântica funciona com zero configuração. No seu próprio banco de dados, a curadoria de entidades pode ser executada depois via schemabrain entities suggest --apply assim que você tiver uma chave.

SchemaBrain init — activation wizard

  [1/7] Source check       ✓ source reachable + read-only
  [2/7] Index schema       ✓ 12 tables, 84 columns indexed
  [3/7] Curate entities    ✓ 12 entities applied (bundled demo pack)
  [4/7] Curate metrics     ✓ 5 metrics applied (bundled demo pack)
  [5/7] Curate joins       ✓ 11 canonical joins applied (bundled demo pack)
  [6/7] Wire host          ✓ wrote schemabrain entry to claude_desktop_config.json
                           (default; switch with --host claude-code|cursor|windsurf|manual)
  [7/7] Next               ✓ restart your MCP host, then ask: "list the entities SchemaBrain knows about"

Referência completa do assistente (etapas explicadas, flags, detecção automática de dbt, --print-only para hosts que não são Claude Desktop, opt-outs --no-entities / --no-metrics / --no-joins, pausas por limite de custo): docs/setup.md.

3. Reinicie o Claude Desktop e pergunte

1. Saia do Claude Desktop completamente — Cmd+Q, não apenas feche a janela. A configuração MCP só é lida na inicialização a frio.

2. Reabra.

3. Nova conversa:

   liste as entidades que o SchemaBrain conhece

Se o Claude chamar list_entities e reportar user, order, etc., está pronto. Se não, veja Solução de problemas.

Depois do assistente, schemabrain inspect mostra o que o agente tem e schemabrain tail transmite cada chamada de ferramenta ao vivo — veja docs/operations.md.

Seus arquivos de projeto

init escreve apenas ./schemabrain.db (o armazenamento local — adicione ao .gitignore) além da configuração do seu host. Para ajustar a política de PII e a camada semântica como YAML editável, execute novamente com --emit-yaml-dir:

schemabrain init --url-env DATABASE_URL --emit-yaml-dir ./schemabrain
# → ./schemabrain/pii_policy.yaml + entities/ + metrics/ + joins/

Edite um arquivo, schemabrain apply ./schemabrain, schemabrain check para validar, reinicie o serve. Não existe schemabrain.yaml — configuração é flags de CLI + variáveis de ambiente SCHEMABRAIN_* (carregadas automaticamente de .env) + essa árvore YAML. Mapa completo: Seu projeto.

---

Garantias de segurança

Seis propriedades que o SchemaBrain aplica na fronteira do SQL hoje:

1. Somente-leitura por arquitetura, não por configuração

A superfície MCP expõe doze ferramentas — nenhuma das quais pode escrever. Sem execute(), sem query(), sem caminho de prompt de agente até uma escrita no seu banco de dados, independentemente do estado da sessão — a garantia é estrutural, não uma flag que o agente pode virar. schemabrain serve também fixa default_transaction_read_only=on como cinto e suspensórios. Somente-leitura por arquitetura →

2. Recusa com ciência de PII na fronteira da ferramenta get_metric

Qualquer get_metric que toque uma categoria de PII bloqueada retorna um envelope refused — o SQL compilado nunca é executado e a recusa é registrada em mcp_audit. describe_entity aplica o mesmo no nível de coluna (colunas bloqueadas enviam redacted=True). init bloqueia o conjunto de vazamento catastrófico por padrão (credential,payment_card,government_id); --pii-block substitui o conjunto, então amplie listando o alvo completo. A detecção é correspondência de padrão de nomes de coluna em doze categorias GDPR / CCPA / HIPAA / PCI; classificação com consciência de conteúdo está no roadmap. Taxonomia e propagação de PII →

3. Log de auditoria à prova de adulteração

Cada chamada de ferramenta escreve uma linha em uma tabela mcp_audit somente-acréscimo — categorias de PII, fingerprints endereçáveis por conteúdo, cadeia de hash sha256. audit verify percorre novamente a cadeia e sai com código não-zero se qualquer linha passada foi reescrita.

schemabrain audit verify   # exit 0 = chain clean

Cadeia de auditoria à prova de adulteração →

4. Falha é um contrato, não uma string

Toda chamada sem sucesso — recusada, com erro ou degradada — retorna um bloco estruturado recovery.suggested_args, não uma mensagem para parsear. Bloqueios de PII (status: "refused") enviam a entidade para tentar de novo; dimensões ambíguas e entidades inalcançáveis (status: "error") enviam o candidato para escolher ou a próxima ferramenta a chamar. Apenas recusas de política são refused; "não vou adivinhar" é error com um payload de recuperação.

{ "status": "error", "kind": "ambiguous_time_dimension",
  "recovery": { "suggested_tool": "get_metric",
                "suggested_args": {"time_dimension": "order.placed_at"} } }

Recuperação estruturada →

5. Caminho de compilação: definições → SQL parametrizado

Entidades, métricas e joins canônicos compilam para SQL parametrizado que o SchemaBrain executa do seu lado. O agente vê linhas + o SQL que foi executado — nunca declarações arbitrárias no seu banco de dados. Definições sugeridas por LLM durante init são revisadas e aplicadas explicitamente. Construa sua camada semântica →

6. Integrável a qualquer loop de agente

A mesma superfície MCP stdio que o Claude Desktop vê é exposta a qualquer host MCP — incluindo seu próprio loop Anthropic, OpenAI ou LangGraph. examples/anthropic_demo.py é um drop-in de ~260 LOC que conecta Claude Haiku 4.5 ao schemabrain serve e imprime exatamente quais ferramentas o agente escolheu. Walkthrough SDK Anthropic →

---

Dashboard de observabilidade

O SchemaBrain inclui um dashboard opcional, somente-leitura, sobre os mesmos dados de auditoria + PII + recusa que o servidor MCP já está escrevendo. schemabrain dashboard inicializa um sidecar FastAPI local servindo uma UI estática pré-construída — sem runtime Node, sem exposição de rede, sem caminhos de escrita.

pip install "schemabrain[ui]"
schemabrain dashboard
# → http://127.0.0.1:7878

É um visualizador, não um console — sem configurações, sem área de SQL, sem caminho de escrita. Nove superfícies somente-leitura, cada uma respondendo a uma pergunta de operador que o envelope MCP sozinho nunca expõe visualmente. A superfície de destaque é o Knowledge Graph — seu esquema renderizado como a mesma projeção de relacionamento entre entidades que a camada semântica compila joins:

• Knowledge Graph (/graph) — como meu schema realmente se conecta? Entidades como nós, joins canônicos como arestas (sólidas para FKs declaradas, tracejadas para mineração de log), entidades com PII sinalizadas e pontos críticos de recusa destacados, com cardinalidade de FK declarada mostrada no caminho de join destacado — o schema como um grafo, não uma lista de tabelas.
• Overview (/overview) — a superfície inicial: contagens de entidades / métricas / joins / PII catastrófica de relance.
• Entities (/entities) — um índice ordenável; aprofunde-se nas colunas, PII, métricas e joins canônicos de qualquer entidade.
• Data Dictionary (/dict) — toda tabela, coluna, tipo, classe de PII, join e métrica, com exportação em Markdown em um clique (o mesmo artefato que schemabrain docs escreve).
• PII matrix (/pii) — quais colunas carregam dados sensíveis? Um heatmap com uma linha por coluna classificada e uma célula por categoria de PII, cada coluna marcada como block / redact / allow pela sua faixa consultiva. Colunas em categoria de vazamento catastrófico (credential, payment_card, government_id) são bloqueadas permanentemente independentemente da política e fixadas no topo — para que você pegue uma coluna payment_card escondida dentro de users antes de apontar um agente para um novo schema, e veja de relance o que dispara a política padrão --pii-block. Selecione qualquer linha para aprofundar nas colunas, métricas e joins da entidade.
• Refusals (/refusals) — o que o SchemaBrain bloqueou, e o que o agente viu? Um feed cronológico de chamadas retidas; expanda qualquer linha para revelar o envelope completo inline — o motivo que disparou (pii_blocked, allowlist_violation, fragment_unsafe, cost_cap_exceeded, ambiguous_resolution, schema_drift), o conjunto exato de categorias que intersectou a política, e o error.recovery estruturado (ferramenta sugerida + argumentos) que o agente recebeu para se recuperar. Use para triagem de "o agente diz que não consegue acessar isso" e para revisar se essas dicas realmente ajudaram.
• Audit Viewer (/audit) — a cadeia de auditoria ainda está intacta? A face visual do log à prova de adulteração: cada chamada de ferramenta escreve exatamente uma linha — independentemente do resultado — ancorada por chain_hash = sha256(prev_hash || canonical(row)). Uma faixa de integridade lê not verified this session até você executar uma passada, depois verified · n/N intact (ou sinaliza N rows edited after write); o botão Verify re-percorre a cadeia no servidor e recalcula a prova de inclusão Merkle RFC-6962 de cada linha visível no seu navegador. Selecionar uma linha abre o corpo completo (ferramenta, status, classe de custo, categorias de PII, fingerprint, chain_hash, e a escada de prova até a raiz). Recarregue para pegar novas chamadas.
• Policy (/policy) — a grade block / redact / allow que o firewall aplica, com o piso de vazamento catastrófico sempre ativo divulgado (não pode ser removido). Alterações são feitas via ações de copiar-o-CLI — o dashboard nunca escreve.
• Drift (/drift) — drift de configuração e enriquecimento que o store pode detectar, cada um com uma correção de copiar-o-CLI.

Knowledge Graph — seu schema como a projeção de relacionamento de entidade contra a qual a camada semântica compila joins; entidades com PII catastrófica sinalizadas, o caminho de join canônico rastreado.

Mais visualizações do dashboard — Overview, PII matrix, Refusals, Audit, Entities, Data Dictionary, Policy & Drift

Overview — todo o limite em uma tela: o que está vinculado, o que está protegido, o que sofreu drift.

PII matrix — quais colunas carregam dados sensíveis, e o que a política padrão bloqueia.

Refusals — toda chamada bloqueada, o motivo que disparou, e a dica de recuperação que o agente recebeu.

Audit Viewer — a cadeia à prova de adulteração, verificada no servidor até a vinculação de hash de cada linha.

Entities — toda entidade de negócio vinculada ao schema bruto, com exposição de PII e contagens de joins.

Data Dictionary — toda tabela, coluna, tipo e join, exportável para Markdown para seu repositório ou wiki.

Policy — a grade block / redact / allow que o firewall aplica, com o piso sempre ativo divulgado.

Drift — drift de configuração e enriquecimento que o store pode detectar, cada um com uma correção de copiar-o-CLI.

O dashboard vincula 127.0.0.1 apenas — não há flag --host, por design. É somente leitura e lê o mesmo store SQLite que serve escreve. Nenhum agente fala com ele.

Guia do dashboard → · PII matrix → · Refusals → · Audit Viewer →

---

Funciona com

O SchemaBrain fala o Model Context Protocol via stdio. schemabrain init --host <X> escreve configuração de primeira parte para quatro clientes MCP; tudo o mais que fala MCP stdio funciona via --host manual (imprime o snippet, você cola).

Integração de primeira parte

schemabrain init --host <X> escreve a entrada MCP diretamente no arquivo de configuração do host.

Cliente	Guia de configuração	Caminho de configuração
Claude Desktop	/setup/claude-desktop	macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json
Claude Code	/setup/claude-code	Executa via claude mcp add
Cursor	/setup/cursor	~/.cursor/mcp.json
Windsurf	/setup/windsurf	~/.codeium/windsurf/mcp_config.json

Qualquer outro host MCP stdio

schemabrain init --host manual imprime a entrada JSON na saída padrão — cole-a na configuração do host que você estiver usando. Qualquer cliente que inicie um subprocesso e fale MCP stdio deve funcionar em princípio; não testamos exaustivamente cada um. Alvos comuns:

• Zed — passo a passo completo em docs/setup/zed.md
• Codex CLI (caminho funcional para usuários do ChatGPT) — passo a passo completo em docs/setup/codex.md
• Cline (extensão do VS Code) — schemabrain init --host manual imprime o bloco mcpServers; cole-o nas configurações do Cline via MCP Servers → Configure MCP Servers. Passo a passo completo em docs/setup/cline.md
• Continue — cole em ~/.continue/config.json
• Seu próprio loop de agente — veja examples/anthropic_demo.py para uma referência de ~250 linhas do Anthropic-SDK

A superfície de 12 ferramentas, recusa ciente de PII, cadeia de auditoria e contratos de recuperação são agnósticos de transporte — qualquer cliente MCP stdio compatível recebe as mesmas garantias.

Frameworks de agente

A mesma superfície MCP stdio é acessível de qualquer framework que possa iniciar um servidor MCP. O caminho do Anthropic SDK é testado de primeira parte; os outros funcionam em princípio se a integração MCP do framework falar stdio.

• Anthropic SDK — passo a passo de primeira parte em docs/setup/manual.md; loop de referência em examples/anthropic_demo.py
• LangChain / LangGraph — via langchain-mcp-adapters
• Pydantic AI — via seu suporte MCP integrado
• CrewAI / AutoGen / Agno / loops personalizados — qualquer framework com um cliente MCP stdio funciona em princípio; não testamos cada um

Não enviamos adaptadores por framework; o cliente MCP padrão do framework é suficiente.

Ainda não suportado (hosts cloud / HTTPS)

O SchemaBrain v0.6 envia apenas stdio — sem transporte HTTPS / SSE. Clientes que exigem um endpoint HTTPS em nuvem não funcionam hoje:

• ChatGPT Connectors — veja a página de lacuna honesta para soluções alternativas e o roadmap v0.5+
• Gateways MCP hospedados — por design (cunha local-first; veja vs Querybear)

Se você precisar de suporte ao ChatGPT hoje, uma ponte comunitária stdio→HTTPS (mcp-remote, mcp-proxy, etc.) pode funcionar; não validamos nenhuma ponte específica contra as semânticas de PII / auditoria / recuperação.

Postura de segurança para compras / revisão →

---

Sessão de exemplo

Sessão real do Claude Desktop contra o fixture SaaS incluído (12 tabelas, 84 colunas, 12 entidades). Condensado por tamanho — um agente real explora list_metrics / suggest_joins primeiro, depois conclui que o caminho é inalcançável:

Você: Usando o SchemaBrain, calcule nosso volume de uso dividido por nível de plano.

Claude: (chama get_metric(name="usage_volume", group_by=["plan.title"]). A métrica ancora em usage_event; alcançar plan exigiria um join que não está no schema, então ele recusa:)

{ "status": "error",
  "error": {
    "kind": "unreachable_entity",
    "message": "entity 'plan' is not reachable from metric anchor 'usage_event'; no canonical join exists. Run `schemabrain joins suggest` to surface candidate joins.",
    "recovery": { "suggested_tool": "resolve_join",
                  "suggested_args": { "entity_a": "usage_event", "entity_b": "plan" } } } }

(Claude confirma na camada de join — resolve_join("usage_event", "plan") retorna kind: no_canonical_join. usage_events carrega apenas workspace_id, nunca um plan_id, e nenhuma tabela faz a ponte entre os dois.)

Veredito antecipado: não consigo calcular uso-por-plano, e você não deveria querer que eu fingisse — não há relacionamento modelado entre eventos de uso e planos neste schema. usage_events registra um workspace_id, não um plano, e nada une os dois. "Volume de uso por nível de plano" é inrespondível até que esse link exista — e não vou inventá-lo.

O que posso te dar — receita contratada por nível de plano (este caminho resolve completamente: subscription_item → subscription → plan, ambos os joins fk_constraint, confidence: HIGH):

SELECT p.title                                     AS plan_tier,
       SUM(si.unit_price_cents * si.seats) / 100.0  AS revenue   -- prices stored in integer cents
FROM   public.subscription_items si
JOIN   public.subscriptions      s ON si.subscription_id = s.id
JOIN   public.plans              p ON s.plan_id          = p.id
GROUP BY p.title
ORDER BY revenue DESC;

plan_tier	revenue
Enterprise	$379,620.00
Pro	$539.00
Free	$54.00

Duas ressalvas honestas:

• Contratado, não coletado. Esta é a receita de itens de linha de assinatura (seats × unit_price_cents), não faturas pagas. Para totais faturados, a métrica total_revenue ancora em invoices em vez disso.
• Centavos inteiros. unit_price_cents é armazenado como um inteiro; o / 100.0 converte para moeda.

O diferencial é o que não aconteceu: a maioria das ferramentas de LLM-sobre-banco-de-dados, ao ser solicitada para uso-por-plano, emitiria confiantemente JOIN plans p ON usage_events.plan_id = p.id contra uma coluna plan_id que não existe. O SchemaBrain recusou — get_metric retornou kind: unreachable_entity com recovery.suggested_tool: resolve_join, não prosa. O agente agiu no contrato de recuperação estruturado programaticamente em vez de fabricar um join. Recusa-em-vez-de-fabricação é o mecanismo de segurança, demonstrado ao vivo. Custo. ~US$ 0,0004/coluna com Claude Haiku 4.5 (colunas com nomes crípticos podem optar pelo Sonnet 4.6 via --enable-sonnet). O fixture de 12 tabelas incluído (84 colunas, 12 entidades + 5 métricas + 11 joins) já vem pré-curado, então o caminho de demonstração o aplica por US$ 0 — sem chave de API. Indexar essas 84 colunas com descrições de coluna via LLM custa cerca de US$ 0,03. A amostra de aluguel de DVD do Pagila (87 colunas após deduplicação de partições) é a referência medida diretamente — US$ 0,0299 em 105s. Reindexar um esquema inalterado custa US$ 0 — a impressão digital content-addressable pula a chamada de LLM por completo.

Para verificar se o SQL do Claude está mecanicamente correto (e se as ressalvas sinalizadas são o comportamento real dos dados), veja Validando SQL que o Claude gera.

Execute esta mesma sessão você mesmo: schemabrain init leva você a um Claude Desktop configurado em um único comando; depois pergunte ao Claude "Usando SchemaBrain, calcule nosso volume de uso dividido por nível de plano." e observe a recusa-e-depois-mudança ao vivo.

---

Para onde está indo

O SchemaBrain está evoluindo para uma camada de confiança e inteligência entre agentes de IA e seu banco de dados — ele dá ao agente um mapa semântico do seu esquema, compila respostas a partir de definições que você controla e mantém cada chamada ciente de PII e auditada. A segurança na fronteira do SQL é um ponto de prova dessa camada, não sua identidade inteira.

Essa postura se apoia em um substrato semântico. Você não pode recusar "esta consulta toca PII" sem saber quais colunas são PII. Você não pode responder "junte através desta junção" sem definições de junção canônica. Você não pode servir uma métrica sem saber seu grão.

Portanto, a ordem de engenharia é inteligência de esquema → substrato semântico → primitivas de confiança. Hoje o agente nunca escreve SQL bruto: ele chama get_metric e as ferramentas da camada semântica, o SchemaBrain compila SQL parametrizado que o agente nunca vê, e você obtém recusa ciente de PII, recuperação estruturada em cada chamada recusada ou degradada, execução somente leitura com timeouts de declaração e limites de linhas, e uma cadeia de auditoria à prova de adulteração. Essa postura orientada a definições e SQL compilado é o padrão e a recomendada. Inspecionar SQL arbitrário emitido pelo agente (validate_query / execute) é um caminho posterior, opcional e opt-in — não a direção para a qual estamos mudando. Veja o Roadmap.

---

Roadmap

Os rótulos v0.5 / v1 / v2 / v3 são nomes de marcos do roadmap, não versões de pacote. O pacote segue semver estrito — 1.0.0 é reservado para uma API que foi testada em batalha por usuários externos sem uma quebra forçada. Veja ADR-0003.

O roadmap completo e vivo — incluindo não-objetivos explícitos e como influenciar prioridades — está em ROADMAP.md.

Agora — lançando na v0.6.x

O que você obtém do pip install schemabrain:

• Servidor MCP, 12 ferramentas somente leitura — find_relevant_tables, find_relevant_entities, describe_table, describe_column, describe_entity, list_entities, list_metrics, list_joins, suggest_joins, resolve_join, get_example_queries, get_metric.
• Compilação orientada a definições — o agente nunca escreve SQL bruto; as respostas são compiladas a partir de definições que você controla, com execução somente leitura imposta na camada do banco de dados, além de timeouts de declaração e limites de linhas.
• Mecanismo de inteligência de esquema — indexa Postgres em um armazenamento SQLite local; enriquecimento semântico via LLM com limite de custo (com roteamento opt-in para Sonnet em colunas crípticas, --enable-sonnet); embeddings no dispositivo (BAAI/bge-small ONNX); recuperação semântica de tabelas (similaridade de cosseno sobre esses embeddings, classificadas por tabela pela melhor coluna correspondente); identificação de entidades com justificativa + confiança; mineração de joins por FK declarada, log de consultas e dbt-relationships; um grafo de junção canônica persistido com BFS multi-hop; e uma camada de métricas.
• Confiança e segurança — classificação de PII (60 regras em 12 categorias) com confiança por coluna, propagação de tags, um piso de vazamento catastrófico (agrupar por uma coluna PII recusa como divulgação em nível de linha), uma política editável (bloquear / redigir / permitir, além de substituições por coluna) e um log de auditoria com hash sha256 encadeado e à prova de adulteração, com provas Merkle RFC-6962 verificáveis no navegador e audit verify.
• Dashboard liderado por grafo, 9 superfícies — um Knowledge Graph interativo exclusivo, além de Overview, Entities (índice classificável + drilldown com painel semântico), Data Dictionary (Exportar para Markdown), matriz de PII, Refusals, Audit Viewer, um editor de Policy editável e inteligência de Drift. Tema duplo, opt-in, somente leitura, apenas 127.0.0.1.
• CLI — init, demo, index, import dbt, inspect, diff, check, entities, joins, metrics, policy {show, apply, tag}, docs, dashboard, doctor, serve, audit. Distribuído no PyPI (licenciado sob Apache-2.0) e como imagem Docker headless.

Depois — roadmap (adiado; apenas direção futura)

Fase 2 — diferenciadores

• Estimativa de custo de consulta (EXPLAIN do SQL compilado)
• Detecção de isolamento de locatário — verificações de filtro ausente e junção entre locatários
• Análise de impacto entre definições
• Inteligência de uso — detecção de pontos quentes e tabelas mortas
• Uma gramática geral de regras de política
• Descoberta de FK implícita sem logs de consulta
• Orçamento de contexto para respostas de ferramentas

Fase 3 — exploratória

• Memória persistente do agente
• Coordenação multiagente
• Transporte MCP remoto mais um SDK de cliente fino
• Um caminho opcional e opt-in para SQL escrito pelo agente (validate_query / execute) atrás de uma flag explícita. O SQL compilado orientado a definições permanece a postura padrão e recomendada; este caminho é para equipes que querem parse-antes-de-executar sobre SQL arbitrário emitido pelo agente, caso ele chegue. Não é enviado e não é uma mudança planejada para longe do padrão orientado a definições.

Tudo neste roadmap é open source.

---

Solução de problemas

As cinco falhas mais comuns na primeira execução. Solucionador completo em docs/setup/manual.md.

• pip install schemabrain me deu uma versão mais antiga. Verifique schemabrain --version. Se não corresponder ao último lançamento, seu cache do pip está desatualizado — execute pip install --upgrade schemabrain. schemabrain init grava a mesma versão no snippet do Claude Desktop para que permaneça reproduzível entre reinicializações. Quando você instalou do PyPI e uv está no seu PATH, o snippet executa uvx schemabrain==<pin> (aumente o pin manualmente após um upgrade do pip); caso contrário — uma instalação não-PyPI (wheel local, editable ou checkout git) ou sem uvx — ele fixa o caminho absoluto do ponto de entrada schemabrain instalado, que rastreia o ambiente a partir do qual você executou init.
• init relata source unreachable. O Postgres pode não estar pronto na primeira execução — aguarde alguns segundos e execute novamente. Para seu próprio banco de dados, verifique host, porta e credenciais. URLs de conexão em qualquer formato são aceitas (postgresql://, postgres://, postgresql+psycopg://).
• O primeiro init ou schemabrain index trava por ~60 segundos. Normal. O primeiro índice baixa o modelo de embedding ONNX (~67 MB) e faz uma chamada de LLM por coluna. Execuções subsequentes são rápidas.
• init falha no estágio 6 "wire host". O Claude Desktop deve ser instalado primeiro — o SchemaBrain escreve em seu arquivo de configuração, que não existe até que o Claude Desktop seja iniciado pelo menos uma vez.
• O Claude Desktop não mostra o SchemaBrain após reiniciar. Cmd+Q é necessário (fechar a janela não aciona uma releitura da configuração do MCP). Execute schemabrain doctor para verificar se a configuração foi aplicada. Se doctor disser que está tudo certo, mas o Claude Desktop ainda não vê a ferramenta, verifique ~/Library/Logs/Claude/mcp*.log.
• Apple Silicon + Python 3.12. A dependência onnxruntime do fastembed não fornece wheel arm64 para Python 3.12+, então os embeddings não podem ser construídos. init detecta isso no preflight e informa para você usar Python 3.11 (por exemplo, pyenv local 3.11.10) ou executar novamente com --no-embed (busca por palavras-chave em vez de semântica — todo o resto funciona).

---

Documentação

Doc	O que contém
docs/setup.md	Assistente de ativação (recomendado) — escolha um host, execute o assistente, pergunte ao agente (~60s)
docs/setup/docker.md	Instalação Docker (imagem com modelo de embedding embutido, sem download na primeira execução)
docs/setup/manual.md	index manual, mineração de consultas, configuração de logs, solução de problemas, MCP Inspector, escada de validação de SQL
docs/first-5-queries.md	O que realmente fazer após init — cinco consultas que exercitam somente leitura, recusa ciente de PII, cadeia de auditoria e recuperação estruturada
docs/semantic-layer.md	Construção de entidades, métricas (incl. expressões compostas), junções canônicas (incl. multi-hop), importação dbt
docs/operations.md	inspect, check (drift), index --dry-run, Docker compose
docs/observability.md	tail, log de auditoria, exportação OTel, classificação de PII
docs/reference/mcp-tools/overview.mdx	Referência completa para todas as 12 ferramentas MCP (visão geral + 12 páginas por ferramenta)
docs/architecture.mdx	Pipeline, contrato de recuperação, lógica de cache, modelo de custo, avaliação
docs/dashboard/overview.mdx	Dashboard de observabilidade somente leitura — matriz de PII, recusas, visualizador de auditoria
docs/landscape.md	Comparação vs Vanna / Atlan / dbt-mcp / WrenAI; "isso é uma camada semântica?"
docs/threat-model.md	Modelo de segurança + limites
docs/adr/	Registros de decisão de arquitetura (taxonomia de auditoria/PII, protocolo de armazenamento, política de versionamento, barramento de observabilidade)
examples/	Configurações MCP prontas para copiar e colar, loop de agente headless, passo a passo de ecommerce de ponta a ponta

---

FAQ

Meus dados saem da minha máquina? Apenas descrições de coluna enriquecidas por LLM e os valores de amostra redigidos que as alimentam. Três passadas de regex (email, SSN dos EUA, sequências de dígitos em formato de cartão de crédito) são executadas em cada amostra antes de sair do módulo profiler — veja schemabrain/profiler/stats.py. A chamada de API da Anthropic envia metadados de coluna + amostras redigidas + contexto de colunas irmãs — nenhuma linha bruta. Os embeddings são gerados localmente via fastembed (BAAI/bge-small-en-v1.5, ONNX, ~67 MB).

Quais bancos de dados funcionam hoje? Postgres 16+ é o único conector fonte hoje (o armazenamento local em si é um arquivo SQLite). Um conector fonte SQLite, além de Snowflake / BigQuery / MySQL, é principalmente uma nova implementação de DataSource mais um ajuste no profiler — no roadmap v1.x.

Por que MCP e não uma API REST? O consumidor é um agente, não um serviço. O MCP padroniza o registro de ferramentas, a descrição de esquema e o transporte de solicitação/resposta. Os agentes descobrem o SchemaBrain nativamente e obtêm sua superfície de ferramentas — sem wrapper de API, sem SDK para manter por linguagem.

Isso é uma camada semântica como Cube ou dbt Semantic Layer? Não exatamente — o SchemaBrain é a camada de confiança e inteligência entre agentes de IA e seu banco de dados, construída sobre um substrato de camada semântica. Entidades, métricas e junções canônicas são definições persistidas de primeira classe (list_entities, describe_entity, resolve_join, get_metric), e elas tornam possíveis as primitivas de segurança — somente leitura por arquitetura, recusa ciente de PII, cadeia de auditoria. O substrato semântico é a fundação; a segurança na fronteira do SQL, incluindo o firewall, é um ponto de prova da camada, não sua identidade inteira. Comparação completa vs Cube / dbt-mcp / Vanna / WrenAI em docs/landscape.md.

Mais perguntas respondidas em docs/setup/manual.md (por que embeddings locais, mais solução de problemas).

---

Executando em seu próprio Postgres?

Se você está apontando agentes de IA para um Postgres real (não demo), eu realmente gostaria de saber como foi — o que funcionou, o que quebrou, o que pareceu afiado ou áspero. Abra uma GitHub Discussion ou uma GitHub issue, ou fale comigo no GitHub (@Arun-kc). Fico feliz em ajudar você a configurá-lo.

---

Contribuidores

---

Contribuição e Licença

PRs são bem-vindos. O padrão é alto — veja CONTRIBUTING.md para a checklist test-first / 99%-coverage / conventional-commits / architecture-invariants. CI aplica tudo isso.

Bugs e solicitações de recursos usam os modelos estruturados em .github/ISSUE_TEMPLATE/. Issues sem reprodução (bugs) ou sem um problema subjacente claro (recursos) são fechadas com um pedido para reabrir com as informações corretas.

Apache 2.0.