pipeline optimization, new parameters (see README.md)

.env.dist

@@ -4,3 +4,7 @@ OPENCODE_API_KEY=sk-...
 # HuggingFace — токен для скачивания моделей (Surya 2, Qwen GGUF)
 # Получить: https://huggingface.co/settings/tokens (read-only)
 HF_TOKEN=hf_...
+
+# Debug-лог OCR (необязательно). Путь к файлу для записи всех событий.
+# Если не задан — только консольный вывод.
+# OCR_LOG_FILE=image_ocr.log

README.md

@@ -31,11 +31,13 @@ src/image_split.py          ← Stage 1: разрезание
 JPEG страницы
     │
     ▼
-src/image_to_latex.py       ← Stage 2: OCR + Markdown
+src/image_ocr.py           ← Stage 2: OCR + Markdown (бывший image_to_latex.py)
     │ --ocr-engine paddle|surya
     │ --input file.jpg         (одна страница)
     │ --input pages/           (пакетный режим: все изображения в каталоге)
-    │ --llm, --vlm (optional)
+    │ --llm, --vlm, --force-ocr
+    │ --pause 5 (по умолчанию)
+    │ --result-one-document    (по умолчанию ON, объединить в один .md)
     │
     ├─ PP-StructureV3 / Surya 2    (OCR)
     ├─ fixups                      (VaR, V^2)
@@ -68,7 +70,7 @@ 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`
+### Stage 2: `src/image_ocr.py`
 
 | Параметр | Описание | По умолчанию |
 |----------|----------|:---:|
@@ -78,20 +80,37 @@ python -m src.image_split -i scan.jpg --slice-auto
 | `--ocr-engine` | `paddle` или `surya` | `paddle` |
 | `--llm` | Локальный LLM-корректор (Qwen2.5-7B) | OFF |
 | `--vlm` | Vision LM корректор (Qwen3.8 Max, API) | OFF |
+| `--force-ocr` | Перераспознать даже при наличии `.json` | OFF |
+| `--pause` | Пауза между изображениями (сек) | 5 |
+| `--result-one-document` | Объединить `.md` в один документ | ON |
+| `--no-result-one-document` | Не объединять | — |
 
 Пример:
 ```bash
 # Одна страница
-python -m src.image_to_latex -i page.jpg
+python -m src.image_ocr -i page.jpg
 
-# Пакетный режим — все изображения в каталоге (Surya: batch-оптимизация)
+# Пакетный режим — все изображения в каталоге
+python -m src.image_ocr -i ./pages/ --ocr-engine surya
 
-python -m src.image_to_latex -i ./pages/ --ocr-engine surya
+# Принудительное перераспознавание
+python -m src.image_ocr -i ./pages/ --force-ocr
 
-# Пакетный режим (PaddleOCR: последовательно)
-python -m src.image_to_latex -i ./pages/ --ocr-engine paddle
+# Без объединения в один документ
+python -m src.image_ocr -i ./pages/ --no-result-one-document
 ```
 
+### Debug-лог
+
+Для отладки зависаний и падений — файл с полным логом всех этапов обработки.
+В `.env` добавить:
+
+```
+OCR_LOG_FILE=image_ocr.log
+```
+
+Формат вывода: `ЧЧ:ММ:СС [LEVEL] сообщение`. Файл пишется рядом со скриптом или по указанному пути. Уровень DEBUG показывает: начало/конец OCR, сохранение JSON/MD, вызов корректоров.
+
 ### Переменные окружения (`.env`)
 
 Скопируй шаблон и заполни своими ключами:
@@ -105,6 +124,7 @@ cp .env.dist .env
 |-----------|-----------|-----------|
 | `OPENCODE_API_KEY` | VLM-корректор через OpenCode Go | [opencode.ai/auth](https://opencode.ai/auth) → скопировать ключ |
 | `HF_TOKEN` | Скачивание моделей с HuggingFace (Surya 2) | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) (read-only) |
+| `OCR_LOG_FILE` | Путь к debug-логу (необязательно) | Например: `image_ocr.log` |
 
 `.env` уже добавлен в `.gitignore` — не коммитится.
 
@@ -112,7 +132,7 @@ cp .env.dist .env
 
 ## Результат
 
-CLI (`image_to_latex.py`) генерирует два файла для каждого изображения:
+CLI (`image_ocr.py`) генерирует два файла для каждого изображения:
 
 | Файл | Формат | Описание |
 |------|--------|----------|
@@ -220,7 +240,7 @@ llama-server не указывает количество потоков — п
 ```
 src/
   image_split.py         — CLI Stage 1
-  image_to_latex.py      — CLI Stage 2
+  image_ocr.py          — CLI Stage 2 (бывший image_to_latex.py)
   split/slicer.py        — разрезание, post-crop
   ocr/
     paddle_engine.py     — PP-StructureV3
@@ -233,6 +253,8 @@ src/
   markdown/generator.py  — Markdown + валидация
   latex/
     surya2html.py        — Surya JSON → HTML
+    surya2latex.py       — Surya JSON → LaTeX
+    json_to_latex.py     — Единый JSON→LaTeX (Paddle + Surya)
     tex2html.py           — TeX → HTML
 ```
 

installation.md

@@ -2,129 +2,94 @@
 
 ## Системные требования
 
-- **OS:** Linux (x86_64)
-- **CPU:** 8+ ядер (рекомендуется)
-- **RAM:** 16+ GB (32 GB для LLM-корректора)
-- **Диск:** 10+ GB свободного места
+- **OS:** Linux x86_64
+- **CPU:** 8+ ядер (i7-1165G7 или лучше)
+- **RAM:** 16+ GB (32 GB с LLM-корректором)
+- **Диск:** 15+ GB свободного места
 
 ---
 
-## Шаг 1: Python 3.12 + venv
+## Шаг 1: Python 3.12 + venv + все зависимости
 
 ```bash
