Truthound

Truthound — データ品質ワークフロー

Polars ベースのゼロ設定データ品質フレームワーク
Polars を活用したゼロ設定データ品質フレームワーク

不良データを検出します。

---

プラグインプラットフォーム（Plugin Platform）

MCP で使用する

Codex と Claude Desktop で Truthound Local を接続すると、承認したローカルデータの欠損値・重複を検査し、カラムの要約と PII サンプル検出を実行できます。

• Codex のインストールガイド — 前提条件、リポジトリマーケットプレイスの追加、プラグインのインストールと許可フォルダーの設定
• Claude Desktop のインストールガイド — MCPB のダウンロード、拡張機能のインストールと許可フォルダーの設定

インストール後、使用するデータフォルダーを別途承認する必要があります。他の MCP クライアントの設定については、Registry・クライアント接続ガイドを参照してください。

基本的な検証・プロファイリング・PII 検出に加え、Core プロファイルではドリフト比較・マスキング・スキーマ検証を使用できます。主な使用フローとプロファイルの選択を参照してください。

---

概要（Overview）

Truthound は、データ検証（Data Validation）とデータワークフロー（Data Workflow）のためのオープンソースフレームワークです。Polars ベースの検証カーネルを中心に、スキーマ検証・カスタムルール・品質チェック・異常データ検出をコードで宣言し、その結果を再現可能な形で管理します。

Truthound は、Polars を中心とする検証カーネルを基盤とした、データ検証とデータ品質ワークフローのためのオープンソースフレームワークです。

th.scan()は、文字列カラムごとに最初の 1,000 件の非欠損値を検査する PII サンプル検出です。フレーム全体を読み込まず、集計と制限付きサンプルを使用するため、検出件数は推定値です。完全な Parquet フッター統計がある場合は、カラムごとにサンプルを確保した後、読み取りを終了します。統計がない場合は、バッチ全体をカウントします。PII APIを参照してください。

英語版 README: 英語版 README
ドキュメント（Documentation）: truthound.netlify.app

---

式の検証では、合格したチェックを省略しても、失敗サンプル・頻度・行を該当するカラムに関連付けます。

3.3.0 の ai・mcp・all extra では、Pydantic 2.11 以上が必要です。 truthound-mcp bundle --profile core --output truthound-core.mcpbで Core バンドルを作成します。別の truthound-core プラグイン候補では Core 3.3.0 に固定し、データ・ワークスペース・承認済みストレージ・機密結果の権限を明示的に設定して、変更後に再接続します。

プロジェクト紹介（Introduction）

Truthound は、Polars ベースのオープンソースデータ検証フレームワークとワークフローオーケストレーションを提供するプロジェクトです。データスキーマ検証、カスタムルール、品質チェック、異常データ検出など、さまざまな検証機能をサポートしており、Airflow、Dagster、Prefect などの主要なワークフロー環境と連携して検証手順を自動化できます。コード中心の宣言的な検証方式により、データ品質管理の再現性と保守性を高め、さまざまなデータパイプラインで簡単に活用できるよう設計されています。

Truthound は、2 つのリポジトリで構成される 1 つのオープンソースエコシステムです。

コンポーネント	リポジトリ	役割
Truthound	truthound	検証カーネル — th.check()、ValidationRunResult、プランナー／ランタイム、ゼロ設定ワークスペース、レポーター、チェックポイント
Truthound Orchestration	truthound-orchestration	Airflow、Dagster、Prefect、dbt、Mage、Kestra などのワークフロー環境との連携レイヤー

---

主な特徴（Key Features）

• Polars 優先の実行：ローカル検証では、基準経路として Polars LazyFrame を使用します。バッチ式や共有メトリクスユーティリティも提供しますが、デフォルトの th.check() 経路ですべてのバリデーターのメトリクスが自動的に単一の集計に統合されるわけではありません。
• ゼロ設定（Zero-Configuration）：th.check(data) と 1 行呼び出すだけで、ローカル .truthound/ ワークスペースを自動的に作成・再利用します。
• 決定論的な自動検証スイート：スキーマ・NULL 許容・型・範囲・キーのヒューリスティックに基づいて、必要なチェックだけを選択します（「すべて実行」ではありません）。
• 単一の結果モデル：1 つの ValidationRunResult をチェックポイント、レポーター、検証ドキュメント、プラグインで共有します。
• 明示的な契約（Contract）：コンテキスト、チェックファクトリー、バックエンド、アーティファクト生成のための安定したインターフェースを提供します。
• ワークフローとの連携：Truthound Orchestration により、スケジューラー／ワークフロー環境でホストネイティブに実行されます。

AI レビュー機能は、任意の補助レイヤーとして提供されます。Truthound の中核はデータ品質ワークフローであり、AI はプロンプトベースの検証提案や実行分析などを、人間によるレビューを前提として支援するだけです。AI がなくても、すべての中核機能が動作します。

---

ベンチマーク（Benchmark）

