kaos-pdf

Part of Kelvin Agentic OS (KAOS) — open agentic infrastructure for legal work, built by 273 Ventures. See the full KAOS package map for the rest of the stack.

kaos-pdf is the PDF-extraction layer of KAOS — it turns a PDF byte stream into a typed kaos-content ContentDocument AST with provenance (page numbers, bounding boxes, extraction confidence) on every node, plus a small set of read-only MCP tools for agentic workflows. The engine is pypdfium2 (Apache-2.0) and all PDFium calls are serialised through a global lock so the library is safe to call from threaded executors. The primary parse path (parse_pdf, extract_outline, extract_metadata, render APIs) returns AST nodes, typed dataclasses, or KaosImage values with provenance. extract_page_text(path, page_number) and its MCP counterpart kaos-pdf-extract-page-text are an intentional escape hatch that returns raw page text for lightweight context-free page inspection; use the AST path when provenance, structure, or downstream redaction / verification is required.

The base install is intentionally small: three runtime dependencies (kaos-content[images,layout,markdown], kaos-core, pypdfium2) and no compiled native code beyond the PDFium wheel. Heavier capabilities are opt-in extras: [ocr] adds pytesseract for scanned pages (and requires a system tesseract binary), [tables] adds pdfplumber (MIT, pure Python — no Java, no GPU) for borderless and multi-line tables, and [nlp] adds kaos-nlp-core for BM25 sentence-level search. VLM page programs (describe / classify / OCR-via-VLM) live in kaos-llm-core[vision] — they were moved out of kaos-pdf to keep the extraction → LLM dependency direction one-directional. We do not and will not depend on AGPL or GPL libraries (this rules out Surya for OCR and camelot-lattice / Tabula for tables).

Install

uv add "kaos-pdf>=0.1.0"
# or
pip install "kaos-pdf>=0.1.0"

# OCR for scanned PDFs (requires system tesseract binary)
uv add 'kaos-pdf[ocr]>=0.1.0'

# Structured table extraction via pdfplumber
uv add 'kaos-pdf[tables]>=0.1.0'

# BM25 sentence-level search via kaos-nlp-core
uv add 'kaos-pdf[nlp]>=0.1.0'

kaos-pdf requires Python 3.13 or newer (3.14 is supported). The package is pure Python — the only native code is the PDFium wheel shipped by pypdfium2, which has prebuilt wheels for Linux, macOS, and Windows on x86_64 and arm64.

Quick start

Extract a PDF into the document AST, render a page, and search for a term:

from kaos_pdf import (
    extract_pdf,
    get_pdf_metadata,
    get_pdf_outline,
    render_page,
    search_document,
)

# Parse the whole document into a kaos-content ContentDocument
doc = extract_pdf("contract.pdf")
print(len(doc.body), "top-level blocks")

# Typed metadata (PdfMetadata dataclass; sparse to_dict() for JSON)
meta = get_pdf_metadata("contract.pdf")
print(meta.page_count, meta.title, meta.author)

# Outline / bookmarks (list[PdfOutlineEntry], also typed)
for entry in get_pdf_outline("contract.pdf"):
    print("  " * entry.level, entry.title, "p", entry.page)

# Render the first page as a 300-DPI PIL image (returned as KaosImage)
image = render_page("contract.pdf", page_number=0, dpi=300)
image.pil.save("page-1.png")

# AST-grounded search — paragraph-level by default
hits = search_document(doc, "indemnification", top_k=5)
for hit in hits.results:
    print(f"score={hit.score:.2f} :: {hit.text[:80]}")

Every node in the returned ContentDocument carries a Provenance (source path, 1-based page, bounding box, extractor name, confidence) so downstream consumers — citation verifiers, redaction tooling, labelers — can ground answers back to the original PDF.

Concepts

The package is a thin, typed surface over pypdfium2. The most important entries:

CLI

kaos-pdf ships two entry-point scripts. Every structured command on the admin CLI supports --json for machine-readable output piped to other agents:

kaos-pdf --help                                     # admin CLI
kaos-pdf-serve --help                               # MCP server

kaos-pdf info contract.pdf --json                   # metadata + page count + classification
kaos-pdf outline contract.pdf --json                # PDF bookmarks (falls back to detected headings)
kaos-pdf page contract.pdf 3 --json                 # plain text from a single page (1-based)
kaos-pdf extract contract.pdf -f markdown -p 1-5    # full AST → markdown / text / json / html
kaos-pdf render contract.pdf 1 --dpi 300 -o p1.png  # render a page as PNG
kaos-pdf classify contract.pdf --page 1 --json      # document- or page-level type
kaos-pdf search contract.pdf "indemnification" -k 5 # AST-grounded ranked search

kaos-pdf-serve                                      # stdio (Claude Code / Desktop)
kaos-pdf-serve --http --port 8000                   # streamable HTTP

The admin CLI uses 1-based page numbers (consistent with how the file opens in any PDF viewer) and translates internally to the 0-based indices the Python API uses. kaos-pdf-serve exposes the seven MCP tools listed in Concepts above.

Compatibility & status

Documentation

Per-package reference: see in-tree docstrings and CHANGELOG.md.

Cross-cutting KAOS guides (agentic patterns, persona presets, settings policy, citations, MCP data flow, migration to 0.1.0 GA) live in kaos-modules/docs/guides/.

Companion packages

kaos-pdf is one of the packages in the Kelvin Agentic OS. The broader stack:

Packages depend on kaos-core; everything else is opt-in. Mix and match the ones you need.

Development

git clone https://github.com/273v/kaos-pdf
cd kaos-pdf
uv sync --group dev

Install pre-commit hooks (recommended — they run the same checks as CI on every commit, scoped to staged files):

uvx pre-commit install
uvx pre-commit run --all-files     # one-time full sweep

Manual QA commands (the same set CI runs):

uv run ruff format --check kaos_pdf tests
uv run ruff check kaos_pdf tests
uv run ty check kaos_pdf tests
uv run pytest tests/unit -q --no-cov

Build from source

uv build
uv pip install dist/*.whl
python -c "import kaos_pdf; print(kaos_pdf.__version__)"  # smoke import

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for setup, quality gates, pull request expectations, and engineering standards. By contributing you agree to follow the project conduct expectations and certify the Developer Certificate of Origin v1.1 — sign every commit with git commit -s. Please open an issue before starting on a non-trivial change so we can align on scope.

Security

For security issues, please do not file a public issue. Report privately via GitHub Private Vulnerability Reporting or email security@273ventures.com. See SECURITY.md for the full disclosure policy.

License

Apache License 2.0 — see LICENSE and NOTICE.

Copyright 2026 273 Ventures LLC. Built for kelvin.legal.