GoldenAnalysis

> **v3.22.0：ゼロ設定の人物重複排除が18～30倍高速になり、レコードは入力時の値のまま返されます。** 25万行の処理時間は520秒から18秒になり、クラスターは同一です（アップグレードにより `goldenmatch-native` 0.2.3がインストールされます）。一意、重複、重複排除済みの各テーブルには、標準化された値ではなく元の値が保持されるようになりました。以前の出力に戻すには、`keep_original_values=False` または `--standardized-values` を指定します。 > > **v3.21.0：小さなファイルで誤警告が出なくなり、要求していないLLM呼び出しも行われなくなりました。** 小さなファイルを正しく処理した場合、「精度が低い可能性があります」という赤いログが表示されなくなりました。また、自動設定で（有料の）LLM スコアラーが有効になるのは、`llm_auto=True` を渡した場合だけになりました。以前は、`OPENAI_API_KEY` または `ANTHROPIC_API_KEY` が設定されているだけで有効になっていました。この動作に依存していた場合は、`llm_auto=True` を渡すか、設定で `llm_scorer` を指定してください。 > > **v3.20.0：整数ID列が原因でゼロ設定の処理がクラッシュすることはなくなりました。** 電話番号列やアカウント列が数字のみ（int64として読み込まれる）のCSVでは、自動設定のブロッキング処理で `ArrowNotImplementedError` が発生し、`gm.dedupe(path)` と `goldenmatch dedupe` が異常終了していました。現在は正常に実行され、そのような列の否定的な根拠も、無効化されることなくスコアに反映されます。CLIの要約には、集計内容が表示されるようになりました（`12 records -> 7 entities (4 duplicate groups)`）。また、`result.total_entities` もこの値と一致します。

---

試してみる

pip install goldenmatch
goldenmatch dedupe customers.csv

同じ人が複数回入力されている customers.csv を用意します。

id	名前	メールアドレス	電話番号	住所	郵便番号
1	Maria Gonzalez	[email protected]	555-201-3344	14 Oak Street	62704
2	Maria Gonzales	[email protected]	(555) 201-3344	14 Oak St	62704
3	María González	[email protected]	5552013344	14 Oak St.	62704
4	James O'Neil	[email protected]	555-883-1200	902 Pine Avenue	84065
5	Jim O'Neill	[email protected]	555.883.1200	902 Pine Ave	84065
8	Thomas Becker	[email protected]	555-667-0192	77 Elm Court	97024
12	Thomas Baker	[email protected]	555-120-4455	41 Walnut Way	97024

GoldenMatchは、行1～3を同じ人物としてまとめ、行4～5を別の人物としてまとめます。Thomas BeckerとThomas Bakerは郵便番号が同じですが、別々のままです。各グループは、各フィールドの最適な値を使って1つのゴールデンレコードになります。実行すると、1人につき1行の <timestamp>_deduplicated.csv（4件のゴールデンレコードと、重複のなかった3人）と、統合されたレコードのみを含む <timestamp>_golden.csv が出力されます。

Pythonから実行する場合：

import goldenmatch as gm

result = gm.dedupe("customers.csv")
print(result)       # DedupeResult(records=12, clusters=4, match_rate=75.0%)

result.deduplicated # one row per person: 7 here
result.golden       # one merged record per duplicate group
result.unique       # the records that had no duplicate
result.clusters     # which input rows belong together
result.config       # the matching config it chose

データがすでにメモリ上にある場合は、gm.dedupe_df(table) に pyarrow Table または polars DataFrame を渡せます。

判定内容と変更方法

ここでの処理はブラックボックスではありません。上記のファイルでは、自動設定によって email と phone は完全一致で、name と address はあいまい一致で照合され、zip が共通するレコード同士のみが比較されました。この判定内容は result.config に保存されます。

• 再利用する場合は、新しいデータに適用します：gm.dedupe("next_month.csv", config=result.config)。
• 独自のルールを使う場合は、gm.dedupe("customers.csv", exact=["email"], fuzzy={"name": 0.85}) または YAML 設定を指定します。設定を参照してください。

1つのファイルを超えて

顧客データは、CRM、請求システム、そして誰も管理していない3つのスプレッドシートに分散しています。重複しているレコードもあれば、同じ会社名が4通りの表記になっていることもあります。実際の顧客数はいくつなのか、誰にも答えられません。そのうえ、これらのデータをもとに構築されたすべてのダッシュボードにも、その疑念が引き継がれます。

Splinkを上回るエンティティ解決を、チューニング不要でArrowネイティブかつRustの高速性で実現し、あらゆるソースの不揃いなレコードを、レコード全体のCustomer-360プロベナンスを備えた安定したゴールデンエンティティに変える永続的なアイデンティティレイヤーへとつなぎます。

