bloat2md

Превращает документ в markdown, который не стыдно положить в промпт. PDF, docx, xlsx, pptx, OpenDocument, rtf, html, epub, csv, json, yaml, xml, ipynb, картинки и zip — на выходе один markdown, а страницы, на которых текста нет, приезжают пережатыми jpeg.

Пакет — это две половины. bloat2md без экстры ставит только SDK: класс, который умеет сходить в сервис по HTTP. bloat2md[server] добавляет парсеры и сам сервис.

Установка

pip install bloat2md
pip install 'bloat2md[server]'

SDK

from bloat2md import Client

client = Client("http://bloat2md:8084", timeout=45.0)

rendered = await client.convert("report.pdf", raw)
if rendered is not None:
    print(rendered.markdown)

convert не бросает: сервис лежит, документ не распознан, ответ невнятный — везде None и запись в лог. Вызывающему остаётся решить, что делать с документом, который прочитать не вышло, и это обычно «пропустить».

Rendered — это kind, markdown, images (список пар mime/bytes), pages, truncated и dropped. Последнее — счётчики того, что выкинули по дороге: hidden_nodes, hidden_spans, hidden_sheets, unsafe_names, bidi, zero_width и прочее.

Сервис

bloat2md

POST /convert принимает файл как есть, application/octet-stream, имя — в заголовке X-File-Name. Имя нужно только там, где по содержимому не отличить csv от txt, а yaml от чего угодно.

GET /healthz отвечает {"status": "ok"} и не попадает в трейсы.

Песочница

Документ — чужой ввод, и парсеры у него на пути написаны не нами. Поэтому конвертация уходит в дочерний процесс: своя сессия, свой TMPDIR, урезанное окружение и RLIMIT_AS, RLIMIT_CPU, RLIMIT_FSIZE, RLIMIT_CORE. Воркер общается с сервисом одним JSON через stdout, а по таймауту его группа процессов получает SIGKILL.

Из этого следует, что MemoryError в парсере стоит одного запроса, а не пода.

Инъекции

Текст, которого человек в документе не увидит, до промпта не доходит: скрытые css-ом узлы html, невидимый и микроскопический текст в pdf, спрятанные листы xlsx. Bidi-управляющие символы, теги Unicode, нулевой ширины и длинные цепочки joiner'ов вырезаются, а сколько чего вырезали — видно в dropped.

Zip не распаковывается, а описывается: имена и размеры. Архив с ratio выше BLOAT2MD_MAX_ARCHIVE_RATIO отвергается целиком.

Настройки

Переменные окружения с префиксом BLOAT2MD_, читается и .env.

LibreOffice

Doc, xls, ppt и всё, на чём споткнулись питонячьи парсеры, уходят в soffice --convert-to pdf, а дальше идут как pdf. Если бинаря нет, формат просто становится неподдерживаемым — падать по этому поводу незачем.

Образ ghcr.io/wprhvso/bloat2md собирается с libreoffice-*-nogui внутри.

CI

Раннеры здесь ubuntu-latest, а не pool, как в остальных репозиториях. Флот self-hosted раннеров разворачивается по списку реп в runners.toml, а тот лежит зашифрованным в кластере — новый репозиторий в него сам собой не попадёт, и job'ы висели бы в очереди вечно. Репозиторий публичный, GitHub считает его минуты бесплатными, так что цена нулевая. Появится строка в runners.toml — можно вернуть pool и убрать шаги установки uv и earthly.

cd собирает и публикует только тогда, когда версии в pyproject.toml ещё нет тега: PyPI по trusted publishing, образ в ghcr, следом тег vX.Y.Z.

Пин образа по digest в deploy/bloat2md/deployment.yaml CD ставит сам: сразу после пуша в ghcr он спрашивает у реестра digest тега и коммитит его в main. Руками digest не резолвится и в манифесте не выдумывается никогда.

Лицензия

MIT