franken_ocr

franken_ocr

A pure-Rust, memory-safe, CPU-only OCR engine for a small family of hand-ported vision-language models. Baidu Unlimited-OCR is the fast default for document OCR, GOT-OCR2 handles specialized structured formats, SmolVLM2 handles image description and VQA, OneChart extracts chart data, and Polyphonic-TrOMR turns full scanned sheet-music pages or staff crops into MusicXML through --task music. All five runtime models are available through focr pull; TrOMR publishes both the 61 MB int8 default artifact and an 86 MB f32 reference artifact. The v0.7.0 Unlimited-OCR artifact uses the conservative exact recipe and passes the hard-page termination and complete 20-page corpus budget. The models run through model-specific Rust kernels and need no general ML framework, Python, CUDA, FFI at inference, or GPU.

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/franken_ocr/main/install.sh | bash

irm https://raw.githubusercontent.com/Dicklesworthstone/franken_ocr/main/install.ps1 | iex

The installer detects your platform, resolves the latest published GitHub binary release (currently v0.10.0), verifies the downloaded asset by SHA256, and puts focr on your PATH. Install compatible model weights separately; after they are present, inference is offline.

Current Release

v0.10.0 ships raw executables for macOS Apple Silicon, macOS Intel, Linux x86-64, Linux ARM64, Windows x86-64, and Windows ARM64, each with a SHA256 sidecar. Its embedded schema-v2 manifest continues to pin the v0.7.0 4,157,448,783-byte Unlimited-OCR artifact using recipe unlimited-ocr-ffn-int8-attn-bf16-lmhead-bf16-v1; focr pull verifies all three part hashes and the reassembled file before installation.

The exact-recipe artifact emits EOS on page0590 and passes the complete 20-page corpus budget at aggregate normalized CER 0.19307925. The release does not claim the strict three-party OpenPGP certificate: the committed fail-closed finalizer requires three independently controlled registry-pinned signers and production audit receipts, which are not available in this release process. The local corpus, model-census, installer, and binary checks are evidence, not a substitute for that governance claim.

TL;DR

The problem. Baidu Unlimited-OCR is a strong document-parsing model: Markdown, tables, LaTeX, reading order, many pages in one pass. The official stack is Python plus CUDA. Most machines that need OCR (laptops, CI runners, agent hosts, edge boxes) have no usable GPU, and a Python plus CUDA dependency is heavy to ship and awkward to embed.

The solution. franken_ocr is a library plus a single-binary CLI (focr) that runs the ready model set on CPU with nothing but a Rust binary. It transforms bf16 checkpoints into custom .focrq int8 artifacts and runs them through kernels written for each model’s exact shapes. A historical real-page Unlimited-OCR run measured end-to-end character-error-rate 0.0094 and matched the reference decode to within a single token. The v0.7.0 corpus receipt records 20/20 pages within budget and a still-high page0590 tail; the release publishes that measured artifact without claiming the unavailable three-party signing certificate.

Why focr?

System Map

Quick Example

# 1. Install the versioned conservative Unlimited-OCR artifact.
focr pull

# 2. OCR a page into Markdown (the human default).
focr ocr page.png

# 3. Same page as structured JSON (markdown + every span's bounding boxes).
focr ocr page.png --json

# 4. Write the result to a file; format follows the extension (.md or .json).
focr ocr page.png -o page.md
focr ocr page.png -o page.json            # structured JSON with bounding boxes

# 5. Also save figures the model can't transcribe (charts/photos) next to the .md.
focr ocr page.png -o page.md --extract-figures   # -> page.md + page_figures/

# 6. Use a specialized model when the task is not plain document OCR.
focr pull got-ocr2
focr ocr --model got-ocr2.int8.focrq --task tables table.png

focr pull smolvlm2
focr ocr --model smolvlm2.int8.focrq --task describe photo.jpg
focr ocr --model smolvlm2.int8.focrq --task describe --question "How many people are visible?" photo.jpg

focr pull onechart
focr ocr --model onechart.int8.focrq --task chart-data chart.png

focr pull tromr
focr ocr --model tromr.int8.focrq --task music score-page-or-staff.png -o score.musicxml
focr pull tromr --quant f32                 # bit-exact reference artifact when needed
focr ocr --model tromr.focrq --task music score-page-or-staff.png -o score.musicxml

# 7. OCR only the pages you need from a scanned PDF; optionally split two-page spreads.
focr ocr book.pdf --pages 3,5-9 --split-spreads -o excerpt.md

# 8. Stream NDJSON pipeline events for an agent (music runs also emit `staff` events).
focr ocr page.png --robot
focr robot triage

# 9. Prove the int8 kernels on THIS CPU are bit-identical to the scalar oracle.
focr robot selftest

# 10. Generate the parity-ladder and release-readiness scorecards used by release gates.
scripts/ladder_scorecard.sh --self-test
scripts/ladder_scorecard.sh --out scorecard.json
python3 scripts/gauntlet_cert.py --self-test
python3 scripts/bench_guardrail.py --self-test
python3 scripts/gauntlet_cert.py --from-parity docs/FEATURE_PARITY.md \
  --scorecard-out /tmp/focr-release-scorecard.json
# From a clean final source/evidence commit, produce the red provisional bundle.
# It exits 1 until fresh CI artifacts and three trusted signers finalize it.
python3 scripts/gauntlet_cert.py --bundle .gauntlet-output/bundle
# After downloading the exact CI, dist, Model Parity, and Performance Gauntlet
# artifacts for this HEAD, run --finalize-bundle as documented in
# docs/gauntlet/RELEASE_CERTIFICATION_TEMPLATE.md.
python3 scripts/gauntlet_cert.py --release-readiness \
  --readiness-out .gauntlet-output/release_readiness.json

