OCR script with engines SuryaOCR and PaddleOCR

.env.dist

@@ -0,0 +1,2 @@
+OPENCODE_API_KEY=your_private_opencode_api_key
+HF_TOKEN=your_private_huggingface_readonly_api_key

3.md

@@ -0,0 +1,43 @@
+
+## 2.1.Highlights of the IRB setup and evolution
+
+
+individual borrower's level.
+
+
+More than a decade later, the concept to consider a bunch of such individual borrowers was developed in Vasicek (1987). The starting point was to decompose the individual borrowers' pattern into specific (idiosyncratic) and common (systemic) components as in Eq. (1).
+
+$$
+A_{i}=Z\cdot r+u_{i}\cdot\sqrt{1-R}
+$$
+
+
+where - common factor; $u_{i}\sim N(0,1)$ -specific factor$ ,$
+
+
+$r=\mathrm{corr}(A_i,Z)$ $$ \rho \text{ (conventional mathematical correlation) as it originally appeared without a squared power in the works by Vasicek (1987); Gordy (2000)} \text{ (let us call it default correlation):} $$
+
+
+\(R=r^{2}\) - asset (value) correlation using BCBS notations (mathematically speaking, it is the square of the conventional mathematical correlation between \(A_{i}\) and \(Z\)).
+
+
+Due to the nice properties of the Gaussian distribution, Vasicek uses the Value-at-Risk (VaR) measure to slice the default rate (DR) distribution of the loan portfolio and arrives at the most feasible default rate realization given the chosen significance level of α in Eq. (2).
+
+$$
+V a R=N\left(\frac{N^{-1}(PD)+N^{-1}(1-\alpha)\cdot\sqrt{R}}{\sqrt{1-R}}\right).
+$$
+
+
+Important to note that Vasicek did not impose any restrictions on \( r \) over its feasible values. The only thing he notes is that in case \( r > 50\% \), the DR distribution becomes U-shaped (bimodal). Remembering the notations that \( R = r^2 \) or \( r = \sqrt{R} \), we should take away that Vasicek was speaking of DR distribution bimodality when the asset (value) correlation exceeds 25% (\( R > 25\% \)).
+
+
+006 BCBS amendment to the Vasicek model. The idea to internationally introduce model-based (IRB) credit risk regulation seems to have become popular after the success of such regulation introduction for the market risk in the Basel I amendment BCBS (1996). Thus, the very first draft of the future Basel II Accord incorporating IRB appeared on the edge of the new millennium, see Penikas (2020a), while it
+
+
+When designing IRB, the Basel Committee implemented five conceptual amendments, originally not previewed in the Vasicek model:
+
+
+1. BCBS chose the IRB significance level of $\alpha=0.1\%$ (inversely, confidence level of 99.9\%) which corresponds to the risk-measure breach (bank failure) once in one hundred years given the annual horizon for PD, see BCBS (2005a).
+
+
+2. BCBS added other credit risk parameters like loss given default (LGD), exposure at default (EAD), maturity (M) etc. For instance, VaR from Eq. (2) is multiplied by LGD and EAD.

3_1200_02.md

@@ -0,0 +1,72 @@
+
+38
+
+$$
+1\mathrm{C Rec}_{\mathrm{it}}=\sum_{\mathrm{T}}^{\mathrm{t}}\mathrm{M Rec}_{\mathrm{it}} .
+$$
+
+
+где:
+
+
+i – индекс договора
+
+
+t — номер месяца в дефолте, на который прогнозируются возвраты для договора, в диапазоне между текущим сроком в дефолте и горизонтом взыскания:
+
+
+Т — рассчитанный горизонт взыскания
+
+
+$MBec_{i,t}$ — маржинальные возвраты, оцененные по модели, для договора $i$ в месяц $t$.
+
+
+7.1.10. На основе текущих полученных возвратов по дефолту на дату разработки модели и оцененной суммарной оставшейся доли возвратов к получению рассчитывается общий уровень потерь по дефолту за весь период взыскания с учетом экстраполяции (формула [18] ниже). В процессе моделирования минимальное экстраполированное значение уровня потерь ограничивается нулем.
+
+$$
+\mathrm{LGD\_extr_{i}}=\max(\mathrm{LGD\_act_{it}}-\mathrm{CRec_{it}},0) \mathrm{LGD\_extr_{i}}=\max(\mathrm{LGD\_act_{it}}-\mathrm{CRec_{it}},0) ______
+$$
+
+$$
+\mathrm{LGD\_act_{it}}=1-\frac{\sum_{t}\mathrm{DCF_{i,t}}}{\mathrm{EAD_{t}}}, ____
+$$
+
+
+где:
+
+
+$LGD\_extr_i$ — экстраполированное значение LGD для $i$-го договора в месяц нахождения в дефолте $t$;
+
+
+except — оцененная суммарная оставшаяся доля возвратов для $i$-го договора в месяц нахождения в дефолте $t$;
+
+
+$\mathrm{LGD\_act_{it}}$ - фактический уровень потерь для i -го договора в месяц нахождения вдефолте t;
+
+
+$\sum_t DCF_{i,t}$ — дисконтированная сумма возвратов, получаемых на t-ом периоде от созданной в дефолте;
+
+EAR — ожидаемая доходность из сети дефолта для договора i.
+
+
+11. Полученные значения уровней потерь для незавершенных д
+
+
+использованы в процессе моделирования. При учете таких дефолтов они рассматриваются как не выздоровевшие.
+
+7.2 Модель на основе дерева решений
+
+
+## 7.2.1. Данный подраздел применяется
+
+
+решений по ключевым характеристикам портфеля.
+
+
+[17]
+
+
+[18]
+
+
+[19]

3_1200_02_surya.md

@@ -0,0 +1,49 @@
+## 38
+
+$$
+CRec_{it} = \sum_T^t MRec_{it}
+$$
+
+[17]
+
+где:
+
+i – индекс договора;
+
+t – номер месяца в дефолте, на который прогнозируются возвраты для договора, в диапазоне между текущим сроком в дефолте и горизонтом взыскания;
+
+T – рассчитанный горизонт взыскания;
+
+$MRec_{it}$ – маржинальные возвраты, оцененные по модели, для договора i в месяц t.
+
+7.1.10. На основе текущих полученных возвратов по дефолту на дату разработки модели и оцененной суммарной оставшейся доли возвратов к получению рассчитывается общий уровень потерь по дефолту за весь период взыскания с учетом экстраполяции (формула [18] ниже). В процессе моделирования минимальное экстраполированное значение уровня потерь ограничивается нулем.
+
+$$
+LGD_{extr_i} = \max(LGD_{act_{it}} - CRec_{it}, 0)
+$$
+
+[18]
+
+$$
+LGD_{act_{it}} = 1 - \frac{\sum_t DCF_{i,t}}{EAD_i},
+$$
+
+[19]
+
+где:
+
+$LGD_{extr_i}$ – экстраполированное значение LGD для i-го договора в месяц нахождения в дефолте t;
+
+$CRec_{it}$ – оцененная суммарная оставшаяся доля возвратов для i-го договора в месяц нахождения в дефолте t;
+
+$LGD_{act_{it}}$ – фактический уровень потерь для i-го договора в месяц нахождения в дефолте t;
+
+$\sum_t DCF_{i,t}$ – дисконтированная сумма возвратов, полученных на t-ый месяц нахождения в дефолте;
+
+$EAD_i$ – величина задолженности на дату дефолта для договора i.
+
+7.1.11. Полученные значения уровней потерь для незавершенных дефолтов могут быть использованы в процессе моделирования. При учете таких дефолтов они рассматриваются как не выздоровевшие.
+
+7.2. Модель на основе дерева решений
+
+7.2.1. Данный подраздел применяется при выборе структуры Моделей на основе дерева решений по ключевым характеристикам портфеля.

3_surya.md

@@ -0,0 +1,31 @@
+## 2. Literature review
+
+## 2.1. Highlights of the IRB set-up and evolution
+
+1987 Vasicek model. IRB owes to the Nobel laureate in economics Robert Merton and Oldrich von Vasicek for its birth. As early as in Merton (1974), there came an idea to model a hypothetical borrower's finance, its assets more specifically, as a Normally-distributed random walk. The default event happens when the asset pattern breaches the fixed thresholds signaling for the artificial liabilities. Hence, the probability of such a breach given the known (assumed) nature of the probabilistic distribution allows us to proceed with the probability of default ($PD$) at the individual borrower's level.
+
+More than a decade later, the concept to consider a bunch of such individual borrowers was developed in Vasicek (1987). The starting point was to decompose the individual borrowers' pattern into specific (idiosyncratic) and common (systemic) components as in Eq. (1).
+
+$$
+A_i = Z \cdot r + u_i \cdot \sqrt{1 - R} \quad (1)
+$$
+
+where $Z \sim N(0, 1)$ - common factor; $u_i \sim N(0, 1)$ - specific factor; $r = \text{corr}(A_i; Z)$ - correlation of factors (conventional mathematical correlation) as it originally appeared without a squared power in the works by Vasicek (1987); Gordy (2000) (let us call it default correlation);
+
+$R = r^2$ - asset (value) correlation using BCBS notations (mathematically speaking, it is the square of the conventional mathematical correlation between $A_i$ and $Z$).
+
+Due to the nice properties of the Gaussian distribution, Vasicek uses the Value-at-Risk (VaR) risk-measure to slice the default rate (DR) distribution of the loan portfolio and arrives at the worst feasible default rate realization given the chosen significance level of $\alpha$ in Eq. (2).
+
+$$
+VaR = N \left( \frac{N^{-1}(PD) + N^{-1}(1 - \alpha) \cdot \sqrt{R}}{\sqrt{1 - R}} \right). \quad (2)
+$$
+
+Important to note that Vasicek did not impose any restrictions over $r$, over its feasible values. The only thing he notes is that in case $r > 50\%$, the DR distribution becomes U-shaped (bimodal). Remembering the notations that $R = r^2$, or $r = \sqrt{R}$, we should take away that Vasicek was speaking of DR distribution bimodality when the asset (value) correlation exceeds 25% ($R > 25\%$).
+
+2006 BCBS amendment to the Vasicek model. The idea to internationally introduce model-based (IRB) credit risk regulation seems to have become popular after the success of such regulation introduction for the market risk in the Basel I amendment BCBS (1996). Thus, the very first draft of the future Basel II Accord incorporating IRB appeared on the edge of the new millennium, see Penikas (2020a), while it took another six years to polish it to the very final (comprehensive) version of BCBS (2006).
+
+When designing IRB, the Basel Committee implemented five conceptual amendments, originally not previewed in the Vasicek model:
+
+1. BCBS chose the IRB significance level of $\alpha = 0.1\%$ (inversely, confidence level of 99.9%) what corresponds to the risk-measure breach (bank failure) once in one hundred years given the annual horizon for $PD$, see BCBS (2005a).2. BCBS added other credit risk parameters like loss given default ($LGD$), exposure at default ($EAD$), maturity ($M$) etc. For instance, $VaR$ from Eq. (2) is multiplied by $LGD$ and $EAD$.
+
+3

