Metadata-Version: 2.4
Name: mineru-refine
Version: 0.9.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Summary: MinerU output linter/fixer — LLM tool-use loop that restructures (never generates) MinerU content_list. Machine-verified fidelity: C_out ⊆ C_in.
Keywords: mineru,pdf,content-list,postprocess,linter,llm
Author-email: LcpMarvel <lcpmarvel@gmail.com>
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Repository, https://github.com/LcpMarvel/mineru-refine

# mineru-refine

[MinerU](https://github.com/opendatalab/MinerU) 解析结果的后处理器(linter / fixer)。

接收 MinerU 的 `content_list`(item 对象数组),修掉解析产生的高频结构问题——伪标题、
跨页断句、跨页拆表、混入正文的页眉页脚、LaTeX / 链接残留——返回**同 schema** 的
content_list,下游零改动。

两条核心承诺:

- **绝不新增一个字**:只做削减与重组,输出的每个内容字符都来自输入,由机器逐步校验,
  违反即自动回滚(不是靠 prompt 约束 LLM)。
- **fail-open**:任何异常 / LLM 不可用 → 原样返回输入(`report["failOpen"] == True`),
  绝不搞崩上游。

本包是 Rust 核心实现的 PyO3 原生绑定,与 JS / Rust / HTTP 版选项和返回值完全同构。

## 安装

```bash
pip install mineru-refine
```

需要 Python ≥ 3.9。

## 用法

```python
import json
import mineru_refine

items = json.load(open("content_list.json"))

result = mineru_refine.refine(
    items,                              # content_list(list[dict])
    sha256="...",                       # 可选:源文件 SHA256,提供则启用进程内缓存
    max_iterations=None,                # 可选:修复循环硬上限,默认随疑点数自适应
    concurrency=8,                      # 可选:并行裁决的疑点数,1 = 严格串行
    image_dir="/abs/mineru/out",        # 可选:MinerU 产物目录,提供则启用跨页拆表的视觉裁决
    fix_ocr_confusion=False,            # 可选:opt-in 的 OCR 字符混淆修正层(CE0→CEO 等)
    extra_confusion_pairs=None,         # 可选:混淆准入名单补充对,如 ["0D"]
    rewrite_garbled_tables=False,       # 可选:opt-in 的重度乱码表视觉重转写层(需要 image_dir)
)

result["items"]    # 清洗后的 content_list(同 schema,未知字段原样透传)
result["report"]   # 审计报告:iterations / opCounts / dismissed / removedSpans
                   #          / violations / tokenUsage / failOpen
                   #          (开 fix_ocr_confusion 后另有 confusionFixes 等,见主 README)
```

删除的每段内容都留痕于 `report["removedSpans"]`(itemId / 原文 / 原因),逐条可审计。
`fix_ocr_confusion=True` 开启混淆修正层(直接替换,LLM 提案 + 机械闸门),
开启后输出契约从"只删不增"变为双契约——详见主 README 的「混淆修正层」一节。
`rewrite_garbled_tables=True` 开启重度乱码表的视觉重转写层(机械检测整表认废的表,
Qwen-VL 对照截图逐单元格重转写,全量进 report["tableRewrites"])——详见主 README 的
「乱码表重转写层」一节。

独立工具函数(都不调 LLM):

```python
mineru_refine.render_markdown(items)    # items → full.md 文本(确定性重渲染)
mineru_refine.detect_suspects(items)    # 仅探测疑点,返回疑点列表
```

## 环境变量

| 变量 | 必需 | 用途 |
|---|---|---|
| `DEEPSEEK_APIKEY` | 是 | 文本裁决(DeepSeek)。缺失时 refine 直接 fail-open |
| `QWEN_APIKEY` | 视觉裁决需要 | 跨页拆表的 Qwen-VL 裁决;缺失则该类疑点跳过,表格原样保留 |

库本身不读 `.env`,请在宿主程序里设置环境变量(或自行加载 `.env`)。

## 本地构建

```bash
just py-dev        # 仓库根:构建 wheel 并装进 bindings/python/.venv
just publish-py    # 发布 PyPI:当前平台 wheel + sdist(需 MATURIN_PYPI_TOKEN)
```

探测器、修复操作集、保真闸门的完整设计文档见
[仓库 README](https://github.com/LcpMarvel/mineru-refine#readme)。

## License

MIT

