Boyce

Boyce：エージェント型データベースワークフローのためのセマンティックプロトコル＆セーフティレイヤー

エージェント型データベースワークフローのためのセマンティックセーフティレイヤーです。 Boyce は、組み込みの安全策により、LLM を実際のデータベースコンテキストに接続します。

SQL の共同発明者（1974 年）であり、Boyce-Codd 正規形（BCNF）の共著者である Raymond F. Boyce にちなんで名付けられました。

適切なコンテキストなしでデータベースにクエリを実行する AI エージェントは、信頼性の低い SQL を生成します。不完全なスキーマをもとに作業し、カラム名を推測し、結合パスを当てずっぽうで判断します。Boyce は、正確で安全な SQL を毎回生成するためにエージェントが必要とする、構造化されたデータベースインテリジェンスを、相互に連携する 3 つのシステムを通じて提供します。

レイヤー	機能
SQL コンパイラー	ask_boyce — 自然言語 → StructuredFilter → 決定論的な SQL。SQL ビルダーに LLM は一切使用しません。同じ入力からは、毎回バイト単位でまったく同じ SQL が生成されます。
データベースインスペクター	query_database / profile_data — ライブ Postgres/Redshift アダプターにより、エージェントはフィルターを 1 つ書く前に、実際のスキーマと実際のデータ分布を確認できます。
クエリ検証	生成されるすべてのクエリで、事前に EXPLAIN ループを実行します。不正な SQL は、午前 2 時のオンコール対応中ではなく、プランニング時に検出されます。

なぜ重要なのでしょうか？ → ヌルトラップ：AI エージェントの 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

または、手動で設定できます。ホストに応じて、2 つのセットアップ方法があります。

---

方法 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 組み込みの自然言語→SQL を使用

CLI（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 用のベアラートークン
BOYCE_STATEMENT_TIMEOUT_MS	任意	30000	ステートメントごとのタイムアウト（ミリ秒、デフォルト：30s）

---

MCP ツール

ツール	説明
ingest_source	dbt manifest、dbt プロジェクト、LookML、DDL、SQLite、Django、SQLAlchemy、Prisma、CSV、Parquet から SemanticSnapshot を解析します。
ingest_definition	認定済みのビジネス定義を保存します。クエリ実行時に自動的に挿入されます。
get_schema	スキーマの全コンテキストと StructuredFilter 形式のドキュメントを返します。MCP ホストが Boyce API キーなしでクエリを構築できるよう、ホストの LLM が使用します。
ask_boyce	自然言語から SQL への全パイプライン：クエリプランナー（LiteLLM）→ 決定論的カーネル → NULL トラップチェック → EXPLAIN による事前検証。
validate_sql	手書き SQL を実行せずに検証します。EXPLAIN による事前検証、Redshift の lint、NULL リスクを確認します。
query_database	ライブデータベースに対して読み取り専用の SELECT を実行します。書き込み操作は独立した 2 つのレイヤーで拒否されます。
profile_data	任意のカラムの NULL 率、個別値の数、最小値／最大値を確認し、クエリ結果に影響する前にデータ品質の問題を明らかにします。
check_health	DB 接続、スナップショットの鮮度、実行可能な修正コマンドを確認する運用ヘルスチェックです。クエリが予期せず失敗した場合に呼び出してください。

---

アーキテクチャ

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）：Redshift 1.0（PG 8.0.2）向けに、LATERAL、JSONB、REGEXP_COUNT、後読み正規表現パターンの自動 lint と数値キャストの書き換えを行います。

---

スキャン 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 dict を受け付けます。最小限の例：

{
  "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 種類のソースパーサー	稼働中
スキャン CLI（boyce scan）	稼働中
PostgresAdapter（読み取り専用）	稼働中
EXPLAIN による事前検証	稼働中
NULL Trap の検出	稼働中
Redshift 1.0 の安全 lint	稼働中
再起動後のスナップショット永続化	稼働中
監査ログ（追記専用 JSONL）	稼働中
ビジネス定義（ingest_definition）	稼働中
DSN 永続化（ConnectionStore）	稼働中
環境診断（boyce doctor / check_health）	稼働中
複数スナップショットのマージ	予定

---

サポート

• トラブルシューティングガイド： docs/troubleshooting.md
• ローカル LLM のセットアップ（Ollama/vLLM）： docs/local-llm-setup.md
• バグ報告： GitHub Issues
• セットアップのサポート： GitHub Issues
• メール： [email protected] — 認証情報や機密性の高い設定に関する問題はこちらへご連絡ください

---

Copyright 2026 Convergent Methods, LLC. MIT License.