README.md

@@ -0,0 +1,160 @@
+# scan2html — Offline Document OCR Pipeline
+
+Полностью офлайн-конвейер обработки отсканированных документов:
+разрезание изображений на страницы → OCR → структурированный Markdown.
+
+---
+
+## Цель проекта
+
+Преобразование больших технических документов (JPEG/TIFF/PNG), полученных после печати и сканирования, в структурированный Markdown с формулами LaTeX, пригодный для:
+- просмотра в браузере (HTML + MathJax)
+- анализа LLM
+- конвертации в LaTeX/PDF
+
+**Полностью offline.** Без облачных сервисов.
+
+---
+
+## Pipeline
+
+```
+JPEG/TIFF/PNG (многостраничный скан)
+    │
+    ▼
+src/image_split.py          ← Stage 1: разрезание
+    │ --slice / --slice-auto
+    │ --pre-rotate, --border
+    │ --post-crop
+    │
+    ▼
+JPEG страницы
+    │
+    ▼
+src/image_to_latex.py       ← Stage 2: OCR + Markdown
+    │ --ocr-engine paddle|surya
+    │ --llm, --vlm (optional)
+    │
+    ├─ PP-StructureV3 / Surya 2    (OCR)
+    ├─ fixups                      (VaR, V^2)
+    ├─ LLM corrector               (Qwen2.5-7B, local)
+    ├─ VLM corrector               (Qwen3.8 Max, API)
+    │
+    ▼
+.md + .json + .html
+```
+
+---
+
+## Параметры
+
+### Stage 1: `src/image_split.py`
+
+| Параметр | Описание | По умолчанию |
+|----------|----------|:---:|
+| `--input` / `-i` | Путь к входному изображению | required |
+| `--slice` / `-s` | Сетка `<cols>:<rows>` | — |
+| `--slice-auto` / `-a` | Автоопределение сетки | — |
+| `--output-dir` / `-o` | Каталог для страниц | `.` |
+| `--pre-rotate` / `-r` | Поворот: 90, 180, 270 | — |
+| `--border` / `-b` | Белая рамка (px) | 50 |
+| `--post-crop` / `--no-post-crop` | Обрезка по контенту | ON |
+
+Пример:
+```bash
+python -m src.image_split -i scan.jpg -s 3:3 -b 10 -o pages/
+python -m src.image_split -i scan.jpg --slice-auto
+```
+
+### Stage 2: `src/image_to_latex.py`
+
+| Параметр | Описание | По умолчанию |
+|----------|----------|:---:|
+| `--input` / `-i` | Изображение страницы | required |
+| `--output-dir` / `-o` | Каталог вывода | рядом с `--input` |
+| `--lang` / `-l` | Язык OCR | `en` |
+| `--ocr-engine` | `paddle` или `surya` | `paddle` |
+| `--llm` | Локальный LLM-корректор (Qwen2.5-7B) | OFF |
+| `--vlm` | Vision LM корректор (Qwen3.8 Max, API) | OFF |
+
+Пример:
+```bash
+# Базовый OCR
+python -m src.image_to_latex -i page.jpg
+
+# С LLM-коррекцией
+python -m src.image_to_latex -i page.jpg -l ru --llm
+
+# С VLM-коррекцией (нужен OPENCODE_API_KEY в .env)
+python -m src.image_to_latex -i page.jpg --vlm
+
+# Surya 2
+python -m src.image_to_latex -i page.jpg --ocr-engine surya
+```
+
+---
+
+## Результат
+
+Для каждого входного изображения генерируется:
+
+| Файл | Формат | Описание |
+|------|--------|----------|
+| `page_01.md` | Markdown | Текст + `$$`-формулы + `##`-заголовки |
+| `page_01.json` | JSON | Полный дамп OCR-движка (bbox, confidence, labels) |
+
+Дополнительно (при включённых опциях):
+- `.tex` — LaTeX-документ (скомпилировать в PDF)
+- `.html` — HTML с MathJax-рендерингом формул
+
+---
+
+## Качество OCR
+
+| Движок | Русский текст | Формулы | Скорость |
+|--------|:---:|:---:|:---:|
+| PaddleOCR (PP-StructV3) | ~85% | ✅ отлично | ~140s |
+| + LLM (Qwen2.5-7B) | ~95% | ✅ | +5 min |
+| + VLM (Qwen3.8 Max) | ~98% | ✅✅ | +10s/блок |
+| Surya 2 | ~95% | ✅ отлично | ~430s |
+
+---
+
+## Архитектура
+
+```
+src/
+  image_split.py         — CLI Stage 1
+  image_to_latex.py      — CLI Stage 2
+  split/slicer.py        — разрезание, post-crop
+  ocr/
+    paddle_engine.py     — PP-StructureV3
+    surya_engine.py      — Surya 2
+  postprocess/
+    fixups.py            — OCR-ошибки (VaR)
+    corrector.py         — Corrector protocol
+    llm_corrector.py     — Qwen2.5-7B (local)
+    vlm_corrector.py     — Qwen3.8 Max (API)
+  markdown/generator.py  — Markdown + валидация
+  latex/
+    surya2html.py        — Surya JSON → HTML
+    tex2html.py           — TeX → HTML
+```
+
+---
+
+## Не входит в проект
+
+- GUI
+- Docker
+- PDF (на вход)
+- LLM/RAG
+- Поиск по документам
+- Многопоточность
+- Автоматический deskew / denoise
+
+---
+
+## Лицензия
+
+MIT. Модели PaddleOCR — Apache 2.0, Surya 2 — OpenRAIL-M.

STAGE2_RESEARCH_RESULT.md

