doc-extract

Per-файловые примитивы извлечения текста, вынесенные из radon-library (2026-06-18) для переиспользования между скиллами. Скилл — это библиотека функций, он не хранит корпус, не пишет отчёты и ничего не оркеструет: walk/реестры/*_report.json остаются в скилле-потребителе (например radon-library).

Слой

<rag-skill>     базовый extract_text: .docx / .txt / .md  (фундамент)
   └─ doc-extract   + PDF (текст-слой + детект скана), OCR скана,
                      legacy .doc/.ppt/.rtf (LibreOffice), .pptx, .csv, .xls/.xlsx/.xlsm

doc-extract сидит НАД приватным RAG-скиллом (<rag-skill>, не публикуется): для .docx/.txt/.md по-прежнему вызывайте <rag-skill>.extract.extract_text, doc-extract его не дублирует.

markitdown — turnkey «что угодно → markdown» (+ MCP-сервер)

С 2026-06-19 в окружении есть Microsoft markitdown 0.1.5 (установлен через uv tool): CLI C:\Users\<you>\.local\bin\markitdown.exe, пакет в ...\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\uv\tools\markitdown\. Это готовый конвертер БЕЗ кода: markitdown <in> -o <out.md> (или stdout). Покрытие конвертеров (проверено по converters\*.py): docx, pptx, xlsx, pdf, html, epub, csv, image (EXIF + опц. LLM-caption), outlook .msg, ipynb, zip, rss, wikipedia, youtube, bing-serp, audio (транскрипция). docx→md round-trip проверен на нашем отчёте — GFM-таблицы, кириллица, escape целы.

MCP-сервер markitdown-mcp зарегистрирован в <home>\.claude.json → mcpServers.markitdown (transport stdio, command = ...\.local\bin\markitdown-mcp.exe). Tool convert_to_markdown (принимает http:/https:/file:/data: URI) доступен в новых сессиях Claude Code (сессия, стартовавшая до регистрации, его не видит — тот же эффект, что был с pandoc-PATH). Опц. HTTP-режим: markitdown-mcp --http (127.0.0.1:3001).

• MCP-tool проверен вызовом (2026-06-19): mcp__markitdown__convert_to_markdown с file:///.../doc-extract/README.md вернул корректный markdown (заголовки / код-блоки / ссылки целы) — отвечает сам MCP-tool, не только CLI. В свежей сессии tool приходит deferred → грузить ToolSearch "select:mcp__markitdown__convert_to_markdown" перед первым вызовом. Схема: convert_to_markdown(uri: str) -> str. Windows-file: URI — file:///C:/... (forward-slash, тройной слэш; кириллицу в пути — percent-encode).

Граница markitdown ↔ doc-extract (проверено по исходникам, не по памяти):

Итог: markitdown — предпочтительный первый шаг для штатных форматов и PDF-с-текстом; doc-extract сохраняет уникальную ценность на скан-RU-PDF (Tesseract rus+eng), легаси-бинарном Office (LibreOffice) и детекте скана. Они дополняют друг друга, не заменяют. (Возможная будущая интеграция — markitdown как первичный конвертер в convert.py с fallback на doc-extract-OCR для сканов — пока НЕ сделана, это отдельная задача через IRON MODE.)

Зависимости

PyMuPDF (fitz), pytesseract + Tesseract-OCR (языки rus+eng), python-pptx, openpyxl, xlrd (для старого .xls), LibreOffice (headless, soffice). Пути к Tesseract/LibreOffice зашиты в модулях (Windows-окружение оператора).

API

import sys
sys.path.insert(0, r"<home>\.claude\skills\doc-extract\scripts")
from doc_extract import (
    pdf_text_and_scanflag, pptx_text, csv_text, sheet_text,   # форматы
    ocr_pdf, check_langs,                                      # OCR
    run_libreoffice, SOFFICE,                                  # legacy
)
# чистые алиасы: extract_pdf / extract_pptx / extract_csv / extract_sheet

Детект скана (pdf_text_and_scanflag): is_scan=True, если (n_pages>0 и total_chars==0) ИЛИ (осмотрено>0 и (avg_chars_per_page<50 или доля_пустых>0.7)). Текст возвращается всегда (даже для скана — частичный текст-слой, если он есть).

Тонкости (важно)

• ocr_pdf и pdf_text_and_scanflag возвращают кортеж — распаковывать (text, is_scan, n = ... / text, pages = ocr_pdf(...)), не трактовать как строку.
• run_libreoffice на каждый вызов создаёт уникальный профиль prof_{idx}/ выход out_{idx} под outdir_base и поллит файл до стабилизации размера (~180 с). Потребитель сам передаёт idx (обычно индекс элемента) и базовый staging-каталог.
• MuPDF шумит в stderr (cmsOpenProfileFromMem failed, No default Layer config) — это не фатально, извлечение текста проходит, exit 0.
• На Windows soffice.com блокирует до завершения (нужно), soffice.exe — нет; SOFFICE это уже учитывает.
• Любой Python, печатающий не-ASCII, — с PYTHONIOENCODING=utf-8.

Обратная конвертация: markdown/текст → docx/pdf/html (pandoc)

Извлечение здесь — это «документ → текст». Обратное направление («markdown → готовый документ», экспорт отчётов/сводок) делает pandoc — отдельный бинарь, не Python-зависимость скилла, но логически парный инструмент того же контура.

• Бинарь: C:\Users\<you>\AppData\Local\Pandoc\pandoc.exe, версия 3.10. Прописан в User PATH (реестр) → в новых сессиях/терминалах резолвится по имени pandoc. Сессия, стартовавшая ДО установки, видит его только по полному пути (PATH процесса не обновляется на лету) — тогда зови & "C:\Users\<you>\AppData\Local\Pandoc\pandoc.exe" ....
• Установлен один раз, общий для всех контуров (стоячая директива оператора «скачай один раз для всех», 2026-06-18). Не дублировать установку в проектах.
• Канонический вызов (GitHub-flavored markdown → Word с оглавлением):

  pandoc -f gfm -t docx --toc -o "<out.docx>" "<in.md>"

  PDF — -t pdf (нужен LaTeX-движок) либо -t docx → печать в PDF; HTML — -t html5 -s.
• Кириллица/числа проходят без правок (проверено на отчёте 25.8 КБ, 4 таблицы, заголовки/числа целы). На вход GFM-таблицы → на выходе нативные таблицы Word.

python-docx 1.2.0 тоже доступен — для программной правки уже готового .docx (стили, вставка строк), когда pandoc-конвертации из markdown недостаточно.

Провенанс / целостность

Модули formats.py/ocr.py/legacy.py сгенерированы из спек scripts/_spec_*.md через Ollama qwen3-coder:30b (workflow/scripts/gen_code.py) и доказаны побайтово-идентичными оригинальным radon-примитивам на 160 реальных файлах корпуса (scripts/_smoke_identity.py: checked=160 mismatches=0). После выноса radon-library импортирует эти функции отсюда; его оркестрация (convert_item/write_md/main) осталась без изменений (проверено AST-идентичностью), индекс 179 док/4760 чанков — CONSISTENT.

Ключевые файлы

Тест-план

$env:PYTHONIOENCODING='utf-8'
# 1. Импорт + резолв SOFFICE
python -c "import sys; sys.path.insert(0,r'<home>\.claude\skills\doc-extract\scripts'); import doc_extract as d; print('OK', d.SOFFICE.exists())"
# 2. Идентичность примитивов против radon-оригиналов (нужен radon-library корпус)
python "<home>\.claude\skills\doc-extract\scripts\_smoke_identity.py"   # ждём mismatches=0

Регенерация

Правка примитива → правишь scripts/_spec_<mod>.md → python <home>\.claude\skills\workflow\scripts\gen_code.py scripts\_spec_<mod>.md scripts\doc_extract\<mod>.py (IRON MODE: код пишет Ollama, не Claude) → прогнать _smoke_identity.py.