# eval/ — полигон TextMachine

Зона сессии «Полигон»: эмпирическая валидация допущений архитектуры (мерить, а не верить). Отчёты — `docs/experiments/NN-*.md` (методика + цифры + честные ограничения). `backend/` только читать; расхождения с architecture/research — пингом оркестратору в `docs/PROGRESS.md`. **`.env` не читать; `data/refusal_corpus/*` не открывать без прямой задачи владельца.**

## Карта

| Скрипт | Эксперимент | Заметки |
|---|---|---|
| `refusal_bench.py` | exp02; его `split_sentences`/`classify_output` = **приёмочный оракул** coverage-гейта Go (паритет закреплён Go-тестом; любое изменение — Python-first, лок-степ) | `run_refusal.sh` — однокоманда |
| `token_calc.py` | exp01 токен-калибровка (r-множители) | токенизаторы в `tokenizers/` |
| `editor_bench.py` + `build_editor_artifact.py` | exp04 бейк-офф редакторов | ✅ слепота починена (D13.5): рандомизация меток ПО ФРАГМЕНТУ (соль), ключ+цена в отдельном `--key` файле. Выбор grok-4.3 провизорен — exp04 §Оговорки |
| `coverage_precision.py`, `content_filter_probe.py` | exp07 precision гейта (0 FP/57) | |
| `cost_model_v2.py` | exp08 COGS (~$0.69/ранобэ) | цены датировать и перепроверять |
| `extract_bench.py` | exp06 экстракция терминов (спот=локаль/рендер=облако) | health-верификация каждого ответа — образец |
| `retrieval_bench.py` | эмбеддинг-бенч памяти (bge-m3 дефолт) | |
| `pilot/declmetric.py`, `pilot/memory_eval.py`, `pilot/kana_precision.py` | харнесс пилота Ф2.5 (exp09) | ✅ починен (D13.5): эхо-контроль, ПОЛНЫЕ выходы, **fidelity-ось** (cross-family судья), M0–M3, Go-синк 7 расхождений (self-test+адверсариально verified). `--self-test`/`--dry-run` без API. Инъекция = зеркало `memory.go` — синк с Go v3 выполнен (пакет №2: suppressUnboundedPhonetic + апостроф-фолд, adversarial parity); при расхождении верить Go. `kana_traps.json`+`trad2simp.txt` (508, hash-синк) |
| `webnovel_slice.py` | добор вне претрейна (r-коэф/эхо/coverage-precision) | одна команда по появлению `data/samples/webnovel/<lang>/*.txt`; блокируется корпусом graceful |
| `adaptive_*.py` | research/14 пробы (гибрид отклонён) | индикативные, не решения |
| `memory_hotpath.py` | УСТАРЕЛ (контракт до cc57c7b) — не переиспользовать | актуальное зеркало — `pilot/memory_eval.py` |
| `providers.json` | базовые URL/слаги для зондов | квирки — `docs/experiments/00-provider-quirks.md`, читать ПЕРЕД любым вызовом |

### 18+ / корпус-билдеры
| Скрипт | Эксперимент | Заметки |
|---|---|---|
| `explicit_judges.py`, `gu_corpus_build.py` | exp10 (violence-рука 18+) | корпус-строки в `data/` (gitignore); тексты вне git (Р8) |
| `jpm_corpus_build.py`, `en_corpus_build.py`, `ja_corpus_build.py` | exp11 (erotica-рука 18+, zh/en/ja пары) | `jpm`=金瓶梅 PD; en/ja — файлы владельца вне git |
| `mistral_fidelity.py` | exp02/D14.2 (Mistral base-fidelity ре-съёмка с полным персистом) | почему: первый Mistral-зонд потерял сырьё |
| `dialogue_precision.py` | exp07 package-2 (precision гейта на диалог-плотном срезе) | |
| `refusal_corpus_build.py` | exp02 (наполнение refusal-корпуса L0–L1) | explicit/L3 этим НЕ наполняются |
| `local_bench.py`, `llama_moe_bench.sh` | exp03 (локальный стенд) | dense через ollama / MoE через llama.cpp |