ゼロ設定のマッチングにより、不揃いな顧客レコードで、専門家がチューニングしたSplinkを直接対決で上回ります。ArrowネイティブでRustを正とするエンジンは、ノートPC上のCSVから2億5,000万行の重複排除を11.2分で完了するまで検証済みです。生成されたアイデンティティは、安定したentity_id、フィールドごとのプロベナンス、マージ／分割、改ざん検知可能な監査ログを備えたトランザクションネイティブのコントロールプレーンに保存され、すべてを1回の呼び出しでCustomer 360として利用できます。さらに、独自のプリミティブを備えています。依存関係を借りるのではなく、バイト単位で同一かつrapidfuzz／jellyfish／FAISSより高速なRustカーネルを採用しています。

Python・TypeScript・SQLで小数点以下4桁まで一致 · Postgres + DuckDBにネイティブ対応 · エッジWASM · 70以上のMCPツール · 手動チューニングしたSplinkを上回る · 2億5,000万行を11.2分で処理

_{Webワークベンチでのペアの詳細表示：クラスターメンバー、フィールドレベルの差分、各ペアの1行の自然言語による説明を確認できます。pip install goldenmatch[web]のあと、goldenmatch serve-ui <project>を実行してください。その他のスクリーンショット →}

---

得られるもの：ゴールデンエンティティ

多くのエンティティ解決ツールは、クラスタを返してそこで終わります。GoldenMatch はその先まで進み、煩雑なレコードを永続的なゴールデンエンティティに解決します。実世界の顧客ごとに 1 つのエンティティを作成し、再実行しても維持され、すべてのフィールドの来歴を記録し、「これは誰で、各値はどこから来たのか？」という問いに 1 回の呼び出しで答えます。

• 使い捨てのクラスタ ID ではなく、安定した ID。 各エンティティには安定した entity_id（UUIDv7）が割り当てられ、新しいデータが届いても実行をまたいで維持されます。レコードは取り込まれ、エンティティは統合または分割されますが、エンティティに割り当てられた ID は下流システムが信頼できるものです。実行ごとのクラスタ番号は実行のたびに変わりますが、この ID は変わりません。
• レコード全体の来歴。 ゴールデンレコードの各フィールドは、その値が採用された元のレコードまでたどれます。どのソースから来たのか、最後に確認されたのはいつか、どのサバイバーシップ戦略で選ばれたのかを確認できます。採用されなかった値も、ひそかに破棄されることなく表示されます。来歴はマッチングの判断だけでなく、統合されたレコード全体に記録されます。
• 設計段階からガバナンスに対応。 競合する値は、明示的なサバイバーシップポリシー（最も完全な値・ソース優先順位・最新の値・多数決）によって最適な 1 つの値に集約されます。すべての ID 変更は追記専用のイベントタイムラインに記録され、ログはハッシュチェーン方式の改ざん検知可能な監査記録によって保護されます。レビュー担当者（またはもう一方の言語ポート）が個別に検証できます。

customer_360(entity_id) は以下を 1 つの読み取りにまとめます。ゴールデンレコード、フィールドごとの来歴、リンクされたすべてのソースレコード、イベントタイムライン、エンティティのリレーションシップ近傍です。

// customer_360("018f...c2a1")  (trimmed)
{
  "entity_id": "018f2b7e-...-c2a1", "confidence": 0.97, "record_count": 3,
  "sources": ["salesforce", "billing", "support"],
  "golden_record": { "name": "Ada Lovelace", "email": "[email protected]", "phone": "+1-555-0100" },
  "field_provenance": [
    { "field": "email", "value": "[email protected]",
      "winning_source": "billing", "winning_record_id": "billing:8821",
      "conflicting_values": [ { "value": "[email protected]", "source": "salesforce" } ] },
    { "field": "phone", "value": "+1-555-0100", "winning_source": "salesforce" }
  ],
  "timeline": [ { "kind": "created", "actor": "pipeline", "recorded_at": "2026-07-30T..." },
                { "kind": "absorbed_record", "reason": "matched billing:8821" } ],
  "relationships": [ { "other_entity_id": "018f...9d0e", "kind": "shares_address" } ]
}

現在提供されている機能と、開発中の機能。 ID スパインは本番品質で、main に含まれています。安定した entity_id、フィールドごとの来歴、サバイバーシップ、統合・分割、追記専用ログと監査チェーン、チャネル横断の名寄せ、リレーションシップオーバーレイ、そして永続化されたインデックスに対する増分解決（新しいレコードを全件再実行なしで解決）が含まれます。上記の**customer_360() サービングビューと、ライブシステムから最新状態を保つソースレジストリ**レイヤーは、現在積極的に実装を進めている新しい機能です。ソースコネクター（Snowflake、BigQuery、Salesforce、HubSpot）は現在提供されていますが、それらを ID スパインに接続するレジストリは開発中です。Customer 360 の設計と ADRを参照してください。境界を曖昧にせず、明示しています。

