Research: external fact signal pipeline

[WW-shan]

@Soli22de 我整理了一个新的研究/实现方向，想和你讨论一下是否值得做成后续 PR：

Spec 文档：
https://github.com/WW-shan/poly_strategy/blob/main/docs/superpowers/specs/2026-05-15-external-fact-signal-pipeline-design.md

核心想法

这次不是继续做 maker/cross-platform arb，也不是全网爬虫，而是做一个外部事实信号管线：

1. 从 Polymarket active markets / resolution rules 出发，判断每个市场真正需要等什么外部事实。
2. 只盯少数可信来源，比如 SEC EDGAR、Federal Register、CourtListener。
3. 新文档发布后，用 LLM 把非结构化内容抽成结构化 fact。
4. 把 fact 映射回 market_id，产出当前项目已经能消费的 external_signal。
5. 跑 shadow report，看这个 fact 是否真的早于价格变化，并且扣掉 spread/depth 后还有没有可交易边际。

重要边界

• 不做全网爬虫。
• 不做 live trading。
• 不把新闻/GDELT 当最终 truth source，除非市场规则明确允许。
• 第一阶段只证明这个方向有没有信息优势，不急着下单。

我建议的 PR 拆分

• PR 1: market_fact_need classifier + coverage report
• PR 2: SEC EDGAR / Federal Register / CourtListener source connectors
• PR 3: LLM structured fact extractor + market mapper，输出 external_signal
• PR 4: forward-return / tradability report

希望你先帮忙判断的问题

• 这个方向是否真的有实现价值？
• 第一阶段应该做到哪里？
• 你觉得先做哪个 source family 最合适？
• 第一个 PR 是否只做 classifier/report，还是带一个 connector 做 end-to-end proof？

我的倾向：第一个 PR 先不要实现完整 pipeline，只做 market fact-needs classifier + coverage report，证明我们能把 active markets 合理路由到 sec_edgar / federal_register / courtlistener / manual 这些 source families。

[Soli22de]

@WW-shan 整体方向 ack，shadow-first + 限定 source family + LLM 抽 fact 这套路线我同意。
不过我想推一步——把 "unstructured" 的定义比你现在写的再放宽一点，下面是具体的。

一个 spec 没盖到的维度：OCR / PDF / scan

你 spec 里 "unstructured" 默认是自由文本（SEC EDGAR text、Federal Register API JSON、CourtListener 已 OCR 文本）。
但真实世界里，以下 source 大量是 PDF / 扫描件 / 表格图像：

• SEC 8-K 的 exhibits（合同、薪酬包、settlement letter）—— 不少是 PDF 附件，无文本层
• CourtListener 早期 docket（2010 前后）—— 多为 scan
• 联邦机构纸质公告（FDA Form 483、EPA 罚单）—— PDF 而非 API
• 公司年报 / 财报附件（表格、图表）—— PDF 文本，LLM 直接吃会丢结构

这一层正好是我 dash-ocr-pipeline（#6 PR 里提的）那边的产线能力（OpenRouter LLM + Gemini Flash + Qwen fallback + 表格结构化）。
如果把 OCR/PDF 解析做成 spec 第二个连接器层（在 raw_external_doc 之前），可以打开你 spec 里没列的一类 source。

更重要的是这条路有护城河——大多数其他 Polymarket 参与者用纯 text API 就停了。
公开资料 ≠ 易于结构化，这是真正的 information asymmetry。

你 5 个 open question 我的答案

Q	我的建议
Q1: PR 1 是否含一个 connector？	必须含。纯 classifier 没有 ground truth 验证，跑不出 forward-return report 等于无 audit。建议 PR 1 = classifier + 最小 SEC EDGAR connector + 5-10 个 market sample 的 end-to-end shadow
Q2: 哪类市场最适合？	实测 closed markets 100 个样本估计：FDA 审批 / SCOTUS 判决 / SEC 指控 三类显式有 resolutionSource URL（占比 10-20%）。剩下 80% 是经济数据 (NFP/CPI/FOMC) 这类需要 description-LLM 推断 source family。建议 MVP 只覆盖前 3 类
Q3: LLM profile？	新建一个 high-recall 的 cheaper profile。理由：fact extractor 的 false-positive 成本比 false-negative 低（mapper 阶段还能再筛）。建议 google/gemini-2.0-flash 主 + qwen/qwen-2.5-72b fallback，跟 #6 的 T2 配置同档
Q4: manual audit 样本量？	至少 30，分 3 档：清晰的 direct_trigger (10) / 模糊的 material_update (10) / 边界 case (10)。<30 统计意义弱，>100 我们扛不住人工
Q5: expected_direction 强制吗？	direct_trigger 强制，其他 optional。direct_trigger 是 spec 最敏感的判断，必须有方向；material_update 是温度计，方向可以含糊

