v0.17.2

v0.17.2 — 0.17 系列首个 PyPI 发布版

0.17.0 and 0.17.1 were both tagged but never published to PyPI; 0.17.2 is the first published release of this line and includes everything in 0.17.0 and 0.17.1 plus the fix below.

• 包含 0.17.0 的全部内容：DI markdown 叙事入库与页码标记、页级父子（默认 page+child）、跨语言查询翻译、结构化未命中回落叙事（ADR 0023）、叙事数字防编造（ADR 0024）、LiteLLM / Claude CLI provider、ragspine batch 等。
• 包含 0.17.1 的全部内容：逐调用、分阶段的 LLM 埋点（ADR 0028）；pdfspine 0.11.1 / 0.11.2 上 source-paint 证明的复核修复；测试里 sqlite 连接泄漏与 BM25 同分排序的修复。
• 修复：common/llm_json 新增显式嵌套深度上限 MAX_JSON_DEPTH = 512，超过即返回 None，在 json.loads 之前用字符串感知的 O(n) 扫描判定，结果不再依赖平台栈深（0.17.1 的 release 门禁正是因此在 Linux / Python 3.14 上失败）。正常 LLM 回文行为不变。
• 本地 CI 第 10 步改为在最新 PyPI 依赖、Python 3.14 上复跑完整测试套件。

完整条目见 CHANGELOG。

v0.17.1

Not published to PyPI (release gate failed on Linux/3.14); superseded by 0.17.2.

v0.17.1 — 0.17 系列首个 PyPI 发布版

0.17.0 was tagged but never published to PyPI; 0.17.1 is the first published release of this line and includes everything in 0.17.0 plus fixes.

• 包含 0.17.0 的全部内容：DI markdown 叙事入库与页码标记、页级父子（默认 page+child）、跨语言查询翻译、结构化未命中回落叙事（ADR 0023）、叙事数字防编造（ADR 0024）、LiteLLM / Claude CLI provider、ragspine batch 等。
• 新增逐调用、分阶段的 LLM 埋点（ADR 0028）：请求 trace 带 llm_calls，ragspine batch 汇总各阶段调用。
• 修复：在 pdfspine 0.11.1 / 0.11.2 上，source-paint 证明现在能正常复核（改为显式的“已审阅 SDK 升级”表，未列出的版本仍按失败处理）；另外修复了测试里的 sqlite 连接泄漏，以及依赖 BM25 同分排序的测试。
• 本地 CI 新增第 10 步：用最新 PyPI 依赖、在 Python 3.14 上复跑 PDF 相关测试，和 release runner 保持一致。

完整条目见 CHANGELOG。

v0.17.0 — DI markdown 入库、页级父子、跨语言检索与叙事防编造

Not published to PyPI; superseded by 0.17.1.

v0.17.0 — DI markdown 入库、页级父子、跨语言检索与叙事防编造

• DI markdown 走叙事通道入库，<!-- page: N --> 页码标记让 locator 指向真实 PDF 页（ADR 0027）。
• 页级父子 + 按页去重，默认 page+child；按需附页图 RAGSPINE_PAGE_IMAGES=off|tagged|all（ADR 0025，默认 off）。
• 跨语言查询翻译，默认 auto（译文只进检索，精排与生成仍用原问题）。
• 结构化未命中先回落叙事（ADR 0023）；叙事答案中片段里没有的数字被确定性移除（ADR 0024）。
• 新 provider：LiteLLMProvider（[litellm] extra）与 ClaudeCliProvider；截断重试与容错 JSON 解析。
• ragspine batch：批量问答与 retrieval-only 评测。

升级注意：默认值变化（page_parent / query_translation / narrative fallback / number guard / truncation retry）、.md 进叙事白名单、同名文件入库报 DocIdConflictError、[litellm] 使 openai<3、enterprise_pdf_rag 旧导入路径废弃（ADR 0022 垫片）、ReindexRequiredError 文案变化。详见 CHANGELOG.md 的 [0.17.0] 一节。

