Pretensor OSS

Pretensor OSS introspects PostgreSQL and Snowflake, with optional BigQuery connector support, builds a Kuzu knowledge graph of tables, columns, foreign keys, inferred joins, and related metadata, and exposes that graph to AI tools through an MCP (Model Context Protocol) server. Agents query schema context and search without issuing raw SQL against your graph store.

Status: Beta. Pretensor is on PyPI as pretensor; 0.1.0 is the first non-alpha release. CLI flags, MCP tools, and graph schema can still change between minor versions. Pin exact versions until 1.0.0. See docs/releases.md for the versioning policy.

Who is this for

• Data analysts using AI to explore warehouses.
• Data engineers tired of copy-pasting DDLs into chat.
• Data architects who need grounded schema context for agents.
• Anyone feeding database schemas to an LLM by hand.

Prerequisites

• Python 3.11 or 3.12 (3.13 not yet tested).
• A reachable database for pretensor index. Every database driver ships as an extra: PostgreSQL via pretensor[postgres], Snowflake via pretensor[snowflake], BigQuery via pretensor[bigquery].

Install

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

Heads-up: the database drivers are not bundled in the base install. A bare pip install pretensor installs the CLI and MCP server but no DB driver. pretensor index postgresql://… will then fail at connect time with Postgres connector requires psycopg2. Install the Postgres extra: pip install 'pretensor[postgres]' (or pip install psycopg2-binary). Install the extra matching your database (postgres, snowflake, bigquery, or mysql), or pretensor[all-connectors] for all of them.

Optional features are exposed as extras:

Combine extras with comma separation, e.g. pip install 'pretensor[postgres,clustering]'.

Try it without installing:

uvx --from pretensor pretensor --help

A note on versions. From 0.1.0 on, plain pip install pretensor resolves to the latest non-alpha release, and pre-releases require --pre (e.g. pip install --pre pretensor). Pin to a specific version (e.g. pretensor==<version>) if you want a deterministic install. See the PyPI badge above for the latest.

If you want to hack on Pretensor itself rather than use it, see the contributor setup in CONTRIBUTING.md for the git clone + make install flow.

Quickstart

pip install 'pretensor[postgres]'
pretensor init

init finds your database connection, indexes it, links your code, and registers pretensor with Claude or Cursor. Prefer to drive it yourself? Every step is still a flag: see guides/quickstart.md.

Scan application code (analyze)

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

analyze scans a repository's Python (.py) and SQL (.sql) files: it lifts SQL string literals from Python source via the stdlib AST (no code is executed) and reads bare .sql files whole, resolves each statement's table references with sqlglot, and links the issuing code to the matching tables in the graph as external consumers: service, file, line range, read/write op, and a confidence score. Raw SQL text is never stored, only a fingerprint. The results power the consumers MCP tool and enrich impact, so an agent can answer "which services consume this table?" with provenance.

Useful flags: --service labels the scanned repo (defaults to the directory name), --default-schema sets the schema assumed for unqualified table names, --dry-run previews without writing, --json emits a machine-readable summary. A # noqa: pretensor-analyze comment on or above a statement opts it out.

MCP tools

Join confidence & provenance

context (per relationship) and traverse (per path step) both report how a join was derived, so an agent can decide how much to trust it before writing SQL:

• confidence — a 0.0–1.0 score. Declared foreign keys always report 1.0; inferred joins carry the score produced by the pass that found them.
• source — how the join was derived:
  • declared_fk — a real foreign-key constraint in the database. Always confidence 1.0.
  • heuristic — inferred from naming conventions and column-type overlap.
  • llm_inferred — inferred by an LLM pass over schema metadata.
  • embedding — inferred from vector similarity between column/table descriptions.
  • statistical — a heuristic or LLM candidate whose confidence was re-scored using sampled value overlap; the original hypothesis source is folded into this value once the statistical pass adjusts it.
  • entity_link — cross-database bridge steps in traverse derived from a confirmed SAME_ENTITY link, not a same-database join.
• reasoning — an optional short, human-readable rationale for inferred joins (absent for declared FKs, where the constraint itself is the rationale).

Agents should prefer declared_fk and high-confidence edges when composing SQL, and treat sub-0.5 confidence as speculative — verify with validate_sql (or inspect reasoning) before relying on it.

Agent-framework adapters

Agents that don't run over MCP can still reach the graph tools. Pretensor exposes schema, context, traverse, impact, query, and validate_sql as native tool objects for LangChain, LlamaIndex, and Google ADK. No MCP server process is required. The adapters call the same underlying functions the MCP server uses, so output is identical.

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

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

Install the matching extra (pretensor[langchain], pretensor[llama-index], or pretensor[google-adk]). The docs/agent-framework-adapters.md file has a full example per framework.

Architecture

src/pretensor/ is organized by subsystem:

• connectors/: database-specific introspection (PostgreSQL, Snowflake, BigQuery)
• core/: Kuzu graph store, schema writing, relationship discovery
• intelligence/: deterministic graph intelligence (classification, clustering, join-path precomputation; metric-template code exists but is not part of the default OSS indexing flow)
• enrichment/: optional graph enrichment passes (dbt manifest, analyze code scanner)
• mcp/: MCP server, tools, resources
• cli/: Typer CLI (init, index, reindex, analyze, serve, list, quickstart, export, validate, sync-grants, add, remove, plus the semantic subcommand group)

Status

Pretensor is early software:

• The package on PyPI is named pretensor. 0.1.0 is the first non-alpha release; pre-releases published after it require --pre to install.
• There is no SemVer stability guarantee before 1.0.0, so CLI flags, MCP tools, and graph schema may still change between releases. Pin exact versions.
• Test upgrades in a staging environment before production use.

Progress and release notes: CHANGELOG.md.

Contributing

See CONTRIBUTING.md. Security issues: see SECURITY.md.

Tests

make verify

Individual commands are also available:

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

License

MIT: see LICENSE.