# 11. (optional) Convert the exact pinned Unlimited-OCR bf16 shard.
# Same-shaped or reserialized inputs fail before an unloadable artifact is written.
focr convert model.safetensors -o unlimited-ocr.focrq --quant int8

# TrOMR conversion is available for local sheet-music artifacts.
focr convert /path/to/tromr/model.safetensors -o tromr.int8.focrq --quant int8 --model-id tromr

With FOCR_MODEL_PATH set, default-model inference runs fully offline. Compatible specialized pulls live under ~/.cache/franken_ocr/models and are also offline after installation.

Design Philosophy

A few models, every dimension fixed. A general ML framework pays a generality tax on every operation: dynamic dtype dispatch, arbitrary shapes, autograd bookkeeping, broadcast machinery, and a device abstraction. franken_ocr runs a small set of hand-ported models whose important dimensions are known up front. For the default Unlimited-OCR path that means hidden 1280, 10 heads, head_dim 128, 64 experts, top-6 routing, MoE intermediate 896, R-SWA window 128, and vocab 129280. That buys shape-specialized kernels with no runtime shape branching in the hot loop. The scope is a few hand-tuned, certified models, not any model; there is no generic runtime underneath.

Model status is explicit. focr models is the source of truth for the runtime zoo. Ready models have a runtime forward arm and can be used with focr ocr; planned models are visible so agents and humans can see the roadmap without accidentally running the wrong architecture. The table distinguishes runtime readiness from distribution compatibility. Unlimited-OCR, GOT-OCR2, SmolVLM2, OneChart, and TrOMR are pullable in v0.7.0. Non-primary models install into per-model cache subdirectories with their tokenizer sidecars beside the .focrq artifact. TrOMR publishes both int8 and f32 artifacts: the default pull is the smaller int8 artifact, while focr pull tromr --quant f32 restores the bit-exact reference path for audits.

Scanned books are addressable. PDF input no longer means “the whole document or nothing.” --pages 3,5-9 selects source pages with 1-based ranges, reports out-of-range requests against the document page count, and keeps source page numbers in JSON/robot output. The native renderer applies both PDF page /Rotate metadata and the rotation implied by the image placement matrix, which fixes scanned-book files that store portrait page images but display them landscape through a rotated cm transform. --split-spreads is opt-in for common two-page book scans: a wide rasterized page with a near-blank center gutter becomes left and right logical pages, while pages without a qualifying gutter pass through unsplit.

TrOMR page OMR is resilient. TrOMR accepts either a staff crop or a full printed/scanned page. The page path runs pure-Rust staff detection with global deskew, trims horizontal page margins to the detected ink extent, grows wide staff bands toward neighbor midlines so they fit the model’s 1280-column position budget where possible, orders crops top-to-bottom, recognizes each staff sequentially through the certified ResNetV2 plus ViT encoder and four-head decoder, merges the semantic streams, and emits partwise MusicXML. If a band is still too wide, setting FOCR_TROMR_SPLIT=1 arms an experimental rescue that detects thin full-span barlines, splits the band into in-budget segments, and splices the streams (off by default: isolated segments measurably lose absolute pitch registration, so this trades content fidelity for recognition coverage; the skip with a named reason is the honest default). If one detected staff fails, the page still succeeds with the staves that recognized and logs the skipped staff’s bbox and reason; if every staff fails, the error names each staff reason. JSON output includes the ordered staves array for music runs, and robot mode emits one staff event for each recognized or skipped staff before run_complete. The MusicXML emitter also adds annotate-only sanity comments for overfull bars, underfull middle bars, impossible durations, and cross-staff key mismatches; JSON and robot mode expose the same observations as warnings and music_warning events. Remaining TrOMR work is narrower: optional **kern export, camera-photo dewarp, and broader corpus-quality metrics.

Performance claims are ledgered. The A11 zoo gauntlet records native runs beside pinned Hugging Face CPU references for GOT-OCR2, SmolVLM2, and OneChart. Decode-per-token speedups are documented where the native path is ahead, and full end-to-end rows stay in the ledger even when artifact loading or preprocessing makes the total slower. The CPU backend also records losing rows, such as the f32 TrOMR baseline, instead of turning them into marketing claims. The README summarizes measured rows; docs/PERF_LEDGER.md is the audit trail.

Offline at inference. Network access is limited to explicit compatible pull commands; inference itself never downloads. Raw BF16 or locally converted Unlimited weights can be supplied through FOCR_MODEL_PATH. There is no Python, no CUDA, no FFI, and no GPU in the inference path. The async runtime that orchestrates I/O and cancellation is an owned internal detail; the library API is synchronous and blocking, so there is no async plumbing to thread through your code.

Correctness before speed (always). A parity gate comes first and a faster kernel that drifts the OCR output is reverted, no source landed, and recorded in the negative-evidence ledger. Speed is shipped on top of parity, never instead of it. The conservative recipe keeps the vision tower, projector, embeddings, attention, lm_head, MoE router, and all norms high precision. The v0.7.0 artifact passes page0590 termination and the 20-page corpus budget, with the hard-page CER tail documented. Those measurements do not imply the separate three-party signing certificate.

Conformance has receipts. The L0-L5 parity ladder emits structured NDJSON, and scripts/ladder_scorecard.sh folds that stream into one focr-ladder-scorecard/v1 artifact. An unarmed no-weights run is recorded as skipped_no_model:true, never as green. docs/FEATURE_PARITY.md splits the release surface into the numbered FeatureUniverse and the CLI/robot SurfaceMatrix; tests/surface_matrix.rs fails if a live subcommand, robot event, exit code, or rollup cell is missing from that ledger. The three-pillar gauntlet in docs/gauntlet/METHODOLOGY.md and scripts/gauntlet_cert.py turns those rows into a franken_ocr.gauntlet.scorecard.v1 artifact, while the release ratchet compares lower bounds rather than point estimates. A change that improves the aggregate while lowering one category is blocked.