以下の表は、以前公開された固定ランナーのリリースアーティファクトセットにおける過去の測定結果です。当時、同一条件の 8 つのワークロードで正確性を維持しながら、Great Expectations と比較して実行時間の短縮とメモリ使用量の削減を測定しました。これは、以降のバージョンや変更後の測定方法での性能基準達成を意味するものではありません。

ワークロード	Truthound Warm (s)	GX Warm (s)	速度向上	メモリ比
local-mixed-core-suite	0.028240	0.075232	2.66x	44.29%
local-null	0.016487	0.024964	1.51x	43.62%
local-range	0.002470	0.013219	5.35x	43.84%
local-schema	0.001479	0.017303	11.70x	35.88%
local-unique	0.002023	0.013785	6.81x	42.28%
sqlite-null	0.007370	0.032909	4.47x	48.16%
sqlite-range	0.006053	0.022355	3.69x	43.80%
sqlite-unique	0.002066	0.015655	7.58x	42.12%

この比較は、決定論的な中核チェックと SQLite プッシュダウンのワークロードに範囲を限定した結果であり、すべての機能領域に一般化できる主張ではありません。リポジトリ内の .truthound/benchmarks/artifacts には一部の生の観測値しか残っていない場合があるため、公式数値はリリースアーティファクトセットと Latest Verified Benchmark Summary に基づいて解釈してください。

新しいベンチマークのデフォルト測定方法は truthound-parity-thread-budget-v2 です。両フレームワークに同一のワーカースレッド予算 1 を適用し、コールド 1 回とウォーム 7 回の正確性、およびすべてのウォーム測定値を保持します。既存の結果は上書きせず、方法論・ワークロード契約・データ・バックエンド・正確性が異なる結果を直接比較しません。公開 wheel を変更済みの測定ツールで再検証する場合も、wheel のバージョン・digest とツールの revision を個別に記録します。公式リリース検証には、デフォルトの方法論全体と変更されていない閾値が必要です。カスタム方法論は参考用です。新しい方式での性能基準達成は、実際の検証アーティファクトがある場合にのみ認められます。詳細な基準については、Benchmark Methodology を参照してください。

性能差の主な要因：

• Polars LazyFrame ベースのローカル実行と SQL プッシュダウン経路
• 一部のバリデーターと高度なユーティリティで提供される、バッチ式や共有メトリクスの最適化
• デフォルトの作業を正確かつ関連性の高いものに保つ、決定論的な自動スイート選択
• 重いプロジェクトのブートストラップなしにベースラインとアーティファクトを維持する、軽量なゼロ設定コンテキスト
• レポーター・チェックポイント・検証ドキュメントで共有する、単一の結果契約

---

クイックスタート（Quick Start）

インストール（Installation）

pip install truthound

# 선택적 AI 검토 기능
pip install truthound[ai]

# 이 저장소에서의 개발/문서 작업
uv sync --extra dev --extra docs

Python API

import truthound as th
from truthound.datadocs import generate_validation_report
from truthound.reporters import get_reporter
from truthound.drift import compare

run = th.check(
    {"customer_id": [1, 2, 2], "email": ["[email protected]", None, "[email protected]"]},
)

print(run.execution_mode)
print([check.name for check in run.checks])
print(run.metadata["context_root"])

json_report = get_reporter("json").render(run)
validation_docs = generate_validation_report(run, title="Customer Quality Overview", locale="ko")

context = th.get_context()
schema = th.learn({"id": [1, 2], "status": ["active", "inactive"]})
masked = th.mask(
    {"email": ["[email protected]", "[email protected]"]},
    columns=["email"],
    strategy="hash",
)
drift = compare({"score": [0.1, 0.2]}, {"score": [0.1, 0.8]})

• レポート：A4 サイズの HTML/PDF を生成します。公開テーマは light・dark・minimal です。番号付きの表・図・付録、品質ディメンション・診断基準・閾値を提供します。
• PDF のページ割り付け：長い表やセクションはページごとに分割し、1 ページに収まるカードはまとめて配置します。長い列名や JSON の例は省略せずに改行します。
• データ型・統計：データ型は inferred_type → physical_type → dtype の順に表示し、存在しない場合は unknown とします。未定義の歪度・尖度は JSON null で表現し、元の値とは異なる統計もそのまま保持します。
• 高度な連携：ReportDocument で構造を検査し、generate_html_report、HTMLReportBuilder、export_to_pdf との互換性を維持します。

CLI

truthound check data.csv --validators null,unique
truthound check --connection "sqlite:///warehouse.db" --table users --pushdown
truthound scan pii.csv
truthound profile data.csv
truthound doctor . --workspace
truthound plugins list --json

# 선택적 AI 검토 워크플로우
truthound ai suggest-suite data.csv --prompt "Require customer_id to be unique"
truthound ai proposals list
truthound ai explain-run --run-id <run_id>

---

ゼロ設定ワークフロー（Zero-Config Workflow）

Truthound はプロジェクトルートに .truthound/ ワークスペースを自動的に作成します。デフォルトでは、次を管理します。

