GoldenCheck

移行しました。 このリポジトリは benzsevern/goldenmatch モノレポ内の packages/python/goldencheck (and packages/typescript/goldencheck)/ に移行しました。このリポジトリはアーカイブされており、新規開発はモノレポで行われます。

GoldenCheck

データからルールを自動検出するため、ルールを自分で記述する必要がないデータ検証ツールです。 Ben Severn が開発しました。

競合製品はどれも、まずルールを記述する必要があります。GoldenCheck はその逆です。まず検証し、必要なルールだけを残します。

GoldenCheck を選ぶ理由

	GoldenCheck	Great Expectations	Pandera	Pointblank
ルール	データから自動検出	手動で記述	手動で記述	手動で記述
設定	すぐに使い始められる	大規模な YAML/Python の設定	デコレーター／スキーマ	YAML/Python
インターフェース	CLI + 対話型 TUI	HTML レポート	例外	HTML／ノートブック
学習曲線	コマンド 1 つ	数時間〜数日	中程度	中程度
LLM による強化	あり（スキャン 1 回あたり $0.01）	なし	なし	なし
修正案	あり（TUI 内）	なし	なし	なし
信頼度スコア	あり（検出結果ごとに H/M/L）	なし	なし	なし
DQBench スコア	88.40	21.68（ベストエフォート）	32.51（ベストエフォート）	6.94（自動）

インストール

pip install goldencheck

LLM による強化をサポートする場合：

pip install goldencheck[llm]

詳細なプロファイリングとベースラインのサポートを利用する場合（scipy、numpy）：

pip install goldencheck[baseline]

ベースラインのセマンティック型推論を利用する場合（sentence-transformers）：

pip install goldencheck[baseline,semantic]

JavaScript / TypeScript

npm install goldencheck

エッジセーフなコア（ブラウザー、Cloudflare Workers、Vercel Edge）：

import { scanData, TabularData } from "goldencheck/core";

Node.js（ファイル読み込み、CLI、MCP）：

import { readFile, scanData } from "goldencheck/node";

クイックスタート

# Scan a file — discovers issues, launches interactive TUI
goldencheck data.csv

# CLI-only output (no TUI)
goldencheck data.csv --no-tui

# With LLM enhancement (requires API key)
goldencheck data.csv --llm-boost --no-tui

# Validate against saved rules (for CI/pipelines)
goldencheck validate data.csv

# JSON output for CI integration
goldencheck data.csv --no-tui --json

# Learn baseline (one-time, deep analysis)
goldencheck baseline data.csv

# Scan with drift detection (fast, uses saved baseline)
goldencheck scan new_data.csv

TypeScript クイックスタート

// Scan an array of records (edge-safe — works anywhere)
import { scanData, TabularData, Severity } from "goldencheck";

const data = new TabularData([
  { id: 1, email: "[email protected]", age: 30, status: "active" },
  { id: 2, email: "[email protected]", age: -5, status: "inactive" },
  { id: 3, email: "not-an-email", age: 25, status: "active" },
]);

const { findings, profile } = scanData(data);
for (const f of findings) {
  console.log(`[${f.severity === Severity.ERROR ? "ERROR" : "WARNING"}] ${f.column}: ${f.message}`);
}

// Scan a CSV file (Node.js)
import { readFile, scanData, applyConfidenceDowngrade, healthScore } from "goldencheck/node";

const data = readFile("data.csv");
const result = scanData(data, { domain: "healthcare" });
const findings = applyConfidenceDowngrade(result.findings, false);

// Health score
const byCol = {};
for (const f of findings) {
  if (f.severity >= 2) {
    byCol[f.column] ??= { errors: 0, warnings: 0 };
    byCol[f.column][f.severity === 3 ? "errors" : "warnings"]++;
  }
}
const { grade, points } = healthScore(byCol);
console.log(`Health: ${grade} (${points}/100)`);