ゴールデンエンティティはコントロールプレーンに存在し、それを構築するマッチング処理はコンピュートエンジンで実行されます。この分離については次のセクションで説明します。

---

1つのプロダクト、2つのエンジン

上記のゴールデンエンティティは、実質的に異なるものを最適化する2つのエンジンによって生成されます。それらを分けておくことは実装の詳細ではなく、アーキテクチャそのものです（ADR 0047）。

flowchart LR
    src([source records])
    e360([golden entities · Customer 360])
    subgraph compute ["Identity Compute Engine: Arrow-native, Rust-authoritative"]
        match[block · score · cluster]
    end
    subgraph control ["Identity Control Plane: transaction-native state machine"]
        spine[stable ids · survivorship · merge/split · provenance · audit]
    end
    src --> compute -->|resolution batch + evidence| control --> e360
    control -.->|persisted index| compute

	アイデンティティ計算エンジン	アイデンティティ制御プレーン
形状	バルク処理の境界では Arrow、カーネルは Rust が権威を持ちます	トランザクションネイティブな状態マシン（デフォルトは SQLite · Postgres）
役割	ブロック化、スコアリング、クラスタリング：スループット重視、ベクトル化、実行ごとに決定的	安定した ID、サバイバーシップ、マージ／分割、来歴、追記専用の監査
状態	呼び出しごとにステートレス。測定に基づくカーネル化	永続的、トランザクション対応、再生可能、監査可能
バックエンド	DataFusion · Ray · Sail · Spark は交換可能な実行バックエンドであり、GoldenMatch と同義のものはありません	ストレージバックエンドは、外部から観測できる1つのセマンティクスに準拠します

多様なインターフェース、1つの答え。 同じ機能を Python、エッジセーフな TypeScript（同じ Rust カーネルを実行するオプトインの WASM バックエンド付き）、PostgreSQL と DuckDB 内の SQL、さらに MCP／REST／A2A から利用できます。すべてはコピー＆ペーストではなく、仕様＋適合性によって統制されます。各機能には権威を持つオーナーが1つあります。純粋な Python／スタンドアロンの TS の経路は、適合性テスト済みのフォールバックとして分類されます。境界をバイト単位で越えられない場合は、同等性を主張するのではなく、測定して明示します。

プラットフォームエンジニアにとって重要な理由：

• 計算レイヤーはフレームワークにロックインされません。 Arrow ネイティブでバックエンドを交換できるため、プランニング、スピル、分散処理が可能なクエリエンジンに、重いマッチングを任せられます（2億5,000万行まで検証済み）。その際、アイデンティティの状態を持ち込む必要はありません。
• アイデンティティレイヤーは本物の状態マシンです。 毎回再構築するカラムナーバッチではありません。永続的な ID、トランザクション対応のマージ／分割、来歴、監査は、連携して利用できる第一級の操作です。
• 共有される範囲では、動作に一貫性があります。 SQL、Python、TypeScript は、適合性仕様に照らして同じ答えを返すため、構築の基盤となるインターフェースが独自のセマンティクスをひそかに作り出すことはありません。

---

専門家を上回る名寄せ

ID レイヤーの品質は、その下にあるマッチングの品質次第です。そして、マッチングはゼロコンフィグから始められます。dedupe_df(df) はルールもトレーニングデータも不要で実行でき、データをプロファイリングして妥当な設定を選び、すぐにゴールデンレコードを返します。選択された設定は result.config に返されるため、確認、差分比較、バージョン管理ができます。ブラックボックスにはなりません。

• 初期状態で専門家を上回ります。 ノイズの多い顧客レコードでは、オプトイン方式の Fellegi-Sunter エンジンが、手作業で調整した Splink を直接比較で上回ります。historical_50k では、ペア単位の F1 が 0.827 対 0.757、クラスタ B³ が 0.862 対 0.788 です。評価器は共通で、再現可能な比較テストを実施できます。ファジー、完全一致、確率的（Fellegi-Sunter）、LLM スコアラーに加え、EM でトレーニングした重みとキャリブレーション済みスコアを利用できます。
• 一度きりではなく、改善を続けるループ。 ゼロコンフィグで大部分を処理し、その後の各実行で無料の教師なしシグナルを確認します。改善の余地がある場合は、優先順位付けされ、自己検証済みの設定変更案を result.suggestions に追加します。各変更案は健全性の代理指標を悪化させない場合にのみ保持されるため、提案によって結果が悪化することはありません。dedupe_df(df, heal=True) を使うと、1 回の呼び出しで変更を適用して再実行できます。専門家でなくても、専門家が調整した結果との差を縮められます。
• プライバシーを保護するレコードリンケージ。 生データを共有せずに組織間でマッチングできます。Bloom フィルターによる PPRL は、HMAC ソルト付きエンコーディングを使用し、FEBRL4 で F1 92.4％ を達成しています。
• 自己検証機能。 各ステップで実行前と実行後にチェックを行い、黙って失敗するのではなく、確認可能なレポートを返します。これが「高度でありながら、決してブラックボックスではない」という契約であり、安全な自動 ID レイヤーの基盤となります。

