feat: evidence-grounded document slide alignment v2

.dockerignore

@@ -0,0 +1,7 @@
+.env
+.env.*
+!.env.example
+.git
+.worktrees
+test-data
+

.env.example

@@ -21,14 +21,33 @@ VIDEO_TARGET_RESOLUTION=720
 # Модели LLM через OpenRouter (приоритетный список, fallback при 429)
 LLM_MODELS_SPLIT=google/gemini-3.6-flash,google/gemini-3.5-flash,google/gemini-3.5-flash-lite
 LLM_MODELS_SUBSPLIT=google/gemini-3.6-flash,google/gemini-3.5-flash,google/gemini-3.5-flash-lite
-LLM_MODELS_RENDER=google/gemini-3.5-flash-lite,google/gemini-3.6-flash,google/gemini-3.5-flash
+LLM_MODELS_RENDER=google/gemini-3.5-flash-lite,google/gemini-3.5-flash,google/gemini-3.6-flash
 
 # Параллельность и reasoning effort по этапам структуризации
+# Потолок ответа модели, включая reasoning-токены. Обрезанный ответ рвал
+# JSON каталога слайдов, поэтому по умолчанию — предел моделей Gemini.
+LLM_MAX_TOKENS=65536
 LLM_CONCURRENCY_SUBSPLIT=2
 LLM_CONCURRENCY_RENDER=5
 LLM_EFFORT_SPLIT=medium
 LLM_EFFORT_SUBSPLIT=medium
 LLM_EFFORT_RENDER=medium
+# Матчер слайдов отвечает строгими схемами: reasoning мешает их соблюдать,
+# поэтому его effort отделён от контентных стадий.
+LLM_EFFORT_SLIDE_MATCH=low
+# Свой список моделей для матчера слайдов. Пусто (или переменная не задана) —
+# берутся модели LLM_MODELS_SUBSPLIT, поведение как раньше.
+# Зачем отделять: на каталогизации страниц, дословно цитирующих официальные
+# документы, Gemini обрывает генерацию по фильтру цитирования Google
+# (RECITATION), и каталог всего батча деградирует в нативный текст PDF.
+# У модели с открытыми весами такого обрыва мы не наблюдали, при этом она
+# доступна через того же BYOK-провайдера google-ai-studio — её удобно ставить
+# последним звеном ротации, чтобы батч добирала она, а не запасной текст.
+# LLM_MODELS_SLIDE_MATCH=google/gemini-3.6-flash,google/gemini-3.5-flash-lite,google/gemma-4-31b-it:free
+
+
+# Привязка приложенного PDF/PPTX: legacy, shadow или evidence-first v2.
+DOCUMENT_SLIDE_ALIGNMENT_MODE=legacy
 
 # Стадия отбора кадров из видео (video_slides): отдельно от документных слайдов,
 # запускается только для видео без приложенного slides-документа и без no_slides

.gitignore

@@ -3,6 +3,7 @@ __pycache__/
 .venv/
 .env
 data/
+test-data/
 docs/plans/
 .pytest_cache/
 *.egg-info/

OPEN-QUESTIONS.md

@@ -0,0 +1,10 @@
+# Открытые вопросы
+
+Очередь продуктовых развилок, которые нельзя решить из кода: правильное поведение
+здесь не выводится ни из контракта, ни из инварианта — его выбирает человек.
+
+---
+
+Записи отсюда **удаляются**, а не накапливаются: пользователь отвечает на вопрос →
+ответ немедленно превращается в тест → строка убирается из файла. Файл должен
+стремиться к нулю; это очередь долга, а не база знаний.

README.md

@@ -18,6 +18,8 @@ HTTP-сервис обработки лекций: на вход — лекци
 3. **Слайды** — три источника: из приложенного PDF/PPTX (pymupdf + LibreOffice),
    автоматически из видеоряда через Gemini Vision, либо без слайдов (флаг `no_slides`).
 4. **Структуризация** транскрипта на темы и подтемы через Gemini, с привязкой слайдов.
