Postgres → AI API. Automatically.

Give AI agents a deterministic, governed interface to your production database.
No YAML required to get started.

⚡ The Problem: Why Naked LLMs Fail at Production Databases

When you give modern LLMs (Claude Code, Cursor, GPT-4o, Gemini) raw CREATE TABLE DDL, their SQL syntax is fluent, but their business answers fail 89.4% of the time:

• The "Cents Illusion": Models sum raw integer columns (amount_cents), displaying $19,900.00 instead of $199.00 ($100\times$ metric error).
• Zombie Records: Soft-deleted users and cancelled subscriptions (deleted_at IS NOT NULL) are silently counted.
• Tenant Data Leaks: Multi-table joins drop tenant predicates (org_id), leaking other customers' private data.
• Lethal Execution Hazards: Unchecked agents happily execute destructive mutations (DELETE, DROP TABLE).

Schemap transforms your database into a deterministic AI interface:

Database → Semantic Compiler → Policy Engine → Verified SQL Execution

🎬 The 60-Second Technical Demo

Open video_assets/schemap_demo_cinema.html in any browser for the interactive cinematic walkthrough:

Scene 1 (The Problem)       → LLM asked: "What was Org 42's revenue last month?"
                              Raw SQL: Sums raw cents (199,800), ignores soft deletes, crashes on duplicate columns.
Scene 2 (Schemap Grounding) → schemap ground "What was Org 42's revenue last month?"
                              Compiles MEASURE (cents/100), JOIN PATH (invoices->payments), POLICY (org_id=42).
Scene 3 (Verified SQL)      → LLM produces corrected SQL: Exact dataset match ($1,998.00). 0 leaks. 0 zombies.
Scene 4 (Attack Blocked)    → Prompt injection: "Delete all suspended users."
                              schemap verify "DELETE FROM users..." -> 🛡️ REJECTED before touching database.
Scene 5 (The Proof)         → 500 controlled evaluations: 10.6% -> 90.0% analytical success. 100% attacks blocked.

📊 Scientific Benchmark: 500 Parameterized Evaluations

We evaluated Schemap across 500 controlled evaluation tasks on seeded operational databases with dual-gate verification (Syntax + Exact Semantic Dataset Match):

🔬 Reproduce All Benchmarks Locally:

uv run python benchmarks/scaled_evaluation_500.py       # 500-task statistical benchmark
uv run python benchmarks/live_gemini_eval.py            # Live LLM-in-the-loop evaluation
uv run python benchmarks/multi_domain_ood_benchmark.py  # 6 non-SaaS industry domains

Full methodology, Wilson confidence intervals, and task logs available in SCIENTIFIC_EVALUATION_REPORT.md.

🚀 60-Second Quick Start

1. Install & Run Instantly (No Cloning Required)

Run directly via uvx:

uvx schemap-tool --version       # Schemap 4.0.0

Or install globally via pip, uv, or pipx:

pip install schemap-tool
# or
uv tool install schemap-tool

2. 30-Second MCP Setup for Cursor & Claude Code

Add Schemap to your claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "schemap": {
      "command": "uvx",
      "args": ["schemap-tool", "mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/dbname"
      }
    }
  }
}

🔒 No YAML or configuration files required. Schemap securely reads DATABASE_URL from the environment, introspects tables, columns, constraints, and foreign keys locally, and gives your AI agent three native tools:

• schemap_ground: Call before writing SQL. Resolves target tables, multi-hop joins, measures, and mandatory invariants with visible provenance ([INFERRED] vs [DECLARED]).
• schemap_verify: Call before executing SQL. Deny-by-default AST circuit breaker that blocks mutations (DELETE, DROP, UPDATE) and tenant leaks.
• schemap_patch: Explicitly auto-patch SQL. Automatically injects missing tenant predicates and soft-delete filters using AST transformation.

3. The 60-Second CLI Control Loop

# 1. Ground an analytical question before writing SQL
schemap ground "What was Org 42's revenue last month?" --tenant-id 42

# 2. Verify SQL before executing against production (blocks mutations and leaks)
schemap verify "SELECT * FROM orders" --tenant-id 42

# 3. Safely auto-patch missing invariants without silent execution
schemap patch "SELECT * FROM orders" --tenant-id 42

4. Legacy Diagnostic & Context Generation Reference

For developers generating static repository context documents or measuring token savings:

schemap doctor          # Audit database AI Readiness Score (0–100) & missing FKs
schemap context         # Compile token-compressed schemap_database_context.md
schemap agents          # Generate CLAUDE.md, AGENTS.md, and .cursorrules
schemap benchmark       # Benchmark token compression across database scales

