updated discovered self skills

.ai/SKILLS.md

+# Наработанные навыки
+
+## OCR / PaddleOCR
+
+- **PP-StructureV3**: конфигурация через YAML-файл, замена моделей распознавания (`eslav_PP-OCRv5_mobile_rec` для русского, `PP-OCRv6_medium_rec` для английского), смена детектора `PP-OCRv5_server_det` → `PP-OCRv6_medium_det` без апгрейда `paddlepaddle`
+- **Архитектура детекторов**: DB (Differentiable Binarization) vs DB++ (RepLKFPN, ASF, DCN), PPLCNetV4, EncoderWithLightSVTR
+- **Модельный зоопарк**: `eslav` vs `cyrillic` (обе mobile, разница ~1%), `PP-OCRv6_medium_rec` (46 латинских + CN/JP/EN, без кириллицы), PP-FormulaNet для формул, SLANeXt для таблиц
+- **Параметры детектора**: `thresh` (порог карты вероятности), `box_thresh` (фильтр bbox), `unclip_ratio` (расширение контура), `max_side_limit` (обрезает upscale)
+- **Источники моделей**: PaddlePaddle CDN, HuggingFace Hub, modelscope — fallback-цепочка в `paddlex`
+
+## Surya 2 / llama.cpp
+
+- **CPU-оптимизации**: `SURYA_INFERENCE_KEEP_ALIVE=true` (-23s повторный старт), `CTX_PER_SLOT=8192` (-30% RAM), `PARALLEL=1` (-80% слотов), `pre-scale=1056px` (~96 DPI), `-t 8 --threads-batch 8` (стабильная загрузка CPU)
+- **Health-check + retry**: проверка `http://host:port/health`, пересоздание engine при падении llama-server, `lru_cache.cache_clear()` для сброса
+
+## OpenCV
+
+- **Unwarping**: Canny → findContours → approxPolyDP → _order_points → getPerspectiveTransform → warpPerspective с порогом `min_area ≥ 30%` (чтобы не детектить внутренние таблицы как страницу)
+- **Denoising**: `fastNlMeansDenoisingColored` — Non-Local Means. Полезен для шумных сканов, NOP для чистых. НЕ вреден для нейросетевого OCR
+- **Бинаризация**: `adaptiveThreshold` (Gaussian, окно 31) вредна для нейросетевого OCR — жёсткие границы рвут буквы, создают ложные контуры. Нейросети обучены на естественных изображениях, не на бинарных
+- **Upscale**: `cv2.resize(INTER_CUBIC)` бесполезен, если OCR-движок обрезает `max_side_limit`
+
+## Архитектура Python / SOLID
+
+- **Вынос общих моделей**: `ParsedBlock`, `OcrPageResult` → отдельный `models.py` — 7 модулей отвязаны от `paddle_engine`
+- **Protocol → Callable**: если Protocol никем не реализован — YAGNI. `Callable[[ParsedBlock], None]` проще
+- **lru_cache вместо глобальных синглтонов**: `@functools.lru_cache(maxsize=N)` вместо `_engine: X | None = None` + `global _engine`
+- **idempotent env loader**: `load_env()` с внутренним guard'ом — не нужны внешние `_ENV_LOADED` флаги
+- **Shared API client**: `call_qwen_vlm()` + `image_to_base64()` в `qwen_client.py` — общий для OCR-движка и корректора
+
+## CLI / Typer
+
+- **Annotated-параметры**: `Annotated[Path, typer.Option("--input", "-i")]` — минимум бойлерплейта
+- **Параметры по умолчанию**: обязательные без default, опциональные с `= None`, булевы через `--flag / --no-flag`
+- **Collapsible --help в README**: `<details><summary>--help</summary>...</details>`
+
+## pip / Управление зависимостями
+
+- **opencv конфликт**: `opencv-contrib-python` и `opencv-python-headless` делят `cv2/` — удаление одного ломает другой. Выбор: headless легче (-18 MB), без X11
+- **version pinning**: `paddlepaddle==3.2.2` (баг ONEDNN/PIR в 3.3.1), `numpy<2.4` (paddlex ограничение), `opencv-python-headless<5.0` (surya-ocr требует 4.11)
+- **pip freeze → ручной requirements.txt**: 118 пакетов → 14 (только прямые зависимости)
+
+## Многоформатный вывод
+
+- **JSON → LaTeX**: 3 формата (Paddle `parsing_res_list`, Surya `blocks[].html`, Qwen `blocks[].content`), автоопределение по структуре
+- **JSON → HTML + MathJax**: единый шаблон `HTML_TEMPLATE`, CDN MathJax 3, `$$...$$` для display-формул
+- **Таблицы**: HTML `<table>` → LaTeX `tabular`, Markdown `|...|` → HTML `<table>`
+
+## Документирование
+
+- **Аудит SOLID/DRY/KISS/YAGNI**: дважды за проект, фиксация нарушений с severity и планом исправления
+- **История экспериментов**: `stage2_results.md` — 16 вариантов, маркировка ✅/❌/⚠️, причина решения
+- **Модельный инвентарь**: какие модели установлены, размер, назначение, какие можно удалить
+
+## Удалённое за ненадобностью
+
+| Что | Причина |
+|---|---|
+| LLM-корректор (Qwen2.5-7B, 4.4 GB) | Галлюцинации, слепой, большой |
+| Binarization (adaptive threshold) | Вредна для нейросетевого OCR |
+| Upscale ×2 | max_side_limit=4000 съедает |
+| surya2html.py, tex2html.py | Дубликаты json_to_latex.py |
+| 100+ пакетов в requirements.txt | Транзитивные зависимости pip freeze |
+| 2.2 GB мёртвых моделей | Неиспользуемые v5 и cyrillic |