@@ -0,0 +1,265 @@
+# STAGE2_RESEARCH_RESULT.md
+
+## Результат исследования PaddleOCR 3.7.0 + Docling 2.117.0
+
+Дата: 2026-08-03
+
+---
+
+## 1. PaddleOCR — возможности
+
+Версия: **3.7.0** (июнь 2026)
+
+**PP-StructureV3** — ключевой компонент для обработки документов:
+- Преобразует PDF/изображения в структурированный **Markdown** или **JSON**
+- Определяет layout страницы, reading order, таблицы, формулы
+- Предоставляет **координаты** каждого элемента (текстовые блоки, ячейки таблиц, строки)
+- Возвращает **confidence** для результатов OCR
+- Поддерживает 100+ языков (PP-OCRv6: 50 языков в единой модели)
+
+**PP-OCRv6** — текстовое распознавание:
+- 34.5M параметров, превосходит большие VLM по точности
+- 5.2× ускорение на CPU (OpenVINO)
+- Детекция + распознавание текста
+
+**Экспорт:** Markdown, JSON, DOCX
+
+---
+
+## 2. Docling — возможности
+
+Версия: **2.117.0** (июль 2026), IBM Research, MIT License
+
+**Ключевая функциональность:**
+- Парсинг PDF, DOCX, PPTX, XLSX, HTML, EPUB, изображений (PNG/TIFF/JPEG)
+- Layout detection, reading order, table structure, code, formulas, image classification
+- Единый формат `DoclingDocument`
+- Экспорт: **Markdown, HTML, JSON, DocTags, lossless JSON**
+- Confidence scores (с v2.34.0): layout_score, ocr_score, parse_score, table_score
+
+**OCR-движки (НЕТ PaddleOCR!):**
+- EasyOCR, Tesseract, Tesseract CLI, RapidOCR, Nemotron OCR, OcrMac, OnnxTR
+
+**Форматы экспорта:**
+
+| Формат | Официально | Структура | Для LLM |
+|--------|-----------|-----------|---------|
+| HTML | ✅ | Полная (таблицы, изображения, заголовки) | Отлично |
+| Markdown | ✅ | Хорошая (таблицы, заголовки) | Отлично |
+| JSON | ✅ | Полная, lossless | Хорошо |
+| DocTags | ✅ | Полная, с координатами | Средне |
+| Plain Text | ❌ (через Markdown) | Базовая | Плохо |
+
+---
+
+## 3. Совместимость PaddleOCR + Docling
+
+**Docling НЕ поддерживает PaddleOCR как OCR-движок** (v2.117.0). 
+
+Доступные движки: EasyOCR, Tesseract, RapidOCR, Nemotron, OcrMac, OnnxTR.
+
+**Вывод:** напрямую интегрировать PaddleOCR в Docling в качестве OCR-backend невозможно без форка Docling.
+
+Альтернативы для проекта scan2html:
+- **Вариант А**: Использовать **PaddleOCR PP-StructureV3** напрямую — он сам выполняет полный pipeline (OCR + структура + Markdown/JSON) — Docling не нужен
+- **Вариант Б**: Использовать **Docling** со встроенным OCR (EasyOCR/RapidOCR) — HTML экспорт из коробки
+- **Вариант В**: Самостоятельная генерация HTML из результатов PaddleOCR
+
+---
+
+## 4. Качество HTML (Docling)
+
+Docling генерирует HTML с сохранением:
+- ✅ Таблицы (включая rowspan/colspan)
+- ✅ Заголовки (h1-h6)
+- ✅ Списки (ul/ol)
+- ✅ Изображения (встроенные base64)
+- ✅ Подписи рисунков
+- ✅ Формулы (MathML)
+- ❗ Объединённые ячейки — зависит от качества OCR
+
+**PaddleOCR PP-StructureV3** также сохраняет структуру в Markdown/JSON с координатами — но HTML-экспорта из коробки не предоставляет (только Markdown, JSON, DOCX).
+
+---
+
+## 5. Таблицы
+
+**Docling:**
+- Таблицы с поддержкой rowspan/colspan ✅
+- Качество зависит от OCR-движка
+- Экспорт в HTML с сохранением colspan/rowspan ✅
+
+**PaddleOCR PP-StructureV3:**
+- Таблицы с координатами ячеек ✅
+- Восстановление сложных таблиц ✅
+- Экспорт в Markdown (базовый) и JSON (с координатами)
+
+---
+
+## 6. Формулы
+
+**Docling:**
+- Распознавание формул ✅
+- Экспорт в MathML ✅
+- LaTeX не поддерживается в HTML (только через MathML)
+
+**PaddleOCR PP-StructureV3:**
+- Распознавание формул ✅
+- Экспорт LaTeX ✅ (в Markdown/JSON)
+
+---
+
+## 7. OCR Confidence
+
+**PaddleOCR:** предоставляет confidence для каждого распознанного слова/символа.
+
+**Docling:** с v2.34.0 предоставляет:
+- `layout_score` — качество детекции элементов
+- `ocr_score` — качество OCR
+- `parse_score` — 10-й перцентиль уверенности
+- `table_score` — качество таблиц (ещё не реализовано)
+- Page-level и document-level оценки
+
+Confidence можно использовать для подсветки сомнительных мест.
+
+---
+
+## 8. Координаты элементов
+
+**PaddleOCR PP-StructureV3:** ✅ Полные координаты
+- Страницы ✅
+- Абзацы ✅
+- Таблицы + ячейки строк ✅
+- Отдельные слова/символы ✅
+
+**Docling:** координаты доступны через DoclingDocument API (bounding boxes), но в HTML экспорт не передаются.
+
+---
+
+## 9. Производительность
+
+**PaddleOCR PP-StructureV3:**
+- ~2-5 секунд на страницу на CPU
+- RAM: ~2-4 GB для моделей
+- GPU: значительное ускорение
+- Пакетная обработка ✅
+
+**Docling:**
+- ~1-3 секунды на страницу на CPU (EasyOCR: >10 с)
+- RAM: ~2-4 GB для моделей
+- Пакетная обработка ✅
+- GPU: поддерживается через PyTorch/CUDA
+
+---
+
+## 10. Offline-режим
+
+**PaddleOCR:** ✅ полностью offline. Модели скачиваются один раз в `~/.paddlex/official_models/`.
+
+**Docling:** ✅ полностью offline. Модели кешируются локально. Нет обращений к облачным сервисам. Поддерживает air-gapped environments.
+
+---
+
+## 11. Минимальный рабочий пример
+
+```python
+# ===== PaddleOCR PP-StructureV3: полный pipeline =====
+from paddleocr import PaddleOCR
+
+ocr = PaddleOCR(lang="en", use_structure=True)
+result = ocr.predict("page.jpg")
+# result содержит:
+#   - markdown: структурированный Markdown
+#   - json: полный JSON с координатами
+#   - ocr_result: детальный OCR с confidence
+#   - table_result: таблицы с ячейками
+#   - layout_result: layout страницы
+
+# ===== Docling: преобразование в HTML =====
+from docling.document_converter import DocumentConverter
+
+converter = DocumentConverter()
+result = converter.convert("page.jpg")
+html = result.document.export_to_html()
+markdown = result.document.export_to_markdown()
+json_out = result.document.export_to_dict()
+confidence = result.confidence  # ConfidenceReport
+```
+
+---
+
+## 12. Что уже реализовано библиотеками (не требует разработки)
+
+| Функция | PaddleOCR | Docling |
+|---------|-----------|---------|
+| OCR текста | PP-OCRv6 | EasyOCR/Tesseract/RapidOCR |
+| Layout detection | PP-StructureV3 | Встроенный DocLayNet |
+| Reading order | ✅ | ✅ |
+| Таблицы + ячейки | PP-StructureV3 | TableFormer |
+| Формулы → LaTeX | PP-StructureV3 | Formula recognition |
+| HTML экспорт | ❌ (только MD/JSON/DOCX) | ✅ |
+| Markdown экспорт | ✅ | ✅ |
+| JSON экспорт | ✅ | ✅ |
+| DOCX экспорт | ✅ (v3.5+) | ❌ |
+| Confidence scores | ✅ | ✅ |
+| Координаты элементов | ✅ | ✅ |
+| Пакетная обработка | ✅ | ✅ |
+
+---
+
+## 13. Что придётся реализовать самостоятельно
+
+1. **Генерация HTML с координатами элементов из PaddleOCR** — если выбран PaddleOCR
+2. **Подсветка сомнительных мест** — на основе confidence (любой движок)
+3. **Передача confidence в HTML** — через data-атрибуты или CSS-классы
+4. **Интеграция PaddleOCR + Docling** — если нужна, требует форка Docling
+
+---
+
+## 14. Рекомендуемая архитектура Stage 2
+
+### Рекомендация: использовать **PaddleOCR PP-StructureV3** как основной движок
+
+**Обоснование:**
+1. PaddleOCR PP-StructureV3 сам выполняет полный pipeline: OCR + структура + таблицы + формулы + координаты
+2. Docling не нужен как промежуточный слой — он не добавляет ценности при уже имеющемся PaddleOCR
+3. PaddleOCR даёт более детальные координаты и confidence, чем Docling
+4. Не требуется интеграция двух библиотек — снижается сложность
+5. HTML-генерацию можно реализовать как отдельный модуль (`src/html/`), принимающий на вход JSON от PaddleOCR
+
+### Pipeline Stage 2:
+
+```
+JPEG page
+    ↓
+PaddleOCR PP-StructureV3
+    ↓
+JSON (структура + координаты + confidence)
+    ↓
+Генератор HTML (src/html/)
+    ↓
+HTML с data-атрибутами (confidence, координаты)
+```
+
+### Модули для реализации:
+
+```
+src/
+  split/       — разрезание (Stage 1, готово)
+  preprocess/  — deskew, crop, denoise (будущие этапы)
+  ocr/         — обёртка над PaddleOCR PP-StructureV3
+  html/        — генерация HTML из JSON-результата OCR
+  image_split.py — CLI (Stage 1)
+```
+
+---
+
+## 15. Итоговая рекомендация
+
+1. **Не использовать Docling** для данного проекта — он не даёт преимуществ перед PaddleOCR PP-StructureV3 и не поддерживает PaddleOCR как OCR-backend
+2. **Использовать PaddleOCR PP-StructureV3** для OCR и извлечения структуры документа
+3. **Реализовать HTML-генератор** (модуль `src/html/`) на основе JSON-вывода PaddleOCR
+4. **Добавить confidence-подсветку** в HTML через data-атрибуты
+5. **Структура проекта** уже соответствует архитектуре из `.ai/ARCHITECTURE.md`
+
+Главная цель минимизации собственного кода достигнута: PaddleOCR PP-StructureV3 покрывает OCR, layout detection, таблицы, формулы, координаты и confidence. Собственной реализации требует только HTML-генератор и CLI-интеграция.

installation.md

@@ -0,0 +1,130 @@
+# Установка окружения
+
+## Системные требования
+
+- **OS:** Linux (x86_64)
+- **CPU:** 8+ ядер (рекомендуется)
+- **RAM:** 16+ GB (32 GB для LLM-корректора)
+- **Диск:** 10+ GB свободного места
+
+---
+
+## Шаг 1: Python 3.12 + venv
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+---
+
+## Шаг 2: Stage 1 — разрезание изображений
+
+```bash
+pip install opencv-python-headless typer
+```
+
+Зависимости: `opencv-python-headless`, `numpy`, `typer`, `ruff` (dev).
+
+Проверка:
+```bash
+python -m src.image_split --help
+```
+
+---
+
+## Шаг 3: Stage 2 — OCR (PaddleOCR)
+
+```bash
+pip install paddlepaddle==3.2.2
+pip install paddleocr pyyaml
+```
+
+Модели загружаются автоматически при первом запуске в `~/.paddlex/official_models/` (~2.5 GB).
+
+Проверка:
+```bash
+python -m src.image_to_latex --help
+```
+
+---
+
+## Шаг 4 (опционально): LLM-корректор (Qwen2.5-7B)
+
+```bash
+pip install llama-cpp-python
+```
+
+Модель загружается из HuggingFace при первом запуске (~4.4 GB):
+```bash
+# Автоматически при первом --llm, или вручную:
+curl -L "https://huggingface.co/bartowski/Qwen2.5-7B-Instruct-GGUF/resolve/main/Qwen2.5-7B-Instruct-Q4_K_M.gguf" \
+  -o ~/.cache/llama_models/Qwen2.5-7B-Instruct-Q4_K_M.gguf
+```
+
+Использование:
+```bash
+python -m src.image_to_latex -i page.jpg --llm
+```
+
+---
+
+## Шаг 5 (опционально): VLM-корректор (Qwen3.8 Max)
+
+Требуется подписка OpenCode Go. Токен записать в `.env`:
+
+```bash
+echo 'OPENCODE_API_KEY=sk-...' > .env
+echo 'HF_TOKEN=hf_...' >> .env
+```
+
+`.env` уже добавлен в `.gitignore`.
+
+Использование:
+```bash
+python -m src.image_to_latex -i page.jpg --vlm
+```
+
+---
+
+## Шаг 6 (опционально): Surya 2
+
+Surya 2 требует отдельного venv из-за конфликтов зависимостей с PaddleOCR.
+
+```bash
+# Установка llama-server (CPU-версия)
+mkdir -p ~/.local/bin
+curl -L "${URL}" -o /tmp/llama.tar.gz
+tar -xzf /tmp/llama.tar.gz -C /tmp/
+cp /tmp/llama-*/llama-server /tmp/llama-*/lib*.so* ~/.local/bin/
+export PATH="$HOME/.local/bin:$PATH"
+
+# Установка пакетов (в основном venv — конфликтует с PaddleOCR)
+pip install surya-ocr torch torchvision --index-url https://download.pytorch.org/whl/cpu
+pip install "opencv-python-headless==4.11.0.86" "pillow<11" transformers platformdirs
+```
+
+Использование:
+```bash
+python -m src.image_to_latex -i page.jpg --ocr-engine surya
+```
+
+---
+
+## Шаг 7: Разработка
+
+```bash
+pip install ruff pytest
+ruff check src/ tests/
+python -m pytest tests/ -v
+```
+
+---
+
+## Структура моделей (локально)
+
+```
+~/.paddlex/official_models/          PaddleOCR (~2.5 GB)
+~/.cache/llama_models/               LLM (~4.4 GB)
+/tmp/hf_cache/                       Surya 2 (~1.5 GB, HuggingFace)
+```

src/cli_utils.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import sys
+
+import typer
+
+
+def run_main(app: typer.Typer) -> None:
+    if len(sys.argv) == 1:
+        app(["--help"], standalone_mode=False)
+        return
+    app()

src/image_split.py

@@ -2,12 +2,12 @@ from __future__ import annotations
 
 import logging
 import os
-import sys
 from pathlib import Path
 from typing import Annotated
 
 import typer
 
