Boyce

Don't let your agents guess. Give them Eyes.

Gives AI agents structured database intelligence to generate correct, safe SQL — deterministically.

pip install boyce
GitHub PyPI Docs llms.txt llms-full.txt

The Problem

AI agents querying databases without context generate unreliable SQL. They work from incomplete schemas, guess join paths, and miss NULL distributions that silently corrupt results.

A naive equality filter on a column with 30% NULLs silently drops those rows — and the agent never knows. Your query returns confidently wrong numbers. At 2am. In production.

Boyce gives agents structured database intelligence so this doesn't happen.

Your AI Agent’s SQL Is Correct. The Answer Is Still Wrong.
How NULL distributions silently corrupt agentic database workflows — and why the fix isn’t a better model.

What Boyce Does

Layer What it does
🧠 The Brain NL → StructuredFilter → deterministic SQL. Same inputs, same SQL, byte-for-byte, every time. Zero LLM in the SQL compiler.
👁 The Eyes Live Postgres/Redshift adapter. Your agent sees real schema, real data distributions, real NULL rates before writing a single filter.
🛡 The Nervous System EXPLAIN pre-flight on every generated query. Bad SQL is caught at planning time — not at 2am in your on-call rotation.
💬 Response Intelligence Every tool response includes a next_step directive and contextual safety findings — your agent always knows what Boyce found and exactly what to do next. Safety warnings only appear when material; clean queries return clean responses.

Quick Start

  1. Install: pip install boyce
  2. Configure: boyce init (auto-detects your MCP host)
  3. Scan: boyce scan ./my-project/
  4. Ask: boyce ask "total revenue by customer segment"

How to Install

pip install boyce

# With live Postgres/Redshift adapter
pip install "boyce[postgres]"

Then configure your MCP host. There are two paths:

If you use Claude Desktop, Cursor, Claude Code, Cline, Windsurf, DataGrip, or Codex — you do not need to configure an LLM provider. The host's model handles reasoning. Boyce supplies schema context and a deterministic SQL compiler via get_schema and ask_boyce.

Run the setup wizard:

boyce init

Or configure manually:

{
  "mcpServers": {
    "boyce": {
      "command": "boyce",
      "env": {
        "BOYCE_DB_URL": "postgresql://user:pass@host:5432/db"
      }
    }
  }
}

BOYCE_DB_URL is optional. Without it, Boyce runs in schema-only mode — SQL generation still works; EXPLAIN pre-flight returns "unchecked".

For the CLI (boyce ask), HTTP API, or VS Code extension, configure Boyce's internal query planner:

{
  "mcpServers": {
    "boyce": {
      "command": "boyce",
      "env": {
        "BOYCE_PROVIDER": "anthropic",
        "BOYCE_MODEL": "claude-sonnet-4-6",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "BOYCE_DB_URL": "postgresql://user:pass@host:5432/db"
      }
    }
  }
}

Boyce uses LiteLLM — supports Anthropic, OpenAI, Ollama (local), vLLM (local), Azure, Bedrock, Vertex, Mistral, and 100+ providers.

MCP Tools

Seven tools exposed via the Model Context Protocol:

Tool Purpose
ingest_source Teach Boyce about a database — accepts dbt, LookML, DDL, SQLite, Django, SQLAlchemy, Prisma, CSV, Parquet, or live PostgreSQL DSN (10+ formats, auto-detected)
ingest_definition Store certified business definitions — auto-injected at query time
get_schema Return full schema context — host LLM uses this to construct queries without a Boyce API key
ask_boyce Full NL → SQL pipeline with NULL trap detection and EXPLAIN pre-flight
validate_sql Validate hand-written SQL — EXPLAIN pre-flight, Redshift lint, NULL risk check — without executing
query_database Execute read-only SELECT with NULL risk scan and EXPLAIN pre-flight on every query
profile_data See how a column actually behaves — null rate, distinct count, min/max

What It Parses

Point Boyce at your project. It figures out what you have.

boyce scan ./my-project/
dbt manifest dbt project LookML Raw DDL SQLite Django SQLAlchemy Prisma CSV Parquet

Architecture

SemanticSnapshot (JSON)
        |
        v  ingest_source
  +-----------------------------------+
  |     SemanticGraph (NetworkX)      |
  |  entities -> weighted joins       |
  +-----------------------------------+
        |
        v  ask_boyce
   QueryPlanner  ->  Dijkstra
   (LiteLLM)         join resolver
        |                 |
        +--------+--------+
                 v
        kernel.process_request()    <- ZERO LLM
        SQLBuilder (dialect-aware)
                 |
                 v
        EXPLAIN pre-flight          <- safety layer
                 |
                 v
         SQL + validation result

Dialect support: Redshift, Postgres, DuckDB, BigQuery