Runtime ISA dispatch, one binary per arch. There is no per-CPU-feature variant to choose. One x86_64 binary covers AVX2 / AVX-VNNI / AVX-512-VNNI; one aarch64 binary covers NEON / SDOT / SMMLA. Hardware capability and the effective ordinary dense-int8 route are distinct: Apple Silicon exposes SDOT/SMMLA, but measured decode results select the LLVM-autovectorized scalar loop by default. Forced SDOT and SMMLA remain available for parity and benchmark sweeps. Non-Apple ARM64 can select SMMLA when it is actually faster. On a Threadripper 5995WX, a Zen 3 part whose ceiling is AVX2, dispatch correctly selects AVX2.

Bounded generated-token KV. Every decoder attention layer is R-SWA (Reference Sliding Window Attention). Each generated token attends to all reference tokens (visual plus prompt prefix, kept as a frozen, never-evicted global KV) plus only the previous 128 generated tokens through a ring-buffer KV cache. Generated-token KV memory stays constant instead of growing with output length. That, not arbitrary input resolution, is what “Unlimited” means.

How franken_ocr Compares

franken_ocr is the only one of these built for a fixed, hand-tuned set of models on CPU.

When to use franken_ocr:

• You need this model’s output and your host has no usable GPU.
• You want to embed OCR in a Rust program with no Python or FFI.
• You want one binary you can drop on a CI runner, an agent host, or an edge box.

When franken_ocr might not be ideal:

• You need a generic inference runtime that loads arbitrary models. franken_ocr runs a few hand-ported, certified models by design.
• You need the OmniDocBench leader; Unlimited-OCR is strong but not the top of the board.

Installation

Quick install (recommended)

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/franken_ocr/main/install.sh | bash

The script detects your OS and CPU architecture, downloads the matching asset from the latest published binary release, verifies the SHA256 sidecar, and installs focr. At the time this source tag was cut, the latest published binary release was v0.10.0. Under WSL it proceeds as Linux. Under native Git-Bash, MSYS, or Cygwin it points you at the PowerShell installer below and exits cleanly.

On native Windows, install from PowerShell:

irm https://raw.githubusercontent.com/Dicklesworthstone/franken_ocr/main/install.ps1 | iex

This selects focr-x86_64-pc-windows-msvc.exe on AMD64 or focr-aarch64-pc-windows-msvc.exe on ARM64, verifies it by SHA256, and puts focr on your PATH. Both installers stage and execute the verified binary before an atomic replacement while holding a destination-scoped process lock, so a failed or concurrent update does not clobber a working install. Both Windows architectures are part of the v0.10.0 release matrix.

Homebrew (macOS / Linux)

brew install dicklesworthstone/tap/focr

The formula installs the same SHA256-pinned release binary for your platform.

Manual binary download

Release binaries are raw executables, not tar.gz archives. Each one is a single portable file that dispatches the ISA tier at runtime, so there is one binary per architecture (no per-CPU-feature variant). Linux assets are GNU binaries linked for glibc 2.17 or newer; the dist producer independently replays readelf against the exact staged bytes and refuses a higher required symbol version.

Each asset has a <asset>.sha256 sidecar in the standard "<hex> <asset>" format. Download the binary and its sidecar from the release base URL, verify, then install. Example for Apple Silicon:

base=https://github.com/Dicklesworthstone/franken_ocr/releases/download/v0.10.0
asset=focr-aarch64-apple-darwin-neon-sdot-i8mm

curl -fsSLO "$base/$asset"
curl -fsSLO "$base/$asset.sha256"

# macOS: shasum -a 256 -c   |   Linux: sha256sum -c
shasum -a 256 -c "$asset.sha256"

chmod +x "$asset"
mv "$asset" /usr/local/bin/focr

On Linux, swap the asset name and use sha256sum -c "$asset.sha256".

From source (advanced; not a one-liner)

franken_ocr requires the nightly Rust toolchain pinned in rust-toolchain.toml. cargo build --locked --release builds both the focr and franken_ocr binaries from one shared entrypoint.

As of v0.10.0 the crate and its dependency closure (frankentorch-core, frankentorch-kernel-cpu, the fsqlite family, asupersync) are published on crates.io, so franken_ocr can be used as a library dependency. Two caveats: the crate requires the pinned nightly toolchain on aarch64 (stdarch feature gates in lib.rs), so cargo install franken_ocr fails on a stable default toolchain there, and the registry build is not the byte-exact release binary. Prebuilt binaries remain the supported install path. A source checkout build still expects the sibling repositories (../asupersync, ../frankentorch, ../frankensqlite) laid out beside it (the workspace path-deps win over the registry).

cargo build --locked --release
# produces target/release/focr and target/release/franken_ocr (identical behavior)

Quick Start

1. Install the binary with the curl one-liner, or download and verify a release asset by hand.
2. Install compatible weights: run focr pull for the versioned conservative Unlimited-OCR artifact. Long documents can use focr pull unlimited-ocr-2; specialized models use focr pull got-ocr2, focr pull smolvlm2, focr pull onechart, or focr pull tromr. Raw BF16 and locally converted exact-recipe artifacts remain available through FOCR_MODEL_PATH.
3. Verify your CPU kernels (optional but reassuring): focr robot selftest. Exit 0 means the dispatched int8 GEMM cases, including the model-specific rows for Unlimited-OCR, GOT-OCR2, SmolVLM2, and OneChart, are bit-identical to the scalar oracle on this host.
4. OCR a page: focr ocr page.png for Markdown, add --json for structured output (markdown + bounding boxes), -o out.md / -o out.json to write a file, or --robot for an NDJSON event stream.
5. Batch many pages in one process (model loaded once): focr ocr-batch page1.png page2.png page3.png --json. Add --multi-page to parse them as ONE cross-referencing document instead of independent pages.