+from src.cli_utils import run_main
 from src.split.slicer import (
     DEFAULT_BORDER_PX,
     VALID_ROTATIONS,
@@ -162,10 +162,7 @@ def slice_pages(
 
 
 def main() -> None:
-    if len(sys.argv) == 1:
-        app(["--help"], standalone_mode=False)
-        return
-    app()
+    run_main(app)
 
 
 if __name__ == "__main__":

src/image_to_latex.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import functools
+import json
+import logging
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from src.cli_utils import run_main
+from src.markdown.generator import generate_markdown
+from src.ocr.paddle_engine import ocr_image
+from src.postprocess.fixups import fix_ocr_errors
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)-8s %(message)s")
+logger = logging.getLogger(__name__)
+app = typer.Typer(add_completion=False, no_args_is_help=True)
+
+MD_EXTENSION: str = ".md"
+DEFAULT_LANG: str = "en"
+OCR_ENGINES: dict[str, str] = {"paddle": "PaddleOCR (PP-StructureV3)", "surya": "Surya 2 (VLM)"}
+
+
+def _get_ocr_engine(name: str):
+    if name == "surya":
+        from src.ocr.surya_engine import surya_ocr_image
+
+        return surya_ocr_image, "Surya 2 VLM"
+    return ocr_image, "PP-StructureV3"
+
+
+@app.command()
+def image_to_latex(
+    input: Annotated[
+        Path,
+        typer.Option(
+            "--input",
+            "-i",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            help="Путь к входному изображению (JPEG, PNG, TIFF)",
+        ),
+    ],
+    output_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--output-dir",
+            "-o",
+            file_okay=False,
+            dir_okay=True,
+            writable=True,
+            help="Каталог для сохранения Markdown-файла (по умолчанию — рядом с входным файлом)",
+        ),
+    ] = None,
+    lang: Annotated[
+        str,
+        typer.Option(
+            "--lang",
+            "-l",
+            help="Язык OCR (en, ru, ch, ...)",
+        ),
+    ] = DEFAULT_LANG,
+    ocr_engine: Annotated[
+        str,
+        typer.Option(
+            "--ocr-engine",
+            help="OCR-движок: paddle (PP-StructureV3) или surya (Surya 2 VLM)",
+        ),
+    ] = "paddle",
+    use_llm: Annotated[
+        bool,
+        typer.Option(
+            "--llm",
+            help="Использовать локальный LLM-корректор (Qwen2.5-7B GGUF) для исправления OCR-ошибок",
+        ),
+    ] = False,
+    use_vlm: Annotated[
+        bool,
+        typer.Option(
+            "--vlm",
+            help="Использовать vision LM (Qwen3.8 Max) для распознавания сомнительных регионов. Токен: OPENCODE_API_KEY",
+        ),
+    ] = False,
+) -> None:
+    """OCR → PostProcess → Markdown. --ocr-engine: paddle (default) или surya. Опционально: --llm, --vlm."""
+    ocr_fn, engine_name = _get_ocr_engine(ocr_engine)
+    logger.info("Запуск %s (lang=%s) ...", engine_name, lang)
+    page = ocr_fn(str(input))
+    logger.info("Распознано %d блоков", len(page.blocks))
+
+    fix_ocr_errors(page.blocks)
+
+    if use_llm or use_vlm:
+        from src.postprocess.corrector import apply_corrector
+
+    if use_llm:
+        from src.postprocess.llm_corrector import llm_correct_block
+
+        apply_corrector(page.blocks, llm_correct_block, "LLM")
+
+    if use_vlm:
+        from src.postprocess.vlm_corrector import vlm_correct_block
+
+        vlm_corrector = functools.partial(vlm_correct_block, image_path=str(input.resolve()))
+        apply_corrector(page.blocks, vlm_corrector, "VLM")
+
+    output_dir_resolved = output_dir.resolve() if output_dir else input.resolve().parent
+    output_name = input.stem + MD_EXTENSION
+    output_path = output_dir_resolved / output_name
+
+    generate_markdown(page.blocks, output_path)
+    logger.info("Markdown сохранён: %s", output_path)
+
+    if page.raw_json:
+        json_path = output_dir_resolved / (input.stem + ".json")
+        json_path.write_text(
+            json.dumps(page.raw_json, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+        logger.info("JSON сохранён: %s", json_path)
+
+
+def main() -> None:
+    run_main(app)
+
+
+if __name__ == "__main__":
+    main()

src/latex/__init__.py

@@ -0,0 +1,3 @@
+from src.latex.tex2html import tex_to_html
+
+__all__ = ["tex_to_html"]

src/latex/surya2html.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from bs4 import BeautifulSoup
+
+HTML_TEMPLATE = """\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>{title} — Surya 2</title>
+<script>
+MathJax = {{
+  tex: {{
+    inlineMath: [['$', '$']],
+    displayMath: [['$$', '$$']],
+    packages: {{'[+]': ['ams']}}
+  }},
+  loader: {{load: ['[tex]/ams']}}
+}};
+</script>
+<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js" async></script>
+<style>
+  body {{ font-family: serif; max-width: 800px; margin: 2em auto; padding: 0 1em; line-height: 1.6; }}
+  h2 {{ margin-top: 1.5em; }}
+  .equation {{ text-align: center; margin: 1em 0; }}
+  .header {{ font-weight: bold; }}
+  p {{ margin: 0.5em 0; text-indent: 1.5em; }}
+</style>
+</head>
+<body>
+{body}
+</body>
+</html>
+"""
+
+
+def surya_json_to_html(json_path: str | Path) -> str:
+    data = json.loads(Path(json_path).read_text())
+    blocks = data.get("blocks", [])
+
+    html_parts: list[str] = []
+    for b in blocks:
+        label = b.get("label", "")
+        raw_html = b.get("html", "")
+        if not raw_html.strip():
+            continue
+
+        if label == "Equation":
+            clean = raw_html.replace('<math display="block">', "").replace("</math>", "").strip()
+            html_parts.append(f'\n<div class="equation">$$\n{clean}\n$$</div>')
+            continue
+
+        soup = BeautifulSoup(raw_html, "html.parser")
+        for math_tag in soup.find_all("math"):
+            display = math_tag.get("display", "") == "block"
+            latex = math_tag.get_text().strip()
+            math_tag.replace_with(f"$$\n{latex}\n$$" if display else f"${latex}$")
+
+        text = " ".join(soup.stripped_strings)
+        if not text:
+            continue
+
+        if label in ("SectionHeader",):
+            html_parts.append(f"<h2>{text}</h2>")
+        elif label == "PageHeader":
+            html_parts.append(f'<p class="header">{text}</p>')
+        else:
+            html_parts.append(f"<p>{text}</p>")
+
+    body = "\n".join(html_parts)
+    return HTML_TEMPLATE.format(title=Path(json_path).stem, body=body)

src/latex/tex2html.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+HTML_TEMPLATE = """\
+<!DOCTYPE html>
+<html lang="ru">
+<head>
+<meta charset="utf-8">
+<title>{title}</title>
+<script>
+MathJax = {{
+  tex: {{
+    inlineMath: [['$', '$']],
+    displayMath: [['$$', '$$']],
+    processEscapes: true
+  }}
+}};
+</script>
+<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js" async></script>
+<style>
+  body {{ font-family: serif; max-width: 800px; margin: 2em auto; padding: 0 1em; line-height: 1.6; }}
+  p {{ text-indent: 1.5em; margin: 0.5em 0; }}
+</style>
+</head>
+<body>
+<pre style="white-space: pre-wrap; font-family: serif;">
+{body}
+</pre>
+</body>
+</html>
+"""
+
+
+def tex_to_html(tex_path: Path) -> Path:
+    tex_content = tex_path.read_text(encoding="utf-8")
+    start = tex_content.find("\\begin{document}") + len("\\begin{document}")
+    end = tex_content.find("\\end{document}")
+    body = tex_content[start:end].strip()
+
+    html_content = HTML_TEMPLATE.format(
+        title=tex_path.stem,
+        body=body,
+    )
+    html_path = tex_path.with_suffix(".html")
+    html_path.write_text(html_content, encoding="utf-8")
+    return html_path
+
+
+if __name__ == "__main__":
+    for p in sys.argv[1:]:
+        result = tex_to_html(Path(p))
+        print(f"HTML: {result}")

src/markdown/__init__.py

@@ -0,0 +1,3 @@
+from src.markdown.generator import generate_markdown, validate_markdown
+
+__all__ = ["generate_markdown", "validate_markdown"]

src/markdown/generator.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+
+from src.ocr.paddle_engine import ParsedBlock
+
+logger = logging.getLogger(__name__)
+
+
+def _validate_latex_braces(content: str) -> list[str]:
+    warnings: list[str] = []
+    depth = 0
+    for i, ch in enumerate(content):
+        if ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth < 0:
+                warnings.append(f"Лишняя }} на позиции {i}")
+                depth = 0
+    if depth > 0:
+        warnings.append(f"Непарные {{: {depth} лишних открывающих")
+    return warnings
+
+
+def _validate_dollar_signs(content: str) -> list[str]:
+    warnings: list[str] = []
+    dollar_count = 0
+    i = 0
+    while i < len(content):
+        if content[i] == "$":
+            if i + 1 < len(content) and content[i + 1] == "$":
+                dollar_count += 2
+                i += 2
+                continue
+            dollar_count += 1
+        i += 1
+    if dollar_count % 2 != 0:
+        warnings.append(f"Непарные знаки $: {dollar_count}")
+    return warnings
+
+
+def _validate_left_right(content: str) -> list[str]:
+    warnings: list[str] = []
+    left_count = content.count("\\left")
+    right_count = content.count("\\right")
+    if left_count != right_count:
+        warnings.append(f"Непарные \\left/\\right: {left_count}/{right_count}")
+    return warnings
+
+
+def validate_markdown(md_content: str) -> list[str]:
+    warnings: list[str] = []
+    warnings.extend(_validate_dollar_signs(md_content))
+    warnings.extend(_validate_left_right(md_content))
+
+    for block in re.findall(r"\$\$(.+?)\$\$", md_content, re.DOTALL):
+        warnings.extend(_validate_latex_braces(block))
+    for block in re.findall(r"\$(.+?)\$", md_content):
+        warnings.extend(_validate_latex_braces(block))
+    return warnings
+
+
+def _blocks_to_markdown(blocks: list[ParsedBlock]) -> str:
+    lines: list[str] = []
+    for block in blocks:
+        text = block.content.strip()
+        if not text:
+            continue
+
+        if block.label == "formula":
+            lines.append(f"$$\n{text}\n$$\n")
+        elif block.label in ("paragraph_title", "title", "section_header"):
+            lines.append(f"\n## {text}\n")
+        elif block.label == "number":
+            lines.append(f"\n{text}\n")
+        else:
+            lines.append(f"\n{text}\n")
+    return "\n".join(lines)
+
+
+def generate_markdown(blocks: list[ParsedBlock], output_path: Path) -> Path:
+    md_content = _blocks_to_markdown(blocks)
+
+    warnings = validate_markdown(md_content)
+    if warnings:
+        logger.warning("Ошибки валидации LaTeX:")
+        for w in warnings:
+            logger.warning("  %s", w)
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(md_content, encoding="utf-8")
+    return output_path

src/ocr/__init__.py

@@ -0,0 +1,3 @@
+from src.ocr.paddle_engine import OcrPageResult, ParsedBlock, ocr_image
+
+__all__ = ["OcrPageResult", "ParsedBlock", "ocr_image"]

src/ocr/paddle_engine.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import importlib.resources
+from dataclasses import dataclass, field
+from typing import Any
+
+import cv2
+import yaml
+from paddlex import create_pipeline
+
+
+@dataclass
+class ParsedBlock:
+    label: str
+    content: str
+    bbox: tuple[int, int, int, int]
+    confidence: float = 0.9
+
+
+@dataclass
+class OcrPageResult:
+    blocks: list[ParsedBlock] = field(default_factory=list)
+    raw_json: dict[str, Any] = field(default_factory=dict)
+    width: int = 0
+    height: int = 0
+
+
+def _load_config() -> dict[str, Any]:
+    ref = importlib.resources.files("paddlex") / "configs" / "pipelines" / "PP-StructureV3.yaml"
+    with importlib.resources.as_file(ref) as path, open(path) as f:
+        config: dict[str, Any] = yaml.safe_load(f)
+
+    config["SubPipelines"]["GeneralOCR"]["SubModules"]["TextRecognition"]["model_name"] = (
+        "eslav_PP-OCRv5_mobile_rec"
+    )
+    table_ocr = config["SubPipelines"]["TableRecognition"]["SubPipelines"]["GeneralOCR"]
+    table_ocr["SubModules"]["TextRecognition"]["model_name"] = "eslav_PP-OCRv5_mobile_rec"
+    return config
+
+
+class OcrEngine:
+    def __init__(self) -> None:
+        self._config: dict[str, Any] = _load_config()
+
+    def process(self, image_path: str) -> OcrPageResult:
+        image = cv2.imread(image_path)
+        if image is None:
+            raise FileNotFoundError(f"Не удалось загрузить изображение: {image_path}")
+
+        h, w = image.shape[:2]
+        pipeline = create_pipeline(
+            config=self._config,
+            use_doc_orientation_classify=False,
+            use_doc_unwarping=False,
+        )
+        raw_results = list(pipeline.predict(image))
+
+        blocks, raw_json = self._parse_results(raw_results)
+        return OcrPageResult(blocks=blocks, raw_json=raw_json, width=w, height=h)
+
+    @staticmethod
+    def _parse_results(raw_results: list[Any]) -> tuple[list[ParsedBlock], dict[str, Any]]:
+        if not raw_results:
+            return [], {}
+
+        raw_json: dict[str, Any] = raw_results[0].json["res"]
+        blocks: list[ParsedBlock] = []
+        for item in raw_json.get("parsing_res_list", []):
+            text = item.get("block_content", "")
+            label = item.get("block_label", "text")
+            bbox = item.get("block_bbox", [0, 0, 0, 0])
+            if not text.strip():
+                continue
+            blocks.append(ParsedBlock(
+                label=label, content=text,
+                bbox=(int(bbox[0]), int(bbox[1]), int(bbox[2]), int(bbox[3])),
+            ))
+        return blocks, raw_json
+
+
+_engine: OcrEngine | None = None
+
+
+def ocr_image(image_path: str) -> OcrPageResult:
+    global _engine
+    if _engine is None:
+        _engine = OcrEngine()
+    return _engine.process(image_path)

src/ocr/surya_engine.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+from pathlib import Path
+
+from src.ocr.paddle_engine import OcrPageResult, ParsedBlock
+
+logger = logging.getLogger(__name__)
+
+_ENV_LOADED: bool = False
+
+
+def _load_env() -> None:
+    global _ENV_LOADED
+    if _ENV_LOADED:
+        return
+    env_path = Path(__file__).resolve().parent.parent.parent / ".env"
+    if env_path.exists():
+        with open(env_path) as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    key, _, value = line.partition("=")
+                    key = key.strip()
+                    if key not in os.environ:
+                        os.environ[key] = value.strip().strip("\"'")
+    _ENV_LOADED = True
+
+
+def _ensure_env() -> None:
+    _load_env()
+    os.environ.setdefault("SURYA_INFERENCE_BACKEND", "llamacpp")
+    os.environ.setdefault("SURYA_GUIDED_LAYOUT", "false")
+    if "LLAMA_CPP_BINARY" not in os.environ:
+        binary = shutil.which("llama-server") or os.path.expanduser(
+            "~/.local/bin/llama-server"
+        )
+        if Path(binary).exists():
+            os.environ["LLAMA_CPP_BINARY"] = binary
+
+
+class SuryaEngine:
+    """OCR engine using Surya 2 VLM via llama.cpp."""
+
+    def __init__(self) -> None:
+        _ensure_env()
+        try:
+            from surya.inference import SuryaInferenceManager
+            from surya.recognition import RecognitionPredictor
+
+            self._manager = SuryaInferenceManager()
+            self._predictor = RecognitionPredictor(self._manager)
+        except ImportError as e:
+            msg = (
+                "Surya engine not available. Install: pip install surya-ocr torch"
+            )
+            raise ImportError(msg) from e
+
+    def process(self, image_path: str) -> OcrPageResult:
+        from PIL import Image
+
+        image = Image.open(image_path)
+        results = self._predictor([image])
+
+        blocks: list[ParsedBlock] = []
+        raw_json: dict = {}
+
+        if results:
+            page = results[0]
+            for blk in getattr(page, "blocks", []):
+                html = getattr(blk, "html", "") or ""
+                label = getattr(blk, "label", "text")
+                bbox = getattr(blk, "bbox", [0, 0, 0, 0])
+                confidence = float(getattr(blk, "confidence", 0.9))
+                blocks.append(
+                    ParsedBlock(
+                        label=label,
+                        content=html,
+                        bbox=(int(bbox[0]), int(bbox[1]), int(bbox[2]), int(bbox[3])),
+                        confidence=confidence,
+                    )
+                )
+
+        return OcrPageResult(
+            blocks=blocks,
+            raw_json=raw_json,
+            width=image.width,
+            height=image.height,
+        )
+
+
+_surya_engine: SuryaEngine | None = None
+
+
+def surya_ocr_image(image_path: str) -> OcrPageResult:
+    global _surya_engine
+    if _surya_engine is None:
+        _surya_engine = SuryaEngine()
+    return _surya_engine.process(image_path)

src/postprocess/__init__.py

@@ -0,0 +1,3 @@
+from src.postprocess.fixups import fix_ocr_errors
+
+__all__ = ["fix_ocr_errors"]

src/postprocess/corrector.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import logging
+from typing import Protocol
+
+from src.ocr.paddle_engine import ParsedBlock
+
+logger = logging.getLogger(__name__)
+
+
+class Corrector(Protocol):
+    def __call__(self, block: ParsedBlock) -> ParsedBlock: ...
+
+
+def apply_corrector(
+    blocks: list[ParsedBlock],
+    corrector: Corrector,
+    name: str,
+    skip_formulas: bool = True,
+) -> None:
+    for i, block in enumerate(blocks):
+        if skip_formulas and block.label == "formula":
+            continue
+        logger.info("%s: блок %d/%d...", name, i + 1, len(blocks))
+        corrector(block)
+    logger.info("%s: завершено", name)

src/postprocess/fixups.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import re
+
+from src.ocr.paddle_engine import ParsedBlock
+
+_SPACED_VARS = re.compile(r"\b([A-Z])\s+([A-Z])\b")
+
+
+def fix_ocr_errors(blocks: list[ParsedBlock]) -> list[ParsedBlock]:
+    for block in blocks:
+        if block.label == "formula":
+            block.content = _fix_formula_errors(block.content)
+    return blocks
+
+
+def _fix_formula_errors(content: str) -> str:
+    for _ in range(4):
+        prev = content
+        content = _SPACED_VARS.sub(r"\1\2", content)
+        if prev == content:
+            break
+    return content

src/postprocess/llm_corrector.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import os
+
+from llama_cpp import Llama
+
+from src.ocr.paddle_engine import ParsedBlock
+
+DEFAULT_LLM_PATH = os.path.expanduser("~/.cache/llama_models/Qwen2.5-7B-Instruct-Q4_K_M.gguf")
+
+
+class LlmCorrector:
+    def __init__(self, model_path: str = DEFAULT_LLM_PATH) -> None:
+        self._llm = Llama(
+            model_path=model_path,
+            n_ctx=1024,
+            n_threads=8,
+            verbose=False,
+        )
+
+    def __call__(self, block: ParsedBlock) -> ParsedBlock:
+        if block.label == "formula":
+            return block
+        if len(block.content) < 30:
+            return block
+
+        text = block.content[:400]
+        messages = [
+            {"role": "system", "content": "Ты корректор OCR-ошибок. Возвращай ТОЛЬКО исправленный текст."},
+            {"role": "user", "content": f"Исправь:\n\n{text}"},
+        ]
+        response = self._llm.create_chat_completion(messages=messages, max_tokens=150, temperature=0.0)
+        corrected = response["choices"][0]["message"]["content"].strip()
+
+        if corrected and len(corrected) > 10 and corrected != text:
+            block.content = corrected
+        return block
+
+
+_llm_corrector: LlmCorrector | None = None
+
+
+def llm_correct_block(block: ParsedBlock) -> ParsedBlock:
+    global _llm_corrector
+    if _llm_corrector is None:
+        _llm_corrector = LlmCorrector()
+    return _llm_corrector(block)

src/postprocess/vlm_corrector.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import base64
+import logging
+import os
+import time as _time
+from pathlib import Path
+from typing import Any
+
+import cv2
+import requests
+
+from src.ocr.paddle_engine import ParsedBlock
+
+logger = logging.getLogger(__name__)
+
+API_KEY_ENV: str = "OPENCODE_API_KEY"
+API_URL_ENV: str = "OPENCODE_API_URL"
+DEFAULT_MODEL: str = "qwen3.8-max"
+
+_ENV_LOADED: bool = False
+
+
+def _load_env() -> None:
+    global _ENV_LOADED
+    if _ENV_LOADED:
+        return
+    env_path = Path(__file__).resolve().parent.parent.parent / ".env"
+    if env_path.exists():
+        with open(env_path) as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    key, _, value = line.partition("=")
+                    if key.strip() not in os.environ:
+                        os.environ[key.strip()] = value.strip().strip("\"'")
+    _ENV_LOADED = True
+
+
+def _get_api_key() -> str:
+    _load_env()
+    return os.environ.get(API_KEY_ENV, "")
+
+
+def _get_api_url() -> str:
+    return os.environ.get(API_URL_ENV, "https://opencode.ai/zen/go/v1/messages")
+
+SYSTEM_PROMPT: str = (
+    "Extract ALL visible text from this document image region. "
+    "Preserve LaTeX math ($...$ and $$...$$). "
+    "Return ONLY the corrected text, no commentary."
+)
+
+
+def _image_to_base64(image: Any) -> str:
+    _, buffer = cv2.imencode(".jpg", image, [cv2.IMWRITE_JPEG_QUALITY, 90])
+    return base64.b64encode(buffer).decode("utf-8")
+
+
+def vlm_correct_block(block: ParsedBlock, image_path: str, model: str = DEFAULT_MODEL) -> ParsedBlock:
+    if block.label == "formula":
+        return block
+    if not _get_api_key():
+        logger.warning("VLM: %s не задан, пропускаем", API_KEY_ENV)
+        return block
+
+    image = cv2.imread(image_path)
+    if image is None:
+        return block
+
+    h, w = image.shape[:2]
+    x1, y1, x2, y2 = block.bbox
+    x1 = max(0, x1 - 5)
+    y1 = max(0, y1 - 5)
+    x2 = min(w, x2 + 5)
+    y2 = min(h, y2 + 5)
+    if x1 >= x2 or y1 >= y2:
+        return block
+
+    crop = image[y1:y2, x1:x2]
+    crop_h, crop_w = crop.shape[:2]
+    logger.info("VLM: отправка региона %dx%d px (bbox %d,%d,%d,%d)", crop_w, crop_h, x1, y1, x2, y2)
+    b64 = _image_to_base64(crop)
+
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": "image/jpeg",
+                        "data": b64,
+                    },
+                },
+                {
+                    "type": "text",
+                    "text": f"{SYSTEM_PROMPT}\n\nExtract all text from this image region. Return ONLY the extracted text.",
+                },
+            ],
+        },
+    ]
+
+    for attempt in (1, 2):
+        try:
+            response = requests.post(
+                _get_api_url(),
+                headers={
+                    "x-api-key": _get_api_key(),
+                    "anthropic-version": "2023-06-01",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "model": model,
+                    "max_tokens": 300,
+                    "messages": messages,
+                },
+                timeout=120,
+            )
+            response.raise_for_status()
+            data = response.json()
+            text = ""
+            for item in data.get("content", []):
+                if item.get("type") == "text":
+                    text = item.get("text", "").strip()
+                    break
+            if text and len(text) > 5:
+                block.content = text
+                logger.info("VLM: результат (%d символов): %s", len(text), text[:120])
+            else:
+                logger.info("VLM: пустой или короткий ответ (%d символов)", len(text) if text else 0)
+            return block
+        except requests.HTTPError as e:
+            if e.response is not None and e.response.status_code == 500 and attempt == 1:
+                logger.info("VLM: HTTP 500, ожидание 5с и повтор...")
+                _time.sleep(5)
+                continue
+            logger.warning("VLM: ошибка — %s", e)
+            return block
+        except (requests.RequestException, KeyError, IndexError) as e:
+            logger.warning("VLM: ошибка — %s", e)
+            return block
+
+    return block