// Validate against pinned rules
import { readFile, scanData, validateConfig, validateData } from "goldencheck/node";
import { readFileSync } from "node:fs";
import YAML from "yaml";

const config = validateConfig(YAML.parse(readFileSync("goldencheck.yml", "utf-8")));
const data = readFile("data.csv");
const findings = validateData(data, config);

// Create baseline and detect drift
import { readFile, createBaseline, serializeBaseline, scanData } from "goldencheck/node";
import { runDriftChecks, deserializeBaseline } from "goldencheck";
import { writeFileSync, readFileSync } from "node:fs";

// Learn baseline
const data = readFile("reference.csv");
const baseline = createBaseline(data);
writeFileSync("baseline.json", serializeBaseline(baseline));

// Later: detect drift
const newData = readFile("production.csv");
const saved = deserializeBaseline(readFileSync("baseline.json", "utf-8"));
const driftFindings = runDriftChecks(newData, saved);

// LLM-enhanced scanning (edge-safe)
import { scanData, TabularData, callLlm, parseLlmResponse, mergeLlmFindings, buildSampleBlocks } from "goldencheck";

const data = new TabularData(records);
const result = scanData(data, { returnSample: true });
const blocks = buildSampleBlocks(result.sample, result.findings);
const { text } = await callLlm("anthropic", JSON.stringify(blocks));
const llmResponse = parseLlmResponse(text);
if (llmResponse) {
  const enhanced = mergeLlmFindings(result.findings, llmResponse);
}

仕組み

1. SCAN     →  goldencheck data.csv
                GoldenCheck profiles your data and discovers what "healthy" looks like

2. REVIEW   →  Interactive TUI shows findings sorted by severity
                Each finding has: description, affected rows, sample values

3. PIN      →  Press Space to promote findings into permanent rules
                Dismiss false positives — they won't come back

4. EXPORT   →  Press F2 to save rules to goldencheck.yml
                Human-readable YAML with your pinned rules

5. VALIDATE →  goldencheck validate data.csv
                Enforce rules in CI with exit codes (0 = pass, 1 = fail)

検出できる項目

列レベルのプロファイラー

プロファイラー	検出できる内容	例
型推論	実際には数値である文字列列	「列 age は文字列型ですが、98% が整数です」
NULL 許容性	必須列と任意列	「5 万行すべてで NULL が 0 件です。必須列である可能性が高いです」
一意性	主キー候補、ほぼ重複している値	「100% 一意です。主キーである可能性が高いです」
形式の検出	メールアドレス、電話番号、URL、日付	「94% がメール形式で、6% は形式が正しくありません」
範囲と分布	外れ値、最小値／最大値の範囲	「10,000 を超える値が 3 行あります」
カーディナリティ	カーディナリティの低い列挙型の候補	「一意な値が 4 つあります。列挙型の可能性があります」
パターンの一貫性	列内の形式の混在	「3 種類の電話番号形式が検出されました」

列間プロファイラー

プロファイラー	検出できる内容
時間順序	start_date > end_date の違反
NULL の相関	同時に NULL になる列（例：address + city + zip）
数値列間の検査	値 > 最大値の違反（例：claim_amount > policy_max）
年齢と生年月日	年齢列の値が、date_of_birth から計算した年齢と一致しない

ベースラインの詳細プロファイリングとドリフト検出

goldencheck baseline を一度実行して、正常なデータの統計プロファイルを作成します。その後のスキャンでは毎回、GoldenCheck が新しいデータを保存済みのベースラインと比較し、13 種類のチェックでドリフトを報告します。

チェックの種類	検出できる内容
distribution_drift	値の分布が大幅に変化した
entropy_drift	列の値のエントロピーが変化した
bound_violation	値が過去の最小値／最大値の範囲を超えている
benford_drift	先頭桁の分布がベンフォードの法則から逸脱している
fd_violation	列間の関数従属性が崩れている
key_uniqueness_loss	以前は一意だった列に重複が発生している
temporal_order_drift	過去の列の順序制約に違反している
type_drift	列の主要な意味型が変化した
correlation_break	以前は相関していた列が相関しなくなった
new_correlation	予期しない新たな相関が発生した
pattern_drift	値の形式／パターンの分布が変化した
new_pattern	列に新たな構造パターンが現れた