v0.16.1 — 文档树路由默认开启

v0.16.1 — 文档树路由默认开启

• ADR 0019 的文档树路由通道现在默认开启（短查询仍不调用；请求里 tree_route: false 可关闭）。
• 测试里的 pdfspine 版本标签改为从安装版本推导，避免上游升级时无关变红。
• 其余与 0.16.0 相同。

v0.16.0 — 图表全量放行、页窗口、查询分类与问答审计

本版把 enterprise_pdf_rag 的检索从"一次只看见一个 fragment"推到"看得见整页、读得懂问题、看得见文档结构"：图表按 point 逐条放行（ADR 0016）、每个命中连同整页上下文一起读（ADR 0017）、按问题挑通道并把外语问题先复述进索引语言（ADR 0018）、文档目录树作为第三通道（ADR 0019，默认关闭）；同时把一次缓存命中的问答从 8.90s 压到 0.69s，并补上采样确定性、本地问答审计与可配置超时。ragspine 的既有 API 与行为不变；本版能力都不动 snapshot id、不重建索引，旧快照原样挂载即可获得。

ADR：0016 · 0017 · 0018 · 0019

检索能力

• 图表按 point 放行，不再整张丢弃（ADR 0016）。figure-source-labels-only-v1 只能拿标签跟一整条 source span 比、带数字即拒，再把整张图清空——29 个图表对象 20 个整张被拒。新 scope source-labels-and-verbatim-points-v1 改为逐 point fail-closed：category 与 value（含单位）各自在图区内逐字印出才留下，figures/source_label_match.py 允许跨行、跨相邻 span 拼接（33 + % 即一条 33%）。pinned AIA release 上严格索引覆盖 44.6%（125/280）→ 81.4%（228/280），图表事实 3.7%（6/161）→ 67.7%（109/161）。旧 scope 逐字节冻结，老快照照常挂载重放，adapters/visual_requalification.py 可无模型重投影它们。

• 每个命中连同整页一起读，而整页本身不可引用（ADR 0017）。检索一次只给一个成员打分，图表到了 prompt 里没有标题、标题没有正文。processing/context_builder.PageContextBlock 把该页其余成员各折成一行挂在 [page_context page_index=N] 之下，每页只放一块（answers/page_window.py）。这一块不打印 field path、不打印 member id，模型硬要引它就落进既有的 unknown member 拒绝；散文数字门只放宽"可复述页上下文印过的数字"、不放宽引用，三个对抗金标仍照常弃答。

• 按问题挑通道，外语问题先在索引语言里复述一遍（ADR 0018）。混合检索此前无条件 RRF 融合两路，而没人量过它是否有用：覆盖探针（125 条事实各问两种问法）说没有——BM25 单路 recall@10 74.4% 对融合的 70.4%。answers/query_mode.py 无模型、无 I/O 地分类：≤5 token 且 ≤2 实词走 BM25 单路，词法通道打不了分的走向量单路，其余保持融合。adapters/query_translation.py 用一次有界且可缓存的调用复述索引语言之外的问题，且复述只喂词法通道——向量通道与 rerank 判官读原问题（中文问题把要找的图排在第 12 位、其英文复述排在第 32 位），prompt 与散文门也只看原话。

