agent-pdf-workspace 0.1.1

Offline, agent-oriented PDF exploration workspaces

agent-pdf-workspace

agent-pdf-workspace converts one local PDF into a persistent, agent-oriented workspace. Text, layout, tables, OCR, metadata, exact/regex/full-text search, rendering, and integrity checks run locally. The package contains no LLM, vision-model, embedding, or network client.

An external agent can inspect queued image crops with its own vision capability and return short, schema-validated descriptions. PDF content is always treated as untrusted data.

Install

Python 3.11–3.14 is supported.

uv tool install .
# or, for development from this checkout
uv sync
uv run pdfws --version

LiteParse supplies local PDF parsing and OCR. Check the OCR languages available on the machine when using non-English scans:

tesseract --list-langs

In auto mode the package first inspects native extraction and sends only image-dominated or text-empty complex pages through local OCR; both layers retain their provenance when merged.

Quick start

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

For encrypted input, provide the password through standard input so it is not exposed in process arguments or persisted:

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

Visual descriptions

pdfws visuals next returns either a describe_region task or an annotated audit_page task. For a region, have the calling agent inspect asset_path and submit JSON like:

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

pdfws 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 an already 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 bboxes missed by deterministic raster/vector detection; every added region then becomes its own description task. Accepted descriptions are persisted as both readable Markdown and a versioned JSON sidecar under visuals/descriptions/.

Python API

from agent_pdf_workspace 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 ingestion limits supplied with IngestConfig are persisted without secrets and remain effective when the workspace is reopened.

The main public contracts are Pydantic models exported from agent_pdf_workspace. Versioned JSON Schemas and the bundled agent skill are included in the wheel; export the latter with pdfws skill export TARGET.

OpenCode installation

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

pdfws opencode path --json
pdfws opencode install --json

The install command writes the skill to <config>/skills/agent-pdf-workspace and native tools to <config>/tools/agent_pdf_workspace.ts. Use --config-dir DIR for an explicit directory or --force to replace only those two package-owned artifacts. The OpenCode tools invoke pdfws without a shell and expose 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 version 1.

The reproducible local comparison and its limitations are documented in benchmarks/parsebench/results/2026-07-15-test-suite.md.

See docs/format-v1.md for the format contract and SECURITY.md for the trust model.

Development

uv sync --python 3.12
uv run pytest --cov=agent_pdf_workspace --cov-fail-under=80
uv run ruff check .
uv run ruff format --check .
uv run mypy src/agent_pdf_workspace
uv run python -m build

No public PyPI release or remote repository is created automatically.