skavuri143/mapverity

项目介绍

MapVerity 针对 ETL 与数据平台里一种常见而隐蔽的故障：输出类型正确、非空、取值看似合法，内容却是错的。它不靠剖析目标数据，而是读取分析师本来就在维护的源到目标映射表，把每个映射字段编译成可执行检查：从源记录重新推导期望值，再与管道实际写入的结果比对。支持的规则包括 direct、trim、upper、lower、lookup:、date:、concat:、constant:、count、ref: 与 expr:，完整字段说明见映射表参考。

除逐字段比对外，它还覆盖作业筛选条件下的记录完整性、按复合键匹配的嵌套数组、数组基数、外键、必填字段与取值域。数据源支持 COBOL copybook（EBCDIC、COMP-3、二进制、zoned decimal、OCCURS、REDEFINES）、带控制总计的多记录定宽布局、CSV/JSON/Parquet、S3、DocumentDB/MongoDB、任意 SQLAlchemy 数据库以及分页 REST API。目标用户是运行医疗保险、政府或金融数据管道的团队，尤其是链路中含大型机抽取和长转换链的场景。

测试套件本身也能打分：变异测试向输出注入 15 类真实 ETL 故障，报告哪些被检查捕获、哪些是盲区。可选的 AI 部分包括基于公开 NASA MDP 数据训练、带 SHAP 解释的缺陷风险模型，以及按「单位成本下最可能失败」排序的 ERAD-QA。质量门禁根据证据给出 PASS/WARN/BLOCK/INCOMPLETE，预测风险默认只作参考。

快速使用

README 提供的 15 分钟示例无需云账号。安装全部可选依赖，克隆仓库并进入会员资格示例，生成合成源数据并运行被测管道：

pip install "mapverity[all]"
git clone https://github.com/skavuri143/mapverity && cd mapverity/examples/member_eligibility
python generate_data.py
python transform.py
mapverity from-mapping mapping/member_data_model_mapping.csv --datasets datasets.yaml -o member.mapverity.yaml
mapverity validate member.mapverity.yaml --html report.html

预期输出为 49 passed · 0 failed · 0 errors，并生成 HTML 报告。要观察失败，可让管道带一个故意缺陷重跑，再校验一次：

python transform.py --defect D07_comp3_scale_lost
mapverity validate member.mapverity.yaml

此时 monthlyIncome 的映射检查应失败并给出不匹配行数。第二个示例 insurance_claims 演示带嵌套理赔行的多记录定宽文件校验。

测量与门禁

恢复干净运行后，可用变异测试给套件打分，并把结果交给门禁策略一起校验：

python transform.py
mapverity mutate member.mapverity.yaml --dataset members --json mutation.json
mapverity validate member.mapverity.yaml --mapping mapping/member_data_model_mapping.csv \
    --mutation-report mutation.json --gates gates.yaml --html report.html --junit results.xml

README 中该流程的结果为 PASS。风险排序是单独的选用流程：训练模型、给转换函数打分、对比映射差异并规划优先执行顺序。排序不会删减检查——阻断级检查始终执行，因时间预算被截断的运行会报告 INCOMPLETE 而不是 PASS。

使用约束

• Python 包核心依赖 pandas、numpy、pyyaml 与 typer；S3/MongoDB、SQL、REST 和 AI 功能各自需要对应的 extra，只装核心包用不了这些能力。
• 项目处于 alpha 阶段，1.0 之前规格格式可能变化。
• 风险分数只作参考，依赖前应阅读模型卡的局限说明；项目自己的研究也发现风险信号没有改善排序效果。
• 所有示例与测试均使用合成或公开数据，真实会员、患者或投保人记录不应附到 issue 中。
• 许可证为 Apache-2.0。

证据与范围

README 报告的结果由 experiments/ 中的脚本复现：映射驱动检查捕获 20 个真实 Glue 作业缺陷中的 20 个，而数据模型约束为 5/20、剖析推断为 15/20；两个示例的变异体击杀率分别为 99.0% 与 100%；20 次独立干净运行零误报；在 2 vCPU 上以 49 项检查校验 10 万份会员文档（163,107 个嵌套段）耗时 8.7 秒。这些是维护者自行报告的测量，实验目录中附有置信区间、消融与负面发现。

HotRepo 点评

该项目出现在 HotRepo 2026-11-04 的 Python 新项目榜中，约一小时内新增 4 个 Star 和 4 个 Fork，总数达到 105 Star、106 Fork。观察窗口非常短，也没有记录到全语言日榜名次，这条快照只能说明项目在早期被关注，不足以判断趋势。更值得注意的是 Star 与 Fork 数几乎持平，而仓库本身的投入并不轻：已发布的包、copybook 与定宽格式读取器、变异引擎、CI 模板，以及带负面发现的实验目录。评价这个项目时，参考示例管道与模型卡比看早期增长数字更有意义。