-python3 -m venv .venv
+python3.12 -m venv .venv
 source .venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
 ```
 
+**Важно:** PaddlePaddle — версия **3.2.2** (3.3.1 содержит баг PIR/ONEDNN на CPU).
+
 ---
 
-## Шаг 2: Stage 1 — разрезание изображений
+## Шаг 2: llama-server (для Surya 2 на CPU)
 
-```bash
-pip install opencv-python-headless typer
-```
+Surya 2 использует llama.cpp сервер. Нужен бинарник `llama-server`:
 
-Зависимости: `opencv-python-headless`, `numpy`, `typer`, `ruff` (dev).
-
-Проверка:
 ```bash
-python -m src.image_split --help
-```
-
----
-
-## Шаг 3: Stage 2 — OCR (PaddleOCR)
+mkdir -p ~/.local/bin
 
-```bash
-pip install paddlepaddle==3.2.2
-pip install paddleocr pyyaml
-```
+# Скачать последний релиз (URL обновить из https://github.com/ggml-org/llama.cpp/releases/latest)
+curl -L "https://github.com/ggml-org/llama.cpp/releases/download/b10268/llama-b10268-bin-ubuntu-x64.tar.gz" \
+  -o /tmp/llama.tar.gz
 
-Модели загружаются автоматически при первом запуске в `~/.paddlex/official_models/` (~2.5 GB).
+tar -xzf /tmp/llama.tar.gz -C /tmp/
+cp /tmp/llama-b10268/llama-server /tmp/llama-b10268/lib*.so* ~/.local/bin/
 
-Проверка:
-```bash
-python -m src.image_to_latex --help
+export PATH="$HOME/.local/bin:$PATH"
+llama-server --version  # проверка
 ```
 
 ---
 
-## Шаг 4 (опционально): LLM-корректор (Qwen2.5-7B)
+## Шаг 3: Конфигурация (.env)
 
 ```bash
-pip install llama-cpp-python
+cp .env.dist .env
+# Отредактировать .env — вставить токены
 ```
 
-Модель загружается из 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
-```
+| Переменная | Назначение |
+|-----------|-----------|
+| `OPENCODE_API_KEY` | API-ключ OpenCode Go для VLM-корректора |
+| `HF_TOKEN` | HuggingFace токен (read-only) для скачивания моделей |
+| `OCR_LOG_FILE` | Путь к debug-логу (необязательно) |
 
 ---
 
-## Шаг 5 (опционально): VLM-корректор (Qwen3.8 Max)
+## Шаг 4: Модели (загружаются автоматически при первом запуске)
 
-Требуется подписка OpenCode Go. Токен записать в `.env`:
+При первом запуске скрипты скачают нужные модели. Для ускорения можно предварительно задать `HF_TOKEN` в `.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
-```
+| Движок | Модели | Размер | Куда |
+|--------|--------|:---:|------|
+| PaddleOCR | PP-StructureV3 (ансамбль) | ~2.5 GB | `~/.paddlex/official_models/` |
+| Surya 2 | surya-2.gguf + mmproj | ~1.5 GB | HF Hub (кеш) |
+| LLM | Qwen2.5-7B-Q4_K_M.gguf | ~4.4 GB | `~/.cache/llama_models/` |
 
 ---
 
-## Шаг 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"
+# Stage 1
+python -m src.image_split --help
 
-# Установка пакетов (в основном 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
-```
+# Stage 2 — PaddleOCR
+python -m src.image_ocr -i test.jpg
 
-Использование:
-```bash
-python -m src.image_to_latex -i page.jpg --ocr-engine surya
+# Stage 2 — Surya
+python -m src.image_ocr -i test.jpg --ocr-engine surya
+
+# Stage 2 — с LLM-корректором
+python -m src.image_ocr -i test.jpg --llm
 ```
 
 ---
 
-## Шаг 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)
-```

requirements.txt

