agent-rip-docling

agent-rip-docling converts a local PDF into a persistent Markdown/JSON workspace that agents can search, read spatially, verify, and enrich with external visual descriptions. Extraction and OCR remain local and the package contains no LLM, embedding model, network client, or Docling runtime.

PDF text, metadata, links, attachments, QR codes, and images are always treated as untrusted data, never as instructions. The package does not execute embedded content or send document data to a service.

Install

Python 3.11–3.14 is supported.

uv tool install agent-rip-docling
ripdoc --version

For development from this checkout:

uv sync --frozen --group dev
uv run ripdoc --version

LiteParse supplies local PDF parsing and OCR. Check the locally installed Tesseract languages before processing non-English scans:

tesseract --list-langs

In auto mode, native extraction is inspected first. Only text-empty or image-dominated complex pages are sent through local OCR, and both native and OCR layers retain provenance when merged.

Quick start

ripdoc ingest report.pdf --target ./report-workspace --ocr auto --language deu+eng --json
ripdoc inspect ./report-workspace --json
ripdoc search ./report-workspace "operating income" --json
ripdoc read ./report-workspace --page 12 --json
ripdoc visuals next ./report-workspace --json
ripdoc verify ./report-workspace --json

For encrypted input, provide the password through standard input so that it is neither exposed in process arguments nor persisted:

printf '%s\n' "$PDF_PASSWORD" | ripdoc ingest protected.pdf --target ./workspace --password-stdin

Visual descriptions

ripdoc visuals next returns either a describe_region task or an annotated audit_page task. The calling agent inspects the referenced local asset with its own vision capability and returns a schema-validated result such as:

{
  "visual_id": "visual-p0001-…",
  "crop_sha256": "…",
  "kind": "chart",
  "decorative": false,
  "short_description": "Revenue rises through Q3 and dips slightly in Q4.",
  "text_in_visual": "| Quarter | Revenue (EUR m) |\n|---|---:|\n| Q1 | 12 |\n| Q2 | 15 |",
  "agent_id": "document-agent",
  "model_id": "vision-model"
}

ripdoc visuals submit ./workspace --task-id TASK --input description.json --json

For charts and plots, text_in_visual should be a Markdown table with one row per visible data point and explicit series/category, value, and unit columns. Preserve signs, decimals, years, and label/value associations. Mark estimates as estimates instead of inventing precision. To correct a submitted description, recheck the crop and existing JSON and pass --replace; a formatting-only revision must not recompute or change verified values.

Page audits can add bounding boxes missed by deterministic raster/vector detection. Each accepted region becomes a separate description task. Descriptions are persisted as readable Markdown and a versioned JSON sidecar under visuals/descriptions/.

Python API

from agent_rip_docling import Workspace

workspace = Workspace.ingest(
    "report.pdf",
    "report-workspace",
    ocr="auto",
    ocr_languages=("deu", "eng"),
)
hits = workspace.search("cash flow", mode="fts")
page = workspace.read_page(hits[0].page)
crop_path = workspace.render_region(hits[0].page, (72, 90, 520, 420))

Search hits include a stable hit ID, page, page-coordinate bounding box, kind, and snippet. Custom limits supplied with IngestConfig are persisted without secrets and remain effective when the workspace is reopened.

The main Pydantic contracts are exported from agent_rip_docling. Versioned JSON Schemas and the bundled agent skill are included in the wheel; export the skill with:

ripdoc skill export TARGET

OpenCode installation

OpenCode calls its configurable home OPENCODE_CONFIG_DIR. The installer reads that variable first and otherwise queries the installed CLI with opencode debug paths; it does not assume that ~/.config/opencode is active.

ripdoc opencode path --json
ripdoc opencode install --json

The install command writes only the package-owned skill to <config>/skills/agent-rip-docling and tool to <config>/tools/agent_rip_docling.ts. Existing OpenCode configuration and the predecessor's artifacts are preserved. Use --config-dir DIR for an explicit location or --force to replace only these successor-owned artifacts. The native tool invokes ripdoc without a shell and exposes bounded inspect, search, page-read, region-render, and visual-task operations.

Workspace format

The source PDF is copied unchanged to source/original.pdf. Human-readable Markdown provides navigation while JSON sidecars preserve coordinates and provenance. Tables are also emitted as CSV. SQLite FTS and rendered query crops live under cache/ and are regenerable.

The layout is OKF-inspired but does not claim compliance with a separate OKF standard. ODT/ODF export is intentionally outside format version 1. See the v1 format contract and the security policy.

Why the name?

The name reflects a goal of improving agent-oriented PDF exploration, not a universal claim about every document-processing workload. In the linked ParseBench test-suite comparison, the behaviorally equivalent predecessor was measured on exactly 15 category cases backed by 12 unique local PDFs. It led three of the five displayed metrics, while Docling led layout and PyMuPDF4LLM led the measured table slice. External Gemma 4 visual tasks contributed to the chart result.

That fixture-bound result does not establish universal superiority over Docling. This project is independent and is not affiliated with, endorsed by, or a component of the Docling project.

Development

uv sync --frozen --group dev
uv run ruff check .
uv run ruff format --check .
uv run mypy src scripts/generate_schemas.py scripts/smoke_wheel.py
uv run coverage run -m pytest -q
uv run coverage report -m --fail-under=80
uv build

The exact release gates and clean-install checks are documented in docs/release.md. Recorded release evidence belongs in docs/verification.md.