stage2_OCR_updates.md

@@ -0,0 +1,188 @@
+# Требования к улучшению генерации Markdown
+
+## Цель
+
+Повысить качество Markdown, генерируемого из PDF с помощью PP-StructureV3, чтобы результат можно было использовать для:
+
+- просмотра в браузере;
+- последующего анализа LLM;
+- конвертации в HTML;
+- корректного отображения формул через MathJax/KaTeX.
+
+---
+
+# 1. Формулы
+
+## Display-формулы
+
+- Все блочные формулы должны сохраняться в исходном LaTeX, полученном от PP-StructureV3.
+- Формулы не должны изменяться или экранироваться.
+- Использовать стандартный синтаксис
+
+```markdown
+$$
+...
+$$
+```
+
+---
+
+## Inline-формулы
+
+Текущая проблема:
+
+```markdown
+\$R=r\^{}\{2\}\$
+```
+
+или
+
+```markdown
+\textbackslash{}sim
+```
+
+Такой вывод недопустим.
+
+Требования:
+
+- inline-формулы должны сохраняться как
+
+```markdown
+$R=r^{2}$
+```
+
+или
+
+```markdown
+$u_i \sim N(0,1)$
+```
+
+- не использовать `\textbackslash{}`
+- не использовать `\$`
+- не использовать экранирование LaTeX-команд
+
+---
+
+# 2. Не преобразовывать LaTeX в текст
+
+Запрещается преобразовывать
+
+```latex
+\alpha
+\sqrt
+\frac
+\sim
+\left
+\right
+```
+
+в
+
+```text
+\textbackslash{}alpha
+\textbackslash{}sqrt
+...
+```
+
+Markdown должен содержать настоящий LaTeX.
+
+---
+
+# 3. OCR-постобработка формул
+
+Исправлять наиболее типичные OCR-ошибки.
+
+Например
+
+| Было | Должно стать |
+|------|--------------|
+| `V a R` | `VaR` |
+| `P D` | `PD` |
+| `N ^ {-1}` | `N^{-1}` |
+| `l` вместо `1` | исправлять при высокой уверенности |
+| `O` вместо `0` | исправлять при высокой уверенности |
+
+---
+
+# 4. Inline-формулы внутри текста
+
+По возможности выделять математические выражения внутри абзацев.
+
+Например
+
+```text
+where u_i ~ N(0,1)
+```
+
+↓
+
+```markdown
+where $u_i \sim N(0,1)$
+```
+
+Даже если PP-StructureV3 не выделил их отдельным Formula Block.
+
+---
+
+# 5. Не генерировать TeX-документ
+
+Не использовать экспорт в полноценный `.tex`.
+
+Целевой формат — Markdown.
+
+Формулы должны быть совместимы с MathJax и KaTeX.
+
+---
+
+# 6. Проверка корректности LaTeX
+
+Перед сохранением желательно проверить:
+
+- баланс фигурных скобок;
+- баланс `\left...\right`;
+- парность `$`;
+- отсутствие повреждённых команд.
+
+Некорректный LaTeX должен логироваться.
+
+---
+
+# 7. Качество Markdown
+
+Запрещается появление конструкций вида
+
+```text
+\textbackslash{}
+\$
+\_
+```
+
+если они являются следствием экранирования LaTeX.
+
+В итоговом Markdown должен оставаться исходный LaTeX.
+
+---
+
+# 8. HTML
+
+Markdown должен без дополнительной обработки корректно преобразовываться в HTML с использованием MathJax или KaTeX.
+
+После конвертации все формулы должны отображаться без ручного исправления.
+
+---
+
+# 9. Разделить этапы OCR и генерации Markdown
+
+Не смешивать OCR, исправление текста и генерацию Markdown в одном проходе.
+
+Рекомендуемый pipeline:
+
+1. PP-StructureV3
+2. OCR результатов
+3. Постобработка OCR
+4. Исправление типичных ошибок LaTeX
+5. Генерация Markdown
+6. Валидация Markdown
+7. Конвертация в HTML
+
+Это позволит независимо улучшать качество OCR, постобработки и форматирования без изменения остальных этапов.