• .truthound/config.yaml：解決済みのプロジェクトデフォルト
• .truthound/catalog/：アセットのフィンガープリントとソースシグネチャ
• .truthound/baselines/：学習済みスキーマとメトリクスの履歴
• .truthound/runs/：保存済みの ValidationRunResult メタデータ
• .truthound/docs/：生成された検証ドキュメント
• .truthound/plugins/：解決済みのプラグインマニフェストと信頼メタデータ

th.check(data) を呼び出すだけで、Truthound は次の順に動作します。

1. アセット／バックエンドの検出
2. 有効な TruthoundContext の解決
3. ベースラインの読み込みまたは作成
4. 自動検証スイートの合成
5. 検証計画の策定と実行
6. （有効な場合）実行結果と検証ドキュメントの保存

truthound doctor . --workspace を実行すると、ローカル .truthound/ の構成と、インデックス、ベースライン、保存済み実行アーティファクトの構造的整合性を確認できます。

---

공개 API (Public Surface)

Lineage sample 메타데이터는 명시적 활성화 시에만 행·바이트 제한 안에서 복사하며 원본 자산을 자동으로 샘플링하지 않습니다.

고급 Arrow 변환에 보관된 인덱스·null·시간 정책과 행·바이트 제한을 적용합니다. materialization 한계는 분산 프로파일링 가이드에 설명되어 있습니다.

파일 저장소의 suite 쿼리는 선택한 정렬 뒤 페이지를 나누며, 모호한 JSON 기록은 인덱스 재구축에서도 거부합니다.

루트 패키지는 의도적으로 작은 API만 노출합니다. 공개 함수와 타입은 첫 접근 시 로드하며 기존 Core 객체와 동작을 유지합니다.

• 안정 파사드: check, scan, mask, profile, learn, read, get_context
• 핵심 타입: TruthoundContext, ValidationSuite, CheckSpec, SchemaSpec, ValidationRunResult, CheckResult
• th.check()는 ValidationRunResult를 직접 반환합니다.
  • 3.1.14부터 issue 상세가 없어도 명시적으로 실패한 check를 실패로 보존합니다. 설치된 버전을 확인해야 합니다.
• 체크포인트 결과: CheckpointResult.validation_run이 정식이며, CheckpointResult.validation_view는 레거시 호환 프로젝션입니다.
• 리포터 타입: truthound.reporters.RunPresentation, truthound.reporters.ReporterContext
• 검증 문서 진입점: truthound.datadocs.ValidationDocsBuilder, truthound.datadocs.generate_validation_report
  • 3.1.13부터 locale="en"(기본값) 또는 locale="ko"는 본문 제목·표 머리글·알림을 번역합니다. 품질 수치·상태 코드·사용자 데이터는 바꾸지 않으며 미지원 locale은 ValueError입니다. 이전 버전에는 이 옵션이 없습니다.
• 드리프트 비교: truthound.drift.compare; 명시한 0 임계값을 유지하며 잘못된 설정과 유한하지 않은 숫자 입력은 오류로 보고합니다.
• ERD 감사(개발 중): truthound.schema_audit의 불변 모델·JSON·digest, 표준→설계 감사 A, 설계→카탈로그 감사 B와 제한된 PG14/17 읽기 전용 수집기. Console·접속 인가·승인 권한은 별도입니다.
• 고급 시스템: 네임스페이스로 임포트 (예: truthound.ml, truthound.lineage, truthound.realtime, truthound.datadocs) 네이티브 모델 생성자는 설정을 복사하고 알 수 없는 override를 거부합니다. 학습 표본에 시드를 적용하고 내장 탐지기의 재학습 실패 시 기존 모델을 보존합니다. 개념 드리프트는 상관관계 기본값과 실제 River DDM·ADWIN·Page-Hinkley 스트림 비교를 제공합니다(계약). 계보 추적은 명시적 행 위치·컨텍스트 연결·재개 가능한 자동 저장·명시적으로 제공한 제한된 표본을 지원하며 OpenLineage 전송은 결과 불명 전환을 보존하고 종료 시 소유 요청을 회수합니다(계약).
• 선택적 AI 레이어: truthound[ai] 설치 후 truthound.ai 임포트

---

문서 (Documentation)

• 메인 문서 포털: truthound.netlify.app
• 개요: docs/index.md
• 시작하기: docs/getting-started/index.md
• 아키텍처: docs/concepts/architecture.md
• 제로 설정 컨텍스트: docs/concepts/zero-config.md
• 가이드: docs/guides/index.md
• 레퍼런스: docs/reference/index.md
• AI 문서: docs/ai/index.md
• 오케스트레이션: truthound.netlify.app/orchestration/
• 오케스트레이션 시작하기: docs/orchestration/getting-started.md
• 최신 검증 벤치마크 요약: docs/releases/latest-benchmark-summary.md

---

라이선스 (License)

Apache License 2.0. 자세한 내용은 LICENSE를 참고하세요.