### Скрипты «дуги качества» 12 → 13 → 14 → 14b (эксперименты ЗАКРЫТЫ — отчёты см. `docs/experiments/README.md`)
Оставлены на месте намеренно: цитируются по пути из D-лога/PROGRESS/отчётов; перемещение рвёт грепы (D23.3). Прогонять повторно не нужно — вердикты ратифицированы (D30/D32/D37/D38).

| Семья | Эксперимент | Общие/особые модули |
|---|---|---|
| `exp12_*.py` (arms, blocks, candidate, extract, glossary_v2, judges, monitor, pack, reflow_demo, rootcause) | exp12 диагноз (закрыт D30) | `exp12_judges` **импортит** `exp12_pack` — семья неделима |
| `exp13_*.py` (aggregate, blind_stage, gates, judges, monitor, translate) | exp13 бейк-офф переводчиков (закрыт D32) | — |
| `exp13_seed_v2.py`, `exp13_seed_signoff.py` | **ЖИВОЙ провенанс сида v2** (воспроизводимый трансформ, цитируется D-логом D30.5) | НЕ спент, НЕ трогать/не перемещать |
| `exp14_*.py` (arms, judges, kpi, monitor, rank, regate, sizecurve) | exp14 рычаги качества (закрыт D37) | все импортят `exp14_common` (+ arms/sizecurve → `exp14_prompts`); `exp14_material` автономен |
| `exp14b_*.py` (arms, judge, monitor, score) | exp14b батарея смысл-трапов (закрыт D38) | реюзят `exp14_common`/`exp14_prompts` → **exp14 и 14b неразделимы** |

> **`exp14_common.py` + `exp14_prompts.py` — общий фундамент exp14 И exp14b.** Их не переносить/не переименовывать без переезда обеих семей вместе (иначе рвётся `import exp14_common`).

## Правила (выучены на ошибках)

1. **Провенанс данных:** results-файлы не перезаписывать ре-раном (урок exp02: сырьё 66 вызовов утрачено); каждый прогон — model id + дата + usage; сырые ВЫХОДЫ сохранять целиком.
2. **Претрейн-контаминация:** вся классика (Лу Синь/Акутагава/Уэллс) в претрейне моделей — C0 частично выдаёт канон, эхо систематично (deepseek 13/24 zh-чанков). Выводы на классике = предварительные; решающие замеры — на вебновелл-корпусе владельца.
3. **Тест ставится, только если его исход может перевернуть решение** и не установлен литературой (урок снятого exp05).
4. **LLM-судьи:** ≤2–3 семейства, 11+ повторов со свапом позиций, Bradley-Terry/медиана, судья не судит выходы своего семейства (D13.3); κ против человеческого IAA, не «средняя корреляция».
5. Env: `eval/.venv` (torch-cpu, sentence-transformers, openai, dotenv, pymorphy3); ключи скрипты читают из `eval/.env` сами. Стенд: GTX 1070 8GB — модель полигона `qwen3-abliterated:30b-a3b` в ollama не выселять без нужды; **localhost из-под прокси даёт 403** — для локальных вызовов no-proxy.
6. `data/` в .gitignore (коммитится только код) — критичные результаты дублируй цифрами в `docs/experiments/`.
7. **Аномалия провайдера ≠ повод гадать:** странный отказ (интермиттентный 404/5xx, новый `finish_reason`, молча игнорируемые параметры) → сначала официальная дока вендора (deprecations/changelog/status) + свежий /models живьём, потом диагноз; в отчёт оба слоя — наблюдение И вендор-факт с датой/URL. Урок: 404-флейки gemini-2.5-flash оказались предвестником EOL всей 2.5-серии 16.10.2026 (research/15 → фактчек 10.07; правило — шапка `00-provider-quirks.md`).

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