非構造化入力にも対応しています。PDF や画像からレコードを抽出し、ほかのソースと同様に名寄せできます（pip install goldenmatch[documents]）。

---

スタックに合わせて実行

エンジンと ID レイヤーは、すでに使っているインターフェイスを通じてスタックに接続します。各インターフェイスで個別に薄く再実装するのではなく、適合性テスト（#1 つの製品、2 つのエンジン）で管理された同じ機能を提供します。

• SQL ネイティブで、同等の機能を提供。 同じ関数を PostgreSQL（pgrx 拡張機能）と DuckDB 内で実行できます。名寄せ・マッチング・スコアリング・自動設定とテレメトリー・ID グラフの読み取り・プロファイリング・evaluate・Fellegi-Sunter スコアリング・GoldenFlow 変換に対応しています。ウェアハウスからデータを移動せずに名寄せできます。
• Python とエッジセーフな TypeScript。 フルスイートは PyPI に加えて npm でも提供されます。TS コアは依存関係がなく、node:* にも依存しないため、ブラウザー、Cloudflare Workers、Vercel Edge、Deno で利用できます。オプトインの WebAssembly バックエンド（await enableWasm()）を使うと、Python ホイールと SQL UDF が使用する pyo3 非依存の同じ Rust カーネルに切り替わります。デフォルトはバイト単位で同一の純粋な TS 実装です。
• デフォルトで AI ネイティブ。 各パッケージには MCP サーバー、REST API、A2A エージェントインターフェイスが付属します（スイート全体で 70 以上の MCP ツール）。Web、TUI、CLI、Postgres、DuckDB、MCP のいずれでも、同じ JSON テレメトリー形式を提供します。
• Spark 対応で、エグゼキューターに Python は不要。 Rust カーネルを単一の JAR（spark.addArtifact("goldenmatch-spark.jar")）で Spark クラスターに導入し、JNI 経由で呼び出せます。そのため、エグゼキューターに goldenmatch の仮想環境も、パッケージ化された環境も、インストール済みのソフトウェアも必要ありません。この経路では Fellegi-Sunter のトレーニングを分散実行できます。E ステップは合意パターンに対する Spark の GROUP BY として実行されるため、クラスターが集計を行い、ドライバーはモデルのフィッティングのみを行います。これはスループットではなく、デプロイのための選択肢です。JVM のスコアリング経路は、Python ワーカー経路より約 2.4 倍遅いことが実測されており、この経路を使う理由はインストールが不要なことです。
• パイプラインネイティブ。 dbt パッケージ（名寄せ／マッチングのマテリアライゼーション、品質テスト、ID グラフの読み取り）、GitHub Action（データ品質の低下時に PR を失敗させる）、そのまま使える Airflow DAG が 13 個あります（デプロイ）。
• 本番環境向けの経路。 Postgres 同期、デーモンモード、リネージ追跡、レビューキューに対応します。

言語間の同等性

表面的な同等性とは、パイプラインのどのフェーズでも、一方の言語からもう一方の言語へバイト単位でそのまま引き渡せるという意味ではありません。以下の各判定は、想定ではなく、適合性ハーネスによって測定されたものです。

境界	判定
Identity graph DB	✅ バイトセーフで、暗号学的に相互検証可能（一方のツールキットで書き込んだシールを、もう一方で検証できます）
score → cluster とエンドツーエンドの分割実行	✅ バイトセーフで、単一言語での実行を再現します
クラスター JSON · 設定 YAML · Learning Memory · record_fingerprint	✅ ポータブル
文字列スコアリング	🟡 小数点以下4桁の許容差があり、しきい値上のペアでは結果が変わる場合があります（共有 WASM スコアラーを使用した場合のみバイト単位で一致します）
標準化／日付 · 埋め込み · 自動設定コントローラー	🟠 動作が異なり、バイト単位での移植はできません
分散処理／Ray · ドキュメント（VLM）の取り込み	⛔ アーキテクチャ上、Python 専用です

経験則： クラスターまたはアイデンティティの境界で引き渡せばシームレスです。一方、standardize／日付、埋め込み、コントローラーをまたいで分割し、ビット単位で完全に一致する結果を期待しないでください。詳細と、これらの判定を検証可能な状態に保つ実行可能なハーネスについては、言語間の同等性とフェーズ引き渡しの制限をご覧ください。