• 文档目录树成为第三通道——默认关闭的 opt-in（ADR 0019）。借 PageIndex（VectifyAI）的思路，processing/document_tree.py 在摄入时把目录折成一棵树：确定性地建在 ADR 0013 的逐字页元数据上，"子节点按序铺满父节点"由 __post_init__ 强制，丢页重页的树构造不出来；模型只写非叶节点的路由注记——它路由、不作证，不进索引、不可引用。每问一次有界调用返回至多 6 个节点、6 个页面，作为第三个排名进入同一个 fuse() 而非预过滤（过滤只会删，一次错路由就能藏掉答案）。
  这一路用自己的 RRF 常数称重，第一次实测就是原因：按 k = 60 与打分通道平起平坐时，真实模型金标从 21/22 跌到 17/22，路由成员占去 220 席中的 117，"Agency share of VONB 1H26" 答出有据可查却错误的 68.3%（ex-Thailand），而 p18 的图写的是 72%。fuse(…, tree_k=600.0) 单独计权，由 HybridSearch.__init__ 强制 tree_k + 1 > k + channel_limit（1/601 = 0.00166 对 1/110 = 0.00909）：路由页可以抬起没有通道够到的成员，但不能把它排到任何被打过分的成员之上。同日复测：开与关都是 22/22，无一判定改变、引用页完全相同，路由席位降到 78/220、其中只有 4 席是树独自够到的。
  所以 ROUTE_BY_DEFAULT = False，要用传 AnswerRequest.tree_route=True：这份 20 页文档的两个打分通道已够到每一页，树不改变任何一个答案，却每问多花一次实时调用、多 +3.8s ~ +23.0s——不改变任何东西的特性不该每问烧一次调用；PageIndex 的前提是远长于此的文档，翻默认之前该在数百页文档上重测。树是不入 manifest 的增量旁路记录，旧 release 跑一次 enterprise-pdf-rag tree 即可补上。

性能

• 挂载时验一次，之后只看漂移。挂载会完整验证整个 pinned release（约 5000 个内容寻址资产及其证据），然后每个请求原样再验一遍：一个缓存命中的问题 8.90s 里 6.06s 是 resolve、4.37s 是 manifest，模型调用还没登场。release 不可变且内容寻址，挂载之后那些工作只证明一件事——没漂移。现在一次请求只重读"其摘要即 processing id"的 pinned manifest，改写照旧拒绝、不一致则回落完整验证；检索 plan 与 index 也改为每进程解析一次。实测单问 8.90s → 0.69s、十个金标问题均值 9.00s → 0.81s，每例状态不变；APP_VERIFY_EVERY_REQUEST=1 可恢复旧的逐请求验证以备审计。

确定性与可观测性

• 一个 release 一套采样（ADR 0018 amendment 4）：adapters/json_completion.py 的 vision 与 text 两条路径现在都发 DETERMINISTIC_TEMPERATURE = 0.0，并在配了 APP_ANSWER_SEED（默认 0）时带 seed。它使现有 completion 缓存全部失效（采样在请求体内，而请求体正是指纹所摘要的东西）；它买不到的是可复现的答案——两次冷跑 22 次调用里 21 次指纹逐字节相同，仍有 9 个答案措辞不同：引擎是确定的，而这家 provider 不兑现贪心解码；不可变的 completion 缓存仍是唯一的可重复性保证。
• 缓存留下发出去的请求，而不只是拿回来的答案：model-cache/contexts/<request_fingerprint>.json 存下发给 provider 的逐字 JSON 请求体（system rules、每条消息、response schema、token 预算）；vision 调用把内联 image_url 换成 {"omitted": true, "sha256", "bytes"}，写失败只留个码、绝不让调用失败。
• 每个答案都写进本地 sqlite 问答日志：adapters/answer_audit.py 一问一行、写两次——prompt 装配完、碰传输之前开行（prompt_system / prompt_user 与信封的 payload.messages 逐字节一致，另含融合排名与席位），拿到结果后闭行（model_output_raw、llm_live_calls、cache_hit、status / abstain_reason 与两侧 claim）。写日志永不改变答案，失败一律降级为警告；APP_ANSWER_AUDIT_ENABLED（默认开）/ APP_ANSWER_AUDIT_PATH 控制，enterprise-pdf-rag audit --db … [--last N] [--show ID] 不启服务、不调模型即可回看。它保留证据原文，因此永远是 ingestion root 下的本地文件。
• 单次模型调用的等待时间可配置：APP_ANSWER_TIMEOUT_SECONDS（默认 45，按 (0, 180] 校验，配错在启动时就失败）。此前所有部署都钉在 45 秒默认值上，而 ADR 0017 的页窗口让"总结某一节"这类问题足以越线——Summarise the Growth Engines section for Hong Kong 就在 48.3s 上 503 了。

