textmachine/docs/architecture/02-mvp-plan.md

План MVP (v2, 2026-07-04)

Цель MVP (бриф, п. 24): бэкенд переводит целую книгу целиком — консистентно, дёшево, с учётом стоимости. Интерфейс — CLI; HTTP API закладываем как тонкий слой (Фаза 3), IDE-фронт — после бэкенда. v2 — после адверсариального ревью: фазы перебалансированы, приёмка сделана проверяемой, добавлены интерим-правила для 18+ и спецификации, блокировавшие старт кодинга. Реалистичный горизонт — 10–11 недель (было «8», критики показали, что пилот не влезал).

Дорожка данных (параллельно всем фазам, владелец + сессия «Полигон»)

Закупка/подбор лицензионных изданий для золотого набора, выравнивание, глоссарии, отбор 25–35 глав пилота, refusal-корпус 50–100 фрагментов, замеры токенизации. Стартует с недели 1 — к пилоту (Фаза 2.5) данные должны быть готовы.

Фаза 0 — Каркас (нед. 1–2)

Монорепо Go (backend/). Портирование ядра из vojo/apps/ai-bot:

• pkg/llm: интерфейс LLMClient, OpenAI-совместимый транспорт (retry/backoff), адаптеры DeepSeek/Qwen/GLM/xAI/Gemini/llama-server; новое: нативный Anthropic-адаптер (cache_control), поддержка prompt caching в структуре запроса. Batch API → Фаза 2; SSE-стриминг → Фаза 3 (нужен только IDE-фронту).
• pkg/ledger: цены в конфиге (с датой проверки), биллинг по usage (+reasoning-токены), reserve/settle, потолки $ на книгу/день.
• pkg/obs: trace_id, структурные логи, request_log (per-книга/глава/чанк/стадия/роль/модель, $, latency, cache-hit, вердикты гейтов).
• pkg/store: SQLite (modernc.org/sqlite, без нативных расширений) + идемпотентные миграции; durable jobs (глава×стадия) + чанк-чекпоинты (Р6: каждый сырой ответ LLM персистится после settle; snapshot контекста на джобу; kill -9-тест — часть приёмки).
• Конфиг проекта книги = translation brief (языковая пара, жанр, аудитория, 18+ да/нет, слайдер Venuti, хонорифики, транскрипция, сноски); brief_hash входит в ключ TM.
• Приложение к фазе: YAML-конфиг ядра C1 (+скелет C2) — фиксирует границу «конфиг vs раннер» (Р2) до начала Фазы 1.
• Эмпирическая проверка cache-поведения: DeepSeek direct + топ-2 ru-агрегатора (пробрасывают ли cache-hit тарифы) — вход для экономики Р5.

Приёмка: tmctl translate --config book.yaml гоняет один чанк draft→edit с полным учётом $ в request_log; kill -9 теряет максимум один вызов.

Фаза 1 — Перевод целой книги (нед. 3–5)

• Импорт/чанкинг по спеке: txt/epub; epub v1 = извлечение текста глав по spine, экспорт простым xhtml (инлайн-разметка/ruby-фуригана не сохраняются — честное ограничение v1); чанк 1–2k токенов по границам абзацев; перекрытие — read-only контекст (повторно не переводится, дедупликации при склейке нет по построению).
• Банк памяти v1 (SQLite на книгу): глоссарий (схема Р3, авто-decl при коммите) с автоэкстракцией кандидатов; series-bible-lite (gender + матрица ты/вы); резюме глава→арка→книга; STM; TM-кэш; селективная инъекция (ключи/алиасы/леммы, без эмбеддингов). Батч-подтверждение терминов раз в главу; в безлюдном режиме auto→approved с журналом.
• Пайплайн C1: Analyst (map-reduce по книге) → Terminologist → per-глава/per-чанк: сборка контекста (кэшируемый префикс по Р5) → Translator (DeepSeek V4 Flash) → Editor → гейты → эскалация в пределах премиум-бюджета → коммит чанка; на границе главы — обновление резюме, подтверждение терминов, телеметрия главы.
• QA-гейты Фазы 1 (Go, без морфологии): CJK-артефакты, глоссарная консистентность (процедура из Р7), coverage-гейт v1 (регэксп-сегментация предложений, соотношение длин, blacklist refusal-паттернов; валидируется мини-набором 20–30 фрагментов с выпиленными предложениями). В TM коммитится только вывод, прошедший гейты. «Флаг редактору» = секция в отчёте + ненулевой exit code (приёмка допускает N флагов).
• Интерим-правило 18+ (до NSFW-роутера Фазы 2): приёмочный корпус — только SFW; при 18+: да в brief — Anthropic принудительно исключается из роутинга книги, эскалация без Opus (GLM/Kimi/Gemini), включён regex-детектор отказов перед коммитом в TM. Редактор Фазы 1 по умолчанию — GLM-5/Kimi (Sonnet — только SFW-книги и прямые ключи).
• Режим онгоинга (Р9, сегмент «ИИ-фабрик»): tmctl add-chapters — дозагрузка новых глав в существующий проект с наследованием глоссария/резюме/series bible.
• Экспорт: txt/epub + отчёт (стоимость по стадиям, cache-hit по стадиям, метрики, журнал творческого вклада, флаги).