---

スイート：パイプラインを支える基盤

GoldenMatch は看板製品ですが、エンティティ解決の品質は、その入力元の品質に左右されます。5つの関連ツールが、レコードをアイデンティティレイヤーに渡す前に、クリーンアップ、標準化、マッピングを行います。それぞれ単独でも利用できますが、GoldenPipe が宣言的にオーケストレーションすることで、1つのパイプラインとして組み合わせられます。

flowchart LR
    raw([raw rows])
    golden([golden entities])
    subgraph orchestration ["GoldenPipe orchestrates"]
        direction LR
        infermap[InferMap] --> goldencheck[GoldenCheck] --> goldenflow[GoldenFlow] --> goldenmatch[GoldenMatch]
    end
    raw --> infermap
    goldenmatch --> golden

パッケージ	言語	パイプラインでの役割	インストール
InferMap	Python · TS	スキーママッピング：異種ソース間の列を自動で対応付けます	pip install infermap · npm i infermap
GoldenCheck	Python · TS	データ品質のスキャン：エンコーディング、形式の検証、異常検出	pip install goldencheck · npm i goldencheck
GoldenFlow	Python · TS	変換と標準化：電話番号、日付、住所、カテゴリ値	pip install goldenflow · npm i goldenflow
GoldenMatch	Python · TS	設定不要のエンティティ解決 → アイデンティティ基盤。看板パッケージです。	pip install goldenmatch · npm i goldenmatch
GoldenAnalysis	Python · TS	分析とレポート作成：任意のステージの成果物 → 統合された AnalysisReport と、実行間のリグレッション検出	pip install goldenanalysis · npm i goldenanalysis
GoldenPipe	Python · TS	オーケストレーター：ステップを YAML で宣言的に接続します	pip install goldenpipe · npm i goldenpipe
golden-suite	Python	1行でメタインストール：スイート全体とネイティブアクセラレーション	pip install golden-suite

最も詳細なドキュメントは packages/python/goldenmatch/README.md にあります（約1,300行：機能一覧、CLI、アーキテクチャ、ベンチマークを網羅）。

共有コンポーネント

パイプラインのステージではなく、各ステージが連携するための部品と、エージェントが接続する単一の窓口です。

パッケージ	内容	インストール
goldencheck-types	共有の標準フィールド型レジストリ：すべてのパッケージと両言語で、フィールド型の意味を定める唯一の信頼できる情報源	pip install goldencheck-types · npm i goldencheck-types
goldensuite-mcp	すべてのスイートツールを単一のエンドポイント（stdio または Streamable HTTP）で公開する1つの MCP サーバー	pip install goldensuite-mcp

所有ライブラリ（単独利用可能）

このスイートは、文字列マッチングの基本機能を外部から借りるのではなく、自前で提供しています。バイト単位で完全に一致するドロップイン代替品を個別に公開しているため、スイート外でも利用できます。

ライブラリ	置き換え対象	内容	インストール
goldenfuzz	rapidfuzz	あいまい文字列のスコアラーに加え、fuzz.* の複合関数一式、および1対多数の extract／cdist を提供します。バイト単位で完全に一致し（オラクルによるファジングで検証済み）、短い文字列ではより高速です。	pip install goldenfuzz · cargo add goldenfuzz-core
goldenphonetic	jellyfish	音声的符号化関数：soundex／metaphone／nysiis／match-rating。バイト単位で完全に一致し（6,000件の入力と2,500組のファジングコーパスで検証済み）、依存関係のない純粋な Rust 実装です。	pip install goldenphonetic · cargo add goldenphonetic-core
goldenmatch-hnsw	FAISS IndexHNSWFlat	C 依存関係のない、純粋な Rust による HNSW 近似最近傍インデックスです。Python、Rust、TS/WASM における埋め込みベースのブロッキングを支えます。	pip install goldenmatch-hnsw

ナレッジグラフ

エンティティ解決は、ほとんどの GraphRAG パイプラインが最も苦手とする段階です。同じエンティティを指す表記の揺れが、複数の文書に散在してしまいます。2つのパッケージが、GoldenMatch の解決機能をこの領域に提供します。

パッケージ	機能	ステータス
goldenmatch-kg	既存の KG フレームワーク（neo4j-graphrag、LlamaIndex、Graphiti）の ER 段階で、GoldenMatch による解決機能をドロップインで提供します。	リポジトリ内 · 未公開（意図的）
goldengraph	テキストから独自の KG を構築します：text → LLM extraction → GoldenMatch resolution → durable bi-temporal store。Rust エンジンを採用し、ER が差別化要因です。	リポジトリ内 · PyPI 初回リリース準備中