@@ -0,0 +1,118 @@
+aiohappyeyeballs==2.7.1
+aiohttp==3.14.3
+aiosignal==1.4.0
+aistudio_sdk==0.3.9
+annotated-doc==0.0.5
+annotated-types==0.8.0
+anyio==4.14.2
+attrs==26.1.0
+bce-python-sdk==0.9.76
+beautifulsoup4==4.15.0
+cachetools==7.1.7
+certifi==2026.7.22
+chardet==7.4.3
+charset-normalizer==3.4.9
+click==8.4.2
+colorlog==6.12.0
+crc32c==2.8
+cssselect==1.5.0
+cssutils==2.15.0
+diskcache==5.6.3
+distro==1.9.0
+docling==2.117.0
+einops==0.8.2
+encutils==1.0.0
+et_xmlfile==2.0.0
+filelock==3.32.2
+filetype==1.2.0
+frozenlist==1.8.0
+fsspec==2026.7.0
+ftfy==6.3.1
+future==1.0.0
+h11==0.16.0
+hf-xet==1.5.2
+httpcore==1.0.9
+httpx==0.28.1
+huggingface_hub==1.26.0
+idna==3.18
+imagesize==2.0.0
+iniconfig==2.3.0
+Jinja2==3.1.6
+jiter==0.16.0
+joblib==1.5.3
+latex2mathml==3.81.0
+llama_cpp_python==0.3.34
+lxml==6.1.1
+markdown-it-py==4.2.0
+MarkupSafe==3.0.3
+mdurl==0.1.2
+modelscope==1.39.0
+modelscope-hub==0.2.0
+more-itertools==11.1.0
+mpmath==1.3.0
+multidict==6.7.1
+narwhals==2.24.0
+networkx==3.6.1
+numpy==2.3.5
+openai==2.53.0
+opencv-contrib-python==4.10.0.84
+opencv-python-headless==4.11.0.86
+openpyxl==3.1.5
+opt-einsum==3.3.0
+packaging==26.2
+paddleocr==3.7.0
+paddlepaddle==3.2.2
+paddlex==3.7.2
+pandas==3.0.5
+pdftext==0.7.1
+pillow==10.4.0
+platformdirs==4.11.0
+pluggy==1.6.0
+premailer==3.10.0
+prettytable==3.18.0
+propcache==0.5.2
+protobuf==7.35.1
+psutil==7.2.2
+py-cpuinfo==9.0.0
+pyclipper==1.4.0
+pycryptodome==3.23.0
+pydantic==2.13.4
+pydantic-settings==2.14.2
+pydantic_core==2.46.4
+Pygments==2.20.0
+pypdfium2==5.10.1
+pytest==9.1.1
+python-bidi==0.6.11
+python-dateutil==2.9.0.post0
+python-dotenv==1.2.2
+PyYAML==6.0.2
+regex==2026.7.19
+requests==2.34.2
+rich==15.0.0
+ruamel.yaml==0.19.1
+ruff==0.16.1
+safetensors==0.8.0
+scikit-learn==1.9.0
+scipy==1.18.0
+sentencepiece==0.2.2
+setuptools==83.0.0
+shapely==2.1.2
+shellingham==1.5.4
+six==1.17.0
+sniffio==1.3.1
+soupsieve==2.9.1
+surya-ocr==0.22.1
+sympy==1.14.0
+threadpoolctl==3.6.0
+tiktoken==0.13.0
+tokenizers==0.22.2
+torch==2.13.0+cpu
+tqdm==4.70.0
+transformers==5.14.1
+typer==0.27.0
+typing-inspection==0.4.2
+typing_extensions==4.16.0
+ujson==5.13.0
+urllib3==2.7.0
+wcwidth==0.8.2
+yarl==1.24.5