修复

• 图表 claim 先读单位、再读数字（ADR 0016）：$m 图只印裸的 294，模型照 prompt 写 294$m，于是每个 $m 图表值都被当成 CLAIM_NOT_IN_EVIDENCE 扔掉。_split_unit 现在把展示串拆成数字与它周围印着的东西（含会计式 (294)），两者各自逐字比对、不做归一化；反向的洞一并补上——294% 对一个 $m point 过去竟然能通过，现在是独立的拒绝理由 AbstainReason.UNIT_MISMATCH。
• 带小数点的 chart point id 可以被引回：points.point-1h26-roe-17.5.value 是 prompt 印出的可引路径，校验器却在第一个点截断，忠实的答案被 MODEL_OUTPUT_INVALID 掉——凡是 context block 印成可引的就必须能读回。
• 并排图按列绑定地区（ADR 0013 amendment 1）：p.13 三张并排的 VONB ($m) 图（AIA Thailand 514 / Singapore 294 / Malaysia 232）共享同一组页级地区值，四次冷跑里两个泰国问题答了八次、一次都不对。纯模块 processing/column_regions.py 把已验证的地区 span 绑到它所覆盖的图表列上，全有或全无：任一列没拿到标题就回落页级值。无模型、无 I/O，只是挂载期的内存投影，snapshot id 不变、不重新索引。k01-region-thailand-en / k02-region-thailand-zh 从 known gap 变成 status: answered，金标自此零 known gap。
• 地区过滤整词匹配，排除式取值永不匹配（ADR 0018 amendment 1）：Thailand 从 29 个候选成员放宽到 51 个，而 ex-Thailand / Asia ex-Japan 这类"相反的断言"全部 18 个成员照旧排除。外语问题还会从复述里多派生一份过滤条件并取并集。
• 问题自己印出的数字按形式判定，而非按拼写：_NUMBER_RE 会读千分位，"In 2024, VONB grew" 的逗号被吃进 token，2024, 永不等于问题里的 2024，完整引用的答案因此被判弃答；现在按量级与百分号形态比较，而裸 11 仍撑不起 11%。
• 成员用短别名引用，而不是 64 个十六进制字符：一次真实运行里模型抄对了 57 个字符，p05-donut-title-only-en 整个被 unknown member 丢掉。prompt 现在对真正进入它的 block 铸造 m1 … mN，resolve_member_aliases 在任何校验之前换回真 id；完整 id 仍"每个字符都抄对才接受"，没铸造过的串照旧被拒。别名不离开这次调用，契约仍用真实 64 位 id；代价是同样使 completion 缓存失效。
• 短问题必须是短标签才走 BM25 单路（ADR 0018 amendment 2）：Agency share of VONB 1H26 是 5 个 token 但 3 个实词，单走 BM25 会把它需要的图从融合的第 7 位掉到第 12 位。短句现在同时花两份预算（≤5 token 且 ≤2 实词），代价明码标价：探针 recall@10 74.4% → 73.6%，换回三个真实金标案例。
• 视觉对象的保底席位按它自己通道里的名次判定（ADR 0012 / 0015，取代 0.15.0 记的 2 * top_k 融合窗口）：RRF 会把只有一路够到的命中排在两路都够到的命中之后，而那恰恰是保底席位要救的对象；窗口现在是"接下来 k 个融合名次 或 任一通道自己排在 2 * top_k 以内"。另外，页序几何读取失败不再拖垮一次挂载。

其他变更

