textmachine/eval/README.md

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