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 fazem buscas 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 podem mudar entre versões menores. Fixe versões exatas até 1.0.0. Consulte docs/releases.md para a política de versionamento.

Para quem é isso

• Analistas de dados que usam IA para explorar data warehouses.
• Engenheiros de dados cansados de copiar e colar DDLs em chats.
• 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]' (ou 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 (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 tabela automaticamente (desative com --no-embeddings ou PRETENSOR_EMBEDDINGS_DISABLED=1), a ferramenta MCP semantic_search executa ranqueamento por similaridade de cosseno contra vetores de tabela indexados, e a ferramenta query ganha um re-ranqueamento híbrido BM25+cosseno RRF. As passagens experimentais com embeddings da camada de inteligência (mistura de clustering, votação de classificação de papéis, junções candidatas semânticas) permanecem como alternâncias de configuração opt-in. Sem o extra, semantic_search ainda é registrada, 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. Consulte o badge do PyPI acima para a versão mais recente.

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

Início rápido

pip install 'pretensor[postgres]'
pretensor init

init encontra sua conexão de banco, indexa, vincula seu código e registra pretensor com Claude ou Cursor. Prefere controlar você mesmo? Cada etapa ainda é uma flag: veja guides/quickstart.md.

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

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

analyze escaneia arquivos Python (.py) e SQL (.sql) de um repositório: extrai literais de string SQL do código-fonte Python via AST da stdlib (nenhum código é executado) e lê arquivos .sql simples por completo, resolve as referências de tabela de cada instruçã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 sem qualificação, --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 instruçã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. Cada relacionamento carrega proveniência confidence + source. 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. Cada etapa carrega proveniência confidence + source. Quando ambíguo e as tabelas têm embeddings, ranqueia caminhos empatados por similaridade de embeddings.
impact	Tabelas a jusante alcançáveis a partir de uma tabela via arestas de FK e junções inferidas. Cada tabela alcançada carrega os consumidores de código externos encontrados por pretensor analyze.
consumers	Localizações de código externas (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 um nome de métrica, tabela ou coluna não resolvido tem correspondências próximas.
validate_sql	Valida SQL contra o grafo indexado antes da execução.

Confiança e proveniência de junções

context (por relacionamento) e traverse (por etapa de caminho) ambos relatam como uma junção foi derivada, para que um agente possa decidir o quanto confiar antes de escrever SQL:

• confidence — uma pontuação 0.0–1.0. Chaves estrangeiras declaradas sempre relatam 1.0; junções inferidas carregam a pontuação produzida pela passagem que as encontrou.
• source — como a junção foi derivada:
  • declared_fk — uma restrição real de chave estrangeira no banco. Sempre confiança 1.0.
  • heuristic — inferida a partir de convenções de nomenclatura e sobreposição de tipos de coluna.
  • llm_inferred — inferida por uma passagem de LLM sobre metadados de esquema.
  • embedding — inferida a partir de similaridade vetorial entre descrições de coluna/tabela.
  • statistical — um candidato heurístico ou de LLM cuja confiança foi re-pontuada usando sobreposição de valores amostrados; a fonte original da hipótese é incorporada a este valor quando a passagem estatística o ajusta.
  • entity_link — etapas de ponte entre bancos em traverse derivadas de um link SAME_ENTITY confirmado, não uma junção no mesmo banco.
• reasoning — uma justificativa curta e legível opcional para junções inferidas (ausente para FKs declaradas, onde a própria restrição é a justificativa).

Agentes devem preferir declared_fk e arestas de alta confiança ao compor SQL, e tratar confiança abaixo de 0.5 como especulativa — verifique com validate_sql (ou inspecione reasoning) antes de confiar nela.

Adaptadores para frameworks de agentes

Agentes que não rodam sobre MCP ainda podem acessar as ferramentas de grafo. Pretensor expõe schema, context, traverse, impact, query e validate_sql como objetos de ferramenta nativos para LangChain, LlamaIndex e Google ADK. Nenhum processo de servidor MCP é necessário. 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 padrão de indexação OSS)
• enrichment/: passagens opcionais de enriquecimento de grafo (manifesto dbt, scanner de código analyze)
• mcp/: servidor MCP, ferramentas, recursos
• cli/: CLI Typer (init, 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 é nomeado 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 o 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.