主張ではなく、測定結果です（ER-KG-Bench）。ラベル付きデータセットで、解決スコアは F1 0.602 となり、Neo4j-KGBuilder（0.456）、neo4j-graphrag（0.403）、MS-GraphRAG／LightRAG／Cognee／mem0（0.066）を上回ります。解決済みグラフは、パッセージウィンドウ方式の RAG では構造上実現できないことも2つ可能にします。正確な集計（クラスタサイズの区分をまたいでも不変。RAG の再現率が 0.99 → 0.64 に低下する場合でも維持）と、過去時点での検索（過去日付のクエリで 1.000 対 0.002）です。

---

規模とベンチマーク

すべての主要な数値は、コミット済みの単一の実行スクリプト（scripts/run_benchmarks.py）で再現できます。数値ごとのコマンド、データセットの URL、許容誤差を含む期待出力については、docs/reproducing-benchmarks.md を参照してください。

• 顧客データに近いデータでの精度。 NC Voter は F1 0.9719（実データのサンプル）、Febrl3 は F1 0.9912 です。オプトイン方式の Fellegi-Sunter パスは、Splink がスコアを算出するすべてのデータセットで、手動調整した Splink を直接比較で上回ります（比較結果）。（書誌データベースの DBLP-ACM では、レコードリンケージ分野向けに F1 96.4% を達成していますが、重点は顧客のアイデンティティです。）
• プライバシー保護。 PPRL は FEBRL4 で F1 92.4% を達成し、生データを共有せずに当事者間でマッチングします。
• スケールの適用範囲（docs/scale-envelope.md）：バックエンド別の規模範囲（インメモリ／バケット方式は数百万件まで · DuckDB のアウトオブコア処理は約5,000万件まで · Ray による分散処理は5,000万件以上）、ブロックサイズに起因する失敗パターン、バックエンド選定のための判断ツリーを説明しています。 Ray ティアで検証済み： 5 ノードの Ray クラスターで、1 億行の重複排除を 9.2 分（554 秒）で完了し、20,000,000 件のゴールデンレコードを正確に復元、ドライバーのピーク RSS は 0.36 GB でした。（より大規模な 2 億 5,000 万行／11.2 分という見出しは、異なるクラスター構成の Spark ティアのものです。この 2 つは別々のレーンであり、一方が他方に取って代わる数値ではありません。また、以下の再現率完全保証を備えているのはこちらです。）デフォルトの分散処理パスは再現率完全です。入力のパーティション分割方法にかかわらず、重複データを正しく統合します（ブロッキングキーのシャッフルによるスコアリング＋分散ランダム化縮約 WCC）。また、処理の最初から最後までドライバーにデータを集めません。設定例：configs/distributed-100m.yaml。

Spark 上で分散処理する Fellegi-Sunter 学習： E ステップは、合意パターンに対する Spark の GROUP BY 1 回に集約されるため、学習コストはペア数ではなく DISTINCT な比較ベクトルの数（prod(levels + 1) 以下）に応じて決まります。Python がインストールされていない、JAR のみのエグゼキューターを使用する実際の 2 ワーカー Spark クラスターで測定したところ、100 万行から 500 万行への増加で、候補ペアは 5.00 倍、分散カウント段階は 5.25 倍に増加しました。一方、distinct パターンは 3.0%（433 件から 446 件）の増加にとどまり、ドライバー側の EM は 0.01 秒のままでした。この特性がこのティアの基盤です。クラスターがデータを処理し、ドライバーの作業量は一定に保たれます。

実際の Spark クラスターで、5,000 万行を使って Splink と直接比較。 両エンジンを同じ 5 ノードクラスター、同じフィクスチャ、同じ共有メトリック実装で実行しました。また、Splink は独自のパフォーマンスガイドの推奨どおりに設定しました。実際の分散ファイルシステム上で break_lineage_method="parquet" を使用し、シャッフルパーティション数をクラスターのコア数の 5 倍に設定し、エグゼキューターは同じ 48 GB にしました。463,923,179 件の候補ペアを、両方で同一のスコアリングを行った結果：

	GoldenMatch	Splink	比率
経過時間	552 秒	1,054 秒	1.91 倍
u／推定値	3.5 秒	30.8 秒	8.78 倍
シャッフル書き込み	86.8 GB	212.1 GB	2.44 倍
ステージ数	119	394	3.31 倍
エグゼキューター CPU	31,300 秒	51,572 秒	1.65 倍

