Boyce

Boyce：面向 Agent 数据库工作流的语义协议与安全层

面向 Agent 数据库工作流的语义安全层。 Boyce 将大模型连接到实时数据库上下文，并内置安全护栏。

Boyce 以 Raymond F. Boyce 命名。他是 SQL 的共同发明者（1974 年），也是 Boyce-Codd 范式（BCNF）的合著者。

缺少适当上下文的 AI Agent 查询数据库时，会生成不可靠的 SQL——依赖不完整的架构、臆测列名、猜测联接路径。Boyce 为 Agent 提供所需的结构化数据库信息，让它们每次都能生成正确、安全的 SQL，具体通过三个相互关联的系统实现：

层级	功能
SQL 编译器	ask_boyce — NL → StructuredFilter → 确定性 SQL。SQL 构建器中不使用大模型。每次输入相同，输出的 SQL 就完全相同，逐字节一致。
数据库检查器	query_database / profile_data — 实时 Postgres/Redshift 适配器让你的 Agent 在编写任何筛选条件前查看真实架构和实际数据分布。
查询验证	对每个生成的查询执行预检 EXPLAIN 循环。错误的 SQL 会在规划阶段被发现，而不是等到凌晨 2 点轮值响应时才发现。

为什么这很重要？ → 空值陷阱：你的 AI Agent 编写的 SQL 是正确的，但答案仍然错误。

---

安装

需要 Python 3.10+

pip install boyce

# With live Postgres/Redshift adapter (enables EXPLAIN pre-flight + column profiling)
pip install "boyce[postgres]"

# uv (recommended)
uv pip install boyce
uv pip install "boyce[postgres]"

从源代码安装：

git clone https://github.com/boyce-io/boyce
uv pip install -e "boyce/"

---

快速入门

安装后，运行 boyce init 自动配置 MCP 主机：

boyce init

该向导会检测 Claude Desktop、Cursor、Claude Code 和 JetBrains（DataGrip、IntelliJ 等），并为每个主机写入正确的配置块。

从源代码进行开发？ 仓库中附带了一个设置脚本：

./quickstart.sh   # detects uv or python, installs package, writes .env template

---

配置 MCP 主机

最快捷的方法是运行 boyce init——它会检测你的 MCP 主机并自动写入配置：

boyce init

你也可以手动配置。根据主机的不同，有两种设置方式：

---

方式 1 — MCP 主机（无需 LLM 密钥）

如果你使用的是 Claude Desktop、Cursor、Claude Code、Codex、Cline、Windsurf、JetBrains（DataGrip、 IntelliJ）或任何兼容 MCP 的主机，则无需为 Boyce 配置 LLM 提供商。 主机自带的模型负责推理——Boyce 则通过 get_schema 和 ask_boyce 提供架构上下文和确定性 SQL 编译器。只需要 BOYCE_DB_URL（而且它也是可选的）。

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

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

Cursor（项目根目录中的 .cursor/mcp.json）：

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

---

方式 2 — 使用 Boyce 内置的 NL→SQL

如果你使用命令行（boyce ask）、HTTP API 或非 MCP 客户端（例如 VS Code 扩展），请使用你的 LLM 提供商配置 Boyce 内部的查询规划器：