• 自然语言答案金标冻结成集：data/benchmarks/enterprise-pdf-rag/aia-2026-interim/nl-answers-gold-v1.json 冻结 25 例（15 正、7 弃答、3 对抗），只冻跨运行稳定的东西（page_index、field_path、quote、claim 的 value / unit），绝不冻 claim_id、member_id、快照 id 或散文措辞。两个 runner 共用 adapters/nl_gold.py 的 judge()——离线的在默认门里重放，nl_gold_eval.py 打真实服务。
• 金标要求可以写备选锚点：required_claims 的一项或 filters_expected 可写成 {"any_of": [...]}。pinned release 把 record Operating ROE 印了两遍（p.3 的句子、p.7 的图表 point），引哪一个并不稳定——原先"一条要求一个锚点"断言了比证据更多的东西。
• 目录搬迁：benchmarks/ → data/benchmarks/（金标是数据），examples/ → scripts/examples/。

---

升级：pip install -U rag-spine==0.16.0

scripts/ci.sh 九道门本地全绿（pytest 收集 5477 例：主套 5388 passed / 41 skipped，docling 套 19 passed；demo ALL CHECKS PASSED）；发布门另在 Python 3.12 / 3.13 / 3.14 三条 matrix 腿上复跑。真实模型金标 22/22、零 known gap。

Full Changelog: v0.15.0...v0.16.0

v0.15.0 — 表格网格来源证明与 Diagram/Formula 可检索

本版让 enterprise_pdf_rag 的三类视觉 / 结构对象获得"从源文件本身证明"的能力：有格线表格的行列网格从页面绘图证明（ADR 0014），Diagram 与 Formula 在结构被无模型规则证明后进入索引、上下文与引用（ADR 0015）；并修复三处从 AIA 报告验收中暴露的问题（视觉对象保底席位、散文门枚举标记、strict schema 离线守卫）。ragspine 的既有 API 与行为不变；此前发布的所有快照仍可原样解析、挂载与 resolve。

表格网格来源证明（ADR 0014）

• TableIR / TableCell.verification 此前一律 PENDING，单元格引用只能引其文本、引不到行列。现在当且仅当存在证明时 VERIFIED：每条行 / 列边界落在 page.get_drawings() 的真实轴对齐格线上（0.5pt 内），每条单元格边被连续格线覆盖（共线碎段拼接），每个合并单元格由"其内部不存在格线"证明。
• processing/geometry.py 新增格线词汇，processing/table_grid_proof.py 为纯规则，adapters/pdfspine_tables.py 产出观测（实线描边、细填充矩形、描边矩形的边；虚线 / 曲线 / 过粗路径不算格线）。
• 表头分级：粗内部格线或填充色带是 proved、可引用；粗体或"第一行"只是 heuristic、永不可引。
• stage receipt 绑定 grid_scope + ruling_digest，每次 resolve 从 pinned 源 PDF 重新推导整套证明。答案可引用单元格的 row / col / header——仅限已验证网格，表头须逐字匹配（忽略空白）。
• 无格线、吸附、双线表格保持 PENDING，仍可检索、仍可按单元格文本引用。

Diagram / Formula 可检索（ADR 0015）

• DIAGRAM / FORMULA 对象此前止步于 ADR 0006 的"无独立验证器"诊断，从不进索引 / 上下文 / 引用。现在一条无模型、可重放的证明与两条模型分支并行跑在同一 pinned 裁剪上；成立时写入 qualified_ir / qualified_description / qualification。
• Diagram（adapters/diagram_geometry.py + diagram_qualification.py，processing/diagram_models.py + diagram_description.py）：每个节点标签须与所引 span 逐字相等，节点 bbox 须匹配真实绘制的框（2pt 内），每条边须有从源节点出发的连接线加一枚落在目标节点内的实心箭头，对象内每个 span 都必须被引用——否则整个对象带逐字诊断 fail-closed。仅节点无边的图也可通过，且不打印任何边。
• Formula（processing/formula_models.py + formula_rules.py，adapters/pdfspine_formula.py + formula_qualification.py）：token 在铺砌闭包规则下引用 span 子串并携带逐字符 bbox；上下标由 PDF 自身的 Ts 证明或标为 derived；分数线与根号引用真实 get_cdrawings() 路径，对象内每条路径都必须被解释。全证明公式为 VERIFIED（proof_level="full"），含 derived 上下标的公式在 literal 级可检索但保持 PENDING。
• 两者的描述都是确定性模板，绝不是第二次模型调用。索引文本 policy 升至 source-transcription-and-scoped-chart-qualification-v5（新增共用门 VISUAL_PROJECTION_POLICIES）；答案可引用 nodes.<id>.label、edges.<index>、formula.linear、formula.readable、tokens.<index>（折叠空白、保留大小写比较；_literal 更名 _exact）。
• rag-chat-v1 新增 diagram / formula block 与 diagram_node / diagram_edge / formula claim；processing_export 新增 diagram_structure_qualified / formula_tokens_qualified 覆盖列。
• 新脚本：scripts/enterprise_pdf_rag/requalify_visual_objects.py 用已存分支重证已发布快照的图（无模型、不动指针、--dry-run 不写），让发布版无需重跑 semantics 即可获得能力；scripts/enterprise_pdf_rag/formula_smoke.py 对已存 processing id 只读跑公式证明。