Library API

franken_ocr is a library as well as a CLI. The public API is synchronous and blocking: OcrEngine owns the internal asupersync runtime, loads the model on first use, caches that model behind an Arc, and returns ordinary FocrResult<T> values. Callers do not need to build or pass an async runtime.

use std::path::Path;

use franken_ocr::{OcrEngine, FocrResult};

fn main() -> FocrResult<()> {
    let engine = OcrEngine::new()?;

    let markdown = engine.recognize(Path::new("page.png"))?;
    println!("{markdown}");

    let document = engine.recognize_with_layout(Path::new("page.png"))?;
    println!("{} layout spans", document.layout.len());

    Ok(())
}

The same engine exposes the surfaces the CLI uses:

OcrEngine belongs to the native feature. A program that wants the engine alone links default-features = false, features = ["library"], which brings no CLI, async runtime, run store, signal handler or network path, and calls OcrModel directly. docs/library-output.md is its versioned contract: page and span fields, box coordinates, reading order, side effects and what is not promised.

A document parse, using the pages of a PDF:

use std::path::Path;

use franken_ocr::page_source::PageSource;
use franken_ocr::{DocumentOptions, FocrResult, OcrEngine};

fn main() -> FocrResult<()> {
    let engine = OcrEngine::new()?;
    let source = PageSource::pdf(Path::new("book.pdf"))?.select(Some("1-20"))?;
    let document = engine.recognize_document(
        &OcrEngine::model_path(),
        source,
        &DocumentOptions::default(),
        Box::new(|_| {}),
        Some(Box::new(|page| eprintln!("page {} done", page.index))),
    )?;
    println!("{}", document.markdown);
    eprintln!("{} pages, finish: {}", document.pages.len(), document.finish_reason.as_str());
    Ok(())
}

Model resolution follows the CLI rules: FOCR_MODEL_PATH wins, then the default cache location is searched. For path-explicit calls, pass the model artifact directly. The engine keeps the one-live-forward discipline from the CLI, so a single process can reuse weights without fanning out concurrent model forwards.

Command Reference

Both focr ocr and focr robot run accept the same image plus inference-tuning flags. The default crop mode is base (the certified single 1024-pixel global view); --crop-mode gundam selects the reference dynamic-resolution tiling, whose end-to-end certification is still pending.

focr ocr <image>

Parse a document image into Markdown (default), JSON, or an NDJSON stream.

focr ocr page.png                          # Markdown to stdout
focr ocr page.png --json                   # structured JSON to stdout
focr ocr page.png -o page.md               # write Markdown to a file
focr ocr page.png -o page.json             # write structured JSON (markdown + boxes) to a file
focr ocr page.png -o page.md --extract-figures   # also save figures, referenced from the .md
focr ocr page.png --robot                  # NDJSON pipeline events
focr ocr page.png --crop-mode gundam       # reference dynamic-resolution tiling (uncertified)
focr ocr page.png --max-length 4096 --temperature 0.0
focr ocr page.png --model /path/to/unlimited-ocr.focrq
focr ocr eq.png --task formula --model got-ocr2.int8.focrq   # specialized task routing (see below)
focr ocr chart.png --task chart-data --model onechart.int8.focrq
focr ocr book.pdf --pages 3,5-9 --split-spreads -o excerpt.md
focr ocr ./scans/ --multi-page -o book.md  # a directory of page images as one document
curl -s "$URL" | focr ocr - -o page.md     # an image or a PDF on stdin
focr ocr book.pdf --multi-page --check     # is this run ready? about a second, no weights loaded
focr ocr page.png --raw -o page.raw.txt    # the model's output, grounding markers included
focr ocr page.png --threads 8 --timing     # eight kernel threads, stage timings on stderr

Stdin (-). focr ocr - reads an image or a PDF from stdin, whichever the bytes are. The run holds them in a private temp file and removes it when it ends. A file actually named - is ./-. Empty stdin, or bytes that are neither, exits 4.

Preflight (--check). Runs the checks that can fail before a decode, then stops: the arguments, the input’s header or page list, --pages, the model’s header and tokenizer, and that -o has a directory to write into. It takes about a second on the real artifacts, exits with the code the run would fail with, and records nothing in focr runs. --json prints {command: "ocr.check", ok, input, model, output}. It does not decode pixels, so a truncated image or a PDF page that will not rasterize passes here and fails in the run. Use --json, not --robot, with it.

Output (-o/--output FILE). Writes the result to a file instead of stdout; the format follows the extension: .json emits structured JSON, any other extension (e.g. .md) emits Markdown. --json forces JSON regardless of extension. The structured JSON carries the rendered markdown plus a layout array, one {label, boxes} entry per grounded span, where each box is [x1, y1, x2, y2] in source-image pixels. A span adds text, what the model wrote for that region: the text after its marker, up to the next span, normalized as the markdown is. Image spans have no text, and neither does a region the model boxed without writing anything. An Unlimited-OCR-2 title adds its heading level (1, 2, …). A PDF nests these under a per-page pages array; split spreads become separate logical page entries with the same source page number and a "half": "left" or "right" marker. This is the same shape --json prints to stdout. TrOMR music runs also include a staves array in source order; each entry carries the 1-based staff number, page-space bbox, recognized or skipped status, and an optional skip reason.

Raw output (--raw). Outputs the decode as the model wrote it, grounding markers included: <|det|>label [x1, y1, x2, y2]<|/det|> spans (or the <|ref|> form), or Unlimited-OCR-2’s <BLOCK>label[x1, y1, x2, y2]<FORK> prefixes. It replaces the markdown on stdout and in a text -o file. With JSON it adds a raw string beside the markdown and to each entry of pages, and with --robot to run_complete. Boxes stay on the model’s 0–999 grid, relative to each page, or to each strip of a tall image, so use layout for source-image pixels.

