Deploy OCR Model Workbench

.dockerignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+.env
+*.zip
+.DS_Store

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,13 +1,34 @@
 ---
-title: Ocr Workbench Zerogpu
-emoji: 💻
+title: OCR Model Workbench
+emoji: 🔬
 colorFrom: indigo
-colorTo: green
+colorTo: blue
 sdk: gradio
-sdk_version: 6.19.0
-python_version: '3.13'
 app_file: app.py
+python_version: "3.12"
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# OCR Model Workbench — Gateway
+
+This Space provides the shared Gradio UI. It does not load OCR weights itself; it sends page images to model-specific worker Spaces.
+
+Set these Space Variables:
+
+- `PADDLEOCR_VL_WORKER_URL`
+- `QIANFAN_WORKER_URL`
+- `UNLIMITED_WORKER_URL`
+- `PPOCRV6_WORKER_URL`
+
+Optional secrets:
+
+- `HF_TOKEN`: needed when worker Spaces are private.
+- `WORKER_API_TOKEN`: shared token checked by workers through `X-OCR-Worker-Token`.
+
+Optional limits:
+
+- `MAX_INPUT_MB=80`
+- `DEFAULT_MAX_PAGES=8`
+- `ABSOLUTE_MAX_PAGES=40`
+- `STALE_RUN_HOURS=12`（一時結果の保持時間）

THIRD_PARTY.md

@@ -0,0 +1,15 @@
+# Third-party models and runtime notice
+
+このリポジトリはOCRモデルの重み、上流ソースコード、サンプル文書を再配布しません。各Workerは実行時に指定されたHugging Faceリポジトリまたはマウント済みStorage Bucketからモデルを読み込みます。
+
+利用者はモデル、依存ライブラリ、入力文書、生成結果に適用されるライセンス・利用規約・個人情報保護要件を個別に確認してください。モデルrevisionの既定値は `main` であり、上流更新によりコード・挙動・ライセンス表示が変わる可能性があります。評価や本番運用では `MODEL_REVISION` をcommit hashへ固定することを推奨します。
+
+2026-06-23時点でモデルカードに表示されていたライセンスは次のとおりです。
+
+- `baidu/Qianfan-OCR`: Apache License 2.0（上流NOTICEにMIT対象ファイルの記載あり）
+- `baidu/Unlimited-OCR`: MIT License
+- `PaddlePaddle/PaddleOCR-VL-1.6`: Apache License 2.0
+- `PaddlePaddle/PP-OCRv6_medium_det_safetensors`: Apache License 2.0
+- `PaddlePaddle/PP-OCRv6_medium_rec` および実行時に取得される補助モデル: 使用するリポジトリのモデルカードを確認
+
+本リポジトリ自身のコードはルートの `LICENSE` に従います。

