.raw as non-changeable results of VLM processing, all postprocessing routines are moved to 3rd stagge generate_result; postprocessing upgraded

.gitignore

 .vscode/
 .DS_Store
 
+*.log

README.md

 JPEG/TIFF/PNG (многостраничный скан)
     │
     ▼
-src/image_prepare.py        ← Stage 1: подготовка (разрезание, обрезка)
+src/image_prepare.py        ← Stage 1: подготовка (разрезание, unwarp, denoise)
     │ --slice / --slice-auto
     │ --pre-rotate, --border
-    │ --post-crop
+    │ --unwarp, --denoise, --post-crop
     │
     ▼
-JPEG страницы
+JPEG/PNG страницы
     │
     ▼
-src/image_ocr.py           ← Stage 2: OCR + Markdown
-    │ --ocr-engine paddle|surya
-    │ --input file.jpg         (одна страница)
-    │ --input pages/           (пакетный режим: все изображения в каталоге)
-    │ --llm, --vlm, --force-ocr
-    │ --pause 5 (по умолчанию)
-    │ --result-one-document    (по умолчанию ON, объединить в один .md)
-    ├─ PP-StructureV3 / Surya 2    (OCR)
-    ├─ fixups                      (VaR, V^2)
-    ├─ VLM corrector               (Qwen3.8 Max, API)
+src/image_ocr.py           ← Stage 2: OCR → сырой ответ
+    │ --ocr-engine paddle|surya|external-qwen3
+    │ --main-lang ru|en
+    │ --fix-by-external-qwen3
     │
     ▼
-.md + .json + .html
+.raw (сырой ответ VLM, неизменяемый)
+    │
+    ▼
+src/generate_result.py     ← Stage 3: постпроцессинг
+    │ фильтрация номеров страниц
+    │ восстановление таблиц между страницами
+    │ очистка формул (\text, \_)
+    │
+    ▼
+.json + .md + объединённый .md + .tex + .html
 ```
 
 ---
 | `--input` / `-i` | Файл изображения **или** каталог | required |
 | `--output-dir` / `-o` | Каталог вывода | рядом с `--input` |
 | `--ocr-engine` | **Обязательный:** `paddle`, `surya` или `external-qwen3` | — |
+| `--main-lang` | Основной язык: `ru` (eslav rec) или `en` (PP-OCRv6 rec) | `ru` |
 | `--fix-by-external-qwen3` | Исправить ошибки VLM API (Qwen3.8 Max) | OFF |
-| `--main-lang` | Основной язык: `ru` (eslav) или `en` (PP-OCRv6 rec) | `ru` |
 | `--pause` | Пауза между изображениями (сек) | 5 |
-| `--no-result-one-document` | Не объединять `.md` в один документ | — |
-| `--no-post-crop` | Не обрезать по контенту (Stage 1) | — |
+
+Выход: `.raw`-файл с сырым ответом движка (write-once, не изменяется при постпроцессинге).
 
 Пример:
 ```bash
 # Одна страница — PaddleOCR
 python -m src.image_ocr -i page.jpg --ocr-engine paddle
 
-# Одна страница — Surya 2
-python -m src.image_ocr -i page.jpg --ocr-engine surya
+# Внешняя VLM как OCR-движок (Qwen3.8 Max) — лучший для русского
+python -m src.image_ocr -i pages/ --ocr-engine external-qwen3
 
-# Пакетный режим
+# Английский документ (PP-OCRv6 rec)
+python -m src.image_ocr -i page.jpg --ocr-engine paddle --main-lang en
+
+# Пакетный режим — Surya 2 (batch)
 python -m src.image_ocr -i ./pages/ --ocr-engine surya
+```
 
-# Внешняя VLM как OCR-движок (Qwen3.8 Max)
-python -m src.image_ocr -i page.jpg --ocr-engine external-qwen3
+### Stage 3: `src/generate_result.py`
 
-# Без объединения в один документ
-python -m src.image_ocr -i ./pages/ --ocr-engine surya --no-result-one-document
+Постпроцессинг `.raw` → `.json` + `.md` + `.tex` + `.html`.
 
-# С VLM-корректором
-python -m src.image_ocr -i page.jpg --ocr-engine paddle --fix-by-external-qwen3
+| Параметр | Описание | По умолчанию |
+|----------|----------|:---:|
+| `--input` / `-i` | Каталог с `.raw`-файлами | required |
+| `--skip-latex` | Не генерировать LaTeX и HTML | OFF |
 
-# Английский документ (PP-OCRv6 rec)
-python -m src.image_ocr -i page.jpg --ocr-engine paddle --main-lang en
+Что делает:
+1. **Фильтрация номеров страниц** — блоки вида `42`, `[73]` в конце страницы удаляются
+2. **Восстановление таблиц** — таблицы, разорванные между страницами, объединяются (по кол-ву колонок)
+3. **Очистка формул** — `\text{score\_beh}` → `score_beh` для читаемости LLM
+4. **Генерация** — объединённый `.md` + `.tex` + `.html` (MathJax)
+
+```bash
+python -m src.generate_result -i cbr2/
 ```
 
 <details>
 │                                                        работает с            │
 │                                                        --ocr-engine          │
 │                                                        external-qwen3        │
-│    --no-result-one-doc…                                Не объединять .md     │
-│                                                        результаты в один     │
-│                                                        документ              │
-│                                                        [default: True]       │
+│    --main-lang                   <str>                 Основной язык: ru     │
+│                                                        (eslav_PP-OCRv5_mobi… │
+│                                                        или en                │
+│                                                        (PP-OCRv6_medium_rec) │
+│                                                        [default: ru]         │
 │    --pause                       <int range>           Пауза между           │
 │                                  [0<=x<=600]           изображениями в       │
 │                                                        секундах (по          │
 ```
 </details>
 