修复

• 已证明的 Diagram / Formula 与图表一样获得保底 prompt 席位（ADR 0012 推广到 ADR 0015）：AIA p6 三阶段路径已资格化并进索引，却从未进入十个席位，模型改答 p5 散文。answer_service.select_context 现为每种可引用视觉类型（带显式值的图表、带标签节点的图、带线性形式的公式）保留一席，取 2 * top_k 窗口内、top_k 之外的首个成员；席位从末尾向前让出，永不挤占已持有可引用视觉对象的席位，pending / 仅标签的对象永不晋升。
• 编号列表不再触发散文数字门（answers/verify.prose_grounded）：行首或句首的 1. / 2) / 3、 / (4) / 第 5 / Step 6 视为枚举标记而非数字，列表形答案在有已验证 claim 时正常作答；条目正文内的金额 / 百分比 / 年份照旧把关，句末小数永不误判为标记。
• strict response schema 离线守卫（tests/enterprise_pdf_rag/adapters/test_strict_response_schemas.py）：ADR 0015 验证时每次对话都被 provider 侧 HTTP 400 拒绝，根因是 ModelClaim 一个可选字段使 required 不完整（a0a0d18），离线测试看不见。新增参数化守卫遍历 _response_schema 实际发送的九个 response_model schema，强制 strict 规则（每个属性 required、additionalProperties: false、无不支持的组合关键字、$ref 仅指向本地 $defs）。

---

scripts/ci.sh 九道门全绿（Python 3.12 / 3.13 / 3.14）；pytest 收集 5050 例（-m "not gpu and not docling and not network"）。

v0.14.0 — enterprise_pdf_rag 并包与经验证的答案链

本版首次把 enterprise_pdf_rag（可追溯财务 PDF 取证 / 问答后端）作为独立顶层包并入同一分发（ADR 0021）：pip install rag-spine 同时得到 import ragspine 与 import enterprise_pdf_rag，以及两个控制台入口 ragspine 与 enterprise-pdf-rag。两包在同一 pyproject.toml、同一测试收集、同一 scripts/ci.sh 九道门下发版；ragspine 的既有 API 与行为不变。

enterprise_pdf_rag — 新的 sibling 包（ADR 0021）

• 内容寻址的不可变快照（source → processing → retrieval）、从 PDF span / drawing 到答案的证据链、source-qualified ChartQA。历史经 git subtree 完整保留。
• ragspine 只允许在 adapters/ 下被 import；figures/ documents/ processing/ 为纯 stdlib 包，由 check_architecture.py 守护；四道结构门（conformance / architecture / schema / drift）成为 ci.sh 第 9 步。
• 资源（resources/）、CLAUDE.md / AGENTS.md 契约随 wheel 出货；文档、PRD、ADR 0001–0011 与 JSON schema 位于 docs/enterprise-pdf-rag/。

通用 PDF 摄入入口（ADR 0010）