app.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+
+import json
+import os
+import statistics
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+
+from ocr_workbench.client import WorkerError, check_health, normalize_endpoint, run_page
+from ocr_workbench.documents import (
+    DocumentError,
+    cleanup_stale_runs,
+    gallery_items,
+    normalize_gradio_path,
+    prepare_document,
+)
+from ocr_workbench.export import build_exports
+from ocr_workbench.registry import ModelSpec, load_registry
+
+
+REGISTRY = load_registry()
+MAX_INPUT_MB = int(os.getenv("MAX_INPUT_MB", "80"))
+DEFAULT_MAX_PAGES = int(os.getenv("DEFAULT_MAX_PAGES", "8"))
+ABSOLUTE_MAX_PAGES = int(os.getenv("ABSOLUTE_MAX_PAGES", "40"))
+STALE_RUN_HOURS = float(os.getenv("STALE_RUN_HOURS", "12"))
+
+
+def _spec(model_id: str) -> ModelSpec:
+    try:
+        return REGISTRY[model_id]
+    except KeyError as exc:
+        raise gr.Error(f"Unknown model: {model_id}") from exc
+
+
+def _model_info(spec: ModelSpec) -> str:
+    endpoint = spec.endpoint() or "未設定"
+    return (
+        f"### {spec.label}\n\n"
+        f"{spec.description}\n\n"
+        f"**Worker URL:** `{endpoint}`  \n"
+        f"**環境変数:** `{spec.endpoint_env}`  \n"
+        f"**画像出力:** {spec.result_note}"
+    )
+
+
+def on_model_change(model_id: str) -> tuple[str, str, str, int, bool, str]:
+    spec = _spec(model_id)
+    return (
+        spec.default_prompt,
+        spec.endpoint(),
+        _model_info(spec),
+        spec.default_max_tokens,
+        spec.default_layout_as_thought,
+        spec.default_image_mode,
+    )
+
+
+def health_check(model_id: str, endpoint_override: str) -> str:
+    spec = _spec(model_id)
+    endpoint = normalize_endpoint(endpoint_override) or spec.endpoint()
+    try:
+        payload = check_health(endpoint)
+    except WorkerError as exc:
+        return f"❌ **Health check failed:** {exc}"
+    return "✅ **Worker reachable**\n\n```json\n" + json.dumps(payload, ensure_ascii=False, indent=2) + "\n```"
+
+
+def run_ocr(
+    file_value: object,
+    model_id: str,
+    prompt: str,
+    endpoint_override: str,
+    page_selection: str,
+    max_pages: int,
+    dpi: int,
+    max_new_tokens: int,
+    layout_as_thought: bool,
+    unlimited_image_mode: str,
+    request_timeout: int,
+    progress: gr.Progress = gr.Progress(track_tqdm=False),
+) -> tuple[
+    list[tuple[str, str]],
+    list[tuple[str, str]],
+    str,
+    str,
+    str,
+    str,
+    str,
+]:
+    cleanup_stale_runs(STALE_RUN_HOURS)
+    source_path = normalize_gradio_path(file_value)
+    spec = _spec(model_id)
+    endpoint = normalize_endpoint(endpoint_override) or spec.endpoint()
+    if not endpoint:
+        raise gr.Error(
+            f"{spec.label} のWorker URLが未設定です。Space Variable "
+            f"`{spec.endpoint_env}` または画面のWorker URL欄を設定してください。"
+        )
+
+    max_pages = min(max(1, int(max_pages)), ABSOLUTE_MAX_PAGES)
+    progress(0.03, desc="入力を展開しています")
+    try:
+        run_dir, pages = prepare_document(
+            source_path,
+            dpi=int(dpi),
+            selection=page_selection,
+            max_pages=max_pages,
+            max_input_mb=MAX_INPUT_MB,
+        )
+    except DocumentError as exc:
+        raise gr.Error(str(exc)) from exc
+
+    source_gallery = gallery_items(pages)
+    options: dict[str, Any] = {
+        "max_new_tokens": int(max_new_tokens),
+        "layout_as_thought": bool(layout_as_thought),
+        "image_mode": unlimited_image_mode,
+    }
+
+    responses: list[dict[str, Any]] = []
+    elapsed_values: list[float] = []
+    for index, page in enumerate(pages, start=1):
+        progress(
+            0.08 + 0.82 * ((index - 1) / len(pages)),
+            desc=f"Page {page.page_number} / {pages[-1].page_number}: {spec.label}",
+        )
+        try:
+            response = run_page(
+                endpoint=endpoint,
+                model_id=model_id,
+                page_path=page.image_path,
+                prompt=prompt,
+                options=options,
+                timeout_seconds=float(request_timeout),
+            )
+        except WorkerError as exc:
+            raise gr.Error(f"Page {page.page_number} failed: {exc}") from exc
+        responses.append(response)
+        elapsed = response.get("metrics", {}).get("elapsed_seconds")
+        if isinstance(elapsed, (int, float)):
+            elapsed_values.append(float(elapsed))
+
+    progress(0.94, desc="結果をまとめています")
+    annotated, markdown, text, raw_json, archive = build_exports(
+        run_dir=run_dir,
+        model_id=model_id,
+        model_label=spec.label,
+        pages=pages,
+        responses=responses,
+    )
+    total_elapsed = sum(elapsed_values)
+    median_elapsed = statistics.median(elapsed_values) if elapsed_values else 0.0
+    warning_count = sum(len(response.get("warnings", []) or []) for response in responses)
+    status = (
+        f"完了: {spec.label} / {len(pages)} page(s). "
+        f"Worker inference total {total_elapsed:.1f}s, median {median_elapsed:.1f}s/page. "
+        f"Warnings: {warning_count}."
+    )
+    progress(1.0, desc="完了")
+    return source_gallery, annotated, markdown, text, raw_json, archive, status
+
+
+model_choices = [(spec.label, spec.id) for spec in REGISTRY.values()]
+default_model_id = next(iter(REGISTRY))
+default_spec = REGISTRY[default_model_id]
+
+CSS = """
+#status-box textarea {font-family: ui-monospace, SFMono-Regular, Menlo, monospace;}
+.result-gallery {min-height: 460px;}
+"""
+
+with gr.Blocks(title="OCR Model Workbench") as demo:
+    gr.Markdown(
+        "# OCR Model Workbench\n"
+        "PDF・画像を共通UIから最新OCRモデルへ送り、ページ画像、可視化画像、Markdown、テキスト、JSONを比較します。"
+    )
+
+    with gr.Row(equal_height=False):
+        with gr.Column(scale=5):
+            input_file = gr.File(
+                label="PDF / 画像",
+                file_count="single",
+                type="filepath",
+                file_types=["image", ".pdf"],
+            )
+            model = gr.Dropdown(
+                choices=model_choices,
+                value=default_model_id,
+                label="モデル",
+            )
+            prompt = gr.Textbox(
+                value=default_spec.default_prompt,
+                label="プロンプト（VLM系のみ）",
+                lines=4,
+            )
+            with gr.Accordion("ページ・推論設定", open=False):
+                page_selection = gr.Textbox(
+                    label="PDFページ指定",
+                    placeholder="空欄=先頭から。例: 1-3,5",
+                    value="",
+                )
+                max_pages = gr.Slider(
+                    minimum=1,
+                    maximum=ABSOLUTE_MAX_PAGES,
+                    step=1,
+                    value=min(DEFAULT_MAX_PAGES, ABSOLUTE_MAX_PAGES),
+                    label="最大ページ数",
+                )
+                dpi = gr.Slider(96, 300, value=180, step=12, label="PDF rasterize DPI")
+                max_new_tokens = gr.Slider(
+                    256,
+                    32768,
+                    value=default_spec.default_max_tokens,
+                    step=256,
+                    label="生成上限（max_new_tokens / max_length）",
+                )
+                layout_as_thought = gr.Checkbox(
+                    label="Qianfan Layout-as-Thought",
+                    value=default_spec.default_layout_as_thought,
+                )
+                unlimited_image_mode = gr.Radio(
+                    choices=["gundam", "base"],
+                    value=default_spec.default_image_mode,
+                    label="Unlimited-OCR image mode",
+                )
+                request_timeout = gr.Slider(
+                    60,
+                    1800,
+                    value=600,
+                    step=30,
+                    label="1ページのタイムアウト（秒）",
+                )
+            with gr.Accordion("Worker接続", open=False):
+                endpoint_override = gr.Textbox(
+                    value=default_spec.endpoint(),
+                    label="Worker URL（空欄ならSpace Variableを使用）",
+                    placeholder="https://username-space-name.hf.space",
+                )
+                health_button = gr.Button("Health check")
+            run_button = gr.Button("OCRを実行", variant="primary")
+            status = gr.Textbox(label="Status", interactive=False, elem_id="status-box")
+
+        with gr.Column(scale=7):
+            model_info = gr.Markdown(_model_info(default_spec))
+            health_output = gr.Markdown()
+            with gr.Tabs():
+                with gr.Tab("入力ページ"):
+                    source_gallery = gr.Gallery(
+                        label="Source pages",
+                        columns=2,
+                        height=520,
+                        elem_classes=["result-gallery"],
+                    )
+                with gr.Tab("結果画像"):
+                    result_gallery = gr.Gallery(
+                        label="Annotated / normalized result images",
+                        columns=2,
+                        height=520,
+                        elem_classes=["result-gallery"],
+                    )
+                with gr.Tab("Markdown"):
+                    markdown_output = gr.Markdown()
+                with gr.Tab("Text"):
+                    text_output = gr.Textbox(lines=28, buttons=["copy"])
+                with gr.Tab("JSON"):
+                    json_output = gr.Code(language="json", lines=28)
+                with gr.Tab("Download"):
+                    download_output = gr.File(label="全結果ZIP")
+
+    model.change(
+        fn=on_model_change,
+        inputs=model,
+        outputs=[
+            prompt,
+            endpoint_override,
+            model_info,
+            max_new_tokens,
+            layout_as_thought,
+            unlimited_image_mode,
+        ],
+    )
+    health_button.click(
+        fn=health_check,
+        inputs=[model, endpoint_override],
+        outputs=health_output,
+    )
+    run_button.click(
+        fn=run_ocr,
+        inputs=[
+            input_file,
+            model,
+            prompt,
+            endpoint_override,
+            page_selection,
+            max_pages,
+            dpi,
+            max_new_tokens,
+            layout_as_thought,
+            unlimited_image_mode,
+            request_timeout,
+        ],
+        outputs=[
+            source_gallery,
+            result_gallery,
+            markdown_output,
+            text_output,
+            json_output,
+            download_output,
+            status,
+        ],
+    )
+
+
+if __name__ == "__main__":
+    demo.queue(default_concurrency_limit=2, max_size=12).launch(
+        server_name="0.0.0.0",
+        server_port=int(os.getenv("PORT", "7860")),
+        css=CSS,
+    )