Figures (--extract-figures). The model sees figures/photos/diagrams it does not transcribe to text. With --extract-figures, those regions are cropped out of the source image and saved into a subfolder (default <output-stem>_figures/, or set --figures-dir DIR), then referenced from the output: the Markdown gets a real ![figure N](<output-stem>_figures/page1_figure_1.jpg) in place of each figure, and the JSON gains a figures array of {label, page, bbox, path}. Each figure’s format is chosen by content: JPG (quality 85) for photographic regions, lossless PNG for line-art / charts / screenshots. Requires -o (or --figures-dir for a stdout run). PDFs name figures per page (page{N}_figure_{M}); an Unlimited-OCR-2 document with --split-spreads names a half’s figures page{N}l_… / page{N}r_….

Directory input. focr ocr ./scans/ reads a directory of page images (.png, .jpg, .jpeg, .tif, .tiff, .webp, .bmp, .gif, .pnm and its variants) as one document, in natural order: p2.png comes before p10.png. Each image’s EXIF orientation is applied, as for a single image. Hidden files and subdirectories are passed over. Any other file is left out and reported once as an ignored_files warning (on stderr, run_complete and --json). Everything below that applies to a PDF’s pages applies to a directory’s images.

PDF controls. --pages SPEC is for PDFs and directories only. SPEC is a comma-separated list of 1-based pages and inclusive ranges, such as 3, 3-7, or 1,5-9,218; selected pages run in source order with duplicates removed. Out-of-range pages are usage errors that name the document page count. Before OCR, the pure-Rust PDF path applies both the page /Rotate entry and any axis-aligned rotation from the content stream’s image placement matrix, so scans stored sideways but displayed upright are normalized before OCR or spread splitting. --split-spreads is also off by default and applies only to documents. It looks for wide raster pages with a near-blank vertical gutter near the center, then OCRs the left and right halves as separate logical pages; no qualifying gutter means the page remains unsplit. Pages are rasterized one at a time as the run reaches them, so a long book never holds every page image in memory.

Runaway pages (v1). A v1 page that never ends would decode to the token limit (32,768) and come back mostly repetition. The runaway guard stops it instead: past 8,192 tokens it checks the last 2,048 every 256, and three repeating checks in a row end the decode. The text before that point is written, the run reports finish_reason: runaway and exits 5, and ocr-batch marks that image failed and goes on. In robot mode the text arrives as page events (status: decoded) before the run_error. FOCR_RUNAWAY_GUARD=0 turns it off and decodes to the limit, as the reference does. On ground truth it fires on no OmniDocBench page and on 9 of 18,118 MarathonDocBench pages, 7 with broken references and 2 long charts (DISC-023).

Multi-page cross-page parsing (--multi-page). By default every page is parsed independently. --multi-page instead parses the whole document across pages using the Unlimited-OCR infer_multi contract, so page N can reference content on the pages before it, and the output is a single Markdown document with <PAGE> separators. On focr ocr it takes a PDF or a directory of page images and composes with --pages; for an image list use focr ocr-batch page1.png page2.png --multi-page. v1 has 32,768 positions shared by prompt and output (≈29 dense pages); longer documents stop early and report finish_reason: length with a v1_truncated warning (a prompt that alone exceeds the budget fails with an actionable error). When v1 ends with fewer page bodies than pages, a v1_page_merge warning says the page boundaries are unreliable; with more bodies than pages, a v1_extra_pages warning says it repeated or invented pages. On v1 it does not compose with --split-spreads or --extract-figures (per-page semantics), and --json lists real pages[] only when the text has exactly one body per page (otherwise pages: []).

--page-window N|auto|off sets how unlimited-ocr-2 splits a --multi-page document into decode windows. N is pages per window, at most 102, and the default is 10. auto picks the largest window, up to 10, whose estimated whole-process memory fits FOCR_MEMORY_BUDGET, and refuses with the estimate’s parts when not even one page fits. off reads one pass with no checkpoint, so a long document can stop at the position limit with its pages written and exit 5. Robot mode reports a window event after each window’s pages, and a terminal shows pages and windows done, tokens per second and an estimate of the time left.

Unlimited-OCR-2 (--model unlimited-ocr-2) emits exactly one <PAGE> per page, so its document mode has real pages. A document of more than 10 pages is read in windows of 10: each window’s prompt holds its own pages and the next window’s first, a page sees the pages before it in its window, and memory stays bounded at any length. A window that stops early ends the document with its completed pages. --json lists one pages[] entry per page read: page (the source page), half on a split spread, run_index, window when windowed, text, layout (boxes in that page’s own pixels), tokens and finish (marker, eos, page_cap, runaway, length, budget or cancelled), and raw under --raw. A v2_page_cap warning lists any page the per-page cap (--max-page-tokens, default 20,000) closed, which is almost always a runaway. FOCR_RUNAWAY_GUARD=1 (off by default here) closes such a page sooner: once a page passes 8,192 tokens and its last 2,048 repeat (any number counts as the same token, so a counting loop repeats too), the next page opens. The page ends runaway, keeps its text so far, and is listed in the same warning. With FOCR_REREAD_CAPPED_PAGES=1 (off by default), each such page is read again alone once the document is decoded. The re-read replaces the page when the model ends it, and a v2_page_reread warning lists the pages replaced and the pages kept. Robot page events are not sent again. Document mode composes with --split-spreads (each half is one page of the prompt) and with --extract-figures: figures are cropped from their page after the decode and named page{N}_figure_{M}, or page{N}l_figure_{M} / page{N}r_figure_{M} on a half. Robot page events add source_page, half, model_id, and for decoded pages tokens, finish, window (null in one pass) and, for a page read in one pass, elapsed_ms.