stage2_OCR_updates2.md

@@ -0,0 +1,293 @@
+# Оценка качества OCR и требования к улучшению
+
+## Общая оценка
+
+### Что получилось хорошо
+
+✅ Структура документа (layout) определяется качественно.
+
+✅ Порядок чтения блоков в целом корректный.
+
+✅ Таблицы извлекаются хорошо.
+
+✅ Display-формулы (отдельные блочные формулы) успешно выделяются и экспортируются в LaTeX.
+
+Например:
+
+```latex
+A_{i}=Z\cdot r+u_{i}\cdot\sqrt{1-R}
+```
+
+является корректным LaTeX и без проблем отображается в MathJax/KaTeX.
+
+---
+
+## Основные проблемы
+
+### 1. Inline-формулы практически не распознаются
+
+Это самая серьёзная проблема текущего pipeline.
+
+Формулы вида
+
+```text
+u_i ~ N(0,1)
+
+R = r²
+
+r = corr(...)
+```
+
+не выделяются как математические выражения.
+
+Вместо этого они становятся частью обычного текста.
+
+Именно это является причиной большинства последующих ошибок.
+
+---
+
+### 2. LaTeX повреждается при генерации Markdown
+
+В результате появляются конструкции вида
+
+```text
+\$R=r\^{}\{2\}\$
+```
+
+```text
+\textbackslash{}sim
+```
+
+```text
+\textbackslash{}mathrm
+```
+
+```text
+A\_i
+```
+
+Это уже невалидный LaTeX.
+
+MathJax здесь не является причиной проблемы — он получает уже повреждённый текст.
+
+---
+
+### 3. Избыточное экранирование
+
+Необходимо полностью исключить появление:
+
+```
+\$
+\_
+\textbackslash{}
+```
+
+если они являются результатом сериализации LaTeX.
+
+Markdown должен содержать настоящий LaTeX, а не его текстовое представление.
+
+---
+
+### 4. OCR допускает типичные ошибки
+
+Например
+
+```
+V a R
+```
+
+вместо
+
+```
+VaR
+```
+
+```
+P D
+```
+
+вместо
+
+```
+PD
+```
+
+```
+vhere
+```
+
+вместо
+
+```
+where
+```
+
+```
+ndividual
+```
+
+вместо
+
+```
+Individual
+```
+
+Это снижает качество итогового документа.
+
+---
+
+# Требования к улучшению
+
+## Высокий приоритет
+
+### 1. Исправить обработку inline-формул
+
+Inline-математика должна сохраняться как
+
+```markdown
+$u_i \sim N(0,1)$
+```
+
+а не как текст
+
+```text
+\$u\_\{i\}\textbackslash{}sim...
+```
+
+---
+
+### 2. Не экранировать LaTeX
+
+Запрещается преобразовывать
+
+```latex
+\sqrt
+\frac
+\alpha
+\sim
+\mathrm
+```
+
+в
+
+```text
+\textbackslash{}sqrt
+\textbackslash{}frac
+...
+```
+
+---
+
+### 3. Сохранять display-формулы без изменений
+
+LaTeX, полученный от PP-StructureV3, должен использоваться без модификации.
+
+Формат вывода:
+
+```markdown
+$$
+...
+$$
+```
+
+---
+
+### 4. Улучшить OCR-постобработку
+
+Исправлять наиболее типичные ошибки OCR.
+
+Например:
+
+| Было | Должно стать |
+|------|--------------|
+| `V a R` | `VaR` |
+| `P D` | `PD` |
+| `N ^ {-1}` | `N^{-1}` |
+| `l` → `1` | при высокой уверенности |
+| `O` → `0` | при высокой уверенности |
+
+---
+
+## Средний приоритет
+
+### 5. Валидировать LaTeX
+
+Перед сохранением желательно проверять:
+
+- баланс фигурных скобок;
+- баланс `\left...\right`;
+- баланс `$`;
+- корректность команд.
+
+---
+
+### 6. Генерировать "чистый" Markdown
+
+Итоговый Markdown должен сразу корректно отображаться через MathJax или KaTeX без дополнительной обработки.
+
+---
+
+# Предлагаемая архитектура pipeline
+
+Текущий pipeline смешивает OCR, обработку текста и генерацию Markdown.
+
+Предлагается разделить его на независимые этапы:
+
+```
+PDF
+    │
+    ▼
+PP-StructureV3
+    │
+    ▼
+Извлечение структуры документа
+    │
+    ├── текст
+    ├── таблицы
+    ├── изображения
+    └── display-формулы
+    │
+    ▼
+Постобработка OCR
+    │
+    ▼
+Выделение inline-формул
+    │
+    ▼
+Исправление типичных OCR-ошибок
+    │
+    ▼
+Генерация Markdown
+    │
+    ▼
+Валидация Markdown / LaTeX
+    │
+    ▼
+HTML + MathJax / KaTeX
+```
+
+---
+
+# Итоговая оценка
+
+| Компонент | Оценка |
+|-----------|:------:|
+| Layout | ⭐⭐⭐⭐⭐ |
+| Reading order | ⭐⭐⭐⭐⭐ |
+| Таблицы | ⭐⭐⭐⭐⭐ |
+| Display-формулы | ⭐⭐⭐⭐☆ |
+| Русский OCR | ⭐⭐⭐☆☆ |
+| Inline-формулы | ⭐☆☆☆☆ |
+| Генерация Markdown | ⭐⭐☆☆☆ |
+
+## Главный вывод
+
+Основная проблема текущего решения — не качество MathJax и не display-формул.
+
+Критические недостатки находятся в двух местах:
+
+1. **inline-математические выражения не выделяются как отдельные математические объекты;**
+2. **при генерации Markdown происходит повреждение LaTeX из-за его экранирования.**
+
+До устранения этих проблем невозможно получить Markdown, пригодный для качественного отображения формул и последующего анализа LLM.
+