ocr_workbench/__init__.py

@@ -0,0 +1,3 @@
+"""Shared components for the OCR Workbench gateway."""
+
+__version__ = "0.1.0"

ocr_workbench/client.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import json
+import os
+import inspect
+import time
+from pathlib import Path
+from typing import Any
+
+from gradio_client import Client, handle_file
+
+
+class WorkerError(RuntimeError):
+    pass
+
+
+def normalize_endpoint(endpoint: str) -> str:
+    value = (endpoint or "").strip().rstrip("/")
+    if not value:
+        return ""
+    if not value.startswith(("http://", "https://")):
+        value = "https://" + value
+    return value
+
+
+def _client(endpoint: str) -> Client:
+    hf_token = os.getenv("HF_TOKEN", "").strip() or None
+    if not hf_token:
+        return Client(endpoint)
+
+    signature = inspect.signature(Client.__init__)
+    if "hf_token" in signature.parameters:
+        return Client(endpoint, hf_token=hf_token)
+    if "token" in signature.parameters:
+        return Client(endpoint, token=hf_token)
+    if "headers" in signature.parameters:
+        return Client(endpoint, headers={"Authorization": f"Bearer {hf_token}"})
+    return Client(endpoint)
+
+
+def check_health(endpoint: str, timeout_seconds: float = 20.0) -> dict[str, Any]:
+    endpoint = normalize_endpoint(endpoint)
+    if not endpoint:
+        raise WorkerError("Worker URL is not configured.")
+    try:
+        payload = _client(endpoint).predict(api_name="/health")
+        if not isinstance(payload, dict):
+            raise WorkerError("Worker health response is not a JSON object.")
+        return payload
+    except Exception as exc:
+        raise WorkerError(f"Worker health check failed: {exc}") from exc
+
+
+def run_page(
+    *,
+    endpoint: str,
+    model_id: str,
+    page_path: Path,
+    prompt: str,
+    options: dict[str, Any],
+    timeout_seconds: float,
+) -> dict[str, Any]:
+    endpoint = normalize_endpoint(endpoint)
+    if not endpoint:
+        raise WorkerError("Worker URL is not configured.")
+
+    retry_delays = (0.0, 2.0, 6.0)
+    last_error: Exception | None = None
+
+    for attempt, delay in enumerate(retry_delays, start=1):
+        if delay:
+            time.sleep(delay)
+        try:
+            payload = _client(endpoint).predict(
+                handle_file(str(page_path)),
+                model_id,
+                prompt or "",
+                json.dumps(options, ensure_ascii=False),
+                os.getenv("WORKER_API_TOKEN", "").strip(),
+                api_name="/ocr",
+            )
+            if not isinstance(payload, dict):
+                raise WorkerError("Worker response is not a JSON object.")
+            required = {"model", "text", "markdown", "metrics"}
+            missing = sorted(required - payload.keys())
+            if missing:
+                raise WorkerError(f"Worker response is missing fields: {missing}")
+            return payload
+        except (ValueError, OSError, WorkerError, Exception) as exc:
+            last_error = exc
+            if attempt >= len(retry_delays):
+                break
+
+    raise WorkerError(f"OCR request failed after retries: {last_error}")