Stopping and resuming a long document. After each window, a windowed Unlimited-OCR-2 run appends its pages to a journal and replaces a checkpoint: <out>.partial and <out>.focr-ckpt beside -o, or ~/.cache/franken_ocr/document-runs/<key>/ when the output goes to stdout. Ctrl+C or a spent stage budget writes the completed pages and exits 6 or 5, and the terminal run_error names the checkpoint. Re-running the same command (--resume says so explicitly) continues from the last completed window, and the result is byte-identical to an uninterrupted run; resumed_from on the terminal event gives the page decoding restarted at, and a stdout run prints the whole document again. The pages of a window that was interrupted are decoded again. A run whose input, page selection or decode settings differ is refused, with the fields named. --resume=recompute then keeps the completed pages and recomputes the next window: the pages after it can differ, so a resume_recompute warning says so. Both files are removed when the document finishes (--keep-checkpoint keeps the checkpoint), and focr doctor lists a stale stdout run with the command that continues it.

Tall captures (full-page screenshots). A full-page browser capture (e.g. the Awesome Screenshot extension) is one extremely tall image — 1:4 to 1:10 aspect. A single model pass over such an image squashes glyphs below legibility and used to come back near-empty with exit 0. Two things now happen instead. First, single images with height ≥ 3× width are automatically OCR’d as smart-cut horizontal strips (each cut lands on the blankest row near the boundary so text lines are not severed) and the per-strip results are merged, with layout boxes mapped back to source-image coordinates — no flags needed; FOCR_TIMING=1 logs the strip plan. Second, a large input that still yields almost no text is flagged: robot mode adds low_yield: true (plus yield_chars and input_megapixels) to run_complete, human mode prints a stderr warning, and --fail-on-low-yield turns it into exit 8 (low_yield) before any output is written. A capture that is low-yield even after strip routing usually has glyphs below ~12px — re-capture at higher resolution; no OCR engine recovers 7px text. Manual alternative for exotic layouts: cut the page yourself and run focr ocr-batch strip1.png strip2.png ….

Tasks (--task). Convenience routing over the model zoo (focr models). --task ocr (the default) is plain document OCR, unchanged. --task formula, tables, chart, molecular, and geometry are served by GOT-OCR2’s OCR with format: mode, so each implies --format (an explicit --format composes idempotently) and needs the got-ocr2 model: focr pull got-ocr2, then --model got-ocr2.int8.focrq. --task chart and --task formula also pad the image to a white square first, because GOT misreads both when upstream’s square resize stretches them; --format alone keeps that resize, and so does every other task. GOT can also read one region of an image, as upstream’s fine-grained mode does: --box x1,y1,x2,y2 in the image’s pixels (or a point x,y), or --color red|green|blue for a frame of that colour drawn around the text. Either composes with --format; a box does not compose with --task chart or --task formula, because they pad the image. --task music has two valid lanes: TrOMR is the native OMR path and returns MusicXML, while GOT-OCR2 can still run its sheet-music format mode. Use focr pull tromr, then --model tromr.int8.focrq --task music for a full printed/scanned page or a staff crop. Use focr pull tromr --quant f32 and --model tromr.focrq when you need the bit-exact reference artifact. You can also use the GOT lane (--model got-ocr2.int8.focrq --task music). --task describe (photo description / VQA) is served by the smolvlm2 model: focr pull smolvlm2, then --model smolvlm2.int8.focrq --task describe, optionally with --question "What color is the car?". SmolVLM2 has no instruction modes; the task is the question (default: the model-card caption prompt). --task chart-data is the OneChart path: it runs chart-to-dict extraction with the number-head reliability check and needs a onechart artifact, for example focr pull onechart, then --model onechart.int8.focrq. A reading that does not pass that check says so with a chart_unverified warning. Pointing a specialized task at the wrong model family fails with usage guidance before any weights load.

Tuning flags: --base-size and --image-size (preprocessing resolution), --crop-mode (gundam or base), --max-length (decode token cap), --temperature (only 0: every model decodes greedily, and anything else exits 2 before a model loads), --no-repeat-ngram and --ngram-window (the sliding no-repeat n-gram decode guard).

focr ocr-batch <images...>

OCR many images in one process, loading the model once and reusing it across all pages.

focr ocr-batch a.png b.png c.png --json     # one load, many pages
FOCR_INT8_ATTN=1 FOCR_INT8_LMHEAD=1 \
  focr ocr-batch *.png --experimental-full-int8  # explicitly arm the gated cache
FOCR_INT8_ATTN=1 FOCR_INT8_LMHEAD=1 FOCR_BATCH_SPINE=1 \
  focr ocr-batch *.png --experimental-full-int8 --json
FOCR_BATCH_SPINE=0 focr ocr-batch *.png --json   # force the sequential oracle path

With --json, each image’s row says how its decode ended: finish_reason, any warnings, and chart on a OneChart run. An Unlimited-OCR-2 page stopped by its stage budget or position limit, or a v1 page the runaway guard stopped, keeps its markdown, but reads ok: false with an error, the same stop that makes focr ocr exit 5. So check ok, not whether markdown is present.

ocr-batch loads the model once either way. Unlimited-OCR defaults to the conservative recipe path. Its continuous-batch R-SWA spine currently belongs to the explicitly gated all-int8 experiment, so FOCR_BATCH_SPINE=1 uses that spine only with --experimental-full-int8 and both accuracy switches shown above. The dense zoo path batches GOT-OCR2, SmolVLM2, and OneChart decode streams. GOT-OCR2 and OneChart reuse hydrated SAM weights, projectors, and widened embedding tables; SmolVLM2 does the same for its SigLIP tower, modality projection, and text embeddings. The same statics are cached on the loaded model for ordinary sequential pages too, so a multi-page PDF or repeated in-process calls no longer re-widen those large tensors for each page. FOCR_BATCH_SIZE defaults to 128 active streams and clamps at 256; FOCR_BATCH_PACK=1 groups similar prefill lengths before restoring output order. Without the experimental flag, attention and lm_head stay high precision by construction.