+### Stage 3: `src/generate_result.py` — `--help`
+
+<details>
+<summary><code>--help</code></summary>
+
+```
+ Usage: python -m src.generate_result [OPTIONS]
+
+ Постобработка результатов OCR: фильтрация, таблицы, объединение, LaTeX+HTML.
+
+╭─ Options ────────────────────────────────────────────────────────────────────╮
+│ *  --input       -i      <path>  Путь к каталогу с .raw-файлами             │
+│                                  (результаты OCR)                           │
+│                                  [required]                                 │
+│    --skip-latex                  Не генерировать LaTeX и HTML               │
+│    --help                        Show this message and exit.                │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+</details>
+
 ### Debug-лог
 
 Для отладки зависаний и падений — файл с полным логом всех этапов обработки.
 
 ## Результат
 
-CLI (`image_ocr.py`) генерирует два файла для каждого изображения:
+### Stage 2 (`image_ocr.py`) — сырой ответ
 
 | Файл | Формат | Описание |
 |------|--------|----------|
-| `page_01.md` | Markdown | Текст + `$$`-формулы + `##`-заголовки. **Готов к загрузке в LLM.** |
-| `page_01.json` | JSON | Полный дамп OCR: bbox, confidence, labels, formulas |
+| `page_01.raw` | JSON | Сырой ответ OCR-движка. **Неизменяемый** — пишется один раз, все постпроцессинги читают его |
 
-**При пакетной обработке** (каталог на входе) — дополнительно:
+### Stage 3 (`generate_result.py`) — итоговые файлы
 
-| Файл | Описание |
-|------|----------|
-| `<dirname>.md` | Объединённый многостраничный Markdown (по умолчанию) |
-| `<dirname>.tex` | LaTeX для всех страниц (через `json_to_latex.py`) |
-
-**Ручные утилиты:**
-
-| Файл | Утилита | Назначение |
-|------|---------|------------|
-| `.tex` | `src/latex/json_to_latex.py` | JSON (Paddle / Surya / Qwen) → LaTeX + HTML (автодетект) |
+| Файл | Формат | Описание |
+|------|--------|----------|
+| `page_01.json` | JSON | Очищенный результат (фильтр номеров страниц, объединённые таблицы) |
+| `page_01.md` | Markdown | Текст + `$$`-формулы + `##`-заголовки. **Готов к загрузке в LLM.** |
+| `<dirname>.md` | Markdown | Объединённый многостраничный документ |
+| `<dirname>.tex` | LaTeX | LaTeX для всех страниц |
+| `<dirname>.html` | HTML | HTML + MathJax для просмотра в браузере |
 
 ```bash
-# JSON → LaTeX (один файл, автоопределение формата)
-python -m src.latex.json_to_latex page.json
-
-# JSON → LaTeX + HTML (каталог — объединённый многостраничный)
-python -m src.latex.json_to_latex cbr_en_2/
-
-# Программный вызов
-python -c "from src.latex.json_to_latex import json_to_latex; \
-  open('page.tex','w').write(json_to_latex('page.json'))"
-
-python -c "from src.latex.json_to_latex import multi_json_to_latex; \
-  multi_json_to_latex('out/', 'out/document.tex')"
+# Полный цикл
+python -m src.image_prepare -i scan.jpg -s 3:3 -o pages/
+python -m src.image_ocr -i pages/ --ocr-engine external-qwen3
+python -m src.generate_result -i pages/
 ```
 
 ---
 
 ## Качество OCR
 
-| Движок | Русский текст | Формулы | Скорость (CPU) |
-|--------|:---:|:---:|:---:|
-| PaddleOCR (PP-StructV3) | ~85% | ✅ отлично | ~140s |
-| + VLM (Qwen3.8 Max) | ~98% | ✅✅ | +10s/блок |
-| Surya 2 | ~95% | ✅ отлично | ~300s |
+| Движок | Русский текст | Английский | Формулы | Скорость |
+|--------|:---:|:---:|:---:|:---:|
+| PaddleOCR `--main-lang ru` (eslav rec + v6 det) | ~85-90% | ~60% | ✅ PP-FormulaNet | ~100-160s CPU |
+| PaddleOCR `--main-lang en` (v6 rec) | — | ~75-80% | ✅ PP-FormulaNet | ~100-160s CPU |
+| Surya 2 | ~95% | ~95% | ✅ VLM | ~300s CPU |
+| External VLM (Qwen3.8 Max) | ~98% | ~98% | ✅✅ | ~60-120s API |
+
+**Детектор:** PP-OCRv6_medium_det (RepLKFPN) — +4.6% vs v5_server.
 
 ---
 
 
 ```
 src/
-  image_prepare.py      — CLI Stage 1
-  image_ocr.py          — CLI Stage 2
-  split/slicer.py        — разрезание, post-crop
+  models.py             — ParsedBlock, OcrPageResult
+  image_utils.py        — calc_scale_dims
+  env.py                — загрузка .env
+  cli_utils.py          — run_main()
+  image_prepare.py      — CLI Stage 1 (разрезание, unwarp, denoise)
+  image_ocr.py          — CLI Stage 2 (OCR → .raw)
+  generate_result.py    — CLI Stage 3 (постпроцессинг → .json/.md/.tex/.html)
+  split/slicer.py        — разрезание, post-crop, border, unwarp, denoise
   ocr/
-    paddle_engine.py     — PP-StructureV3
-    surya_engine.py      — Surya 2
+    paddle_engine.py     — PP-StructureV3 + v6-det + ru/en rec
+    surya_engine.py      — Surya 2 + batch + CPU-оптимизации
+    external_vlm_engine.py — Qwen3.8 Max full-page OCR
   postprocess/
-    fixups.py            — OCR-ошибки (VaR)
-    corrector.py         — Corrector protocol
-    vlm_corrector.py     — Qwen3.8 Max (API)
-  markdown/generator.py  — Markdown + валидация
+    fixups.py            — OCR-ошибки (VaR, V^2)
+    corrector.py         — apply_corrector (Callable)
+    vlm_corrector.py     — Qwen3.8 Max per-block
+    qwen_client.py       — общий Qwen API-клиент
+  markdown/
+    tables.py            — общие функции таблиц (parse, detect, ncols)
+    generator.py         — Markdown + валидация LaTeX
   latex/
-    json_to_latex.py     — Единый JSON→LaTeX+HTML (Paddle + Surya + Qwen)
+    json_to_latex.py     — JSON→LaTeX+HTML (Paddle + Surya + Qwen)
 ```
 
 ---

