仓库文件导航
claimseed
带种子、完全合成的美国医疗账单样本文件——Medicare Summary Notice、医院逐项账单和 Medicare Advantage 福利说明——渲染为 PDF,并附带 ground-truth JSON,精确说明注入了哪些账单错误以及注入在哪里。用于测试文档提取器、账单审查工具和 agent,而无需接触任何真实个人的文书。
- 每个姓名、标识符、地址、电话号码和金额都由种子生成。本仓库中的任何内容都不是真实文件,也不源自真实文件;参见 docs/synthetic-data-policy.md。
- 每个渲染页面都会声明这一点:底部页边距中的一条样本带(文本)、一个对角线水印(以形状绘制,因此绝不会把字母泄漏到文本提取中)以及 PDF 元数据,均由渲染器本身盖印到最终 PDF 中——没有任何 CLI 标志、库调用或数据对象可以关闭它们。
- 相同种子,相同文档:所有内容都由种子派生,字体已捆绑,PDF 元数据固定,因此同一 Chrome 构建(Linux,如 CI 中)上的两次渲染字节完全一致;其他平台产生相同内容,字节可能因 Chrome 版本而异。
现成的测试集
标准集为覆盖全部 34 个已发布场景的 1,022 份盲文档:260 份 Medicare Summary Notice(13 个场景 x 20 个种子)、250 份逐项账单(5 x 50)、256 份 PPO EOB(8 x 32)和 256 份 HMO EOB(8 x 32)。账单和 EOB 会轮换使用标准版式及其 12 个变体;每五份文档中就有一份是降质副本(依次为扫描、传真、照片、低分辨率);每份 notice 和 EOB 都配有对应的 835。版式、预设和 835 对每个场景都同样轮换,因此任何一项都不会暴露场景。
claimseed 0.6.0 的副本附在 GitHub release v0.6.0 上:claimseed-0.6.0-standard-documents.zip 解压到 claimseed-0.6.0-standard/documents/(PDF、835、README.md、SHA256SUMS),claimseed-0.6.0-standard-keys.zip 解压到 claimseed-0.6.0-standard/keys/(答案键、manifest.jsonl、README.md、SHA256SUMS 和 set.json:claimseed 和 Chrome 版本、该 release 的 git tree、文档数量、salt 和 canary)。只把 documents 文件夹交给被测工具。835 就放在那里的 PDF 旁边;若只想就读取 PDF 这一项给工具打分,则只给它 .pdf 文件:
# run the tool on every PDF in documents/; write one report per document to reports/<id>.json,
# in the shape of schemas/extractor-output.schema.json
npx @claimseed/core verify --manifest claimseed-0.6.0-standard/keys/manifest.jsonl --outputs reports
# the same content again with claimseed 0.6.0 and the salt in set.json (or any of its keys); PDF bytes can
# differ by machine and Chrome install, so the SHA-256s in the manifest and SHA256SUMS name the published files
npx @claimseed/[email protected] batch --set standard --out documents --blind-keys keys --blind-salt SALT
这是一个带有公开密钥的公开开发集;每个答案键和 manifest 行都带有一个含固定 GUID(blind.canary)的 canary 字符串,以便训练模型的人能够找到并排除 claimseed 答案键,而测试模型的人可以检查模型是否见过它们。请将密钥排除在训练数据之外。对于留出测试,请用 batch --blind-keys(一个新的 salt)制作你自己的盲集,并将密钥留给自己。
快速开始
从 npm(Node.js 22.13 或更高版本):
npx @claimseed/core list
npx @claimseed/core render msn combined-three-errors --seed demo --out ./out
npx @claimseed/core generate itemized-bill balance-billing --seed demo > demo.json
渲染需要 Chrome 或 Chromium 二进制文件(CLAIMSEED_CHROME=/path/to/chrome,或安装在常见位置);generate 不需要。请在本仓库检出目录之外的任意文件夹中运行这些命令:在检出目录内,npx 会使用仓库自带的包副本,这需要先运行 npm ci(参见下文“从检出目录运行”)。
文章标题:Show HN: Claimseed,带有植入错误和答案键的合成 Medicare 文档
正文: 作为库使用(npm install @claimseed/core,ESM):
import { generateData, render } from '@claimseed/core';
const { data, groundTruth } = generateData({ type: 'msn', scenario: 'baseline-clean', seed: 'demo' });
const { pdf, groundTruth: gt } = await render({ type: 'msn', scenario: 'baseline-clean', seed: 'demo', outDir: './out' });
作为面向 agent 的 MCP server 使用(@claimseed/mcp,stdio)。渲染后的文档以页面图像的形式返回,聊天客户端会在对话中展示这些图像(直接展示,或在 MCP Apps 视图中展示,并在页面旁边显示注入的错误),不保存任何文件:
npx -y @claimseed/mcp
或者,同时保留每个 PDF 及其 ground truth,并指定一个只在此处写入的文件夹:
npx -y @claimseed/mcp --workspace ./claimseed-out
或者使用已发布的容器镜像,其中包含 Chromium:
docker run -i --rm --network none --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \
--user "$(id -u):$(id -g)" -v "$PWD/claimseed-out:/work" ghcr.io/claimseed/claimseed-mcp
该服务器也以 io.github.claimseed/claimseed 的名义列在 MCP registry 中。工具、客户端配置和限制见 packages/mcp/README.md。
从本仓库的检出开始:
npm ci
cd packages/core
node src/cli.js list
node src/cli.js render msn combined-three-errors --seed demo --out ./out
在仓库根目录执行 docker build -t claimseed-mcp . 可构建出与已发布镜像相同的镜像。
引擎见 packages/core/README.md,场景可注入的错误类型见 docs/error-taxonomy.md,ground-truth 格式见 schemas/ground-truth.schema.json。
为抽取器评分
渲染一组文档,对 PDF 运行你的抽取器或账单审计器,并用答案键为其报告评分:
npx @claimseed/core batch --types msn,itemized-bill --seeds 20 --out ./set
# write one report per document to ./reports/<pdf name>.json, in the shape of schemas/extractor-output.schema.json
npx @claimseed/core verify --manifest ./set/manifest.jsonl --outputs ./reports
评分给出字段准确率、错误召回率和精确率、误报,以及读错或漏读的路径。干净场景用于测试误报;每种类型的某些场景还会植入诱饵,即看起来像错误但实际符合规则的行(同一服务出现在两个日期、远高于批准金额的收费、会员达到自付上限时被截短的共付额),标记其中任何一项都计为误报。Agent 可以用 MCP 工具 verify_document 一次为一份文档评分。
verify --manifest 的 headline 数字(字段、错误)现在会统计每一份文档:缺失或无效的报告按空报告计分,报告遗漏的某一部分(字段或错误)也同样处理,只要有任何报告给出了该部分。跳过一份文档绝不会提高字段准确率或错误召回率;精确率只统计被标记的内容,因此要结合召回率一起看。scoredOnly 保存了早先的数字,仅覆盖已评分的报告;byType、byDegradation(干净或预设)和 byKind(每种错误类型的预期数、找到数和召回率)对其做了细分。
盲文档
对于不能看到答案的工具,render 和 batch 接受 --blind-keys KEYDIR。盲文档以一个不透明 id(doc- 加 16 个十六进制数字)命名:其标本带、PDF 标题、文件名、页面图像标记和 835 都带有该 id,绝不会包含场景、植入错误或 seed。其答案键(ground truth 1.5)和批次的 manifest 会写入 KEYDIR,绝不会写入文档的文件夹或其内部的文件夹:
npx @claimseed/core batch --types msn,itemized-bill --seeds 20 --out ./set --blind-keys ./keys
文章标题:Show HN: Claimseed,带有植入错误和答案键的合成 Medicare 文档
正文: 内容来自一个由 salt 派生出的 seed,每组抽取 128 个随机比特并记录在每一个 key 中,因此没有人能从猜测的场景和 seed 重建文档并匹配上打印的索赔编号。--blind-salt SALT(来自更早一组文档的 key)会重新生成同一组;文档按从 salt 抽取出的顺序写出。降级副本同样是盲的,其 key 中有自己的 id 和 copyOf。标本带、水印和元数据仍将每一页标记为标本;只是场景词没有了。verify --manifest 对盲组的评分与对开放组完全一样。
通过 MCP,render_blind 返回 id 和页面图像,绝不返回 key、场景或 seed,而 get_answer_key 返回 key(见 packages/mcp/README.md)。
看起来像扫描件的副本
提取器会遇到扫描件、传真和手机照片,而不只是干净的 PDF。降级副本保留文档的答案键:
npx @claimseed/core render msn combined-three-errors --seed demo --out ./out --degrade fax
npx @claimseed/core batch --types msn,itemized-bill --seeds 20 --degrade scan --out ./set
预设为 scan、fax、photo 和 low-res。render --degrade 写出仅含图像的 PDF、每页一张图像以及答案键;batch --degrade 写出一组文档的 PDF 和答案键,以及其 manifest。答案键在 degradationParams 中保存 seed 选定的设置(旋转、分辨率、噪声等)。标本带和水印绘制在降级页面的上层,绝不经过降级处理(传真还会将水印打印成能在黑白下存活的点阵图案),并且每个图像文件都带有标本标记。Agent 可以通过 MCP 工具 degrade_document 请求副本。
汇款文件(835)
Medicare Summary Notice 或 Medicare Advantage EOB 可以附带同一批索赔的 X12 835 汇款文件,用于测试读取付款而非纸质文档的软件:
npx @claimseed/core render msn combined-three-errors --seed demo --out ./out --also 835
npx @claimseed/core batch --types msn,ppo-eob,hmo-eob --seeds 20 --also 835 --out ./set
每个 .835 都是标记为测试数据的 005010X221A1 文件(ISA15 为 T,发送方和接收方 ID、付款方和联系人写明 specimen 或 test),不含银行数据。答案键将其列在 PDF 旁边,每个出现在 835 中的植入错误都在其中标明其位置(x12Ref):错误的索赔总额会破坏该索赔的余额或其患者责任总额,而重复项是重复的服务行。Agent 通过 MCP 工具 render_document 上的 also: "835" 请求它。文件包含什么、省略什么,见 core README。
布局变体
在一种布局上测试过的提取器可能学到的是布局而非文档。因此,itemized bill 和两个 Medicare Advantage EOB 各自都有 12 种布局变体(b01-b12、p01-p12、h01-h12):一个 id 固定列顺序、页眉和标题措辞、字体、密度和颜色,以及表格续到下一页时如何标记。数据、每一笔金额和每一个必需项保持不变,答案键的差异仅在于命名变体、页数和 PDF 的哈希:
npx @claimseed/core render ppo-eob combined-three-errors --seed demo --layout-variant p07 --out ./out
npx @claimseed/core render hmo-eob baseline-clean --seed demo --layout-variant all --out ./out
npx @claimseed/core batch --types itemized-bill,ppo-eob,hmo-eob --seeds 20 --layout-variant seeded --out ./set
文章标题:Show HN: Claimseed,带有植入错误和答案键的合成 Medicare 文档
正文: all(render 和 batch)为每个 id 写入一个文档。seeded 仅根据种子选择一个 id,因此对于一个种子,三种类型在各自列表中占据相同位置(b04、p04 和 h04 一起);给出显式 id 可将布局分散到各类型。文件命名为 <type>_<scenario>_<seed>.<id>.pdf,答案键记录变体(documents[0].layout 为 ppo-eob.p07,详情在 documents[0].layoutVariant 中;ground truth 1.4)。该选项可与 --degrade 和 --also 835 一起使用(835 与标准文档的相同)。Medicare Summary Notice 只有一种全国格式,不接受变体。Agent 将 layout_variant 传递给 MCP 工具;id 及各 id 修复的内容列在 packages/core/data/<type>/variants.json 中。
claimseed 如何比较
- Synthea 模拟合成患者群体,并将其记录(包括理赔)导出为 FHIR、C-CDA 和 CSV。它建模的是诊疗过程,而非打印的账单文档。
- CMS 的 Blue Button 2.0 API 为开发者提供合成 Medicare 参保人数据的沙箱,以 FHIR 资源形式提供。
- claimseed 打印患者或账单审核人实际阅读的文档(Medicare Summary Notices、逐项账单、Medicare Advantage EOB),带有 CPT/HCPCS 代码、来自公开费用表的金额、植入错误和诱饵,以及每份文档的答案键。它不建模临床病史;请与 Synthea 配合使用。
状态
0.6.0 增加了盲文档和集合(--blind-keys 和 --blind-salt,以及 MCP 工具 render_blind 和 get_answer_key)、已发布的 1,022 份盲文档标准集及其答案键(附在 GitHub release v0.6.0 上),以及计入每份文档的集合得分。0.5.0 在 Medicare Advantage EOB 上增加了植入错误和诱饵(14 个新场景)、逐项账单和两个 EOB 的布局变体(--layout-variant,layout_variant:每种类型 12 个 id,变体记录在答案键中),以及严格的 MCP 参数(每个工具拒绝其未声明的参数)。0.4.0 增加了 835 汇款和扫描件样式的副本。0.3.0 增加了评分、带清单的批量输出和诱饵。0.2.0 在 MCP 服务器的结果中增加了页面图像、一个 MCP Apps 视图和一个不写文件的模式。1.0 之前的版本仍可能更改其接口。随附的布局有 msn、itemized-bill、ppo-eob 和 hmo-eob。接下来是同一就诊的账单和 EOB(一份虚构的商业雇主计划 EOB 与提供者的逐项账单并列,错误仅在两者之间显现);docs/roadmap.md 给出了其后的工作顺序。examples/ 列出了每个场景一份渲染文档和每个布局变体 id 一份。依据 Apache-2.0 许可(见 LICENSE 和 NOTICE)。
可接受使用
输出用于测试软件。不要将样本作为真实文档出示给受益人、患者、付款方或机构,也不要从你传递的样本中移除样本标记;见 docs/synthetic-data-policy.md。
贡献
见 CONTRIBUTING.md(合成数据规则、审查清单、DCO 签署)和 SECURITY.md。