我可以承诺的（先克制）

• 不马上接 PR 1 全量实现（你那是 4 个 PR series，工作量大）
• 可以先做一个最小 OCR POC 分支：
  1. 拉 1 个 SEC 8-K + 1 个 8-K exhibit PDF
  2. 跑 PDF 解析 → 抽文本
  3. 用 LLM 抽 fact
  4. 跟 EDGAR text-only fact 做对比，看 OCR 是否捕到 text-only 漏掉的 fact
• 跑完一周后给你看结果，再决定要不要把 OCR 加进 PR 2 connectors

一条 kill criteria 补充建议

你列的 5 条 kill criteria 漏了成本边界：

• "OCR/PDF 解析 + LLM token cost 超过单 signal mid-price move 期望值" → 停 OCR 这条路

OCR 不是 free。一份 50 页扫描 PDF Gemini Flash 跑下来 ~$0.05-0.10。如果该类 signal 的 expected edge 跑不过这个，OCR 路径要砍。

—

如果你 OK 这个方向，我这周起 OCR POC 分支，跑完先在这条 issue 下报告，不直接开 PR。

[Soli22de]

小更新——按上面承诺跑了个 OCR POC，实测推翻了我自己上一条回复里的一个 claim，先发出来。

分支：feat/ocr-fact-extraction-poc
报告：docs/ocr_poc/report_2026-05-19.md

做了什么

最小 e2e pipeline：SEC EDGAR API + Federal Register API → 下 PDF → pypdf 抽文本 → stub LLM fact extractor（占位 regex，生产换 OpenRouter gemini-flash）。

关键实测（驳我自己上一条）

Source family	我上次说	实测
SEC 8-K exhibits	"常是 PDF"	现代 0% — Apple/Tesla 最近 8-K 14 个 attachment 全是 HTM/XBRL，0 个 PDF
Federal Register PDF	"需要 OCR"	现代 100% 有 text layer — 3/3 sample 都能直接 pypdf 抽出来 2,400-3,900 chars

→ OCR 在 spec 列的现代主流 source 上 0 价值。我上次把 SEC 8-K 当 OCR 主战场是错的——modern XBRL/inline filing 已经全 text-first。

修正后的 OCR 真实价值在哪

Source	OCR 是否需要
SEC EDGAR modern (post-2010)	❌
Federal Register modern	❌
CourtListener early dockets (pre-2010)	✅ scan-only
FDA Form 483 / 警告信	⚠️ 部分
EPA / OSHA 执法	⚠️ 部分
外国监管文件（中证监 / BaFin / FCA）	✅ 全球扩展时关键

→ OCR 不是 PR 2 的 connector 主体，是 PR 2 的 conditional fallback layer：

def fetch_filing(filing):
    text = try_text_api(filing)
    if text: return text
    pdf = try_pdf_url(filing)
    if pdf and has_text_layer(pdf): return pypdf_extract(pdf)
    if pdf: return ocr_extract(pdf)  # 这一层才是我能加的价值
    return None

这次 POC 没做的事

• 没拉到一个真正的 scan-only PDF 测（CourtListener API 需 auth，没继续）—— 所以"OCR 在老文档上有价值"这个 claim 现在还是未实测
• 没真调 LLM（占位 regex 跑通了，但 fact schema 没填）
• 没接 Polymarket market mapping（FR notice → market_id 这步没动）

我现在的建议（修订上一条）

• 把 OCR 在 PR 2 里降级为 conditional fallback，不要为它单独开 connector
• 想真证明 OCR 的扩展价值，先要一个 scan-only sample 实测（你有 CourtListener API key 吗？或者你认可的另一个 scan-rich source？）
• 如果你 OK 这个新 framing，我可以接着做：(a) 找一份 scan-only PDF 跑 tesseract/Gemini Vision 实测、(b) 接 1 个 Polymarket SEC-related closed market 的端到端 shadow report，验证 fact-precedes-price thesis

不急着 push 这个分支变 PR，等你 react 再说。

[Soli22de]

更新——上一条说"OCR 在 scan-only 类源上有价值"还是未实测 claim。刚跑了一个干净对比把它落实：

实验

用 pdf2image 把一份已知有 text-layer 的 FR PDF 栅格化成 image-only PDF（模拟"本来就是扫描的"），然后三路对比 vs ground truth：

