Surya v0.24.0 — Zero-PyTorch Lightweight Architecture, Interactive Web Viewer (surya_gui) & Agent-Ready CLI
Surya 0.24.0 completes the transition to Surya 2.5 (datalab-to/surya-ocr-2.5) — our 689M-parameter vision-language model for full-page & per-block OCR, layout analysis & reading order, inline & block LaTeX math (<math>), and HTML table recognition (<table> with colspan / rowspan) across 90+ languages:
- 85.9 on OmniParseBench (highest of any open model under 1B parameters) and 83.7% on olmOCR-bench.
- 4.5 pages/s on a single H100 at 192 DPI (
6.2 pages/sat 96 DPI) — 1.7× faster than Surya 2 and 3.2× faster on Apple Silicon (llama.cppMetal) because compact block headers (<|Label|><|x0|><|y0|><|x1|><|y1|>) and compact table tokens cut output tokens per page by 62%. - Zero Heavy ML Dependencies (
pip install surya-ocrinstalls in seconds) — removedtorch,torchvision,transformers,opencv-python-headless, andstreamlitfrom runtime dependencies (>10,000lines of legacy v1/RF-DETR code removed). Surya now runs as a lightweight client/orchestrator overvllm(Docker or Podman),llama.cpp(llama-server/llama-cli), ormlx-vlm(Apple Silicon). - New Built-In Interactive Web Viewer (
surya_gui) — zero-extra-dependency browser UI to inspect layout boxes, reading order, KaTeX-typeset math, HTML tables, and JSON page by page across all Surya modes.
Need handwriting, complex forms, or managed VLM parsing at scale with zero infrastructure? Try Chandra on the Datalab API — get 5,000 free pages every month when you sign up with a work email.
1. Built-In Interactive Web Viewer (surya_gui)
surya_gui now launches a fast, self-contained web viewer directly from the standard library (no streamlit installation required):
surya_gui --port 8000- Drag & drop any PDF or image (
PNG,JPG,WEBP,GIF,TIFF,BMP). - Switch live between Full-Page OCR, Block OCR (96 DPI layout + 192 DPI block crops), Layout, and Table Recognition.
- Interactive SVG overlays for layout bounding boxes, canonical block labels, and reading order with bidirectional hover highlighting between the page canvas and the
Blockstab. - Inspect Preview (with live KaTeX math rendering and styled HTML tables), Blocks, HTML, and JSON, with one-click
Copy HTMLand.jsondownload.
2. Clean Top-Level Python API & New Predictor Capabilities
from PIL import Image
from surya import (
LayoutPredictor,
RecognitionPredictor,
SuryaInferenceManager,
TableRecPredictor,
)
manager = SuryaInferenceManager() # auto-spawns vllm (GPU) or llama-server (CPU / Apple Silicon)
image = Image.open("page.png").convert("RGB")
# 1. Full-page OCR (default: one VLM call per page -> blocks, bboxes, reading order, HTML + <math>)
rec = RecognitionPredictor(manager)
pages = rec([image])
# Optional: pass skip_labels=[] to also OCR text inside Figure / Picture / Diagram regions
pages_with_figures = rec([image], skip_labels=[])
# 2. Two-stage Layout + Block-mode OCR (auto-runs LayoutPredictor if layouts not passed)
block_pages = rec([image], full_page=False)
# 3. HTML Table Recognition (<table> with colspan / rowspan)
tables = TableRecPredictor(manager)([image])
print(tables[0].html)What's New in the Predictors & Backends
- Top-level package exports: Import
SuryaInferenceManager,get_default_manager,LayoutPredictor,RecognitionPredictor,TableRecPredictor, and__version__directly fromsurya. - Configurable
skip_labels(#544): Passskip_labels=[](or a custom set of labels) toRecognitionPredictorto OCR text insideFigure,Picture, orDiagramregions. - Automatic Table Rescue (
#551): If full-page OCR labels a region asTable/TableOfContentswithout emitting a<table>tag,RecognitionPredictorautomatically crops the region and re-runsBLOCK_PROMPTso table structure is preserved. - Docker & Podman Auto-Detection (
#572,#549): Automatically detectsdockerorpodman(override viaSURYA_CONTAINER_RUNTIME) and uses CDI--device nvidia.com/gpu=...flags on Podman. - Multi-Model & Authenticated OpenAI Servers (
#565):SURYA_INFERENCE_URLnow matchesSURYA_MODEL_CHECKPOINTagainst all models returned by/v1/modelsand supportsSURYA_INFERENCE_API_KEY. - Security Hardening (
#547,#548): Container ports bind to127.0.0.1by default, andclean_block_html/parse_full_page_htmlsanitize unsafe tags (<script>,<iframe>,on*=attributes,javascript:URLs).
3. Agent-First CLI Upgrades (surya_ocr, surya_layout, surya_table)
# Stream OCR, layout, or table JSON directly to stdout (ideal for AI agents & shell pipelines)
surya_ocr document.pdf --stdout
surya_layout document.pdf --stdout
surya_table table.png --skip_table_detection --stdout
# Run two-stage layout + per-block crop OCR from the CLI
surya_ocr document.pdf --block_mode --images --output_dir ./results
# Recursively process a directory of PDFs/images and keep the VLM server alive across runs
surya_ocr ./documents --recursive --keep_server --output_dir ./results
# Print or install the bundled AI agent skill (SKILL.md) for Claude Code / Cursor / Antigravity
surya_ocr --skill
surya_ocr --install_skill .agents/skillsUpgrade
pip install -U surya-ocr