To watch a long batch, add --progress-events PATH (- for stderr). Each line is one JSON object: batch_start with the resolved thread budget, model and backend, then image_complete or image_error as each image ends, with the pages per hour measured so far and eta_ms, and batch_end with the outcome. stdout does not change, so --json is still one final object. eta_ms is null until one image has ended, then the mean time per image so far times the images left; the first image carries the model load, so the estimate starts high. With --multi-page the lines are page_complete and page_skipped, and batch_start says the pages are one cross-page pass, not independent images. focr robot schema lists every field under batch_progress. The flag refuses FOCR_BATCH_SPINE, which decodes the images together and has no per-image end to report.

--inputs-from FILE reads more paths, one per line, after any named on the command line (- reads stdin). --output-dir DIR writes each image’s markdown to DIR/<stem>.md as it ends, so a stopped batch keeps what it finished; two inputs that would write one file are refused before any work.

An image that fails does not stop the batch: the run goes on, and fails with the first failure’s exit code only if no image was read. --fail-fast stops at the first failure instead. Ctrl+C stops at the image it interrupted, and the run exits 6. Either way the images that ended are still reported, and --json adds "stopped": "image_failed" or "stopped": "cancelled".

focr pull

Download a manifest-compatible model and tokenizer into the cache, verifying every byte. The embedded v0.7.0 Unlimited-OCR entry declares the runtime-compatible conservative recipe unlimited-ocr-ffn-int8-attn-bf16-lmhead-bf16-v1; the historical schema-v1 full-int8 entry remains incompatible and is rejected.

focr pull                                   # versioned conservative Unlimited-OCR artifact
focr pull unlimited-ocr-2                   # long-document successor (4.17 GB, three parts)
focr pull got-ocr2                          # structured OCR model
focr pull smolvlm2                          # image description / VQA model
focr pull onechart                          # chart-to-data model
focr pull tromr                             # sheet-music OMR model (int8 default)
focr pull tromr --quant f32                 # bit-exact reference artifact
focr pull got-ocr2 --quant int8 --json      # explicit quant, machine-readable
focr pull --manifest ./manifest.json        # compatible custom default manifest

Downloads run over asupersync’s native HTTP stack (rustls + webpki-roots), reassemble GitHub split parts, verify against a committed SHA256 manifest, and cache to ~/.cache/franken_ocr/models. Manifest schema v2 requires an exact recipe for every quant; size, paths, counts, declared sizes, HTTPS URLs, and hashes are validated before installation. The release-bound schema-v2 manifest is embedded in each binary; a local or HTTPS override is explicit. The v0.7.0 primary Unlimited-OCR artifact uses the conservative exact recipe and installs as unlimited-ocr/unlimited-ocr.v0.7.0.int8.focrq. The embedded manifest pins its three release parts, byte count, and final SHA256; the historical full-int8 artifact remains only in the schema-v1 manifest used by already-released v0.6 binaries. Every model installs as one package under ~/.cache/franken_ocr/models/<model-id>/. Tokenizer sidecars cannot collide, and a pull replaces the whole directory at once, so a crash never leaves a new artifact beside an old tokenizer. The resolver searches those packages, then the cache root, so --model onechart.int8.focrq, --model tromr.int8.focrq, and --model tromr.focrq work after their pulls. TrOMR publishes int8 and f32; the default focr pull tromr fetches the int8 artifact, while focr pull tromr --quant f32 fetches the bit-exact f32 reference artifact.

focr models

List the model zoo with each id, runtime status, task set, model families, default artifact name, and compatible or blocked pull recipes.

focr models                                 # human table
focr models --json                          # machine-readable list

Which model do I use?

unlimited-ocr is the fast default for ordinary text. Reach for got-ocr2 only when you need format extraction (formulas, tables, charts, etc.); it is a much larger decode and is not meant to replace the default for plain text. Install and run it with:

focr pull got-ocr2                                    # download the weights + tokenizer
focr ocr --model got-ocr2.int8.focrq page.png         # plain-text OCR
focr ocr --model got-ocr2.int8.focrq --format eq.png  # structured .mmd: LaTeX / tables / charts / music
focr ocr --model got-ocr2.int8.focrq --task tables page.png  # task shorthand (implies --format)

How far to trust the structured lanes. These are small synthetic sets, measured on the published artifacts. They can show a lane failing; they do not show one working on your documents. None of these lanes warns on a wrong reading except OneChart.

Tables, the molecule, music and formulas read the same on the upstream f32 checkpoint. Charts do not, in both directions: at --task chart, int8 misses two charts that f32 reads right and reads three that f32 misses, so f32 would not fix this lane. Evidence: artifacts/accuracy/bd-kd75/ and tests/fixtures/got/format_corpus/.

Run SmolVLM2 (photo description / VQA):

focr pull smolvlm2
focr ocr --model smolvlm2.int8.focrq --task describe photo.jpg
focr ocr --model smolvlm2.int8.focrq --task describe --question "How many dogs are there?" photo.jpg

Run OneChart (chart-to-data extraction):

focr pull onechart
focr ocr --model onechart.int8.focrq --task chart-data chart.png

Run TrOMR sheet-music OMR:

focr pull tromr
focr ocr --model tromr.int8.focrq --task music score-page.png -o score.musicxml
focr pull tromr --quant f32
focr ocr --model tromr.focrq --task music score-page.png -o score.musicxml
focr convert /path/to/tromr/model.safetensors -o tromr.int8.focrq --quant int8 --model-id tromr
scripts/tromr_convert_e2e.sh
scripts/tromr_music_e2e.sh
scripts/realscan_music_gate.sh