enterprise-pdf-rag ingest --pdf <任意 PDF> --pages all|1-3,5 --stage source|layout|semantics --max-live-calls N：任意 PDF 进入不可变草稿；默认 source 阶段零模型调用，完整源始终保留，页选择只作用于下游。随后 qualify → index → publish 三步各自显式、无隐式模型调用、无隐式激活。装好 wheel 后在项目树外用 APP_ROOT_DIR / APP_DATA_DIR 即可运行。

文档目录、挂载服务与经验证的自然语言答案链（ADR 0011）

• document-catalog 执行模式：APP_EXECUTION_MODE=document-catalog 扫描 APP_INGESTION_DIR 下的已发布文档，逐份挂载并在任何模型调用前重验 pinned manifest；漂移 / 损坏 → 409，缺 embedder → 503，绝不退回 mock。
• document-catalog-v1 契约：GET /v1/documents、GET /v1/documents/{id}、.../manifest、POST .../search、POST .../context（schema 见 docs/enterprise-pdf-rag/schemas/）。
• 混合检索：pinned 余弦向量通道 + 同一描述文本上的 BM25 词法通道，复用 ragspine 的检索 / 重排件而非再写一套检索器。
• OpenAI 兼容对话：POST /v1/chat/completions 从"只做 source review、财务问题 422"升级为经证据链回答的自然语言问答，答案逐条对照证据校验，继承家族的反编造 / 溯源不变量。
• 散文数值门放宽（ISSUE-3）：此前回答里任何不在已验证 claim 文本 / 值中的数字都整体拒答（“…in 1H 2026 was 17.5%.” 因 “2026” 被拒）。现在数字满足其一即视为有据：属于已验证 claim 的 text / value；逐字出现在用户问题里；出现在已验证 claim 所引用证据的原文中（span quote、表格 cell、图表 period / category 标签与 source_display）。其余数字仍整体拒答，零验证 claim 的处理与 decide 顺序不变。
• 图表召回（ISSUE-2，ADR 0012）：图表成员改为按其已资格化 IR 的投影建索引（<title> <period> <grammar> chart figure + 每点 <category> <series> <value><unit>，检索 policy v3，BM25 与向量通道打分同一字符串）；top_k 6→10、channel_limit 20→50；top-k 内没有可引用图表而后 k 位内有时，给它一个 prompt 席位；响应新增可选 member_ranks 便于读出检索行为。已发布快照继续可挂载可回答，但要重跑 index + publish 才拿到投影。
• 页级自动元数据、上下文索引文本与期间 / 区域预过滤（ADR 0013）：新增 page_metadata 处理阶段，全自动为每页生成元数据（公司 / 报告 / 期间 / 页主题，无人工标注）；页标题等上下文前置进成员的索引文本而不改动存储原文；检索支持期间 / 区域等值预过滤，候选枯竭时自动放弃过滤回退到全量排序。
• TABLE 图元放行进目录；图表几何匹配加入显式容差（COORDINATE_TOLERANCE）。
• Open WebUI 预览脚本新增 document-catalog profile，ENTERPRISE_PREVIEW_STATE_DIR 可把预览的日志 / PID 记录挪到别处，与已记录的预览并行。

ragspine — TableStructureRecognizer 缝 + TATR 后端（新 [tsr] extra）

针对 FinTabNet.c 实测（pdfspine strategy="text" 表格检出召回 79.6% / 精确率 100%，瓶颈在检出后的网格重建）新增只做 TSR 一半的缝：Protocol + 离线确定性默认 GridStructureRecognizer + 工厂 + RAGSPINE_TABLE_STRUCTURE 环境选择 + 参数化 conformance。默认 None = 关，既有抽取路径字节不变；[tsr] extra 接入 Microsoft Table Transformer 的结构识别，torch / transformers / pillow 延迟 import。

依赖与工具链

