DataSentry

DataSentry

在用户发现问题之前，先找出糟糕的数据。
自动发现数据质量问题，提供有证据支撑的说明，并安全、可逆地修复。
本地优先。默认确定性。AI 可选。

在线演示 · 30 秒快速开始 · 使用场景 · 常见问题 · PyPI · 示例 · MCP 设置 · 参与贡献

中文导读：DataSentry 会先自动发现数据质量问题，再给出样本、比例、置信度等证据。修复采用 propose → preview → apply to a copy → verify → rollback 的保守流程。检测与评分不依赖 LLM，AI 只作为可选辅助，数据可以完全留在本机。

30 秒快速开始

安装当前 PyPI 版本并运行零配置产品导览：

pip install --upgrade datasentry-ai
datasentry demo

也可以直接使用控制台别名 datasentry-demo。

此演示会生成合成脏数据，运行内置检测器，导出 JSON 和 HTML 报告，将一项安全修复应用到副本，重新扫描修复后的副本，并打印回滚命令。无需数据集、云服务、API 密钥或 LLM。

synthetic dirty CSV
        ↓
39 deterministic detectors
        ↓
evidence-backed issues + quality score
        ↓
preview → repaired copy
        ↓
re-scan → verify new/persistent issues

想立即扫描自己的数据？

curl -L https://raw.githubusercontent.com/Jackxiaozhiren/datasentry/main/demo-data/orders.csv -o orders.csv
datasentry scan orders.csv
datasentry issues list --severity high

或者启动交互式界面：

datasentry          # terminal UI
datasentry-server   # Web UI + REST API at http://localhost:8000/ui/

从你的问题开始

如果你需要……	从这里开始
在还不清楚所有规则时，找出可疑数据	datasentry scan data.csv
查看完整的发现 → 修复 → 验证流程	datasentry demo
在 CI 中拦截严重数据问题	docs/GITHUB_ACTIONS.md
为 dbt / Airflow 添加质量门禁	examples/integrations/
检查并修复问题，而不覆盖源数据	安全修复
为 AI Agent 提供确定性的数据质量工具	docs/MCP.md

默认流程刻意降低了尝试门槛：先扫描，再检查证据，然后决定是否要将发现的问题固化为永久规则或进行修复。

DataSentry 的由来

大多数数据质量工具在你已经知道要执行哪些预期、检查或契约时都很出色。但实际事故往往始于更早的一步：你还不知道问题出在哪里。

DataSentry 围绕完整的修复闭环构建：

Find → Explain → Fix safely → Verify

• 发现 — 无需事先编写每条规则，即可找出常见的数据质量问题。
• 说明 — 附上样本、受影响数量/比例、检测器证据和置信度。
• 安全修复 — 预览变更并将修复应用到副本，而不是直接修改源数据。
• 验证 — 重新扫描修复后的副本，并显示持续存在或新引入的问题。

如果你正在查看尚不完全信任的数据、希望在将检查固化为规则前先获取证据，或需要保守的修复途径，DataSentry 尤其适用。它可以与基于预期和契约的工具互补，无需取而代之。

自动捕获的问题

DataSentry 内置 39 个确定性检测器，可覆盖常见故障模式，例如：

• 缺失值和占位值；
• 无效的电子邮件地址、URL、日期和编码；
• 标识符重复和唯一性违规；
• 类别不一致和跨字段矛盾；
• 外键和引用完整性问题；
• 数值和统计异常值；
• 架构、行数、评分和问题分布漂移。

每次扫描都会生成一份有证据支持的问题列表，并针对完整性、有效性、唯一性、一致性、完整性和及时性六个维度给出质量评分。

安全修复，而非盲目修改

# inspect the highest-severity findings
datasentry issues list --severity high

# propose a repair without changing data
datasentry repair propose <issue_id> --file orders.csv

# preview the exact effect
datasentry repair preview <issue_id> --file orders.csv

# apply to a repaired copy; the original is not overwritten
datasentry repair apply <issue_id> --file orders.csv

# re-scan the repaired copy and detect regressions
datasentry repair verify <run_id>

# inspect or undo the repair
datasentry repair diff <run_id>
datasentry repair rollback <run_id>

修复操作会进行指纹标记、可审计且可撤销。AI 生成的修复提案仍需经人工批准，才能作为状态变更执行。

CI 质量门禁

datasentry scan orders.csv --fail-on high

对于 GitHub 代码仓库，可直接使用 DataSentry 维护的 workflow_call 门禁，无需重复配置安装和退出码处理：

jobs:
  datasentry:
    uses: Jackxiaozhiren/datasentry/.github/workflows/datasentry-quality-gate.yml@main
    with:
      path: data/orders.csv
      fail_on: high

有关输入项、构件、安全边界和版本固定指南，请参阅 docs/GITHUB_ACTIONS.md。

报告可导出为 JSON、Markdown、HTML、JUnit 和 SARIF 格式。版本化、机器可读的 JSON 报告 Schema 可供下游验证使用。GitHub Actions 示例会在发现严重问题时使工作流失败，同时仍会上传 HTML 报告供审查。

