Summary

It refuses rather than inventing the join.

The behaviour worth the setup is what happens when a question cannot be answered: the tool returns a structured refusal naming the reason and suggesting the recovery call, instead of fabricating a relationship that looks plausible. Add the PII refusal happening before the query runs, and a SHA256-hashed append-only audit log that `audit verify` exits non-zero on if a past row was rewritten, and you get a surface you can point at a production database. The cost is curation — the semantic layer only exists after an operator confirms entities.

What it is

A read-only layer between an agent and a database. Queries are compiled from definitions you control — entities, canonical joins and declared metrics — so there is no path from a prompt to raw SQL at your database.

What you get

Physical-schema tools work as soon as you have indexed: `find_relevant_tables` retrieves by embedding cosine, `describe_table` dumps one table, `describe_column` drills in with the bidirectional FK graph
`suggest_joins` returns the shortest FK-graph paths between table pairs; `get_example_queries` returns real SQL observed against a table from pg_stat_statements
The semantic layer opens once an entity is confirmed: `find_relevant_entities`, `list_entities` and `describe_entity` cover curated entities and their identity columns
`list_metrics` and `get_metric` declare and run pre-defined metrics; `list_joins` and `resolve_join` return canonical relationships, paste-ready
Every response carries a `token_estimate` so an agent can budget context, and a status of success, empty, partial, degraded, error or refused with `follow_up_hints` for the next call
PII tags propagate from the physical schema through joins and metrics — a query touching a blocked category is refused before the database is reached

Requirements

The PyPI package schemabrain, version 0.6.0, run as `uvx schemabrain serve` over stdio, or `uvx schemabrain init` to walk the whole setup. DATABASE_URL holds the Postgres connection string and stays in the environment, so credentials never appear in argv or logs; `--store-path` points at the SQLite store built by `schemabrain index`, defaulting to ./schemabrain.db. Postgres is the supported source today.

Setup effort

One command plus a key — uvx schemabrain init, then supply credentials