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==`) 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

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

`serve --config-only` prints the `mcpServers` JSON to stdout. Merge the `pretensor` entry into your Claude or Cursor MCP settings — the IDE starts the server automatically. Run `pretensor serve` directly if you prefer a long-running terminal process (config hints go to stderr, keeping stdout clean for JSON-RPC).

Use `--state-dir` on `index` / `reindex` and `--graph-dir` on `serve` when overriding the default state directory (`.pretensor`).

Full guide — install, tools, visibility, reindexing, graph visualization: guides/quickstart.md

Scan application code (`analyze`)

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

`analyze` scans a repository for SQL string literals in Python source (stdlib

AST — no code is executed), 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

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

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 (`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.