src/generate_result.py

+from __future__ import annotations
+
+import json
+import logging
+import re
+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.markdown.tables import (
+    MD_TABLE_SEP,
+    PAGE_NUM,
+    table_ncols,
+)
+from src.models import ParsedBlock
+
+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)
+
+_TABLE_ROW: re.Pattern = re.compile(r"^\|.+\|$")
+_UNESCAPE_TEXT: re.Pattern = re.compile(r"\\text\{([^}]+)\}")
+
+
+def _clean_formula(text: str) -> str:
+    def _replace(m: re.Match) -> str:
+        inner = m.group(1)
+        inner = inner.replace("\\_", "_").replace("\\ ", " ")
+        return inner
+    return _UNESCAPE_TEXT.sub(_replace, text)
+
+
+def _is_table_block(block: dict) -> bool:
+    content = (block.get("content", "") or "").strip()
+    if not content or "|" not in content:
+        return False
+    lines = content.splitlines()
+    data = [l for l in lines if not MD_TABLE_SEP.match(l)]
+    return len(data) >= 1 and all(_TABLE_ROW.match(line) for line in lines)
+
+
+def _table_ncols(block: dict) -> int:
+    return table_ncols(block.get("content", "") or "")
+
+
+def _table_data_rows(block: dict) -> str | None:
+    """Возвращает все строки данных (без заголовка и разделителя)."""
+    lines = (block.get("content", "") or "").strip().splitlines()
+    data = [l for l in lines if not MD_TABLE_SEP.match(l)]
+    if not data:
+        return None
+    first_cells = [c.strip() for c in data[0].split("|")[1:-1]]
+    is_header = _row_num(data[0]) is None and (
+        not any(first_cells)
+        or any(_row_num(l) is not None for l in data)
+    )
+    if len(data) >= 2 and is_header:
+        return "\n".join(data[1:])
+    return "\n".join(data)
+
+
+def _row_num(line: str) -> int | None:
+    try:
+        return int(line.strip().split("|")[1].strip())
+    except (ValueError, IndexError):
+        return None
+
+
+def _last_table_block(blocks: list[dict]) -> tuple[dict | None, int]:
+    for i in range(len(blocks) - 1, -1, -1):
+        if _is_table_block(blocks[i]):
+            return blocks[i], i
+    return None, -1
+
+
+def _merge_split_tables(pages: list[dict], names: list[str]) -> int:
+    """Объединяет split tables, охватывающие несколько соседних страниц (in-place)."""
+    merged_count = 0
+    i = 0
+    while i < len(pages) - 1:
+        blocks_a = pages[i].get("blocks", pages[i].get("parsing_res_list", []))
+        last_a, _ = _last_table_block(blocks_a)
+        if last_a is None:
+            i += 1
+            continue
+
+        ncols_a = _table_ncols(last_a)
+        j = i + 1
+        while j < len(pages):
+            blocks_b = pages[j].get("blocks", pages[j].get("parsing_res_list", []))
+            first_b = blocks_b[0] if blocks_b and _is_table_block(blocks_b[0]) else None
+            if first_b is None or _table_ncols(first_b) != ncols_a:
+                break
+
+            tail_rows = _table_data_rows(first_b)
+            if tail_rows is None:
+                break
+
+            rows_a = (last_a.get("content", "") or "").strip().splitlines()
+            data_a_rows = [l for l in rows_a if not MD_TABLE_SEP.match(l)]
+            tail_lines = tail_rows.splitlines()
+            if data_a_rows and tail_lines:
+                nums_a = {_row_num(l) for l in data_a_rows}
+                nums_a.discard(None)
+                tail_nums = {_row_num(l) for l in tail_lines}
+                tail_nums.discard(None)
+                if nums_a and tail_nums and min(tail_nums) > max(nums_a) + 1:
+                    break
+
+            last_a["content"] = (last_a.get("content", "") or "").rstrip() + "\n" + tail_rows
+            del blocks_b[0]
+            merged_count += 1
+            logger.info("Таблицы объединены: %s + %s (%d колонок)", names[i], names[j], ncols_a)
+            j += 1
+
+        i = max(i + 1, j - 1)
+
+    return merged_count
+
+
+def _filter_page_numbers(blocks: list[dict]) -> list[dict]:
+    dropped = [b for b in blocks if b.get("label") == "text" and PAGE_NUM.match((b.get("content", "") or "").strip())]
+    if dropped:
+        nums = ", ".join((b["content"] or "").strip() for b in dropped)
+        return [b for b in blocks if b not in dropped], nums
+    return blocks, ""
+
+
+def _process_raw(raw_path: Path) -> dict | None:
+    """Читает .raw, фильтрует номера страниц. Возвращает очищенные данные (не пишет)."""
+    data = json.loads(raw_path.read_text())
+    blocks = data.get("blocks", data.get("parsing_res_list", []))
+    if not blocks:
+        return None
+
+    clean, dropped_nums = _filter_page_numbers(blocks)
+    if dropped_nums:
+        logger.info("%s: убраны номера страниц [%s]", raw_path.name, dropped_nums)
+
+    if "blocks" in data:
+        data["blocks"] = clean
+    else:
+        data["parsing_res_list"] = clean
+    return data
+
+
+def _html_to_text(content: str) -> str:
+    if "<" not in content:
+        return content
+    from bs4 import BeautifulSoup
+
+    soup = BeautifulSoup(content, "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}$")
+    return soup.get_text("\n").strip()
+
+
+def _save_output(data: dict, raw_path: Path) -> None:
+    """Сохраняет .json и .md из очищенных данных."""
+    blocks = data.get("blocks", data.get("parsing_res_list", []))
+    for b in blocks:
+        key = "content" if "content" in b else "block_content"
+        b[key] = _html_to_text(_clean_formula(b.get(key, "")))
+    json_path = raw_path.with_suffix(".json")
+    json_path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    parsed = [ParsedBlock(
+        label=b.get("label", b.get("block_label", "text")),
+        content=b.get(key, ""),
+        bbox=tuple(b.get("bbox", b.get("block_bbox", [0, 0, 0, 0]))[:4]),
+    ) for b in blocks]
+    generate_markdown(parsed, json_path.with_suffix(".md"))
+
+
+def _generate_latex_html(json_dir: Path) -> None:
+    from src.latex.json_to_latex import _generate_all as gen
+    gen(json_dir)
+
+
+def _merge_md(json_dir: Path) -> None:
+    parts: list[str] = []
+    for md_path in sorted(json_dir.glob("*.md")):
+        if md_path.stem == json_dir.name:
+            continue
+        content = md_path.read_text(encoding="utf-8")
+        parts.append(f"<!-- page: {md_path.stem} -->\n\n{content}")
+    if parts:
+        merged = "# Merged document\n\n" + "\n\n---\n\n".join(parts)
+        out = json_dir / f"{json_dir.name}.md"
+        out.write_text(merged, encoding="utf-8")
+        logger.info("Объединённый документ: %s", out)
+
+
+@app.command()
+def generate_result(
+    input: Annotated[
+        Path,
+        typer.Option(
+            "--input",
+            "-i",
+            exists=True,
+            file_okay=True,
+            dir_okay=True,
+            readable=True,
+            help="Путь к каталогу с .raw-файлами (результаты OCR)",
+        ),
+    ],
+    skip_latex: Annotated[
+        bool,
+        typer.Option("--skip-latex", help="Не генерировать LaTeX и HTML"),
+    ] = False,
+) -> None:
+    """Постобработка результатов OCR: фильтрация, таблицы, объединение, LaTeX+HTML."""
+    if input.is_dir():
+        raw_files = sorted(input.glob("[!.]*.raw"))
+        if not raw_files:
+            raise typer.BadParameter(f"Нет .raw-файлов в каталоге: {input}")
+
+        logger.info("Обработка %d .raw-файлов...", len(raw_files))
+        pages: list[dict] = []
+        names: list[str] = []
+        active_raw: list[Path] = []
+        for rp in raw_files:
+            if rp.stem == input.name:
+                continue
+            data = _process_raw(rp)
+            active_raw.append(rp)
+            if data is not None:
+                pages.append(data)
+            else:
+                pages.append({})
+            names.append(rp.stem)
+
+        merged = _merge_split_tables(pages, names)
+        if merged:
+            logger.info("Всего объединено таблиц между страницами: %d", merged)
+
+        for rp, data in zip(active_raw, pages):
+            if not data.get("blocks") and not data.get("parsing_res_list"):
+                for suffix in (".json", ".md"):
+                    stale = rp.with_suffix(suffix)
+                    if stale.exists():
+                        stale.unlink()
+                continue
+            _save_output(data, rp)
+
+        _merge_md(input)
+
+        if not skip_latex:
+            _generate_latex_html(input)
+    else:
+        data = _process_raw(input)
+        if data:
+            _save_output(data, input)
+
+
+def main() -> None:
+    run_main(app)
+
+
+if __name__ == "__main__":
+    main()