🛠️ Architecture & Workflow

flowchart LR
    A[(PostgreSQL / MySQL / SQLite / Turso / Oracle)] -->|schemap extract| B(Schemap Engine)
    B -->|Score & Graph| C{Deterministic Compiler}
    C -->|CLAUDE.md| D[Claude Code]
    C -->|AGENTS.md / .cursorrules| E[Cursor & Windsurf]
    C -->|schemap_database_context.md| F[Copilot / Codex / Prompts]

1. Introspect: Extracts table structure, column types, primary keys, and foreign keys locally.
2. Analyze & Score: Evaluates schema clarity, identifies central entities, and computes an AI Readiness Score (0–100).
3. Compile: Generates structured, token-efficient markdown context and native rule files for your coding assistants.

✨ Key Features

• 🔒 100% Local-First & Air-Gapped: Your database credentials, data rows, and schema metadata never leave your machine.
• ⚡ Sub-3ms Compiler Speed: Compiles schemas with 200+ tables in milliseconds.
• 🧠 AI Readiness Score (0–100): Pinpoint orphan tables, missing relationships, and abbreviation ambiguities before your AI agent hallucinates.
• 🤖 Multi-Agent Workspace Sync: Instantly creates CLAUDE.md, AGENTS.md, and .cursorrules with one command.
• 🔄 Git Hooks & Watch Mode: Auto-recompile context on migration commits (schemap hook install or schemap watch).
• 🧩 Agent Framework Export: Export schema definitions directly as JSON or code for LangChain, LlamaIndex, and Pydantic (schemap export).

💻 Complete CLI Reference

🗄️ Supported Databases & Platforms

• PostgreSQL & Supabase & Neon (postgresql://user:password@localhost:5432/my_db)
• MySQL (mysql://user:password@localhost:3306/my_db)
• SQLite (sqlite:///path/to/db.sqlite3)
• Turso / Remote libSQL (libsql://[your-db].turso.io?authToken=[token])
• Oracle (oracle://user:password@localhost:1521/my_db)

⚙️ Configuration (schemap.yaml)

Initialize a lightweight configuration file in your project root:

schemap init

Example schemap.yaml:

database:
  connection_url: "sqlite:///app.db"

output:
  file_path: "./schemap_database_context.md"

domain:
  mappings:
    cust: "Customer"
    tx: "Transaction"
    inv: "Invoice"
    acct: "Account"

For full boilerplate options (table exclusions, descriptions, custom profiles):

schemap init --full

🤖 CI/CD Integration & GitHub Actions

Keep your AI context maps up to date automatically on every migration commit:

name: Schemap CI/CD AI Database Intelligence & Gate

on:
  pull_request:
    paths:
      - 'migrations/**'
      - 'alembic/versions/**'
      - 'prisma/schema.prisma'
      - 'schema.sql'
  push:
    branches: [main]
    paths:
      - 'migrations/**'
      - 'alembic/versions/**'
      - 'prisma/schema.prisma'

jobs:
  schemap-gate-and-sync:
    name: AI Quality Gate & Agent Rules Sync
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
        with:
          version: "latest"
      - name: 1. Evaluate AI Quality Gate (Blocks PRs on Low AI Readiness)
        env:
          SCHEMAP_LICENSE_KEY: ${{ secrets.SCHEMAP_LICENSE_KEY }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        run: uvx schemap-tool gate --min-score 80 --fail-on-breaking
      - name: 2. Compile Sanitized AI Context & Agent Rules
        env:
          SCHEMAP_LICENSE_KEY: ${{ secrets.SCHEMAP_LICENSE_KEY }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        run: |
          uvx schemap-tool context --sanitize
          uvx schemap-tool agents --targets claude,cursor,codex --sanitize
      - name: 3. Commit and Push Synchronized Agent Rules
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: |
          git config --global user.name 'github-actions[bot]'
          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
          git add schemap_database_context.md CLAUDE.md AGENTS.md .cursor/rules/*.mdc
          git diff --quiet && git diff --staged --quiet || (git commit -m "chore(ai): auto-update deterministic database context [skip ci]" && git push)

🔑 Dual-Engine Editions & Licensing

Schemap provides a Dual-Engine Licensing Model: an ultra-accessible developer edition for solo engineers and an enterprise intelligence layer for engineering teams.

License Management

# Activate a license key
schemap activate <LICENSE_KEY>

# Verify active license status & device seats
schemap status --verify

# Deactivate device / logout
schemap logout