Приёмка: SFW-том ранобэ (~150k токенов) end-to-end за один запуск с резюмируемостью; COGS: стандарт на DeepSeek ≤ $0.6, премиум-микс ≤ $5 (два порога вместо неопределённого «стандарт-микса»); глоссарная консистентность approved-имён ≥98% по процедуре Р7; coverage-гейт ловит ≥90% искусственных пропусков на валидационном мини-наборе. (Род/ты-вы — приёмка Фазы 2, когда появится гейт по series-bible-lite.)

Фаза 2 — Качество: судья, NSFW, гейты второй очереди (нед. 6–8)

• Judge-роль (шкала Комиссарова, пара судей), режимы C2/C3 как конфиги; Batch API (OpenAI-стиль + Anthropic Message Batches) для батчуемых стадий (Analyst/Terminologist/судья/книжный QA).
• NSFW-роутер: локальный классификатор 0–3, каналы A/B, channel-aware эскалация, refusal-мониторинг с автопереносом, детектор молчаливых вырезаний; refusal-бенчмарк из дорожки данных.
• Интеграция llama-server (скрининг, abliterated-переводчик канала B, эмбеддинги bge-m3 — второй эшелон инъекции).
• Python-сайдкар качества: CometKiwi + морфодетектор канцелярита (pymorphy/Natasha, чек-лист Галь) + гейт ты/вы и рода по series-bible-lite; роли второй очереди: Line Editor, Continuity Editor, анти-translationese пасс.
• Eval-харнесс (паттерн routereval): golden-set реплей, свип порогов эскалации.
• Генерация аннотаций/обвязки главы для заливки (дешёвая фича, паттерн топов Rulate).

Приёмка: 18+ книга проходит пайплайн без молчаливых потерь (проверено детектором + refusal-бенчмарком); гейт рода/ты-вы работает на series-bible-lite; C2/C3 запускаются конфигом.

Фаза 2.5 — Пилот 4 рук (нед. 8–10, elapsed 2–3 недели)

По протоколу Р2/gap-3: C0/C1/C2/C3 на 25–35 главах zh/ja/en→ru (данные готовы из дорожки данных), человеческие попарные сравнения (внешние редакторы 20–40 ч) + панель LLM-судей чужих семейств с человеческим переводом как якорем. Решение о ядре пайплайна; 2–3 главы 18+ в корпусе — замер отказов по ролям.

Фаза 3 — Продуктовизация (после MVP)

HTTP API + SSE для IDE-фронта; выравнивание Bertalign (параллельное чтение, полноценный импорт reference-переводов прошлых томов; до этого — упрощённый импорт бэк-каталога парами глав); TMX/TBX; BYOK-пресеты агрегаторов; биллинг ЮKassa/СБП; batch-планировщик внепиковых окон DeepSeek; кандидаты из Р2: консультант поп-культуры, tool-calling, webfetch культурного контекста.

Вне скоупа MVP

IDE-фронтенд (закладываем только API), B2B white-label, дистилляция своей 7–14B модели (логируем long-CoT синтетику с первого дня — рецепт DRT, но не обучаем), ru→en направление (следствие для выручки — см. Р9), автоматическая публикация куда-либо (Р8).

Метрики успеха MVP

1. COGS тома ранобэ: стандарт ≤ $0.6, премиум-микс ≤ $5 (контур прямых ключей; cache-hit — по стадиям, справочно).
2. Глоссарная консистентность approved-терминов ≥98% (процедура Р7); ноль молчаливых пропусков, подтверждено coverage-гейтом, отвалидированным на мини-наборе.
3. Качество: статистически значимый win rate >50% (биномиальный тест, α=0.05, ≥150 человеческих попарных сравнений) против DeepSeek+селективный глоссарий (честный baseline уровня VseGPT, не соломенный «сырой DeepSeek»); 70% — aspirational-цель, калибруется пилотом.
4. Резюмируемость: kill -9 в середине главы → продолжение с потерей максимум одного LLM-вызова.