ベースラインは、次の 6 つの手法を使って作成されます：統計プロファイラー（分布、ベンフォードの法則、エントロピー）、制約マイナー（関数従属性、時間順序）、意味型推論器（埋め込み＋キーワード）、相関アナライザー（ピアソン、Cramér の V）、パターン文法の帰納、信頼度事前分布の構築。

ドメインパック

ドメイン固有の型定義を使用して、検出精度を高めます。

goldencheck scan data.csv --domain healthcare   # NPI, ICD, insurance, patient types
goldencheck scan data.csv --domain finance      # accounts, routing, CUSIP, transactions
goldencheck scan data.csv --domain ecommerce    # SKUs, orders, tracking, products

ドメインパックは、偽陽性を減らし、業界固有のデータの分類精度を高める意味型を追加します。

スキーマ差分

データファイルの 2 つのバージョンを比較します。

goldencheck diff data.csv                  # compare against git HEAD
goldencheck diff old.csv new.csv           # compare two files
goldencheck diff data.csv --ref main       # compare against a branch

自動修正

自動修正を適用して、データをクリーンアップします。

goldencheck fix data.csv                          # safe: trim, normalize, fix encoding
goldencheck fix data.csv --mode moderate          # + standardize case
goldencheck fix data.csv --mode aggressive --force # + coerce types
goldencheck fix data.csv --dry-run                # preview changes

監視モード

データ品質を確認するために、ディレクトリを継続的に監視します。

goldencheck watch data/ --interval 30        # re-scan every 30s
goldencheck watch data/ --exit-on error      # CI mode: fail on first error

REST API

GoldenCheck をマイクロサービスとして実行します。

goldencheck serve --port 8000

# Scan via file upload
curl -X POST http://localhost:8000/scan --data-binary @data.csv

# Scan via URL
curl -X POST http://localhost:8000/scan/url -d '{"url": "https://example.com/data.csv"}'

データベーススキャン

テーブルを直接スキャンします。CSV へのエクスポートは不要です。

pip install goldencheck[db]
goldencheck scan-db "postgresql://user:pass@host/db" --table orders
goldencheck scan-db "snowflake://..." --query "SELECT * FROM orders WHERE date > '2024-01-01'"

定期実行

Webhook 通知に対応した Cron のようなスケジュール設定です。