路径	抽出字符	词级 recall
pypdf 在原 PDF（text-layer）	3,084	100% (gt)
pypdf 在 scan-only PDF	1	0% ❌
tesseract @ 300 DPI 在 scan-only	2,976	98.7% ✅

Tesseract 输出首 200 字（验证非随机）：

This document is scheduled to be published in the
Federal Register on 2026-05-18 and available online at
https://www.federalregister.gov/d/2026-09841, and on
https://govinfo.gov
Agency for Healthcar...

含义

OCR fallback 在 scan-only PDF 上 0% → 98.7% recall —— 不是空话。

修正后的 fetcher pseudo-code：

def fetch_filing(filing):
    text = try_text_api(filing)
    if text: return text
    pdf = try_pdf_url(filing)
    if not pdf: return None
    if has_text_layer(pdf):
        return pypdf_extract(pdf)       # 现代 PDF 95% 走这里
    return tesseract_ocr(pdf)           # CourtListener early / FDA scan / 外国监管

对 spec 的影响（修订）：

• PR 2 不需要单独开 OCR connector
• raw_external_doc 的 fetcher 必须含 text_layer 检测 + tesseract OCR fallback 分支
• LLM cost 不变（OCR 输出是 text，进 LLM 跟正常 text 一样）

仍未做

• 没拉 CourtListener / FDA Form 483 真实 scan-only PDF（用 rasterize 模拟代替）—— PoC 立住但 claim 强度差一档
• LLM 还是 stub regex
• Polymarket market mapping 没接

最新代码 + 报告：branch feat/ocr-fact-extraction-poc，commit 341b293。

[WW-shan]

@Soli22de ack，这个 POC 很有用，尤其是你把前一个 OCR claim 自己推翻再收窄了范围。我的判断是：OCR 方向成立，但不应该成为 #11 第一阶段的主线。

我建议这样收口：

决策

1. PR 1 先做 market_fact_need classifier + coverage/audit report，不接 connector。

   • 输出 market_fact_need NDJSON。
   • 报告各 source family 覆盖率、automation_eligible 比例、低置信样本。
   • 导出 30 个 manual audit 样本：direct_trigger / material_update / boundary case 各 10 个。
   • 目标是先证明：active markets 能不能被稳定、可审计地路由到 sec_edgar / federal_register / courtlistener / manual。

2. PR 2 再做一个 source family 的最小 vertical slice。

   • 不要一次上 SEC + FR + CourtListener。
   • 根据 PR 1 coverage 决定先做哪个；如果现在预选，我倾向先做 SEC EDGAR，因为 timestamp、official source、entity mapping 都相对清楚，更容易验证 fact-precedes-price thesis。
   • CourtListener 先延后，auth/docket/scan-only PDF 会把复杂度提前放大。

3. OCR 不作为独立 connector，也不作为 PR 1/PR 2 blocker。

   • 你的 POC 证明了 scan-only PDF 上 OCR fallback 有价值，这个我认可。
   • 但现代 SEC/FR 主路径基本 text-first，所以 OCR 应该是 fetcher 的 conditional fallback layer：

text = try_text_api(doc)
if text:
    return text

text = try_html_or_text_attachment(doc)
if text:
    return text

pdf = try_pdf_url(doc)
if not pdf:
    return None

if has_text_layer(pdf):
    return pypdf_extract(pdf)

return ocr_extract(pdf)

4. raw_external_doc schema 里建议加一个 provenance 字段。
   • 例如 body_text_source: api|html|pdf_text_layer|ocr。
   • 这样后续 report 可以单独看 OCR fallback 的命中率、成本和质量，而不是把它混在普通 text source 里。

对你这个 POC 分支的处理建议

我不建议直接把 feat/ocr-fact-extraction-poc 合进 main。它更适合作为 research artifact：

• live network script
• 硬编码 SEC User-Agent/email
• docs 下实验脚本和生成结果
• tesseract/poppler/pdf2image 这类系统依赖

这些都还不是正式 connector 边界。可以保留分支和报告作为 #11 的设计依据，等 PR 2 做 source fetcher 时，把里面的有效结论迁移成测试过的生产代码。

下一步

我建议先开 PR 1：market_fact_need classifier + coverage report + audit export。等这个报告告诉我们哪类市场覆盖最多、最可自动化，再决定 PR 2 先接 SEC EDGAR 还是 Federal Register。

这条路线的关键验证还是：published_at 是否早于 market price move，以及扣掉 spread/depth 后是否还有 edge。OCR 只有在真实 source 样本显示 text path 失效时再启用。