# TextMachine — документация

Проект: бэкенд (позже — фронтенд-IDE) художественного перевода крупных текстов (книги, ранобэ, вебновеллы; zh/ja/en→ru) через мультиагентный пайплайн поверх LLM API. Стартовый бриф: [../START_PROMT.MD](../START_PROMT.MD). Онбординг Claude-сессий: [../CLAUDE.md](../CLAUDE.md).

Ключевые цели:
1. Максимальное художественное качество — победить «нехудожественность» AI-переводов.
2. Низкая себестоимость: пайплайн из дешёвых моделей + редкие адресные вызовы дорогих.
3. Банк памяти / глоссарий на всю книгу — консистентность имён, терминов, стиля.
4. Обработка 18+ с учётом цензуры провайдеров (мультипровайдерность).
5. Телеметрия токенов/стоимости/качества с первого дня.

## Структура

- `architecture/` — синтез. **Источник истины по решениям — [`05-decisions-log.md`](architecture/05-decisions-log.md) (D1–D35); при конфликте с любым доком он выше.**
  - `01-decisions.md` — принципы Р1–Р10; `02-mvp-plan.md` — фазы и приёмка (v3, 09.07); `03-implementation-notes.md` — контракты Фазы 0; `04-unhappy-paths.md` — ~70 режимов отказа → механизм; `06-memory-risk-registry.md` — реестр рисков банка памяти; **[`07-strategic-review.md`](architecture/07-strategic-review.md) — стратегический аудит (09.07): вердикт end-to-end, топ-риски, курс-коррекции**; `components.puml`/`pipeline.puml` — диаграммы v3 (владелец смотрит PlantUML-расширением VS Code; вручную НЕ рендерить).
- `experiments/` — эмпирика «Полигона»: `00-provider-quirks` (читать перед любым вызовом провайдера), `01-token-calibration`, `02-refusal-benchmark`, `03-local-stand`, `04-editor-quality`, `06-local-extraction`, `07-coverage-precision`, `08-cost-model-v2` (актуальная денежная модель), `09-pilot-protocol` (пилот Ф2.5 + поправки D13), `10-explicit-benchmark` (18+ violence-рука канала B), `11-erotica-benchmark` (erotica по трём парам/регистрам — закрытие D14.4, D22).
- `research/` — фактура исследований 04–05.07: `01–10` базовые, `11-gap-*` добор критиком, `12-*` режимы отказа/отзывы/таксономии (+ два внешних материала с провенанс-шапками), `13` валидация памяти, `14` адаптивная память, `15` голос и состояние (принят, D21), **`16` ридер-IDE (принят с ревью-шапкой, D29)**, **`17` внешняя критика GPT-5.6 (принят с ревью-шапкой, D25)** — у 16/17 читать шапку прежде тела. ⚠ Часть под superseded-баннерами (01/02/03/04/05/09 и gap-1/2/5) — **читай баннер прежде содержимого**.
- `PROGRESS.md` — **журнал** (CURRENT-STATE сверху, ниже хронология; НЕ источник решений).
- **Активные хендофф-промты** (пивот D35→D37, очередь «мерить→строить»): [`ORCHESTRATOR_SESSION_PROMPT.md`](ORCHESTRATOR_SESSION_PROMPT.md) (роль оркестратора) · [`POLYGON_PACKAGE4_SESSION_PROMPT.md`](POLYGON_PACKAGE4_SESSION_PROMPT.md) (**ОТЛОЖЕН, пилот-residual:** task-1 закрыт exp13/D32; открыты D22.6 судья-дублёр + D25.7 echo-кал + пилот-пре-рег + P4-хвост — для пилота, не exp14). [`BACKEND_INFRA_PACK_SESSION_PROMPT.md`](BACKEND_INFRA_PACK_SESSION_PROMPT.md) (**СЛЕДУЮЩИЙ, ВЫДАН — D38.1, ПЕРВЫЙ «строить»:** san-класс CJK-в-выходе + экспорт-фикс флагнутого-в-пусто D35.4a + число/omission-гард; ∥ reseed-глоссарий промоут грейды А/Б/В/Г + 四代族长 approved) → единый resnapshot → пере-прогон 3–10 глав (дискурс-промпт glm; editor-swap mistral/deepseek-pro как арм) → чтение владельца (стейдж Б/В D15.2 — свежий промт, дизайн = спека v3.1). Закрытые в `archive/prompts/`: exp14b (смысл-батарея)→D38, exp14 (нарезка×промпт+blind-eval)→D37, research/18-ресёрчер→D36, exp13→D32, санитайзер-фикс→D33.1, приёмка v2 (цикл ЗАКРЫТ D35), D152-этап-А→D33, пакеты №3–5, erotica, «Голос», r/17, r/16, exp12→D30.
- `archive/` — закрытые сессионные промты (только история, инструкции оттуда не исполнять).

## Статус (2026-07-12, пост-пивот D35)

Фаза 0 ✅; Ф1-инфра ✅ (D20–D28); приёмка этап A ✅ (D24). **Путь D26→D35 «качество-первым»:** флип D1 моно→БИЛИНГВ (D30), reflow + output-санитайзер (D30/D33), сид v2 подписан (D34), переводчик flash сохранён (exp13/D32). **Пере-прогон 25 глав связкой выполнен; вердикт владельца: «лучше, но крайне слабо художественно» (2 претензии: абзацы/конвенции + понимание связей).** **ПИВОТ D35:** цикл прогонов ЗАКРЫТ (инфра ✅/читаемость ❌ = не провал; диагноз «Ф2-недострой + near-term промпт/нарезка-рычаги, не баг» верифицирован). Планка = 2 претензии (интерим). Очередь «мерить→строить»: **ресёрч рычагов качества (research/18 Claude + ChatGPT — ждут ревью оркестратором) → полигон-эмпирика (нарезка×промпт + диагностик-фронтир-арм + fidelity re-gate) → бэкенд под доказанный ROI.** Вопрос эмпирики: потолок в дешёвых моделях или в нашей нарезке/промпте. Трек: дешёвые сейчас, фронтир потом (D30.7). Решающая точка — пилот Ф2.5; блокеры — билингв-якорь/аннотаторы ≥3 (D25.9-Q1), корпус, судья-дублёр 18+ (D22.6). Ключ xAI: единый, data-sharing, off перед продом (D27).

## Доступные ключи от моделей
DEEPSEEK_API_KEY, ZAI_API_KEY, KIMI_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, XAI_API_KEY, MISTRAL_API_KEY