src/image_ocr.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import functools
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from src.cli_utils import run_main
+from src.env import load_env
+from src.markdown.generator import generate_markdown
+from src.ocr.paddle_engine import ocr_image
+from src.postprocess.fixups import fix_ocr_errors
+
+load_env()
+
+# Подавление китайских иероглифов и ANSI-кодов из PaddleOCR/paddlex
+os.environ.setdefault("PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK", "True")
+os.environ.setdefault("DISABLE_PROGRESS_BAR", "True")
+os.environ.setdefault("PADDLESEG_NO_PROGRESS", "1")
+os.environ.setdefault("LOG_LEVEL", "2")  # WARNING для Paddle внутренных логов
+
+# Приглушаем шумные библиотеки
+for _mod in ("paddle", "paddlex", "paddleocr", "modelscope", "huggingface_hub", "urllib3"):
+    logging.getLogger(_mod).setLevel(logging.WARNING)
+
+# Настройка логирования
+_log_format = logging.Formatter("%(asctime)s [%(levelname)-5s] %(message)s", datefmt="%H:%M:%S")
+_console = logging.StreamHandler()
+_console.setFormatter(_log_format)
+_root = logging.getLogger()
+_root.handlers.clear()
+_root.setLevel(logging.INFO)
+_root.addHandler(_console)
+
+_log_file = os.environ.get("OCR_LOG_FILE", "")
+if _log_file:
+    _fh = logging.FileHandler(_log_file, encoding="utf-8")
+    _fh.setLevel(logging.DEBUG)
+    _fh.setFormatter(_log_format)
+    _root.addHandler(_fh)
+
+logger = logging.getLogger(__name__)
+app = typer.Typer(add_completion=False, no_args_is_help=True)
+
+MD_EXTENSION: str = ".md"
+DEFAULT_LANG: str = "en"
+IMG_EXTENSIONS: set[str] = {".jpg", ".jpeg", ".png", ".tiff", ".tif"}
+
+
+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"
+
+
+def _merge_markdown_files(output_dir: Path, md_files: list[Path]) -> None:
+    merged_parts: list[str] = []
+    for md_path in sorted(md_files):
+        content = md_path.read_text(encoding="utf-8")
+        merged_parts.append(f"<!-- page: {md_path.stem} -->\n\n{content}")
+    if merged_parts:
+        merged = "# Merged document\n\n" + "\n\n---\n\n".join(merged_parts)
+        merged_path = output_dir / (output_dir.name + MD_EXTENSION)
+        merged_path.write_text(merged, encoding="utf-8")
+        logger.info("Объединённый документ: %s", merged_path)
+
+
+def _process_single(
+    ocr_fn, input_path: Path, lang: str,
+    output_dir_resolved: Path, use_llm: bool, use_vlm: bool,
+) -> None:
+    """Обрабатывает одно изображение: OCR → fixups → корректоры → JSON + Markdown."""
+    # Этап OCR — самое долгое и хрупкое место
+    logger.debug("OCR: начало %s", input_path.name)
+    t0 = time.time()
+    page = ocr_fn(str(input_path))
+    dt = time.time() - t0
+    logger.info("Распознано %d блоков за %.1fs", len(page.blocks), dt)
+    logger.debug("OCR: завершено %s (блоков: %d)", input_path.name, len(page.blocks))
+
+    # Исправление типичных OCR-ошибок (VaR, V^2)
+    fix_ocr_errors(page.blocks)
+    logger.debug("Fixups: завершено")
+
+    # Опциональная коррекция через VLM / локальный LLM
+    if use_vlm or use_llm:
+        from src.postprocess.corrector import apply_corrector
+        logger.debug("Корректоры: инициализация")
+
+    if use_vlm:
+        from src.postprocess.vlm_corrector import vlm_correct_block
+        corrector = functools.partial(vlm_correct_block, image_path=str(input_path.resolve()))
+        apply_corrector(page.blocks, corrector, "VLM")
+        logger.debug("VLM: завершено")
+
+    if use_llm:
+        from src.postprocess.llm_corrector import llm_correct_block
+        apply_corrector(page.blocks, llm_correct_block, "LLM")
+        logger.debug("LLM: завершено")
+
+    # Сохранение JSON (всегда) + Markdown (всегда)
+    json_path = output_dir_resolved / (input_path.stem + ".json")
+    if not json_path.exists():
+        # Если raw_json пуст (Surya), строим из ParsedBlock
+        json_payload = page.raw_json or {
+            "blocks": [{"label": b.label, "content": b.content, "bbox": list(b.bbox)}
+                       for b in page.blocks]
+        }
+        json_path.write_text(json.dumps(json_payload, ensure_ascii=False, indent=2), encoding="utf-8")
+        logger.debug("JSON сохранён: %s", json_path)
+
+    md_path = output_dir_resolved / (input_path.stem + MD_EXTENSION)
+    generate_markdown(page.blocks, md_path)
+    logger.debug("Markdown сохранён: %s", md_path)
+    logger.info("%s → %s, %s", input_path.name, md_path.name, json_path.name)
+
+
+@app.command()
+def image_to_latex(
+    input: Annotated[
+        Path,
+        typer.Option(
+            "--input",
+            "-i",
+            exists=True,
+            file_okay=True,
+            dir_okay=True,
+            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="Каталог для сохранения результатов (по умолчанию — рядом с входным файлом)",
+        ),
+    ] = 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,
+    result_one_document: Annotated[
+        bool,
+        typer.Option(
+            "--result-one-document / --no-result-one-document",
+            help="Объединить все .md результаты в один многостраничный документ (по умолчанию — да)",
+        ),
+    ] = True,
+    force_ocr: Annotated[
+        bool,
+        typer.Option(
+            "--force-ocr",
+            help="Принудительно перераспознать все изображения, игнорируя уже существующие .json",
+        ),
+    ] = False,
+    pause: Annotated[
+        int,
+        typer.Option(
+            "--pause",
+            min=0,
+            max=600,
+            help="Пауза между изображениями в секундах (по умолчанию 5)",
+        ),
+    ] = 5,
+) -> None:
+    """OCR → PostProcess → Markdown. Принимает файл или каталог изображений."""
+    ocr_fn, engine_name = _get_ocr_engine(ocr_engine)
+
+    if input.is_dir():
+        image_paths = sorted(
+            p for p in input.iterdir()
+            if p.suffix.lower() in IMG_EXTENSIONS and p.is_file()
+        )
+        if not image_paths:
+            raise typer.BadParameter(f"Нет изображений в каталоге: {input}")
+
+        out = output_dir.resolve() if output_dir else input.resolve()
+        out.mkdir(parents=True, exist_ok=True)
+
+        skipped = 0
+        if not force_ocr:
+            filtered: list[Path] = []
+            for p in image_paths:
+                if (out / (p.stem + ".json")).exists():
+                    logger.info("Пропуск %s (уже есть .json)", p.name)
+                    skipped += 1
+                else:
+                    filtered.append(p)
+            image_paths = filtered
+
+        if not image_paths:
+            logger.info("Все изображения уже обработаны (пропущено %d)", skipped)
+            return
+
+        logger.info(
+            "Пакетная обработка %d изображений через %s (пропущено %d)",
+            len(image_paths), engine_name, skipped,
+        )
+
+        total_start = time.time()
+
+        for i, img_path in enumerate(image_paths):
+            logger.info("[%d/%d] %s...", i + 1 + skipped, len(image_paths) + skipped, img_path.name)
+            _process_single(ocr_fn, img_path, lang, out, use_llm, use_vlm)
+            if i < len(image_paths) - 1 and pause > 0:
+                time.sleep(pause)
+
+        total_dt = time.time() - total_start
+        processed = len(image_paths)
+        avg_dt = total_dt / processed if processed else 0
+
+        if result_one_document:
+            _merge_markdown_files(out, sorted(out.glob("*.md")))
+
+        logger.info(
+            "Готово: %d изображений, всего %.1fs, среднее %.1fs/изобр",
+            processed, total_dt, avg_dt,
+        )
+    else:
+        out = output_dir.resolve() if output_dir else input.resolve().parent
+        out.mkdir(parents=True, exist_ok=True)
+        _process_single(ocr_fn, input, lang, out, use_llm, use_vlm)
+
+
+def main() -> None:
+    run_main(app)
+
+
+if __name__ == "__main__":
+    main()

src/image_to_latex.py

