knowhive-pdf

KnowHive 的 PDF 解析插件：用 docling 把 PDF 解析成 KnowHive 的 DocumentIR JSON（server/src/documentIr.ts 的形状），通过 stdio 协议供主程序调用。主程序保持 single runtime——本插件经 uv tool install knowhive-pdf 按需安装，不装则主程序完全无感。

开发期暂驻主仓库 pdf-plugin/；发布时整体迁出为独立 repo + PyPI + GitHub Actions Trusted Publishing。

协议

$ knowhive-pdf --stdio
→ {"type":"ready","schema_version":1,"plugin_version":"0.1.0","docling_version":"..."}
← /path/to/file.pdf
→ {"type":"result","path":"...","ir":{"format":"pdf","blocks":[...]}}
→ {"type":"error","path":"...","code":"needs_ocr|bad_text_layer|parse_failed","message":"..."}

调试用一次性模式：knowhive-pdf file.pdf。

v1 范围与设计决定

不含 OCR（do_ocr=False）。扫描件由 triage 拦截返回 needs_ocr；中文 OCR 留 v2。
triage 先行（pypdfium2，毫秒级）：每页字符中位数 <50 且页面含图 → needs_ocr；无图或乱码字符占比 >10% → bad_text_layer。坏文字层是最阴的静默失败——页面渲染正常但抽出来是空/乱码（校准样本：pdf.js issue9534_reduced.pdf）。
NFKC 归一化：子集化中文字体会把部分汉字映射到康熙部首码位（⼀ U+2F00 ≠ 一 U+4E00），肉眼相同、检索必死。所有输出文本过 NFKC。
标题层级从编号推导（"3.1"→L3）：docling 的 section_header 是平的。
表格 caption 拆分：docling 的表格 markdown 前缀 caption；拆成独立段落块，表格块从表头行开始——主程序 splitTable() 的表头重复逻辑依赖"首行=表头、次行=分隔行"。

开发

uv sync
uv run pytest                      # 快速套件（不加载 docling 模型）
KNOWHIVE_PDF_SLOW=1 uv run pytest  # 含完整 docling 解析（首跑下载版面模型）

tests/fixtures/bad-textlayer.pdf 来自 mozilla/pdf.js 测试语料（issue9534_reduced）。

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

knowhive_pdf-0.2.0.tar.gz (542.6 kB view details)

Uploaded Aug 1, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

knowhive_pdf-0.2.0-py3-none-any.whl (8.8 kB view details)

Uploaded Aug 1, 2026 Python 3

File details

Details for the file knowhive_pdf-0.2.0.tar.gz.

File metadata

Download URL: knowhive_pdf-0.2.0.tar.gz
Upload date: Aug 1, 2026
Size: 542.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for knowhive_pdf-0.2.0.tar.gz
Algorithm	Hash digest
SHA256	`ec8cc3bfa12cb73e100923a110da25021f6cb9ce5f88329a590542d924b3f53c`
MD5	`61d5cf44258cda365f0c60918ba3790f`
BLAKE2b-256	`08d9c14df279f58e2ca9198fec30b5350bda44a2cd3eea8a927550457b025cfb`

See more details on using hashes here.

Provenance

The following attestation bundles were made for knowhive_pdf-0.2.0.tar.gz:

Publisher: publish.yml on PlonGuo/knowhive-pdf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: knowhive_pdf-0.2.0.tar.gz
- Subject digest: ec8cc3bfa12cb73e100923a110da25021f6cb9ce5f88329a590542d924b3f53c
- Sigstore transparency entry: 2312620973
- Sigstore integration time: Aug 1, 2026
Source repository:
- Permalink: PlonGuo/knowhive-pdf@285672f0a74f1f2cf4d50bbaf0139efc567f8f59
- Branch / Tag: refs/tags/v0.2.0
- Owner: https://github.com/PlonGuo
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@285672f0a74f1f2cf4d50bbaf0139efc567f8f59
- Trigger Event: push