• httpx>=0.27 进入 base：enterprise_pdf_rag 的 HTTP 层静态 import httpx，此前不装 [service] 时 enterprise-pdf-rag --help 直接 ModuleNotFoundError；新增守卫测试 tests/enterprise_pdf_rag/test_base_dependencies.py，断言 enterprise_pdf_rag 的每个第三方 import 都被 [project].dependencies 覆盖。
• 基础依赖升至 corespine>=0.5.1、pdfspine>=0.11.0、pydantic>=2.12,<3；pydantic-settings[yaml]、fastapi / uvicorn / jinja2 / resvg-py / fonttools 进入 base（enterprise_pdf_rag 的默认能力）。
• 全仓统一 ruff 0.16 格式；mypy strict 覆盖 src/ragspine、src/enterprise_pdf_rag、tests/enterprise_pdf_rag、scripts/enterprise_pdf_rag；uv 0.12.17。

---

scripts/ci.sh 九道门全绿（Python 3.12 / 3.13 / 3.14）；pytest 收集 4863 例（-m "not gpu and not docling and not network"）。

v0.13.0 — 三方互通兼容层

新增三条兼容层，让 RAGSpine 能接入既有生态、也能吃下别人的产物。均为薄适配：只做签名/工件翻译，不重写检索或编排逻辑。

OpenAI Chat Completions 兼容端点

POST /v1/chat/completions（阻塞 + SSE 流式）与 GET /v1/models，形状对齐 OpenAI 官方，故 openai SDK、Open WebUI、LangChain、以及任何 "OpenAI-compatible provider" 位置都能零改动直连。复用 /v1/ask 的守卫链，继承「守卫先于流」不变量；客户端 system 消息刻意丢弃（系统提示服务端受控）。溯源经顶层 ragspine 扩展字段带出，不因套形状而丢失。

LightRAG 形状 Python 适配器

from ragspine.compat.lightrag import LightRAG, QueryParam —— 既有 LightRAG 调用方改一行 import 即可迁移。query() 按对方签名返回裸字符串，另开 query_with_sources() 保住 AgentResult。insert() 的裸文本落成内容寻址文件后走正规摄入，从而获得真实血缘。mode 映射与召回口径差异在 docstring 明说，不假装等价。

MS GraphRAG parquet 工件双向互通

新增 [graphrag-compat] extra。import_graphrag_artifacts() 把 graphrag index 的产物吃进任意 GraphStore；export_graphrag_artifacts() 反向写出。导入项血缘经 text_units 回溯（绝不留空）并戳 model-derived/unverified；导出走 subgraph，RESTRICTED 不可能外泄。

---

28 个新测试；scripts/ci.sh 八道门全绿（QA 评测双模式 41 例全过、0 编造）。Python >=3.12。

RAGSpine 0.12.1

Python floor relaxed back to >=3.12 (no upper bound) — 0.12.0's 3.14-only requirement is lifted.

Changed

• requires-python = ">=3.12"; classifiers 3.12 / 3.13 / 3.14; CI and release matrices run 3.12–3.14.
• Restored the quoted self-referential annotations that 3.12/3.13 need (no PEP 649 lazy evaluation there); ruff target py312 / mypy 3.12.

Full changelog: https://github.com/VoldemortGin/ragspine/blob/main/CHANGELOG.md

RAGSpine 0.12.0

RAGSpine workspace facade + Python 3.14

Breaking

• Python 3.14 only (>=3.14,<3.15). Python 3.11–3.13 users stay on 0.11.0.

Added

• High-level RAGSpine workspace facade with unified dual-channel ingestion and guarded asking
• economy / balanced / quality retrieval presets with explicit typed overrides
• Installed ingest, doctor, config init/show, and zero-Redis local serve CLI paths
• Effective-configuration provenance and offline dependency / key / model / filesystem diagnostics
• Per-file ingestion channel, fact, chunk, review, skipped-page, warning, and remediation feedback
• Automatic workspace GraphRAG; workflow readiness checks, deploy bundles, and typed run inputs

Changed

• Package-root API exposes the RAGSpine facade alongside the four original primitives
• Toolchain (ruff/mypy), CI matrices, and Docker images target Python 3.14

🤖 Generated with Claude Code