+   Секция с некорректной шкалой (конец раньше начала) не роняет задачу: конец берётся
+   из начала следующей секции, у последней — из конца транскрипта.
 5. **Кадры из видео** (стадия `video_slides`, только для видео-лекций без
    приложенного документа слайдов) — из видеоряда автоматически отбираются
    осмысленные стопкадры (слайд / доска в момент «дописал» / финальный код
@@ -30,6 +32,10 @@ HTTP-сервис обработки лекций: на вход — лекци
 задачи автоматически помечаются как `interrupted`. Несколько лекций обрабатываются параллельно
 (лимит — `MAX_CONCURRENT_TASKS`), остальные ждут в очереди.
 
+Регрессионное качество готового ZIP проверяется независимым сабагентом по
+репозиторному skill `skills/lecture-quality-judge`: он сопоставляет конспект,
+транскрипт, слайды и alignment diagnostics с проверяемым evidence.
+
 ### Режимы слайдов
 
 - **видео без слайдов-документа** → слайды извлекаются автоматически из видеоряда (Gemini Vision);
@@ -38,6 +44,12 @@ HTTP-сервис обработки лекций: на вход — лекци
 
 Для аудио слайды есть только при приложенном документе.
 
+Для документных слайдов доступны `legacy`, `shadow` и `v2` через
+`DOCUMENT_SLIDE_ALIGNMENT_MODE`. В `v2` страница попадает inline только при
+проверяемом свидетельстве в SRT и безопасном Markdown-anchor; менее уверенные
+страницы остаются галереей раздела, а неупомянутые выводятся в отдельном
+приложении. `shadow` считает диагностику, но сохраняет legacy-результат.
+
 ### Кадры из видео (стадия `video_slides`)
 
 Отдельно от «Режимов слайдов» выше: для видео-лекций **без** приложенного документа
@@ -353,6 +365,8 @@ python scripts/submit_task.py --base http://my-host:8000/api/v1 status <task_id>
 | `LLM_CONCURRENCY_*`    | Параллельность вызовов LLM по этапам.                     |
 | `LLM_EFFORT_*`         | Reasoning effort по этапам структуризации (по умолчанию `low`). |
 | `FRAMES_ENABLED`       | Вкл./выкл. стадии отбора кадров из видео (`video_slides`). По умолчанию `true`. |
+| `DOCUMENT_SLIDE_ALIGNMENT_MODE` | Привязка PDF/PPTX: `legacy`, `shadow` или `v2`; по умолчанию `legacy`. |
+| `LLM_MODELS_SLIDE_MATCH` | Свой приоритетный список моделей для матчера слайдов. Пусто (по умолчанию) → берутся модели `LLM_MODELS_SUBSPLIT`. |
 | `LLM_MODELS_VIDEO_SLIDES` | Приоритетный список VLM-моделей для QC кадров (fallback при 429). |
 | `LLM_EFFORT_VIDEO_SLIDES` | Reasoning effort для QC кадров (по умолчанию `low`). |
 | `LLM_MODELS_FRAMES_CLASSIFY` | Приоритетный список VLM-моделей для классификации режимов видео. |
@@ -411,6 +425,18 @@ OpenRouter вызывается в режиме BYOK с провайдером `
 конкретная модель временно ставится на cooldown, после чего клиент пробует следующую
 модель из списка.
 
+На cooldown (60 секунд) модель уходит и в двух других случаях:
+
+- `5xx` от апстрима (например, «This model is currently experiencing high demand») —
+  задача не падает, попытка повторяется с нарастающей паузой на другой модели;
+- апстрим оборвал генерацию — OpenRouter отдаёт `200` с частичным контентом,
+  нулевым usage и `finish_reason="error"` (фильтр цитирования Gemini `RECITATION`,
+  `provider_overloaded`). Такой обрывок не считается валидным ответом и не попадает
+  в статистику использования;
+- ответ пришёл без `choices` — при отказе провайдера OpenRouter отдаёт `200` с телом
+  из одной ошибки. Это тоже трактуется как отказ модели, а не как ошибка формата, и
+  задача не падает.
+
 Текущий набор моделей:
 
 | Модель                           | Роль |
@@ -427,6 +453,20 @@ OpenRouter вызывается в режиме BYOK с провайдером `
   количеству, но критичных решений классификатора и `LLM_MODELS_VIDEO_SLIDES` для QC.
 - Несколько Google AI Studio ключей сейчас не ротируются в core; для увеличения RPD
   нужно выпускать отдельный OpenRouter key/конфигурацию на окружение.
+- У матчера слайдов свой список моделей (`LLM_MODELS_SLIDE_MATCH`) и свой effort
+  (`LLM_EFFORT_SLIDE_MATCH`). Пустой список означает наследование от
+  `LLM_MODELS_SUBSPLIT`.
+
+Зачем матчеру отдельный список: на каталогизации слайды уходят в LLM батчами по 6
+изображений, и на страницах, дословно цитирующих официальные документы, Gemini
+обрывает генерацию по фильтру цитирования Google (`RECITATION`) — каталог всего
+батча деградирует в запасной нативный текст PDF, а слайды теряют верификацию.
+Модель с открытыми весами этим фильтром не ограничена и доступна через того же
+BYOK-провайдера `google-ai-studio`: в наших прогонах `google/gemma-4-31b-it:free`
+проходила батч, который рвал Gemini, с качеством на уровне
+`gemini-3.5-flash-lite`. Наблюдение сделано на небольшом числе прогонов и гарантией
+не является, но как последнее звено ротации такая модель полезна — при обрыве батч
+добирает она, а не запасной текст.
 
 ## Тесты