@@ -1,166 +0,0 @@
-from __future__ import annotations
-
-import functools
-import json
-import logging
-import time
-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"
-IMG_EXTENSIONS: set[str] = {".jpg", ".jpeg", ".png", ".tiff", ".tif"}
-
-
-def _get_ocr_engine(name: str):
-    if name == "surya":
-        from src.ocr.surya_engine import surya_ocr_batch, surya_ocr_image
-
-        return surya_ocr_image, surya_ocr_batch, "Surya 2 VLM"
-    return ocr_image, None, "PP-StructureV3"
-
-
-def _process_single(
-    ocr_fn, input_path: Path, lang: str,
-    output_dir_resolved: Path, use_llm: bool, use_vlm: bool,
-) -> None:
-    t0 = time.time()
-    page = ocr_fn(str(input_path))
-    dt = time.time() - t0
-    logger.info("Распознано %d блоков за %.1fs", len(page.blocks), dt)
-
-    fix_ocr_errors(page.blocks)
-
-    if use_vlm or use_llm:
-        from src.postprocess.corrector import apply_corrector
-
-    if use_vlm:
-        from src.postprocess.vlm_corrector import vlm_correct_block
-
-        corrector = functools.partial(vlm_correct_block, image_path=str(input_path.resolve()))
-        apply_corrector(page.blocks, corrector, "VLM")
-
-    if use_llm:
-        from src.postprocess.llm_corrector import llm_correct_block
-
-        apply_corrector(page.blocks, llm_correct_block, "LLM")
-
-    output_name = input_path.stem + MD_EXTENSION
-    generate_markdown(page.blocks, output_dir_resolved / output_name)
-    logger.info("Markdown: %s", output_dir_resolved / output_name)
-
-    if page.raw_json:
-        json_path = output_dir_resolved / (input_path.stem + ".json")
-        json_path.write_text(json.dumps(page.raw_json, ensure_ascii=False, indent=2), encoding="utf-8")
-
-
-@app.command()
-def image_to_latex(
-    input: Annotated[
-        Path,
-        typer.Option(
-            "--input",
-            "-i",
-            exists=True,
-            file_okay=True,
-            dir_okay=True,
-            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="Каталог для сохранения результатов (по умолчанию — рядом с входным файлом)",
-        ),
-    ] = 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_fn, ocr_batch_fn, engine_name = _get_ocr_engine(ocr_engine)
-
-    if input.is_dir():
-        image_paths = sorted(
-            p for p in input.iterdir()
-            if p.suffix.lower() in IMG_EXTENSIONS and p.is_file()
-        )
-        if not image_paths:
-            raise typer.BadParameter(f"Нет изображений в каталоге: {input}")
-
-        out = output_dir.resolve() if output_dir else input.resolve()
-        logger.info("Пакетная обработка %d изображений через %s", len(image_paths), engine_name)
-
-        total_start = time.time()
-
-        if ocr_batch_fn and ocr_engine == "surya":
-            results = ocr_batch_fn([str(p) for p in image_paths])
-            for img_path, page in zip(image_paths, results):
-                logger.info("%s: %d блоков", img_path.name, len(page.blocks))
-                fix_ocr_errors(page.blocks)
-                generate_markdown(page.blocks, out / (img_path.stem + MD_EXTENSION))
-        else:
-            for img_path in image_paths:
-                logger.info("%s...", img_path.name)
-                _process_single(ocr_fn, img_path, lang, out, use_llm, use_vlm)
-
-        total_dt = time.time() - total_start
-        avg_dt = total_dt / len(image_paths)
-        logger.info(
-            "Готово: %d изображений, всего %.1fs, среднее %.1fs/изобр",
-            len(image_paths), total_dt, avg_dt,
-        )
-    else:
-        out = output_dir.resolve() if output_dir else input.resolve().parent
-        _process_single(ocr_fn, input, lang, out, use_llm, use_vlm)
-
-
-def main() -> None:
-    run_main(app)
-
-
-if __name__ == "__main__":
-    main()

src/latex/json_to_latex.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from bs4 import BeautifulSoup
+
+LATEX_PREAMBLE = r"""\documentclass[12pt,a4paper]{article}
+\usepackage[T2A]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage[russian,english]{babel}
+\usepackage{amsmath,amssymb}
+\usepackage{geometry}
+\usepackage{booktabs}
+\geometry{margin=2cm}
+\begin{document}
+"""
+
+
+def _detect_format(data: dict) -> str:
+    if "blocks" in data and isinstance(data["blocks"], list):
+        first = data["blocks"][0] if data["blocks"] else {}
+        if "html" in first:
+            return "surya"
+    if "parsing_res_list" in data:
+        return "paddle"
+    raise ValueError("Неизвестный формат JSON: ожидается PaddleOCR или Surya")
+
+
+def _escape(text: str) -> str:
+    for char, repl in [("\\", "\\textbackslash{}"), ("&", "\\&"), ("%", "\\%"),
+                       ("$", "\\$"), ("#", "\\#"), ("_", "\\_"),
+                       ("{", "\\{"), ("}", "\\}"), ("~", "\\textasciitilde{}"),
+                       ("^", "\\^{}"), ("<", "\\textless{}"), (">", "\\textgreater{}")]:
+        text = text.replace(char, repl)
+    return text
+
+
+def _paddle_to_body(data: dict) -> str:
+    lines: list[str] = []
+    for item in data.get("parsing_res_list", []):
+        content = item.get("block_content", "").strip()
+        if not content:
+            continue
+        label = item.get("block_label", "text")
+
+        if label == "formula":
+            lines.append(f"\\[\n{content}\n\\]\n")
+        elif label in ("paragraph_title", "title", "section_header"):
+            lines.append(f"\\section*{{{_escape(content)}}}")
+        elif label == "text":
+            lines.append(f"\n{_escape(content)}\n")
+        else:
+            lines.append(f"\n{_escape(content)}\n")
+    return "\n".join(lines)
+
+
+def _surya_to_body(data: dict) -> str:
+    lines: list[str] = []
+    for b in data.get("blocks", []):
+        label = b.get("label", "")
+        html = b.get("html", "").strip()
+        if not html:
+            continue
+
+        if label == "Equation":
+            clean = html.replace('<math display="block">', "").replace("</math>", "").strip()
+            lines.append(f"\\[\n{clean}\n\\]\n")
+            continue
+
+        soup = BeautifulSoup(html, "html.parser")
+
+        if soup.find("table"):
+            lines.append(_table_to_latex(soup))
+            lines.append("")
+            continue
+
+        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 = soup.get_text("\n").strip()
+        if not text:
+            continue
+
+        if label in ("SectionHeader",):
+            lines.append(f"\\section*{{{text}}}")
+        elif label == "PageHeader":
+            lines.append(f"{text}")
+        else:
+            lines.append(f"\n{text}\n")
+    return "\n".join(lines)
+
+
+def _table_to_latex(soup: BeautifulSoup) -> str:
+    rows = soup.find_all("tr")
+    if not rows:
+        return ""
+    ncols = max(len(row.find_all(["td", "th"])) for row in rows)
+    lines = [f"\\begin{{tabular}}{{|{'c|' * ncols}}}", "\\hline"]
+    for row in rows:
+        cells = [cell.get_text().strip() for cell in row.find_all(["td", "th"])]
+        lines.append(" & ".join(cells) + " \\\\")
+        lines.append("\\hline")
+    lines.append("\\end{tabular}")
+    return "\n".join(lines)
+
+
+def json_to_latex(json_path: str | Path) -> str:
+    data = json.loads(Path(json_path).read_text())
+    fmt = _detect_format(data)
+
+    if fmt == "paddle":
+        body = _paddle_to_body(data)
+    else:
+        body = _surya_to_body(data)
+
+    return LATEX_PREAMBLE + body + "\n\\end{document}\n"
+
+
+def multi_json_to_latex(json_dir: str | Path, output_path: str | Path | None = None) -> str:
+    json_dir = Path(json_dir)
+    pages: list[str] = []
+    for jp in sorted(json_dir.glob("[!.]*.json")):
+        if jp.stem == json_dir.name:
+            continue
+        try:
+            body = json_to_latex(jp)
+            start = body.find("\\begin{document}") + len("\\begin{document}")
+            end = body.find("\\end{document}")
+            pages.append(f"% {jp.stem}\n{body[start:end].strip()}\n\\newpage")
+        except (json.JSONDecodeError, KeyError, ValueError):
+            continue
+
+    if not pages:
+        return ""
+
+    first_path = min(json_dir.glob("[!.]*.json"), key=lambda p: p.stem)
+    first = json_to_latex(first_path)
+    preamble_end = first.find("\\begin{document}") + len("\\begin{document}")
+    full = first[:preamble_end] + "\n" + "\n".join(pages) + "\n\\end{document}\n"
+
+    if output_path:
+        Path(output_path).write_text(full, encoding="utf-8")
+    return full

src/ocr/surya_engine.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import logging
 import os
 import shutil
-from collections.abc import Sequence
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -47,7 +46,7 @@ class SuryaEngine:
       - llama-server kept alive between calls (SURYA_INFERENCE_KEEP_ALIVE=true)
       - reduced context per slot (8192 vs 12288) saves memory
       - single parallel slot (no batch needed for single page)
-      - image pre-scaled to 1056px wide (≈96 DPI) 
+      - image pre-scaled to 1056px wide (≈96 DPI)
       - explicit thread count matching CPU cores
     """
 
@@ -71,12 +70,19 @@ class SuryaEngine:
         image = Image.open(image_path)
         return self._process_image(image)
 
-    def process_batch(self, image_paths: Sequence[str]) -> list[OcrPageResult]:
-        from PIL import Image
+    def _health_check(self) -> bool:
+        import requests
 
-        images = [_pre_scale(Image.open(p)) for p in image_paths]
-        results = self._predictor(images)
-        return [self._to_result(page, img) for page, img in zip(results, images)]
+        port = os.environ.get("SURYA_INFERENCE_PORT", "")
+        host = os.environ.get("SURYA_INFERENCE_HOST", "127.0.0.1")
+        if not port:
+            return True
+        try:
+            r = requests.get(f"http://{host}:{port}/health", timeout=10)
+            return r.status_code == 200
+        except requests.RequestException:
+            logger.warning("llama-server health check failed")
+            return False
 
     def _process_image(self, image: PILImage.Image) -> OcrPageResult:
         scaled = _pre_scale(image)
@@ -124,11 +130,15 @@ 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)
 
+    if not _surya_engine._health_check():
+        logger.warning("llama-server не отвечает, перезапуск...")
+        _surya_engine = SuryaEngine()  # пересоздать — заново spawn сервер
+        if not _surya_engine._health_check():
+            raise RuntimeError(
+                "llama-server недоступен после перезапуска. "
+                "Проверьте: `ps aux | grep llama-server`. "
+                "Попробуйте: `llama-server --version`"
+            )
 
-def surya_ocr_batch(image_paths: Sequence[str]) -> list[OcrPageResult]:
-    global _surya_engine
-    if _surya_engine is None:
-        _surya_engine = SuryaEngine()
-    return _surya_engine.process_batch(image_paths)
+    return _surya_engine.process(image_path)

src/postprocess/llm_corrector.py

@@ -37,8 +37,8 @@ class LlmCorrector:
 _llm_corrector: LlmCorrector | None = None
 
 
-def llm_correct_block(block: ParsedBlock) -> ParsedBlock:
+def llm_correct_block(block: ParsedBlock) -> None:
     global _llm_corrector
     if _llm_corrector is None:
         _llm_corrector = LlmCorrector()
-    return _llm_corrector(block)
+    _llm_corrector(block)

src/postprocess/vlm_corrector.py

@@ -39,16 +39,16 @@ def _image_to_base64(image: Any) -> str:
     return base64.b64encode(buffer).decode("utf-8")
 
 
-def vlm_correct_block(block: ParsedBlock, image_path: str, model: str = DEFAULT_MODEL) -> ParsedBlock:
+def vlm_correct_block(block: ParsedBlock, image_path: str, model: str = DEFAULT_MODEL) -> None:
     if block.label == "formula":
-        return block
+        return
     if not _get_api_key():
         logger.warning("VLM: %s не задан, пропускаем", API_KEY_ENV)
-        return block
+        return
 
     image = cv2.imread(image_path)
     if image is None:
-        return block
+        return
 
     h, w = image.shape[:2]
     x1, y1, x2, y2 = block.bbox
@@ -57,7 +57,7 @@ def vlm_correct_block(block: ParsedBlock, image_path: str, model: str = DEFAULT_
     x2 = min(w, x2 + 5)
     y2 = min(h, y2 + 5)
     if x1 >= x2 or y1 >= y2:
-        return block
+        return
 
     crop = image[y1:y2, x1:x2]
     crop_h, crop_w = crop.shape[:2]
@@ -112,16 +112,16 @@ def vlm_correct_block(block: ParsedBlock, image_path: str, model: str = DEFAULT_
                 logger.info("VLM: результат (%d символов): %s", len(text), text[:120])
             else:
                 logger.info("VLM: пустой или короткий ответ (%d символов)", len(text) if text else 0)
-            return block
+            return
         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
+            return
         except (requests.RequestException, KeyError, IndexError) as e:
             logger.warning("VLM: ошибка — %s", e)
-            return block
+            return
 
-    return block
+    return

src/split/slicer.py

@@ -128,6 +128,9 @@ def is_empty(image: np.ndarray) -> bool:
 
 
 def _binarize(image: np.ndarray) -> np.ndarray:
+    """Бинаризация: серый → Гаусс-блюр → Otsu-порог → морф.закрытие.
+    При слишком низком пороге Otsu (<50) — адаптивный порог (Gaussian, окно 31).
+    Морфологическое закрытие (3×3) склеивает фрагменты букв в непрерывные регионы."""
     gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
     blurred = cv2.GaussianBlur(gray, (3, 3), 0)
     otsu_th, binary = cv2.threshold(
@@ -143,6 +146,9 @@ def _binarize(image: np.ndarray) -> np.ndarray:
 
 
 def detect_grid(image: np.ndarray) -> tuple[int, int]:
+    """Автоопределение сетки: бинаризация → проекция плотности → дилатация → подсчёт полос.
+    Дилатация (ядро = max(5, длина/40)) сливает строки текста в непрерывные блоки,
+    но не перекрывает межстраничные пробелы (они шире)."""
     binary = _binarize(image)
 
     cols = _count_bands(binary, axis=0)

stage2_results.md

@@ -20,21 +20,21 @@
 **Результат:** 22 структурированных блока с layout-разметкой.
 - Layout detection: ✅ `[number]`, `[formula]`, `[text]`, `[paragraph_title]`
 - Display-формулы: ✅ `\mathrm{C Rec}_{\mathrm{it}}=\sum...`
-- Таблицы: ✅ (PP-TableMagic)
-- Русский текст: ⚠️ ~85% (eslav_PP-OCRv5_mobile_rec — мобильная модель)
-- **Вывод:** структура отлично, текст — приемлемо
+- Таблицы: ✅ PP-TableMagic с bbox ячеек
+- Русский текст: ⚠️ ~85% (eslav_PP-OCRv5_mobile_rec)
+- **Вывод:** структура отлично, текст — терпимо
 
-### 3. Замена модели на cyrillic_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 не существует
+- PP-OCRv6: 52 латинских языка
+- **Вывод:** русский — только mobile-версии
 
 ### 5. Локальный LLM-корректор (Qwen2.5-7B GGUF)
 **Результат:** +25% читаемости текста.
@@ -46,172 +46,167 @@
 - **Вывод:** эффективен для пост-обработки
 
 ### 6. VLM-корректор (Qwen3.8 Max через OpenCode API)
-**Результат:** полное восстановление текста + автоопределение inline-формул.
+**Результат:** полное восстановление текста + авто inline-формулы.
 ```
 До:   ΣДсе, - дисконтированная сумма возвратов
-После: $\sum_t DCF_{i,t}$ — дисконтированная сумма возвратов, получаемых на t-ом периоде
+После: $\sum_t DCF_{i,t}$ — дисконтированная сумма возвратов
 ```
-- ~10s/блок, Anthropic API через `zen/go/v1/messages`
-- **Вывод:** лучшее качество, но требует API-доступа
+- ~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 → распознавание единой моделью
-- Теоретически решает проблему русского (языковая модель понимает контекст)
+### 8. PaddleOCR-VL (ERNIE-4.5-0.3B)
+**Результат:** модель загружена (1.79 GB), ~15 мин/стр на CPU.
+- Одна VLM вместо ансамбля
+- Теоретически решает проблему русского (LM понимает контекст)
 - **Вывод:** правильный подход при GPU, нереализуем на CPU
 
-### 9. Surya 2 (Datalab, 650M VLM)
-**Результат:** ⭐ лучший русский OCR из коробки.
+### 9. Surya 2 (Datalab, 650M VLM) ⭐
+**Результат:** лучший русский OCR из коробки — но медленно на CPU.
 - 95%+ точность русского текста без коррекции
-- Автоопределение inline-формул: `<math>MRec_{it}</math>`
-- ~430s/стр на CPU (vs 140s у PaddleOCR, но качество несравнимо)
-- Вывод Markdown с `$$...$$` формулами
-- **Вывод:** лучший выбор при достаточных ресурсах
+- Авто inline-формулы: `<math>MRec_{it}</math>` → `$MRec_{it}$`
+- ~300s/стр после CPU-оптимизаций (vs 140s PaddleOCR)
+- **Слабость:** таблицы требуют много токенов → таймауты на CPU
+- **Вывод:** лучший выбор по качеству, медленнее на CPU
+
+### 10. VLM full-page (Qwen3.8 Max) для таблиц
+**Результат:** 118s на страницу с таблицей, качество отличное.
+- Таблица → pipe-Markdown: `| col1 | col2 |`
+- Формулы → `$...$`
+- Структура заголовков сохранена
+- **Вывод:** для табличных страниц — лучший вариант
 
 ---
 
 ## Итоговая архитектура
 
 ```
-                        Входное изображение (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)
-      полный дамп)
+Входное изображение (JPEG/PNG/TIFF)
+    │
+    ▼
+src/image_split.py          ← Stage 1: разрезание
+    │ --slice / --slice-auto
+    │ --border, --post-crop
+    │
+    ▼
+src/image_ocr.py            ← Stage 2: OCR + Markdown
+    │ --ocr-engine paddle|surya
+    │ --llm, --vlm
+    │ --force-ocr, --pause
+    │ --result-one-document (ON по умолчанию)
+    │
+    ├─ PaddleEngine / SuryaEngine   (OCR)
+    ├─ fix_ocr_errors               (VaR, V^2)
+    ├─ LlmCorrector                 (Qwen2.5-7B, local)
+    ├─ VlmCorrector                 (Qwen3.8 Max, API)
+    │
+    ▼
+.md + .json (per page) + merged.md
 ```
 
+### По умолчанию включено
+
+| Функция | Статус |
+|---------|:------:|
+| `--resume` (пропуск JSON) | ON |
+| `--result-one-document` | ON |
+| `--pause 5` | ON |
+| `--post-crop` (Stage 1) | ON |
+
 ### Модули
 
 ```
 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
+  image_split.py         — CLI Stage 1
+  image_ocr.py           — CLI Stage 2
+  cli_utils.py           — run_main()
+  env.py                 — загрузка .env
+  split/slicer.py        — разрезание, post-crop, border
   ocr/
     paddle_engine.py     — PP-StructureV3 + кастом YAML (eslav)
-    surya_engine.py      — Surya 2 VLM + llama.cpp
+    surya_engine.py      — Surya 2 + CPU-оптимизации + health_check
   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
+    corrector.py         — Corrector Protocol
+    llm_corrector.py     — Qwen2.5-7B локально
+    vlm_corrector.py     — Qwen3.8 Max API (Anthropic)
+  markdown/generator.py  — Markdown + валидация LaTeX
   latex/
-    tex2html.py          — .tex → .html + MathJax
+    json_to_latex.py     — Единый JSON→LaTeX (Paddle + Surya)
+    surya2html.py        — Surya JSON → HTML + MathJax
+    tex2html.py          — TeX → HTML
 ```
 
-### Модели (локально, ~4 GB)
+---
+
+## Оптимизации Surya 2 для CPU
+
+| Параметр | До | После | Эффект |
+|----------|:---:|:---:|--------|
+| KEEP_ALIVE | off | on | -23s повторный старт |
+| CTX per slot | 12288 | 8192 | -30% RAM |
+| Parallel slots | 8 | 1 | -80% слотов |
+| Pre-scale | 2552px | 1056px | -60% пикселей |
+| Threads | default | `-t 8` | стабильно |
+| **Итого** | **430s** | **300s** | **-30%** |
 
+### Health-check + retry
 ```
-~/.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
+llama-server не отвечает → logger.warning → перезапуск SuryaEngine
+→ повторный health_check → OK / RuntimeError с инструкцией
 ```
 
 ---
 
 ## Сравнение движков
 
-| Параметр | 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 | VLM Qwen3.8 |
+|----------|:---:|:---:|:---:|
+| Архитектура | Ансамбль 5 моделей | Один VLM (650M) | Cloud VLM |
+| Русский текст | ~85% | 95%+ | 98%+ |
+| Формулы | PP-FormulaNet | VLM (отлично) | VLM (отлично) |
+| Таблицы | PP-TableMagic + bbox | ❌ CPU timeout | ✅ Pipe-Markdown |
+| Inline-формулы | Нет | `<math>` тэги | `$...$` |
+| Скорость CPU | ~140s | ~300s | ~120s (API) |
+| Офлайн | ✅ | ✅ | ❌ |
+| Размер моделей | ~2.5 GB | ~1.5 GB | 0 (cloud) |
 
 ---
 
-## Ключевые цифры
+## Ключевые цифры (на CPU: 8 ядер, 32 GB RAM)
 
-| Этап | 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 |
+| Этап | PaddleOCR | Surya 2 | VLM |
+|------|:---:|:---:|:---:|
+| OCR (одна страница) | 140s | 300s | 120s |
+| LLM-корректор | +5 min | не нужен | не нужен |
+| VLM-корректор | +10s/блок | не нужен | — |
+| JSON + MD сохранение | <1s | <1s | <1s |
+| Merge в один документ | <1s | <1s | <1s |
+| **Итого на страницу** | ~5 min | ~5 min | ~2 min |
+| **12 страниц (batch)** | ~28 min* | ~60 min | ~24 min |
+
+\* PaddleOCR с `--pause 5`
 
 ---
 
 ## Неиспользованные подходы
 
-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. **EasyOCR** — WER 0.12 vs Paddle 0.056
+2. **Tesseract** — нет GPU, хуже на русском
+3. **RapidOCR** — легче, качество ниже
+4. **Fine-tune eslav** — требует 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.
+1. **PP-StructureV3** — надёжен для структуры и формул, русский текст требует LLM/VLM коррекции
+2. **Surya 2** — лучший русский OCR из коробки, CPU-оптимизации дали -30% времени
+3. **VLM Qwen3.8 Max** — решает таблицы там, где Surya падает, при приемлемой скорости
+4. **Гибридный подход**: Surya для текста + VLM для таблиц = лучший баланс
+5. **LLM/VLM коррекция** эффективна для PaddleOCR, не нужна для Surya 2
+6. **CPU-ограничения** — основной фактор, GPU сделал бы Surya/PaddleOCR-VL идеальным выбором