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 footer 统计信息完整，则按列获取样本后停止读取；如果没有统计信息，则会对整个批次计数。请参阅 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 bundle。独立的 truthound-core 插件候选版本固定使用 Core 3.3.0，并要求明确配置数据、工作区、授权存储库和敏感结果权限；配置变更后需重新连接。

项目介绍（Introduction）

Truthound 是一个提供基于 Polars 的开源数据验证框架和工作流编排的项目。它支持数据架构验证、自定义规则、质量检查和异常数据检测等多种验证功能，并可与 Airflow、Dagster、Prefect 等主要工作流环境集成，以自动执行验证流程。通过以代码为中心的声明式验证方式，它能提升数据质量管理的可复现性和可维护性，并且旨在便于应用于各种数据管道。

Truthound 由两个存储库组成，构成一个开源生态系统。

组成部分	存储库	作用
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)，即可自动创建并复用本地 .truthound/ 工作区。
• 确定性自动验证套件：根据架构、是否允许空值、类型、范围和键启发式规则，仅选择必要的检查（而非“全部运行”）。
• 统一结果模型：单个 ValidationRunResult 由检查点、报告器、验证文档和插件共享。
• 显式契约（Contract）：为上下文、检查工厂、后端和工件生成提供稳定的接口。
• 工作流集成：通过 Truthound Orchestration，在调度器/工作流环境中以主机原生方式运行。

AI 审查功能作为可选辅助层提供。Truthound 的核心是数据质量工作流；AI 仅通过基于提示词的验证建议、执行分析等方式辅助，并由人工审查。所有核心功能在没有 AI 的情况下也能运行。

---

基准测试（Benchmark）

下表展示了此前公开的固定运行器发布工件集中的历史测量结果。当时，在相同条件下的 8 个工作负载中，保持准确性的同时，测得的运行时间比 Great Expectations 更短、内存使用量更低；这并不代表后续版本或变更后的测量方法也通过了性能测试。

工作负载	Truthound 预热（s）	GX 预热（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。该方法为两个框架应用相同的 worker thread budget 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 排版：较长的表格和章节会分页；可放在同一页的卡片会排在一起。较长的列名和 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를 참고하세요.