Pretensor

Pretensor OSS

Pretensor OSS faz introspecção em PostgreSQL e Snowflake, com suporte opcional ao conector BigQuery, constrói um grafo de conhecimento Kuzu de tabelas, colunas, chaves estrangeiras, junções inferidas e metadados relacionados, e expõe esse grafo a ferramentas de IA por meio de um servidor MCP (Model Context Protocol). Agentes consultam contexto de esquema e buscam sem emitir SQL bruto contra seu armazenamento de grafo.

Status: Beta. Pretensor está no PyPI como pretensor; 0.1.0 é a primeira versão não-alfa. Flags de CLI, ferramentas MCP e o esquema do grafo ainda podem mudar entre versões menores — fixe versões exatas até 1.0.0. Veja docs/releases.md para a política de versionamento.

Para quem é

• Analistas de dados que usam IA para explorar warehouses.
• Engenheiros de dados cansados de copiar e colar DDLs no chat.
• Arquitetos de dados que precisam de contexto de esquema fundamentado para agentes.
• Qualquer pessoa que alimenta esquemas de banco de dados a um LLM manualmente.

Pré-requisitos

• Python 3.11 ou 3.12 (3.13 ainda não testado).
• Um banco de dados acessível para pretensor index. Cada driver de banco é distribuído como um extra — PostgreSQL via pretensor[postgres], Snowflake via pretensor[snowflake], BigQuery via pretensor[bigquery].

Instalação

# Indexing PostgreSQL? Install the postgres extra:
pip install 'pretensor[postgres]'
# or, inside a uv-managed environment:
uv pip install 'pretensor[postgres]'

Atenção: os drivers de banco não estão incluídos na instalação base. Uma instalação simples de pip install pretensor instala a CLI e o servidor MCP, mas nenhum driver de banco — pretensor index postgresql://… falhará no momento da conexão com Postgres connector requires psycopg2. Install the Postgres extra: pip install 'pretensor[postgres]' (or pip install psycopg2-binary). Instale o extra correspondente ao seu banco (postgres, snowflake, bigquery ou mysql), ou pretensor[all-connectors] para todos eles.

Recursos opcionais são expostos como extras:

Extra	Adiciona	Use quando
pretensor[postgres]	psycopg2-binary	Você está indexando PostgreSQL. Obrigatório — uma instalação simples não tem driver Postgres.
pretensor[snowflake]	snowflake-sqlalchemy	Você está indexando um warehouse Snowflake.
pretensor[bigquery]	google-cloud-bigquery	Você está indexando BigQuery.
pretensor[clustering]	leidenalg	Você quer detecção de comunidades Leiden durante a indexação. Sem isso, Pretensor usa igraph Louvain como fallback (funciona, mas sem ajuste de resolução).
pretensor[embeddings]	onnxruntime, transformers, huggingface-hub, numpy	Você quer embeddings ONNX locais (Snowflake/snowflake-arctic-embed-xs, 384-dim). Com o extra instalado, pretensor index calcula embeddings de tabelas automaticamente (desative com --no-embeddings ou PRETENSOR_EMBEDDINGS_DISABLED=1), a ferramenta MCP semantic_search executa ranqueamento por similaridade de cosseno contra vetores de tabelas indexados, e a ferramenta query ganha um re-ranqueamento híbrido BM25+cosseno RRF. As passagens experimentais da camada de inteligência que usam embeddings (blend de clustering, voto de classificação de papéis, junções candidatas semânticas) permanecem como toggles de configuração opcionais. Sem o extra, semantic_search ainda é registrado, mas retorna um envelope estruturado fallback_bm25; a saída heurística é byte-idêntica às versões anteriores.

Combine extras com separação por vírgula, ex.: pip install 'pretensor[postgres,clustering]'.

Experimente sem instalar:

uvx --from pretensor pretensor --help

Uma nota sobre versões. A partir de 0.1.0, pip install pretensor simples resolve para a versão não-alfa mais recente, e pré-lançamentos exigem --pre (ex.: pip install --pre pretensor). Fixe uma versão específica (ex.: pretensor==<version>) se quiser uma instalação determinística — veja o badge do PyPI acima para a mais recente.

Se você quiser contribuir com o Pretensor em vez de usá-lo, veja a configuração para contribuidores em CONTRIBUTING.md para o fluxo git clone + make install.

Início rápido

pretensor index postgresql://USER:PASSWORD@HOST:5432/DBNAME
pretensor serve --config-only   # prints mcpServers JSON for Claude / Cursor

serve --config-only imprime o JSON mcpServers na saída padrão. Mescle a entrada pretensor nas configurações MCP do seu Claude ou Cursor — a IDE inicia o servidor automaticamente. Execute pretensor serve diretamente se preferir um processo de terminal de longa duração (dicas de configuração vão para stderr, mantendo a saída padrão limpa para JSON-RPC).

Use --state-dir em index / reindex e --graph-dir em serve ao substituir o diretório de estado padrão (.pretensor).

Guia completo — instalação, ferramentas, visibilidade, reindexação, visualização do grafo: guides/quickstart.md

Escanear código de aplicação (analyze)

pretensor analyze path/to/service-repo --connection mydb