The TrOMR runtime accepts a single staff crop or a full printed/scanned page. If the detector finds multiple staves, it deskews the page globally, crops staves top-to-bottom, recognizes each staff through the same certified single-staff path, and emits one MusicXML part per staff; if it finds fewer than two staves, it treats the whole image as the staff input. For genuinely over-wide systems, the page path uses the five detected staff-line anchors to find thin barline columns, splits at the farthest usable barline within the positional budget, recognizes each segment sequentially, and concatenates the semantic stream while suppressing continuation clef/key/time artifacts. A multi-staff page succeeds when at least one staff recognizes, logging skipped staves with bbox and reason; an all-fail page errors with every staff reason named. The published int8 artifact is 61 MB and quantizes the 40 decoder-GEMM candidate tensors; the 86 MB f32 artifact stays published for bit-exact reference work. The int8 default is accepted with a ledgered discrepancy on one degraded Spohr page where both int8 and f32 garble differently while the corpus gate verdict stays unchanged. Local conversion is still available when you have your own TrOMR checkpoint.

The real-scan music corpus lives in tests/fixtures/realscan_music/. It starts with public-domain Spohr page and staff fixtures, tier-1 attributes that can be verified by eye, and one frozen MusicXML regression anchor. scripts/realscan_music_gate.sh is model-gated and exits successfully when local TrOMR weights are absent; when weights are present it checks attributes, frozen anchors, and page-level staff event floors. This is the real-scan regression base for the TrOMR lane, not a claim that broad note-level SER coverage is complete.

focr convert <input>

Offline weight transformation: a bf16 safetensors checkpoint into a custom .focrq artifact. Decoder tensors are int8 where that policy is validated for the model; tiny models such as TrOMR can stay f32 by default while still using the same one-binary runtime.

focr convert model.safetensors -o unlimited-ocr.focrq --quant int8
focr convert unlimited-ocr-2/ -o unlimited-ocr-2.v0.1.0.int8.focrq --quant int8
focr convert got.safetensors -o got-ocr2.int8.focrq --quant int8 --model-id got-ocr2
focr convert smolvlm2.safetensors -o smolvlm2.int8.focrq --quant int8 --model-id smolvlm2
focr convert onechart.safetensors -o onechart.int8.focrq --quant int8 --model-id onechart
focr convert tromr/model.safetensors -o tromr.int8.focrq --quant int8 --model-id tromr
focr convert model.safetensors -o out.focrq --quant int8 --json

For Unlimited-OCR, conversion stamps recipe unlimited-ocr-ffn-int8-attn-bf16-lmhead-bf16-v1, quantizes exactly 2,148 FFN/expert matrices, and copies all 48 attention projections plus lm_head at source precision. The source SHA256 is stamped into the header, and the loader rejects any default-model .focrq whose tensor dtypes violate that recipe.

Unlimited-OCR-2 converts from its checkpoint directory (the index plus two shards). The same 2,148 matrices are int8 under recipe unlimited-ocr-2-ffn-int8-attn-bf16-lmhead-bf16-v1. Attention, lm_head, and every SR-SWA dash_router and indexer tensor stay at source precision; the router steers a discrete block choice, so it is never quantized. The header’s source_sha256 is the SHA-256 over the two shard digests in index order, and each shard is listed in its provenance. The loader refuses a v2 .focrq with any other recipe id, any other source, or a tensor stored outside the recipe. v2 has no int4 recipe yet.

--model-id selects the architecture descriptor, tied-head policy, tensor-name prefixes, tokenizer expectation, and license notice. Without it, the converter picks the Unlimited-OCR generation whose tensor census the source matches; the zoo models need it. An id that disagrees with the source’s census exits 2 and names both, after reading only the shard headers. --arch <target> records architecture-specific prepacking intent (default: generic). Int4 remains gated and unvalidated.

focr robot <subcommand>

Agent-facing surface: versioned NDJSON, self-describing, line-oriented, easy to pipe.

focr robot run page.png                      # stream OCR events as NDJSON (same flags as ocr)
focr robot schema                            # self-describing, versioned event/contract schema
focr robot health                            # model present? arch features? thread budget?
focr robot backends                          # detected SIMD tiers + core count
focr robot selftest                          # int8 kernel vs scalar oracle on this host
focr robot triage                            # quick_ref + health + recommendations + commands

focr robot selftest runs the selected dense-int8 implementation against the bit-identical scalar oracle across a shape battery, including the worst-case K=6848 i32-accumulation overflow case, and emits one JSON verdict; it exits 1 on either numeric divergence or a route-trace mismatch. The payload separates hardware_selected from the effective selected route and lists the branch-derived executed_routes. oracle_independent=false is explicit for scalar/autovec because those paths invoke the oracle implementation itself. Set FOCR_FORCE_ARCH to verify each available intrinsic tier independently.

focr robot triage is the first command an agent should run in an unfamiliar checkout or host. It returns one JSON object with a compact command reference, the live health payload, state-aware next commands, command templates, and the exit-code dictionary.

For TrOMR music runs, robot mode adds a staff event before run_complete for each detected staff. The event carries the 1-based staff index, total detected staff count, page-space bbox, recognized or skipped status, and optional reason. Music runs can also emit music_warning events for annotate-only musical sanity observations: overfull bars, underfull non-final bars, impossible note durations, and cross-staff key mismatches. Existing consumers can ignore these additive events; strict consumers should refresh their schema with focr robot schema.

focr runs and focr sync

focr ocr records each run in a local fsqlite store on a best-effort basis. A store failure prints a note to stderr and never fails the OCR run itself. The default store is ~/.cache/franken_ocr/runs.db; set FOCR_RUN_STORE to use a different path.

focr runs --limit 10                         # recent runs, plain table
focr runs --limi</subcommand></target></dir></model-id></stem></images></key></out></out></page></page></output-stem></output-stem></fork></block></image></t></asset></hex></asset></page>

> README 内容过长，已截取前 64 KB。完整内容请前往 GitHub 仓库查看。