stage2_research.md

@@ -0,0 +1,209 @@
+# Stage 2. Исследование возможностей PaddleOCR + Docling
+
+## Цель исследования
+
+Перед началом реализации второго этапа проекта необходимо изучить возможности современных версий PaddleOCR и Docling.
+
+Цель исследования — максимально использовать готовые возможности библиотек и не реализовывать функциональность, которая уже существует.
+
+По итогам исследования необходимо подготовить краткий технический отчёт и рекомендации по архитектуре второго этапа.
+
+---
+
+# Необходимо исследовать
+
+## 1. Совместимость PaddleOCR и Docling
+
+Необходимо определить:
+
+- может ли Docling использовать PaddleOCR как OCR backend;
+- какие версии библиотек совместимы между собой;
+- существуют ли официально поддерживаемые способы интеграции.
+
+---
+
+## 2. Форматы экспорта
+
+Необходимо определить, какие форматы умеет генерировать Docling.
+
+Для каждого формата необходимо указать:
+
+- поддерживается ли официально;
+- степень сохранения структуры документа;
+- пригодность для последующего анализа LLM.
+
+Минимально исследовать:
+
+- HTML
+- Markdown
+- JSON
+- DocTags
+- Plain Text
+
+---
+
+## 3. Качество HTML
+
+Определить:
+
+- насколько полно сохраняется структура документа;
+- сохраняются ли таблицы;
+- сохраняются ли объединённые ячейки;
+- сохраняются ли изображения;
+- сохраняются ли подписи рисунков;
+- сохраняются ли заголовки;
+- сохраняются ли списки.
+
+Приложить небольшой пример HTML.
+
+---
+
+## 4. Таблицы
+
+Исследовать:
+
+- качество восстановления таблиц;
+- поддержку rowspan;
+- поддержку colspan;
+- возможность восстановления сложных таблиц.
+
+При наличии ограничений подробно их описать.
+
+---
+
+## 5. Формулы
+
+Определить:
+
+- распознаёт ли Docling математические формулы;
+- сохраняются ли формулы как текст;
+- сохраняются ли как изображения;
+- поддерживается ли MathML;
+- поддерживается ли LaTeX.
+
+При наличии ограничений описать их.
+
+---
+
+## 6. OCR Confidence
+
+Определить:
+
+- предоставляет ли PaddleOCR confidence;
+- может ли Docling сохранить confidence;
+- можно ли передать confidence в HTML;
+- можно ли использовать confidence для последующей подсветки сомнительных мест.
+
+---
+
+## 7. Координаты элементов
+
+Определить:
+
+можно ли получить координаты:
+
+- страниц;
+- абзацев;
+- таблиц;
+- строк;
+- отдельных слов.
+
+---
+
+## 8. Производительность
+
+Для документов объёмом около 150 страниц определить:
+
+- примерное время обработки;
+- объём используемой памяти;
+- возможность пакетной обработки.
+
+---
+
+## 9. Работа полностью offline
+
+Подтвердить, что:
+
+- PaddleOCR работает полностью offline;
+- Docling работает полностью offline;
+- отсутствуют обращения к облачным сервисам.
+
+---
+
+## 10. Возможность ручной корректировки
+
+Определить:
+
+Можно ли после генерации HTML:
+
+- открыть его в браузере;
+- открыть в Microsoft Word;
+- открыть в LibreOffice Writer;
+- исправить ошибки OCR;
+- сохранить обратно без существенной потери структуры.
+
+---
+
+## 11. Минимальный пример
+
+Подготовить минимальный рабочий пример.
+
+Pipeline должен выглядеть следующим образом:
+
+```
+JPEG страницы
+
+↓
+
+PaddleOCR
+
+↓
+
+Docling
+
+↓
+
+HTML
+```
+
+Необходимо показать:
+
+- пример входного изображения;
+- пример кода;
+- пример полученного HTML.
+
+---
+
+# Что НЕ требуется
+
+На данном этапе не требуется:
+
+- писать production-код;
+- проектировать архитектуру проекта;
+- реализовывать CLI;
+- реализовывать HTML-генератор;
+- реализовывать OCR самостоятельно.
+
+---
+
+# Результат исследования
+
+По окончании исследования необходимо подготовить документ:
+
+```
+STAGE2_RESEARCH_RESULT.md
+```
+
+Документ должен содержать:
+
+1. Краткое описание возможностей PaddleOCR.
+2. Краткое описание возможностей Docling.
+3. Выявленные ограничения.
+4. Рекомендуемую архитектуру второго этапа.
+5. Минимальный рабочий пример интеграции.
+6. Перечень функций, которые уже реализованы библиотеками и не требуют собственной разработки.
+7. Перечень функций, которые придётся реализовать самостоятельно.
+8. Итоговую рекомендацию по реализации второго этапа проекта.
+
+Главная цель исследования — минимизировать объём собственного кода за счёт максимально полного использования возможностей PaddleOCR и Docling.
+

stage2_results.md

