brewdoc

Document to Markdown for agent systems: PDF, Word, PPTX presentations, spreadsheets and static HTML in, one Markdown file plus a JSON receipt out. No models, no OCR, no network, deterministic (same file, same bytes). The receipt says what was rendered, what was dropped and what the route structurally cannot carry, so an agent never mistakes a silent gap for "the document does not say so".

Install

Alternative, straight from git (no PyPI round-trip):

uvx --from git+https://github.com/kochetkov-ma/brewdoc@v0.2.0 brewdoc file.pdf

Requires Python >= 3.12. Base runtime dependencies: pdfplumber (pulls pypdfium2, Pillow, cryptography) and python-calamine. HTML requires CPython 3.12-3.14 and the native Lexbor parser from this exact conditional dependency:

selectolax==0.4.13; python_version < '3.15' and platform_python_implementation == 'CPython'

Other runtimes retain the .html route and Python API but explicitly refuse HTML. On supported CPython, a missing or broken parser is an environment failure and --self-check exits 1. On an unsupported HTML runtime, self-check verifies HTML refusal and checks all other formats.

Usage

brewdoc file.pdf --out file.md
brewdoc slides.pptx --out slides.md
brewdoc page.html --out page.md
brewdoc file.xlsx                # no --out: receipt line, then the Markdown, on stdout
brewdoc file.xlsx --sheet Calc --sheet Inputs
brewdoc file.xlsm --artifact formula/sheet/000002=formulas.json
brewdoc file.xlsm --artifact vba/project/000001=vbaProject.bin
brewdoc --self-check             # renders synthetic fixtures twice, compares sha256, exit 0 when green

--sheet is repeatable. Names are exact and case-sensitive. Output follows caller order while keeping each sheet's full-workbook ordinal. --artifact is also repeatable. Use keys listed in the Markdown artifact table. Both options are workbook-only. brewdoc validates every request and output collision before writing.

Every successful document uses brewdoc.markdown/2. A quoted source title is followed by Metadata, Artifacts, Known omissions, Contents, then anchored content units. PDF keys are page/000001, workbook keys are sheet/000001, DOCX keys are chapter/000001, PPTX keys are slide/000001, and HTML has one chapter/000001. Metadata contains deterministic source identity, selection, content hashes, conversion tallies, and artifact capabilities. It excludes paths, timestamps, permissions, host data, and unsupported author metadata.

One JSON receipt line always goes to stdout first (wrapped here, unit_keys omitted):

{"artifacts": [], "broken_ligature_words": 0, "columns_split": 1,
 "dropped": {"cid_survivors": 0, "control_chars": 0, "ligatures": 0, "nbsp": 0,
             "non_ascii_replaced": 0, "page_numbers": 3, "pua_glyphs": 0,
             "running_heads": 0, "soft_hyphens": 0},
 "file_ok": true, "markdown_schema": "brewdoc.markdown/2",
 "not_carried": ["images, figures and the text drawn inside them",
                 "a table that spans a page break",
                 "text rotated out of the horizontal reading order"],
 "out": "file.md",
 "reason": "pdf rendered: 7 pages, 1 tables, 26 text regions, 1 column splits",
 "receipt_schema": "brewdoc.receipt/1",
 "route": "pdf", "source": "nist-sp800-145.pdf", "tables": 1,
 "text_regions": 26, "unit_kind": "page", "units": 7}

Paths resolve against the current working directory; --out creates parent directories. Exit code is non-zero on refusal; the receipt line is still printed.

Formats

.xlsx and .xlsm expose original OOXML formulas as one deterministic JSON artifact per formula-bearing selected sheet. Markdown still contains cached values. .xlsm and .xlsb can expose one complete related vbaProject.bin as opaque bytes. brewdoc does not execute macros, decompile VBA, report source-module counts, evaluate formulas, or infer dependency graphs.

HTML reads local strict UTF-8, with an optional BOM. It preserves meaningful Unicode, navigation, main content, sidebars and footers in recovered DOM order. It never fetches links or resources, executes scripts, submits forms or infers interactive values. Links use a restricted scheme policy; form actions remain inert metadata. Inline code outside tables becomes a literal fenced block; surrounding emphasis and links remain balanced. Safe links in literal code and around code/images retain destination records without changing the source literals. Table-cell code uses labelled escaped text. Quotes and list items containing standalone child blocks use explicit nesting boundaries in place of visual Markdown containers. Plain list paragraphs retain their item marker and continuation indentation. See HTML scope and limits.

The public Python API exposes HTML and presentation rendering and generic workbook artifact access:

import brewdoc

markdown, tally = brewdoc.render_html("page.html")
code, receipt, markdown = brewdoc.run("page.html", out="page.md")
markdown, tally = brewdoc.render_presentation("slides.pptx")
refs = brewdoc.list_book_artifacts("book.xlsm", sheets=("Calc",))
payload = brewdoc.read_book_artifact("book.xlsm", refs[0].key, sheets=("Calc",))
code, receipt, markdown = brewdoc.run(
    "book.xlsm", out="book.md", sheets=("Calc",),
    artifact_outputs={refs[0].key: "formulas.json"},
)

artifact_outputs maps artifact keys to paths. The CLI builds it from repeated --artifact KEY=PATH.

Planned formats, deferred ones and the never-list: FORMATS.md. A planned format is refused by name today. The adapter contract and the ordered checklist for adding one are in docs/architecture.md.

PDF regions, in the order tried:

What it does not do

Determinism

No timestamps or unordered iteration. Two renders of one file have the same sha256; --self-check pins it. PDF, DOCX, PPTX and workbook output remains ASCII. HTML Markdown uses UTF-8 without BOM and LF newlines, with the same bytes in the API, file output and CLI stdout. Receipt JSON keeps ASCII escaping.

Size and speed

These measurements cover the existing PDF/workbook baseline before the HTML parser addition. They do not measure HTML conversion or the new installed footprint.

Benchmarks

Browse the corpus catalog, follow the measurement method, and inspect the full-run results. Completed runs include actual outputs and known failures; capture completion does not mean content quality passed.

Releasing

Tag-triggered, see RELEASING.md.

License

MIT, see LICENSE.