Metadata-Version: 2.4
Name: agent-rip-docling
Version: 0.1.0
Summary: Offline, agent-oriented document exploration workspaces
Author-email: Dark Light <darklight@noreply.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,document-processing,ocr,offline,pdf
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.11
Requires-Dist: liteparse<2.7,>=2.6
Requires-Dist: pdfplumber<0.12,>=0.11
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pypdf<7,>=5.7
Requires-Dist: pyyaml<7,>=6
Requires-Dist: regex<2027,>=2024.11
Requires-Dist: typer<1,>=0.16
Description-Content-Type: text/markdown

# 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.

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

For development from this checkout:

```bash
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:

```bash
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

```bash
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:

```bash
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:

```json
{
  "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"
}
```

```bash
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

```python
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:

```bash
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.

```bash
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](docs/format-v1.md)
and [the security policy](SECURITY.md).

## 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](benchmarks/parsebench/results/2026-07-15-test-suite.md), 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

```bash
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](docs/release.md). Recorded release evidence belongs in
[docs/verification.md](docs/verification.md).