@@ -0,0 +1,217 @@
+# Stage 2 Results — OCR Pipeline
+
+## Путь проекта
+
+### Исходная точка
+Единый скрипт `src/cli.py` → разрезание изображений на страницы (Stage 1). Нужен Stage 2 — распознавание текста и структуры документа, генерация LaTeX/HTML/Markdown для последующего анализа LLM.
+
+---
+
+## Опробованные варианты
+
+### 1. PaddleOCR базовый (PP-OCRv5)
+**Результат:** 66 текстовых блоков, русский текст — ~60% точности.
+- `i-WHAeKC AOrOBOpa` вместо `і - индекс договора`
+- `t - номер месяцаB дефолте` — латиница смешана с кириллицей
+- Нет структуры документа (заголовки, формулы, таблицы слиты в сплошной текст)
+- **Вывод:** только для английского, для русского требуется структура
+
+### 2. PP-StructureV3 (ансамбль специализированных моделей)
+**Результат:** 22 структурированных блока с layout-разметкой.
+- Layout detection: ✅ `[number]`, `[formula]`, `[text]`, `[paragraph_title]`
+- Display-формулы: ✅ `\mathrm{C Rec}_{\mathrm{it}}=\sum...`
+- Таблицы: ✅ (PP-TableMagic)
+- Русский текст: ⚠️ ~85% (eslav_PP-OCRv5_mobile_rec — мобильная модель)
+- **Вывод:** структура отлично, текст — приемлемо
+
+### 3. Замена модели на cyrillic_PP-OCRv5_mobile_rec
+**Результат:** разница ~1-2%, несущественна.
+- eslav: `LGD_ехtг;` (кириллица г)
+- cyrillic: `LGD_ехtr;` (латиница r) — чуть лучше
+- **Вывод:** обе мобильные модели с одинаковыми ограничениями
+
+### 4. PP-OCRv5_server_rec / PP-OCRv6
+**Результат:** ❌ не поддерживают русский язык.
+- Server model: только CN/JP/EN
+- PP-OCRv6: 52 латинских языка, русского нет
+- **Вывод:** серверной русской модели в PaddleOCR не существует
+
+### 5. Локальный LLM-корректор (Qwen2.5-7B GGUF)
+**Результат:** +25% читаемости текста.
+```
+До:   t - номер месяцаB дефолте, на который прогнозируются возвраты
+После: т — номер месяца в диапазоне между текущим сроком в дефолте и горизонтом взыскания
+```
+- ~4 tok/sec на CPU, ~20s/блок
+- **Вывод:** эффективен для пост-обработки
+
+### 6. VLM-корректор (Qwen3.8 Max через OpenCode API)
+**Результат:** полное восстановление текста + автоопределение inline-формул.
+```
+До:   ΣДсе, - дисконтированная сумма возвратов
+После: $\sum_t DCF_{i,t}$ — дисконтированная сумма возвратов, получаемых на t-ом периоде
+```
+- ~10s/блок, Anthropic API через `zen/go/v1/messages`
+- **Вывод:** лучшее качество, но требует API-доступа
+
+### 7. Docling (IBM Research)
+**Результат:** ❌ не поддерживает PaddleOCR как OCR-backend.
+- Поддерживает: EasyOCR, Tesseract, RapidOCR, Nemotron
+- Генерирует HTML/Markdown из коробки
+- **Вывод:** несовместим с нашим пайплайном
+
+### 8. PaddleOCR-VL (VLM-подход, ERNIE-4.5-0.3B)
+**Результат:** модель загружена (1.79 GB), но ~15 мин/стр на CPU.
+- Одна VLM вместо ансамбля: layout → распознавание единой моделью
+- Теоретически решает проблему русского (языковая модель понимает контекст)
+- **Вывод:** правильный подход при GPU, нереализуем на CPU
+
+### 9. Surya 2 (Datalab, 650M VLM)
+**Результат:** ⭐ лучший русский OCR из коробки.
+- 95%+ точность русского текста без коррекции
+- Автоопределение inline-формул: `<math>MRec_{it}</math>`
+- ~430s/стр на CPU (vs 140s у PaddleOCR, но качество несравнимо)
+- Вывод Markdown с `$$...$$` формулами
+- **Вывод:** лучший выбор при достаточных ресурсах
+
+---
+
+## Итоговая архитектура
+
+```
+                        Входное изображение (JPEG/PNG/TIFF)
+                                    │
+                      ┌─────────────┴─────────────┐
+                      │    src/image_split.py      │
+                      │  --slice / --slice-auto    │
+                      │  --pre-rotate, --border    │
+                      │  --post-crop (default ON)  │
+                      └─────────────┬─────────────┘
+                                    │
+                             JPEG страницы
+                                    │
+                      ┌─────────────┴─────────────┐
+                      │  src/image_to_latex.py     │
+                      │  --ocr-engine paddle/surya │
+                      │  --llm, --vlm (optional)   │
+                      └─────────────┬─────────────┘
+                                    │
+              ┌─────────────────────┼─────────────────────┐
+              ▼                     ▼                     ▼
+    ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
+    │  src/ocr/        │  │ src/postprocess/ │  │ src/postprocess/ │
+    │  paddle_engine   │  │ fixups.py        │  │ llm_corrector    │
+    │  surya_engine    │  │ vlm_corrector    │  │ corrector.py     │
+    └────────┬────────┘  └────────┬────────┘  └────────┬────────┘
+             │                    │                     │
+             └────────────────────┼─────────────────────┘
+                                  │
+                         ParsedBlock[]
+                                  │
+                    ┌─────────────┴─────────────┐
+                    │  src/markdown/             │
+                    │  generator.py              │
+                    │  Валидация $, {}, \left   │
+                    └─────────────┬─────────────┘
+                                  │
+              ┌───────────────────┼───────────────────┐
+              ▼                   ▼                   ▼
+         .json (raw)          .md              .tex + .html
+     (PP-StructureV3      (Markdown)      (LaTeX + MathJax)
+      полный дамп)
+```
+
+### Модули
+
+```
+src/
+  cli_utils.py           — run_main() общий для CLI
+  image_split.py         — CLI разрезания (Stage 1)
+  image_to_latex.py      — CLI OCR (Stage 2)
+  split/
+    slicer.py            — разрезание, поворот, рамка, post-crop
+  ocr/
+    paddle_engine.py     — PP-StructureV3 + кастом YAML (eslav)
+    surya_engine.py      — Surya 2 VLM + llama.cpp
+  postprocess/
+    fixups.py            — VaR, V^2
+    corrector.py         — Corrector Protocol + apply_corrector()
+    llm_corrector.py     — Qwen2.5-7B локально (llama-cpp-python)
+    vlm_corrector.py     — Qwen3.8 Max через OpenCode API (Anthropic)
+  markdown/
+    generator.py         — Markdown + валидация LaTeX
+  latex/
+    tex2html.py          — .tex → .html + MathJax
+```
+
+### Модели (локально, ~4 GB)
+
+```
+~/.paddlex/official_models/          (PaddleOCR, ~2.5 GB)
+  PP-DocLayout_plus-L                layout detection
+  PP-OCRv5_server_det                text detection
+  eslav_PP-OCRv5_mobile_rec          RU/EN recognition
+  PP-OCRv5_server_rec                EN/CN recognition
+  SLANeXt_wired                      table structure
+  PP-FormulaNet_plus-L               formula recognition (728 MB)
+
+~/.cache/llama_models/               (LLM, ~4.4 GB)
+  Qwen2.5-7B-Instruct-Q4_K_M.gguf    локальный корректор
+
+HF Hub (Surya 2, ~1.5 GB)
+  datalab-to/surya-ocr-2-gguf        650M VLM
+```
+
+---
+
+## Сравнение движков
+
+| Параметр | PaddleOCR (PP-StructV3) | Surya 2 |
+|----------|:---:|:---:|
+| Архитектура | Ансамбль 5 моделей | Один VLM (650M) |
+| Русский текст | ~85% | 95%+ |
+| Формулы | PP-FormulaNet (отлично) | VLM (отлично) |
+| Таблицы | PP-TableMagic + bbox | HTML `<table>` |
+| Inline-формулы | Не детектируются | `<math>` тэги |
+| Скорость CPU | ~140s | ~430s |
+| Размер моделей | ~2.5 GB | ~1.5 GB |
+| LLM-коррекция | Нужна для русского | Не нужна |
+| VLM-коррекция | Нужна для сложных мест | Не нужна |
+
+---
+
+## Ключевые цифры
+
+| Этап | PaddleOCR | Surya 2 |
+|------|:---:|:---:|
+| Image split + post-crop | 1-2s | 1-2s |
+| OCR | 140s | 430s |
+| LLM-корректор (Qwen2.5-7B) | ~20s/блок | не нужен |
+| VLM-корректор (Qwen3.8 Max) | ~10s/блок | не нужен |
+| Markdown генерация | <1s | <1s |
+| **Итого на страницу** | ~5 min | ~7 min |
+
+---
+
+## Неиспользованные подходы
+
+1. **EasyOCR** — WER 0.12 vs Paddle 0.056, хуже по метрикам
+2. **Tesseract** — нет поддержки GPU, хуже качество на русском
+3. **RapidOCR** — легче, но качество ниже PaddleOCR
+4. **OmniParser** — избыточен (YOLO + OCR), медленнее
+5. **Docling** — не поддерживает PaddleOCR как OCR-backend
+6. **Fine-tune модели** — требует GPU + размеченный датасет, не пробовали
+
+---
+
+## Выводы
+
+1. **PaddleOCR PP-StructureV3** — надёжный выбор для структуры документа и формул. Русский текст требует коррекции (LLM или VLM).
+
+2. **Surya 2** — лучший русский OCR из коробки, авто inline-формулы. Медленнее на CPU, но качество несравнимо выше.
+
+3. **Гибрид Surya 2 + PP-FormulaNet** — теоретически лучший вариант (Surya для текста, Paddle для формул), не реализован.
+
+4. **LLM/VLM коррекция** — эффективна для PaddleOCR, не нужна для Surya 2.
+
+5. **OpenCode Go API** — практичный способ подключить мощную VLM без локального GPU.

tests/test_markdown.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from src.markdown.generator import (
+    _validate_dollar_signs,
+    _validate_latex_braces,
+    _validate_left_right,
+    generate_markdown,
+    validate_markdown,
+)
+from src.ocr.paddle_engine import ParsedBlock
+
+
+class TestValidateBraces:
+    def test_balanced(self) -> None:
+        assert _validate_latex_braces(r"a{b}c") == []
+
+    def test_unbalanced_open(self) -> None:
+        warnings = _validate_latex_braces(r"a{b")
+        assert len(warnings) > 0
+
+    def test_unbalanced_close(self) -> None:
+        warnings = _validate_latex_braces(r"a}b")
+        assert len(warnings) > 0
+
+    def test_nested_balanced(self) -> None:
+        assert _validate_latex_braces(r"{a{b}c}") == []
+
+    def test_complex_formula(self) -> None:
+        assert _validate_latex_braces(r"\frac{a}{b}") == []
+
+
+class TestValidateDollar:
+    def test_balanced_inline(self) -> None:
+        assert _validate_dollar_signs("$a + b$") == []
+
+    def test_balanced_display(self) -> None:
+        assert _validate_dollar_signs(r"$$a + b$$") == []
+
+    def test_unbalanced_inline(self) -> None:
+        warnings = _validate_dollar_signs("$a + b")
+        assert len(warnings) > 0
+
+    def test_balanced_multiple(self) -> None:
+        assert _validate_dollar_signs("$x$ and $y$") == []
+
+    def test_unbalanced_multiple(self) -> None:
+        warnings = _validate_dollar_signs("$x and $y$")
+        assert len(warnings) > 0
+
+
+class TestValidateLeftRight:
+    def test_balanced(self) -> None:
+        assert _validate_left_right(r"\left( x \right)") == []
+
+    def test_unbalanced(self) -> None:
+        warnings = _validate_left_right(r"\left( x")
+        assert len(warnings) > 0
+
+
+class TestValidateMarkdown:
+    def test_valid(self) -> None:
+        assert validate_markdown("text\n\n$$\na + b\n$$\n") == []
+
+    def test_unbalanced_dollar(self) -> None:
+        warnings = validate_markdown("$$\n$a\n$$\n")
+        assert len(warnings) > 0
+
+    def test_unbalanced_brace_in_formula(self) -> None:
+        warnings = validate_markdown("$$\na{\nb\n$$\n")
+        assert len(warnings) > 0
+
+
+class TestGenerateMarkdown:
+    def test_text_block(self) -> None:
+        import tempfile
+
+        blocks = [ParsedBlock(label="text", content="Hello world", bbox=(0, 0, 100, 20))]
+        with tempfile.TemporaryDirectory() as tmp:
+            p = generate_markdown(blocks, Path(tmp) / "output.md")
+            assert p.exists()
+            content = p.read_text()
+            assert "Hello world" in content
+
+    def test_formula_block(self) -> None:
+        import tempfile
+
+        blocks = [ParsedBlock(label="formula", content=r"a + b = c", bbox=(0, 0, 100, 20))]
+        with tempfile.TemporaryDirectory() as tmp:
+            p = generate_markdown(blocks, Path(tmp) / "output.md")
+            content = p.read_text()
+            assert "$$\n" in content
+            assert "a + b = c" in content
+
+    def test_title_block(self) -> None:
+        import tempfile
+
+        blocks = [ParsedBlock(label="paragraph_title", content="Section 1", bbox=(0, 0, 100, 20))]
+        with tempfile.TemporaryDirectory() as tmp:
+            p = generate_markdown(blocks, Path(tmp) / "output.md")
+            content = p.read_text()
+            assert "## Section 1" in content
+
+    def test_no_escaped_latex(self) -> None:
+        import tempfile
+
+        blocks = [ParsedBlock(label="text", content=r"alpha \sim", bbox=(0, 0, 100, 20))]
+        with tempfile.TemporaryDirectory() as tmp:
+            p = generate_markdown(blocks, Path(tmp) / "output.md")
+            content = p.read_text()
+            assert r"\textbackslash" not in content
+            assert r"alpha" in content