ocr_workbench/documents.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import re
+import shutil
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+import fitz
+from PIL import Image, ImageOps
+
+
+Image.MAX_IMAGE_PIXELS = 80_000_000
+
+SUPPORTED_IMAGE_SUFFIXES = {
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+    ".bmp",
+    ".tif",
+    ".tiff",
+}
+
+
+@dataclass(frozen=True)
+class DocumentPage:
+    page_number: int
+    image_path: Path
+
+
+class DocumentError(ValueError):
+    pass
+
+
+def cleanup_stale_runs(max_age_hours: float = 12.0) -> None:
+    """Remove old gateway work directories and archives from the ephemeral disk."""
+    cutoff = time.time() - max(0.5, float(max_age_hours)) * 3600
+    root = Path(tempfile.gettempdir())
+    for pattern in ("ocr_workbench_*", "ocr_workbench_*_ocr_result.zip"):
+        for path in root.glob(pattern):
+            try:
+                if path.stat().st_mtime >= cutoff:
+                    continue
+                if path.is_dir():
+                    shutil.rmtree(path, ignore_errors=True)
+                else:
+                    path.unlink(missing_ok=True)
+            except OSError:
+                continue
+
+
+def normalize_gradio_path(value: object) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    path = getattr(value, "name", None)
+    return str(path or value)
+
+
+def parse_page_selection(selection: str, total_pages: int, max_pages: int) -> list[int]:
+    if total_pages < 1:
+        return []
+    max_pages = max(1, int(max_pages))
+    text = (selection or "").strip()
+    if not text:
+        return list(range(min(total_pages, max_pages)))
+
+    selected: set[int] = set()
+    for token in re.split(r"\s*,\s*", text):
+        if not token:
+            continue
+        if "-" in token:
+            match = re.fullmatch(r"(\d+)\s*-\s*(\d+)", token)
+            if not match:
+                raise DocumentError(f"Invalid page range: {token!r}")
+            start, end = map(int, match.groups())
+            if start > end:
+                start, end = end, start
+            selected.update(range(start, end + 1))
+        else:
+            if not token.isdigit():
+                raise DocumentError(f"Invalid page number: {token!r}")
+            selected.add(int(token))
+
+    invalid = sorted(page for page in selected if page < 1 or page > total_pages)
+    if invalid:
+        raise DocumentError(
+            f"Page selection contains pages outside 1-{total_pages}: {invalid}"
+        )
+
+    ordered = sorted(selected)
+    if len(ordered) > max_pages:
+        raise DocumentError(
+            f"Selected {len(ordered)} pages, but the current limit is {max_pages}."
+        )
+    return [page - 1 for page in ordered]
+
+
+def _save_normalized_image(input_path: Path, output_path: Path) -> None:
+    try:
+        with Image.open(input_path) as image:
+            normalized = ImageOps.exif_transpose(image).convert("RGB")
+            normalized.save(output_path, format="PNG", optimize=False)
+    except Exception as exc:
+        raise DocumentError(f"Unable to decode image: {exc}") from exc
+
+
+def prepare_document(
+    source_path: str,
+    *,
+    dpi: int,
+    selection: str,
+    max_pages: int,
+    max_input_mb: int,
+) -> tuple[Path, list[DocumentPage]]:
+    source = Path(source_path)
+    if not source.exists() or not source.is_file():
+        raise DocumentError("Upload an image or PDF first.")
+
+    size_mb = source.stat().st_size / (1024 * 1024)
+    if size_mb > max_input_mb:
+        raise DocumentError(
+            f"Input is {size_mb:.1f} MB; the configured limit is {max_input_mb} MB."
+        )
+
+    run_dir = Path(tempfile.mkdtemp(prefix="ocr_workbench_"))
+    input_dir = run_dir / "input"
+    pages_dir = run_dir / "source_pages"
+    input_dir.mkdir(parents=True, exist_ok=True)
+    pages_dir.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, input_dir / source.name)
+
+    suffix = source.suffix.lower()
+    pages: list[DocumentPage] = []
+    if suffix == ".pdf":
+        try:
+            document = fitz.open(source)
+        except Exception as exc:
+            raise DocumentError(f"Unable to open PDF: {exc}") from exc
+        try:
+            indices = parse_page_selection(selection, document.page_count, max_pages)
+            scale = max(72, min(360, int(dpi))) / 72.0
+            matrix = fitz.Matrix(scale, scale)
+            for index in indices:
+                output = pages_dir / f"page_{index + 1:04d}.png"
+                pixmap = document.load_page(index).get_pixmap(
+                    matrix=matrix,
+                    alpha=False,
+                    colorspace=fitz.csRGB,
+                )
+                pixmap.save(output)
+                pages.append(DocumentPage(index + 1, output))
+        finally:
+            document.close()
+    elif suffix in SUPPORTED_IMAGE_SUFFIXES:
+        output = pages_dir / "page_0001.png"
+        _save_normalized_image(source, output)
+        pages.append(DocumentPage(1, output))
+    else:
+        raise DocumentError(
+            f"Unsupported file type {suffix!r}. Use PDF, PNG, JPEG, WebP, BMP, or TIFF."
+        )
+
+    if not pages:
+        raise DocumentError("No pages were selected.")
+    return run_dir, pages
+
+
+def gallery_items(pages: Iterable[DocumentPage]) -> list[tuple[str, str]]:
+    return [(str(page.image_path), f"Page {page.page_number}") for page in pages]

