Initial release of OvisOCR3

.gitattributes

@@ -19,6 +19,7 @@
 *.pb filter=lfs diff=lfs merge=lfs -text
 *.pickle filter=lfs diff=lfs merge=lfs -text
 *.pkl filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
 *.pth filter=lfs diff=lfs merge=lfs -text
 *.rar filter=lfs diff=lfs merge=lfs -text
@@ -33,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Alibaba Cloud
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,3 +1,537 @@
 ---
 license: apache-2.0
+library_name: transformers
+pipeline_tag: image-text-to-text
+base_model: Qwen/Qwen3.5-0.8B
+tags:
+- ocr
+- document-parsing
+- multimodal
+- markdown
+- tables
+- formulas
+- key-information-extraction
+- figure-captioning
+- vllm
+- qwen3_5
 ---
+
+# OvisOCR3
+
+<p align="center">
+  <img src="https://cdn-uploads.huggingface.co/production/uploads/658a8a837959448ef5500ce5/vRCIu5QD8VuIJolkC_ZHQ.png" alt="Ovis" width="30%" />
+</p>
+
+## Introduction
+
+OvisOCR3 is a **unified 0.8B multimodal model for OCR and document understanding**. It integrates **document parsing, general OCR, key information extraction, document figure captioning, and cross-page table reconstruction** into a single compact model. These capabilities are selected through task-specific prompts, bringing recognition, extraction, and understanding together without requiring separate model deployments for each task.
+
+Built on Qwen3.5-0.8B, OvisOCR3 is trained in four stages: continued pretraining, mid-training, on-policy distillation, and reinforcement learning. This training process builds a strong foundation in text recognition and document structure understanding, then refines these capabilities through domain-specific supervision and rewards.
+
+OvisOCR3 achieves **state-of-the-art performance among models of comparable size across all five domains**, demonstrating that a single compact model can combine strong document parsing with a broad range of OCR and document-understanding capabilities.
+
+![OvisOCR3 performance overview across five task domains.](./assets/ovisocr3_performance_overview.png)
+
+## Capabilities
+
+| Capability | Input | Output |
+| --- | --- | --- |
+| Document parsing | A page image and a parsing-mode prompt | Structured JSON, layout JSON, or Markdown with LaTeX formulas and HTML tables |
+| General OCR | An image, optionally with a region, references, a question, a target language, or candidate labels | Text, bounding boxes, LaTeX, chart data, a label, or an answer |
+| Key information extraction | An image, optionally with specified fields or a JSON output template | Key-value records or JSON following the supplied template |
+| Document figure captioning | A page image and a document-figure-caption-mode prompt | Structured page content with localized visual captions and Mermaid representations for flowcharts |
+| Cross-page table reconstruction | Consecutive page images and their parsed Markdown | Complete HTML tables with source-page associations, or a no-continuation prediction |
+
+The [task prompts](./prompts/) specify the output contracts. The examples below use these files directly.
+
+## Performance
+
+Performance comparisons across five task domains are reported below. `--` denotes an unreported value, not zero. Bold scores indicate the best result in each column.
+
+### Document Parsing
+
+| Model | OmniDocBench1.6 | MDPBench | PureDocBench | Real5-OmniDocBench |
+|---|---:|---:|---:|---:|
+| Qwen3.5-OCR | 91.27 | 60.60 | 68.38 | 82.48 |
+| Qwen3.8-Max | 93.70 | 86.40 | 80.56 | 86.86 |
+| GLM-OCR | 95.22 | 67.30 | 63.34 | 90.32 |
+| PaddleOCR-VL-1.6 | 96.34 | 78.90 | 65.44 | 93.19 |
+| MonkeyOCRv2-B-Parsing | 91.57 | 83.30 | 64.91 | 89.22 |
+| OvisOCR2 | 96.58 | 69.00 | 75.10 | 92.29 |
+| HunyuanOCR-1.5 | 94.74 | 76.80 | 67.58 | 88.53 |
+| Xiaomi-OCR-0 | **96.83** | 73.00 | 74.60 | 92.73 |
+| **OvisOCR3** | 96.74 | **88.80** | **82.31** | **93.63** |
+
+### General OCR
+
+| Model | OCRBench | OCRBench v2 EN | OCRBench v2 ZH |
+| --- | ---: | ---: | ---: |
+| Qwen3.5-0.8B | 79.1 | 41.5 | 43.9 |
+| Qwen3.5-2B | 85.4 | 48.1 | 55.4 |
+| Qwen3.5-4B | 85.0 | 54.1 | 61.0 |
+| Qwen3.5-OCR | 76.8 | 44.5 | 43.8 |
+| PaddleOCR-VL-1.6 | 55.9 | 23.8 | 30.4 |
+| HunyuanOCR-1.5 | 86.1 | 50.7 | 57.7 |
+| GLM-OCR | 83.8 | 32.9 | 48.1 |
+| Xiaomi-OCR-0 | 84.6 | 40.1 | 48.4 |
+| **OvisOCR3** | **88.8** | **65.9** | **61.3** |
+
+### Key Information Extraction
+
+| Model | OCRBench KIE | OCRBench v2 KIE | CC-OCR KIE | In-house KIE Bench |
+| --- | ---: | ---: | ---: | ---: |
+| Qwen3.5-OCR | 78.50 | 72.90 | 88.43 | 59.90 |
+| GLM-OCR | 79.00 | 74.22 | 68.36 | 75.25 |
+| HunyuanOCR-1.5 | 81.00 | 68.63 | 66.08 | 75.96 |
+| Xiaomi-OCR-0 | 76.50 | 74.66 | 79.53 | 75.68 |
+| **OvisOCR3** | **90.50** | **83.01** | **88.69** | **77.73** |
+
+### Document Figure Captioning
+
+| Model | DocFigCapBench Localization F1 | DocFigCapBench Caption Score |
+| --- | ---: | ---: |
+| HunyuanOCR-1.5 | 48.24 | -- |
+| Qwen3.5-OCR | 78.47 | 4.74 |
+| OvisOCR2 | 82.18 | -- |
+| MinerU2.5-Pro | 85.00 | 4.61 |
+| PaddleOCR-VL-1.6 | 85.32 | 4.29 |
+| Qwen3.8-Max | 86.67 | **7.30** |
+| **OvisOCR3** | **90.97** | 6.93 |
+
+### Cross-Page Table Reconstruction
+
+| Model | CrossTabBench Relation F1 (P/R) | CrossTabBench Reconstruction TEDS | MPDocBench-Parse Truncated Table TEDS |
+| :--- | ---: | ---: | ---: |
+| PaddleOCR-VL-1.6 | 42.61 (90.13/27.90) | 24.24 | 83.39 |
+| Logics-Parsing-V3 | 44.55 (90.63/29.53) | 26.10 | 88.05 |
+| MinerU2.5-Pro | 59.14 (93.81/43.18) | 41.02 | 91.44 |
+| MinerU2.5-Pro + MinerU-PoPo | 54.76 (97.40/38.09) | 36.42 | 91.87 |
+| Qwen3.8-Max | 94.47 (90.19/99.19) | **91.71** | 89.57 |
+| **OvisOCR3** | **97.07** (96.20/97.96) | 89.66 | **92.04** |
+
+## Inference
+
+The example uses a local model directory containing the weights, configuration, tokenizer, processor files, and `prompts/`. Run it from that directory, or set `MODEL_PATH` to its location. A GPU environment supported by vLLM is required.
+
+```bash
+pip install "vllm==0.22.1" pillow
+```
+
+```python
+import warnings
+from pathlib import Path
+
+from PIL import Image
+from vllm import LLM, SamplingParams
+
+
+MODEL_PATH = Path(".")
+
+model = LLM(
+    model=str(MODEL_PATH.resolve()),
+    tensor_parallel_size=1,
+    gpu_memory_utilization=0.8,
+    gdn_prefill_backend="triton",
+    limit_mm_per_prompt={"image": 2},
+)
+tokenizer = model.get_tokenizer()
+sampling_params = SamplingParams(max_tokens=16384, temperature=0.0)
+
+
+def load_prompt(name: str) -> str:
+    return (MODEL_PATH / "prompts" / f"{name}.txt").read_text(encoding="utf-8")
+
+
+def infer(
+    images: list[Image.Image], task_prompt: str, *,
+    return_metadata=False,
+):
+    if not 1 <= len(images) <= 2:
+        raise ValueError("This example accepts one or two images per request.")
+
+    content = [{"type": "image"} for _ in images]
+    content.append({"type": "text", "text": task_prompt})
+    prompt = tokenizer.apply_chat_template(
+        [{"role": "user", "content": content}],
+        tokenize=False,
+        add_generation_prompt=True,
+        enable_thinking=False,
+    )
+    request = {
+        "prompt": prompt,
+        "multi_modal_data": {"image": [image.convert("RGB") for image in images]},
+        "mm_processor_kwargs": {
+            "images_kwargs": {
+                "min_pixels": 448 * 448,
+                "max_pixels": 2880 * 2880,
+            }
+        },
+    }
+    output = model.generate([request], sampling_params)[0].outputs[0]
+    if output.finish_reason == "length":
+        warnings.warn("Generation reached a token limit; the output may be incomplete.")
+    return (output.text, output.finish_reason) if return_metadata else output.text
+
+
+page = Image.open("test1.jpg").convert("RGB")
+text = infer([page], load_prompt("plain_ocr"))
+Path("output.txt").write_text(text, encoding="utf-8")
+print(text)
+```
+
+`infer` returns the raw generated text by default; `return_metadata=True` also returns the finish reason. It does not remove image tags, trim repetitions, repair JSON, or otherwise rewrite the response. All task examples share the inference settings above. These are usage settings, not benchmark reproduction settings.
+
+An image list passed to `infer` belongs to **one request**. For independent pages, call `infer([page], prompt)` for each page. The two-image form is used for cross-page reconstruction below.
+
+## Task-Specific Usage
+
+The following snippets reuse `page`, `infer`, and `load_prompt` from the inference example. Replace placeholder values with the fields, regions, or questions needed for your document. Use literal placeholder replacement rather than Python `str.format`, since prompts also contain JSON and LaTeX braces.
+
+### Document Parsing
+
+Compared with OvisOCR2's Markdown parsing, OvisOCR3 adds structured document parsing and document layout detection. Structured parsing returns region-level records with bounding boxes, categories, and content; Markdown parsing returns a continuous document without explicit bounding boxes or category labels for individual text regions.
+
+| Mode | Prompt | Output |
+| --- | --- | --- |
+| Markdown | [document_markdown.txt](./prompts/document_markdown.txt) | A document in natural reading order, with LaTeX formulas, HTML tables, and image-region references |
+| Structured | [document_structured.txt](./prompts/document_structured.txt) | A JSON array with `bbox`, `category`, and `content` for each element |
+| Layout only | [document_layout.txt](./prompts/document_layout.txt) | A JSON array with `bbox` and `category`, without transcription |
+
+For `document_markdown`, follow the [OvisOCR2](https://huggingface.co/ATH-MaaS/OvisOCR2) postprocessing order: strip leading and trailing whitespace, optionally filter image-tag blocks (enabled by default), and then apply repeated-tail cleanup to every response regardless of the finish reason. Set `filter_imgtags=False` to retain visual-region references for rendering. Keep `raw_markdown` for inspection; structured and layout JSON outputs are left unchanged. The helper checks its own length and repetition thresholds. It does not recover missing content or make a truncated response complete.
+
+```python
+def _clean_truncated_repeats(
+    text: str,
+    min_text_len: int = 8000,
+    max_period: int = 200,
+    min_period: int = 1,
+    min_repeat_chars: int = 100,
+    min_repeat_times: int = 5,
+) -> str:
+    n = len(text)
+    if n < min_text_len:
+        return text
+
+    max_period = min(max_period, n - 1)
+    for unit_len in range(min_period, max_period + 1):
+        if text[n - 1] != text[n - 1 - unit_len]:
+            continue
+
+        match_len = 1
+        idx = n - 2
+        while idx >= unit_len and text[idx] == text[idx - unit_len]:
+            match_len += 1
+            idx -= 1
+
+        total_len = match_len + unit_len
+        repeat_times = total_len // unit_len
+        tail_len = total_len % unit_len
+
+        if repeat_times >= min_repeat_times and total_len >= min_repeat_chars:
+            return text[: n - total_len + unit_len] + text[n - tail_len :]
+
+    return text
+
+
+# Format 1: Markdown, with optional image-tag filtering and repeated-tail cleanup.
+raw_markdown = infer([page], load_prompt("document_markdown"))
+filter_imgtags = True
+text = raw_markdown.strip()
+if filter_imgtags:
+    text = "\n\n".join(
+        block
+        for block in text.split("\n\n")
+        if not block.strip().startswith('<img src="images/bbox_')
+    )
+markdown = _clean_truncated_repeats(text)
+
+# Format 2: Structured JSON with bbox, category, and content.
+structured_json = infer([page], load_prompt("document_structured"))
+
+# Format 3: Layout JSON with bbox and category only, without transcription.
+layout_json = infer([page], load_prompt("document_layout"))
+```
+
+Structured and layout outputs follow natural reading order. The allowed category lists and category-specific content formats are defined in their respective prompts.
+
+#### Coordinates and Visual Regions
+
+Bounding boxes use `[left, top, right, bottom]` order with integer coordinates in `[0, 1000)`, relative to the image supplied to the model. The origin is the top-left corner. Convert to pixels with `x * image_width / 1000` and `y * image_height / 1000`. For cropped inputs, coordinates are relative to that crop, not the original page.
+
+Markdown and structured parsing can reference visual regions using `<img src="images/bbox_left_top_right_bottom.jpg" />`. These paths describe crops to create from the input image; the model does not write image files. Preserve the image orientation used for inference when extracting crops.
+
+<details>
+<summary>Save Markdown together with its referenced image crops</summary>
+
+```python
+import re
+
+
+BBOX_IMAGE_PATTERN = re.compile(r'images/bbox_(\d+)_(\d+)_(\d+)_(\d+)\.jpg')
+
+
+def save_markdown_with_crops(markdown: str, page_image: Image.Image, output_dir: str):
+    output_dir = Path(output_dir)
+    images_dir = output_dir / "images"
+    images_dir.mkdir(parents=True, exist_ok=True)
+    width, height = page_image.size
+
+    for left, top, right, bottom in set(BBOX_IMAGE_PATTERN.findall(markdown)):
+        x1 = max(0, min(width, round(int(left) * width / 1000)))
+        y1 = max(0, min(height, round(int(top) * height / 1000)))
+        x2 = max(0, min(width, round(int(right) * width / 1000)))
+        y2 = max(0, min(height, round(int(bottom) * height / 1000)))
+        if x2 <= x1 or y2 <= y1:
+            warnings.warn(f"Skipping invalid crop: {(left, top, right, bottom)}")
+            continue
+        crop_path = images_dir / f"bbox_{left}_{top}_{right}_{bottom}.jpg"
+        page_image.crop((x1, y1, x2, y2)).convert("RGB").save(crop_path)
+
+    (output_dir / "output.md").write_text(markdown, encoding="utf-8")
+
+
+save_markdown_with_crops(markdown, page, "output")
+```
+
+This helper handles single-page Markdown references. For reconstructed tables, resolve each `page_N/` prefix against its corresponding source page and save crops under that page's directory.
+
+</details>
+
+### General OCR
+
+<a id="general-ocr-prompts"></a>
+
+| Task | Prompt | Output |
+| --- | --- | --- |
+| Plain OCR | [plain_ocr.txt](./prompts/plain_ocr.txt) | Text without markup or bounding boxes |
+| Word-level text spotting | [word_spotting.txt](./prompts/word_spotting.txt) | JSON records with `bbox` and `text`, one per word or text token |
+| Reference grounding | [reference_grounding.txt](./prompts/reference_grounding.txt) | JSON records with `bbox` and the requested `reference` |
+| Region OCR | [region_ocr.txt](./prompts/region_ocr.txt) | Text within a specified region |
+| Formula recognition | [formula_recognition.txt](./prompts/formula_recognition.txt) | LaTeX expressions enclosed in `$$ ... $$` |
+| Chart parsing | [chart_parsing.txt](./prompts/chart_parsing.txt) | JSON with `title`, `source`, `x_title`, `y_title`, and `values` |
+| Text translation | [text_translation.txt](./prompts/text_translation.txt) | Text from a specified region translated into the target language |
+| Image classification | [image_classification.txt](./prompts/image_classification.txt) | Exactly one label from the supplied candidates |
+| Visual question answering | [visual_question_answering.txt](./prompts/visual_question_answering.txt) | Reasoning followed by a final answer inside `\boxed{}` |
+| Position-aware VQA | [position_aware_vqa.txt](./prompts/position_aware_vqa.txt) | JSON with `answer` and a string-valued `bbox` |
+
+All ten tasks read the linked `.txt` prompt files. Image classification takes a target description and candidate labels, and position-aware VQA uses its own answer-and-box instruction. Fill only the requested task inputs in each template.
+
+```python
+import re
+
+
+def general_ocr_prompt(name: str) -> str:
+    prompt = load_prompt(name)
+    return prompt if name == "position_aware_vqa" else prompt.strip()
+
+
+def general_vqa_prompt(question: str) -> str:
+    prompt = general_ocr_prompt("visual_question_answering").replace("{question}", question)
+    return re.sub(r"\n{3,}", "\n\n", prompt).strip()
+
+```
+
+```python
+import json
+
+text = infer([page], general_ocr_prompt("plain_ocr"))
+words_json = infer([page], general_ocr_prompt("word_spotting"))
+
+references = json.dumps(["Invoice number", "Total"], ensure_ascii=False, separators=(",", ":"))
+grounding_prompt = general_ocr_prompt("reference_grounding").replace("{references}", references)
+grounding_json = infer([page], grounding_prompt)
+
+region = json.dumps([100, 100, 900, 300], separators=(",", ":"))
+region_prompt = general_ocr_prompt("region_ocr").replace("{target_region}", region)
+region_text = infer([page], region_prompt)
+
+formula_latex = infer([page], general_ocr_prompt("formula_recognition"))
+chart_json = infer([page], general_ocr_prompt("chart_parsing"))
+
+translation_prompt = general_ocr_prompt("text_translation").replace("{target_region}", region)
+translation_prompt = translation_prompt.replace("{target_language}", "English")
+translated_text = infer([page], translation_prompt)
+
+target_description = "the main subject"
+candidate_labels = json.dumps(["cat", "dog", "bird", "fish"], ensure_ascii=False)
+classification_prompt = general_ocr_prompt("image_classification").replace(
+    "{target description}", target_description
+).replace("{candidate_labels}", candidate_labels)
+selected_label = infer([page], classification_prompt)
+
+question = "What is the invoice number?"
+vqa_prompt = general_vqa_prompt(question)
+answer_with_reasoning = infer([page], vqa_prompt)
+
+position_prompt = general_ocr_prompt("position_aware_vqa").replace("{question}", question)
+answer_json = infer([page], position_prompt)
+```
+
+References and regions use compact JSON. Supply references expected to be visible in the image. For classification, `{target description}` specifies what to classify, and `{candidate_labels}` is a JSON array of candidate labels. VQA accepts the complete question, including answer choices when applicable; its visible reasoning ends with a boxed answer. Position-aware VQA accepts the question text and uses its own answer-and-box prompt. Formula recognition and chart parsing need no template substitutions.
+
+Spotting and grounding boxes, as well as input regions, use `[x_min,y_min,x_max,y_max]` with integer coordinates in `[0,1000)`, normalized independently by image width and height. The origin is the top-left corner, and coordinates refer to the supplied image, including when it is a crop. Use `[0,0,999,999]` for whole-image region OCR or translation.
+
+Chart parsing represents scalar data values as strings and uses the literal string `"None"` for missing title, source, or axis metadata. Position-aware VQA uses `"bbox": "(x1,y1,x2,y2)"`, unlike the numeric arrays used by spotting and grounding.
+
+### Key Information Extraction
+
+| Mode | Prompt | Additional input |
+| --- | --- | --- |
+| Open extraction | [kie_open.txt](./prompts/kie_open.txt) | None; extract all visible key-value pairs |
+| Specified-field extraction | [kie_fields.txt](./prompts/kie_fields.txt) | `{keys_json}`: a JSON array of field names |
+| Schema-based extraction | [kie_schema.txt](./prompts/kie_schema.txt) | `{schema_json}`: a JSON template specifying the desired output structure |
+
+Schema-based extraction uses an example of the desired JSON output, not a formal JSON Schema declaration. Empty strings serve as value placeholders, while nested objects and arrays define the output structure.
+
+```python
+import json
+
+open_json = infer([page], load_prompt("kie_open"))
+
+keys = json.dumps(["invoice_number", "date", "total"], ensure_ascii=False)
+fields_prompt = load_prompt("kie_fields").replace("{keys_json}", keys)
+fields_json = infer([page], fields_prompt)
+
+schema = {
+    "invoice_number": "",
+    "date": "",
+    "seller": {
+        "name": "",
+        "address": "",
+    },
+    "items": [
+        {
+            "name": "",
+            "quantity": "",
+            "unit_price": "",
+            "amount": "",
+        }
+    ],
+    "total": "",
+}
+schema_prompt = load_prompt("kie_schema").replace(
+    "{schema_json}", json.dumps(schema, ensure_ascii=False)
+)
+schema_json = infer([page], schema_prompt)
+```
+
+Values should retain the visible source text. Open and specified-field extraction use arrays for repeated values and empty strings for empty values; specified-field extraction also uses empty strings for missing fields. Schema-based extraction follows the supplied template and uses empty strings for missing values. Adherence to the template is prompted, not enforced by constrained decoding in this example; validate generated JSON before downstream use.
+
+### Document Figure Captioning
+
+Use the **full page image** with [figure_captioning.txt](./prompts/figure_captioning.txt):
+
+```python
+caption_json = infer([page], load_prompt("figure_captioning"))
+```
+
+The model returns a structured page JSON array with `bbox`, `category`, and `content`. For visual categories such as `image` and `chart`, `content` contains a concise description inside `<caption>...</caption>`, with a maximum of 100 words requested by the prompt. These captions replace the image references used for visual regions in structured document parsing. Flowcharts additionally include a Mermaid representation inside `<mermaid>...</mermaid>`. Other page elements retain their task-specific text, formula, or table content.
+
+This is localized figure description within a document page, not just transcription of a printed figure caption.
+
+### Cross-Page Table Reconstruction
+
+OvisOCR3 reconstructs cross-page tables in two stages using the same checkpoint:
+
+1. **Stage 1: page parsing.** Parse each page independently with [document_markdown.txt](./prompts/document_markdown.txt) or [document_structured.txt](./prompts/document_structured.txt). For structured JSON output, concatenate each element’s `content` in reading order to obtain Markdown, preserving HTML tables, formulas, and image references.
+2. **Stage 2: table reconstruction.** Supply two adjacent page images and their parsed Markdown with [crosspage_table.txt](./prompts/crosspage_table.txt). The model identifies whether a table continues across the page boundary and reconstructs continued fragments as a single HTML table; otherwise, it returns a negative prediction.
+
+```python
+import re
+
+pages = [
+    Image.open("page1.jpg").convert("RGB"),
+    Image.open("page2.jpg").convert("RGB"),
+]
+page_results = [
+    infer([image], load_prompt("document_markdown"), return_metadata=True)
+    for image in pages
+]
+page_markdowns = []
+for index, (raw, reason) in enumerate(page_results, start=1):
+    if reason not in ("stop", "length"):
+        raise ValueError(f"Page {index}: finish_reason={reason}")
+    markdown = _clean_truncated_repeats(raw.strip())
+    markdown = re.sub(r'^```(?:markdown|html)?\s*\n|\n```\s*$', '', markdown.strip(), flags=re.I)
+    if not markdown:
+        raise ValueError(f"Page {index}: empty Markdown")
+    page_markdowns.append(re.sub(
+        r'(?<![\w/])(?:page_\d+/)?(images/bbox_\d+_\d+_\d+_\d+\.jpg)',
+        rf'page_{index}/\1', markdown,
+    ))
+
+if all(re.search(r'<table\b[^>]*>.*?</table\s*>', md, re.I | re.S) for md in page_markdowns):
+    page_context = "\n\n".join(
+        f'<INPUT_PAGE index="{index}">\n{markdown}\n</INPUT_PAGE>'
+        for index, markdown in enumerate(page_markdowns, start=1)
+    )
+    prompt = load_prompt("crosspage_table").removesuffix("\n") + "\n\nInput Markdown:\n\n" + page_context
+    tables_json, reason = infer(pages, prompt, return_metadata=True)
+    if reason != "stop":
+        raise ValueError(f"Cross-page output is incomplete: finish_reason={reason}")
+else:
+    tables_json = '[{"source_pages": [], "html": "No cross-page table exists between these pages."}]'
+print(tables_json)
+```
+
+The result is a JSON array. Each record has `source_pages`, using **input-local, 1-based page numbers**, and `html`, containing one complete HTML table. Images within tables retain page-qualified references such as `page_1/images/bbox_100_200_300_400.jpg`.
+
+When no cross-page table exists, the specified response is:
+
+```json
+[{"source_pages": [], "html": "No cross-page table exists between these pages."}]
+```
+
+For tables spanning more than two pages, **Stage 2 is applied recursively**, processing adjacent pairs from the end of each consecutive sequence of table-bearing pages toward its beginning. After each merge, the reconstructed table is written into the earlier page and its updated Markdown is re-rendered before the next step, keeping the image and text consistent. For example, the model first merges pages 2 and 3, then pairs the updated page 2 with page 1. Each step uses only two page images while preserving the original source-page associations. A ready-to-run document-level implementation is available in [document_crosspage.py](./document_crosspage.py), supporting either `document_markdown.txt` or `document_structured.txt` for Stage 1 and converting structured JSON to Markdown before reconstruction.
+
+![Recursive reconstruction of a table spanning three pages.](./assets/crosspage_recursive.png)
+
+*Stage 2 first reconstructs the table across pages 2 and 3, then pairs the re-rendered page 2 with page 1. Each step uses two page images and their current Markdown.*
+
+The script uses the same vLLM version and inference settings as the example above. Install the additional dependencies and run the command below from the model repository root, supplying page images in reading order.
+
+```bash
+python -m pip install beautifulsoup4 markdown-it-py playwright
+python -m playwright install --with-deps chromium
+
+python document_crosspage.py \
+    --model . \
+    --stage1-prompt document_structured.txt \
+    --output crosspage_output \
+    page1.jpg page2.jpg page3.jpg
+```
+
+Use a new output directory for each run; it contains `document.md`, per-page Markdown, raw responses, and `result.json` with table provenance and any processing errors.
+
+## Output Handling
+
+### Validation and Rendering
+
+- Preserve raw outputs before parsing, rendering, or applying cleanup. JSON, HTML, LaTeX, and Mermaid may need validation, and generation can stop before an output is complete.
+- Render Markdown with support for HTML tables and LaTeX. Figure captions and Mermaid content require their own handling inside structured JSON.
+- Treat generated HTML and Mermaid as untrusted content. Sanitize or isolate them before rendering in a browser.
+- For evaluation, freeze prompts, preprocessing, generation parameters, and postprocessing. These usage examples do not define a benchmark protocol.
+
+## Limitations
+
+OvisOCR3 can produce incorrect, incomplete, repeated, or malformed outputs. Small or blurred text, severe perspective distortion, dense layouts, complex formulas, and long tables may affect recognition and structure recovery. Captions and answers can include unsupported details; verify them against the source image.
+
+Cross-page reconstruction also depends on the quality of the first-stage page parsing and correct page order. Missing table fragments, inconsistent page context, or truncated generations can lead to incorrect merges. Review results before using them in critical applications.
+
+## Technical Report and Citation
+
+If you find OvisOCR3 useful, please consider citing our technical report:
+
+```bibtex
+@misc{ovisocr3,
+  title  = {{OvisOCR3 Technical Report}},
+  author = {{ATH-MaaS}},
+  year   = {2026}
+}
+```
+
+The technical report link will be added when available.
+
+## License
+
+This project is licensed under the [Apache License, Version 2.0](./LICENSE) (SPDX-License-Identifier: Apache-2.0).

chat_template.jinja

@@ -0,0 +1,154 @@
+{%- set image_count = namespace(value=0) %}
+{%- set video_count = namespace(value=0) %}
+{%- macro render_content(content, do_vision_count, is_system_content=false) %}
+    {%- if content is string %}
+        {{- content }}
+    {%- elif content is iterable and content is not mapping %}
+        {%- for item in content %}
+            {%- if 'image' in item or 'image_url' in item or item.type == 'image' %}
+                {%- if is_system_content %}
+                    {{- raise_exception('System message cannot contain images.') }}
+                {%- endif %}
+                {%- if do_vision_count %}
+                    {%- set image_count.value = image_count.value + 1 %}
+                {%- endif %}
+                {%- if add_vision_id %}
+                    {{- 'Picture ' ~ image_count.value ~ ': ' }}
+                {%- endif %}
+                {{- '<|vision_start|><|image_pad|><|vision_end|>' }}
+            {%- elif 'video' in item or item.type == 'video' %}
+                {%- if is_system_content %}
+                    {{- raise_exception('System message cannot contain videos.') }}
+                {%- endif %}
+                {%- if do_vision_count %}
+                    {%- set video_count.value = video_count.value + 1 %}
+                {%- endif %}
+                {%- if add_vision_id %}
+                    {{- 'Video ' ~ video_count.value ~ ': ' }}
+                {%- endif %}
+                {{- '<|vision_start|><|video_pad|><|vision_end|>' }}
+            {%- elif 'text' in item %}
+                {{- item.text }}
+            {%- else %}
+                {{- raise_exception('Unexpected item type in content.') }}
+            {%- endif %}
+        {%- endfor %}
+    {%- elif content is none or content is undefined %}
+        {{- '' }}
+    {%- else %}
+        {{- raise_exception('Unexpected content type.') }}
+    {%- endif %}
+{%- endmacro %}
+{%- if not messages %}
+    {{- raise_exception('No messages provided.') }}
+{%- endif %}
+{%- if tools and tools is iterable and tools is not mapping %}
+    {{- '<|im_start|>system\n' }}
+    {{- "# Tools\n\nYou have access to the following functions:\n\n<tools>" }}
+    {%- for tool in tools %}
+        {{- "\n" }}
+        {{- tool | tojson }}
+    {%- endfor %}
+    {{- "\n</tools>" }}
+    {{- '\n\nIf you choose to call a function ONLY reply in the following format with NO suffix:\n\n<tool_call>\n<function=example_function_name>\n<parameter=example_parameter_1>\nvalue_1\n</parameter>\n<parameter=example_parameter_2>\nThis is the value for the second parameter\nthat can span\nmultiple lines\n</parameter>\n</function>\n</tool_call>\n\n<IMPORTANT>\nReminder:\n- Function calls MUST follow the specified format: an inner <function=...></function> block must be nested within <tool_call></tool_call> XML tags\n- Required parameters MUST be specified\n- You may provide optional reasoning for your function call in natural language BEFORE the function call, but NOT after\n- If there is no function call available, answer the question like normal with your current knowledge and do not tell the user about function calls\n</IMPORTANT>' }}
+    {%- if messages[0].role == 'system' %}
+        {%- set content = render_content(messages[0].content, false, true)|trim %}
+        {%- if content %}
+            {{- '\n\n' + content }}
+        {%- endif %}
+    {%- endif %}
+    {{- '<|im_end|>\n' }}
+{%- else %}
+    {%- if messages[0].role == 'system' %}
+        {%- set content = render_content(messages[0].content, false, true)|trim %}
+        {{- '<|im_start|>system\n' + content + '<|im_end|>\n' }}
+    {%- endif %}
+{%- endif %}
+{%- set ns = namespace(multi_step_tool=true, last_query_index=messages|length - 1) %}
+{%- for message in messages[::-1] %}
+    {%- set index = (messages|length - 1) - loop.index0 %}
+    {%- if ns.multi_step_tool and message.role == "user" %}
+        {%- set content = render_content(message.content, false)|trim %}
+        {%- if not(content.startswith('<tool_response>') and content.endswith('</tool_response>')) %}
+            {%- set ns.multi_step_tool = false %}
+            {%- set ns.last_query_index = index %}
+        {%- endif %}
+    {%- endif %}
+{%- endfor %}
+{%- if ns.multi_step_tool %}
+    {{- raise_exception('No user query found in messages.') }}
+{%- endif %}
+{%- for message in messages %}
+    {%- set content = render_content(message.content, true)|trim %}
+    {%- if message.role == "system" %}
+        {%- if not loop.first %}
+            {{- raise_exception('System message must be at the beginning.') }}
+        {%- endif %}
+    {%- elif message.role == "user" %}
+        {{- '<|im_start|>' + message.role + '\n' + content + '<|im_end|>' + '\n' }}
+    {%- elif message.role == "assistant" %}
+        {%- set reasoning_content = '' %}
+        {%- if message.reasoning_content is string %}
+            {%- set reasoning_content = message.reasoning_content %}
+        {%- else %}
+            {%- if '</think>' in content %}
+                {%- set reasoning_content = content.split('</think>')[0].rstrip('\n').split('<think>')[-1].lstrip('\n') %}
+                {%- set content = content.split('</think>')[-1].lstrip('\n') %}
+            {%- endif %}
+        {%- endif %}
+        {%- set reasoning_content = reasoning_content|trim %}
+        {%- if loop.index0 > ns.last_query_index %}
+            {{- '<|im_start|>' + message.role + '\n<think>\n' + reasoning_content + '\n</think>\n\n' + content }}
+        {%- else %}
+            {{- '<|im_start|>' + message.role + '\n' + content }}
+        {%- endif %}
+        {%- if message.tool_calls and message.tool_calls is iterable and message.tool_calls is not mapping %}
+            {%- for tool_call in message.tool_calls %}
+                {%- if tool_call.function is defined %}
+                    {%- set tool_call = tool_call.function %}
+                {%- endif %}
+                {%- if loop.first %}
+                    {%- if content|trim %}
+                        {{- '\n\n<tool_call>\n<function=' + tool_call.name + '>\n' }}
+                    {%- else %}
+                        {{- '<tool_call>\n<function=' + tool_call.name + '>\n' }}
+                    {%- endif %}
+                {%- else %}
+                    {{- '\n<tool_call>\n<function=' + tool_call.name + '>\n' }}
+                {%- endif %}
+                {%- if tool_call.arguments is defined %}
+                    {%- for args_name, args_value in tool_call.arguments|items %}
+                        {{- '<parameter=' + args_name + '>\n' }}
+                        {%- set args_value = args_value | tojson | safe if args_value is mapping or (args_value is sequence and args_value is not string) else args_value | string %}
+                        {{- args_value }}
+                        {{- '\n</parameter>\n' }}
+                    {%- endfor %}
+                {%- endif %}
+                {{- '</function>\n</tool_call>' }}
+            {%- endfor %}
+        {%- endif %}
+        {{- '<|im_end|>\n' }}
+    {%- elif message.role == "tool" %}
+        {%- if loop.previtem and loop.previtem.role != "tool" %}
+            {{- '<|im_start|>user' }}
+        {%- endif %}
+        {{- '\n<tool_response>\n' }}
+        {{- content }}
+        {{- '\n</tool_response>' }}
+        {%- if not loop.last and loop.nextitem.role != "tool" %}
+            {{- '<|im_end|>\n' }}
+        {%- elif loop.last %}
+            {{- '<|im_end|>\n' }}
+        {%- endif %}
+    {%- else %}
+        {{- raise_exception('Unexpected message role.') }}
+    {%- endif %}
+{%- endfor %}
+{%- if add_generation_prompt %}
+    {{- '<|im_start|>assistant\n' }}
+    {%- if enable_thinking is defined and enable_thinking is true %}
+        {{- '<think>\n' }}
+    {%- else %}
+        {{- '<think>\n\n</think>\n\n' }}
+    {%- endif %}
+{%- endif %}

config.json

@@ -0,0 +1,96 @@
+{
+    "architectures": [
+        "Qwen3_5ForConditionalGeneration"
+    ],
+    "image_token_id": 248056,
+    "model_type": "qwen3_5",
+    "text_config": {
+        "attention_bias": false,
+        "attention_dropout": 0.0,
+        "attn_output_gate": true,
+        "dtype": "bfloat16",
+        "eos_token_id": 248044,
+        "full_attention_interval": 4,
+        "head_dim": 256,
+        "hidden_act": "silu",
+        "hidden_size": 1024,
+        "initializer_range": 0.02,
+        "intermediate_size": 3584,
+        "layer_types": [
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention"
+        ],
+        "linear_conv_kernel_dim": 4,
+        "linear_key_head_dim": 128,
+        "linear_num_key_heads": 16,
+        "linear_num_value_heads": 16,
+        "linear_value_head_dim": 128,
+        "max_position_embeddings": 262144,
+        "mlp_only_layers": [],
+        "model_type": "qwen3_5_text",
+        "mtp_num_hidden_layers": 0,
+        "mtp_use_dedicated_embeddings": false,
+        "num_attention_heads": 8,
+        "num_hidden_layers": 24,
+        "num_key_value_heads": 2,
+        "rms_norm_eps": 1e-06,
+        "tie_word_embeddings": true,
+        "use_cache": true,
+        "vocab_size": 248320,
+        "mamba_ssm_dtype": "float32",
+        "rope_parameters": {
+            "mrope_interleaved": true,
+            "mrope_section": [
+                11,
+                11,
+                10
+            ],
+            "rope_type": "default",
+            "rope_theta": 10000000,
+            "partial_rotary_factor": 0.25
+        }
+    },
+    "tie_word_embeddings": true,
+    "transformers_version": "4.57.0.dev0",
+    "video_token_id": 248057,
+    "vision_config": {
+        "deepstack_visual_indexes": [],
+        "depth": 12,
+        "hidden_act": "gelu_pytorch_tanh",
+        "hidden_size": 768,
+        "in_channels": 3,
+        "initializer_range": 0.02,
+        "intermediate_size": 3072,
+        "model_type": "qwen3_5",
+        "num_heads": 12,
+        "num_position_embeddings": 2304,
+        "out_hidden_size": 1024,
+        "patch_size": 16,
+        "spatial_merge_size": 2,
+        "temporal_patch_size": 2
+    },
+    "vision_end_token_id": 248054,
+    "vision_start_token_id": 248053
+}

document_crosspage.py

@@ -0,0 +1,1747 @@
+"""Single-file OvisOCR3 document parsing and cross-page table reconstruction.
+
+Reading guide: public entry point -> document pipeline -> text/table helpers ->
+model backend -> browser renderer. Import the text helpers without installing
+vLLM or browser dependencies; those are loaded only when used.
+
+Algorithm: parse pages independently, then visit adjacent table-bearing pages
+from last to first. Write each merged table into the earlier page and render
+that updated page before its next prediction.
+ Keep non-table source untouched.
+
+Support: the document pipeline accepts one merged table per adjacent pair and
+binds the earlier page's last table to the later page's first table. Multiple
+merges need explicit fragment bindings via apply_pair(); nested or incomplete
+HTML tables are rejected on writeback. This is a conservative binding policy,
+not a general table-fragment matching algorithm.
+
+Page numbers are 1-based; table fragment indices are 0-based. Model predictions
+use pair-local pages 1 and 2; saved Markdown and provenance use document pages.
+Raw predictions, intermediate files and partial results are retained.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import copy
+import html
+import io
+import json
+import math
+import re
+import time
+import traceback
+import uuid
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Callable, Mapping, NamedTuple
+
+NEGATIVE = "No cross-page table exists between these pages."
+TABLE = re.compile(r"<table\b[^>]*>.*?</table\s*>", re.I | re.S)
+IMAGE_REF = re.compile(
+    r"(?<![\w/])(?:page_(\d+)/)?images/bbox_(\d+)_(\d+)_(\d+)_(\d+)\.jpg"
+)
+REF = re.compile(r"page_(\d+)/images/")
+CATEGORIES = set(
+    "abstract algorithm aside_text chart content display_formula doc_title figure_title footer footer_image footnote formula_number header header_image image inline_formula number paragraph_title reference_content seal table text vertical_text vision_footnote".split()
+)
+
+FragmentId = tuple[int, int]
+Backend = Callable[[list[str], str, Path, int], tuple[str, str]]
+
+
+class GenerationResult(NamedTuple):
+    """Tuple-compatible raw model output; cleaning belongs to the page adapter."""
+
+    text: str
+    finish_reason: str
+
+
+class RenderResult(NamedTuple):
+    """Tuple-compatible render result; aliases map rendered crops to originals."""
+
+    image_path: str
+    rewritten_source: str
+    alias_to_original: dict[str, str]
+    diagnostics: dict
+
+
+@dataclass
+class PageState:
+    """One document page and the original fragments behind its current tables."""
+
+    number: int
+    image_path: str
+    original_markdown: str
+    markdown: str
+    finish_reason: str
+    parse_diagnostics: dict | None = None
+    table_sources: list[set[FragmentId]] = field(init=False)
+
+    def __post_init__(self):
+        self.table_sources = [
+            {(self.number, index)}
+            for index, _ in enumerate(TABLE.finditer(self.markdown))
+        ]
+
+
+@dataclass
+class PairInput:
+    """Two model inputs with explicit document/pair-local coordinate mapping."""
+
+    page_numbers: tuple[int, int]
+    image_paths: list[str]
+    markdowns: list[str]
+    alias_to_original: dict[str, str]
+    rendered_pages: set[int]
+
+
+@dataclass
+class DocumentState:
+    pages: list[PageState] = field(default_factory=list)
+    chunks: list[list[int]] = field(default_factory=list)
+    steps: list[dict] = field(default_factory=list)
+    merged_tables: list[dict] = field(default_factory=list)
+    parse_warnings: list[dict] = field(default_factory=list)
+
+
+# Public entry point and document pipeline.
+
+
+def reconstruct_document(
+    image_paths,
+    output,
+    *,
+    model_path=".",
+    stage1_prompt="document_structured",
+    mathjax=None,
+    backend: Backend | None = None,
+    renderer=None,
+):
+    """Reconstruct ordered page images into a document, keeping all evidence.
+
+    Use a fresh output directory. Stage 1 accepts document_markdown[.txt] or
+    document_structured[.txt]; prompts are loaded from model_path/prompts.
+    Returns the saved result.json dictionary. Truncated generations, recovered
+    JSON or invalid structured fields return PARTIAL with issue-specific warnings;
+    other processing failures save partial output and raise RuntimeError.
+
+    For research, inject backend(paths, prompt, folder, stage) -> (raw, reason)
+    and/or renderer.render(source, owner, paths, folder, name) -> RenderResult.
+    Injected renderers remain caller-owned. Defaults load vLLM and Chromium lazily.
+    Engine settings, prompt bytes and renderer resize policy are unchanged.
+    """
+    stage1_prompt = stage1_prompt.removesuffix(".txt")
+    if stage1_prompt not in {"document_markdown", "document_structured"}:
+        raise ValueError("Choose document_markdown or document_structured")
+    images = _document_images(image_paths)
+    if Path(output).exists():
+        raise FileExistsError("Use a fresh output directory")
+
+    prompt_dir = Path(model_path) / "prompts"
+    page_prompt = (prompt_dir / f"{stage1_prompt}.txt").read_text().removesuffix("\n")
+    table_prompt = (prompt_dir / "crosspage_table.txt").read_text().removesuffix("\n")
+    if backend is None:
+        backend = VllmBackend(model_path)
+    owns_renderer = renderer is None
+    if owns_renderer:
+        renderer = _BrowserRenderer(
+            mathjax or Path(__file__).resolve().parent / "assets/mathjax.js"
+        )
+    try:
+        result = _run_document(
+            images,
+            output,
+            backend,
+            renderer,
+            page_prompt=page_prompt,
+            table_prompt=table_prompt,
+            stage1_prompt=stage1_prompt,
+        )
+    finally:
+        if owns_renderer:
+            renderer.close()
+
+    if result["error"] and not result["error"].get("recoverable", False):
+        raise RuntimeError(f"Document incomplete; inspect {output}/failure.json")
+    return result
+
+
+def _run_document(
+    image_paths, output, backend, renderer, *, page_prompt, table_prompt, stage1_prompt
+):
+    """Parse pages, reconstruct adjacent pairs backwards, then persist results.
+
+    Recovery is confined to Stage 1 output parsing. A failed window stops further
+    reconstruction while preserving earlier pages, merges and failure details.
+    No benchmark labels are used. The output directory must not already exist.
+    """
+    images = _document_images(image_paths)
+    output = Path(output)
+    output.mkdir(parents=True, exist_ok=False)
+    save(
+        output / "inputs.json",
+        {
+            "images": images,
+            "stage1_prompt": stage1_prompt,
+            "page_prompt": page_prompt,
+            "table_prompt": table_prompt,
+        },
+    )
+    state = DocumentState()
+    error = None
+    context = {"stage": 1, "pages": []}
+    try:
+        for number, image in enumerate(images, 1):
+            context = {"stage": 1, "pages": [number]}
+            page = _parse_page(
+                number, image, output, backend, page_prompt, stage1_prompt
+            )
+            state.pages.append(page)
+            warning = _page_warning(page)
+            if warning:
+                state.parse_warnings.append(warning)
+
+        state.chunks = find_chunks([page.markdown for page in state.pages])
+        save(
+            output / "chunks.json",
+            {
+                "chunks": state.chunks,
+                "basis": "Stage 1 predicted HTML tables only",
+            },
+        )
+        for left, right in _adjacent_pairs(state.chunks):
+            context = {"stage": 2, "pages": [left, right]}
+            folder = output / "stage2" / f"pair_{left:04d}_{right:04d}"
+            folder.mkdir(parents=True)
+            pair = _prepare_pair(
+                state.pages[left - 1 : right], images, folder, renderer
+            )
+            tables = _predict_pair(pair, folder, backend, table_prompt)
+            _apply_merge(state, pair, tables)
+            state.steps.append(
+                {
+                    "pages": list(pair.page_numbers),
+                    "merged": bool(tables),
+                    "rendered_pages": sorted(pair.rendered_pages),
+                }
+            )
+            save(
+                folder / "result.json",
+                {
+                    "tables": tables,
+                    "pages": [
+                        state.pages[number - 1].markdown for number in pair.page_numbers
+                    ],
+                    "groups": copy.deepcopy(state.merged_tables),
+                },
+            )
+    except Exception as exc:
+        error = {
+            "type": type(exc).__name__,
+            "message": str(exc),
+            "recoverable": False,
+            **context,
+        }
+        save(output / "failure.json", {**error, "traceback": traceback.format_exc()})
+    return _finalize_document(state, images, output, error)
+
+
+def _parse_page(number, image, output, backend, page_prompt, stage1_prompt):
+    """Retain raw output, apply the existing cleanup, then adapt the page format."""
+    folder = output / "stage1" / f"page_{number:04d}"
+    folder.mkdir(parents=True)
+    generation = GenerationResult(*backend([image], page_prompt, folder, 1))
+    raw, reason = generation
+    (folder / "raw.txt").write_text(raw)
+    cleaned = _clean_truncated_repeats(raw.strip())
+    save(
+        folder / "generation.json",
+        {
+            "finish_reason": reason,
+            "complete": reason == "stop",
+            "tail_changed": cleaned != raw.strip(),
+            "raw_chars": len(raw.strip()),
+            "cleaned_chars": len(cleaned),
+        },
+    )
+    (folder / "cleaned_raw.txt").write_text(cleaned)
+    if reason not in ("stop", "length"):
+        raise ValueError(f"Stage 1 page {number}: finish_reason={reason}")
+
+    diagnostics = None
+    if stage1_prompt == "document_structured":
+        projected, blocks, diagnostics = structured_to_markdown(cleaned)
+        save(folder / "blocks.json", blocks)
+        save(folder / "adapter.json", diagnostics)
+        (folder / "projected.md").write_text(projected)
+        markdown = page_markdown(projected, number) if projected.strip() else ""
+    else:
+        markdown = page_markdown(cleaned, number)
+    (folder / "page.md").write_text(markdown)
+    return PageState(number, image, markdown, markdown, reason, diagnostics)
+
+
+def _page_warning(page):
+    """Separate generation truncation, JSON recovery and structured schema issues."""
+    codes = []
+    if page.finish_reason == "length":
+        codes.append("generation_truncated")
+    diagnostics = page.parse_diagnostics
+    if diagnostics is not None:
+        if not diagnostics["json_complete"]:
+            codes.append("json_incomplete")
+        if diagnostics["schema_issues"]:
+            codes.append("schema_invalid")
+        if (
+            diagnostics["invalid_content_objects"]
+            or not diagnostics["emitted_contents"]
+        ):
+            codes.append("content_invalid")
+    if not codes:
+        return None
+    warning = {"page": page.number, "finish_reason": page.finish_reason, "codes": codes}
+    if diagnostics is not None:
+        warning["diagnostics"] = diagnostics
+    return warning
+
+
+def _adjacent_pairs(chunks):
+    """Yield (2, 3), then (1, 2) for a three-page table-bearing run."""
+    for chunk in chunks:
+        for left in range(chunk[-1] - 1, chunk[0] - 1, -1):
+            yield left, left + 1
+
+
+def _prepare_pair(pages, images, folder, renderer):
+    page_numbers = tuple(page.number for page in pages)
+    document_to_local = {number: local for local, number in enumerate(page_numbers, 1)}
+    paths, markdowns, aliases, rendered_pages = [], [], {}, set()
+    for page in pages:
+        path, markdown = page.image_path, page.markdown
+        if markdown != page.original_markdown:
+            rendered = RenderResult(
+                *renderer.render(
+                    markdown, page.number, images, folder, f"page_{page.number:04d}"
+                )
+            )
+            path, markdown = rendered.image_path, rendered.rewritten_source
+            aliases.update(rendered.alias_to_original)
+            rendered_pages.add(page.number)
+        paths.append(path)
+        markdowns.append(remap(markdown, document_to_local))
+    return PairInput(page_numbers, paths, markdowns, aliases, rendered_pages)
+
+
+def _predict_pair(pair, folder, backend, table_prompt):
+    page_context = "\n\n".join(
+        f'<INPUT_PAGE index="{index}">\n{markdown}\n</INPUT_PAGE>'
+        for index, markdown in enumerate(pair.markdowns, 1)
+    )
+    prompt = table_prompt.removesuffix("\n") + "\n\nInput Markdown:\n\n" + page_context
+    if all(TABLE.search(markdown) for markdown in pair.markdowns):
+        generation = GenerationResult(*backend(pair.image_paths, prompt, folder, 2))
+    else:
+        generation = GenerationResult(
+            json.dumps([{"source_pages": [], "html": NEGATIVE}]), "stop"
+        )
+        save(
+            folder / "gate_skip.json",
+            {"reason": "README table gate", "model_called": False},
+        )
+    (folder / "raw.txt").write_text(generation.text)
+    save(folder / "generation.json", {"finish_reason": generation.finish_reason})
+    if generation.finish_reason != "stop":
+        raise ValueError(
+            f"Stage 2 pair {list(pair.page_numbers)}: finish_reason={generation.finish_reason}"
+        )
+    tables = parse_tables(generation.text)
+    if len(tables) > 1:
+        raise ValueError(
+            "Multiple merges need explicit fragment bindings; output retained."
+        )
+    return [
+        dict(table, html=_restore_image_refs(table["html"], pair)) for table in tables
+    ]
+
+
+def _restore_image_refs(table_html, pair):
+    """Restore document page IDs, then resolve crops from re-rendered pages exactly."""
+    local_to_document = {
+        local: number for local, number in enumerate(pair.page_numbers, 1)
+    }
+    table_html = remap(table_html, local_to_document)
+
+    def restore(match):
+        reference = match[0]
+        if match[1] is None:
+            raise ValueError("Output crop lacks a page number.")
+        if int(match[1]) in pair.rendered_pages:
+            if reference not in pair.alias_to_original:
+                raise ValueError("Unmappable crop from a rendered page: " + reference)
+            return pair.alias_to_original[reference]
+        return reference
+
+    return IMAGE_REF.sub(restore, table_html)
+
+
+def _apply_merge(state, pair, tables):
+    """Validate writeback before updating page contents or fragment provenance."""
+    earlier, later = (state.pages[number - 1] for number in pair.page_numbers)
+    before = (earlier.markdown, later.markdown)
+    after = apply_pair(before, tables)
+    if any(TABLE.sub("", old) != TABLE.sub("", new) for old, new in zip(before, after)):
+        raise ValueError("Writeback changed non-table content.")
+    if tables:
+        sources = earlier.table_sources[-1] | later.table_sources[0]
+        state.merged_tables = [
+            group
+            for group in state.merged_tables
+            if not sources.intersection(map(tuple, group["fragment_ids"]))
+        ]
+        state.merged_tables.append(
+            {
+                "source_pages": sorted({number for number, _ in sources}),
+                "fragment_ids": sorted(sources),
+                "html": tables[0]["html"],
+            }
+        )
+        earlier.table_sources[-1] = sources
+        del later.table_sources[0]
+    earlier.markdown, later.markdown = after
+
+
+def _save_document_crops(markdown, images, output):
+    """Materialize page-qualified references from the original input images."""
+    from PIL import Image
+
+    errors = []
+    references = {}
+    for match in IMAGE_REF.finditer(markdown):
+        references.setdefault(match[1], {})[match[0]] = match.groups()[1:]
+    for page, crops in references.items():
+        try:
+            if page is None or not 1 <= int(page) <= len(images):
+                raise ValueError("Image reference needs a valid source page number")
+            with Image.open(images[int(page) - 1]) as source:
+                for reference, coordinates in crops.items():
+                    try:
+                        left, top, right, bottom = map(int, coordinates)
+                        width, height = source.size
+                        box = (
+                            max(0, min(width, round(left * width / 1000))),
+                            max(0, min(height, round(top * height / 1000))),
+                            max(0, min(width, round(right * width / 1000))),
+                            max(0, min(height, round(bottom * height / 1000))),
+                        )
+                        if box[2] <= box[0] or box[3] <= box[1]:
+                            raise ValueError("Image crop has zero or negative pixel area")
+                        target = output / reference
+                        target.parent.mkdir(parents=True, exist_ok=True)
+                        source.crop(box).convert("RGB").save(target)
+                    except Exception as exc:
+                        errors.append({"reference": reference, "message": str(exc)})
+        except Exception as exc:
+            errors.extend(
+                {"reference": reference, "message": str(exc)} for reference in crops
+            )
+    return errors
+
+
+def _finalize_document(state, images, output, error):
+    document = "\n\n".join(page.markdown for page in state.pages) + "\n"
+    crop_errors = _save_document_crops(document, images, output)
+    for page in state.pages:
+        target = output / "pages" / f"page_{page.number:04d}.md"
+        target.parent.mkdir(exist_ok=True)
+        # Per-page Markdown is one directory below the shared crop assets.
+        target.write_text(IMAGE_REF.sub(lambda m: "../" + m[0], page.markdown))
+    (output / "document.md").write_text(document)
+    if crop_errors and error is None:
+        error = {"type": "ImageCropExportFailed", "recoverable": False}
+        save(output / "failure.json", {**error, "image_export_errors": crop_errors})
+    if error is None and state.parse_warnings:
+        error = {
+            "type": "Stage1OutputIncomplete",
+            "recoverable": True,
+            "pages": [warning["page"] for warning in state.parse_warnings],
+        }
+    result = {
+        "status": "COMPLETE" if error is None else "PARTIAL",
+        "error": error,
+        "input_pages": len(images),
+        "parsed_pages": len(state.pages),
+        "chunks": state.chunks,
+        "steps": state.steps,
+        "merged_tables": state.merged_tables,
+        "stage1_parse_warnings": state.parse_warnings,
+        "image_export_errors": crop_errors,
+    }
+    save(output / "result.json", result)
+    return result
+
+
+# Reusable text adapters and table operations (standard library only).
+
+
+def _document_images(image_paths):
+    images = [str(Path(path).resolve()) for path in image_paths]
+    if not images or not all(Path(path).is_file() for path in images):
+        raise ValueError("Provide existing page images in reading order.")
+    return images
+
+
+def save(path, value):
+    """Write a JSON artifact, creating its parent directory when needed."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n")
+
+
+def _is_valid_bbox(value):
+    if not isinstance(value, list) or len(value) != 4:
+        return False
+    if not all(type(coordinate) is int for coordinate in value):
+        return False
+    left, top, right, bottom = value
+    return 0 <= left <= right < 1000 and 0 <= top <= bottom < 1000
+
+
+def _recover_json_prefix(text):
+    """Return only complete prefix objects; never guess or repair JSON syntax."""
+    blocks, unparsed_tail_chars = [], 0
+    if not text.startswith("["):
+        return blocks, unparsed_tail_chars
+    position = 1
+    decoder = json.JSONDecoder()
+    while position < len(text):
+        while position < len(text) and text[position].isspace():
+            position += 1
+        if position == len(text) or text[position] == "]":
+            break
+        try:
+            block, end = decoder.raw_decode(text, position)
+        except json.JSONDecodeError:
+            unparsed_tail_chars = len(text) - position
+            break
+        blocks.append(block)
+        position = end
+        while position < len(text) and text[position].isspace():
+            position += 1
+        if position < len(text) and text[position] == ",":
+            position += 1
+        elif position < len(text) and text[position] != "]":
+            unparsed_tail_chars = len(text) - position
+            break
+    return blocks, unparsed_tail_chars
+
+
+def structured_to_markdown(text):
+    """Project content in emitted order, retaining diagnostics for incomplete JSON.
+
+    Preserve every category and keep only complete prefix objects on JSON failure.
+    Invalid bbox/category fields are reported without discarding valid content.
+    """
+    stripped = text.strip()
+    if stripped.startswith("```") and stripped.endswith("```"):
+        stripped = re.sub(r"^```(?:json)?\s*\n|\n```$", "", stripped, flags=re.I)
+    diagnostics = {
+        "json_complete": False,
+        "schema_issues": [],
+        "invalid_content_objects": [],
+        "unparsed_tail_chars": 0,
+    }
+    try:
+        blocks = json.loads(stripped)
+        if not isinstance(blocks, list):
+            raise ValueError("Expected one JSON array")
+        diagnostics["json_complete"] = True
+    except ValueError as exc:
+        diagnostics["parse_error"] = str(exc)
+        blocks, diagnostics["unparsed_tail_chars"] = _recover_json_prefix(stripped)
+
+    contents = []
+    for index, block in enumerate(blocks):
+        if not isinstance(block, dict) or not isinstance(block.get("content"), str):
+            diagnostics["invalid_content_objects"].append(index)
+            continue
+        contents.append(block["content"])
+        if not _is_valid_bbox(block.get("bbox")):
+            diagnostics["schema_issues"].append({"index": index, "field": "bbox"})
+        if (
+            not isinstance(block.get("category"), str)
+            or block["category"] not in CATEGORIES
+        ):
+            diagnostics["schema_issues"].append({"index": index, "field": "category"})
+    diagnostics.update(
+        parsed_objects=len(blocks),
+        emitted_contents=len(contents),
+        policy="join content in emitted array order; preserve every category; retain complete prefix objects only",
+    )
+    diagnostics["valid"] = (
+        diagnostics["json_complete"]
+        and not diagnostics["schema_issues"]
+        and not diagnostics["invalid_content_objects"]
+        and bool(contents)
+    )
+    return "\n\n".join(contents), blocks, diagnostics
+
+
+def _clean_truncated_repeats(
+    text: str,
+    min_text_len: int = 8000,
+    max_period: int = 200,
+    min_period: int = 1,
+    min_repeat_chars: int = 100,
+    min_repeat_times: int = 5,
+) -> str:
+    n = len(text)
+    if n < min_text_len:
+        return text
+
+    max_period = min(max_period, n - 1)
+    for unit_len in range(min_period, max_period + 1):
+        if text[n - 1] != text[n - 1 - unit_len]:
+            continue
+
+        match_len = 1
+        idx = n - 2
+        while idx >= unit_len and text[idx] == text[idx - unit_len]:
+            match_len += 1
+            idx -= 1
+
+        total_len = match_len + unit_len
+        repeat_times = total_len // unit_len
+        tail_len = total_len % unit_len
+
+        if repeat_times >= min_repeat_times and total_len >= min_repeat_chars:
+            return text[: n - total_len + unit_len] + text[n - tail_len :]
+
+    return text
+
+
+def parse_tables(raw: str) -> list[dict]:
+    """Return all positive objects or [] for the exact negative sentinel."""
+    items = json.loads(raw)
+    if not isinstance(items, list) or not items:
+        raise ValueError("Expected a nonempty JSON array.")
+    for item in items:
+        if not isinstance(item, dict) or set(item) != {"source_pages", "html"}:
+            raise ValueError("Each object needs exactly source_pages and html.")
+        if not isinstance(item["source_pages"], list) or not isinstance(
+            item["html"], str
+        ):
+            raise ValueError("Invalid field types.")
+        if not item["source_pages"]:
+            if len(items) == 1 and item["html"] == NEGATIVE:
+                return []
+            raise ValueError("Invalid or mixed negative sentinel.")
+        if item["source_pages"] != [1, 2] or any(
+            type(p) is not int for p in item["source_pages"]
+        ):
+            raise ValueError("A positive two-page result must use [1, 2].")
+        if not TABLE.fullmatch(item["html"].strip()):
+            raise ValueError("Expected complete HTML table output.")
+    return items
+
+
+def apply_pair(
+    markdowns: tuple[str, str],
+    tables: list[dict],
+    bindings: list[tuple[int, int]] | None = None,
+) -> tuple[str, str]:
+    """Replace page 1's last table and remove page 2's first table by default.
+
+    Multiple merged tables require explicit zero-based fragment bindings.
+    Nested or incomplete HTML tables are rejected; non-table source is retained.
+    """
+    if len(markdowns) != 2:
+        raise ValueError("Need exactly two pages.")
+    spans = [list(TABLE.finditer(md)) for md in markdowns]
+    if bindings is None:
+        if not tables:
+            return tuple(markdowns)
+        if len(tables) != 1:
+            raise ValueError("Multiple merged tables require explicit source bindings.")
+        bindings = [(len(spans[0]) - 1, 0)]
+    if len(tables) != len(bindings):
+        raise ValueError("Need one explicit binding per merged table.")
+    for md, matches in zip(markdowns, spans):
+        if len(re.findall(r"<table\b", md, re.I)) != len(matches) or len(
+            re.findall(r"</table\s*>", md, re.I)
+        ) != len(matches):
+            raise ValueError(
+                "Nested or incomplete tables require a layout-aware editor."
+            )
+    edits = [{}, {}]
+    for item, binding in zip(tables, bindings):
+        parse_tables(json.dumps([item]))
+        if len(re.findall(r"<table\b", item["html"], re.I)) != 1:
+            raise ValueError(
+                "Nested or multiple tables cannot be written into one fragment."
+            )
+        if item["source_pages"] != [1, 2] or len(binding) != 2:
+            raise ValueError("Only positive two-page tables can be written back.")
+        for page, index in enumerate(binding):
+            if type(index) is not int or not 0 <= index < len(spans[page]):
+                raise ValueError("Source table index out of range.")
+            if index in edits[page]:
+                raise ValueError("Two results claim the same source fragment.")
+            edits[page][index] = item["html"] if page == 0 else ""
+    output = []
+    for page, md in enumerate(markdowns):
+        for index in sorted(edits[page], reverse=True):
+            span = spans[page][index]
+            md = md[: span.start()] + edits[page][index] + md[span.end() :]
+        output.append(md)
+    return tuple(output)
+
+
+def find_chunks(pages):
+    """Maximal runs of >=2 pages with predicted HTML tables; 1-based IDs."""
+    chunks, run = [], []
+    for page, markdown in enumerate(pages, 1):
+        if TABLE.search(markdown):
+            run.append(page)
+        else:
+            if len(run) >= 2:
+                chunks.append(run)
+            run = []
+    if len(run) >= 2:
+        chunks.append(run)
+    return chunks
+
+
+def remap(markdown: str, mapping: Mapping[int, int]) -> str:
+    def replace(match):
+        page = int(match[1])
+        if page not in mapping:
+            raise ValueError(f"Image page {page} is outside the current pair.")
+        return f"page_{mapping[page]}/images/"
+
+    return REF.sub(replace, markdown)
+
+
+def page_markdown(raw, page):
+    """Accept Markdown, optionally fenced; qualify page-local crop references."""
+    markdown = re.sub(
+        r"^```(?:markdown|html)?\s*\n|\n```\s*$", "", raw.strip(), flags=re.I
+    )
+    if not markdown:
+        raise ValueError("Empty Stage 1 Markdown.")
+    # Each Stage 1 call contains one image, so crop IDs refer to this page.
+    return IMAGE_REF.sub(
+        lambda m: f"page_{page}/images/bbox_" + "_".join(m.groups()[1:]) + ".jpg",
+        markdown,
+    )
+
+
+# Model inference and lazy browser lifecycle.
+
+
+class VllmBackend:
+    """Keep engine, sampling and request settings aligned with README infer().
+
+    Benchmark-specific scheduling overrides do not belong in this backend.
+    """
+
+    def __init__(self, model_path):
+        from vllm import LLM, SamplingParams
+
+        self.model = LLM(
+            model=str(Path(model_path).resolve()),
+            tensor_parallel_size=1,
+            gpu_memory_utilization=0.8,
+            gdn_prefill_backend="triton",
+            limit_mm_per_prompt={"image": 2},
+        )
+        self.tokenizer = self.model.get_tokenizer()
+        self.sampling = SamplingParams(max_tokens=16384, temperature=0.0)
+
+    def __call__(self, paths, task_prompt, folder, stage):
+        from PIL import Image
+
+        images = []
+        for path in paths:
+            with Image.open(path) as image:
+                images.append(image.convert("RGB"))
+        content = [{"type": "image"} for _ in images]
+        content.append({"type": "text", "text": task_prompt})
+        prompt = self.tokenizer.apply_chat_template(
+            [{"role": "user", "content": content}],
+            tokenize=False,
+            add_generation_prompt=True,
+            enable_thinking=False,
+        )
+        request = {
+            "prompt": prompt,
+            "multi_modal_data": {"image": images},
+            "mm_processor_kwargs": {
+                "images_kwargs": {
+                    "min_pixels": 448 * 448,
+                    "max_pixels": 2880 * 2880,
+                }
+            },
+        }
+        save(
+            folder / "input.json",
+            {
+                "stage": stage,
+                "images": list(paths),
+                "prompt": prompt,
+                "mm_processor_kwargs": request["mm_processor_kwargs"],
+            },
+        )
+        output = self.model.generate([request], self.sampling)[0].outputs[0]
+        return GenerationResult(output.text, output.finish_reason)
+
+
+class _BrowserRenderer:
+    def __init__(self, mathjax):
+        self.mathjax = mathjax
+        self.playwright = self.browser = self.renderer = None
+
+    def render(self, *args):
+        if self.renderer is None:
+            from playwright.sync_api import sync_playwright
+
+            self.playwright = sync_playwright().start()
+            self.browser = self.playwright.chromium.launch(headless=True)
+            self.renderer = Renderer(self.browser, self.mathjax)
+        return self.renderer.render(*args)
+
+    def close(self):
+        if self.browser:
+            self.browser.close()
+        if self.playwright:
+            self.playwright.stop()
+
+
+# Content-preserving Markdown/HTML rendering.
+
+
+CROP = re.compile(r"page_(\d+)/images/bbox_(\d+)_(\d+)_(\d+)_(\d+)\.jpg")
+_CROP_ASSET = re.compile(
+    r"(?:page_(\d+)/)?images/(?:bbox_)?(\d+)_(\d+)_(\d+)_(\d+)\.(?:jpg|jpeg|png)", re.I
+)
+_TAG = re.compile(
+    r"<!--.*?-->|</?[A-Za-z][\w:-]*(?:[^>\'\"]|\"[^\"]*\"|\'[^\']*\')*>", re.S
+)
+_SRC = re.compile(r"""(?<![\w:-])src\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))""", re.I)
+_ALLOWED = set(
+    "p div span br hr h1 h2 h3 h4 h5 h6 table thead tbody tfoot tr td th caption colgroup col ul ol li dl dt dd blockquote pre code b strong em i u s del sup sub a img figure figcaption section article main center font".split()
+)
+_DROP = set("script style iframe object embed link meta base template".split())
+_CSS = """
+html,body{margin:0;padding:0;background:#fff;color:#111}
+#capture{padding:28px;box-sizing:border-box;font-family:Arial,'Noto Sans CJK SC',sans-serif;font-size:18px;line-height:1.4}
+table{border-collapse:collapse;width:100%;margin:12px 0}td,th{border:1px solid #666;padding:5px;vertical-align:top;overflow-wrap:anywhere}
+img{max-width:100%;height:auto}h1{font-size:28px}h2{font-size:24px}h3{font-size:21px}p{margin:10px 0}
+pre{white-space:pre-wrap;overflow-wrap:anywhere;font:inherit}code{font-family:monospace;white-space:pre-wrap;overflow-wrap:anywhere}
+.math-display{display:block;text-align:center;margin:10px 0}.math-inline{display:inline-block;vertical-align:middle}.math-fallback{white-space:pre-wrap;overflow-wrap:anywhere}
+mjx-container{max-width:none}svg{overflow:visible}th{font-weight:600}
+"""
+
+
+@dataclass(frozen=True)
+class RenderLimits:
+    """Configurable engineering limits, not validated OCR accuracy thresholds."""
+
+    max_side: int = 32768
+    max_render_pixels: int = 64_000_000
+    max_source_chars: int = 4_000_000
+    min_effective_font_px: float = 12.0
+    min_effective_cell_height_px: float = 8.0
+    timeout_ms: int = 30000
+
+    def __post_init__(self):
+        for name, value in asdict(self).items():
+            if not math.isfinite(value) or value <= 0:
+                raise ValueError(name + " must be finite and positive")
+
+
+class RenderError(ValueError):
+    """Concise caller-facing error; details remain in the render.json sidecar."""
+
+    def __init__(self, code, message):
+        self.code = code
+        super().__init__(message)
+
+
+def _escaped(text, pos):
+    start = pos
+    while start and text[start - 1] == "\\":
+        start -= 1
+    return (pos - start) % 2 == 1
+
+
+def _dollar_is_math(body, mode):
+    if mode == "all":
+        return True
+    if mode == "off" or not body or body != body.strip():
+        return False
+    if re.search(r"\\[A-Za-z]+", body):
+        return True
+    # Pure numbers and prose are ambiguous; preserve them, rather than invent math.
+    if re.fullmatch(r"[A-Za-z]", body):
+        return True
+    if re.search(r"[^\x00-\x7f]", body):
+        return bool(
+            re.fullmatch(r"[\w\s\d.,_^=+*/<>{}()−-]+", body)
+            and re.search(r"[_^=+*/<>−-]", body)
+        )
+    if re.fullmatch(r"\d+(?:\.\d+)?\\[,;!: ](?:[A-Za-z]+)", body):
+        return True
+    words = re.findall(r"[A-Za-z]+", body)
+    if any(
+        len(w) > 1
+        and w not in {"sin", "cos", "tan", "log", "ln", "exp", "max", "min", "lim"}
+        for w in words
+    ):
+        return False
+    return bool(re.search(r"[_^=+*/<>{}]", body) or re.search(r"\w\s*-\s*\w", body))
+
+
+def _markdown_image(text, pos, parser, env):
+    from markdown_it.common.utils import normalizeReference
+    from markdown_it.helpers import parseLinkDestination, parseLinkLabel, parseLinkTitle
+    from markdown_it.rules_inline.state_inline import StateInline
+
+    state = StateInline(text, parser, env, [])
+    end_label = parseLinkLabel(state, pos + 1, False)
+    if end_label < 0:
+        return None
+    alt = text[pos + 2 : end_label]
+    cursor = end_label + 1
+    title = ""
+    if cursor < len(text) and text[cursor] == "(":
+        cursor += 1
+        while cursor < len(text) and text[cursor].isspace():
+            cursor += 1
+        dest = parseLinkDestination(text, cursor, len(text))
+        if not dest.ok:
+            return None
+        ref, cursor = dest.str, dest.pos
+        spaces = cursor
+        while cursor < len(text) and text[cursor].isspace():
+            cursor += 1
+        if cursor > spaces:
+            parsed_title = parseLinkTitle(text, cursor, len(text))
+            if parsed_title.ok:
+                title, cursor = parsed_title.str, parsed_title.pos
+                while cursor < len(text) and text[cursor].isspace():
+                    cursor += 1
+        if cursor >= len(text) or text[cursor] != ")":
+            return None
+        end = cursor + 1
+    else:
+        label, end = alt, cursor
+        if cursor < len(text) and text[cursor] == "[":
+            close = text.find("]", cursor + 1)
+            if close < 0:
+                return None
+            label = text[cursor + 1 : close] or alt
+            end = close + 1
+        definition = env.get("references", {}).get(normalizeReference(label))
+        if not definition:
+            return None
+        ref, title = definition["href"], definition.get("title", "")
+    return end, ref, alt, title
+
+
+def _image_markup(item, ref):
+    if item["kind"] == "html":
+        return html.escape(ref, quote=True)
+    title = (
+        (' "' + item["title"].replace("\\", "\\\\").replace('"', '\\"') + '"')
+        if item["title"]
+        else ""
+    )
+    return "![" + item["alt"] + "](<" + ref + ">" + title + ")"
+
+
+def _edit_source(text, edits):
+    out, previous = [], 0
+    for start, end, value in sorted(edits):
+        if start < previous:
+            raise RenderError(
+                "overlapping_source_spans",
+                "Cannot safely map overlapping source elements.",
+            )
+        out.extend([text[previous:start], value])
+        previous = end
+    out.append(text[previous:])
+    return "".join(out)
+
+
+def prepare_source(source, parser, dollar_math="auto", html_document=False):
+    """Protect math before CommonMark and identify each actual image occurrence.
+
+    Code fences, indented code, inline code, HTML attributes and comments remain
+    literal. Markdown image references are expanded per occurrence, not per URL.
+    """
+    from markdown_it.helpers import parseLinkDestination, parseLinkTitle
+
+    prefix = "RDR" + uuid.uuid4().hex.upper()
+    env = {}
+    tokens = [] if html_document else parser.parse(source, env)
+    offsets = [0]
+    for line in source.splitlines(keepends=True):
+        offsets.append(offsets[-1] + len(line))
+    literal = {
+        offsets[t.map[0]]: offsets[min(t.map[1], len(offsets) - 1)]
+        for t in tokens
+        if t.type in {"fence", "code_block"} and t.map
+    }
+    for definition in env.get("references", {}).values():
+        if definition.get("map"):
+            a, b = definition["map"]
+            literal[offsets[a]] = offsets[min(b, len(offsets) - 1)]
+    formulas, images, edits, notes = [], [], [], []
+    i = 0
+    while i < len(source):
+        if i in literal:
+            i = literal[i]
+            continue
+        if source[i] == "`" and not _escaped(source, i):
+            run = re.match(r"`+", source[i:])[0]
+            close = re.search(
+                r"(?<!`)" + re.escape(run) + r"(?!`)", source[i + len(run) :]
+            )
+            if close:
+                i += len(run) + close.end()
+                continue
+        if source.startswith("](", i):
+            # Markdown link destinations are not mathematical prose.
+            dest = parseLinkDestination(source, i + 2, len(source))
+            if dest.ok:
+                cursor = dest.pos
+                while cursor < len(source) and source[cursor].isspace():
+                    cursor += 1
+                title = parseLinkTitle(source, cursor, len(source))
+                if title.ok:
+                    cursor = title.pos
+                    while cursor < len(source) and source[cursor].isspace():
+                        cursor += 1
+                if cursor < len(source) and source[cursor] == ")":
+                    i = cursor + 1
+                    continue
+        if source[i] == "<":
+            tag = _TAG.match(source, i)
+            if tag:
+                raw = tag[0]
+                kind = re.match(r"<([A-Za-z][\w:-]*)", raw)
+                kind = kind[1].lower() if kind else ""
+                if kind in _DROP | {"code"}:
+                    close = re.search(
+                        r"</" + re.escape(kind) + r"\s*>", source[tag.end() :], re.I
+                    )
+                    if close:
+                        i = tag.end() + close.end()
+                        continue
+                if kind == "img":
+                    src = _SRC.search(raw)
+                    if src:
+                        group = next(j for j in (1, 2, 3) if src[j] is not None)
+                        start, end = i + src.start(group), i + src.end(group)
+                        item = dict(
+                            start=start,
+                            end=end,
+                            ref=html.unescape(src[group]),
+                            kind="html",
+                            token=prefix + "IMG" + str(len(images)),
+                        )
+                        images.append(item)
+                        edits.append((start, end, item["token"]))
+                i = tag.end()
+                continue
+        if source.startswith("![", i) and not _escaped(source, i):
+            found = _markdown_image(source, i, parser, env)
+            if found:
+                end, ref, alt, title = found
+                item = dict(
+                    start=i,
+                    end=end,
+                    ref=ref,
+                    alt=alt,
+                    title=title,
+                    kind="markdown",
+                    token=prefix + "IMG" + str(len(images)),
+                )
+                images.append(item)
+                edits.append((i, end, _image_markup(item, item["token"])))
+                i = end
+                continue
+        opening = next(
+            (s for s in ("\\(", "\\[", "$$", "$") if source.startswith(s, i)), None
+        )
+        if opening and not _escaped(source, i):
+            closing = {"\\(": "\\)", "\\[": "\\]", "$$": "$$", "$": "$"}[opening]
+            pos = i + len(opening)
+            while True:
+                end = source.find(closing, pos)
+                if end < 0:
+                    break
+                if not _escaped(source, end):
+                    break
+                pos = end + len(closing)
+            # Delimiters may not consume table cells or block boundaries.
+            # An explicit unclosed formula remains visible in its own cell.
+            boundary = re.search(
+                r"</?(?:table|thead|tbody|tfoot|tr|td|th|div|p|h[1-6]|li|ul|ol|pre|blockquote)\b[^>]*>|<br\b[^>]*>",
+                source[pos:],
+                re.I,
+            )
+            if boundary and end >= 0 and pos + boundary.start() < end:
+                notes.append({"code": "formula_block_boundary", "offset": i})
+                end = -1
+            if end >= 0:
+                body = source[i + len(opening) : end]
+                allowed = True
+                if opening == "$":
+                    allowed = (
+                        "\n" not in body
+                        and not source.startswith("$$", end)
+                        and _dollar_is_math(body, dollar_math)
+                    )
+                    if not allowed:
+                        notes.append(
+                            {"code": "literal_or_ambiguous_dollar", "offset": i}
+                        )
+                elif "\n\n" in body and opening == "\\(":
+                    allowed = False
+                if allowed:
+                    token = prefix + "MATH" + str(len(formulas)) + "X"
+                    formulas.append(
+                        dict(
+                            token=token,
+                            tex=html.unescape(body),
+                            raw=source[i : end + len(closing)],
+                            display=opening in {"\\[", "$$"},
+                        )
+                    )
+                    edits.append((i, end + len(closing), token))
+                    i = end + len(closing)
+                    continue
+            elif opening != "$":
+                # Preserve malformed explicit notation visibly, even through Markdown.
+                stop = source.find("\n\n", i)
+                stop = len(source) if stop < 0 else stop
+                tag_boundary = _TAG.search(source, i + len(opening))
+                if tag_boundary:
+                    stop = min(stop, tag_boundary.start())
+                token = prefix + "MATH" + str(len(formulas)) + "X"
+                formulas.append(
+                    dict(
+                        token=token,
+                        tex="",
+                        raw=source[i:stop],
+                        display=False,
+                        malformed=True,
+                    )
+                )
+                edits.append((i, stop, token))
+                i = stop
+                continue
+            # Consume an unrecognized delimiter as a unit (do not reinterpret $$ as $).
+            i += len(opening)
+            continue
+        i += 1
+    return _edit_source(source, edits), formulas, images, notes
+
+
+def sanitize(soup):
+    from bs4 import Comment
+
+    removed = 0
+    for node in list(soup.find_all(string=lambda t: isinstance(t, Comment))):
+        node.extract()
+    for tag in list(soup.find_all(True)):
+        if tag.name is None:
+            continue
+        if tag.name in {"svg", "canvas", "math", "video", "audio"}:
+            raise RenderError(
+                "unsupported_embedded_media",
+                "Embedded media needs an explicit image asset; source retained.",
+            )
+        if tag.name in _DROP:
+            tag.decompose()
+            removed += 1
+            continue
+        if tag.name not in _ALLOWED:
+            tag.unwrap()
+            removed += 1
+            continue
+        attrs = {}
+        if tag.name in {"td", "th", "col", "colgroup"}:
+            for key in ("rowspan", "colspan", "span"):
+                if key in tag.attrs:
+                    value = str(tag[key])
+                    if not value.isdecimal() or not (
+                        0 if key == "rowspan" else 1
+                    ) <= int(value) <= (65534 if key == "rowspan" else 1000):
+                        raise RenderError(
+                            "invalid_table_span",
+                            "Invalid table cell span; source retained.",
+                        )
+                    attrs[key] = value
+        if tag.name == "img":
+            attrs.update({k: tag[k] for k in ("src", "alt", "title") if k in tag.attrs})
+        if tag.name == "ol" and str(tag.get("start", "")).lstrip("-").isdigit():
+            attrs["start"] = tag["start"]
+        # Retain safe alignment, but no CSS that can hide, move, clip or fetch.
+        declarations = dict(
+            (k.strip().lower(), v.strip().lower())
+            for k, v in re.findall(r"([\w-]+)\s*:\s*([^;]+)", str(tag.get("style", "")))
+        )
+        align = declarations.get("text-align", str(tag.get("align", "")).lower())
+        valign = declarations.get("vertical-align", str(tag.get("valign", "")).lower())
+        style = []
+        if align in {"left", "right", "center", "justify"}:
+            style.append("text-align:" + align)
+        if valign in {"top", "middle", "bottom", "baseline"}:
+            style.append("vertical-align:" + valign)
+        if style:
+            attrs["style"] = ";".join(style)
+        if dict(tag.attrs) != attrs:
+            removed += 1
+        tag.attrs = attrs
+    return removed
+
+
+def _png_data(image):
+    from PIL import Image
+
+    image = image.convert("RGBA")
+    background = Image.new("RGBA", image.size, "white")
+    background.alpha_composite(image)
+    buf = io.BytesIO()
+    background.convert("RGB").save(buf, format="PNG")
+    return "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode("ascii")
+
+
+def resolve_alias(ref, aliases, *, tolerance=2, min_iou=0.98, events=None):
+    """Exact first; a small coordinate jitter must match one unique occurrence.
+
+    This is a configurable rounding tolerance, not semantic figure localization.
+    An ambiguous or newly predicted region is never assigned to the nearest image.
+    """
+    if ref in aliases:
+        return aliases[ref]
+    target = CROP.fullmatch(ref)
+    if not target:
+        raise RenderError("unmapped_crop", "Cannot map an image region to its source.")
+    page, *box = map(int, target.groups())
+    candidates = []
+    for key in aliases:
+        m = CROP.fullmatch(key)
+        if not m or int(m[1]) != page:
+            continue
+        other = list(map(int, m.groups()[1:]))
+        if max(abs(a - b) for a, b in zip(box, other)) > tolerance:
+            continue
+        intersection = max(0, min(box[2], other[2]) - max(box[0], other[0])) * max(
+            0, min(box[3], other[3]) - max(box[1], other[1])
+        )
+        area = max(0, box[2] - box[0]) * max(0, box[3] - box[1])
+        area2 = max(0, other[2] - other[0]) * max(0, other[3] - other[1])
+        union = area + area2 - intersection
+        if union and intersection / union >= min_iou:
+            candidates.append(key)
+    if len(candidates) != 1:
+        raise RenderError(
+            "ambiguous_crop" if candidates else "unmapped_crop",
+            "Cannot uniquely map an image region to its source.",
+        )
+    if events is not None:
+        events.append(
+            {
+                "code": "coordinate_rounding_match",
+                "predicted": ref,
+                "matched": candidates[0],
+            }
+        )
+    return aliases[candidates[0]]
+
+
+class Renderer:
+    def __init__(
+        self,
+        browser,
+        mathjax,
+        *,
+        limits=None,
+        dollar_math="auto",
+        assets=None,
+        asset_root=None,
+        resize=None,
+        resize_name=None,
+        max_input_pixels=None,
+    ):
+        from markdown_it import MarkdownIt
+
+        if dollar_math not in {"auto", "all", "off"}:
+            raise ValueError("dollar_math must be auto, all or off")
+        self.mathjax = Path(mathjax).resolve()
+        self.limits = limits or RenderLimits()
+        self.dollar_math = dollar_math
+        self.assets = dict(assets or {})
+        self.asset_root = Path(asset_root).resolve() if asset_root else None
+        self.resize = resize
+        self.resize_name = resize_name or (
+            "custom"
+            if resize
+            else "area_budget_estimate" if max_input_pixels else "unknown"
+        )
+        if max_input_pixels is not None and max_input_pixels <= 0:
+            raise ValueError("max_input_pixels must be positive")
+        self.max_input_pixels = max_input_pixels
+        self.page = browser.new_page(
+            viewport={"width": 1200, "height": 900}, device_scale_factor=1
+        )
+        self.page.set_default_timeout(self.limits.timeout_ms)
+        # No external assets, CSS or network dependencies in model-supplied HTML.
+        self.page.route("**/*", lambda route: route.abort())
+        self.md = MarkdownIt("commonmark", {"html": True}).enable(
+            ["table", "strikethrough"]
+        )
+
+    def _asset(self, ref, owner, paths):
+        from PIL import Image
+
+        crop = _CROP_ASSET.fullmatch(ref)
+        if crop:
+            page, left, top, right, bottom = crop.groups()
+            page = int(page) if page else owner
+            left, top, right, bottom = map(int, (left, top, right, bottom))
+            if (
+                not 1 <= page <= len(paths)
+                or not 0 <= left < right <= 1000
+                or not 0 <= top < bottom <= 1000
+            ):
+                raise RenderError(
+                    "invalid_crop",
+                    "An image crop has invalid coordinates; source retained.",
+                )
+            with Image.open(paths[page - 1]) as im:
+                box = (
+                    round(left * im.width / 1000),
+                    round(top * im.height / 1000),
+                    round(right * im.width / 1000),
+                    round(bottom * im.height / 1000),
+                )
+                if box[0] >= box[2] or box[1] >= box[3]:
+                    raise RenderError(
+                        "empty_crop", "An image crop is smaller than one pixel."
+                    )
+                if (box[2] - box[0]) * (
+                    box[3] - box[1]
+                ) > self.limits.max_render_pixels:
+                    raise RenderError(
+                        "asset_limit",
+                        "An image asset exceeds the rendering pixel budget.",
+                    )
+                return _png_data(im.crop(box))
+        if ref.startswith("data:"):
+            header, sep, payload = ref.partition(",")
+            if not sep or not re.fullmatch(
+                r"data:image/(?:png|jpeg|webp|gif);base64", header, re.I
+            ):
+                raise RenderError(
+                    "unsupported_asset",
+                    "An image format is unsupported; source retained.",
+                )
+            with Image.open(io.BytesIO(base64.b64decode(payload, validate=True))) as im:
+                if im.width * im.height > self.limits.max_render_pixels:
+                    raise RenderError(
+                        "asset_limit",
+                        "An image asset exceeds the rendering pixel budget.",
+                    )
+                return _png_data(im)
+        path = self.assets.get(ref)
+        if path is None and self.asset_root:
+            from urllib.parse import unquote, urlsplit
+
+            if not urlsplit(ref).scheme and not ref.startswith("//"):
+                candidate = (self.asset_root / unquote(ref)).resolve()
+                if candidate.is_relative_to(self.asset_root):
+                    path = candidate
+        if path is None:
+            raise RenderError(
+                "unresolved_asset",
+                "An image needs a local asset mapping; source retained.",
+            )
+        with Image.open(path) as im:
+            if im.width * im.height > self.limits.max_render_pixels:
+                raise RenderError(
+                    "asset_limit", "An image asset exceeds the rendering pixel budget."
+                )
+            return _png_data(im)
+
+    def render(self, md, owner, paths, directory, name):
+        directory = Path(directory)
+        directory.mkdir(parents=True, exist_ok=True)
+        if Path(name).name != name or not name:
+            raise ValueError("name must be a filename stem")
+        started = time.monotonic()
+        diag = {
+            "version": 2,
+            "status": "ERROR",
+            "math": 0,
+            "errors": 0,
+            "broken": 0,
+            "images": [],
+            "notes": [],
+            "limits": asdict(self.limits),
+            "resize_policy": self.resize_name,
+        }
+        (directory / (name + ".source.md")).write_text(md)
+        try:
+            result = self._render(md, owner, paths, directory, name, diag)
+            diag["status"] = "DEGRADED" if diag.get("formula_fallbacks") else "COMPLETE"
+            return result
+        except Exception as exc:
+            diag["error"] = {
+                "code": getattr(exc, "code", "render_failed"),
+                "type": type(exc).__name__,
+                "message": str(exc)[:1000],
+            }
+            if isinstance(exc, RenderError):
+                raise
+            raise RenderError(
+                "render_failed",
+                "Page rendering failed; source and diagnostics were retained.",
+            ) from exc
+        finally:
+            diag["seconds"] = time.monotonic() - started
+            save(directory / (name + ".render.json"), diag)
+
+    def _render(self, md, owner, paths, directory, name, diag):
+        from bs4 import BeautifulSoup, Comment, NavigableString
+        from PIL import Image
+
+        if not 1 <= owner <= len(paths):
+            raise RenderError("invalid_owner", "Page index is outside the document.")
+        if len(md) > self.limits.max_source_chars:
+            raise RenderError(
+                "source_limit", "Page source exceeds the configured rendering limit."
+            )
+        probe = (
+            BeautifulSoup(md, "html.parser") if md.lstrip().startswith("<") else None
+        )
+        html_document = bool(
+            probe is not None
+            and probe.find(True)
+            and all(
+                not isinstance(x, NavigableString)
+                or isinstance(x, Comment)
+                or not str(x).strip()
+                for x in probe.contents
+            )
+        )
+        prepared, formulas, occurrences, notes = prepare_source(
+            md, self.md, self.dollar_math, html_document
+        )
+        diag["input_format"] = "html" if html_document else "markdown"
+        diag["notes"].extend(notes)
+        soup = BeautifulSoup(
+            prepared if html_document else self.md.render(prepared), "html.parser"
+        )
+        diag["sanitized_elements"] = sanitize(soup)
+        by_token = {x["token"]: x for x in occurrences}
+        seen = set()
+        for image in soup.find_all("img"):
+            key = image.get("src", "")
+            if key not in by_token or key in seen:
+                raise RenderError(
+                    "image_mapping", "Cannot safely map image occurrences."
+                )
+            seen.add(key)
+            item = by_token[key]
+            image["src"] = self._asset(item["ref"], owner, paths)
+            image["data-image-id"] = key
+        if len(seen) != len(occurrences):
+            raise RenderError(
+                "image_mapping", "An image occurrence was lost during parsing."
+            )
+        by_math = {x["token"]: x for x in formulas}
+        if by_math:
+            pattern = re.compile(
+                "|".join(map(re.escape, sorted(by_math, key=len, reverse=True)))
+            )
+            found = []
+            for node in list(soup.find_all(string=pattern)):
+                if isinstance(node, Comment):
+                    continue
+                pieces = pattern.split(str(node))
+                matches = list(pattern.finditer(str(node)))
+                for k, part in enumerate(pieces):
+                    if part:
+                        node.insert_before(NavigableString(part))
+                    if k < len(matches):
+                        item = by_math[matches[k][0]]
+                        found.append(item["token"])
+                        tag = soup.new_tag("span")
+                        tag["data-math-id"] = item["token"]
+                        tag["class"] = (
+                            "math-display" if item["display"] else "math-inline"
+                        )
+                        tag.string = item["raw"]
+                        node.insert_before(tag)
+                node.extract()
+            if sorted(found) != sorted(by_math):
+                raise RenderError(
+                    "formula_mapping", "A formula was lost during parsing."
+                )
+        tables = soup.find_all("table")
+        expected_cells = len(soup.find_all(["td", "th"]))
+        columns = max(
+            (
+                sum(
+                    int(c.get("colspan", 1))
+                    for c in row.find_all(["td", "th"], recursive=False)
+                )
+                for row in soup.find_all("tr")
+            ),
+            default=1,
+        )
+        with Image.open(paths[owner - 1]) as original:
+            width = max(original.width, columns * 120 + 56)
+        document = (
+            '<!doctype html><html><head><meta charset="utf-8"><style>'
+            + _CSS
+            + '</style></head><body><div id="capture" style="width:'
+            + str(width)
+            + 'px">'
+            + str(soup)
+            + "</div></body></html>"
+        )
+        # Persist complete render input before any resource/readability rejection.
+        (directory / (name + ".html")).write_text(document)
+        if width > self.limits.max_side:
+            raise RenderError(
+                "size_limit",
+                "Rendered page exceeds the configured size limit; complete source retained.",
+            )
+        page = self.page
+        page.set_viewport_size({"width": width, "height": 900})
+        page.set_content(document, wait_until="domcontentloaded")
+        diag["expected_formulas"] = len(formulas)
+        formula_results = []
+        if formulas:
+            if not self.mathjax.is_file():
+                raise RenderError("mathjax_missing", "Local MathJax bundle is missing.")
+            page.evaluate(
+                "window.MathJax={startup:{typeset:false},svg:{fontCache:'none'},tex:{maxBuffer:100000,packages:['base','ams','newcommand']}}"
+            )
+            page.add_script_tag(path=str(self.mathjax))
+            page.wait_for_function(
+                "window.MathJax && MathJax.startup && MathJax.startup.promise"
+            )
+            formula_results = page.evaluate(
+                """async ({items,timeout})=>{
+              const work=async()=>{
+                await MathJax.startup.promise;
+                if(typeof MathJax.tex2svgPromise!=='function') throw Error('MathJax SVG API unavailable');
+                const results=[];
+                for(const item of items){
+                  const target=document.querySelector('[data-math-id="'+item.token+'"]');
+                  let error=null;
+                  try{
+                    if(item.malformed) throw Error('Unclosed formula delimiter');
+                    if(!item.tex.trim()) throw Error('Empty formula');
+                    const rendered=await MathJax.tex2svgPromise(item.tex,{display:item.display});
+                    if(rendered.querySelector('[data-mml-node="merror"],mjx-merror,[data-mjx-error]')) throw Error('Invalid TeX');
+                    // This screenshot renderer needs only SVG. Standalone tex2svg
+                    // may emit assistive MathML without the CSS that hides it.
+                    rendered.querySelectorAll('mjx-assistive-mml').forEach(node=>node.remove());
+                    target.replaceChildren(rendered);
+                  }catch(e){error=String(e.message||e);target.textContent=item.raw;target.classList.add('math-fallback');}
+                  results.push({id:item.token,rendered:!error,error});
+                }
+                return results;
+              };
+              let timer;try{return await Promise.race([work(),new Promise((_,reject)=>{timer=setTimeout(()=>reject(Error('Formula rendering timeout')),timeout)})]);}finally{clearTimeout(timer);}
+            }""",
+                {"items": formulas, "timeout": self.limits.timeout_ms},
+            )
+        diag["formulas"] = formula_results
+        diag["formula_fallbacks"] = sum(not x["rendered"] for x in formula_results)
+        page.evaluate(
+            """async timeout=>{
+          let timer;try{await Promise.race([(async()=>{await document.fonts.ready;await Promise.all([...document.images].map(i=>i.decode()));await new Promise(r=>requestAnimationFrame(()=>requestAnimationFrame(r)));})(),new Promise((_,reject)=>{timer=setTimeout(()=>reject(Error('Image/font readiness timeout')),timeout)})]);}finally{clearTimeout(timer);}
+        }""",
+            self.limits.timeout_ms,
+        )
+        # Allow intrinsically wide math/tables to grow once, within the resource budget.
+        needed = page.evaluate("document.documentElement.scrollWidth")
+        if needed > width:
+            width = needed + 28
+            if width > self.limits.max_side:
+                raise RenderError(
+                    "size_limit",
+                    "Rendered content is too wide; complete source retained.",
+                )
+            page.set_viewport_size({"width": width, "height": 900})
+            page.locator("#capture").evaluate('(e,w)=>e.style.width=w+"px"', width)
+        layout = page.evaluate("""()=>{
+          const root=document.getElementById('capture');const area=root.getBoundingClientRect();
+          const boxes=[...root.querySelectorAll('table,td,th,img,[data-math-id]')];
+          const bad=boxes.filter(e=>{const b=e.getBoundingClientRect(),s=getComputedStyle(e);return !b.width||!b.height||s.display==='none'||s.visibility==='hidden'||Number(s.opacity)===0||b.left<0||b.right>area.right+.5;}).map(e=>({tag:e.tagName,id:e.dataset.imageId||e.dataset.mathId||null}));
+          const fonts=[];const walker=document.createTreeWalker(root,NodeFilter.SHOW_TEXT);let n;
+          while(n=walker.nextNode()){if(n.textContent.trim()&&!n.parentElement.closest('mjx-container')){const s=getComputedStyle(n.parentElement);fonts.push(parseFloat(s.fontSize));}}
+          const cellHeights=[...root.querySelectorAll('td,th')].map(e=>e.getBoundingClientRect().height);
+          return {math:root.querySelectorAll('mjx-container').length,broken:[...root.querySelectorAll('img')].filter(i=>!i.complete||!i.naturalWidth).length,
+            tables:root.querySelectorAll('table').length,cells:cellHeights.length,invisible_or_clipped:bad,
+            min_font_px:fonts.length?fonts.reduce((a,b)=>Math.min(a,b),Infinity):18,min_cell_height_px:cellHeights.length?cellHeights.reduce((a,b)=>Math.min(a,b),Infinity):null,
+            width:document.documentElement.scrollWidth,height:document.documentElement.scrollHeight,
+            images:[...root.querySelectorAll('img')].map(i=>{const b=i.getBoundingClientRect();return {id:i.dataset.imageId,x:b.x,y:b.y,w:b.width,h:b.height}})};
+        }""")
+        diag.update(layout)
+        diag["errors"] = diag["formula_fallbacks"]
+        if layout["tables"] != len(tables) or layout["cells"] != expected_cells:
+            raise RenderError(
+                "table_structure",
+                "Browser parsing changed the table structure; source retained.",
+            )
+        if layout["invisible_or_clipped"] or layout["broken"]:
+            raise RenderError(
+                "invisible_content",
+                "Some page content is not visible; source retained.",
+            )
+        if layout["math"] + diag["formula_fallbacks"] != len(formulas):
+            raise RenderError(
+                "formula_coverage", "Formula rendering coverage is incomplete."
+            )
+        w, h = layout["width"], layout["height"]
+        # Snapshot has no live external scripts or assets; it opens offline as rendered.
+        (directory / (name + ".html")).write_text(
+            page.evaluate(
+                "() => { const root=document.documentElement.cloneNode(true); root.querySelectorAll('script').forEach(e=>e.remove()); return '<!doctype html>'+root.outerHTML; }"
+            )
+        )
+        if max(w, h) > self.limits.max_side or w * h > self.limits.max_render_pixels:
+            raise RenderError(
+                "size_limit",
+                "Rendered page exceeds the configured size limit; complete HTML retained.",
+            )
+        target = (w, h)
+        if not self.resize and not self.max_input_pixels:
+            diag["notes"].append({"code": "model_resize_unspecified"})
+        if self.resize:
+            try:
+                target = tuple(self.resize(w, h))
+            except Exception as exc:
+                raise RenderError(
+                    "model_resize_limit",
+                    "Page exceeds the model image-size limits; complete HTML retained.",
+                ) from exc
+        elif self.max_input_pixels:
+            scale = min(1, math.sqrt(self.max_input_pixels / (w * h)))
+            target = (max(1, math.floor(w * scale)), max(1, math.floor(h * scale)))
+        if len(target) != 2 or min(target) <= 0:
+            raise RenderError(
+                "resize_policy", "Invalid target dimensions from resize policy."
+            )
+        scale = min(target[0] / w, target[1] / h)
+        font = layout["min_font_px"] * scale
+        cell = (
+            layout["min_cell_height_px"] * scale
+            if layout["min_cell_height_px"]
+            else None
+        )
+        diag["readability"] = {
+            "input_size": [w, h],
+            "model_size": list(target),
+            "scale": scale,
+            "effective_font_px": font,
+            "effective_cell_height_px": cell,
+            "model_resize_known": bool(self.resize),
+            "estimated_from_pixel_budget": bool(
+                not self.resize and self.max_input_pixels
+            ),
+            "thresholds_are_heuristic": True,
+        }
+        if font < self.limits.min_effective_font_px or (
+            cell is not None and cell < self.limits.min_effective_cell_height_px
+        ):
+            raise RenderError(
+                "readability_limit",
+                "Page text would be too small after resizing; complete HTML retained.",
+            )
+        aliases, edits = {}, []
+        for image in layout["images"]:
+            item = by_token[image["id"]]
+            image["ref"] = item["ref"]
+            box = [
+                round(image["x"] / w * 1000),
+                round(image["y"] / h * 1000),
+                round((image["x"] + image["w"]) / w * 1000),
+                round((image["y"] + image["h"]) / h * 1000),
+            ]
+            if not 0 <= box[0] < box[2] <= 1000 or not 0 <= box[1] < box[3] <= 1000:
+                raise RenderError(
+                    "crop_quantization",
+                    "An image is too small for normalized coordinate mapping.",
+                )
+            alias = f"page_{owner}/images/bbox_" + "_".join(map(str, box)) + ".jpg"
+            if alias in aliases:
+                raise RenderError(
+                    "crop_alias_collision",
+                    "Image positions cannot be uniquely represented.",
+                )
+            aliases[alias] = item["ref"]
+            edits.append((item["start"], item["end"], _image_markup(item, alias)))
+        rewritten = _edit_source(md, edits)
+        path = directory / (name + ".png")
+        page.screenshot(path=str(path), full_page=True, timeout=self.limits.timeout_ms)
+        with Image.open(path) as rendered:
+            if rendered.size != (w, h):
+                raise RenderError(
+                    "screenshot_dimensions",
+                    "Screenshot dimensions differ from image coordinate mapping.",
+                )
+        (directory / (name + ".rewritten.md")).write_text(rewritten)
+        save(directory / (name + ".aliases.json"), aliases)
+        return RenderResult(str(path), rewritten, aliases, diag)
+
+
+# Command-line interface.
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="OvisOCR3 document-level cross-page reconstruction"
+    )
+    parser.add_argument("images", nargs="+", help="Page images in reading order")
+    parser.add_argument("--model", default=".")
+    parser.add_argument("--output", required=True)
+    parser.add_argument(
+        "--stage1-prompt",
+        default="document_structured.txt",
+        choices=[
+            "document_markdown",
+            "document_markdown.txt",
+            "document_structured",
+            "document_structured.txt",
+        ],
+    )
+    parser.add_argument(
+        "--mathjax",
+        default=None,
+        help="Local MathJax bundle; defaults to assets/mathjax.js beside this script",
+    )
+    args = parser.parse_args()
+    result = reconstruct_document(
+        args.images,
+        args.output,
+        model_path=args.model,
+        stage1_prompt=args.stage1_prompt,
+        mathjax=args.mathjax,
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:aa2311c6b22b07cf3afe9aac6e8bcb02a2b19dd8671b2a91d0b144071577e600
+size 1706030528

preprocessor_config.json

@@ -0,0 +1,21 @@
+{
+    "size": {
+        "longest_edge": 16777216,
+        "shortest_edge": 65536
+    },
+    "patch_size": 16,
+    "temporal_patch_size": 2,
+    "merge_size": 2,
+    "image_mean": [
+        0.5,
+        0.5,
+        0.5
+    ],
+    "image_std": [
+        0.5,
+        0.5,
+        0.5
+    ],
+    "processor_class": "Qwen3VLProcessor",
+    "image_processor_type": "Qwen2VLImageProcessorFast"
+}

prompts/chart_parsing.txt

@@ -0,0 +1,8 @@
+Parse all key information in the chart and output one valid JSON object using exactly this top-level schema:
+{"title":"","source":"","x_title":"","y_title":"","values":{}}
+
+Rules:
+1. Preserve visible title, source, axis titles, series or category labels, x-axis labels, and values without explanation or inference.
+2. Use the literal string "None" when the chart has no visible value for title, source, or an axis title. For a dual-axis chart, `y_title` may be an array of two strings in visual order; otherwise it must be one string.
+3. `values` must be a non-empty object. Preserve the chart hierarchy and encode every scalar data value as a JSON string. An empty series name may be represented by the key "" when the chart has no visible series label.
+4. Output JSON only. Do not output Python syntax, Markdown fences, comments, prose, or extra keys.

prompts/crosspage_table.txt

@@ -0,0 +1,5 @@
+Find and reconstruct every table whose content continues across two or more consecutive input pages.
+
+Return only one JSON array. Each cross-page table is one object with exactly these fields: source_pages and html. source_pages contains the input-local 1-based pages of that table. html contains one complete HTML <table>...</table>.
+
+If no cross-page table exists, return [{"source_pages":[],"html":"No cross-page table exists between these pages."}]. Preserve figures inside cross-page tables as <img src="page_N/images/bbox_left_top_right_bottom.jpg" />; page_N is 1-based. Return no explanation or code fence.

prompts/document_layout.txt

@@ -0,0 +1,9 @@
+Analyze the document structure and return a single JSON array in natural reading order.
+
+Each element follows this schema:
+`{"bbox": [x_min, y_min, x_max, y_max], "category": "string"}`
+
+Rules:
+1. The bbox coordinates are integers scaled to [0, 1000).
+2. The category is exactly one of:
+["abstract", "algorithm", "aside_text", "chart", "content", "display_formula", "doc_title", "figure_title", "footer", "footer_image", "footnote", "formula_number", "header", "header_image", "image", "inline_formula", "number", "paragraph_title", "reference_content", "seal", "table", "text", "vertical_text", "vision_footnote"].

prompts/document_markdown.txt

@@ -0,0 +1 @@
+Extract all readable content from the image in natural human reading order and output the result as a single Markdown document. For charts or images, represent them using an HTML image tag: <img src="images/bbox_{left}_{top}_{right}_{bottom}.jpg" />, where left, top, right, bottom are bounding box coordinates scaled to [0, 1000). Format formulas as LaTeX. Format tables as HTML: <table>...</table>. Transcribe all other text as standard Markdown. Preserve the original text without translation or paraphrasing.

prompts/document_structured.txt

@@ -0,0 +1,15 @@
+Analyze the document structure and extract text content. Return a single JSON array in natural reading order.
+
+Each element follows this schema:
+`{"bbox": [x_min, y_min, x_max, y_max], "category": "string", "content": "string"}`
+
+Rules:
+1. The bbox coordinates are integers scaled to [0, 1000).
+2. The category is exactly one of:
+["abstract", "algorithm", "aside_text", "chart", "content", "display_formula", "doc_title", "figure_title", "footer", "footer_image", "footnote", "formula_number", "header", "header_image", "image", "inline_formula", "number", "paragraph_title", "reference_content", "seal", "table", "text", "vertical_text", "vision_footnote"].
+3. The content formatting depends on category:
+- For "footer_image", "header_image", "image", or "chart": write as an HTML image tag <img src="images/bbox_{x_min}_{y_min}_{x_max}_{y_max}.jpg" />.
+- For "display_formula" or "inline_formula": write in LaTeX.
+- For "table": write as a standard HTML `<table>...</table>`.
+- Otherwise: write in Markdown.
+4. Output must be strictly valid JSON. Properly escape quotes and special characters inside content.

prompts/figure_captioning.txt

@@ -0,0 +1,17 @@
+Analyze the document structure and extract text content. Return a single JSON array in natural reading order.
+
+Each element follows this schema:
+`{"bbox": [x_min, y_min, x_max, y_max], "category": "string", "content": "string"}`
+
+Rules:
+1. The bbox coordinates are integers scaled to [0, 1000).
+2. The category is exactly one of:
+["abstract", "algorithm", "aside_text", "chart", "content", "display_formula", "doc_title", "figure_title", "footer", "footer_image", "footnote", "formula_number", "header", "header_image", "image", "inline_formula", "number", "paragraph_title", "reference_content", "seal", "table", "text", "vertical_text", "vision_footnote"].
+3. The content formatting depends on category:
+- For "footer_image", "header_image", "image", or "chart":
+  - Always provide a concise English caption of no more than 100 words inside `<caption>...</caption>`, preserving visible labels in their original language when needed.
+  - For a flowchart, a valid Mermaid representation may follow the caption inside `<mermaid>...</mermaid>`.
+- For "display_formula" or "inline_formula": write in LaTeX.
+- For "table": write as a standard HTML `<table>...</table>`.
+- Otherwise: write in Markdown.
+4. Output must be strictly valid JSON. Properly escape quotes and special characters inside content.

prompts/formula_recognition.txt

@@ -0,0 +1,8 @@
+Recognize and transcribe every mathematical expression in the image as LaTeX. Directly output the formula content.
+
+Rules:
+1. Preserve every visible symbol, operator, delimiter, superscript, subscript, accent, matrix row, alignment, and line break without translation, paraphrasing, correction, completion, or omission.
+2. Wrap each standalone or display expression as `$$ ... $$`.
+3. If multiple standalone expressions are visible, output one `$$ ... $$` block per expression in natural reading order, separated by a single line break.
+4. Use one decoded backslash for a LaTeX command and two decoded backslashes for a LaTeX row break. JSON serialization may escape these backslashes on disk, but the decoded target must retain valid LaTeX semantics.
+5. Output formula content only. Do not output prose, explanations, translations, Markdown code fences, HTML, document-level table markup, or JSON.

prompts/image_classification.txt

@@ -0,0 +1,5 @@
+Classify {target description} in the image. Select exactly one label from the candidate list.
+
+Candidate labels: {candidate_labels}
+
+Directly output the selected label exactly as written. Do not output explanations, punctuation, JSON, Markdown, or any other text.

prompts/kie_fields.txt

@@ -0,0 +1 @@
+Extract the values for the following keys from the image: {keys_json}. Return a JSON object using exactly these keys. Keep the values exactly as shown, use empty strings for missing values, and use arrays for repeated values. Output JSON only.

prompts/kie_open.txt

@@ -0,0 +1 @@
+Extract all key-value pairs from the image and return them as a JSON object. Keep the values exactly as shown, use empty strings for empty values, and use arrays for repeated values. Output JSON only.

prompts/kie_schema.txt

@@ -0,0 +1,3 @@
+Extract the information from the image using exactly this JSON schema:
+{schema_json}
+Keep the values exactly as shown and use empty strings for missing values. Output JSON only.

prompts/plain_ocr.txt

@@ -0,0 +1,7 @@
+Read all the text in the image. Directly output the content.
+
+Rules:
+1. Preserve the original text exactly without translation, paraphrasing, correction, or completion.
+2. Follow the natural human reading order.
+3. Output plain text only. Use spaces and line breaks only to preserve text separation and reading order.
+4. Do not output Markdown, HTML, JSON, bounding boxes, category labels, explanations, or code fences.

prompts/position_aware_vqa.txt

@@ -0,0 +1,6 @@
+{question} Output the answer with 'answer' and 'bbox'. 'bbox' refers to the bounding box position of the 'answer' content in the image. The output format is "answer:gt, bbox:(x1,y1,x2,y2)", where the bbox is the coordinates of the top-left corner and the bottom-right corners. The 'bbox' should be normalized coordinates ranging from 0 to 1000 by the image width and height.
+Your answer should be in the JSON format:
+{
+    "answer": "..",  # The answer
+    "bbox": "(x1,y1,x2,y2)"     # The bounding box position of the 'answer'
+}

prompts/reference_grounding.txt

@@ -0,0 +1,19 @@
+Locate every visible region corresponding to the requested reference or references in the image.
+
+Requested references (JSON array, source order):
+{references}
+
+Return a single JSON array in the requested reference order.
+
+Each element follows this schema:
+`{"bbox": [x_min, y_min, x_max, y_max], "reference": "string"}`
+
+Rules:
+1. Each element must represent exactly one requested reference and one corresponding visible region. If one requested reference corresponds to multiple separate regions, output one element for each bbox and repeat the same reference.
+2. The bbox coordinates are integers scaled to [0, 1000).
+3. Each bbox must tightly enclose its corresponding referenced entity or region and must not include unrelated content.
+4. Copy each reference exactly from the requested-references array without translation, paraphrasing, correction, or completion. Do not output any reference that was not requested.
+5. Do not add leading or trailing whitespace to reference.
+6. Return bounding boxes only. Do not return points, polygons, masks, explanations, or confidence scores.
+7. Every requested reference must appear in at least one output element.
+8. Output strictly valid JSON only. Do not output Markdown, explanations, or code fences. Properly escape quotes, backslashes, and other special characters inside reference.

prompts/region_ocr.txt

@@ -0,0 +1,9 @@
+Transcribe all readable text in the specified image region. Directly output the content.
+Target region: {target_region}
+
+Rules:
+1. Read only the visible text inside the target region.
+2. Preserve the original text exactly without translation, paraphrasing, correction, completion, or omission.
+3. Follow the natural human reading order within the target region.
+4. Output plain text only. Use spaces and line breaks only where needed to preserve text separation and reading order.
+5. Do not output the target region, bounding boxes, coordinates, category labels, Markdown formatting, HTML, JSON, explanations, or code fences.

prompts/text_translation.txt

@@ -0,0 +1,9 @@
+Translate all readable text in the specified image region into {target_language}. Directly output the translated content.
+Target region: {target_region}
+
+Rules:
+1. Translate only the visible text inside the target region.
+2. Preserve the original meaning, names, numbers, symbols, and line order. Do not add explanations, corrections, or omitted context.
+3. Keep content that should not be translated unchanged.
+4. Output plain translated text only. Use spaces and line breaks only where needed to preserve the source separation.
+5. Do not output the source text, language labels, bounding boxes, Markdown, JSON, or code fences.

prompts/visual_question_answering.txt

@@ -0,0 +1,3 @@
+{question}
+
+Please reason step by step, and put your final answer within \boxed{}.

prompts/word_spotting.txt

@@ -0,0 +1,13 @@
+Locate and transcribe every readable word or text token in the image. Return a single JSON array in natural reading order.
+
+Each element follows this schema:
+`{"bbox": [x_min, y_min, x_max, y_max], "text": "string"}`
+
+Rules:
+1. Use word-level annotations. Each element must represent exactly one visible word or text token. Do not merge multiple words into a text line, paragraph, label, or table cell.
+2. The bbox coordinates are integers scaled to [0, 1000).
+3. Each bbox must tightly enclose its corresponding visible word or text token and must not include adjacent words or unrelated text regions.
+4. Preserve the original text exactly without translation, paraphrasing, correction, or completion.
+5. Do not add leading or trailing whitespace to text.
+6. Include every readable word or text token and exclude non-text visual content.
+7. Output strictly valid JSON only. Do not output Markdown, explanations, or code fences. Properly escape quotes, backslashes, and other special characters inside text.

tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5f9e4d4901a92b997e463c1f46055088b6cca5ca61a6522d1b9f64c4bb81cb42
+size 12807982

tokenizer_config.json

@@ -0,0 +1,305 @@
+{
+    "add_prefix_space": false,
+    "added_tokens_decoder": {
+        "248044": {
+            "content": "<|endoftext|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248045": {
+            "content": "<|im_start|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248046": {
+            "content": "<|im_end|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248047": {
+            "content": "<|object_ref_start|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248048": {
+            "content": "<|object_ref_end|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248049": {
+            "content": "<|box_start|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248050": {
+            "content": "<|box_end|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248051": {
+            "content": "<|quad_start|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248052": {
+            "content": "<|quad_end|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248053": {
+            "content": "<|vision_start|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248054": {
+            "content": "<|vision_end|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248055": {
+            "content": "<|vision_pad|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248056": {
+            "content": "<|image_pad|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248057": {
+            "content": "<|video_pad|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248058": {
+            "content": "<tool_call>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": false
+        },
+        "248059": {
+            "content": "</tool_call>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": false
+        },
+        "248060": {
+            "content": "<|fim_prefix|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": false
+        },
+        "248061": {
+            "content": "<|fim_middle|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": false
+        },
+        "248062": {
+            "content": "<|fim_suffix|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": false
+        },
+        "248063": {
+            "content": "<|fim_pad|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": false
+        },
+        "248064": {
+            "content": "<|repo_name|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": false
+        },
+        "248065": {
+            "content": "<|file_sep|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": false
+        },
+        "248066": {
+            "content": "<tool_response>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": false
+        },
+        "248067": {
+            "content": "</tool_response>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": false
+        },
+        "248068": {
+            "content": "<think>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": false
+        },
+        "248069": {
+            "content": "</think>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": false
+        },
+        "248070": {
+            "content": "<|audio_start|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248071": {
+            "content": "<|audio_end|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248072": {
+            "content": "<tts_pad>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248073": {
+            "content": "<tts_text_bos>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248074": {
+            "content": "<tts_text_eod>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248075": {
+            "content": "<tts_text_bos_single>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        },
+        "248076": {
+            "content": "<|audio_pad|>",
+            "lstrip": false,
+            "normalized": false,
+            "rstrip": false,
+            "single_word": false,
+            "special": true
+        }
+    },
+    "additional_special_tokens": [
+        "<|im_start|>",
+        "<|im_end|>",
+        "<|object_ref_start|>",
+        "<|object_ref_end|>",
+        "<|box_start|>",
+        "<|box_end|>",
+        "<|quad_start|>",
+        "<|quad_end|>",
+        "<|vision_start|>",
+        "<|vision_end|>",
+        "<|vision_pad|>",
+        "<|image_pad|>",
+        "<|video_pad|>"
+    ],
+    "bos_token": null,
+    "chat_template": "{%- set image_count = namespace(value=0) %}\n{%- set video_count = namespace(value=0) %}\n{%- macro render_content(content, do_vision_count, is_system_content=false) %}\n    {%- if content is string %}\n        {{- content }}\n    {%- elif content is iterable and content is not mapping %}\n        {%- for item in content %}\n            {%- if 'image' in item or 'image_url' in item or item.type == 'image' %}\n                {%- if is_system_content %}\n                    {{- raise_exception('System message cannot contain images.') }}\n                {%- endif %}\n                {%- if do_vision_count %}\n                    {%- set image_count.value = image_count.value + 1 %}\n                {%- endif %}\n                {%- if add_vision_id %}\n                    {{- 'Picture ' ~ image_count.value ~ ': ' }}\n                {%- endif %}\n                {{- '<|vision_start|><|image_pad|><|vision_end|>' }}\n            {%- elif 'video' in item or item.type == 'video' %}\n                {%- if is_system_content %}\n                    {{- raise_exception('System message cannot contain videos.') }}\n                {%- endif %}\n                {%- if do_vision_count %}\n                    {%- set video_count.value = video_count.value + 1 %}\n                {%- endif %}\n                {%- if add_vision_id %}\n                    {{- 'Video ' ~ video_count.value ~ ': ' }}\n                {%- endif %}\n                {{- '<|vision_start|><|video_pad|><|vision_end|>' }}\n            {%- elif 'text' in item %}\n                {{- item.text }}\n            {%- else %}\n                {{- raise_exception('Unexpected item type in content.') }}\n            {%- endif %}\n        {%- endfor %}\n    {%- elif content is none or content is undefined %}\n        {{- '' }}\n    {%- else %}\n        {{- raise_exception('Unexpected content type.') }}\n    {%- endif %}\n{%- endmacro %}\n{%- if not messages %}\n    {{- raise_exception('No messages provided.') }}\n{%- endif %}\n{%- if tools and tools is iterable and tools is not mapping %}\n    {{- '<|im_start|>system\\n' }}\n    {{- \"# Tools\\n\\nYou have access to the following functions:\\n\\n<tools>\" }}\n    {%- for tool in tools %}\n        {{- \"\\n\" }}\n        {{- tool | tojson }}\n    {%- endfor %}\n    {{- \"\\n</tools>\" }}\n    {{- '\\n\\nIf you choose to call a function ONLY reply in the following format with NO suffix:\\n\\n<tool_call>\\n<function=example_function_name>\\n<parameter=example_parameter_1>\\nvalue_1\\n</parameter>\\n<parameter=example_parameter_2>\\nThis is the value for the second parameter\\nthat can span\\nmultiple lines\\n</parameter>\\n</function>\\n</tool_call>\\n\\n<IMPORTANT>\\nReminder:\\n- Function calls MUST follow the specified format: an inner <function=...></function> block must be nested within <tool_call></tool_call> XML tags\\n- Required parameters MUST be specified\\n- You may provide optional reasoning for your function call in natural language BEFORE the function call, but NOT after\\n- If there is no function call available, answer the question like normal with your current knowledge and do not tell the user about function calls\\n</IMPORTANT>' }}\n    {%- if messages[0].role == 'system' %}\n        {%- set content = render_content(messages[0].content, false, true)|trim %}\n        {%- if content %}\n            {{- '\\n\\n' + content }}\n        {%- endif %}\n    {%- endif %}\n    {{- '<|im_end|>\\n' }}\n{%- else %}\n    {%- if messages[0].role == 'system' %}\n        {%- set content = render_content(messages[0].content, false, true)|trim %}\n        {{- '<|im_start|>system\\n' + content + '<|im_end|>\\n' }}\n    {%- endif %}\n{%- endif %}\n{%- set ns = namespace(multi_step_tool=true, last_query_index=messages|length - 1) %}\n{%- for message in messages[::-1] %}\n    {%- set index = (messages|length - 1) - loop.index0 %}\n    {%- if ns.multi_step_tool and message.role == \"user\" %}\n        {%- set content = render_content(message.content, false)|trim %}\n        {%- if not(content.startswith('<tool_response>') and content.endswith('</tool_response>')) %}\n            {%- set ns.multi_step_tool = false %}\n            {%- set ns.last_query_index = index %}\n        {%- endif %}\n    {%- endif %}\n{%- endfor %}\n{%- if ns.multi_step_tool %}\n    {{- raise_exception('No user query found in messages.') }}\n{%- endif %}\n{%- for message in messages %}\n    {%- set content = render_content(message.content, true)|trim %}\n    {%- if message.role == \"system\" %}\n        {%- if not loop.first %}\n            {{- raise_exception('System message must be at the beginning.') }}\n        {%- endif %}\n    {%- elif message.role == \"user\" %}\n        {{- '<|im_start|>' + message.role + '\\n' + content + '<|im_end|>' + '\\n' }}\n    {%- elif message.role == \"assistant\" %}\n        {%- set reasoning_content = '' %}\n        {%- if message.reasoning_content is string %}\n            {%- set reasoning_content = message.reasoning_content %}\n        {%- else %}\n            {%- if '</think>' in content %}\n                {%- set reasoning_content = content.split('</think>')[0].rstrip('\\n').split('<think>')[-1].lstrip('\\n') %}\n                {%- set content = content.split('</think>')[-1].lstrip('\\n') %}\n            {%- endif %}\n        {%- endif %}\n        {%- set reasoning_content = reasoning_content|trim %}\n        {%- if loop.index0 > ns.last_query_index %}\n            {{- '<|im_start|>' + message.role + '\\n<think>\\n' + reasoning_content + '\\n</think>\\n\\n' + content }}\n        {%- else %}\n            {{- '<|im_start|>' + message.role + '\\n' + content }}\n        {%- endif %}\n        {%- if message.tool_calls and message.tool_calls is iterable and message.tool_calls is not mapping %}\n            {%- for tool_call in message.tool_calls %}\n                {%- if tool_call.function is defined %}\n                    {%- set tool_call = tool_call.function %}\n                {%- endif %}\n                {%- if loop.first %}\n                    {%- if content|trim %}\n                        {{- '\\n\\n<tool_call>\\n<function=' + tool_call.name + '>\\n' }}\n                    {%- else %}\n                        {{- '<tool_call>\\n<function=' + tool_call.name + '>\\n' }}\n                    {%- endif %}\n                {%- else %}\n                    {{- '\\n<tool_call>\\n<function=' + tool_call.name + '>\\n' }}\n                {%- endif %}\n                {%- if tool_call.arguments is defined %}\n                    {%- for args_name, args_value in tool_call.arguments|items %}\n                        {{- '<parameter=' + args_name + '>\\n' }}\n                        {%- set args_value = args_value | tojson | safe if args_value is mapping or (args_value is sequence and args_value is not string) else args_value | string %}\n                        {{- args_value }}\n                        {{- '\\n</parameter>\\n' }}\n                    {%- endfor %}\n                {%- endif %}\n                {{- '</function>\\n</tool_call>' }}\n            {%- endfor %}\n        {%- endif %}\n        {{- '<|im_end|>\\n' }}\n    {%- elif message.role == \"tool\" %}\n        {%- if loop.previtem and loop.previtem.role != \"tool\" %}\n            {{- '<|im_start|>user' }}\n        {%- endif %}\n        {{- '\\n<tool_response>\\n' }}\n        {{- content }}\n        {{- '\\n</tool_response>' }}\n        {%- if not loop.last and loop.nextitem.role != \"tool\" %}\n            {{- '<|im_end|>\\n' }}\n        {%- elif loop.last %}\n            {{- '<|im_end|>\\n' }}\n        {%- endif %}\n    {%- else %}\n        {{- raise_exception('Unexpected message role.') }}\n    {%- endif %}\n{%- endfor %}\n{%- if add_generation_prompt %}\n    {{- '<|im_start|>assistant\\n' }}\n    {%- if enable_thinking is defined and enable_thinking is true %}\n        {{- '<think>\\n' }}\n    {%- else %}\n        {{- '<think>\\n\\n</think>\\n\\n' }}\n    {%- endif %}\n{%- endif %}",
+    "clean_up_tokenization_spaces": false,
+    "eos_token": "<|im_end|>",
+    "errors": "replace",
+    "model_max_length": 262144,
+    "pad_token": "<|endoftext|>",
+    "split_special_tokens": false,
+    "tokenizer_class": "Qwen2Tokenizer",
+    "unk_token": null,
+    "add_bos_token": false,
+    "pretokenize_regex": "(?i:'s|'t|'re|'ve|'m|'ll|'d)|[^\\r\\n\\p{L}\\p{N}]?[\\p{L}\\p{M}]+|\\p{N}| ?[^\\s\\p{L}\\p{M}\\p{N}]+[\\r\\n]*|\\s*[\\r\\n]+|\\s+(?!\\S)|\\s+",
+    "extra_special_tokens": {
+        "audio_bos_token": "<|audio_start|>",
+        "audio_eos_token": "<|audio_end|>",
+        "audio_token": "<|audio_pad|>",
+        "image_token": "<|image_pad|>",
+        "video_token": "<|video_pad|>",
+        "vision_bos_token": "<|vision_start|>",
+        "vision_eos_token": "<|vision_end|>"
+    }
+}

video_preprocessor_config.json

@@ -0,0 +1,21 @@
+{
+    "size": {
+        "longest_edge": 25165824,
+        "shortest_edge": 4096
+    },
+    "patch_size": 16,
+    "temporal_patch_size": 2,
+    "merge_size": 2,
+    "image_mean": [
+        0.5,
+        0.5,
+        0.5
+    ],
+    "image_std": [
+        0.5,
+        0.5,
+        0.5
+    ],
+    "processor_class": "Qwen3VLProcessor",
+    "video_processor_type": "Qwen3VLVideoProcessor"
+}