markitdown is a pip-installable Python library that drops straight into bud's existing FastAPI attachment handling and field-notes' Python-based enrichment pipeline with no new infrastructure, containers, or services required. Both target projects already run Python on the homelab, so this is a dependency add, not an architecture change.
This is exactly the kind of boring, practical utility the operator prefers: free, self-hostable, no new moving parts, and it upgrades a pipeline that already runs unattended rather than introducing a new experimental system. The AGPL-3.0 license is not a practical concern for an internal, non-distributed tool.
Implementation Options
01bud attachment preprocessing
bud4-8 hourslow risk
Add markitdown as a conversion step in bud's email ingestion path: when a message has a PDF or Office attachment (receipt, invoice, contract), run it through MarkItDown().convert() before handing text to the Claude classifier, replacing whatever ad-hoc extraction exists today.
+Directly improves extraction quality for the attachment types bud already processes regularly (receipts, invoices, contracts)
+Single-call API keeps the integration small and easy to test against real sample emails
-OCR and audio extras pull in system-level dependencies (tesseract, ffmpeg) that bloat the CT image if enabled broadly
-Unclear how much of bud's current attachment handling is actually broken vs. just unpolished, so the improvement is somewhat speculative until measured against real inbox samples
02field-notes PDF/Office scan resolution
field-notes3-5 hourslow risk
Add a markitdown preprocessing branch in the field-notes enrichment pipeline: when a scan item's external_url resolves to a PDF or Office document instead of an HTML page, convert it to Markdown so the CCR gets readable content instead of falling back to URL metadata.
+Closes a real gap - non-HTML scan sources currently degrade to metadata-only enrichment
+Reuses the same library and integration pattern as the bud option, so marginal cost is low if bud ships first
-Frequency of scan items actually resolving to PDF/Office URLs (vs. web pages) is unknown and may be rare enough to not justify the effort on its own
-Requires content-type sniffing logic in the enrichment pipeline that doesn't exist yet
bud stops relying on ad-hoc or missing extraction for PDF/Office email attachments, so receipts, invoices, and contract summaries actually reach the Claude classifier as readable text instead of being skipped or mis-parsed.
Both bud and field-notes are unattended pipelines that quietly degrade when they hit content they can't parse - attachments in bud, non-HTML links in field-notes. A shared, well-maintained conversion library closes that gap once instead of requiring bespoke parsing logic per format in each project.
03 · What Implementation Looks Like In bud: add markitdown to pyproject/requirements, insert a conversion call in the attachment-handling module before the Claude classification step, and add a couple of test fixtures (a sample PDF receipt, a sample DOCX contract) to confirm output quality. A minimal v1 covers PDF and DOCX only, skipping OCR/audio extras to avoid the extra system dependencies until there's a concrete need.