github datalab-to/surya v0.24.0
Surya v0.24.0 — Zero-PyTorch Lightweight Architecture, Interactive Web Viewer (surya_gui) & Agent-Ready CLI

8 days ago

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/s at 96 DPI) — 1.7× faster than Surya 2 and 3.2× faster on Apple Silicon (llama.cpp Metal) 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-ocr installs in seconds) — removed torch, torchvision, transformers, opencv-python-headless, and streamlit from runtime dependencies (>10,000 lines of legacy v1/RF-DETR code removed). Surya now runs as a lightweight client/orchestrator over vllm (Docker or Podman), llama.cpp (llama-server / llama-cli), or mlx-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 Blocks tab.
  • Inspect Preview (with live KaTeX math rendering and styled HTML tables), Blocks, HTML, and JSON, with one-click Copy HTML and .json download.

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 from surya.
  • Configurable skip_labels (#544): Pass skip_labels=[] (or a custom set of labels) to RecognitionPredictor to OCR text inside Figure, Picture, or Diagram regions.
  • Automatic Table Rescue (#551): If full-page OCR labels a region as Table / TableOfContents without emitting a <table> tag, RecognitionPredictor automatically crops the region and re-runs BLOCK_PROMPT so table structure is preserved.
  • Docker & Podman Auto-Detection (#572, #549): Automatically detects docker or podman (override via SURYA_CONTAINER_RUNTIME) and uses CDI --device nvidia.com/gpu=... flags on Podman.
  • Multi-Model & Authenticated OpenAI Servers (#565): SURYA_INFERENCE_URL now matches SURYA_MODEL_CHECKPOINT against all models returned by /v1/models and supports SURYA_INFERENCE_API_KEY.
  • Security Hardening (#547, #548): Container ports bind to 127.0.0.1 by default, and clean_block_html / parse_full_page_html sanitize 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/skills

Upgrade

pip install -U surya-ocr

Don't miss a new surya release

NewReleases is sending notifications on new releases.