"""Handwritten form reader: paste or upload a form screenshot, get copyable fields.
Runs on a Hugging Face ZeroGPU Space (Gradio SDK).
Model: datalab-to/chandra-ocr-2 (override with the MODEL_ID variable).
Access: one shared password, stored in the Space secret APP_PASSWORD.
Privacy: the app writes no images or extracted values to disk or logs.
"""
import os
# Keep usage analytics off. This must be set before gradio is imported.
os.environ.setdefault("GRADIO_ANALYTICS_ENABLED", "False")
import hmac
import html
import re
import time
try:
import spaces # import before torch, as ZeroGPU expects
except ImportError: # local runs without the spaces package
class spaces: # noqa: N801
@staticmethod
def GPU(*args, **kwargs):
if len(args) == 1 and callable(args[0]) and not kwargs:
return args[0]
return lambda fn: fn
import gradio as gr
import torch
from PIL import Image
from transformers import AutoModelForImageTextToText, AutoProcessor
from chandra.model.hf import generate_hf
from chandra.model.schema import BatchInputItem
from chandra.output import parse_markdown
# ---------------------------------------------------------------- settings
MODEL_ID = os.environ.get("MODEL_ID", "datalab-to/chandra-ocr-2")
APP_PASSWORD = os.environ.get("APP_PASSWORD", "")
MAX_FIELDS = 30 # field boxes shown; extra fields appear in "All fields"
MAX_IMAGE_SIDE = 2048 # larger screenshots are shrunk to save GPU time
GPU_SECONDS = 60 # GPU time requested per form (ZeroGPU default)
# "ocr" writes plain text/tables and is faster. "ocr_layout" also writes a
# position box and label for every block, which costs extra generation time.
PROMPT_TYPE = os.environ.get("PROMPT_TYPE", "ocr")
if PROMPT_TYPE not in ("ocr", "ocr_layout"):
PROMPT_TYPE = "ocr"
# Cap on generated tokens. Stops a runaway read from burning the whole GPU
# slot. Raise it (Space variable MAX_OUTPUT_TOKENS) for very long forms.
MAX_OUTPUT_TOKENS = int(
os.environ.get("MAX_OUTPUT_TOKENS", 2048 if PROMPT_TYPE == "ocr" else 6000)
)
if not APP_PASSWORD:
# Fail closed: never start an open app by accident.
raise RuntimeError(
"APP_PASSWORD is not set. Add it in Space Settings > "
"Variables and secrets, then restart the Space."
)
# ------------------------------------------------------------------- model
# ZeroGPU wants the model moved to "cuda" at module level; a real GPU is
# attached only while a @spaces.GPU function runs.
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
model = AutoModelForImageTextToText.from_pretrained(
MODEL_ID, dtype=torch.bfloat16
).to(DEVICE)
model.eval()
model.processor = AutoProcessor.from_pretrained(MODEL_ID)
model.processor.tokenizer.padding_side = "left"
def to_markdown(raw: str) -> str:
"""Convert the model's HTML output to markdown text.
chandra's parse_markdown only reads top-level
blocks, so plain
"ocr" output (no divs) is wrapped in one first. It also backslash-escapes
characters such as _ and *, which would corrupt emails, so undo that.
"""
if not re.search(r"
{raw}
"
markdown = parse_markdown(raw)
return re.sub(r"\\([\\`*_{}\[\]()#+\-.!$|<>~])", r"\1", markdown)
@spaces.GPU(duration=GPU_SECONDS)
def run_ocr(image: Image.Image) -> tuple[str, bool]:
"""Read the form image. Returns (markdown text, hit_token_limit)."""
batch = [BatchInputItem(image=image, prompt_type=PROMPT_TYPE)]
result = generate_hf(batch, model, max_output_tokens=MAX_OUTPUT_TOKENS)[0]
return to_markdown(result.raw), result.token_count >= MAX_OUTPUT_TOKENS
# --- PARSING START ---------------------------------------------------------
MAX_LABEL_CHARS = 160 # some form labels list all their options
_HEADER_PAIRS = {("field", "value"), ("label", "value"), ("item", "value")}
def _clean(text: str) -> str:
"""Strip markdown/HTML decoration from one piece of text."""
text = re.sub(r"
", " ", text, flags=re.I)
text = re.sub(r"<[^>]+>", "", text)
text = re.sub(r"!\[[^\]]*\]\([^)]*\)", "", text)
text = text.replace("**", "").replace("__", "").replace("`", "")
text = html.unescape(text)
text = text.strip(" *")
return re.sub(r"\s+", " ", text).strip()
def parse_fields(markdown: str) -> list[tuple[str, str]]:
"""Pull (label, value) pairs out of OCR markdown.
Handles 'Label: value' lines, markdown tables, and HTML tables.
Anything it cannot pair stays available in the full-text box.
"""
fields: list[tuple[str, str]] = []
seen: set[tuple[str, str]] = set()
def add(label: str, value: str) -> None:
label = _clean(label).rstrip("::").strip()
value = _clean(value)
if not label or len(label) > MAX_LABEL_CHARS:
return
if not re.search(r"[^\W\d_]", label): # label needs at least one letter
return
if value.startswith("//"): # skip URLs such as https://...
return
if (label.lower(), value.lower()) in _HEADER_PAIRS:
return
key = (label.lower(), value.lower())
if key in seen:
return
seen.add(key)
fields.append((label, value))
def add_cells(cells: list[str]) -> None:
cells = [c for c in cells]
if len(cells) < 2:
return
for i in range(0, len(cells) - 1, 2):
add(cells[i], cells[i + 1])
# HTML tables
for row in re.findall(r"
]*>(.*?)
", markdown, flags=re.I | re.S):
cells = re.findall(r"
]*>(.*?)", row, flags=re.I | re.S)
add_cells([_clean(c) for c in cells])
remaining = re.sub(r"
", "", markdown, flags=re.I | re.S)
# Markdown tables and 'Label: value' lines
for line in remaining.splitlines():
s = line.strip()
if not s:
continue
if s.startswith("|"):
cells = [c.strip() for c in s.strip("|").split("|")]
if all(re.fullmatch(r":?-{2,}:?", c) or not c for c in cells):
continue # separator row
add_cells([_clean(c) for c in cells])
continue
m = re.match(r"^[#>\-\*\s]*([^::|]{1,160}?)\s*[::]\s*(.*)$", s)
if m:
add(m.group(1), m.group(2))
return fields
# --- PARSING END -----------------------------------------------------------
def prepare_image(image: Image.Image) -> Image.Image:
image = image.convert("RGB")
image.thumbnail((MAX_IMAGE_SIDE, MAX_IMAGE_SIDE))
return image
# --------------------------------------------------------------------- UI
def copy_box(**kwargs):
"""Textbox with a copy button on Gradio 5 and Gradio 6."""
try:
return gr.Textbox(buttons=["copy"], **kwargs) # Gradio 6
except TypeError:
return gr.Textbox(show_copy_button=True, **kwargs) # Gradio 5
def extract(image):
if image is None:
raise gr.Error("Upload or paste a form screenshot first.")
started = time.perf_counter()
try:
markdown, truncated = run_ocr(prepare_image(image))
except gr.Error:
raise # GPU quota messages already explain themselves
except Exception as exc: # never echo form content into errors or logs
raise gr.Error(
f"Reading the form failed ({type(exc).__name__}). Try again in a minute."
)
seconds = time.perf_counter() - started # includes any GPU queue wait
fields = parse_fields(markdown)
all_fields = "\n".join(f"{label}: {value}" for label, value in fields)
if fields:
status = (
f"Found {len(fields)} fields. Check the values against the "
"screenshot before copying."
)
else:
status = "No label and value pairs found. Copy from the full text below."
if len(fields) > MAX_FIELDS:
status += f" The first {MAX_FIELDS} have their own boxes; all are in All fields."
if truncated:
status += (
" The form was long and the text may be cut off. Set the Space "
"variable MAX_OUTPUT_TOKENS higher to read all of it."
)
status += f" Read in {seconds:.1f} s."
slot_updates = []
for i in range(MAX_FIELDS):
if i < len(fields):
label, value = fields[i]
slot_updates.append(gr.Textbox(label=label, value=value, visible=True))
else:
slot_updates.append(gr.Textbox(value="", visible=False))
return [status, all_fields, markdown, *slot_updates]
def clear():
hidden = [gr.Textbox(value="", visible=False) for _ in range(MAX_FIELDS)]
return [None, "", "", "", *hidden]
with gr.Blocks(
title="Form reader",
analytics_enabled=False,
delete_cache=(600, 600), # remove cached uploads after 10 minutes
) as demo:
gr.Markdown(
"## Form reader\n"
"Paste or upload a screenshot of a filled form, then select **Read form**. "
"Nothing is saved by this app."
)
image_in = gr.Image(
label="Form screenshot",
type="pil",
sources=["upload", "clipboard"],
height=380,
)
with gr.Row():
read_btn = gr.Button("Read form", variant="primary")
clear_btn = gr.Button("Clear")
status_md = gr.Markdown("")
slots = [
copy_box(label=f"Field {i + 1}", value="", interactive=True,
visible=False, lines=1, max_lines=4)
for i in range(MAX_FIELDS)
]
all_fields_box = copy_box(label="All fields", lines=6, interactive=True)
raw_box = copy_box(label="Full text", lines=10, interactive=True)
outputs = [status_md, all_fields_box, raw_box, *slots]
read_btn.click(extract, inputs=image_in, outputs=outputs)
clear_btn.click(clear, inputs=None,
outputs=[image_in, status_md, all_fields_box, raw_box, *slots])
def check_login(username: str, password: str) -> bool:
"""Shared password; the username can be anything."""
return hmac.compare_digest(password.encode(), APP_PASSWORD.encode())
demo.queue(max_size=10)
if __name__ == "__main__":
demo.launch(
auth=check_login,
auth_message="Team access. Enter any username and the shared password.",
)