polishing the code and docs

.ai/CODE_STYLE.md

@@ -99,3 +99,60 @@ CLI должен завершаться ненулевым кодом возвр
 - закомментированный код;
 - неиспользуемый код;
 - TODO без объяснения.
+
+---
+
+## Паттерны, выработанные в проекте
+
+### Корректоры: мутация in-place
+
+Функции-корректоры (LLM, VLM, fixups) изменяют `ParsedBlock.content` на месте и возвращают `None`.
+
+```python
+def fix_ocr_errors(blocks: list[ParsedBlock]) -> None:  # ← None, не list
+    for block in blocks:
+        if block.label == "formula":
+            block.content = _fix_formula_errors(block.content)
+```
+
+Протокол:
+
+```python
+class Corrector(Protocol):
+    def __call__(self, block: ParsedBlock) -> None: ...
+```
+
+### Общие переменные окружения через `src/env.py`
+
+Любой модуль, читающий `.env`, использует `from src.env import load_env`. Не дублировать `_load_env()` в каждом файле.
+
+### Multi-engine через фабрику
+
+```python
+def _get_ocr_engine(name: str):
+    if name == "surya":
+        return surya_ocr_image, surya_ocr_batch, "Surya 2 VLM"
+    return ocr_image, None, "PP-StructureV3"
+```
+
+Возвращает `(single_fn, batch_fn, display_name)`. Новый движок — добавить elif-ветку.
+
+### Синглтоны для ML-моделей
+
+Допустимы ленивые синглтоны для тяжёлых объектов (модели, pipeline'ы), но через фабричную функцию:
+
+```python
+_engine: OcrEngine | None = None
+
+def ocr_image(path: str) -> OcrPageResult:
+    global _engine
+    if _engine is None:
+        _engine = OcrEngine()
+    return _engine.process(path)
+```
+
+Не использовать модульные глобальные переменные напрямую.
+
+### Периодический SOLID/DRY/KISS/YAGNI аудит
+
+После реализации крупной фичи — прогнать аудит по `.ai/SOLID_AUDIT.md`. Не накапливать технический долг.

.ai/SOLID_AUDIT.md

@@ -0,0 +1,60 @@
+# SOLID/DRY/KISS/YAGNI Audit
+
+Периодический аудит кода по принципам SOLID, DRY, KISS, YAGNI.
+
+## Когда запускать
+
+- После реализации крупной фичи (>200 строк нового кода)
+- Перед финальным тестированием этапа
+- При рефакторинге
+- Когда файл превышает 300 строк
+
+## Категории проверки
+
+### YAGNI — код, который не используется
+- Функции/классы без вызовов
+- Импорты без использования
+- Параметры, которые всегда передаются с одним значением
+- Return-значения, которые игнорируются ВСЕМИ вызывающими
+
+### DRY — дублирование
+- Идентичные блоки кода в разных файлах (ctrl-c/ctrl-v)
+- Одинаковая логика с разными именами
+- Дублирование `_load_env`, шаблонов, моделей данных
+- Повторяющиеся импорты внутри функции/модуля
+
+### KISS — излишняя сложность
+- Вложенность >3 уровней
+- Функции >40 строк без явной причины
+- Сложная арифметика там, где есть библиотечная функция
+- Типы `Any` там, где известна структура
+- Magic numbers вместо именованных констант
+
+### SRP — смешение ответственности
+- Функция делает ≥3 логически разных действий
+- Модуль импортирует несвязанные библиотеки
+- Класс/функция и генерирует данные, и форматирует, и сохраняет
+
+### Связность (Coupling)
+- Глобальные переменные-синглтоны
+- Прямые импорты конкретных реализаций вместо протоколов
+- Жёсткая привязка к путям в ФС (`/home/user/...`)
+
+### Обработка ошибок
+- Нет try/except вокруг внешних вызовов (сеть, диск, API)
+- `assert` для control flow
+- Строковые срезы без проверки на `find() == -1`
+
+## Процесс
+
+1. Пройти по всем `src/*.py` сверху вниз
+2. Для каждого файла отметить проблемы с номером строки
+3. Сгруппировать по категориям
+4. Приоритезировать: bug > DRY > YAGNI > style
+5. Исправлять от высокого приоритета к низкому
+
+## Что НЕ является проблемой (не чинить)
+
+- Ленивые импорты внутри функций (для избежания циклических зависимостей)
+- Синглтоны для тяжёлых объектов (ML-модели, pipeline'ы) — оправдано производительностью
+- Кодогенерация/шаблоны — читаемость важнее «чистоты» строк

.ai/VLM_OFFLOAD.md

@@ -0,0 +1,67 @@
+# Offload to Cloud VLM
+
+## Когда применять
+
+Если локальное железо не может выполнить задачу:
+- Нет GPU, CPU-инференс >5 минут на страницу
+- Модель не помещается в RAM
+- Точность локальной модели недостаточна, а fine-tune невозможен
+
+**И есть подписка с доступом к VLM по API** (OpenCode Go, OpenAI, Anthropic).
+
+Тогда локальный OCR делает быструю «грязную» работу, а сомнительные регионы отправляются в cloud VLM.
+
+## Паттерн
+
+```
+Локальный OCR (быстрый, среднее качество)
+    │
+    ├─ confidence > 0.8 → OK, сохраняем как есть
+    │
+    └─ confidence < 0.8 → вырезаем bbox из изображения
+            │
+            ▼
+       Cloud VLM API (высокое качество)
+            │
+            ▼
+       Заменяем текст блока
+```
+
+## Что отправлять
+
+- **Не** весь документ — только регион изображения (bbox + padding 5px)
+- Формат: base64 JPEG, quality=90
+- Prompt: «Извлеки весь текст из этого региона. Сохрани формулы как LaTeX.»
+- API: Anthropic Messages (`/v1/messages`) или OpenAI Chat Completions
+
+## Интеграция
+
+```python
+class VlmCorrector:
+    def __init__(self, image_path: str, model: str = "qwen3.8-max"):
+        self._image = cv2.imread(image_path)
+        self._model = model
+    
+    def __call__(self, block: ParsedBlock) -> None:
+        # crop bbox → base64 → API call → block.content = result
+```
+
+Через `Corrector` протокол подключается к общему циклу `apply_corrector()`.
+
+## Конфигурация
+
+API-ключ через `.env`: `OPENCODE_API_KEY=sk-...`
+URL из документации провайдера (для OpenCode Go: `https://opencode.ai/zen/go/v1/messages`)
+
+## Ограничения
+
+- Требует интернет (нарушает offline-требование)
+- Задержка API: 5-15s на блок
+- Лимиты подписки (OpenCode Go: 160 запросов/5ч для Qwen3.8 Max)
+- Стоимость: ~$0.01 за блок (при 200 выходных токенах)
+
+## Когда НЕ применять
+
+- Весь документ умещается в RAM и обрабатывается <30s локально
+- Нет API-подписки
+- Документ содержит конфиденциальные данные (offline-требование)

.env.dist

@@ -1,2 +1,6 @@
-OPENCODE_API_KEY=your_private_opencode_api_key
-HF_TOKEN=your_private_huggingface_readonly_api_key
+# OpenCode Go — API-ключ для VLM-корректора (Qwen3.8 Max)
+OPENCODE_API_KEY=sk-...
+
+# HuggingFace — токен для скачивания моделей (Surya 2, Qwen GGUF)
+# Получить: https://huggingface.co/settings/tokens (read-only)
+HF_TOKEN=hf_...

3_1200_02_surya.md

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

3_surya.md

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

README.md

@@ -85,12 +85,29 @@ python -m src.image_split -i scan.jpg --slice-auto
 python -m src.image_to_latex -i page.jpg
 
 # Пакетный режим — все изображения в каталоге (Surya: batch-оптимизация)
+
 python -m src.image_to_latex -i ./pages/ --ocr-engine surya
 
 # Пакетный режим (PaddleOCR: последовательно)
 python -m src.image_to_latex -i ./pages/ --ocr-engine paddle
 ```
 
+### Переменные окружения (`.env`)
+
+Скопируй шаблон и заполни своими ключами:
+
+```bash
+cp .env.dist .env
+# Отредактируй .env — вставь свои API-ключи
+```
+
+| Переменная | Назначение | Где взять |
+|-----------|-----------|-----------|
+| `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) |
+
+`.env` уже добавлен в `.gitignore` — не коммитится.
+
 ---
 
 ## Результат