ocr: add hpd-parsing-server.py (HPD-Parsing 1B, vendor vLLM fork, server-only)

[davanstrien]

Adds ocr/hpd-parsing-server.py for PaddlePaddle/HPD-Parsing (1B, Apache-2.0) — a document parser that forks a child decoding branch per page region, with a medusa P-MTP head drafting inside each branch. 94.91 OmniDocBench v1.6 at 4,752 TPS.

It earns a slot on layout output + throughput, not accuracy — 94.91 sits below ovis-ocr2 (96.58) and paddleocr-vl-1.6 (96.33). What it gives that those don't is its native <BLOCK> <type> [bbox] <CHILD> stream: block types, bboxes and reading order in one pass, kept in an hpd_blocks column alongside the markdown.

Two things reviewers should look at first

1. First non-Docker-Hub image in the collection. The model only runs on Paddle's vLLM fork (0.17.1+hpdparsing), which ships in their own registry image. It pulls anonymously (verified) and HF Jobs can fetch it, but it's ~11 GB and every job re-pulls it. build_serve_args() is the image's own /home/hpd/entrypoint.sh, not our translation.

2. Server-only by design, no offline sibling. Forking is a scheduler feature, so an offline llm.generate loop forfeits the point of the model — the vendor agrees, their image entrypoint is the serve command.

Sharp edges (all in ocr/CLAUDE.md)

• Vendor image ships no uv, so hf jobs uv run --image fails; the job command bootstraps it
• The entrypoint's speculative path PaddlePaddle/HPD-Parsing/P-MTP is neither a repo id nor a directory — vLLM rejects it outside the image's offline mode; resolve_spec_model() materializes it locally
• --enable-prefix-caching stays on, against SERVING.md's usual OCR pattern, because forked children share the parent prefix KV (52.9% hit rate measured)
• bboxes are 0–1000 normalized, not pixels (unlike surya_blocks), stamped in inference_info.bbox_space

Testing

Set	Result
ufo-ColPali 5 + shuffled 10	15/15, 0 errors, 0 tag leaks, 0 out-of-range bboxes; bbox space confirmed by overlay render
OmniDocBench 12 shuffled	12/12, 0 errors; covers tables (HTML w/ rowspan/colspan) + equations (LaTeX)
Chronicling America 12 (1774–1809)	10/12 excellent — within 1% of LoC's own OCR length and cleaner — 2/12 repetition collapse

Known failure mode, documented not fixed

On dense 1809 advertisement pages that fragment into 279–340 blocks, output degenerates into repetition loops; one page emitted 726,706 chars against 24,907 in the reference OCR. Structural cause: --max-tokens bounds one branch, not the page, so hundreds of forked children can each spend the full budget. Nothing errors and nothing truncates. A per-block repetition guard + repetition flag is the follow-up (pairs with the deferred ocr_error column); flagging rather than silently trimming, since upstream's own postprocessing does no repetition cleanup.

Also unexercised: chart and seal blocks, the two types whose text is deliberately suppressed.

🤖 Generated with Claude Code