analyze escaneia um repositório em busca de literais de string SQL em código-fonte Python (AST da stdlib — nenhum código é executado), resolve as referências de tabela de cada declaração com sqlglot, e vincula o código emissor às tabelas correspondentes no grafo como consumidores externos: serviço, arquivo, intervalo de linhas, operação de leitura/escrita e uma pontuação de confiança. O texto SQL bruto nunca é armazenado, apenas uma impressão digital. Os resultados alimentam a ferramenta MCP consumers e enriquecem impact, para que um agente possa responder "quais serviços consomem esta tabela?" com proveniência.

Flags úteis: --service rotula o repositório escaneado (padrão: nome do diretório), --default-schema define o esquema assumido para nomes de tabela não qualificados, --dry-run pré-visualiza sem gravar, --json emite um resumo legível por máquina. Um comentário # noqa: pretensor-analyze em ou acima de uma declaração a exclui.

Ferramentas MCP

Nome	Papel
list_databases	Lista conexões de banco indexadas com contagens de tabelas e obsolescência.
schema	Inspeciona rótulos de nós, tipos de arestas e propriedades disponíveis antes de escrever Cypher.
query	Busca por palavras-chave BM25 em metadados de tabelas e entidades. Re-ranqueamento híbrido BM25 + cosseno RRF quando [embeddings] está instalado e as tabelas têm vetores.
semantic_search	Ranqueamento por cosseno sobre embeddings SchemaTable indexados. Requer pretensor[embeddings]; retorna um envelope estruturado de fallback BM25 quando o extra está ausente ou nenhuma tabela foi incorporada.
cypher	Cypher Kuzu somente leitura para um banco indexado; cláusulas de mutação são rejeitadas.
context	Contexto completo para uma tabela física, incluindo colunas, junções, linhagem e metadados de cluster. O argumento opcional include_similar expõe vizinhos mais próximos entre clusters quando embeddings estão presentes.
traverse	Caminhos de junção entre duas tabelas físicas. Quando ambíguo e as tabelas têm embeddings, classifica caminhos empatados por similaridade de embedding.
impact	Tabelas a jusante alcançáveis a partir de uma tabela via arestas de FK e junção inferida. Cada tabela alcançada carrega os consumidores de código externos encontrados por pretensor analyze.
consumers	Localizações de código externo (serviço, arquivo, intervalo de linhas, operação de leitura/escrita, confiança) que consomem uma tabela, de pretensor analyze.
detect_changes	Compara o esquema de banco ao vivo com o último snapshot indexado sem mutar o grafo.
compile_metric	Compila YAML de camada semântica em SQL validado para um banco indexado. A string de erro inclui uma lista de sugestões "você quis dizer: …" quando uma métrica, tabela ou nome de coluna não resolvido tem correspondências próximas.
validate_sql	Valida SQL contra o grafo indexado antes da execução.

Adaptadores para frameworks de agentes

Agentes que não rodam sobre MCP ainda podem acessar as ferramentas do grafo. Pretensor expõe schema, context, traverse, impact, query e validate_sql como objetos de ferramenta nativos para LangChain, LlamaIndex e Google ADK — sem necessidade de processo de servidor MCP. Os adaptadores chamam as mesmas funções subjacentes que o servidor MCP usa, então a saída é idêntica.

from pathlib import Path
from pretensor.integrations import load_langchain_tools  # or load_llamaindex_tools, load_adk_tools

tools = load_langchain_tools(Path(".pretensor"))

Instale o extra correspondente (pretensor[langchain], pretensor[llama-index] ou pretensor[google-adk]). O arquivo docs/agent-framework-adapters.md tem um exemplo completo por framework.

Arquitetura

src/pretensor/ é organizado por subsistema:

• connectors/ — introspecção específica de banco (PostgreSQL, Snowflake, BigQuery)
• core/ — armazenamento de grafo Kuzu, escrita de esquema, descoberta de relacionamentos
• intelligence/ — inteligência de grafo determinística (classificação, clustering, pré-computação de caminhos de junção; código de template de métricas existe, mas não faz parte do fluxo de indexação OSS padrão)
• enrichment/ — passagens opcionais de enriquecimento do grafo (manifesto dbt, scanner de código analyze)
• mcp/ — servidor MCP, ferramentas, recursos
• cli/ — CLI Typer (index, reindex, analyze, serve, list, quickstart, export, validate, sync-grants, add, remove, além do grupo de subcomandos semantic)

Status

Pretensor é software inicial:

• O pacote no PyPI é chamado pretensor. 0.1.0 é a primeira versão não-alfa; pré-lançamentos publicados depois dela exigem --pre para instalar.
• Não há garantia de estabilidade SemVer antes de 1.0.0, então flags de CLI, ferramentas MCP e esquema do grafo podem mudar entre versões. Fixe versões exatas.
• Teste atualizações em um ambiente de staging antes do uso em produção.

Progresso e notas de versão: CHANGELOG.md.

Contribuindo

Veja CONTRIBUTING.md. Problemas de segurança: veja SECURITY.md.

Testes

make verify

Comandos individuais também estão disponíveis:

make test      # pytest
make lint      # ruff check
make typecheck # pyright

Licença

MIT — veja LICENSE.