goldencheck schedule data/*.csv --interval hourly --webhook https://hooks.slack.com/...
goldencheck schedule data/*.csv --interval daily --notify-on grade-drop

LLM による強化

--llm-boost を追加すると、LLM の能力を活用してプロファイラーの検出結果を強化できます。LLM はデータの代表的なサンプルを受け取り、次の処理を行います。

1. プロファイラーが見逃す問題を検出 — 意味を理解して検出します（例：名前列にある「12345」）。
2. 重大度を引き上げ — プロファイラーが「INFO」としか示さなくても、「メールアドレスは必須にすべき」と判断します。
3. 関連性を発見 — signup_date と last_login のような列間の時間順序を特定します。
4. 偽陽性の重大度を引き下げ — 「電話番号形式の混在はよくあることで、エラーではありません」と判断します。

# Using OpenAI
export OPENAI_API_KEY=sk-...
goldencheck data.csv --llm-boost --llm-provider openai --no-tui

# Using Anthropic
export ANTHROPIC_API_KEY=sk-ant-...
goldencheck data.csv --llm-boost --no-tui

コスト： 1 スキャンあたり約 0.01 ドル（行ごとではなく、代表的なサンプルを使った API 呼び出し 1 回）。

予算管理：

export GOLDENCHECK_LLM_BUDGET=0.50  # max spend per scan in USD

設定（goldencheck.yml）

version: 1

settings:
  sample_size: 100000
  fail_on: error

columns:
  email:
    type: string
    required: true
    format: email
    unique: true

  age:
    type: integer
    range: [0, 120]

  status:
    type: string
    enum: [active, inactive, pending, closed]

relations:
  - type: temporal_order
    columns: [start_date, end_date]

ignore:
  - column: notes
    check: nullability

このファイルに記載されるのはピン留めされたルールのみであり、すべての検出結果ではありません。ignore リストを使うと、却下した検出結果が再表示されなくなります。

CLI リファレンス

コマンド	説明
goldencheck <file>	スキャンして TUI を起動
goldencheck scan <file>	明示的にスキャン（--smart、--guided に対応）
goldencheck validate <file>	goldencheck.yml に照らして検証
goldencheck review <file>	スキャンと検証を行い、TUI を起動
goldencheck init <file>	対話式セットアップウィザード（スキャン → 設定 → CI）
goldencheck diff <file> [file2]	2 つのファイル、またはファイルと git HEAD を比較
goldencheck watch <dir>	ディレクトリをポーリングし、変更時に再スキャン
goldencheck fix <file>	データ品質の問題を自動修正
goldencheck baseline <file>	データを詳細にプロファイリングし、統計的ベースラインを YAML に保存
goldencheck learn <file>	LLM 検証ルールを生成
goldencheck history	スキャン履歴と傾向を表示
goldencheck serve	REST API サーバーを起動
goldencheck scan-db <conn>	データベースのテーブルを直接スキャン
goldencheck schedule <files>	cron スケジュールでスキャンを実行
goldencheck mcp-serve	MCP サーバーを起動（19 個のツール）

フラグ

フラグ	説明
--no-tui	結果をコンソールに出力
--json	JSON 出力
--fail-on <level>	重大度が error または warning の場合に終了コード 1 を返す
--domain <name>	ドメインパック：healthcare、finance、ecommerce
--llm-boost	LLM による拡張を有効化
--llm-provider <name>	LLM プロバイダー：anthropic（デフォルト）または openai
--mode <level>	修正モード：safe、moderate、aggressive
--smart	自動トリアージ：確信度が高いものをピン留めし、低いものを却下
--guided	検出結果を 1 件ずつ確認
--webhook <url>	検出結果を Slack／PagerDuty／任意の URL に POST
--notify-on <trigger>	Webhook のトリガー：grade-drop、any-error、any-warning
--baseline <path>	ドリフト検出に使うベースライン YAML のパス
--no-baseline	goldencheck_baseline.yaml の自動検出をスキップ
--skip <technique>	ベースラインの手法をスキップ（複数指定可能）
--update	上書きせず、既存のベースラインを更新
-o <path>	ベースラインファイルの出力先（デフォルト：goldencheck_baseline.yaml）
--version	バージョンを表示

TypeScript CLI

npx goldencheck-js scan data.csv --json
npx goldencheck-js scan data.csv --domain healthcare
npx goldencheck-js health-score data.csv
npx goldencheck-js profile data.csv
npx goldencheck-js validate data.csv --config goldencheck.yml
npx goldencheck-js baseline data.csv --output baseline.json
npx goldencheck-js fix data.csv --mode safe
npx goldencheck-js diff old.csv new.csv
npx goldencheck-js demo

TypeScript アーキテクチャ

goldencheck (npm)
├── goldencheck/core    # Edge-safe: browsers, Workers, Edge Runtime
│   ├── types           # Finding, Severity, DatasetProfile, Config types
│   ├── data            # TabularData — zero-dep columnar abstraction
│   ├── profilers       # 10 column profilers + 4 relation profilers
│   ├── semantic        # Type classifier, suppression, 3 domain packs
│   ├── engine          # Scanner, confidence, validator, triage, differ, fixer
│   ├── baseline        # Statistical profiling, constraints, correlation, patterns
│   ├── drift           # 13 drift checks against saved baseline
│   ├── llm             # Anthropic + OpenAI via fetch(), merger, budget
│   ├── agent           # Strategy, handoff, review queue
│   └── reporters       # JSON, CI
└── goldencheck/node    # Node.js >= 20
    ├── reader          # CSV, Parquet (via nodejs-polars)
    ├── mcp             # MCP server (7 tools)
    ├── a2a             # Agent-to-Agent HTTP server
    ├── tui             # ANSI terminal output
    ├── db-scanner      # Postgres, MySQL, SQLite
    └── watcher         # Directory polling

ベンチマーク

速度

データセット	時間	スループット
1K rows	0.05s	19K rows/sec
10K rows	0.23s	43K rows/sec
100K rows	2.29s	44K rows/sec
1M rows	2.07s	482K rows/sec

DQBench v1.0 — 直接比較

ツール	モード	DQBench スコア
GoldenCheck	設定不要	88.40
Pandera	ベストエフォートのルール	32.51
Soda Core	ベストエフォートのルール	22.36
Great Expectations	ベストエフォートのルール	21.68

GoldenCheck の設定不要の検出機能は、競合製品のすべてを上回ります。手書きのルールを使用した場合でも同様です。

ベンチマークを自分で実行するには：

pip install dqbench goldencheck
dqbench run goldencheck

検出精度

モード	列の再現率	コスト
プロファイラーのみ（v0.1.0）	87%	$0
プロファイラーのみ（確信度機能付き v0.2.0）	100%	$0
LLM による拡張あり	100%	~$0.003-0.01

9 つのカテゴリにわたる 341 件のデータ品質問題を仕込んだ独自のベンチマークでテストしました。

v0.2.0 の改善点：少数の誤った型の検出、範囲プロファイラーの連結、より幅広い時間的ヒューリスティクス、確信度スコアリングにより、プロファイラーのみの場合の再現率が 87% から 100% に向上しました。

Raha ベンチマークデータセット

データセット	列の再現率
Flights（2,376 行）	100%（4/4 列）
Beers（2,410 行）	80%（4/5 列）

技術スタック

依存関係	用途
Polars	すべてのデータ操作
Typer	CLI フレームワーク
Textual	対話型 TUI
Rich	CLI 出力のフォーマット
Pydantic 2	設定の検証

オプション： LLM Boost 用の Anthropic SDK / OpenAI SDK | MCP サーバー用の MCP SDK | 詳細なベースラインプロファイリング用の scipy + numpy（[baseline]）| ベースラインでのセマンティック型推論用の sentence-transformers（[semantic]）

TypeScript / Node.js

依存関係	用途
ランタイム依存関係なし	コアパッケージに依存関係はありません（エッジセーフ）
nodejs-polars	Parquet の読み込み（オプション、Node.js のみ）
csv-parse	CSV の読み込み（Node.js のみ）
@modelcontextprotocol/sdk	MCP サーバー（Node.js のみ）

MCP サーバー（Claude Desktop）

GoldenCheck には、Claude Desktop との統合用 MCP サーバーが含まれています。

pip install goldencheck[mcp]

Claude Desktop の設定（claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "goldencheck": {
      "command": "goldencheck",
      "args": ["mcp-serve"]
    }
  }
}

利用可能なツール：

ツール	説明
scan	ファイルをスキャンしてデータ品質の問題を検出します（オプションで LLM による強化が可能）
validate	goldencheck.yml の固定ルールに照らして検証します
profile	列レベルの統計情報とヘルススコアを取得します
health_score	データファイルの簡易 A〜F 評価を取得します
get_column_detail	特定の列を詳しく調査します
list_checks	利用可能なすべてのプロファイラーチェックを一覧表示します

リモート MCP サーバー

GoldenCheck は Smithery でホスト型 MCP サーバーとして利用できます。インストールせずに、任意の MCP クライアントから接続できます。

Claude Desktop / Claude Code：

{
  "mcpServers": {
    "goldencheck": {
      "url": "https://goldencheck-mcp-production.up.railway.app/mcp/"
    }
  }
}

ローカルサーバー：

pip install goldencheck[mcp]
goldencheck mcp-serve

ファイルのスキャン、ルールの検証、列のプロファイリング、データセットのヘルススコア算出、検証の自動設定、調査結果の説明、ドメインの比較、修正案の提案を行う 19 個のツールを利用できます。

Jupyter / Colab

GoldenCheck は Jupyter ノートブックでリッチな HTML をレンダリングします。

from goldencheck.engine.scanner import scan_file
from goldencheck.engine.confidence import apply_confidence_downgrade
from goldencheck.notebook import ScanResult

findings, profile = scan_file("data.csv")
findings = apply_confidence_downgrade(findings, llm_boost=False)

# Rich HTML display in notebooks
ScanResult(findings=findings, profile=profile)

API クイックリファレンス

Python

import goldencheck

# Scan a CSV for quality issues
findings = goldencheck.scan_file("data.csv")
for f in findings:
    print(f"[{f.severity}] {f.column}: {f.check} — {f.message}")

# Create baseline and detect drift
from goldencheck import create_baseline, scan_file
baseline = create_baseline("data.csv")
baseline.save("goldencheck_baseline.yaml")
findings, profile = scan_file("data.csv", baseline="goldencheck_baseline.yaml")

# Health score
score = goldencheck.health_score("data.csv")
print(score)  # e.g. "B (78/100)"

TypeScript

import { scanData, TabularData, Severity } from "goldencheck";

// Scan records (edge-safe)
const data = new TabularData(records);
const { findings, profile } = scanData(data);
for (const f of findings) {
  console.log(`[${f.severity === Severity.ERROR ? "ERROR" : "WARNING"}] ${f.column}: ${f.message}`);
}

import { readFile, scanData, applyConfidenceDowngrade, healthScore } from "goldencheck/node";

// Scan a CSV file (Node.js)
const data = readFile("data.csv");
const result = scanData(data, { domain: "healthcare" });
const findings = applyConfidenceDowngrade(result.findings, false);

// Health score
const byCol = {};
for (const f of findings) {
  if (f.severity >= 2) {
    byCol[f.column] ??= { errors: 0, warnings: 0 };
    byCol[f.column][f.severity === 3 ? "errors" : "warnings"]++;
  }
}
const { grade, points } = healthScore(byCol);
console.log(`Health: ${grade} (${points}/100)`);

import { readFile, createBaseline, serializeBaseline } from "goldencheck/node";
import { runDriftChecks, deserializeBaseline } from "goldencheck";
import { writeFileSync, readFileSync } from "node:fs";

// Create baseline and detect drift
const data = readFile("reference.csv");
const baseline = createBaseline(data);
writeFileSync("baseline.json", serializeBaseline(baseline));

const newData = readFile("production.csv");
const saved = deserializeBaseline(readFileSync("baseline.json", "utf-8"));
const driftFindings = runDriftChecks(newData, saved);

コントリビュート

開発環境のセットアップとガイドラインについては、CONTRIBUTING.md をご覧ください。

作者

Ben Severn

ライセンス

MIT — LICENSE をご覧ください。

---

Golden Suite の一部

ツール	用途	インストール
GoldenCheck	データ品質を検証・プロファイリング	pip install goldencheck / npm install goldencheck
GoldenFlow	データを変換・標準化	pip install goldenflow
GoldenMatch	レコードの重複を排除・照合	pip install goldenmatch
GoldenPipe	パイプライン全体をオーケストレーション	pip install goldenpipe

関連プロジェクト：

• dbt-goldencheck — dbt テストとしてのデータ検証。
• goldencheck-types — コミュニティが提供するドメイン型パック。
• goldencheck-action — PR コメントに対応した CI 用 GitHub Action。