brewdoc

Fast, deterministic document-to-Markdown conversion for agent systems. Easy to install. No model weights, OCR or external services.

Local conversion runs offline after installation, with no runtime component downloads. Supported documents become one Markdown file and a JSON receipt describing omissions. See supported formats and limits.

Install

These examples select 0.3.2. Use a channel listed as available in that release. Choose one method:

python -m pip install "brewdoc==0.3.2"
uv tool install --python 3.12 "brewdoc==0.3.2"
pipx install --python 3.12 "brewdoc==0.3.2"

Use a virtual environment for pip. Python 3.12+ is required; HTML/URL need CPython 3.12-3.14. INSTALL.md covers prerequisites, Windows, uvx, PATH, update and removal. Latest release lists actual assets and channel availability.

Standalone downloads

Use downloads listed as available in the release. Python and dependencies are bundled. Verify SHA256SUMS and keep the entire extracted directory.

Older OSes, Linux musl/ARM64 and macOS Intel are outside this binary set. Windows is unsigned; macOS has an ad hoc signature without Developer ID/notarization. Linux archives have checksums, without a detached publisher signature. Download and launch.

npm

npm targets Linux x64/glibc and macOS ARM64. Windows uses the GitHub native download or Python package. Use npm/npx only when listed as available in the release. INSTALL.md contains exact-version installation, update and removal instructions.

Usage

brewdoc file.pdf --out file.md
brewdoc book.epub --out book.md
brewdoc file.xlsx --sheet Calc --sheet Inputs --out book.md
brewdoc file.xlsm --artifact formula/sheet/000002=formulas.json
brewdoc file.xlsm --artifact vba/project/000001=vbaProject.bin
brewdoc --self-check

--sheet and --artifact are repeatable and workbook-only. Sheet names are exact and case-sensitive; caller order retains full-workbook ordinals. Artifact keys come from the Markdown artifact table. Requests and output collisions are validated before writes. Paths resolve against the caller's directory; --out creates parents. Refusal preserves existing output. Self-check is offline and has its own output.

Markdown and receipts

Successful output uses brewdoc.markdown/2: quoted source title, Metadata, Artifacts, Known omissions, Contents, then anchored units. PDF uses page/000001, workbooks sheet/000001, PPTX slide/000001, and DOCX/EPUB/HTML chapter/000001. Empty declared units remain navigable. Metadata holds source/selection/content hashes, conversion tallies and artifact capabilities; it excludes paths, timestamps, permissions and host data. EPUB retains declared publication metadata.

Conversion prints one JSON receipt line first. With --out, Markdown goes to the file; without it, Markdown follows on stdout. Local receipts use brewdoc.receipt/1; URL receipts use brewdoc.receipt/2.

Exit 0 means conversion, 1 refusal and 2 invalid usage. Success does not prove content fidelity or complete JavaScript. PDF/DOCX/PPTX/workbooks emit ASCII; HTML/EPUB emit UTF-8 without BOM, with LF newlines. JSON keeps ASCII escaping. The same local file or frozen snapshot produces identical bytes; live pages can change.

Python API

import brewdoc

code, receipt, markdown = brewdoc.run("book.epub", out="book.md")
markdown, tally = brewdoc.render_html("page.html")
refs = brewdoc.list_book_artifacts("book.xlsm", sheets=("Calc",))
payload = brewdoc.read_book_artifact("book.xlsm", refs[0].key, sheets=("Calc",))

run accepts sheets and an artifact_outputs key-to-path mapping. Renderers include render_pdf, render_doc, render_presentation, render_epub, render_html and render_book. read_formulas provides typed formulas; self_check verifies installed routes. Local APIs never acquire URLs.

Explicit URL acquisition

--url deliberately acquires a public HTTP(S) page before local conversion.

brewdoc --url https://example.com/article --out article.md
brewdoc --url https://example.com/article --render-js --timeout 30 --out article.md

--timeout is one positive finite waiting budget, default 30 seconds; cleanup/conversion can add time. Public destinations, DNS, redirects, TLS, requests and bytes are validated. Ordinary requests use GET; JS admits only the narrow credential-free HN Algolia XHR POST exception. Local HTML never fetches or runs scripts. Optional JS needs installed/bundled prerequisites, refuses unsupported runtimes before HTTP and downloads no engine. Timing-only expiry can preserve valid partial content; hard failures refuse output. Full URL/JS limits.

Format contracts | Corpus | Measurements | Results Releasing | Agent entry point | MIT license