勝ちだけを公表するベンチマークは証拠にならないため、次の点も併せて報告します。規模が大きくなるほど差は縮まります（100 万行で 2.54 倍から、5,000 万行で 1.91 倍）。このレーンの単独実行の結果は約 16%変動するため、どの比率も過度に重視すべきではありません。この傾向を測定したビルドでは、スピルゼロは特定の規模までに限られていました（5,000 万行では該当、1 億行で 56.4 GB、2 億 5,000 万行で 201.3 GB。ただし #2698 により、その後 2 億 5,000 万行でスピルゼロを達成したため、この注意点は出荷済みのパスではなく傾向を説明するものです）。フィクスチャは合成データであり、そこに記載された精度の数値は精度の判定結果ではありません。精度については ベイクオフを参照してください。その後さらに測定： 同じ 5 ノードクラスターで、2 億 5,000 万行／23 億 2,000 万ペアを 670 秒で処理しました。エグゼキューターの停止も失敗タスクもゼロで、100 万ペアあたり 0.289 秒でした。この値は、この傾向を最初に測定したときの 2,766 秒より 4.13 倍高速で、エグゼキューター CPU は 3.1 倍少なく、スピルゼロ、学習済みモデルはバイト単位で完全に同一です。コストは行数ではなくペア数に対して線形に増加し、定数部分は 4 分の 1 になりました。この比較の過去 4 回の試みは、私たちが Splink の設定を誤っていたため無効でした。それぞれの不具合と影響は、結果と併せて記録されています。手法、注意点、再現コマンドの全詳細。

公開データを使い、実規模でこれを実行する、再現可能な実世界のパイプラインが 3 つあります。

• shell-company-network：ICIJ Offshore Leaks + OpenSanctions + GLEIF + UK PSC を横断する調査用 ER。単一ソースのベースラインと比べて、トリアージにかかるアナリストの作業時間を−62.5%削減します。
• vuln-attribution：40 のソースにわたる OSS 脆弱性レコード 6,126,895 件 → 正規化された脆弱性 847,475 件を、64GB のランナー 1 台で約 5 分で処理します。
• sanctions-reconciliation：50 以上の管轄区域における公開制裁リスト 85 件を横断して照合します。

---

インストールとクイックスタート

30 秒で CSV を重複排除。設定は不要で、<timestamp>_golden.csv に書き出します。

pip install goldenmatch && goldenmatch dedupe customers.csv

import goldenmatch as gm

result = gm.dedupe("customers.csv")               # zero-config
print(result)                                     # DedupeResult(records=12, clusters=4, match_rate=75.0%)
result.to_csv("golden.csv")                       # one merged record per duplicate group

result = gm.dedupe("customers.csv",               # or be explicit
    exact=["email"], fuzzy={"name": 0.85, "zip": 0.95}, blocking=["zip"], threshold=0.85)

import { dedupe } from "goldenmatch";           // edge-safe: browsers, Vercel Edge, Workers, Deno
const result = dedupe(rows, { fuzzy: { name: 0.85 }, blocking: ["zip"], threshold: 0.85 });

パフォーマンス重視に設定されたスイート全体。 golden-suite はすべてのパッケージとネイティブ（Rust）カーネルを取り込み、バージョンを固定して、パフォーマンス最適化済みの設定をデフォルトで使用します。ネイティブのホイールは意図的に必須の依存関係です。ホイールのないプラットフォームでは、遅い純 Python の処理経路に黙って切り替わるのではなく、明示的にエラーになります。

pip install golden-suite
golden-suite doctor        # verify every package + native kernel is importable and healthy
golden-suite optimize      # repair / re-enable the perf-optimized config

pip install golden-suite[mcp]     # + aggregator MCP server (every tool, one endpoint)
pip install golden-suite[all]     # everything

GoldenMatch のみ。 必要なものだけを利用できる、充実したオプション追加機能を用意しています（一般的なプラットフォームではネイティブアクセラレーションがデフォルトで有効です）。

pip install goldenmatch                    # core (CSV in, CSV out) + native
pip install goldenmatch[documents]         # + PDF/image ingest (resolve unstructured input)
pip install goldenmatch[embeddings]        # + sentence-transformers, FAISS
pip install goldenmatch[llm]               # + Claude / OpenAI for LLM boost
pip install goldenmatch[ray]               # + Ray distributed backend (50M+ rows)
pip install goldenmatch[postgres]          # + Postgres sync  (also: [snowflake] [bigquery] [databricks] [salesforce])
pip install goldenmatch[mcp]               # + MCP server     (also: [agent] A2A, [web] browser workbench)

Web ワークベンチ。 pip install 'goldenmatch[web]' を実行してから goldenmatch serve-ui my-project を実行すると（http://localhost:5050 が開きます）、ライブ検証付きでルールを編集したり、サンプルデータに対してプレビューしたり、ペアにラベルを付けたり（Learning Memory にも反映されます）、実行結果を比較したりできます。

詳細： examples/。Python（クイックスタート、パイプライン全体、顧客 360、PPRL、MCP クライアント）· TypeScript（クイックスタート、Vercel Edge、MCP クライアント）· Airflow を網羅しています。