ocr_workbench/export.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import mimetypes
+import re
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .documents import DocumentPage
+
+
+_IMAGE_EXTENSION = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/webp": ".webp",
+}
+
+
+def _decode_image(payload: dict[str, Any], output_stem: Path) -> Path | None:
+    encoded = payload.get("annotated_image_base64")
+    if not encoded:
+        return None
+    mime = str(payload.get("annotated_image_mime") or "image/png")
+    extension = _IMAGE_EXTENSION.get(mime) or mimetypes.guess_extension(mime) or ".png"
+    output = output_stem.with_suffix(extension)
+    try:
+        output.write_bytes(base64.b64decode(encoded, validate=True))
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError(f"Worker returned an invalid base64 image: {exc}") from exc
+    return output
+
+
+def _plain_from_markdown(markdown: str) -> str:
+    text = re.sub(r"```[^\n]*\n(.*?)```", r"\1", markdown, flags=re.DOTALL)
+    text = re.sub(r"!\[[^\]]*\]\([^)]*\)", "", text)
+    text = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", text)
+    text = re.sub(r"<[^>]+>", "", text)
+    text = re.sub(r"^[#>*+-]+\s*", "", text, flags=re.MULTILINE)
+    text = re.sub(r"[`*_~]", "", text)
+    return text.strip()
+
+
+def build_exports(
+    *,
+    run_dir: Path,
+    model_id: str,
+    model_label: str,
+    pages: list[DocumentPage],
+    responses: list[dict[str, Any]],
+) -> tuple[list[tuple[str, str]], str, str, str, str]:
+    output_dir = run_dir / "results"
+    annotated_dir = output_dir / "annotated"
+    annotated_dir.mkdir(parents=True, exist_ok=True)
+
+    annotated_gallery: list[tuple[str, str]] = []
+    markdown_parts = [f"# OCR result — {model_label}"]
+    text_parts: list[str] = []
+    raw_pages: list[dict[str, Any]] = []
+
+    for page, response in zip(pages, responses, strict=True):
+        image = _decode_image(
+            response,
+            annotated_dir / f"page_{page.page_number:04d}",
+        )
+        if image is None:
+            image = annotated_dir / f"page_{page.page_number:04d}.png"
+            shutil.copy2(page.image_path, image)
+        annotated_gallery.append((str(image), f"Page {page.page_number}"))
+
+        markdown = str(response.get("markdown") or "").strip()
+        text = str(response.get("text") or "").strip()
+        if not text and markdown:
+            text = _plain_from_markdown(markdown)
+        warnings = [str(item) for item in (response.get("warnings", []) or [])]
+        warning_markdown = ""
+        warning_text = ""
+        if warnings:
+            warning_markdown = "\n\n> ⚠ " + "\n> ⚠ ".join(warnings)
+            warning_text = "\n\n[Warnings]\n- " + "\n- ".join(warnings)
+        markdown_parts.append(
+            f"\n## Page {page.page_number}\n\n"
+            f"{markdown or text or '(empty result)'}{warning_markdown}"
+        )
+        text_parts.append(
+            f"===== Page {page.page_number} =====\n"
+            f"{text or '(empty result)'}{warning_text}"
+        )
+
+        raw_page = dict(response)
+        raw_page.pop("annotated_image_base64", None)
+        raw_page["page_number"] = page.page_number
+        raw_pages.append(raw_page)
+
+    markdown_document = "\n".join(markdown_parts).strip() + "\n"
+    text_document = "\n\n".join(text_parts).strip() + "\n"
+    raw_payload = {
+        "schema_version": "1.0",
+        "model": model_id,
+        "model_label": model_label,
+        "pages": raw_pages,
+    }
+    json_document = json.dumps(raw_payload, ensure_ascii=False, indent=2)
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    (output_dir / "result.md").write_text(markdown_document, encoding="utf-8")
+    (output_dir / "result.txt").write_text(text_document, encoding="utf-8")
+    (output_dir / "result.json").write_text(json_document, encoding="utf-8")
+
+    archive_base = run_dir.parent / f"{run_dir.name}_ocr_result"
+    archive = shutil.make_archive(str(archive_base), "zip", run_dir)
+    return annotated_gallery, markdown_document, text_document, json_document, archive

