trimitdown v0.3.1
Python 3.10+ · Offline CLI & Library · MIT

Turn messy documents into token-tight Markdown.

trimitdown converts PDF, Word, Excel, PowerPoint, and HTML into clean Markdown for LLMs and AI agents — fully offline, with dual-decoder PDF checks so silent text corruption never leaks into your prompt.

$uv tool install trimitdown
Zero cloud uploads cl100k token accounting Tables preserved as Markdown
$ trimitdown convert report.pdf --page-anchors -o report.md
# Cross-checking pdf-inspector against pypdf...
page 1 [accept] clean text layer + 1 table
page 2 [substitute] pypdf layer restored Cyrillic glyphs
page 3 [scan] no reliable text layer → marker emitted
page 4 [blank] skipped

# Output preview (report.md)
<!-- page 1 -->
## Quarterly Summary
| Metric | Q1 | Q2 |
| --- | --- | --- |
$ trimitdown convert contract.docx -o contract.md
error: unaccepted tracked changes detected (4 insertions, 2 deletions)
hint: re-run with --accept-changes to apply revisions before conversion

$ trimitdown convert contract.docx --accept-changes -o contract.md
stderr: document contains headers and 2 comments omitted from Markdown
wrote contract.md (footnotes preserved)
$ trimitdown convert scan.pdf --review-dir out/
created out/document.md
created out/manifest.json & out/REVIEW.md
rendered out/pages/p0003.png (+ Tesseract candidate)

# After verifying or transcribing flagged pages:
$ trimitdown assemble out/ -o report.md
assembled report.md cleanly
Architecture

Explicit page routing instead of silent garbled text

Every PDF page is extracted by pdf-inspector and verified against an independent pypdf decode, comparing character integrity across scripts (Cyrillic, Latin, Greek, CJK, and others).

1. Primary Extract

pdf-inspector reads layout structure, headings, and Markdown tables from each page.

2. Independent Cross-Check

pypdf decodes the same page independently to catch broken ToUnicode maps and Cyrillic-to-Latin substitution.

3. Deterministic Route

Each page receives one of five explicit outcomes:

accept substitute scan corrupt blank
Capabilities

Built for reliable LLM ingestion

Minimum tokens, honest failure modes, and zero external dependencies at runtime.

Tracked Changes & Hidden Element Guard

Before converting .docx, .doc, or .rtf, trimitdown checks for unaccepted revisions and rejects ambiguous files by default (accept via --accept-changes for DOCX). Omitted headers, comments, or images are flagged in a top HTML comment and stderr while preserving footnotes.

Structured Scan Review Bundles

Pass --review-dir out/ to generate document.md, manifest.json, REVIEW.md, PNG renders in pages/, and optional Tesseract text candidates in candidates/. Stitch verified text back in with trimitdown assemble.

CLI & Clean Python Library

Pipe stdin/stdout in shell workflows (trimitdown convert - --type pdf), export JSON diagnostics with --report PATH, or call convert_path() directly in Python to inspect result.text, result.pages, and result.tokens_after.

100% Local & Offline

Documents stay on your machine. Core PDF, TXT, and Markdown support installs cleanly without heavy ML weights; add the [office] extra only when you need Office, EPUB, CSV, or HTML conversion.

Quick Start

Install & run in seconds

Requires Python 3.10+. Works with uv, pipx, or standard virtual environments.

# Core package (PDF, .txt, .md)
uv tool install trimitdown              # or: pipx install trimitdown

# With Office, EPUB, CSV, and HTML support (firecrawl-anydoc + markdownify)
uv tool install "trimitdown[office]"    # or: pip install "trimitdown[office]"

# One-off run without permanent installation
uvx trimitdown convert report.pdf
# Basic conversion (omit -o to write to stdout)
trimitdown convert report.pdf -o report.md

# Insert <!-- page N --> anchors and save a JSON routing report
trimitdown convert report.pdf --page-anchors --report report.json -o report.md

# Convert from stdin or accept DOCX tracked changes
trimitdown convert - --type pdf < report.pdf
trimitdown convert contract.docx --accept-changes -o contract.md

# Render specific pages or run the scan review workflow
trimitdown render report.pdf --pages 5,7 -o img/
trimitdown convert scan.pdf --review-dir out/
trimitdown assemble out/ -o report.md
from trimitdown.convert import convert_path
from trimitdown.review import prepare_review, assemble, render_pages

result = convert_path("report.pdf")
print(result.tokens_after)   # cl100k token count of resulting Markdown
print(result.pages)          # per-page routing decisions and reasons
print(result.text)           # Markdown output

# Accept tracked changes in Word documents
docx_result = convert_path("contract.docx", accept_changes=True)
Compatibility

Supported file formats

Unsupported container or binary types are rejected explicitly instead of producing silent garbage.

Package / Extra Formats Backend & Behavior
trimitdown (core) .pdf, .txt, .md pdf-inspector + pypdf dual-decoder check for PDF; UTF-8 pass-through for plain text and Markdown.
trimitdown[office] .docx, .doc, .rtf, .xlsx, .xls, .ods, .csv, .pptx, .ppt, .odp, .epub Converted via firecrawl-anydoc with tracked-changes inspection on Word/RTF (.odt currently rejected).
trimitdown[office] .html, .htm Converted via markdownify with scripts and styles stripped.
Explicitly rejected Encrypted PDF, .msg, .json, .xml, .zip, images, audio Fails fast with a clear error message rather than returning partial or binary noise.
Scope & Trade-offs

Design notes and known limitations

What trimitdown intentionally does — and does not — attempt to do.

Why is OCR not bundled directly inside trimitdown?

Keeping OCR external avoids shipping large model weights in a lightweight CLI. If tesseract is installed locally, --review-dir automatically runs it to populate candidates/pNNNN.txt alongside rendered page images for human or vision-model review.

How does the dual-decoder check affect speed and Latin-only PDFs?

Cross-checking with pypdf is slower than running pdf-inspector alone, which is an intentional trade-off for accuracy. Pure Latin character loss is not gated by default (GATE_LATIN is off), while Cyrillic-to-Latin corruption is caught automatically. Text embedded underneath an image is treated as a text layer.

Where did the Docker server and desktop apps go?

Starting in v0.2.0, the standalone Python CLI and library became the primary product. The earlier self-hosted Docker server, iOS PWA, and Windows/macOS wrappers remain preserved in repository history up to release v0.1.2.