Transcribe

transcribe: конвертация бинарных источников в markdown

Превращает PDF или DOCX в читаемый структурированный markdown, пригодный для synthesis через ingest. Оригинальный файл уходит в raw/formats/, восстановленный .md — в raw/.

---

Команды и флаги

Команда	Поведение
/transcribe <file>	Полный pipeline: Step 1 + Step 2 (restore)
/transcribe --no-restore <file>	Только Step 1 (для документов >100 страниц)
/transcribe --ingest <file>	Pipeline + автоматически вызвать /ingest на результате

---

Pipeline

Пользователь даёт файл (PDF/DOCX)
         ↓
[Проверка расположения]
  Не в raw/formats/ → переместить туда
         ↓
Step 1а: bin/transcribe.py raw/formats/<file>
  → манифест изображений в stdout (JSON)
  → изображения сохранены в _attachments/
         ↓
Step 1б: Read tool на исходном файле
  → агент видит весь контент нативно:
    текст, формулы LaTeX, таблицы, списки
         ↓
Step 2: агент пишет качественный markdown
  (если ≤100 страниц — полное восстановление)
  → сохраняет raw/<stem>.md
         ↓
Готово. raw/<stem>.md — обычный источник,
готов к /ingest когда понадобится.

Детали каждого шага — в references/:

• references/raw-pipeline.md — Step 1, форматы, изображения, именование, файловая структура
• references/wiki-integration.md — frontmatter восстановленного .md, интеграция с ingest

---

Важные правила для агента

Step 2 — это транскрипция, а не реферирование.

Задача агента: перевести визуальное содержимое документа в markdown дословно и полностью. Не сокращать, не суммировать, не "улучшать" — даже если текст кажется повторяющимся или избыточным.

Обязательно:

• Читать через Read tool. Нативный multimodal-агент корректно видит формулы, таблицы и структуру.
• Воспроизводить каждое предложение оригинала. Если в источнике три абзаца — в markdown три абзаца. Если один абзац занимает страницу — он занимает страницу.
• Форматирование по оригиналу:
  • Формулы → LaTeX: $...$ inline, $$...$$ block
  • Таблицы → markdown tables с теми же колонками и данными
  • Нумерованные и маркированные списки → точно по структуре
  • Жирный/курсив → **bold**, *italic*
  • Подзаголовки → соответствующий уровень ##/###
  • Ссылки, сноски, цитаты (Author, YYYY) → сохранять

Встраивание изображений:

• Из манифеста → ![[image.png]] там где стоит рисунок в оригинале, перед/после подписи
• Изображение не извлечено (вектор) → плейсхолдер:

  > **Рис. 1.10** *(изображение не извлечено — добавьте вручную)*
  > [текстовое описание того что на рисунке, основанное на контексте]
  

Категорически запрещено:

• ❌ Сокращать абзацы ("автор пишет о...")
• ❌ Пересказывать своими словами
• ❌ Объединять несколько предложений в одно
• ❌ Пропускать разделы, которые кажутся неважными
• ❌ Добавлять пояснения, комментарии, резюме от себя
• ❌ Менять структуру разделов

Если что-то не читается (OCR-артефакт, нечёткий скан) → оставлять [нечитаемо] или максимально близкую транслитерацию в скобках.

Исключение — аудио и видео: whisper-cpp возвращает «плоский» текст без пунктуации структуры (заголовков, списков). Агент вправе:

• разбить на логические разделы по смыслу (## подзаголовки)
• расставить абзацы по сменам темы
• исправить очевидные ошибки распознавания (имена, термины)
• убрать слова-паразиты («эээ», «ну вот», «как бы») если они не несут смысла
• но не сокращать содержание — каждая мысль говорящего должна остаться

Для видео — то же самое (ffmpeg извлекает аудиодорожку, дальше тот же pipeline).

---

Что делать если файл не туда положили

Пользователь может положить paper.pdf в raw/ или куда угодно. Агент всегда выполняет проверку и перемещает:

# Если файл не в raw/formats/ — переместить
mkdir -p raw/formats
mv raw/paper.pdf raw/formats/paper.pdf

После перемещения продолжать pipeline.