ocr_workbench/registry.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    id: str
+    label: str
+    endpoint_env: str
+    default_prompt: str
+    description: str
+    result_note: str
+    default_max_tokens: int = 4096
+    default_layout_as_thought: bool = False
+    default_image_mode: str = "gundam"
+
+    def endpoint(self) -> str:
+        return os.getenv(self.endpoint_env, "").strip().rstrip("/")
+
+    def public_dict(self) -> dict[str, Any]:
+        value = asdict(self)
+        value["endpoint"] = self.endpoint()
+        return value
+
+
+_BUILTIN_MODELS: list[ModelSpec] = [
+    ModelSpec(
+        id="paddleocr-vl-1.6",
+        label="PaddleOCR-VL 1.6",
+        endpoint_env="PADDLEOCR_VL_WORKER_URL",
+        default_prompt="Parse this document to Markdown.",
+        description=(
+            "Compact document parser for text, layout, tables, formulas, charts and seals. "
+            "The Storage Bucket can be mounted on this worker as a persistent model/cache volume."
+        ),
+        result_note="Returns PaddleOCR export images plus Markdown/JSON where available.",
+        default_max_tokens=4096,
+    ),
+    ModelSpec(
+        id="qianfan-ocr",
+        label="Qianfan-OCR",
+        endpoint_env="QIANFAN_WORKER_URL",
+        default_prompt="Parse this document to Markdown.",
+        description=(
+            "Prompt-driven end-to-end document intelligence model. Layout-as-Thought can emit "
+            "layout reasoning before the final document output."
+        ),
+        result_note=(
+            "When parseable layout boxes are emitted, they are drawn over the page. "
+            "Otherwise the result image is the normalized source page."
+        ),
+        default_max_tokens=4096,
+        default_layout_as_thought=True,
+    ),
+    ModelSpec(
+        id="unlimited-ocr",
+        label="Unlimited-OCR",
+        endpoint_env="UNLIMITED_WORKER_URL",
+        default_prompt="document parsing.",
+        description=(
+            "One-shot long-horizon document parser. The worker uses the model's native "
+            "result.md and result_with_boxes image exports."
+        ),
+        result_note="Native visualization is returned when the model generates it.",
+        default_max_tokens=32768,
+        default_image_mode="gundam",
+    ),
+    ModelSpec(
+        id="ppocrv6-medium",
+        label="PP-OCRv6 Medium (det + rec)",
+        endpoint_env="PPOCRV6_WORKER_URL",
+        default_prompt="",
+        description=(
+            "Lightweight OCR pipeline combining PP-OCRv6_medium_det with "
+            "PP-OCRv6_medium_rec. The detection checkpoint alone does not emit text."
+        ),
+        result_note="Returns recognized text and the PaddleOCR detection/recognition overlay.",
+        default_max_tokens=512,
+    ),
+]
+
+
+def _custom_models() -> list[ModelSpec]:
+    raw = os.getenv("OCR_MODEL_CONFIG_JSON", "").strip()
+    if not raw:
+        return []
+    payload = json.loads(raw)
+    if not isinstance(payload, list):
+        raise ValueError("OCR_MODEL_CONFIG_JSON must contain a JSON list.")
+
+    result: list[ModelSpec] = []
+    for index, item in enumerate(payload):
+        if not isinstance(item, dict):
+            raise ValueError(f"OCR_MODEL_CONFIG_JSON[{index}] must be an object.")
+        result.append(
+            ModelSpec(
+                id=str(item["id"]),
+                label=str(item.get("label", item["id"])),
+                endpoint_env=str(item["endpoint_env"]),
+                default_prompt=str(item.get("default_prompt", "Extract all visible text.")),
+                description=str(item.get("description", "Custom OCR worker.")),
+                result_note=str(item.get("result_note", "Uses the common OCR worker response schema.")),
+                default_max_tokens=int(item.get("default_max_tokens", 4096)),
+                default_layout_as_thought=bool(item.get("default_layout_as_thought", False)),
+                default_image_mode=str(item.get("default_image_mode", "gundam")),
+            )
+        )
+    return result
+
+
+def load_registry() -> dict[str, ModelSpec]:
+    registry: dict[str, ModelSpec] = {model.id: model for model in _BUILTIN_MODELS}
+    for model in _custom_models():
+        registry[model.id] = model
+    return registry

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=5.49.1,<7.0
+gradio_client>=2.3.0,<3.0
+httpx==0.28.1
+PyMuPDF==1.27.2.2
+Pillow==12.1.1