为 AI Agent 提供确定性数据质量工具

DataSentry 内置 MCP stdio 服务：

datasentry mcp --project /path/to/project

支持 MCP 的客户端可以扫描文件、检查有证据支持的问题、读取质量评分和趋势、比较漂移、验证契约、管理计划任务，并调用 DataSentry 工具，而无需绕过 CLI 和 REST API 使用的同一套底层安全规则。

docs/MCP.md 中提供了适用于 VS Code 和 Claude Desktop 的复制粘贴式配置指南。

**边界：**AI 可以提出建议；涉及状态变更的修复须经人工批准。

与热门数据质量项目的定位对比

这是一份定位指南，而非评判优劣的功能评分表。这些项目解决的工作有所重叠，但各有侧重；有关当前功能，请查阅各项目的上游文档。

项目	核心思路	适合以下需求……
DataSentry	发现 → 解释 → 修复 → 验证	自动发现问题，并提供受控、可撤销的修复闭环
Great Expectations	预期 / 表达力丰富的数据测试	明确的验证规则、验证结果和自动生成的数据质量文档
Soda Core	数据契约和质量检查	基于 YAML 的契约，以及跨广泛数据技术栈的验证
Deequ	Spark 上的“数据单元测试”	以 Spark 为核心的环境中的大规模数据验证
ydata-profiling	一行代码完成分析 / EDA	快速探索性分析和可分享的分析报告

DataSentry 并不打算取代元数据目录、数据血缘平台或所有验证器。它的关注范围更窄：发现有问题的数据，说明标记原因，并在不拿源数据冒险的前提下完成修复闭环。

本地优先的设计

• 确定性检测和评分均在本地运行；
• 核心本地执行由 DuckDB 提供支持；
• OpenAI/Ollama 助手功能为可选项；
• 启用 AI 时，可使用 PII 遮蔽、加密映射和 LLM 审计记录；
• 修复工作流不会覆盖原始源文件。

数据源

• CSV、Parquet、JSONL、XLSX
• DuckDB 和 SQLite
• PostgreSQL 和 MySQL
• s3://、gs:// 和 az:// 对象
• 单个文件、批次和 glob 模式

历史记录与漂移

持久化保存扫描结果，并比较数据随时间的变化：

datasentry drift latest orders
datasentry score

跟踪的信号包括架构变更、行数变化、质量评分变化和问题分布漂移。

架构

flowchart LR
    Sources[Files / DBs / cloud objects] --> DuckDB[Local execution]
    DuckDB --> Detect[39 detectors]
    Detect --> Evidence[Evidence fusion]
    Evidence --> Score[6-dimension score]
    Score --> Reports[Reports / history / gates]
    Reports --> CLI[CLI / TUI]
    Reports --> Web[Web / REST]
    Reports --> MCP[MCP]
    Evidence --> Proposal[Repair proposal]
    Proposal --> Preview[Preview]
    Preview --> Apply[Apply to copy]
    Apply --> Verify[Verify by re-scan]
    Verify --> Rollback[Rollback artifact]
    LLM[Optional OpenAI / Ollama] -. proposes .-> Proposal

可复现基准测试

uv sync
uv run python benchmarks/bench_scan.py 1000000 42

该基准测试会生成合成脏数据，并衡量数据分析、检测／融合／评分、数值异常检测、JSONL 读取、采样、分数漂移和内存峰值。请参阅 docs/BENCHMARKS.md。

开发

uv sync
make check          # lint + mypy --strict + tests/coverage
make demo           # exercise the public datasentry demo path
make bench          # benchmark
make build          # distributions

贡献

欢迎提交新检测器、连接器、集成示例、可复现的基准测试用例、文档／翻译、最小化的 Bug 复现，以及 CLI／TUI／Web 易用性改进等贡献。

想从小处着手吗？可以从 good first issue #14 或 good first issue #15 开始。

请参阅 CONTRIBUTING.md、CODE_OF_CONDUCT.md、SECURITY.md 和 ROADMAP.md。小型贡献会通过 good first issue 和 help wanted 标签进行跟踪。

文档

• 项目网站和实时报告
• docs/FAQ.md — 评估、安全边界，以及 DataSentry 如何与其他数据质量工具配合使用
• examples/ — 以场景为先的可运行示例
• docs/MCP.md — VS Code 和 Claude Desktop 的 MCP 配置
• docs/GITHUB_ACTIONS.md — 可复用的 GitHub 质量门禁
• examples/integrations/github-actions/ — 可直接复制粘贴的 CI 门禁
• docs/BENCHMARKS.md — 基准测试策略
• docs/DEVELOPMENT.md — 工程说明
• 检测 → 修复 → 验证 / 中文版

许可证

Apache-2.0 — 请参阅 LICENSE。

---

如果 DataSentry 帮你在生产环境接收数据前发现了有问题的数据，不妨给仓库点个 ⭐。
这有助于其他数据工程师发现这个项目。