SQLMesh AI Assistant

A conversational AI agent that understands your SQLMesh project, translates natural language to SQL, explains plan diffs, traces column-level lineage, and generates new models — all powered by Claude.

Why SQLMesh + AI?

SQLMesh exposes a rich Python API that makes it ideal for AI integration:

• Column-level lineage — trace any column back to its source, automatically
• Plan/apply diffs — see exactly what will change before applying, explained in plain English
• Python-native — no manifest parsing; everything is accessible via sqlmesh.core.context.Context
• DuckDB — fully self-contained, no external database needed

Features

Feature	Description
NL-to-SQL	Ask questions in plain English, get executable DuckDB SQL
Plan Explainer	AI-powered explanation of sqlmesh plan diffs and downstream impact
Column Lineage	Trace any column back through the DAG to its source
Model Generator	Describe a model in English, get a complete SQLMesh .sql file
Audits	Built-in data quality checks (not_null, unique_values, custom)

Quick Start

# Clone and setup
cd SQLMesh-AI
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Copy your API key
cp .env.example .env
# Edit .env with your ANTHROPIC_API_KEY

# Initialize the SQLMesh project
sqlmesh plan --auto-apply

# Run the CLI
python -m agent.cli

# Or run the Streamlit UI
streamlit run app.py

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  INTERFACE LAYER                                                │
│    CLI (agent/cli.py)  ◄──►  Streamlit UI (app.py)             │
└──────────────────────────┬──────────────────────────────────────┘
                           │
         ┌─────────────────┼─────────────────────┐
         ▼                 ▼                     ▼
  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐
  │ Query Gen    │  │ Plan         │  │ Model            │
  │ NL → SQL     │  │ Explainer    │  │ Generator        │
  └──────┬───────┘  └──────┬───────┘  └──────┬───────────┘
         │                 │                  │
  ┌──────▼─────────────────▼──────────────────▼───────────┐
  │  AGENT CORE                                           │
  │    Introspection  ·  Executor  ·  Lineage             │
  └──────────────────────────┬────────────────────────────┘
                             │
  ┌──────────────────────────▼────────────────────────────┐
  │  SQLMESH                                              │
  │    Context API  ·  Plan/Diff  ·  Column Lineage       │
  └──────────────────────────┬────────────────────────────┘
                             │
  ┌──────────────────────────▼────────────────────────────┐
  │  DuckDB (local, self-contained)                       │
  └───────────────────────────────────────────────────────┘

Project Structure

SQLMesh-AI/
├── config.yaml              # SQLMesh config (DuckDB gateway)
├── seeds/                   # TPC-H sample CSVs
├── models/
│   ├── seeds/               # SEED kind models loading CSVs
│   ├── staging/             # VIEW kind models with clean types
│   └── marts/               # FULL kind aggregate models
├── audits/                  # Custom audit SQL files
├── agent/
│   ├── introspection.py     # SQLMesh Context API wrapper
│   ├── query_generator.py   # NL → SQL via Claude
│   ├── executor.py          # Safe query execution
│   ├── lineage.py           # Model + column lineage
│   ├── plan_explainer.py    # AI-powered plan diff explanation
│   ├── model_generator.py   # Generate models from descriptions
│   └── cli.py               # Interactive chat CLI
├── app.py                   # Streamlit UI
└── requirements.txt

CLI Commands

/context              Show project models and schema
/lineage <model>      AI-powered lineage explanation
/column <model> <col> Trace column-level lineage
/plan [env]           Explain pending plan changes
/generate <desc>      Generate a new model from description
/models               List all models
/help                 Show help

Data

Uses TPC-H sample data (20 customers, 30 orders, 60 line items) across 5 regions and 25 nations. The data is self-contained in CSV seeds — no external database required.