src/image_ocr.py

 
 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
 
 # Настройка логирования
 _log_format = logging.Formatter("%(asctime)s [%(levelname)-5s] %(message)s", datefmt="%H:%M:%S")
 _console = logging.StreamHandler()
+_console.setLevel(logging.INFO)
 _console.setFormatter(_log_format)
 _root = logging.getLogger()
 _root.handlers.clear()
-_root.setLevel(logging.INFO)
+_root.setLevel(logging.DEBUG)
 _root.addHandler(_console)
 
 _log_file = os.environ.get("OCR_LOG_FILE", "")
 logger = logging.getLogger(__name__)
 app = typer.Typer(add_completion=False, no_args_is_help=True)
 
-MD_EXTENSION: str = ".md"
+RAW_EXTENSION: str = ".raw"
 IMG_EXTENSIONS: set[str] = {".jpg", ".jpeg", ".png", ".tiff", ".tif"}
 
 
     return functools.partial(ocr_image, main_lang=main_lang), "PP-StructureV3", False
 
 
-def _merge_markdown_files(output_dir: Path, input_name: str, 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 / (input_name + MD_EXTENSION)
-        merged_path.write_text(merged, encoding="utf-8")
-        logger.info("Объединённый документ: %s", merged_path)
-
-
 def _log_low_confidence(raw_json: dict) -> None:
     layout = raw_json.get("layout_det_res", {}).get("boxes", [])
     if not layout:
 
 
 def _save_result(page, input_path: Path, output_dir: Path) -> None:
-    json_path = output_dir / (input_path.stem + ".json")
-    if not json_path.exists():
-        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 / (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)
+    raw_path = output_dir / (input_path.stem + RAW_EXTENSION)
+    raw_payload = page.raw_json or {
+        "blocks": [{"label": b.label, "content": b.content, "bbox": list(b.bbox)}
+                   for b in page.blocks]
+    }
+    raw_path.write_text(json.dumps(raw_payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    logger.info("%s → %s (%d блоков)", input_path.name, raw_path.name, len(page.blocks))
 
 
 def _process_single(
             help="Основной язык: ru (eslav_PP-OCRv5_mobile_rec) или en (PP-OCRv6_medium_rec)",
         ),
     ] = "ru",
-    result_one_document: Annotated[
-        bool,
-        typer.Option(
-            "--no-result-one-document",
-            help="Не объединять .md результаты в один документ",
-        ),
-    ] = True,
     pause: Annotated[
         int,
         typer.Option(
         skipped = 0
         filtered: list[Path] = []
         for p in image_paths:
-            if (out / (p.stem + ".json")).exists():
+            if (out / (p.stem + RAW_EXTENSION)).exists():
                 logger.info("Пропуск %s (уже есть .json)", p.name)
                 skipped += 1
             else:
         else:
             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, out, use_vlm)
+                ok = False
+                for attempt in (1, 2, 3):
+                    try:
+                        _process_single(ocr_fn, img_path, out, use_vlm)
+                        ok = True
+                        break
+                    except Exception:
+                        logger.exception("Ошибка обработки %s (попытка %d/3)", img_path.name, attempt)
+                        if attempt < 3:
+                            logger.info("Пауза %dс и повтор...", pause)
+                            time.sleep(pause)
+                if not ok:
+                    logger.error("Не удалось обработать %s после 3 попыток", img_path.name)
+                    raise SystemExit(1)
                 if i < len(image_paths) - 1 and pause > 0:
                     time.sleep(pause)
 
         processed = len(image_paths)
         avg_dt = total_dt / processed if processed else 0
 
-        if result_one_document:
-            _merge_markdown_files(out, input.name, sorted(out.glob("*.md")))
-
         logger.info(
             "Готово: %d изображений, всего %.1fs, среднее %.1fs/изобр",
             processed, total_dt, avg_dt,

src/latex/json_to_latex.py

 
 from bs4 import BeautifulSoup
 
+from src.markdown.tables import (
+    PAGE_NUM,
+    is_markdown_table,
+    parse_markdown_table,
+    strip_formula_delimiters,
+)
+
 LATEX_PREAMBLE = r"""\documentclass[12pt,a4paper]{article}
 \usepackage[T2A]{fontenc}
 \usepackage[utf8]{inputenc}
 """
 
 MD_HEADING: re.Pattern = re.compile(r"^#{1,6}\s+")
-MD_TABLE_SEP: re.Pattern = re.compile(r"^\|?[\s:-]+\|[\s|:-]+\|?$")
-
-
-def _is_md_table(text: str) -> bool:
-    lines = text.strip().splitlines()
-    if len(lines) < 3:
-        return False
-    has_sep = any(MD_TABLE_SEP.match(line) for line in lines)
-    if not has_sep:
-        return False
-    return all("|" in line for line in lines)
-
-
-def _parse_md_table(text: str) -> list[list[str]]:
-    lines = text.strip().splitlines()
-    rows: list[list[str]] = []
-    for line in lines:
-        if MD_TABLE_SEP.match(line):
-            continue
-        cells = [c.strip() for c in line.split("|")[1:-1]]
-        rows.append(cells)
-    return rows
 
 
 def _md_table_to_html(text: str) -> str:
-    rows = _parse_md_table(text)
+    rows = parse_markdown_table(text)
     if not rows:
         return ""
     html_rows: list[str] = []
 
 
 def _md_table_to_latex(text: str) -> str:
-    rows = _parse_md_table(text)
+    rows = parse_markdown_table(text)
     if not rows:
         return ""
     ncols = max(len(row) for row in rows)
     lines: list[str] = []
     for b in data.get("blocks", []):
         content = b.get("content", "").strip()
-        if not content:
+        if not content or PAGE_NUM.match(content):
             continue
         label = b.get("label", "text")
 
         if label == "formula":
-            formula = content.strip()
-            if (formula.startswith("$$") and formula.endswith("$$")) or \
-               (formula.startswith("\\[") and formula.endswith("\\]")):
-                formula = formula[2:-2].strip()
+            formula = strip_formula_delimiters(content)
             lines.append(f"\\[\n{formula}\n\\]\n")
         elif label == "SectionHeader":
             heading = MD_HEADING.sub("", content).strip()
             lines.append(f"\\section*{{{_escape_latex(heading)}}}")
-        elif _is_md_table(content):
+        elif is_markdown_table(content):
             lines.append(f"\n{_md_table_to_latex(content)}\n")
         else:
             lines.append(f"\n{content}\n")
         content = block.get("content", "").strip()
         if not content:
             return ""
+        if PAGE_NUM.match(content):
+            return ""
         if label == "formula":
-            clean = content.strip()
-            for prefix, suffix in [("$$", "$$"), ("\\[", "\\]")]:
-                if clean.startswith(prefix) and clean.endswith(suffix):
-                    clean = clean[len(prefix):-len(suffix)].strip()
+            clean = strip_formula_delimiters(content)
             return f'\n<div class="equation">$$\n{clean}\n$$</div>'
         if label == "SectionHeader":
             heading = MD_HEADING.sub("", content).strip()
             return f"<h2>{heading}</h2>"
-        if _is_md_table(content):
+        if is_markdown_table(content):
             return _md_table_to_html(content)
         return f"<p>{content}</p>"
 
         try:
             page_html = json_to_html(jp)
             inner = page_html[page_html.find("<body>") + 6:page_html.find("</body>")]
-            pages.append(f'<div class="page-sep">{jp.stem}</div>\n<hr>\n{inner}')
+            pages.append(f'<hr>\n{inner}')
         except (json.JSONDecodeError, KeyError, ValueError):
             continue
 

src/markdown/generator.py

 import re
 from pathlib import Path
 
+from src.markdown.tables import fix_md_table
 from src.models import ParsedBlock
 
 logger = logging.getLogger(__name__)
         elif block.label == "number":
             lines.append(f"\n{text}\n")
         else:
+            text = fix_md_table(text)
             lines.append(f"\n{text}\n")
     return "\n".join(lines)
 

src/markdown/tables.py

+from __future__ import annotations
+
+import re
+
+MD_TABLE_SEP: re.Pattern = re.compile(r"^\|?[\s:-]*-[\s|:-]*\|$")
+PAGE_NUM: re.Pattern = re.compile(r"^\s*\d{1,4}\s*$")
+
+
+def is_markdown_table(text: str) -> bool:
+    lines = text.strip().splitlines()
+    if len(lines) < 2:
+        return False
+    if not all("|" in line for line in lines):
+        return False
+    if any(MD_TABLE_SEP.match(line) for line in lines):
+        return True
+    data_lines = [l for l in lines if not MD_TABLE_SEP.match(l)]
+    return len(data_lines) >= 2
+
+
+def parse_markdown_table(text: str) -> list[list[str]]:
+    rows: list[list[str]] = []
+    for line in text.strip().splitlines():
+        if MD_TABLE_SEP.match(line):
+            continue
+        rows.append([c.strip() for c in line.split("|")[1:-1]])
+    return rows
+
+
+def table_ncols(text: str) -> int:
+    rows = parse_markdown_table(text)
+    if not rows:
+        return 0
+    return len(rows[0])
+
+
+def fix_md_table(text: str) -> str:
+    lines = text.strip().splitlines()
+    if len(lines) < 2 or not all("|" in line for line in lines):
+        return text
+    if any(MD_TABLE_SEP.match(line) for line in lines):
+        return text
+    ncols = len(lines[0].split("|")[1:-1])
+    lines.insert(1, "|" + "|".join(["---"] * ncols) + "|")
+    return "\n".join(lines)
+
+
+def strip_formula_delimiters(text: str) -> str:
+    text = text.strip()
+    for prefix, suffix in (("$$", "$$"), ("\\[", "\\]")):
+        if text.startswith(prefix) and text.endswith(suffix):
+            return text[len(prefix):-len(suffix)].strip()
+    return text

src/models.py

     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

src/ocr/external_vlm_engine.py

     return OcrPageResult(
         blocks=blocks,
         raw_json={"blocks": [{"label": b.label, "content": b.content} for b in blocks]},
-        width=image.shape[1],
-        height=image.shape[0],
     )
 
 
 
     t0 = time.time()
     b64 = image_to_base64(scaled)
-    text = call_qwen_vlm(
+    text, usage = call_qwen_vlm(
         b64,
         (
-            "Extract ALL text from this document page. "
-            "For tables use | column | format |. "
-            "For formulas use $$...$$ or $...$. "
-            "Preserve structure: headers as ##, paragraphs as text. "
-            "Return ONLY the extracted content, no commentary."
+            "You are a high-accuracy document OCR engine.\n\n"
+            "Extract ALL visible textual and mathematical content from the image.\n\n"
+            "IMPORTANT:\n"
+            "- Do not summarize, interpret, paraphrase, or omit content.\n"
+            "- Do not invent or correct content that is unclear.\n"
+            "- Preserve the original wording, spelling, numbers, symbols, punctuation, and order.\n"
+            "- Preserve the reading order of the document.\n"
+            "- Include headers, footers, page numbers, captions, footnotes, marginal text, "
+            "labels, and text inside figures whenever readable.\n\n"
+            "DOCUMENT STRUCTURE:\n"
+            "1. Headings: Use Markdown headings (#, ##, ###) according to their visual hierarchy.\n"
+            "2. Paragraphs: Preserve paragraphs and line breaks where structurally meaningful.\n"
+            "3. Lists: Preserve numbered and bulleted lists.\n"
+            "4. Tables: Reconstruct every table completely. Preserve all rows and columns. "
+            "Do not omit empty cells. Use Markdown table syntax. Do not convert a table into prose.\n"
+            "5. Formulas: Reproduce every formula using LaTeX: inline $...$, display $$...$$. "
+            "Preserve subscripts, superscripts, fractions, Greek letters, operators, parentheses.\n"
+            "6. Figures: Preserve readable text inside them. For non-textual graphics: [FIGURE].\n"
+            "7. Uncertain text: Never guess. Use [?] for unrecognized characters.\n"
+            "8. Language: Preserve the original language. Do not translate.\n\n"
+            "OUTPUT: Return ONLY the reconstructed document. "
+            "No explanations, comments, confidence statements, or Markdown code fences."
         ),
-        max_tokens=4000,
+        max_tokens=12000,
     )
     dt = time.time() - t0
-    logger.debug("VLM: ответ за %.1fs", dt)
+    in_tok = usage.get("input_tokens", "?")
+    out_tok = usage.get("output_tokens", "?")
+    logger.info("VLM: ответ за %.1fs, токенов: in=%s out=%s", dt, in_tok, out_tok)
+    logger.debug("VLM: %dx%d px → in=%s out=%s tokens, %.1fs", scaled.shape[1], scaled.shape[0], in_tok, out_tok, dt)
 
     if not text:
         raise RuntimeError("VLM вернул пустой ответ")

src/ocr/paddle_engine.py

         if image is None:
             raise FileNotFoundError(f"Не удалось загрузить изображение: {image_path}")
 
-        h, w = image.shape[:2]
         if self._pipeline is None:
             self._pipeline = create_pipeline(
                 config=self._config,
         raw_results = list(self._pipeline.predict(image))
 
         blocks, raw_json = self._parse_results(raw_results)
-        return OcrPageResult(blocks=blocks, raw_json=raw_json, width=w, height=h)
+        return OcrPageResult(blocks=blocks, raw_json=raw_json)
 
     @staticmethod
     def _parse_results(raw_results: list[Any]) -> tuple[list[ParsedBlock], dict[str, Any]]:

src/ocr/surya_engine.py

             )
             raise ImportError(msg) from e
 
-    def process(self, image_path: str) -> OcrPageResult:
-        from PIL import Image
-
-        image = Image.open(image_path)
-        return self._process_image(image)
-
     def process_batch(self, image_paths: list[str]) -> list[OcrPageResult]:
         from PIL import Image
 
         images = [_pre_scale(Image.open(p)) for p in image_paths]
         results = self._predictor(images)
-        return [self._to_result(results[i], images[i]) if i < len(results) else OcrPageResult()
+        return [self._to_result(results[i]) if i < len(results) else OcrPageResult()
                 for i in range(len(images))]
 
     def _health_check(self) -> bool:
             logger.warning("llama-server health check failed")
             return False
 
-    def _process_image(self, image: PILImage.Image) -> OcrPageResult:
-        scaled = _pre_scale(image)
-        results = self._predictor([scaled])
-        if results:
-            return self._to_result(results[0], scaled)
-        return OcrPageResult()
-
     @staticmethod
-    def _to_result(page, image: PILImage.Image) -> OcrPageResult:
+    def _to_result(page) -> OcrPageResult:
         blocks: list[ParsedBlock] = []
         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={},
-            width=image.width,
-            height=image.height,
-        )
+        return OcrPageResult(blocks=blocks, raw_json={})
 
 
 def _pre_scale(image: PILImage.Image) -> PILImage.Image:
     return SuryaEngine()
 
 
-def surya_ocr_image(image_path: str) -> OcrPageResult:
-    engine = _get_surya_engine()
-    return engine.process(image_path)
-
-
 def surya_ocr_batch(image_paths: list[str]) -> list[OcrPageResult]:
     engine = _get_surya_engine()
     if not engine._health_check():

src/postprocess/qwen_client.py

     prompt: str,
     model: str = DEFAULT_MODEL,
     max_tokens: int = 300,
-) -> str | None:
-    """Отправляет изображение + prompt в Qwen3.8 Max API и возвращает текст ответа."""
+) -> tuple[str | None, dict]:
+    """Отправляет изображение + prompt в Qwen3.8 Max API.
+    Возвращает (текст, usage_dict)."""
+    empty_usage: dict = {}
     if not _api_key():
         logger.warning("OPENCODE_API_KEY не задан")
-        return None
+        return None, empty_usage
 
     messages = [{
         "role": "user",
         ],
     }]
 
-    for attempt in (1, 2):
+    for attempt in (1, 2, 3):
         try:
             r = requests.post(
                 API_URL,
             )
             r.raise_for_status()
             data = r.json()
+            text = ""
             for item in data.get("content", []):
                 if item.get("type") == "text":
-                    return item.get("text", "").strip()
-            return None
+                    text = item.get("text", "").strip()
+            stop = data.get("stop_reason", "")
+            usage = data.get("usage", {})
+            if text and stop == "max_tokens":
+                logger.warning("Qwen API: ответ обрезан (max_tokens=%d), stop_reason=%s", max_tokens, stop)
+            return text or None, usage
         except requests.HTTPError as e:
-            if e.response is not None and e.response.status_code == 500 and attempt == 1:
-                logger.info("Qwen API: HTTP 500, ожидание 5с и повтор...")
-                _time.sleep(5)
+            status = e.response.status_code if e.response is not None else 0
+            if status in (500, 503) and attempt < 3:
+                delay = 5 * attempt
+                logger.info("Qwen API: HTTP %d, ожидание %dс и повтор...", status, delay)
+                _time.sleep(delay)
                 continue
             logger.warning("Qwen API: ошибка — %s", e)
-            return None
+            return None, {}
         except (requests.RequestException, KeyError, IndexError) as e:
             logger.warning("Qwen API: ошибка — %s", e)
-            return None
-    return None
+            return None, {}
+    return None, {}

src/postprocess/vlm_corrector.py

     b64 = image_to_base64(crop)
     total_sent = len(b64) // 1024
     logger.info("VLM: отправка %dx%d px → %d KB (bbox %d,%d,%d,%d)", x2 - x1, y2 - y1, total_sent, x1, y1, x2, y2)
-    text = call_qwen_vlm(
+    text, _ = call_qwen_vlm(
         b64,
         "Extract ALL visible text from this image region. Preserve LaTeX math. Return ONLY the extracted text.",
         max_tokens=300,

src/split/slicer.py

         approx = cv2.approxPolyDP(cnt, 0.02 * peri, True)
         if len(approx) == 4:
             rect = _order_points(approx.reshape(4, 2))
-            return _apply_perspective(image, rect)
+            result = _apply_perspective(image, rect)
+            if result.shape[0] >= h * 0.8 and result.shape[1] >= w * 0.8:
+                return result
     return image
 
 

stage2_results.md

 6. **VLM-корректор (Qwen3.8 Max)** — отличный, но API
 7. **Surya 2** — лучший русский OCR из коробки, CPU-оптимизации дали -30% времени
 8. **Гибридный подход**: Surya для текста + VLM для таблиц = лучший баланс
-9. **CPU-ограничения** — основной фактор, GPU сделал бы Surya/PaddleOCR-VL идеальным выбором
+9. **CPU-ограничения** — основной фактор, GPU сделал бы Surya/PaddleOCR-VL идеальным выбором
+
+---
+
+## Трёхэтапный пайплайн (рефакторинг)
+
+### Проблема
+Изначально `image_ocr.py` делал всё: OCR → фильтрация → объединение → LaTeX. Постпроцессинг **изменял `.json`-файлы на месте**, что приводило к накоплению ошибок (повторная генерация портила данные, таблицы дублировались).
+
+### Решение: `.raw` write-once + Stage 3
+
+```
+image_prepare  (Stage 1) → подготовка изображений
+image_ocr      (Stage 2) → OCR → .raw  (сырой ответ, НИКОГДА не изменяется)
+generate_result (Stage 3) → постпроцессинг → .json + .md + .tex + .html
+```
+
+Ключевой принцип: **`.raw` — неизменяемый**. Все операции постпроцессинга читают `.raw` и пишут результат в отдельные файлы. Повторный запуск Stage 3 даёт идентичный результат (идемпотентность).
+
+### VLM-промпт (Qwen3.8 Max) — ключевое улучшение ✅
+
+Старый промпт (4 строки) → новый (детальный, 30 строк):
+
+| Аспект | Старый | Новый |
+|---|---|---|
+| Роль | — | "high-accuracy document OCR engine" |
+| Анти-галлюцинации | — | "Do not summarize, interpret, paraphrase, or omit" |
+| Порядок чтения | — | "Preserve the reading order" |
+| Таблицы | "| col | format |" | "Reconstruct every table completely. Do not omit empty cells." |
+| Неуверенный текст | — | [?] вместо догадок |
+| Язык | — | "Do not translate" |
+| max_tokens | 4000 | 8000 (+предупреждение о truncation) |
+
+**Эффект:** 4 блока → 11 блоков на одной странице; таблицы полностью восстанавливаются.
+
+### Восстановление таблиц между страницами ✅
+
+Таблицы, разорванные между страницами (заголовок на стр. N, строки на стр. N+1...), объединяются по кол-ву колонок. Цепочки из 2-4 страниц склеиваются в одну таблицу (например, Таблица 76 на 4 страницах).
+
+### Unwarp-баг и фикс ⚠️→✅
+
+Первая версия unwarp искала 4-угольный контур и warp'ила в него — на плоских сканах находила внутренние таблицы и обрезала до 40% высоты. Фикс: порог `min_area ≥ 30%` + проверка, что результат ≥ 80% оригинала. Для плоского сканера unwarp = NOP.
+
+### Очистка формул для LLM ✅
+
+`\text{score\_beh}` → `score_beh` — формулы читаемы для LLM без LaTeX-шума.
+
+### Удалено за ненадобностью
+
+| Что | Причина |
+|---|---|
+| LLM-корректор (Qwen2.5-7B) | галлюцинирует, слепой (не видит изображение), +60s/стр |
+| Binarization (adaptive threshold) | рвёт буквы, вредна для нейросетевого OCR |
+| Upscale ×2 | max_side_limit=4000 съедает |
+| `surya2html.py`, `tex2html.py` | дубликаты json_to_latex.py |
+| `confidence`, `width`, `height` в моделях | write-only поля |
+| single-image Surya path | используется только batch |
+
+### Общий модуль таблиц ✅
+
+`src/markdown/tables.py` — единые `MD_TABLE_SEP`, `PAGE_NUM`, `is_markdown_table()`, `parse_markdown_table()`, `table_ncols()`, `fix_md_table()`, `strip_formula_delimiters()`. Устранена тройная дупликация regex между `generate_result.py`, `generator.py`, `json_to_latex.py`.