Add inference code and usage instructions

NOTICE

@@ -9,5 +9,10 @@ revision 97c77dff50b2797bcc558fa2d909761dbc575c59), licensed under the Apache Li
 weights were fine-tuned with LoRA for Japanese page transcription and the adapter was merged into BF16 weights.
 The base model's publisher also publishes a usage policy, reproduced in notices/Muse-Glimmer-30B-USAGE_POLICY.md.
 
-The separately distributed document pipeline is released under the GNU Affero General Public License v3.0.
-It includes UVDoc code, MIT licensed, Copyright (c) 2023 Tanguy MAGNE.
+The page reader wasabi_read (orientation check, UVDoc flattening, whole-page read and per-page output) is released
+under the GNU Affero General Public License v3.0.
+
+UVDoc (https://github.com/tanguymagne/UVDoc), code at commit 4c9b82b537057aff2526e6dd118a847cdd072e82: MIT License,
+Copyright (c) 2023 Tanguy MAGNE. wasabi_read downloads the UVDoc code and its pretrained weights
+(model/best_model.pkl) from that commit at first use and does not redistribute them. The UVDoc repository carries
+no weights-specific licence statement; the weights remain under their own terms.

README.md

@@ -1,97 +1,169 @@
 ---
 license: agpl-3.0
 base_model: meta-models/Muse-Glimmer-30B
-base_model_relation: finetune
-library_name: transformers
 pipeline_tag: image-text-to-text
 language:
 - ja
+library_name: transformers
 tags:
 - ocr
 - document-transcription
 - japanese
+- vllm
 ---
 
 # Wasabi-30B
 
-Wasabi-30B is Sionic AI's Japanese document fine-tune of [Muse Glimmer 30B](https://huggingface.co/meta-models/Muse-Glimmer-30B). It transcribes page images into Markdown, including headings, paragraphs, tables and mathematical notation.
+Wasabi-30B reads a Japanese document page image and writes the page as Markdown:
 
-The checkpoint is provided as merged BF16 weights in two safetensors shards, approximately 60 GB in total. No separate adapter or base-model download is needed.
+- full text in reading order;
+- tables as HTML `<table>`;
+- math as LaTeX, `$...$` inline and `$$...$$` for display;
+- ruby (furigana) kept inline as `<ruby>base<rt>reading</rt></ruby>`.
 
-## Document processing
+## Model details
 
-Fine-tuning focuses on Japanese text structure, paragraph continuity and faithful transcription. The full document-processing pipeline also handles page orientation, complex layouts and small text annotations through preprocessing and output refinement.
+- Fine-tune of Muse-Glimmer-30B (https://huggingface.co/meta-models/Muse-Glimmer-30B, revision
+  `97c77dff50b2797bcc558fa2d909761dbc575c59`).
+- A LoRA adapter trained for Japanese page transcription, merged into BF16 weights.
+- Two safetensors shards.
 
-The complete pipeline is maintained in Sionic AI's private [Wasabi repository](https://github.com/sionic-ai/Wasabi-30B), accessible to authorized collaborators. The Docker package supplied for evaluation includes the full inference pipeline and its runtime assets.
+## Files in this repository
 
-## Quickstart
+| path | what it is |
+|---|---|
+| `model-00001-of-00002.safetensors`, `model-00002-of-00002.safetensors`, `model.safetensors.index.json` | merged BF16 weights |
+| `config.json`, `generation_config.json`, `processor_config.json` | model and processor configuration |
+| `tokenizer.json`, `tokenizer_config.json`, `chat_template.jinja` | tokenizer and chat template |
+| `inference/` | the page reader package (`wasabi_read`, AGPL-3.0) and its two prompts |
+| `LICENSE`, `NOTICE`, `notices/` | licence texts: this model (AGPL-3.0), the base model (Apache-2.0) and its usage policy |
+| `SHA256SUMS` | checksums of every file |
 
-This example transcribes one upright page image. Convert PDFs to page images first. Allow GPU memory for the weights, image processing and generated tokens; `device_map="auto"` distributes the model across available devices.
+## Inference
 
-Install PyTorch for your CUDA environment, then:
+The package reads a folder of page images (`.jpg`, `.jpeg`, `.png`) and writes one `.md` file per page.
 
-```bash
-pip install "transformers==5.15.0" accelerate pillow huggingface_hub
-```
+    pip install -e "./inference[dewarp]"
 
-Save the following as `transcribe.py` and run `python transcribe.py page.jpg > page.md`:
+Python 3.10+. The reader flattens every page locally with UVDoc on CPU, so torch and OpenCV are required in every
+mode, including endpoint mode.
 
-```python
-import argparse
-from pathlib import Path
+Local serving needs vLLM with muse_glimmer support, built from commit `6adad08767583f52eb4d2122111af0bf638ed5e6`
+(version `0.26.1rc1.dev769`). Released vLLM 0.26.0 has no muse_glimmer model, so it cannot serve this model. A
+source build needs a CUDA toolchain:
 
-import torch
-from huggingface_hub import hf_hub_download
-from PIL import Image, ImageOps
-from transformers import AutoModelForImageTextToText, AutoProcessor
+    pip install "vllm @ git+https://github.com/vllm-project/vllm.git@6adad08767583f52eb4d2122111af0bf638ed5e6" "transformers==5.15.0"
 
-parser = argparse.ArgumentParser()
-parser.add_argument("image")
-parser.add_argument("--rotate", type=int, choices=[0, 90, 180, 270], default=0,
-                    help="Additional clockwise rotation in degrees")
-args = parser.parse_args()
+Then, with the Python of that vLLM environment, apply the one-file processor fix. Without it, the muse_glimmer
+processor of this vLLM commit rejects the `max_image_tokens` setting that every server below is started with, and the
+server does not start. The script edits one file, checks its sha256 before and after, and can undo the edit
+(`--check`, `--revert`). A server you start yourself (endpoint mode, direct model use) needs it too.
 
-model_id = "sionic-ai/Wasabi-30B"
-processor = AutoProcessor.from_pretrained(model_id)
-model = AutoModelForImageTextToText.from_pretrained(
-    model_id, dtype=torch.bfloat16, device_map="auto"
-).eval()
+    python inference/patch_vllm_max_image_tokens.py --apply
 
-prompt_path = hf_hub_download(model_id, "prompt.txt")
-prompt = Path(prompt_path).read_text(encoding="utf-8")
-with Image.open(args.image) as source:
-    image = ImageOps.exif_transpose(source).convert("RGB")
-if args.rotate:
-    image = image.rotate(-args.rotate, expand=True)
-messages = [{"role": "user", "content": [
-    {"type": "image", "image": image},
-    {"type": "text", "text": prompt},
-]}]
-inputs = processor.apply_chat_template(
-    messages, add_generation_prompt=True, tokenize=True,
-    return_dict=True, return_tensors="pt", reasoning_strength="low",
-).to(model.device)
+An endpoint run needs no local vLLM.
 
-with torch.inference_mode():
-    output = model.generate(**inputs, max_new_tokens=8192, do_sample=False)
-generated = output[0, inputs["input_ids"].shape[1]:]
-print(processor.decode(generated, skip_special_tokens=True))
-```
+Tested with Python 3.12, vLLM `0.26.1rc1.dev769` (commit 6adad087), transformers 5.15.0, torch 2.13.0,
+opencv-python-headless 5.0.0.93, numpy 2.3.5 and Pillow 13.0.0.
 
-The example applies EXIF orientation metadata. For a page still turned sideways, use `python transcribe.py page.jpg --rotate 90 > page.md`. Automatic visual orientation correction is part of the private pipeline.
+Wasabi-30B is the only checkpoint the reader needs: it checks the page orientation and reads the page.
 
-Use the included [transcription prompt](prompt.txt) with the supplied chat template. The example covers direct model inference. For deployment support, contact [Sionic AI](https://sionic.ai).
+Local vLLM (the package starts and stops the servers itself: first the orientation check, then the reader, both from
+the same weights):
 
-File checksums are provided in `SHA256SUMS`.
+    python inference/wasabi_read.py pages/ out/ --engine vllm --model-dir /models/Wasabi-30B --tensor-parallel-size 1 --whole-upscale-tokens 8192
 
-## Limitations
+Against OpenAI-compatible servers you already run, both serving Wasabi-30B: the reader started with
+`--mm-processor-kwargs '{"max_image_tokens": 8192}'`, the orientation check with
+`--mm-processor-kwargs '{"max_image_tokens": 4096}'`, and both with `--reasoning-parser muse_glimmer`. Name what each
+server serves with `--endpoint-revision` and `--orient-endpoint-revision`; the addresses and revisions are part of the
+output identity, so a rerun against another server is refused instead of mixed into the same output directory.
+
+    python inference/wasabi_read.py pages/ out/ --engine endpoint --endpoint-url http://gpu-host:8000 --endpoint-revision wasabi-30b-v1.0 --orient-endpoint-url http://gpu-host:8001 --orient-endpoint-revision wasabi-30b-v1.0
+
+`--plan` prints the stages and exits without loading a model.
+
+The API key, the UVDoc cache location and offline UVDoc use are described under
+[Configuration](inference/README.md#configuration).
+
+### Direct model use
+
+This sends the page image as it is: no orientation check, no flattening, no enlargement and no retries. It is a basic
+transcription path, separate from the reader above. It uses the vLLM build and the processor fix from the Inference
+section.
+
+    pip install openai
+    vllm serve /models/Wasabi-30B --served-model-name wasabi --max-model-len 36864 \
+        --mm-processor-kwargs '{"max_image_tokens": 8192}' --reasoning-parser muse_glimmer
 
-- Dense or low-quality pages can lose text, table structure or reading order.
-- Use upright page images and check important details against the source.
-- Retrieval, question answering and general chat require separate evaluation.
+Then send one page with the OpenAI-compatible API, using the recommended decoding (greedy, repetition penalty 1.10,
+seed 42, up to 24,576 new tokens, low reasoning strength):
 
-## Licence and attribution
+    import base64
+    from openai import OpenAI
 
-Wasabi-30B is released under AGPL-3.0. See `LICENSE` and `NOTICE` for terms and attribution.
+    client = OpenAI(base_url="http://localhost:8000/v1", api_key="none")
+    png = base64.b64encode(open("page.png", "rb").read()).decode()
+    prompt = open("inference/wasabi_read/prompts/draft.txt", encoding="utf-8").read()
+    r = client.chat.completions.create(
+        model="wasabi",
+        messages=[{"role": "user", "content": [
+            {"type": "image_url", "image_url": {"url": "data:image/png;base64," + png}},
+            {"type": "text", "text": prompt}]}],
+        temperature=0.0,
+        seed=42,
+        max_tokens=24576,
+        extra_body={"repetition_penalty": 1.10,
+                    "repetition_detection": {"max_pattern_size": 512, "min_pattern_size": 4, "min_count": 16},
+                    "chat_template_kwargs": {"reasoning_strength": "low", "current_date": "2026-10-16"}},
+    )
+    print(r.choices[0].message.content)
+
+The transcription prompt is the file `inference/wasabi_read/prompts/draft.txt`. The reader pins `current_date` so that the output does
+not depend on the day you run it, and `repetition_detection` stops a looping answer early.
+
+`generation_config.json` keeps the base model's sampling defaults; pass `temperature=0` (as above) for the
+recommended greedy transcription.
+
+## What the reader does
+
+Per page:
+
+1. Orientation check: Wasabi-30B answers a four-way upright probe at 4,096 image tokens; a turn is applied only when
+   the margin is at least 5.0.
+2. Flattening with UVDoc on CPU. The UVDoc code and weights are fetched at first use from a pinned commit and checked
+   by sha256 before loading.
+3. A whole-page read at 8,192 image tokens, greedy.
+4. If the answer is degenerate, a retry ladder at temperatures 0.1, 0.3, 0.5 and 0.8.
+5. Output is written per page as `<stem>.md`, atomically. Rerunning the same command resumes: finished pages are
+   skipped. Pages with no usable answer are listed in `out/.wasabi-read/run-report.json`.
+
+## Benchmark submission
+
+The MDPBench submission includes additional inference components provided to the organizers. The complete inference
+code is maintained in a [private repository](https://github.com/sionic-ai/Wasabi-30B).
+The code included here runs independently of that repository.
+
+## Limitations
 
-The base model is [Muse Glimmer 30B](https://huggingface.co/meta-models/Muse-Glimmer-30B), revision `97c77dff50b2797bcc558fa2d909761dbc575c59`. Its Apache-2.0 licence and publisher usage policy are included in `notices/`.
+- Japanese-focused. Other languages are not a target.
+- The `transformers` engine has not been measured and is not guaranteed to follow the vLLM path's image size and
+  decoding; use the vLLM or endpoint engine for the behaviour documented here.
+- Each orientation decision comes from one greedy probe per rotation, so a different serving stack (attention backend,
+  CUDA build, batching) can change the turn on a few pages.
+- Ruby appears only as the model writes it inline; there is no separate ruby pass.
+- Photographed pages and very small print can be misread.
+- The reader package runs on Linux and macOS only (it uses POSIX file locks). Its local vLLM engine starts the servers
+  with the FlashInfer vision-encoder attention backend; to use another backend, serve the model yourself and use
+  endpoint mode.
+
+## License
+
+- This model and the reader package: GNU Affero General Public License v3.0 (`LICENSE`).
+- Base model Muse-Glimmer-30B: Apache License 2.0 (`notices/Muse-Glimmer-30B-LICENSE.txt`), together with its
+  publisher's usage policy (`notices/Muse-Glimmer-30B-USAGE_POLICY.md`).
+- UVDoc code (commit 4c9b82b5): MIT License, Copyright (c) 2023 Tanguy MAGNE. The reader downloads the UVDoc code
+  and its pretrained weights at first use and does not redistribute them. The weights carry no separate licence
+  statement and remain under their upstream terms.
+
+Copyright 2026 Sionic AI Inc.

SHA256SUMS

@@ -1,11 +1,27 @@
-a0e948ca693c63e0b5139f66bd709003cbcf8bc764acb1ee687a552885c8fe2c  .gitattributes
-d358c3e18ad2722f9784f5f5350181005b5d5779d54abf35ba6b87c4743fc7ab  .gitignore
 0d96a4ff68ad6d4b6f1f30f713b18d5184912ba8dd389f86aa7710db079abcb0  LICENSE
-e4e2e4db780cbe91dc4e739e614a9d8c03953c39b5e4ef324a84393d0a5ade95  NOTICE
-4c413ad09db035795702d4a57e559971d89181a165b8b6232361f9ea8dda5b6e  README.md
+9a696bb21eb15253ed57505ef28b1cf24b21232808ee13336ed7244a6a5ea9b9  NOTICE
+b374b8bfb0cb6eecf7f2a1d9decad8f87bc27c332c4094579c2c34196ef53d26  README.md
 114f55ebdc1804c1af371197b9fdf2d6bb925966c9dfe46b73782a71bc07965e  chat_template.jinja
 1c235df3179388bb56e522a25543d1f9e417a25e71b162887378a4362c5e4dbc  config.json
 519ca0cad3bf6cb10c4f74dfb64786f651533bae2f316c609d66e0bcf5adfde6  generation_config.json
+0d96a4ff68ad6d4b6f1f30f713b18d5184912ba8dd389f86aa7710db079abcb0  inference/LICENSE
+9a696bb21eb15253ed57505ef28b1cf24b21232808ee13336ed7244a6a5ea9b9  inference/NOTICE
+70d546c82d5c2cf88a3dc5f5c4a1772c5c49ededff0ddf2cb92f3cd88cc32c51  inference/README.md
+b47659c857a9df27fcac4eaeade20ec382f733e176350bc8ff38a2d1ea0fc6ac  inference/patch_vllm_max_image_tokens.py
+22c09a27433e96357534f2b8795ecc21a749e534fee895b9d5967f17109ae26c  inference/pyproject.toml
+835cef3a918b418b121c014acc350d08f58410c8692d45545e21bef603d81b46  inference/wasabi_read.py
+7f94773ff631125c1bea6cdaa5a2214d4032a79163ecbdafb331451f52ec60e4  inference/wasabi_read/__init__.py
+377ad9282dcd4e44df878094cf3b1606238059c346cf79ca620567bde2ce7a5e  inference/wasabi_read/cli.py
+ba4a7fb751896db1d9acf402a2c32412ba7c64f0a481028d8fb9251dd5877d02  inference/wasabi_read/dewarp.py
+53d23fe1224e771390ed9f453dc2304263eb93aa487ccfd1cd22cd20860d21b7  inference/wasabi_read/engine.py
+ee8210b9034290c139f1ee99ae1f31fb43960369111315c01984e9d77a4132cb  inference/wasabi_read/identity.py
+c4e1ee6fc0e09276d6ec75d9b6832c7541359a5714871be38d7db5b4bc7b924b  inference/wasabi_read/inputs.py
+930700f660bef1973d05459f34854df6055c14b98e4ba01f211d00d49d2ea607  inference/wasabi_read/orient.py
+647386ef8705c3841606ceb0b5411b6347f06b9fa67d92646226bc942b8d347f  inference/wasabi_read/output.py
+1f80d2ca0bcb5c815ab15f1fe8d6a7fc16d2c2c305ffeabcec90eca4292d97f8  inference/wasabi_read/prompts/draft.txt
+ad089da4c37eb9a25a5bf56dd4124497d2258c282ae0b593112984e10cd7d159  inference/wasabi_read/prompts/orient-upright.txt
+7839b0fc9685bb3a727fe1c0b1122c66ca80893067bcb17e5aa54e8998efcc67  inference/wasabi_read/reliability.py
+aa27844934edb224e0ebee66c8baf1f37c07229d58a94f2fe1cf8152a148b4b7  inference/wasabi_read/views.py
 0a5fdba915e499084969163518830e320040b0f2e03eb43843bbb71be450c5a7  model-00001-of-00002.safetensors
 20dfe7774a3ba1194b853e54fac1fb589bdc28872198b6e80c6c37ea32ef21b4  model-00002-of-00002.safetensors
 79f6028c3b5544f6be46607b8580d7376bf68bdc66647480fd3bfa520ad9efa3  model.safetensors.index.json

inference/LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

inference/NOTICE

@@ -0,0 +1,18 @@
+Wasabi-30B
+Copyright 2026 Sionic AI Inc.
+
+Wasabi-30B is released under the GNU Affero General Public License v3.0 (see LICENSE).
+
+This model is a fine-tune of Muse-Glimmer-30B (https://huggingface.co/meta-models/Muse-Glimmer-30B,
+revision 97c77dff50b2797bcc558fa2d909761dbc575c59), licensed under the Apache License, Version 2.0
+(notices/Muse-Glimmer-30B-LICENSE.txt). The base model snapshot has no NOTICE file. Modification: the base
+weights were fine-tuned with LoRA for Japanese page transcription and the adapter was merged into BF16 weights.
+The base model's publisher also publishes a usage policy, reproduced in notices/Muse-Glimmer-30B-USAGE_POLICY.md.
+
+The page reader wasabi_read (orientation check, UVDoc flattening, whole-page read and per-page output) is released
+under the GNU Affero General Public License v3.0.
+
+UVDoc (https://github.com/tanguymagne/UVDoc), code at commit 4c9b82b537057aff2526e6dd118a847cdd072e82: MIT License,
+Copyright (c) 2023 Tanguy MAGNE. wasabi_read downloads the UVDoc code and its pretrained weights
+(model/best_model.pkl) from that commit at first use and does not redistribute them. The UVDoc repository carries
+no weights-specific licence statement; the weights remain under their own terms.

inference/README.md

@@ -0,0 +1,95 @@
+# wasabi-read
+
+Reads a directory of page images (.jpg, .jpeg, .png) and writes one Markdown file per page with Wasabi-30B.
+The supported setup uses one checkpoint, Wasabi-30B, for every model step. Per page: an orientation check by
+Wasabi-30B itself (a 4-way upright probe at 4,096 image tokens; a turn is applied only at margin >= 5.0), UVDoc dewarp
+on CPU, the whole page read at 8,192 image tokens (greedy), and a temperature ladder when a first answer is degenerate.
+
+## Install
+
+    pip install -e "./inference[dewarp]"
+
+Python 3.10+. Endpoint and local runs both dewarp on the local CPU, so the `dewarp` extra (torch and OpenCV) is needed
+in both modes; without OpenCV the run refuses. The OpenCV, torch, numpy and Pillow versions and the UVDoc pins are part
+of the output identity, so a rerun with other versions is refused and one output directory never mixes them.
+A local GPU run needs the vLLM build of commit 6adad087 (released vLLM 0.26.0 has no muse_glimmer model); an endpoint
+run needs no vLLM. After installing that build, run `python inference/patch_vllm_max_image_tokens.py --apply` with the
+Python of the vLLM environment: unpatched, its processor rejects the `max_image_tokens` setting the servers are started
+with. It edits one file, pinned by sha256 (`--check`, `--revert`); a server you start yourself for endpoint mode needs it
+too. Download the weights with `huggingface-cli download`.
+
+Tested environment: opencv-python-headless 5.0.0.93, torch 2.13.0+cu130, numpy 2.3.5, Pillow 13.0.0,
+vllm 0.26.1rc1.dev769+g6adad0876, transformers 5.15.0, openai 3.37.0 (the package itself talks to servers with the
+Python standard library; openai was present, not required).
+
+The package sets `NUMPY_MADVISE_HUGEPAGE=0` at import unless you set it yourself: with numpy's default, a Linux host with
+transparent huge pages on `madvise` can stall in the kernel while dewarping large page images. The output is the same
+either way.
+
+## Configuration
+
+- `WASABI_READ_API_KEY`: optional API key, sent to both the reader and the orientation endpoint. Set it in the
+  environment and keep the value out of commands, scripts and documentation.
+- `WASABI_READ_CACHE`: directory for the downloaded UVDoc files. The default is `~/.cache/wasabi-read`, and the files go
+  into a pinned `uvdoc-<revision>` subdirectory. Page outputs and run caches stay under the output directory you pass.
+- `--uvdoc-dir PATH`: keep the UVDoc files in PATH in place of the default cache. In the normal fetch mode, missing
+  pinned files are downloaded and every file is verified.
+- `--uvdoc-source vendored --uvdoc-dir PATH`: use an existing local UVDoc copy without downloading. The code and weights
+  it needs must pass the built-in size and sha256 checks.
+
+## Orientation
+
+The orientation check runs on its own server at 4,096 image tokens, before the reader starts. It uses Wasabi-30B and
+turns a page only at margin >= 5.0. A turn is a decision from one greedy probe per rotation: a different serving stack
+(attention backend, CUDA build, batching) can change it on a few pages.
+
+## Run on a CPU-only machine (endpoint mode)
+
+Everything except the 30B forward passes runs on the local CPU. Point the package at two OpenAI-compatible servers, both
+serving Wasabi-30B and started with `--reasoning-parser muse_glimmer`: the reader, with
+`--mm-processor-kwargs '{"max_image_tokens": 8192}'`, and the orientation check, with
+`--mm-processor-kwargs '{"max_image_tokens": 4096}'`. Name what each server serves with `--endpoint-revision` and
+`--orient-endpoint-revision`: the URLs and revisions are part of the output identity, so a rerun against another server
+is refused and one output directory never mixes servers. If the servers need a key, set `WASABI_READ_API_KEY`
+(see Configuration).
+
+    python inference/wasabi_read.py pages/ out/ --engine endpoint --endpoint-url http://gpu-host:8000 --endpoint-revision wasabi-30b-v1.0 --orient-endpoint-url http://gpu-host:8001 --orient-endpoint-revision wasabi-30b-v1.0
+
+`--plan` prints the stages and exits without loading a model.
+
+    python inference/wasabi_read.py pages/ out/ --engine endpoint --endpoint-url http://gpu-host:8000 --endpoint-revision wasabi-30b-v1.0 --orient-endpoint-url http://gpu-host:8001 --orient-endpoint-revision wasabi-30b-v1.0 --plan
+
+## Run on a local GPU (vllm engine)
+
+The package starts and stops the local vLLM servers itself (the orientation check first, then the reader, both from the
+same weights). The engine kind and its version, and the reasoning parser (vLLM's built-in `muse_glimmer`, or the sha256
+of a `--reasoning-plugin` file), are part of the output and orientation identity, so a rerun on another engine or
+parser is refused.
+
+    python inference/wasabi_read.py pages/ out/ --engine vllm --model-dir /models/Wasabi-30B --tensor-parallel-size 1 --whole-upscale-tokens 8192
+
+`--engine transformers` loads the model in-process. It was not part of the measured runs and does not follow the
+`--engine vllm` path: the image-token budget is set on the processor when the model is loaded (not through a server),
+the sampling seed is applied with `torch.manual_seed`, and the raw decoded text is used, with no server-side
+reasoning-channel split and no repetition-detection stop. Use it for a few pages only; its results are not comparable
+to the vLLM runs.
+
+## Resume and exit codes
+
+Each page is written as soon as it finishes (`<stem>.md`, atomic), with a sidecar under `out/.wasabi-read/`. Rerun the same
+command to resume: finished pages are skipped, orientation and dewarp results are reused, and when nothing is left no
+engine is started. An existing output that this input or package settings did not write is refused unless
+`--overwrite-stale` is given. A page whose final answer is degenerate, empty or failed is not written and is listed with
+its reason in `out/.wasabi-read/run-report.json`.
+
+| exit | meaning |
+|---|---|
+| 0 | every page has an output |
+| 2 | refusal (bad input or options, stale or locked output directory) |
+| 4 | incomplete: some pages have no usable output; rerun to retry them |
+
+## Licence
+
+Code: GNU Affero General Public License v3.0 (`LICENSE`, `NOTICE`). UVDoc code is MIT (Copyright (c) 2023 Tanguy MAGNE);
+its pretrained weights are downloaded from the pinned commit at first use (size and sha256 checked before they are loaded)
+and keep their own terms.

inference/patch_vllm_max_image_tokens.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Patch the vLLM build of commit 6adad087 so its Muse-Glimmer processor accepts ``max_image_tokens``.
+
+Why: wasabi-read starts its vLLM servers with ``--mm-processor-kwargs '{"max_image_tokens": N}'`` (the whole-page
+image-token budget). In vLLM commit 6adad08767583f52eb4d2122111af0bf638ed5e6, ``MuseGlimmerProcessor.__init__``
+builds a default ``MuseGlimmerImageProcessor()`` (``max_image_tokens`` 4096) and forwards every unknown keyword to
+``ProcessorMixin.__init__``, which raises ``TypeError`` on ``max_image_tokens``, so the server does not start. The rest
+of vLLM already reads ``image_processor.max_image_tokens``. This script makes one anchored edit to that ``__init__``:
+it takes the key out before ``super().__init__`` and gives it to the image processor. Without the key, behaviour is
+unchanged. Run it once after installing vLLM, with the Python of the environment that holds vLLM; any server you start
+yourself with that kwarg (endpoint mode) needs it too.
+
+The edit is keyed to exact file bytes: ``--apply`` acts only on the pinned ORIGINAL sha256 and verifies the pinned
+PATCHED sha256 after writing; an already-patched file is a no-op (exit 0); any other file is refused (exit 2) with
+nothing changed. ``--apply`` keeps the original next to the file (suffix ``.orig``); ``--revert`` restores it.
+
+  python inference/patch_vllm_max_image_tokens.py --check|--apply|--revert [--venv PREFIX]
+
+PREFIX defaults to the running interpreter's ``sys.prefix``; the file is found under
+``PREFIX/lib/python3*/site-packages/vllm/transformers_utils/processors/muse_glimmer.py``.
+Standard library only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import hashlib
+import os
+import sys
+import tempfile
+
+# vLLM commit 6adad08767583f52eb4d2122111af0bf638ed5e6, file of 582 lines
+ORIGINAL_SHA256 = "66ff8858c571bb9b89702aafdfcc7f49271fe4e8e42a3d1ae7767624957ae96c"
+PATCHED_SHA256 = "ee2033943a2fb0eb45333291466f3dfb3b1a8f914628a08990733fa0ab9c08ab"
+
+REL_PATH = "vllm/transformers_utils/processors/muse_glimmer.py"
+BACKUP_SUFFIX = ".orig"
+
+ANCHOR_OLD = (
+    "        if image_processor is None:\n"
+    "            image_processor = MuseGlimmerImageProcessor()\n"
+    "        if video_processor is None:\n"
+)
+ANCHOR_NEW = (
+    "        # wasabi-read (inference/patch_vllm_max_image_tokens.py): pass max_image_tokens to the image processor.\n"
+    "        _requested_max_image_tokens = kwargs.pop(\"max_image_tokens\", None)\n"
+    "        if image_processor is None:\n"
+    "            if _requested_max_image_tokens is None:\n"
+    "                image_processor = MuseGlimmerImageProcessor()\n"
+    "            else:\n"
+    "                image_processor = MuseGlimmerImageProcessor(\n"
+    "                    max_image_tokens=int(_requested_max_image_tokens))\n"
+    "        elif _requested_max_image_tokens is not None:\n"
+    "            image_processor.max_image_tokens = int(_requested_max_image_tokens)\n"
+    "        if video_processor is None:\n"
+)
+
+RC_OK = 0
+RC_REFUSED = 2
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def locate(prefix: str) -> str:
+    hits = sorted(glob.glob(os.path.join(prefix, "lib", "python3*", "site-packages", REL_PATH)))
+    if len(hits) != 1:
+        raise FileNotFoundError(f"expected exactly one {REL_PATH} under {prefix}, found {len(hits)}: {hits}")
+    return hits[0]
+
+
+def transform(data: bytes) -> bytes:
+    text = data.decode("utf-8")
+    n = text.count(ANCHOR_OLD)
+    if n != 1:
+        raise ValueError(f"anchor found {n} times (need exactly 1)")
+    return text.replace(ANCHOR_OLD, ANCHOR_NEW).encode("utf-8")
+
+
+def atomic_write(path: str, data: bytes, *, like: str | None = None) -> None:
+    """Temp file in the same directory, fsync, then os.replace; keeps the permission bits of ``like`` (default: path)."""
+    mode = os.stat(like or path).st_mode & 0o7777
+    fd, tmp = tempfile.mkstemp(prefix=".patch-", dir=os.path.dirname(path))
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(data)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.chmod(tmp, mode)
+        os.replace(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+
+
+def state(sha: str, orig: str, patched: str) -> str:
+    if sha == orig:
+        return "original"
+    if sha == patched:
+        return "patched"
+    return "unknown"
+
+
+def do_check(path: str, orig: str, patched: str) -> int:
+    with open(path, "rb") as fh:
+        sha = sha256_bytes(fh.read())
+    st = state(sha, orig, patched)
+    print(f"{st} {sha} {path}")
+    return RC_OK if st != "unknown" else RC_REFUSED
+
+
+def do_apply(path: str, orig: str, patched: str) -> int:
+    with open(path, "rb") as fh:
+        data = fh.read()
+    sha = sha256_bytes(data)
+    st = state(sha, orig, patched)
+    if st == "patched":
+        print(f"already patched {sha} {path}")
+        return RC_OK
+    if st == "unknown":
+        print(f"REFUSED: {path} sha {sha} is neither the pinned original {orig} nor the pinned patched {patched}; "
+              f"nothing changed", file=sys.stderr)
+        return RC_REFUSED
+    new = transform(data)
+    new_sha = sha256_bytes(new)
+    if new_sha != patched:
+        print(f"REFUSED: transformed sha {new_sha} != pinned patched {patched}; nothing changed", file=sys.stderr)
+        return RC_REFUSED
+    backup = path + BACKUP_SUFFIX
+    if os.path.exists(backup):
+        with open(backup, "rb") as fh:
+            bsha = sha256_bytes(fh.read())
+        if bsha != orig:
+            print(f"REFUSED: existing backup {backup} sha {bsha} != pinned original; nothing changed", file=sys.stderr)
+            return RC_REFUSED
+    else:
+        atomic_write(backup, data, like=path)
+    atomic_write(path, new)
+    with open(path, "rb") as fh:
+        final = sha256_bytes(fh.read())
+    if final != patched:
+        print(f"ERROR: post-write sha {final} != pinned patched {patched}", file=sys.stderr)
+        return RC_REFUSED
+    print(f"applied {orig} -> {final} {path} (backup {backup})")
+    return RC_OK
+
+
+def do_revert(path: str, orig: str, patched: str) -> int:
+    with open(path, "rb") as fh:
+        sha = sha256_bytes(fh.read())
+    st = state(sha, orig, patched)
+    if st == "original":
+        print(f"already original {sha} {path}")
+        return RC_OK
+    if st == "unknown":
+        print(f"REFUSED: {path} sha {sha} is not the pinned patched sha; nothing changed", file=sys.stderr)
+        return RC_REFUSED
+    backup = path + BACKUP_SUFFIX
+    if not os.path.exists(backup):
+        print(f"REFUSED: no backup {backup}; nothing changed", file=sys.stderr)
+        return RC_REFUSED
+    with open(backup, "rb") as fh:
+        bdata = fh.read()
+    if sha256_bytes(bdata) != orig:
+        print(f"REFUSED: backup {backup} sha != pinned original; nothing changed", file=sys.stderr)
+        return RC_REFUSED
+    atomic_write(path, bdata)
+    with open(path, "rb") as fh:
+        final = sha256_bytes(fh.read())
+    if final != orig:
+        print(f"ERROR: post-revert sha {final} != pinned original {orig}", file=sys.stderr)
+        return RC_REFUSED
+    print(f"reverted {patched} -> {final} {path}")
+    return RC_OK
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--venv", default=sys.prefix,
+                    help="prefix of the environment that holds vLLM (default: this interpreter's sys.prefix)")
+    mode = ap.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--check", action="store_true")
+    mode.add_argument("--apply", action="store_true")
+    mode.add_argument("--revert", action="store_true")
+    ap.add_argument("--expect-shas", nargs=2, metavar=("ORIG", "PATCHED"), help=argparse.SUPPRESS)  # test seam only
+    args = ap.parse_args(argv)
+    orig, patched = args.expect_shas or (ORIGINAL_SHA256, PATCHED_SHA256)
+    try:
+        path = locate(args.venv)
+    except FileNotFoundError as exc:
+        print(f"REFUSED: {exc}", file=sys.stderr)
+        return RC_REFUSED
+    if args.check:
+        return do_check(path, orig, patched)
+    if args.apply:
+        return do_apply(path, orig, patched)
+    return do_revert(path, orig, patched)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

inference/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wasabi-read"
+version = "0.1.0"
+description = "Read a directory of page images into one Markdown file per page with Wasabi-30B."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+dependencies = ["pillow>=10", "numpy>=1.26"]
+
+[project.optional-dependencies]
+# dewarp: UVDoc on CPU, part of every normal run; install the package as ./inference[dewarp]. OpenCV is required
+# (the upstream resize).
+dewarp = ["torch>=2.3", "opencv-python-headless>=4.8"]
+# local CPU/GPU reads without a server (unmeasured, few pages only)
+transformers = ["torch>=2.3", "transformers>=5.15"]
+test = ["pytest>=8"]
+
+[project.scripts]
+wasabi-read = "wasabi_read.cli:main"
+
+[tool.setuptools]
+packages = ["wasabi_read"]
+
+# the two prompt files ship inside the package, so a regular (non-editable) install finds them
+[tool.setuptools.package-data]
+wasabi_read = ["prompts/*.txt"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [".", "tests"]

inference/wasabi_read.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+"""Launcher: python wasabi_read.py INPUT_DIR OUTPUT_DIR [options]."""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from wasabi_read.cli import main  # noqa: E402
+
+if __name__ == "__main__":
+    sys.exit(main())

inference/wasabi_read/__init__.py

@@ -0,0 +1,19 @@
+"""wasabi_read: read a directory of page images into one Markdown file per page (Wasabi-30B)."""
+import os
+
+# numpy reads this once, at its first import, so it is set before any submodule can import numpy or torch. Default numpy
+# madvises huge pages for large arrays; on a Linux host with transparent huge pages on madvise, every fault on a large
+# page array can then stall in kernel compaction and the CPU dewarp crawls. Off, the output bytes are unchanged. A value
+# the user already set is kept.
+os.environ.setdefault("NUMPY_MADVISE_HUGEPAGE", "0")
+
+__version__ = "0.1.0"
+CODE_VERSION = "wasabi-read-" + __version__
+
+
+class PortError(RuntimeError):
+    """A refusal: bad input, bad configuration, or a stale/foreign output directory (exit 2)."""
+
+
+class IncompleteOutput(PortError):
+    """The run finished but some pages have no usable output (exit 4)."""

inference/wasabi_read/cli.py

@@ -0,0 +1,426 @@
+"""wasabi_read command line: INPUT_DIR OUTPUT_DIR -> one Markdown file per page image.
+
+Exit codes: 0 ok (every page has output), 2 refusal (bad input, bad configuration, stale or locked output),
+4 incomplete (some page has no usable output; its reason is in the run report).
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from . import CODE_VERSION, IncompleteOutput, PortError
+from . import dewarp as dw
+from . import engine as eng
+from . import orient as ori
+from .identity import (PROMPT_PINS, check_model_tree, identity_sha, load_prompt, package_identity)
+from .inputs import collect_images, sha256_file
+from .output import OutputStore, atomic_write_bytes
+from .reliability import page_verdict, read_page
+from .views import ALLOWED_TOKENS, png_bytes, prepare_whole
+
+EXIT_OK, EXIT_REFUSED, EXIT_INCOMPLETE = 0, 2, 4
+ENGINES = ("vllm", "endpoint", "transformers")
+
+
+@dataclass
+class Deps:
+    """Test seams: a dewarp backend (PIL -> PIL) with its identity, and an engine opener (EngineSpec -> context
+    manager of a Reader)."""
+    dewarp: Callable | None = None
+    open_reader: Callable | None = None
+    dewarp_identity: dict | None = None
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="wasabi-read", description="Read a directory of page images into one Markdown file per page.")
+    p.add_argument("input_dir", help="directory of .jpg/.jpeg/.png pages (searched recursively)")
+    p.add_argument("output_dir", help="receives <stem>.md per page plus a .wasabi-read/ state directory")
+    p.add_argument("--engine", choices=ENGINES, default="vllm",
+                   help="vllm = spawn a local vLLM server; endpoint = call an OpenAI-compatible URL (CPU-only "
+                        "machines); transformers = local, unmeasured, few pages only")
+    p.add_argument("--endpoint-url", help="reader endpoint base URL (engine endpoint)")
+    p.add_argument("--endpoint-revision",
+                   help="what the reader endpoint serves, e.g. the model revision or its folder digest (engine "
+                        "endpoint, required): recorded in the output identity with the URL")
+    p.add_argument("--model-dir", help="Wasabi-30B folder (engines vllm and transformers; hash-checked)")
+    p.add_argument("--served-model-name", default="wasabi-30b", help="model name sent in requests")
+    p.add_argument("--orient-judge", choices=("self", "base"), default="self",
+                   help="orientation judge: self = Wasabi-30B itself, turn floor 5.0 (default); base = the base "
+                        "Muse-Glimmer-30B, turn floor 2.0")
+    p.add_argument("--orient-model-dir", help="base Muse-Glimmer-30B folder (engines vllm/transformers, judge base)")
+    p.add_argument("--orient-endpoint-url",
+                   help="judge endpoint URL (engine endpoint, required): a server started with max_image_tokens "
+                        f"{ori.ORIENT_IMAGE_TOKENS}, serving Wasabi-30B (judge self) or the base model (judge base)")
+    p.add_argument("--orient-endpoint-revision",
+                   help="what the judge endpoint serves (engine endpoint, required): recorded in the orientation "
+                        "identity with the URL")
+    p.add_argument("--orient-served-model-name", default=None,
+                   help="model name sent to the judge (default: --served-model-name for judge self, "
+                        "muse-glimmer-30b-base for judge base)")
+    p.add_argument("--whole-upscale-tokens", type=int, choices=ALLOWED_TOKENS, default=8192,
+                   help="whole-page image tokens; 4096 = the native whole view (no enlargement)")
+    p.add_argument("--view", choices=("whole",), default="whole", help="page view (the whole page)")
+    p.add_argument("--uvdoc-source", choices=("fetch", "vendored"), default="fetch",
+                   help="fetch = download the pinned UVDoc commit at first use (size + sha256 checked before any "
+                        "unpickle); vendored = use a local checkout given by --uvdoc-dir")
+    p.add_argument("--uvdoc-dir", help="UVDoc checkout directory (vendored: required; fetch: cache location)")
+    p.add_argument("--tensor-parallel-size", type=int, default=1)
+    p.add_argument("--reasoning-plugin", help="path of a vLLM reasoning-parser plugin file (engine vllm)")
+    p.add_argument("--max-tokens", type=int, default=eng.GLIMMER_MAX_TOKENS, help="completion-token cap per request")
+    p.add_argument("--page-budget-s", type=float, default=3600.0, help="wall budget per page, all attempts")
+    p.add_argument("--request-timeout-s", type=float, default=1800.0)
+    p.add_argument("--concurrency", type=int, default=4, help="pages in flight")
+    p.add_argument("--plan", action="store_true", help="print the stages and exit; loads no model, starts no engine")
+    p.add_argument("--overwrite-stale", action="store_true",
+                   help="replace existing outputs that this input/package identity did not write (otherwise refused)")
+    p.add_argument("--report", help="run report JSON path (default OUTPUT_DIR/.wasabi-read/run-report.json)")
+    return p
+
+
+def validate(args: argparse.Namespace) -> None:
+    if args.concurrency < 1:
+        raise PortError("--concurrency must be >= 1")
+    if args.engine == "endpoint":
+        if not args.endpoint_url or not args.endpoint_revision:
+            raise PortError("--engine endpoint needs --endpoint-url and --endpoint-revision (what that server serves)")
+        if not args.orient_endpoint_url or not args.orient_endpoint_revision:
+            raise PortError("--engine endpoint needs --orient-endpoint-url and --orient-endpoint-revision: a judge "
+                            f"server started with max_image_tokens {ori.ORIENT_IMAGE_TOKENS}, serving Wasabi-30B "
+                            "(judge self) or the base model (judge base)")
+    else:
+        if not args.model_dir:
+            raise PortError(f"--engine {args.engine} needs --model-dir")
+        if args.orient_judge == "base" and not args.orient_model_dir:
+            raise PortError("--orient-judge base needs --orient-model-dir (the base Muse-Glimmer-30B folder), "
+                            "or use --orient-judge self")
+    if args.reasoning_plugin:
+        if args.engine != "vllm":
+            raise PortError("--reasoning-plugin applies to --engine vllm only (an endpoint's parser is the server's, "
+                            "named by its revision)")
+        if not Path(args.reasoning_plugin).is_file():
+            raise PortError(f"--reasoning-plugin file does not exist: {args.reasoning_plugin}")
+    if args.uvdoc_source == "vendored" and not args.uvdoc_dir:
+        raise PortError("--uvdoc-source vendored needs --uvdoc-dir")
+
+
+def plan_text(args: argparse.Namespace, images: list[Path], existing: int) -> str:
+    judge = "base Muse-Glimmer-30B" if args.orient_judge == "base" else "Wasabi-30B itself"
+    lines = [f"wasabi_read {CODE_VERSION} plan (no model loaded, no engine started)",
+             f"input: {len(images)} page image(s) in {args.input_dir}",
+             f"output: {args.output_dir} ({existing} <stem>.md already present; resume decides at run time)",
+             f"engine: {args.engine}",
+             f"stage 1 orient: 4-way upright probe on every page at {ori.ORIENT_IMAGE_TOKENS} image tokens, judge = "
+             f"{judge}, turn applied only if margin >= {ori.ORIENT_FLOORS[args.orient_judge]:g}",
+             f"stage 2 dewarp: UVDoc on CPU, source = {args.uvdoc_source}",
+             f"stage 3 read: whole page at {args.whole_upscale_tokens} image tokens, greedy, degeneration ladder "
+             f"{', '.join(str(t) for t in (0.1, 0.3, 0.5, 0.8))}",
+             "stage 4 write: <stem>.md per finished page (atomic), sidecar + journal under .wasabi-read/"]
+    return "\n".join(lines)
+
+
+def _settings(args: argparse.Namespace, dewarp_ident: dict | None = None) -> dict[str, Any]:
+    return {"dewarp": dewarp_ident,"view": args.view, "whole_upscale_tokens": args.whole_upscale_tokens, "orient_judge": args.orient_judge,
+            "orient_floor": ori.ORIENT_FLOORS[args.orient_judge], "orient_variant": ori.ORIENT_VARIANT,
+            "orient_image_tokens": ori.ORIENT_IMAGE_TOKENS, "orient_preprocess": ori.ORIENT_PREPROCESS,
+            "uvdoc_commit": dw.UVDOC_COMMIT, "max_tokens": args.max_tokens, "ladder": [0.1, 0.3, 0.5, 0.8],
+            "serving": serving_identity(args)}
+
+
+def _dist_version(dist: str) -> str | None:
+    import importlib.metadata as md
+    try:
+        return md.version(dist)
+    except md.PackageNotFoundError:
+        return None
+
+
+def serving_identity(args: argparse.Namespace) -> dict[str, Any]:
+    """How the answers are produced and split into reasoning and content: the engine kind and the effective reasoning
+    parser (vLLM's built-in muse_glimmer with the vLLM version, or a plugin file by its sha256). An endpoint's parser
+    is the server's, covered by the endpoint revisions."""
+    if args.engine == "endpoint":
+        return {"engine": "endpoint", "reasoning_parser": {"source": "server side (endpoint revision)"}}
+    if args.engine == "transformers":
+        return {"engine": "transformers", "transformers": _dist_version("transformers"),
+                "reasoning_parser": {"source": "in-process split (no server parser)"}}
+    parser: dict[str, Any] = {"name": "muse_glimmer"}
+    if args.reasoning_plugin:
+        parser.update(source="plugin", plugin_sha256=sha256_file(Path(args.reasoning_plugin)))
+    else:
+        parser.update(source="vllm built-in")
+    return {"engine": "vllm", "vllm": _dist_version("vllm"), "reasoning_parser": parser}
+
+
+def _endpoint(url: str, revision: str) -> dict[str, str]:
+    return {"url": url.rstrip("/"), "revision": revision}
+
+
+def _judge_served_name(args: argparse.Namespace) -> str:
+    if args.orient_served_model_name:
+        return args.orient_served_model_name
+    return args.served_model_name if args.orient_judge == "self" else "muse-glimmer-30b-base"
+
+
+def _model_identity(args: argparse.Namespace, state_dir: Path) -> dict[str, Any]:
+    """What serves the reads and the orientation probe: local folders by their file digests (the reader's pinned
+    files are checked), endpoints by URL plus the declared revision."""
+    judge: dict[str, Any] = {"mode": args.orient_judge, "served_name": _judge_served_name(args),
+                             "image_tokens": ori.ORIENT_IMAGE_TOKENS}
+    if args.engine == "endpoint":
+        judge["endpoint"] = _endpoint(args.orient_endpoint_url, args.orient_endpoint_revision)
+        return {"served_model_name": args.served_model_name, "tree": None,
+                "endpoint": _endpoint(args.endpoint_url, args.endpoint_revision), "judge": judge}
+    state_dir.mkdir(parents=True, exist_ok=True)
+    tree = check_model_tree_cached(Path(args.model_dir), state_dir / "model-tree.json")
+    if args.orient_judge == "self":
+        judge["tree_sha256"] = tree["tree_sha256"]
+    else:
+        judge["tree_sha256"] = check_model_tree_cached(Path(args.orient_model_dir), state_dir / "orient-model-tree.json",
+                                                       pins={})["tree_sha256"]
+    return {"served_model_name": args.served_model_name, "tree": tree, "endpoint": None, "judge": judge}
+
+
+def orient_identity(judge: dict[str, Any], floor: float, serving: dict[str, Any] | None = None) -> str:
+    """The orientation-decision cache key: the judge (weights digest, or endpoint URL and revision; served name;
+    processor geometry), the serving identity (engine kind, reasoning parser), the prompt pin, the floor, the variant,
+    the image preprocessing and the probe request."""
+    probe = eng.build_probe_payload("", b"", "")
+    request = {k: v for k, v in probe.items() if k not in ("model", "messages")}
+    return hashlib.sha256(json.dumps(
+        {"judge": judge, "serving": serving, "prompt": PROMPT_PINS["orient-upright.txt"], "floor": floor,
+         "variant": ori.ORIENT_VARIANT,
+         "preprocess": ori.ORIENT_PREPROCESS, "request": request}, sort_keys=True).encode()).hexdigest()
+
+
+def check_model_tree_cached(model_dir: Path, cache_file: Path, pins: dict | None = None) -> dict:
+    """check_model_tree, remembered by the (name, size, mtime) signature of the files that identify the model, so a
+    resume does not rehash 60 GB."""
+    from .identity import MODEL_FILE_PINS
+    names = sorted(MODEL_FILE_PINS if pins is None else pins)
+    sig = hashlib.sha256(json.dumps(
+        [(p.name, p.stat().st_size, p.stat().st_mtime_ns)
+         for p in (sorted(model_dir / n for n in names) if names else sorted(model_dir.iterdir())) if p.is_file()],
+        sort_keys=True).encode()).hexdigest() \
+        if model_dir.is_dir() else ""
+    if cache_file.is_file():
+        try:
+            hit = json.loads(cache_file.read_text(encoding="ascii"))
+            if hit.get("signature") == sig and sig:
+                return hit["result"]
+        except ValueError:
+            pass
+    result = check_model_tree(model_dir, pins=pins)
+    atomic_write_bytes(cache_file, (json.dumps({"signature": sig, "result": result}) + "\n").encode("ascii"))
+    return result
+
+
+def _load_png_image(path: Path):
+    from PIL import Image
+    with Image.open(path) as im:
+        return im.convert("RGB")
+
+
+def _spec(args, role: str) -> eng.EngineSpec:
+    import os
+    key = os.environ.get("WASABI_READ_API_KEY")
+    if role == "judge":
+        judge_dir = args.model_dir if args.orient_judge == "self" else args.orient_model_dir
+        return eng.EngineSpec(kind=args.engine, served_name=_judge_served_name(args),
+                              model_dir=judge_dir, url=args.orient_endpoint_url, api_key=key,
+                              tensor_parallel=args.tensor_parallel_size, image_tokens=ori.ORIENT_IMAGE_TOKENS,
+                              max_tokens=eng.PROBE_MAX_TOKENS, reasoning_plugin=args.reasoning_plugin,
+                              request_timeout_s=args.request_timeout_s)
+    return eng.EngineSpec(kind=args.engine, served_name=args.served_model_name, model_dir=args.model_dir,
+                          url=args.endpoint_url, api_key=key, tensor_parallel=args.tensor_parallel_size,
+                          image_tokens=args.whole_upscale_tokens, max_tokens=args.max_tokens,
+                          reasoning_plugin=args.reasoning_plugin, request_timeout_s=args.request_timeout_s)
+
+
+def run(args: argparse.Namespace, deps: Deps | None = None) -> int:
+    deps = deps or Deps()
+    opener = deps.open_reader or eng.open_reader
+    validate(args)
+    images = collect_images(Path(args.input_dir))
+    out_dir = Path(args.output_dir)
+    if args.plan:
+        existing = sum(1 for im in images if (out_dir / (im.stem + ".md")).is_file())
+        print(plan_text(args, images, existing))
+        return EXIT_OK
+    draft_prompt = load_prompt("draft.txt")
+    orient_prompt = load_prompt("orient-upright.txt")
+    state_dir = out_dir / ".wasabi-read"
+    dewarp_ident = (deps.dewarp_identity or {"backend": "injected"}) if deps.dewarp else dw.dewarp_identity()
+    model = _model_identity(args, state_dir)
+    identity = package_identity(_settings(args, dewarp_ident), model)
+    digest = identity_sha(identity)
+    orient_ident = orient_identity(model["judge"], ori.ORIENT_FLOORS[args.orient_judge],
+                                   identity["settings"]["serving"])
+    dewarp_key = hashlib.sha256(json.dumps(dewarp_ident, sort_keys=True).encode()).hexdigest()
+    shas = {im.stem: sha256_file(im) for im in images}
+    by_stem = {im.stem: im for im in images}
+    report: dict[str, Any] = {"schema": "wasabi-read-run-report-v1", "code_version": CODE_VERSION,
+                              "identity_sha256": digest, "inputs": len(images), "skipped": 0, "written": 0,
+                              "failed": [], "pages": {}, "stage_seconds": {}}
+    with OutputStore(out_dir, identity, digest, args.overwrite_stale) as store:
+        cls = store.classify([(s, shas[s]) for s in sorted(by_stem)])
+        report["skipped"] = len(cls["done"])
+        pending = sorted(cls["pending"])
+        # A rerun with nothing left to do writes nothing under the output directory (no journal line, no report).
+        if pending:
+            try:
+                store.journal_append({"event": "run_start", "inputs": len(images), "done": len(cls["done"]),
+                                      "pending": len(pending)})
+                _process(args, deps, opener, store, by_stem, shas, pending, draft_prompt, orient_prompt, orient_ident,
+                         dewarp_key, report)
+                store.journal_append({"event": "run_end", "written": report["written"],
+                                      "failed": len(report["failed"])})
+            finally:
+                _write_report(args, store, report)
+    if report["failed"]:
+        print(f"INCOMPLETE: {len(report['failed'])} of {len(images)} page(s) have no usable output; see the run "
+              f"report: " + ", ".join(f"{f['stem']}={f['reason']}" for f in report["failed"][:10]), file=sys.stderr)
+        return EXIT_INCOMPLETE
+    print(f"ok: {report['written']} page(s) written, {report['skipped']} already done", file=sys.stderr)
+    return EXIT_OK
+
+
+def _write_report(args, store: OutputStore, report: dict) -> None:
+    path = Path(args.report) if args.report else store.state / "run-report.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_bytes(path, (json.dumps(report, indent=1, sort_keys=True, ensure_ascii=True) + "\n").encode("ascii"))
+
+
+def _process(args, deps, opener, store, by_stem, shas, pending, draft_prompt, orient_prompt, orient_ident,
+             dewarp_key, report) -> None:
+    import time
+    lock = threading.Lock()
+    floor = ori.ORIENT_FLOORS[args.orient_judge]
+    backend = deps.dewarp or dw.TorchUVDoc(dw.resolve_uvdoc(args.uvdoc_source, args.uvdoc_dir))
+    prepared: dict[str, dict] = {}
+
+    def prep(stem: str) -> None:
+        try:
+            im = ori.load_upright(by_stem[stem])
+            sha = shas[stem]
+            dec = ori.orient_cached(im, sha, orient_ident, store.state / "cache", judge_reader[0].ask, orient_prompt,
+                                    png_bytes, _cache_write, floor)
+            rotated = ori.apply_angle(im, dec["applied_angle"])
+            # one dewarped image per input bytes, full orientation identity and full dewarp identity (UVDoc pins,
+            # preprocessing, OpenCV/torch/numpy/Pillow versions)
+            dpath = store.cache_path("dewarp", f"{sha}-{orient_ident}-{dewarp_key}.png")
+            if dpath.is_file():
+                dewarped_ok = True
+            else:
+                out = dw.dewarp_image(rotated, backend)
+                _cache_write(dpath, png_bytes(out))
+                dewarped_ok = True
+            with lock:
+                prepared[stem] = {"orient": dec, "dewarp_path": dpath, "dewarped": dewarped_ok}
+        except Exception as exc:  # noqa: BLE001 (one bad page must not stop the others)
+            with lock:
+                _fail(report, store, stem, f"prep:{type(exc).__name__}:{exc}")
+
+    def read(stem: str) -> None:
+        p = prepared.get(stem)
+        if p is None:
+            return
+        try:
+            im = _load_png_image(p["dewarp_path"])
+            sent, view = prepare_whole(im, args.whole_upscale_tokens)
+            png = png_bytes(sent) if view["upscaled"] else png_bytes(im)
+            rd = reader_box[0]
+            rec = read_page(stem, lambda rung, t, s, rem: rd.call(png, draft_prompt, t, s, rem),
+                            page_budget_s=args.page_budget_s)
+            ok, reason = page_verdict(rec)
+            with lock:
+                _account(report, stem, rec, p["orient"], view)
+            if ok:
+                store.write_page(stem, rec["final_text"], shas[stem], {
+                    "orientation": {k: p["orient"].get(k) for k in ("applied_angle", "chosen_angle", "margin", "floored")},
+                    "view": view, "outcome": "ok", "final_finish_reason": rec["final_finish_reason"],
+                    "ladder_end": rec["ladder_end"], "retry_attempts": rec["retry_attempts"]})
+                with lock:
+                    report["written"] += 1
+                    store.journal_append({"event": "page_done", "stem": stem, "ladder_end": rec["ladder_end"]})
+            else:
+                with lock:
+                    _fail(report, store, stem, reason)
+        except Exception as exc:  # noqa: BLE001
+            with lock:
+                _fail(report, store, stem, f"read:{type(exc).__name__}:{exc}")
+
+    judge_reader: list = [None]
+    reader_box: list = [None]
+
+    def run_prep():
+        t0 = time.monotonic()
+        store.journal_append({"event": "stage_start", "stage": "orient+dewarp", "pages": len(pending)})
+        with ThreadPoolExecutor(max_workers=args.concurrency) as ex:
+            list(ex.map(prep, pending))
+        report["stage_seconds"]["orient_dewarp"] = round(time.monotonic() - t0, 1)
+
+    def run_read():
+        t0 = time.monotonic()
+        store.journal_append({"event": "stage_start", "stage": "read", "pages": len(prepared)})
+        with ThreadPoolExecutor(max_workers=args.concurrency) as ex:
+            list(ex.map(read, sorted(prepared)))
+        report["stage_seconds"]["read"] = round(time.monotonic() - t0, 1)
+
+    # The judge always has its own server at the probe geometry, the self-judge too (same weights, fewer image
+    # tokens than the read); it is released before the reader starts.
+    with opener(_spec(args, "judge")) as jd:
+        judge_reader[0] = jd
+        run_prep()
+    with opener(_spec(args, "reader")) as rd:
+        reader_box[0] = rd
+        run_read()
+
+
+def _cache_write(path: Path, data: bytes) -> None:
+    atomic_write_bytes(path, data, unique=True)
+
+
+def _fail(report: dict, store: OutputStore, stem: str, reason: str) -> None:
+    report["failed"].append({"stem": stem, "reason": reason})
+    store.journal_append({"event": "page_failed", "stem": stem, "reason": reason})
+
+
+def _account(report: dict, stem: str, rec: dict, orient: dict, view: dict) -> None:
+    cands = rec.get("candidates") or []
+    report["pages"][stem] = {
+        "outcome": rec.get("outcome"), "ladder_end": rec.get("ladder_end"),
+        "final_finish_reason": rec.get("final_finish_reason"), "retry_attempts": rec.get("retry_attempts"),
+        "infra_retries": rec.get("infra_retries"), "initial_degen": rec.get("initial_degen"),
+        "final_degen": rec.get("final_degen"),
+        "selected_rung": (cands[rec["selected_index"]]["rung"] if rec.get("selected_index") is not None else None),
+        "candidate_finish_reasons": [c.get("finish_reason") for c in cands],
+        "applied_angle": orient.get("applied_angle"), "rotated": bool(orient.get("applied_angle")),
+        "upscaled": view.get("upscaled")}
+
+
+def main(argv: list[str] | None = None, deps: Deps | None = None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:  # argparse refusals (unknown engine, bad choice) exit 2
+        return int(exc.code) if isinstance(exc.code, int) else EXIT_REFUSED
+    try:
+        return run(args, deps)
+    except IncompleteOutput as exc:
+        print(f"INCOMPLETE: {exc}", file=sys.stderr)
+        return EXIT_INCOMPLETE
+    except PortError as exc:
+        print(f"REFUSED: {exc}", file=sys.stderr)
+        return EXIT_REFUSED
+
+
+if __name__ == "__main__":
+    sys.exit(main())

inference/wasabi_read/dewarp.py

@@ -0,0 +1,213 @@
+"""UVDoc dewarp on CPU: verified fetch, verified load, per-page dewarp.
+
+The weights are a pickle: size and sha256 are checked BEFORE any unpickle, and the UVDoc code
+files are checked before they are imported. torch is imported lazily and the device is always cpu.
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Callable
+
+from . import PortError
+
+UVDOC_REPO = "tanguymagne/UVDoc"
+UVDOC_COMMIT = "4c9b82b537057aff2526e6dd118a847cdd072e82"
+WEIGHTS = "model/best_model.pkl"
+WEIGHTS_BYTES = 32158393
+#: sha256 pins of every file used, taken from the pinned upstream commit.
+UVDOC_PINS = {
+    "model/best_model.pkl": "7e90861b8a516eb4bc51f84bd889cb77275743d2d1d3ca8091951ec9f2b7da23",
+    "model.py": "320f460edc54cf830dfdd9788dfbc1b96a836429b64ed6078a30582be6f59e42",
+    "utils.py": "64909e09e7493dcef1cd356b833c316e87c8ce31a544c567dee4b95ece78d3c2",
+    "LICENSE": "cf80bdbde76b47756c7fa62b56854ae54902979016bb08a6ba2edbebf93e9b90",
+}
+IMG_SIZE_FALLBACK = (488, 712)   # upstream utils.IMG_SIZE [w, h]
+NUM_FILTER, KERNEL_SIZE = 32, 5  # upstream utils.load_model
+#: The dewarp preprocessing: the network input is resized with OpenCV (the upstream demo's resize), and an output of
+#: another size is resized back to the input size.
+DEWARP_PREPROCESS = ("cv2.resize INTER_LINEAR float32 to the UVDoc img_size; "
+                     "PIL LANCZOS back to the input size when the output size differs")
+
+
+def require_cv2():
+    """OpenCV is required: the network input is resized with it, as upstream does. There is no other resize path."""
+    try:
+        import cv2
+    except ImportError:
+        raise PortError("dewarp needs OpenCV: install the package with its dewarp extra "
+                        "(pip install -e \"./inference[dewarp]\")") from None
+    return cv2
+
+
+def dewarp_identity() -> dict:
+    """What a dewarped page depends on besides its input pixels: the pinned UVDoc files, the resize steps and the
+    library versions that run them. Part of the output identity and of the dewarp cache key; a missing OpenCV or torch
+    refuses here, before any page is read."""
+    import importlib.metadata as md
+    cv2 = require_cv2()
+    versions = {"opencv": cv2.__version__}
+    for dist in ("torch", "numpy", "pillow"):
+        try:
+            versions[dist] = md.version(dist)
+        except md.PackageNotFoundError:
+            raise PortError(f"dewarp needs {dist}: install the package with its dewarp extra") from None
+    return {"uvdoc_commit": UVDOC_COMMIT, "uvdoc_pins": dict(UVDOC_PINS), "num_filter": NUM_FILTER,
+            "kernel_size": KERNEL_SIZE, "preprocess": DEWARP_PREPROCESS, "device": "cpu",
+            "versions": versions}
+
+
+def default_uvdoc_dir() -> Path:
+    return Path(os.environ.get("WASABI_READ_CACHE", str(Path.home() / ".cache" / "wasabi-read"))) / ("uvdoc-" + UVDOC_COMMIT[:8])
+
+
+def url_of(path: str, commit: str = UVDOC_COMMIT) -> str:
+    return f"https://raw.githubusercontent.com/{UVDOC_REPO}/{commit}/{path}"
+
+
+def download(url: str, timeout: float = 60.0, tries: int = 3) -> bytes:
+    last = None
+    for k in range(tries):
+        try:
+            with urllib.request.urlopen(url, timeout=timeout) as r:  # noqa: S310 (pinned https URL)
+                return r.read()
+        except urllib.error.HTTPError as e:
+            raise PortError(f"UVDoc download: HTTP {e.code} on {url}") from None
+        except (urllib.error.URLError, TimeoutError, OSError) as e:
+            last = e
+            time.sleep(2 * (k + 1))
+    raise PortError(f"UVDoc download: network error {type(last).__name__} after {tries} tries on {url}")
+
+
+def check_blob(rel: str, data: bytes) -> None:
+    """Refuse bytes that are not the pinned file (size for the weights, sha256 for every file)."""
+    if rel == WEIGHTS and len(data) != WEIGHTS_BYTES:
+        raise PortError(f"UVDoc {rel}: {len(data)} bytes != pinned {WEIGHTS_BYTES} (an LFS pointer or a wrong file)")
+    got = hashlib.sha256(data).hexdigest()
+    if got != UVDOC_PINS[rel]:
+        raise PortError(f"UVDoc {rel}: sha256 {got} != pinned {UVDOC_PINS[rel]}")
+
+
+def verify_weights(path: Path) -> None:
+    """Size and sha256 of a weights file on disk, checked before it is ever unpickled."""
+    path = Path(path)
+    if not path.is_file():
+        raise PortError(f"UVDoc weights missing: {path}")
+    if path.stat().st_size != WEIGHTS_BYTES:
+        raise PortError(f"UVDoc weights {path}: {path.stat().st_size} bytes != pinned {WEIGHTS_BYTES}")
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for block in iter(lambda: f.read(1 << 20), b""):
+            h.update(block)
+    if h.hexdigest() != UVDOC_PINS[WEIGHTS]:
+        raise PortError(f"UVDoc weights {path}: sha256 {h.hexdigest()} != pinned {UVDOC_PINS[WEIGHTS]}")
+
+
+def verify_dir(uvdoc_dir: Path) -> None:
+    """Every pinned UVDoc file present and matching (weights first, so a bad pickle is refused before code import)."""
+    uvdoc_dir = Path(uvdoc_dir)
+    verify_weights(uvdoc_dir / WEIGHTS)
+    for rel in ("model.py", "utils.py", "LICENSE"):
+        f = uvdoc_dir / rel
+        if not f.is_file():
+            raise PortError(f"UVDoc file missing: {f}")
+        check_blob(rel, f.read_bytes())
+
+
+def fetch_uvdoc(dest: Path, fetcher: Callable[[str], bytes] = download) -> Path:
+    """Make `dest` a verified UVDoc checkout of the pinned commit. An existing verified dir is reused. Every blob is
+    verified in memory before it is written, so unverified bytes never reach disk under their final name."""
+    dest = Path(dest)
+    try:
+        verify_dir(dest)
+        return dest
+    except PortError:
+        pass
+    blobs = {}
+    for rel in (WEIGHTS, "model.py", "utils.py", "LICENSE"):
+        data = fetcher(url_of(rel))
+        check_blob(rel, data)
+        blobs[rel] = data
+    for rel, data in blobs.items():
+        target = dest / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        tmp = target.with_name(target.name + ".tmp")
+        tmp.write_bytes(data)
+        os.replace(tmp, target)
+    verify_dir(dest)
+    return dest
+
+
+def resolve_uvdoc(source: str, uvdoc_dir: str | None, fetcher: Callable[[str], bytes] = download) -> Path:
+    if source == "vendored":
+        if not uvdoc_dir:
+            raise PortError("--uvdoc-source vendored needs --uvdoc-dir PATH (a local UVDoc checkout)")
+        verify_dir(Path(uvdoc_dir))
+        return Path(uvdoc_dir)
+    return fetch_uvdoc(Path(uvdoc_dir) if uvdoc_dir else default_uvdoc_dir(), fetcher)
+
+
+def _load_module(name: str, path: Path):
+    spec = importlib.util.spec_from_file_location(name, str(path))
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+class TorchUVDoc:
+    """The UVDoc network on CPU. Call with a PIL image, get the dewarped PIL image (same size)."""
+
+    def __init__(self, uvdoc_dir: Path):
+        verify_dir(uvdoc_dir)  # size + sha256 before torch.load and before importing model.py
+        self._cv2 = require_cv2()
+        import torch
+        import torch.nn.functional as F
+        torch.set_num_threads(min(32, os.cpu_count() or 4))
+        self._torch = torch
+        uvmodel = _load_module("wasabi_uvdoc_model", Path(uvdoc_dir) / "model.py")
+        net = uvmodel.UVDocnet(num_filter=NUM_FILTER, kernel_size=KERNEL_SIZE)
+        ck = torch.load(str(Path(uvdoc_dir) / WEIGHTS), map_location="cpu", weights_only=True)
+        net.load_state_dict(ck["model_state"] if "model_state" in ck else ck)
+        net.eval()
+        try:
+            uvutils = _load_module("wasabi_uvdoc_utils", Path(uvdoc_dir) / "utils.py")
+            self.img_size, self.unwarp = tuple(uvutils.IMG_SIZE), uvutils.bilinear_unwarping
+        except Exception:
+            def unwarp(warped_img, point_positions, img_size):  # mirror of upstream utils.bilinear_unwarping
+                up = F.interpolate(point_positions, size=(img_size[1], img_size[0]), mode="bilinear",
+                                   align_corners=True)
+                return F.grid_sample(warped_img, up.permute(0, 2, 3, 1), align_corners=True)
+            self.img_size, self.unwarp = IMG_SIZE_FALLBACK, unwarp
+        self.net = net
+
+    def __call__(self, im):
+        import numpy as np
+        from PIL import Image
+        torch = self._torch
+        W, H = im.size
+        arr = np.asarray(im, dtype=np.float32) / 255.0
+        small = self._cv2.resize(arr, tuple(self.img_size), interpolation=self._cv2.INTER_LINEAR)  # upstream demo
+        inp = torch.from_numpy(small.transpose(2, 0, 1)).unsqueeze(0)
+        with torch.no_grad():
+            pts2d, _pts3d = self.net(inp)
+            full = torch.from_numpy(arr.transpose(2, 0, 1)).unsqueeze(0)
+            out = self.unwarp(warped_img=full, point_positions=torch.unsqueeze(pts2d[0], dim=0), img_size=(W, H))
+        o = (out[0].numpy().transpose(1, 2, 0).clip(0, 1) * 255).astype(np.uint8)
+        return Image.fromarray(o)
+
+
+def dewarp_image(im, backend: Callable):
+    """Run a dewarp backend (callable PIL -> PIL) and return an image of the INPUT size (LANCZOS resize if the
+    backend returned another size)."""
+    from PIL import Image
+    out = backend(im)
+    if out.size != im.size:
+        out = out.resize(im.size, Image.LANCZOS)
+    return out.convert("RGB")

inference/wasabi_read/engine.py

@@ -0,0 +1,307 @@
+"""One request builder, three backends: `vllm` (a spawned local server), `endpoint` (an OpenAI-compatible URL) and
+`transformers` (local, CPU-capable, unmeasured). Greedy decoding is forced at rung 0 whatever generation_config says.
+
+Request shape: greedy temperature 0, repetition_penalty 1.10, seed 42,
+repetition_detection (4, 512, 16), chat_template_kwargs reasoning_strength=low, max_tokens 24576.
+"""
+from __future__ import annotations
+
+import base64
+import contextlib
+import json
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Callable, Iterator
+
+from . import PortError
+from .views import whole_upscale_max_model_len
+
+GLIMMER_MAX_TOKENS = 24576
+GLIMMER_MAX_MODEL_LEN = 36864
+REPETITION_STOP = (4, 512, 16)          # (min_pattern_size, max_pattern_size, min_count)
+REPETITION_PENALTY = 1.10
+CHAT_TEMPLATE_KWARGS = {"reasoning_strength": "low", "current_date": "2026-10-16"}
+REPETITION_STOP_REASON = "repetition_detected"
+LOOP_STOP = "loop_stop"
+PROBE_MAX_TOKENS = 1024
+PROBE_TOP_LOGPROBS = 20
+GREEDY_SEED = 42
+
+
+class EngineError(RuntimeError):
+    """A transport or server failure (typed as an infra outcome by the caller)."""
+
+    def __init__(self, msg: str, kind: str = "error"):
+        super().__init__(msg)
+        self.kind = kind
+
+
+def repetition_detection() -> dict:
+    mn, mx, cnt = REPETITION_STOP
+    return {"max_pattern_size": mx, "min_pattern_size": mn, "min_count": cnt}
+
+
+def data_uri_png(png: bytes) -> str:
+    return "data:image/png;base64," + base64.b64encode(png).decode("ascii")
+
+
+def _messages(png: bytes, prompt: str) -> list[dict]:
+    return [{"role": "user", "content": [
+        {"type": "image_url", "image_url": {"url": data_uri_png(png)}},
+        {"type": "text", "text": prompt}]}]
+
+
+def build_read_payload(served_name: str, png: bytes, prompt: str, temperature: float, seed: int,
+                       max_tokens: int = GLIMMER_MAX_TOKENS) -> dict:
+    """The page-read request. temperature is 0.0 on the first pass (greedy); the ladder raises it."""
+    return {"model": served_name, "messages": _messages(png, prompt), "max_tokens": int(max_tokens),
+            "temperature": float(temperature), "repetition_penalty": REPETITION_PENALTY, "seed": int(seed),
+            "repetition_detection": repetition_detection(), "chat_template_kwargs": dict(CHAT_TEMPLATE_KWARGS)}
+
+
+def build_probe_payload(served_name: str, png: bytes, prompt: str, logprobs: bool = True) -> dict:
+    p = {"model": served_name, "messages": _messages(png, prompt), "max_tokens": PROBE_MAX_TOKENS,
+         "temperature": 0.0, "repetition_penalty": REPETITION_PENALTY, "seed": GREEDY_SEED,
+         "repetition_detection": repetition_detection(), "chat_template_kwargs": dict(CHAT_TEMPLATE_KWARGS)}
+    if logprobs:
+        p["logprobs"] = True
+        p["top_logprobs"] = PROBE_TOP_LOGPROBS
+    return p
+
+
+def decode_response(body: dict) -> dict:
+    """OpenAI-style chat body -> {content, finish_reason, logprob_entries, prompt_tokens, completion_tokens}.
+    A native repetition stop is typed `loop_stop` (truncation class), never a clean `stop`."""
+    ch = (body.get("choices") or [{}])[0]
+    msg = ch.get("message") or {}
+    finish = ch.get("finish_reason")
+    if ch.get("stop_reason") == REPETITION_STOP_REASON:
+        finish = LOOP_STOP
+    lp = ch.get("logprobs")
+    usage = body.get("usage") or {}
+    return {"content": msg.get("content") or "", "finish_reason": finish,
+            "logprob_entries": lp.get("content") if isinstance(lp, dict) else None,
+            "prompt_tokens": usage.get("prompt_tokens"), "completion_tokens": usage.get("completion_tokens")}
+
+
+class EndpointClient:
+    """POST /v1/chat/completions to an OpenAI-compatible server."""
+
+    def __init__(self, base_url: str, api_key: str | None = None):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+
+    def chat(self, payload: dict, timeout: float) -> dict:
+        data = json.dumps(payload).encode("utf-8")
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = "Bearer " + self.api_key
+        req = urllib.request.Request(self.base_url + "/v1/chat/completions", data=data, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 (user-chosen endpoint)
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            raise EngineError(f"HTTP {exc.code}", "http_error") from None
+        except (socket.timeout, TimeoutError):
+            raise EngineError("request timed out", "timeout") from None
+        except urllib.error.URLError as exc:
+            if isinstance(exc.reason, (socket.timeout, TimeoutError)):
+                raise EngineError("request timed out", "timeout") from None
+            raise EngineError(f"{type(exc.reason).__name__}: {exc.reason}", "error") from None
+        except (OSError, ValueError) as exc:
+            raise EngineError(f"{type(exc).__name__}: {exc}", "error") from None
+
+
+class Reader:
+    """Page reads and orientation asks over any client with `chat(payload, timeout) -> body`."""
+
+    def __init__(self, client, served_name: str, max_tokens: int = GLIMMER_MAX_TOKENS, request_timeout: float = 1800.0):
+        self.client = client
+        self.served_name = served_name
+        self.max_tokens = max_tokens
+        self.request_timeout = request_timeout
+
+    def _run(self, payload: dict, timeout: float) -> dict:
+        t = time.monotonic()
+        try:
+            body = self.client.chat(payload, max(1.0, min(self.request_timeout, timeout)))
+            out = decode_response(body)
+            out.update(error=None, latency_s=round(time.monotonic() - t, 3))
+            return out
+        except EngineError as exc:
+            return {"content": "", "finish_reason": exc.kind, "error": str(exc), "logprob_entries": None,
+                    "latency_s": round(time.monotonic() - t, 3)}
+        except (socket.timeout, TimeoutError) as exc:
+            return {"content": "", "finish_reason": "timeout", "error": str(exc) or "timeout",
+                    "logprob_entries": None, "latency_s": round(time.monotonic() - t, 3)}
+
+    def call(self, png: bytes, prompt: str, temperature: float, seed: int, timeout: float) -> dict:
+        return self._run(build_read_payload(self.served_name, png, prompt, temperature, seed, self.max_tokens), timeout)
+
+    def ask(self, png: bytes, prompt: str, logprobs: bool = True) -> dict:
+        return self._run(build_probe_payload(self.served_name, png, prompt, logprobs), self.request_timeout)
+
+
+# ---------------------------------------------------------------- local vLLM server
+def server_argv(model_dir: str, served_name: str, port: int, image_tokens: int, tensor_parallel: int,
+                max_tokens: int = GLIMMER_MAX_TOKENS, reasoning_plugin: str | None = None,
+                python: str | None = None) -> list[str]:
+    """The local vLLM server flags, plus tensor parallelism. GPU memory use is left to vLLM's default; to control it, serve
+    the model yourself and use `--engine endpoint`."""
+    argv = [python or sys.executable, "-m", "vllm.entrypoints.openai.api_server", "--model", str(model_dir),
+            "--served-model-name", served_name, "--host", "127.0.0.1", "--port", str(port),
+            "--max-model-len", str(whole_upscale_max_model_len(image_tokens, max_tokens, GLIMMER_MAX_MODEL_LEN)),
+            "--max-num-seqs", "64", "--safetensors-load-strategy", "prefetch", "--mm-encoder-attn-backend", "FLASHINFER"]
+    if tensor_parallel > 1:
+        argv += ["--tensor-parallel-size", str(tensor_parallel)]
+    if reasoning_plugin:
+        argv += ["--reasoning-parser-plugin", str(reasoning_plugin)]
+    argv += ["--reasoning-parser", "muse_glimmer", "--mm-processor-kwargs",
+             json.dumps({"max_image_tokens": int(image_tokens)})]
+    return argv
+
+
+def free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+@dataclass
+class EngineSpec:
+    kind: str                       # vllm | endpoint | transformers
+    served_name: str
+    model_dir: str | None = None
+    url: str | None = None
+    api_key: str | None = None
+    tensor_parallel: int = 1
+    image_tokens: int = 4096
+    max_tokens: int = GLIMMER_MAX_TOKENS
+    reasoning_plugin: str | None = None
+    ready_timeout_s: float = 1800.0
+    request_timeout_s: float = 1800.0
+    spawn: Callable[[list[str]], Any] | None = field(default=None, repr=False)
+    probe_ready: Callable[[str], bool] | None = field(default=None, repr=False)
+
+
+def _http_ready(url: str) -> bool:
+    try:
+        with urllib.request.urlopen(url + "/v1/models", timeout=5) as r:  # noqa: S310 (loopback)
+            return r.status == 200
+    except (OSError, ValueError):
+        return False
+
+
+@contextlib.contextmanager
+def open_reader(spec: EngineSpec) -> Iterator[Reader]:
+    """Yield a Reader for the spec; a spawned server or a loaded model is released on exit."""
+    if spec.kind == "endpoint":
+        if not spec.url:
+            raise PortError("--engine endpoint needs --endpoint-url")
+        yield Reader(EndpointClient(spec.url, spec.api_key), spec.served_name, spec.max_tokens, spec.request_timeout_s)
+        return
+    if spec.kind == "vllm":
+        if not spec.model_dir:
+            raise PortError("--engine vllm needs --model-dir (and --orient-model-dir for --orient-judge base)")
+        port = free_port()
+        argv = server_argv(spec.model_dir, spec.served_name, port, spec.image_tokens, spec.tensor_parallel,
+                           spec.max_tokens, spec.reasoning_plugin)
+        proc = (spec.spawn or (lambda a: subprocess.Popen(a)))(argv)  # noqa: S603 (argv list, no shell)
+        url = f"http://127.0.0.1:{port}"
+        ready = spec.probe_ready or _http_ready
+        try:
+            deadline = time.monotonic() + spec.ready_timeout_s
+            while not ready(url):
+                if getattr(proc, "poll", lambda: None)() is not None:
+                    raise PortError("the vLLM server exited before it was ready")
+                if time.monotonic() > deadline:
+                    raise PortError(f"the vLLM server was not ready after {spec.ready_timeout_s:.0f} s")
+                time.sleep(2.0)
+            yield Reader(EndpointClient(url), spec.served_name, spec.max_tokens, spec.request_timeout_s)
+        finally:
+            with contextlib.suppress(Exception):
+                proc.terminate()
+                proc.wait(timeout=60)
+        return
+    if spec.kind == "transformers":
+        if not spec.model_dir:
+            raise PortError("--engine transformers needs --model-dir")
+        yield Reader(TransformersClient(spec.model_dir, spec.image_tokens), spec.served_name, spec.max_tokens,
+                     spec.request_timeout_s)
+        return
+    raise PortError(f"unknown engine {spec.kind!r}")
+
+
+# ---------------------------------------------------------------- transformers (local, unmeasured)
+def generation_kwargs(payload: dict) -> dict:
+    """HF generate() kwargs from a request payload. temperature 0 is greedy: do_sample False and every sampling knob
+    cleared, so a generation_config with do_sample true / temperature 1.0 / top_k 64 / top_p 0.95 never applies."""
+    temp = float(payload.get("temperature") or 0.0)
+    kw: dict[str, Any] = {"max_new_tokens": int(payload["max_tokens"]),
+                          "repetition_penalty": float(payload.get("repetition_penalty") or 1.0)}
+    if temp <= 0.0:
+        kw.update(do_sample=False, temperature=None, top_p=None, top_k=None)
+    else:
+        kw.update(do_sample=True, temperature=temp, top_p=None, top_k=None)
+    return kw
+
+
+class TransformersClient:
+    """A local chat client on transformers. Correctness path for a few pages: it returns the raw decoded text (no
+    server-side reasoning-channel split, no repetition_detection stop); use the vllm or endpoint engine for real runs."""
+
+    def __init__(self, model_dir: str, image_tokens: int = 4096):
+        self.model_dir = model_dir
+        self.image_tokens = int(image_tokens)
+        self._model = None
+        self._proc = None
+
+    def _load(self):
+        if self._model is None:
+            import torch
+            from transformers import AutoModelForImageTextToText, AutoProcessor
+            self._proc = AutoProcessor.from_pretrained(self.model_dir, max_image_tokens=self.image_tokens)
+            self._model = AutoModelForImageTextToText.from_pretrained(self.model_dir, torch_dtype=torch.bfloat16)
+            self._model.eval()
+        return self._model, self._proc
+
+    def chat(self, payload: dict, timeout: float) -> dict:
+        import io
+
+        import torch
+        from PIL import Image
+        model, proc = self._load()
+        part = payload["messages"][0]["content"]
+        uri = next(p["image_url"]["url"] for p in part if p["type"] == "image_url")
+        im = Image.open(io.BytesIO(base64.b64decode(uri.split(",", 1)[1]))).convert("RGB")
+        text = next(p["text"] for p in part if p["type"] == "text")
+        msgs = [{"role": "user", "content": [{"type": "image"}, {"type": "text", "text": text}]}]
+        prompt = proc.apply_chat_template(msgs, add_generation_prompt=True, tokenize=False,
+                                          **(payload.get("chat_template_kwargs") or {}))
+        inputs = proc(text=[prompt], images=[im], return_tensors="pt")
+        want_lp = bool(payload.get("logprobs"))
+        if payload.get("seed") is not None:
+            torch.manual_seed(int(payload["seed"]))
+        with torch.no_grad():
+            out = model.generate(**inputs, **generation_kwargs(payload), output_scores=want_lp,
+                                 return_dict_in_generate=True)
+        new = out.sequences[0][inputs["input_ids"].shape[1]:]
+        content = proc.tokenizer.decode(new, skip_special_tokens=True)
+        hit_max = new.shape[0] >= int(payload["max_tokens"])
+        choice: dict[str, Any] = {"message": {"content": content}, "finish_reason": "length" if hit_max else "stop"}
+        if want_lp:
+            entries = []
+            for step, tok in zip(out.scores, new):
+                lps = torch.log_softmax(step[0].float(), dim=-1)
+                top = torch.topk(lps, PROBE_TOP_LOGPROBS)
+                entries.append({"token": proc.tokenizer.decode([int(tok)]), "logprob": float(lps[int(tok)]),
+                                "top_logprobs": [{"token": proc.tokenizer.decode([int(i)]), "logprob": float(v)}
+                                                 for v, i in zip(top.values, top.indices)]})
+            choice["logprobs"] = {"content": entries}
+        return {"choices": [choice], "usage": {"prompt_tokens": int(inputs["input_ids"].shape[1]),
+                                               "completion_tokens": int(new.shape[0])}}

inference/wasabi_read/identity.py

@@ -0,0 +1,96 @@
+"""Package identity: code version, prompt pins, model files, settings; the per-page resume key.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from . import CODE_VERSION, PortError
+from .inputs import sha256_file
+
+PROMPT_DIR = Path(__file__).resolve().parent / "prompts"
+#: sha256 of the shipped prompt files; a changed byte refuses.
+PROMPT_PINS = {
+    "draft.txt": "1f80d2ca0bcb5c815ab15f1fe8d6a7fc16d2c2c305ffeabcec90eca4292d97f8",
+    "orient-upright.txt": "ad089da4c37eb9a25a5bf56dd4124497d2258c282ae0b593112984e10cd7d159",
+}
+DRAFT_PROMPT_ID = "wasabi-draft-v1"
+
+#: Per-file pins of the files the model needs (the release SHA256SUMS). Extra files (README, notices)
+#: do not change what is served, so a folder is accepted when every pinned file matches.
+MODEL_FILE_PINS = {
+    "chat_template.jinja": "114f55ebdc1804c1af371197b9fdf2d6bb925966c9dfe46b73782a71bc07965e",
+    "config.json": "1c235df3179388bb56e522a25543d1f9e417a25e71b162887378a4362c5e4dbc",
+    "generation_config.json": "519ca0cad3bf6cb10c4f74dfb64786f651533bae2f316c609d66e0bcf5adfde6",
+    "model-00001-of-00002.safetensors": "0a5fdba915e499084969163518830e320040b0f2e03eb43843bbb71be450c5a7",
+    "model-00002-of-00002.safetensors": "20dfe7774a3ba1194b853e54fac1fb589bdc28872198b6e80c6c37ea32ef21b4",
+    "model.safetensors.index.json": "79f6028c3b5544f6be46607b8580d7376bf68bdc66647480fd3bfa520ad9efa3",
+    "processor_config.json": "97e2a486dd9866b81f40cf4b8bc0c9ced9a7cd8a5bc65aa4cc2f4de0712dae77",
+    "tokenizer.json": "c9dbee66967b58f31a7c27f723c3760da3526ccd0427578e8905b0abb0031c4d",
+    "tokenizer_config.json": "228f829a2d2d0d7793eb5bfdc0c20b2bbee27a9adff0b38c65edca4e7380420c",
+}
+
+
+def load_prompt(name: str, prompt_dir: Path | None = None, pins: dict | None = None) -> str:
+    """The prompt text, refused unless its sha256 matches the pin."""
+    pins = PROMPT_PINS if pins is None else pins
+    path = Path(prompt_dir or PROMPT_DIR) / name
+    if not path.is_file():
+        raise PortError(f"prompt file missing: {path}")
+    data = path.read_bytes()
+    got = hashlib.sha256(data).hexdigest()
+    if got != pins.get(name):
+        raise PortError(f"prompt {name} sha256 {got} != pinned {pins.get(name)}")
+    return data.decode("utf-8")
+
+
+def tree_sha(entries: list[dict]) -> str:
+    digest = hashlib.sha256()
+    for entry in sorted(entries, key=lambda e: e["path"]):
+        digest.update((f"{entry['path']}\0{entry['sha256']}\n").encode("utf-8"))
+    return digest.hexdigest()
+
+
+def check_model_tree(model_dir: Path, pins: dict | None = None) -> dict:
+    """Verify a model folder: every pinned file present with the pinned sha256 (a mismatch refuses).
+    Returns the digest of the pinned files."""
+    pins = MODEL_FILE_PINS if pins is None else pins
+    model_dir = Path(model_dir)
+    if not model_dir.is_dir():
+        raise PortError(f"model directory does not exist: {model_dir}")
+    # Only the files that are served identify the model: an output directory, caches or notes inside the folder
+    # never change the identity. With no pins (a base-model judge folder) every top-level file is used.
+    names = sorted(pins) if pins else sorted(p.name for p in model_dir.iterdir() if p.is_file())
+    by_path = {rel: sha256_file(model_dir / rel) for rel in names if (model_dir / rel).is_file()}
+    entries = [{"path": rel, "sha256": sha} for rel, sha in by_path.items()]
+    for rel, want in pins.items():
+        if rel not in by_path:
+            raise PortError(f"model file missing: {rel} in {model_dir}")
+        if by_path[rel] != want:
+            raise PortError(f"model file {rel} sha256 {by_path[rel]} != pinned {want}")
+    return {"tree_sha256": tree_sha(entries), "files": len(entries), "pinned_files": len(pins)}
+
+
+def package_identity(settings: dict[str, Any], model: dict[str, Any]) -> dict[str, Any]:
+    """Everything that changes what a page's Markdown would be. `settings` carries view/token/judge/uvdoc fields."""
+    return {
+        "schema": "wasabi-read-identity-v1",
+        "code_version": CODE_VERSION,
+        "draft_prompt_sha256": PROMPT_PINS["draft.txt"],
+        "draft_prompt_id": DRAFT_PROMPT_ID,
+        "orient_prompt_sha256": PROMPT_PINS["orient-upright.txt"],
+        "model": model,
+        "settings": settings,
+    }
+
+
+def identity_sha(identity: dict[str, Any]) -> str:
+    text = json.dumps(identity, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+    return hashlib.sha256(text.encode("ascii")).hexdigest()
+
+
+def page_key(input_sha256: str, identity_digest: str) -> str:
+    """The resume key of one page: its input bytes and the package identity."""
+    return hashlib.sha256(f"{input_sha256}:{identity_digest}".encode("ascii")).hexdigest()

inference/wasabi_read/inputs.py

@@ -0,0 +1,38 @@
+"""Input scan: .jpg/.jpeg/.png under a directory, unique stems (case-insensitive), sorted order.
+"""
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from . import PortError
+
+IMAGE_SUFFIXES = {".jpg", ".jpeg", ".png"}
+IMAGE_EXTENSIONS = ".jpg,.jpeg,.png"
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as stream:
+        for block in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def collect_images(input_dir: Path) -> list[Path]:
+    input_dir = Path(input_dir)
+    if not input_dir.is_dir():
+        raise PortError(f"input directory does not exist: {input_dir}")
+    images = sorted(
+        (p for p in input_dir.rglob("*") if p.is_file() and p.suffix.lower() in IMAGE_SUFFIXES),
+        key=lambda p: p.as_posix().casefold(),
+    )
+    if not images:
+        raise PortError(f"no supported images found; supported suffixes: {IMAGE_EXTENSIONS}")
+    ids: dict[str, Path] = {}
+    for image in images:
+        folded = image.stem.casefold()
+        if folded in ids:
+            raise PortError(f"duplicate image stem {image.stem!r}: {ids[folded]} and {image}")
+        ids[folded] = image
+    return images

inference/wasabi_read/orient.py

@@ -0,0 +1,198 @@
+"""4-way upright probe, floored decision, rotation, decision cache.
+
+Angle convention: `angle` = the counter-clockwise turn (PIL Transpose.ROTATE_<angle>) that makes the page upright.
+"""
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+from typing import Callable
+
+ORIENT_VARIANT = "upright-4way"
+#: The turn floor per judge: the Wasabi self-judge (the default) turns a page only at margin >= 5.0; the base
+#: model judge keeps its 2.0.
+ORIENT_FLOORS = {"self": 5.0, "base": 2.0}
+#: The judge server's processor geometry (max_image_tokens) for every probe request, whichever judge.
+ORIENT_IMAGE_TOKENS = 4096
+#: How a probe image is made from the input file: EXIF orientation applied, RGB, rotated, PNG-encoded.
+ORIENT_PREPROCESS = "exif_transpose+rgb+pil_transpose+png"
+ORI_LABELS = (0, 90, 180, 270)
+ORIENT_MAX_TOKENS = 1024
+ORIENT_TOP_LOGPROBS = 20
+YES_WORDS = frozenset({"yes", chr(0x306F) + chr(0x3044)})  # ha-i
+NO_WORDS = frozenset({"no", chr(0x3044) * 2 + chr(0x3048)})  # i-i-e
+CHANNEL_TERMINATORS_PROBE = ("<|eom|>", "<|eot|>", "<|end_of_text|>")
+_ORI_TRANSPOSE_NAMES = {90: "ROTATE_90", 180: "ROTATE_180", 270: "ROTATE_270"}
+
+
+def load_upright(path: Path):
+    """Pixels with EXIF orientation applied (normalization only; the visual probe still runs on every page)."""
+    from PIL import Image, ImageOps
+    with Image.open(path) as im:
+        return ImageOps.exif_transpose(im).convert("RGB")
+
+
+def ori_correct(im, angle: int):
+    from PIL import Image
+    if angle == 0:
+        return im.copy()
+    return im.transpose(getattr(Image.Transpose, _ORI_TRANSPOSE_NAMES[angle]))
+
+
+def ori_make_item(im, angle: int):
+    """The exact inverse of ori_correct: a page whose label is `angle`."""
+    return ori_correct(im, (360 - angle) % 360)
+
+
+def assert_rotation_inverse() -> None:
+    from PIL import Image
+    im = Image.new("RGB", (5, 3), (0, 0, 0))
+    im.putpixel((0, 0), (255, 0, 0))
+    im.putpixel((4, 1), (0, 255, 0))
+    want = im.tobytes()
+    for a in ORI_LABELS:
+        back = ori_correct(ori_make_item(im, a), a)
+        if back.size != im.size or back.tobytes() != want:
+            raise RuntimeError(f"rotation inverse broken at angle {a}")
+
+
+def _entry_bytes(e: dict) -> bytes:
+    b = e.get("bytes")
+    if isinstance(b, list):
+        return bytes(b)
+    return str(e.get("token") or "").encode("utf-8")
+
+
+def content_token_start(entries: list | None, content: str) -> tuple[int, int] | None:
+    """(start, end) of the CONTENT tokens inside a chat logprobs list that may also carry a reasoning turn."""
+    target = (content or "").strip().encode("utf-8")
+    if not entries or not target:
+        return None
+    end = len(entries)
+    while end > 0 and (str(entries[end - 1].get("token") or "") in CHANNEL_TERMINATORS_PROBE
+                       or _entry_bytes(entries[end - 1]) == b""):
+        end -= 1
+    acc = b""
+    for k in range(end - 1, -1, -1):
+        acc = _entry_bytes(entries[k]) + acc
+        s = acc.strip()
+        if s == target:
+            return k, end
+        if len(s) > len(target):
+            return None
+    return None
+
+
+def _lse(xs: list[float]) -> float:
+    m = max(xs)
+    return m + math.log(sum(math.exp(x - m) for x in xs))
+
+
+def _word(tok: str) -> str:
+    return str(tok or "").strip().lower().strip(".!" + chr(0x3002) + chr(0xFF01))
+
+
+def yes_no_margin(entry: dict) -> tuple[float | None, str]:
+    """log P(yes) - log P(no) at the first content token (variants pooled by logsumexp); a side absent from
+    top_logprobs is bounded by the lowest listed logprob (kind ..._bounded)."""
+    pool = {}
+    for t in (entry.get("top_logprobs") or []):
+        pool[t.get("token")] = t.get("logprob")
+    pool.setdefault(entry.get("token"), entry.get("logprob"))
+    vals = [v for v in pool.values() if isinstance(v, (int, float))]
+    ys = [v for k, v in pool.items() if _word(k) in YES_WORDS and isinstance(v, (int, float))]
+    ns = [v for k, v in pool.items() if _word(k) in NO_WORDS and isinstance(v, (int, float))]
+    if not ys and not ns:
+        return None, "logprob_absent_yes_no"
+    if ys and ns:
+        return _lse(ys) - _lse(ns), "logprob_margin"
+    floor = min(vals)
+    return ((_lse(ys) - floor) if ys else (floor - _lse(ns))), "logprob_margin_bounded"
+
+
+def parse_yes_no(content: str) -> int | None:
+    parts = (content or "").split()
+    w = _word(parts[0] if parts else "")
+    return 1 if w in YES_WORDS else 0 if w in NO_WORDS else None
+
+
+def pick_best(scores: dict) -> tuple[int, float, bool]:
+    """(chosen, margin, tie): the unique best candidate, else 0 (a tie for best keeps 0)."""
+    s = {c: v for c, v in scores.items() if v is not None}
+    if not s:
+        return 0, 0.0, True
+    best = max(s.values())
+    win = [c for c, v in s.items() if v == best]
+    if len(win) != 1:
+        return 0, 0.0, True
+    rest = [v for c, v in s.items() if c != win[0]]
+    return win[0], (best - max(rest)) if rest else 0.0, False
+
+
+def decide_upright(resps: dict) -> dict:
+    lp, kinds, parsed = {}, {}, {}
+    for c in ORI_LABELS:
+        r = resps[c]
+        parsed[c] = parse_yes_no(r.get("content"))
+        span = content_token_start(r.get("logprob_entries"), r.get("content") or "")
+        lp[c], kinds[c] = (yes_no_margin(r["logprob_entries"][span[0]]) if span else
+                           (None, "no_logprobs" if not r.get("logprob_entries") else "content_alignment_failed"))
+    if all(lp[c] is not None for c in ORI_LABELS):
+        scores = lp
+        kind = ("logprob_margin_bounded" if any(k == "logprob_margin_bounded" for k in kinds.values())
+                else "logprob_margin")
+    else:
+        scores = {c: float(parsed[c] or 0) for c in ORI_LABELS}
+        kind = "parsed_answer"
+    chosen, margin, tie = pick_best(scores)
+    return {"status": "ok", "chosen_angle": chosen, "score_kind": kind, "margin": margin, "tie": tie,
+            "parse_failed": any(parsed[c] is None for c in ORI_LABELS)}
+
+
+def orient_turn_decision(chosen_angle, margin, floor: float | None) -> dict:
+    """The turn applied from the probe decision alone: a non-zero choice whose margin is None or under the floor
+    keeps 0."""
+    angle = int(chosen_angle) if chosen_angle is not None else 0
+    if floor is not None and angle != 0 and (margin is None or margin < floor):
+        return {"applied_angle": 0, "floored": True}
+    return {"applied_angle": angle, "floored": False}
+
+
+def apply_angle(im, angle: int):
+    return ori_correct(im, angle)
+
+
+def probe_page(im, ask: Callable[..., dict], prompt: str, png_of: Callable, floor: float) -> dict:
+    """Render the page at 0/90/180/270, ask the fixed yes/no question for each (logprobs on), decide, floor.
+    `ask(png_bytes, prompt, logprobs=True)` returns {content, logprob_entries, ...}; `png_of(pil_image)` encodes."""
+    resps = {c: ask(png_of(ori_correct(im, c)), prompt, logprobs=True) for c in ORI_LABELS}
+    failed = sorted(c for c, r in resps.items() if r.get("error"))
+    if failed:  # an infra failure is never turned into a cached "keep 0" decision
+        raise RuntimeError(f"orientation probe request failed for rotation(s) {failed}: {resps[failed[0]]['error']}")
+    dec = decide_upright(resps)
+    turn = orient_turn_decision(dec["chosen_angle"], dec["margin"], floor)
+    return {"status": dec["status"], "chosen_angle": dec["chosen_angle"], "margin": dec["margin"],
+            "tie": dec["tie"], "score_kind": dec["score_kind"], "applied_angle": turn["applied_angle"],
+            "floored": turn["floored"], "floor": floor, "variant": ORIENT_VARIANT}
+
+
+def decision_cache_path(cache_dir: Path, input_sha256: str, orient_ident: str) -> Path:
+    """One decision per input bytes and per orientation identity (judge weights or endpoint and revision, prompt
+    sha, floor, processor geometry, preprocessing)."""
+    return Path(cache_dir) / f"orient-{input_sha256}-{orient_ident}.json"
+
+
+def orient_cached(im, input_sha256: str, orient_ident: str, cache_dir: Path, ask: Callable[..., dict],
+                  prompt: str, png_of: Callable, write: Callable[[Path, bytes], None], floor: float) -> dict:
+    path = decision_cache_path(cache_dir, input_sha256, orient_ident)
+    if path.is_file():
+        try:
+            cached = json.loads(path.read_text(encoding="ascii"))
+            if isinstance(cached, dict) and "applied_angle" in cached:
+                return dict(cached, cached=True)
+        except ValueError:
+            pass
+    dec = probe_page(im, ask, prompt, png_of, floor)
+    write(path, (json.dumps(dec, sort_keys=True) + "\n").encode("ascii"))
+    return dict(dec, cached=False)

inference/wasabi_read/output.py

@@ -0,0 +1,188 @@
+"""Per-page atomic output, sidecar, skip/resume, single-process lock and fsync'ed journal.
+
+Each page is written when it finishes (tmp + fsync + os.replace) so a rerun redoes only missing pages.
+"""
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import json
+import os
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from . import PortError
+from .identity import page_key
+
+STATE_DIR = ".wasabi-read"
+JOURNAL_NAME = "journal.jsonl"
+JOURNAL_SCHEMA = "wasabi-read-journal-v1"
+SIDECAR_SCHEMA = "wasabi-read-page-v1"
+
+
+def utc_stamp() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _fsync_dir(path: Path) -> None:
+    try:
+        fd = os.open(str(path), os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        os.fsync(fd)
+    except OSError:
+        pass
+    finally:
+        os.close(fd)
+
+
+def atomic_write_bytes(path: Path, data: bytes, unique: bool = False) -> None:
+    """Write <path>.tmp, flush + fsync, os.replace onto <path>. A failure leaves no <path> from this call.
+    unique=True adds the pid and thread id to the tmp name (cache files that two pages with identical bytes share)."""
+    path = Path(path)
+    suffix = f".{os.getpid()}.{threading.get_ident()}.tmp" if unique else ".tmp"
+    tmp = path.with_name(path.name + suffix)
+    with tmp.open("wb") as handle:
+        handle.write(data)
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.replace(tmp, path)
+    _fsync_dir(path.parent)
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+class OutputStore:
+    def __init__(self, out_dir: Path, identity: dict[str, Any], identity_digest: str, overwrite_stale: bool = False):
+        self.out_dir = Path(out_dir)
+        self.state = self.out_dir / STATE_DIR
+        self.identity = identity
+        self.identity_digest = identity_digest
+        self.overwrite_stale = overwrite_stale
+        self._lock_handle = None
+
+    # ---- lifecycle
+    def open(self) -> "OutputStore":
+        self.out_dir.mkdir(parents=True, exist_ok=True)
+        for sub in ("pages", "cache"):
+            (self.state / sub).mkdir(parents=True, exist_ok=True)
+        handle = (self.state / ".lock").open("a", encoding="ascii")
+        try:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            handle.close()
+            raise PortError(f"another wasabi_read process is running this output directory: {self.out_dir}") from None
+        self._lock_handle = handle
+        self.discard_tmp()
+        data = (json.dumps(self.identity, indent=1, sort_keys=True, ensure_ascii=True) + "\n").encode("ascii")
+        path = self.state / "identity.json"
+        if not path.is_file() or path.read_bytes() != data:  # an unchanged identity is not rewritten
+            atomic_write_bytes(path, data)
+        return self
+
+    def close(self) -> None:
+        if self._lock_handle is not None:
+            try:
+                fcntl.flock(self._lock_handle.fileno(), fcntl.LOCK_UN)
+            finally:
+                self._lock_handle.close()
+                self._lock_handle = None
+
+    def __enter__(self) -> "OutputStore":
+        return self.open()
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def discard_tmp(self) -> list[str]:
+        """A .tmp left by a killed run is never trusted: it is removed (renamed aside is not needed, it is partial)."""
+        gone = []
+        for base in (self.out_dir, self.state / "pages", self.state / "cache", self.state):
+            for tmp in base.glob("*.tmp"):
+                tmp.unlink()
+                gone.append(tmp.name)
+        return gone
+
+    # ---- paths
+    def md_path(self, stem: str) -> Path:
+        return self.out_dir / (stem + ".md")
+
+    def sidecar_path(self, stem: str) -> Path:
+        return self.state / "pages" / (stem + ".json")
+
+    def cache_path(self, kind: str, name: str) -> Path:
+        return self.state / "cache" / f"{kind}-{name}"
+
+    # ---- resume
+    def read_sidecar(self, stem: str) -> dict | None:
+        path = self.sidecar_path(stem)
+        if not path.is_file():
+            return None
+        try:
+            value = json.loads(path.read_text(encoding="ascii", errors="replace"))
+        except ValueError:
+            return None
+        return value if isinstance(value, dict) else None
+
+    def page_state(self, stem: str, input_sha256: str) -> str:
+        """'done' (output + matching sidecar + matching bytes), 'pending' (nothing usable on disk) or 'stale'
+        (an output exists that this package identity / input did not write)."""
+        md = self.md_path(stem)
+        if not md.is_file() or md.stat().st_size == 0:
+            return "pending"
+        side = self.read_sidecar(stem)
+        want = page_key(input_sha256, self.identity_digest)
+        if (side and side.get("page_key") == want and side.get("input_sha256") == input_sha256
+                and side.get("md_sha256") == sha256_bytes(md.read_bytes())):
+            return "done"
+        return "stale"
+
+    def classify(self, pages: list[tuple[str, str]]) -> dict[str, list[str]]:
+        """pages = [(stem, input_sha256)]. Stale pages refuse unless overwrite_stale (then they are pending)."""
+        out: dict[str, list[str]] = {"done": [], "pending": [], "stale": []}
+        for stem, sha in pages:
+            out[self.page_state(stem, sha)].append(stem)
+        if out["stale"] and not self.overwrite_stale:
+            raise PortError(
+                f"{len(out['stale'])} output file(s) were not written by this input/package identity "
+                f"(e.g. {out['stale'][0]}.md); rerun with --overwrite-stale to replace them")
+        if out["stale"]:
+            out["pending"] = sorted(out["pending"] + out["stale"])
+        return out
+
+    # ---- writing
+    def write_page(self, stem: str, text: str, input_sha256: str, extra: dict[str, Any]) -> None:
+        data = text.encode("utf-8")
+        side = {"schema": SIDECAR_SCHEMA, "stem": stem, "input_sha256": input_sha256,
+                "page_key": page_key(input_sha256, self.identity_digest), "identity_sha256": self.identity_digest,
+                "md_sha256": sha256_bytes(data), "utc": utc_stamp(), **extra}
+        atomic_write_bytes(self.sidecar_path(stem),
+                           (json.dumps(side, indent=1, sort_keys=True, ensure_ascii=True) + "\n").encode("ascii"))
+        atomic_write_bytes(self.md_path(stem), data)
+
+    # ---- journal
+    def journal_append(self, record: dict[str, Any]) -> None:
+        line = json.dumps({"schema": JOURNAL_SCHEMA, "utc": utc_stamp(), **record},
+                          sort_keys=True, ensure_ascii=True) + "\n"
+        with (self.state / JOURNAL_NAME).open("a", encoding="ascii") as handle:
+            handle.write(line)
+            handle.flush()
+            os.fsync(handle.fileno())
+
+    def read_journal(self) -> list[dict[str, Any]]:
+        path = self.state / JOURNAL_NAME
+        rows = []
+        if path.is_file():
+            for line in path.read_text(encoding="ascii", errors="replace").splitlines():
+                try:
+                    row = json.loads(line)
+                except ValueError:
+                    continue  # a torn last line of a killed run
+                if isinstance(row, dict):
+                    rows.append(row)
+        return rows

inference/wasabi_read/prompts/draft.txt

@@ -0,0 +1,7 @@
+文書画像を忠実に転記してください。
+本文と見出しを含め、画像内に記載された文字内容を最後まで省略せず、ページの読み順に出力してください。
+表は有効な HTML の <table>...</table> として表現してください。表の構造に LaTeX の表環境（\begin{tabular} など）を使わないでください。
+独立した数式は、組版可能な LaTeX 数式として表現してください。この LaTeX 形式を表の構造には使わないでください。
+数式は必ず区切り記号で囲んでください。文中の数式は $...$、独立した数式は単独の行に $$...$$ とし、手書きや写真の紙面でも Unicode の記号だけで書かないでください。
+ルビは <ruby>親文字<rt>よみ</rt></ruby> の形で保持してください。
+転記済みの内容を繰り返して出力長を埋めないでください。ページ末尾に到達した時点で終了してください。

inference/wasabi_read/prompts/orient-upright.txt

@@ -0,0 +1 @@
+Is the text in this image upright, that is, neither turned sideways nor upside down? Answer with only yes or no.

inference/wasabi_read/reliability.py

@@ -0,0 +1,123 @@
+"""Degeneration check, temperature ladder and typed outcome for one page.
+
+`loop_stop` is truncation (length) class.
+"""
+from __future__ import annotations
+
+import gzip
+import time
+from typing import Callable
+
+LADDER = (0.1, 0.3, 0.5, 0.8)
+BASE_SEED = 42
+DEGEN_MIN_BYTES = 400
+DEGEN_GZIP_RATIO = 0.18
+LENGTH_CLASS = frozenset({"length", "loop_stop"})
+INFRA_CLASS = frozenset({"time_budget", "error", "timeout", "http_error", "unknown"})
+
+
+def is_degen(text: str, finish_reason: str | None) -> bool:
+    if finish_reason in LENGTH_CLASS:
+        return True
+    b = (text or "").encode("utf-8", "ignore")
+    return len(b) > DEGEN_MIN_BYTES and len(gzip.compress(b)) / max(len(b), 1) < DEGEN_GZIP_RATIO
+
+
+def outcome_class(cand: dict) -> str:
+    fr = cand.get("finish_reason")
+    if cand.get("error") is not None or fr in INFRA_CLASS or fr is None:
+        return "infra"
+    if fr in LENGTH_CLASS:
+        return "length"
+    return "content"
+
+
+def rung_params(rung: int) -> tuple[float, int]:
+    """(temperature, seed): rung 0 is greedy (temperature 0) with seed 42; rung k is LADDER[k-1] with seed 42+k."""
+    if rung == 0:
+        return 0.0, BASE_SEED
+    if not 1 <= rung <= len(LADDER):
+        raise ValueError(f"rung {rung} outside the four-rung ladder")
+    return LADDER[rung - 1], BASE_SEED + rung
+
+
+def read_page(image_id: str, call: Callable[[int, float, int, float], dict], *, page_budget_s: float,
+              clock=time.monotonic) -> dict:
+    """First pass + ladder for one page. `call(rung, temperature, seed, remaining_s)` returns a candidate dict with at
+    least content / finish_reason / error. An infra outcome is retried once (never after time_budget); a
+    length-class or degenerate answer is re-asked only through the ladder; the first non-degenerate answer is kept."""
+    t0 = clock()
+    cands: list[dict] = []
+    infra_retries = 0
+
+    def attempt(rung: int):
+        nonlocal infra_retries
+        temp, seed = rung_params(rung)
+        for infra_try in (0, 1):
+            remaining = page_budget_s - (clock() - t0)
+            if remaining <= 0:
+                c = {"content": "", "finish_reason": "time_budget", "error": "per-page budget exhausted before request"}
+            else:
+                c = dict(call(rung, temp, seed, remaining))
+            c.update({"image_id": image_id, "candidate_index": len(cands), "rung": rung,
+                      "infra_retry": infra_try, "temperature": temp, "seed": seed})
+            c.setdefault("content", "")
+            c.setdefault("error", None)
+            c["outcome_class"] = outcome_class(c)
+            c["degenerate"] = None if c["outcome_class"] == "infra" else is_degen(c["content"], c.get("finish_reason"))
+            c["selected"] = False
+            cands.append(c)
+            if c["outcome_class"] != "infra":
+                return c
+            if infra_try == 0 and c.get("finish_reason") != "time_budget":
+                infra_retries += 1
+                continue
+            return None
+        return None
+
+    first = attempt(0)
+    rec = {"image_id": image_id, "candidates": cands}
+    if first is None:
+        rec.update(outcome="error", first_index=None, selected_index=None, first_text="", final_text="",
+                   first_finish_reason=None, final_finish_reason=None, initial_degen=None, final_degen=None,
+                   retry_attempts=0, retry_adoptions=0, infra_retries=infra_retries, ladder_end="first_pass_infra")
+        return rec
+    sel = first
+    retry_attempts = adoptions = 0
+    ladder_end = "healthy_first_pass"
+    for rung in range(1, len(LADDER) + 1):
+        if not is_degen(sel["content"], sel.get("finish_reason")):
+            ladder_end = "selected_non_degenerate" if rung > 1 else "healthy_first_pass"
+            break
+        retry_attempts += 1
+        c = attempt(rung)
+        if c is None:
+            ladder_end = "infra_ended_ladder"
+            break
+        if not is_degen(c["content"], c.get("finish_reason")) or len(c["content"]) < len(sel["content"]):
+            sel = c
+            adoptions += 1
+    else:
+        ladder_end = ("selected_non_degenerate" if not is_degen(sel["content"], sel.get("finish_reason"))
+                      else "ladder_exhausted")
+    sel["selected"] = True
+    rec.update(outcome="ok", first_index=first["candidate_index"], selected_index=sel["candidate_index"],
+               first_text=first["content"], final_text=sel["content"],
+               first_finish_reason=first.get("finish_reason"), final_finish_reason=sel.get("finish_reason"),
+               initial_degen=is_degen(first["content"], first.get("finish_reason")),
+               final_degen=is_degen(sel["content"], sel.get("finish_reason")),
+               retry_attempts=retry_attempts, retry_adoptions=adoptions,
+               infra_retries=infra_retries, ladder_end=ladder_end)
+    return rec
+
+
+def page_verdict(rec: dict) -> tuple[bool, str]:
+    """(usable, reason): a page is written only when the call succeeded, the final answer is non-degenerate and
+    non-empty. A degenerate, empty or infra-failed page is never written (typed reason for the run report)."""
+    if rec.get("outcome") != "ok":
+        return False, "infra:" + str(rec.get("ladder_end") or "error")
+    if rec.get("final_degen"):
+        return False, "degenerate:" + str(rec.get("final_finish_reason"))
+    if not (rec.get("final_text") or "").strip():
+        return False, "empty"
+    return True, "ok"

inference/wasabi_read/views.py

@@ -0,0 +1,80 @@
+"""Whole-page view enlarged to N image tokens.
+"""
+from __future__ import annotations
+
+import io
+import math
+
+WHOLE_UPSCALE_CELL = 28
+WHOLE_UPSCALE_LEN_MARGIN = 4096
+#: The processor's own cap: a page is sent at its native size (never enlarged) and the server downsamples above it.
+NATIVE_TOKENS = 4096
+ALLOWED_TOKENS = (4096, 8192, 16384)
+
+
+def whole_upscale_fill_grid(w: int, h: int, budget: int, cell: int = WHOLE_UPSCALE_CELL) -> tuple[int, int]:
+    """Largest (cols, rows) with the page's aspect ratio and cols * rows <= budget."""
+    if w <= 0 or h <= 0:
+        raise ValueError("empty page")
+    if budget < 1:
+        raise ValueError(f"budget must be >= 1, got {budget}")
+    s = math.sqrt(budget * cell * cell / (w * h))
+    cols, rows = max(1, math.floor(w * s / cell)), max(1, math.floor(h * s / cell))
+    while cols * rows > budget:
+        if cols >= rows:
+            cols -= 1
+        else:
+            rows -= 1
+    return cols, rows
+
+
+def whole_upscale_native_grid(w: int, h: int, cell: int = WHOLE_UPSCALE_CELL) -> tuple[int, int]:
+    return max(1, w // cell), max(1, h // cell)
+
+
+def whole_upscale_target(w: int, h: int, tokens: int, cell: int = WHOLE_UPSCALE_CELL) -> dict:
+    """Enlarge to the largest cell-aligned size whose grid fits `tokens`, iff that grid is larger than the native
+    grid and the native grid is under the budget; otherwise the page is sent native."""
+    n_cols, n_rows = whole_upscale_native_grid(w, h, cell)
+    f_cols, f_rows = whole_upscale_fill_grid(w, h, tokens, cell)
+    enlarge = f_cols * f_rows > n_cols * n_rows and n_cols * n_rows < tokens
+    sw, sh = (f_cols * cell, f_rows * cell) if enlarge else (w, h)
+    return {"native_wh": [w, h], "sent_wh": [sw, sh], "upscaled": enlarge,
+            "scale": round(sw / w, 4) if enlarge else 1.0,
+            "native_cells": n_cols * n_rows,
+            "expected_cells": f_cols * f_rows if enlarge else min(n_cols * n_rows, tokens)}
+
+
+def whole_upscale_max_model_len(tokens: int, max_tokens: int, base: int,
+                                margin: int = WHOLE_UPSCALE_LEN_MARGIN) -> int:
+    need = int(tokens) + int(max_tokens) + int(margin)
+    return max(int(base), -(-need // 1024) * 1024)
+
+
+def view_target(w: int, h: int, tokens: int) -> dict:
+    """The whole-view resize for a token setting. 4096 = the native whole view: no enlargement (differs from
+    whole_upscale_target(4096), which would enlarge a small page to fill 4096)."""
+    if tokens not in ALLOWED_TOKENS:
+        raise ValueError(f"unsupported whole-view token setting {tokens}; choose from {ALLOWED_TOKENS}")
+    if tokens == NATIVE_TOKENS:
+        n_cols, n_rows = whole_upscale_native_grid(w, h)
+        return {"native_wh": [w, h], "sent_wh": [w, h], "upscaled": False, "scale": 1.0,
+                "native_cells": n_cols * n_rows, "expected_cells": min(n_cols * n_rows, tokens)}
+    return whole_upscale_target(w, h, tokens)
+
+
+def png_bytes(im) -> bytes:
+    buf = io.BytesIO()
+    im.save(buf, format="PNG", optimize=False)
+    return buf.getvalue()
+
+
+def prepare_whole(im, tokens: int):
+    """(PIL image to send, record). A page that is not enlarged is returned unchanged."""
+    from PIL import Image
+    w, h = im.size
+    rec = view_target(w, h, int(tokens))
+    rec["tokens"] = int(tokens)
+    if not rec["upscaled"]:
+        return im, rec
+    return im.resize(tuple(rec["sent_wh"]), Image.Resampling.LANCZOS), rec