{
  "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 支持所有可通过 LiteLLM 使用的 LLM 提供商： Anthropic、OpenAI、Ollama（本地）、vLLM（本地）、Azure、Bedrock、Vertex、Mistral 等。

---

两种方式下，BOYCE_DB_URL 都是可选的。未设置时，Boyce 将以仅架构模式运行——仍可生成 SQL；EXPLAIN 预检和实时查询工具则会返回 "status": "unchecked"。

---

环境变量

变量	何时需要	示例	用途
BOYCE_PROVIDER	仅路径 2（CLI/HTTP/非 MCP）	anthropic	LiteLLM 提供商名称
BOYCE_MODEL	仅路径 2（CLI/HTTP/非 MCP）	claude-sonnet-4-6	传递给 LiteLLM 的模型 ID
ANTHROPIC_API_KEY	使用 Anthropic 时	sk-ant-...	Anthropic 凭据
OPENAI_API_KEY	使用 OpenAI 时	sk-...	OpenAI 凭据
BOYCE_DB_URL	可选（任一路径）	postgresql://user:pass@host:5432/db	asyncpg DSN — 启用 EXPLAIN 预检和实时查询工具
BOYCE_HTTP_TOKEN	仅路径 2 的 HTTP API	my-secret-token	boyce serve --http 的 Bearer 令牌
BOYCE_STATEMENT_TIMEOUT_MS	可选	30000	每条语句的超时时间，单位为 ms（默认：30s）

---

MCP 工具

工具	描述
ingest_source	从 dbt manifest、dbt 项目、LookML、DDL、SQLite、Django、SQLAlchemy、Prisma、CSV 或 Parquet 解析 SemanticSnapshot。
ingest_definition	存储经过认证的业务定义 — 在查询时自动注入。
get_schema	返回完整的架构上下文和 StructuredFilter 格式文档。供 MCP 主机使用，以便主机 LLM 无需 Boyce API 密钥即可构建查询。
ask_boyce	完整的自然语言 → SQL 流程：查询规划器（LiteLLM）→ 确定性内核 → NULL 陷阱检查 → EXPLAIN 预检。
validate_sql	验证手写 SQL — 执行 EXPLAIN 预检、Redshift 检查和 NULL 风险检查，但不执行查询。
query_database	对实时数据库执行只读 SELECT。写操作会在两个独立层级被拒绝。
profile_data	获取任意列的空值百分比、不同值计数、最小值/最大值 — 在数据质量问题影响查询结果前发现它们。
check_health	运行状态健康检查 — 检查数据库连接、快照时效性，并提供可执行的修复命令。查询意外失败时调用。

---

架构

SemanticSnapshot (JSON)
        │
        ▼  ingest_source
 ┌─────────────────────────────────────────────┐
 │          SemanticGraph (NetworkX)            │  ← in-memory, loaded per session
 │  nodes = entities (tables/views/dbt models) │
 │  edges = joins  (weighted by confidence)    │
 └─────────────────────────────────────────────┘
        │                         │
        ▼  ask_boyce              ▼  (internal)
  QueryPlanner                 Dijkstra
  (LiteLLM)                    join resolver
  NL → StructuredFilter             │
        │                           │
        └──────────┬────────────────┘
                   ▼
           kernel.process_request()          ← ZERO LLM HERE
           SQLBuilder (dialect-aware)
                   │
                   ▼
           EXPLAIN pre-flight                ← Query Verification
           (PostgresAdapter)
                   │
                   ▼
            SQL + validation result

方言支持： redshift、postgres、duckdb、bigquery

Redshift 安全防护（safety.py）：自动检查 LATERAL、JSONB、REGEXP_COUNT、前瞻正则表达式模式，并为 Redshift 1.0（PG 8.0.2）重写数值类型转换。

---

Scan CLI

# Scan a single file
boyce scan demo/magic_moment/manifest.json

# Scan a directory (auto-detects all parseable sources)
boyce scan ./my-project/ -v

# Save snapshots for MCP server use
boyce scan ./my-project/ --save

10 种解析器：dbt manifest、dbt 项目、LookML、SQLite、DDL、CSV、Parquet、Django、SQLAlchemy、Prisma。

---

验证安装

# Unit tests — no DB required, runs in ~4 seconds
python boyce/tests/verify_eyes.py

# Expected output:
# Ran 15 tests in 3.5s
# OK
# ✅  All checks passed.

---

SemanticSnapshot 格式

ingest_source 工具接受 SemanticSnapshot JSON 字典。最简示例：

{
  "snapshot_id": "<sha256>",
  "source_system": "dbt",
  "entities": {
    "entity:orders": {
      "id": "entity:orders",
      "name": "orders",
      "schema": "public",
      "fields": ["field:orders:order_id", "field:orders:revenue"]
    }
  },
  "fields": {
    "field:orders:order_id": {
      "id": "field:orders:order_id",
      "entity_id": "entity:orders",
      "name": "order_id",
      "field_type": "ID",
      "data_type": "INTEGER"
    }
  },
  "joins": []
}

完整的字段/实体示例见 boyce/tests/live_fire/mock_snapshot.json。

---

项目布局

boyce/                          ← PRIMARY — headless FastMCP server + pip package
├── boyce/
│   ├── server.py               ← MCP entry point (8 tools)
│   ├── kernel.py               ← Deterministic SQL kernel
│   ├── graph.py                ← SemanticGraph (NetworkX)
│   ├── safety.py               ← Redshift compatibility rails
│   ├── types.py                ← Protocol contract (Pydantic)
│   ├── scan.py                 ← Scan CLI (boyce scan)
│   ├── connections.py          ← DSN persistence (ConnectionStore)
│   ├── doctor.py               ← Environment diagnostics (boyce doctor)
│   ├── sql/                    ← SQLBuilder, dialect layer, join resolver
│   ├── parsers/                ← 10 parsers (dbt, lookml, ddl, sqlite, csv, etc.)
│   ├── planner/                ← QueryPlanner (LiteLLM → StructuredFilter)
│   └── adapters/               ← PostgresAdapter (Eyes)
└── tests/
    ├── verify_eyes.py          ← 15-test suite, no DB required
    ├── test_parsers.py         ← Parser tests (all 10 parsers)
    ├── test_scan.py            ← Scan CLI tests
    └── live_fire/              ← Docker Compose integration tests

---

状态

功能	状态
自然语言 → SQL（确定性内核）	正常运行
SemanticGraph（连接解析）	正常运行
10 种数据源解析器	正常运行
Scan CLI（boyce scan）	正常运行
PostgresAdapter（只读）	正常运行
EXPLAIN 预检验证	正常运行
NULL 陷阱检测	正常运行
Redshift 1.0 安全检查	正常运行
重启后保留快照	正常运行
审计日志（仅追加 JSONL）	正常运行
业务定义（ingest_definition）	正常运行
DSN 持久化（ConnectionStore）	正常运行
环境诊断（boyce doctor / check_health）	正常运行
多快照合并	计划中

---

支持

• 故障排除指南： docs/troubleshooting.md
• 本地 LLM 设置（Ollama/vLLM）： docs/local-llm-setup.md
• Bug 报告： GitHub Issues
• 设置帮助： GitHub Issues
• 电子邮件： [email protected] — 用于涉及凭据或敏感配置的问题

---

版权所有 2026 Convergent Methods, LLC。MIT 许可证。