pdf-ocr

---
name: pdf-ocr
description: Convert text-layer or scanned PDF files to clean Markdown and extracted images with MinerU, then run deterministic quality checks and optional LLM-assisted formula review. Use when a user asks to OCR a PDF, extract a PDF to Markdown, preserve formulas or tables from a PDF, or prepare a PDF for translation.
---

# PDF OCR

Convert a PDF to `<output>/full.md` and `<output>/images/`. Default to MinerU's cloud `vlm` API. Keep the source PDF unchanged.

## Privacy and authorization gate

Before the first network call for each input document:

1. State that selected PDF pages will be uploaded to MinerU for processing.
2. State the input path, selected page range, and output directory.
3. If the document may be confidential, contain personal data, or the user's authorization is unclear, obtain confirmation before uploading. A request that explicitly names MinerU and the exact document can count as confirmation when no sensitivity is apparent.
4. Never ask the user to paste an API token into chat. Never print, log, or write the token into the workspace.

## Preflight

1. Locate this skill directory from the loaded `SKILL.md`; do not assume it is under `~/.codex` or any other platform-specific root.
2. Inspect the PDF with `pdfinfo` when available. Sample `pdftotext` output when deciding whether `--method ocr` is useful.
3. Require Python 3.9+. Prefer `uv`: the cloud entry script declares `requests` and `pypdf` with PEP 723, so `uv run` creates an isolated cached environment automatically.
4. If `uv` is unavailable, require `requests` and `pypdf` in the selected Python environment. Install `requirements.txt` only with the user's approval; it also includes optional `httpx` for external LLM review.
5. Check only whether `MINERU_API_TOKEN` exists. If absent, stop before uploading and direct the user to MinerU's current API management documentation. Do not claim a fixed token lifetime, quota, or price.
6. MinerU cloud API requests, presigned uploads, polling, and result downloads use a direct HTTP session by default. Proxy environment variables are intentionally ignored for this workflow.
7. Default to a small page sample for a large or uncertain document, then inspect quality before processing the full file.

## Run OCR

From the skill root, run cloud OCR with isolated, automatically resolved dependencies:

```bash
uv run scripts/ocr.py --input <pdf> [--output <dir>]
  [--backend cloud-vlm|cloud-pipeline|vlm-auto-engine|hybrid-auto-engine|pipeline|vlm-http-client]
  [--lang ch|en] [--method auto|txt|ocr]
  [--chunk-pages 200] [--start N --end N] [--url <server-url>]
```

`start` and `end` are zero-based and inclusive. Keep each cloud chunk within the provider's current limits; the script rejects values above 600 pages per chunk. Provider limits may change, so provider errors and current documentation are authoritative.

For local backends, require a working `mineru` executable on `PATH`. The local path can use `python3 scripts/ocr.py ...` because it does not need the cloud Python packages. Do not install MinerU or download models without the user's approval.

Fallback when `uv` is unavailable and the user authorizes installing into their selected Python environment:

```bash
python3 -m pip install -r requirements.txt
python3 scripts/ocr.py --input <pdf> [options]
```

## Quality control

`scripts/ocr.py` automatically runs `scripts/qc.py` in report mode after OCR. Treat missing images as blocking. Review the report for:

- broken Markdown or HTML image references;
- spaced digits and suspicious formula patterns;
- degraded mathematical tables;
- `[Unreadable]` markers;
- domain-incongruent hallucination markers.

Apply deterministic fixes only after inspecting the report:

```bash
python3 scripts/qc.py <full.md-or-directory> --fix --promote-display --tables-to-markdown
```

Use `--fix-hallucination` only after confirming the flagged language is inconsistent with the document's domain.

## Optional LLM formula review

Default to host review: use the current agent to inspect flagged formulas and nearby context without an external LLM call. Keep this optional layer separate from deterministic QC, review changes before writing, and do not claim a complete mathematical proof check.

For automated batch review, the user may explicitly choose `openai-chat`, `openai-responses`, or `anthropic-messages`. Before that external call, disclose the selected context scope, protocol, model, and endpoint host; require `LLM_API_KEY` and `LLM_MODEL`; never expose the key. These are wire protocols, not a provider catalog.

```bash
uv run scripts/llm_fix.py repair <full.md-or-directory> --protocol openai-chat
uv run scripts/llm_fix.py repair <full.md-or-directory> --protocol openai-responses --apply
uv run scripts/llm_fix.py audit <full.md-or-directory> --protocol anthropic-messages --key 30 --random 30
```

Run `repair` without `--apply` first. The script only auto-applies small edits and creates `.bak` files plus `_llm_fix_log.md` when writing.

## Handoff to translation

If the user also requests translation, pass `<output>/full.md` to the `md-translate` skill only after OCR QC. Do not translate inside this skill.

## Report

Report the backend, exact output paths, processed page range, Markdown line/word counts, image count, QC findings, and whether LLM review was run. Distinguish `NOT-RUN` from a successful check.