---

デプロイ

リモート MCP。 ホストされたエンドポイントにはベアラートークンが必要です。サーバー上のファイルを読み書きするツールを公開するため、オープンではありません。トークンはメンテナーに問い合わせるか、自分でホストしてください。goldenmatch mcp-serve --transport http で同じサーバーを起動できます。

{ "mcpServers": { "goldenmatch": {
    "url": "https://goldenmatch-mcp-production.up.railway.app/mcp/",
    "headers": { "Authorization": "Bearer YOUR_TOKEN" }
} } }

ループバックでのセルフホストにはトークンは不要です。パブリックインターフェースへのバインドは、GOLDENMATCH_MCP_TOKEN が設定されていない場合、オープンな状態で配信するのではなく拒否されます。

コンテナー。 各パッケージは GHCR 上でマルチアーキテクチャイメージ（linux/amd64 + arm64）として提供され、匿名でプルできます。

docker run -p 8300:8300 ghcr.io/benseverndev-oss/goldensuite-mcp:latest   # one container, every tool
docker run -p 8200:8200 ghcr.io/benseverndev-oss/goldenmatch-mcp:latest   # per-package (also goldencheck/goldenflow/goldenpipe/infermap)
docker run -e POSTGRES_PASSWORD=secret ghcr.io/benseverndev-oss/goldenmatch-extensions:latest   # Postgres + extension

Airflow。 examples/airflow/ に、すぐに導入できる DAG が 13 個あります（TaskFlow API、Airflow 2.7+ / 3.x 対応、冪等、マーカーで保護）。ライフサイクル段階ごとにグループ化されています。

グループ	DAG
コアパイプライン	daily_dedupe、incremental_match、warehouse_native（Snowflake）、customer_360、identity_graph
プライバシー	pprl_linkage（2 者間 PPRL）
オンボーディングと監視	schema_align_and_load、schema_drift_alarm、quality_gate
フィードバックループ	review_worker、active_learning
運用化	reverse_etl（Salesforce/HubSpot）、backfill

---

リポジトリの構成

goldenmatch/
├── packages/
│   ├── python/        goldenmatch · goldencheck · goldenflow · goldenpipe · infermap · goldenanalysis
│   │                  goldensuite-mcp (aggregator) · golden-suite (meta) · goldengraph · goldenmatch-kg
│   ├── typescript/    full TS ports (edge-safe cores + WASM) · goldencheck-types
│   ├── rust/extensions/  Postgres pgrx + DuckDB UDFs + native kernels + owned libraries (own Cargo workspace)
│   ├── dbt/goldensuite/  dbt materializations, tests, macros
│   └── actions/goldencheck/  GitHub Action
├── examples/          python · typescript · airflow (drop-in DAGs)
├── context-network/   architecture decisions + design docs (ADRs, the two-engine frame, Customer 360)
├── docs/superpowers/  design specs and implementation plans
└── justfile · pyproject.toml (uv workspace) · pnpm-workspace.yaml (Turborepo) · .github/workflows/ci.yml

• Cargo：ルートワークスペースはありません。 packages/rust/extensions/ 自体が Cargo ワークスペースです（postgres クレートは pgrx のため除外）。Cargo コマンドはそのディレクトリ内から実行します。
• TypeScript：pnpm ワークスペースは 1 つです。 packages/typescript/* は単一の pnpm + Turborepo ワークスペースを構成しています。

just install   # uv sync + per-package npm install + cargo fetch
just test      # all languages   ·   just lint   ·   just build

コントリビューション

• 機能開発は feature/<name> ブランチで行い、スカッシュ PR でマージします。タイトルは feat: ／ fix: ／ docs: とします。
• 変更が適用されるすべての言語でテストに合格する必要があります。packages/typescript/goldenmatch/tests/parity/ のパリティハーネスにより、Python と TypeScript のスコアラーの小数点以下 4 桁までのパリティが検証されます。
• アーキテクチャの変更は、同じ PR 内で one-product-two-engines frame に準拠するか、改訂してください。設計の根拠は context-network/decisions/ と docs/superpowers/specs/ にあります。

corepack enable                               # one-time, picks up [email protected]
pnpm install
pnpm turbo run build test typecheck           # full pipeline (cached after first run)

Windows： pnpm install でシンボリックリンクを作成できるよう、開発者モードを有効にしてください。corepack enable に管理者権限が必要な場合は、npm i -g [email protected] でも同じことができます。

---

_{このリポジトリは 2026-05-01 に、兄弟リポジトリ 8 件を git filter-repo で goldenmatch に統合して作成されました（全履歴を保持）。Ben Severn が構築しました。MIT ライセンスです。詳しくは LICENSE をご覧ください。}