Rework user-facing learning materials and quickstart flow

Author: Yurashku

README.md

@@ -0,0 +1,99 @@
+# Как интерпретировать результаты OPE в Policyscope (практический RU-гайд)
+
+Этот документ про **практическую интерпретацию** output'ов `compare_policies(...)`:
+как читать `V_A`, `V_B`, `Delta`, CI, `p_value`, diagnostics и `trust_level` без переобещаний.
+
+## 1) Базовые величины
+
+- `V_A` — оценка policy value для logging/behavior policy **A**.
+- `V_B` — оценка policy value для target/candidate policy **B**.
+- `Delta = V_B - V_A` — оценка policy value difference (эффект замены A на B).
+
+Практически:
+- `Delta > 0` означает ожидаемое улучшение метрики при переходе на B;
+- `Delta < 0` означает ожидаемое ухудшение;
+- величина `Delta` важнее «просто знака»: бизнес-значимость и статистическая неопределённость должны рассматриваться вместе.
+
+## 2) Что означают CI и p-value (и что они НЕ означают)
+
+- `Delta_CI` — доверительный интервал для `Delta` (bootstrap-based в текущей библиотеке).
+- `p_value` — сигнал против `H0: Delta = 0` в выбранной процедуре инференса.
+
+Что важно:
+- Узкий CI обычно лучше, чем широкий (меньше неопределённости).
+- `p_value` **не** показывает размер эффекта.
+- CI/p-value **не** доказывают причинную истинность при нарушении предпосылок (особенно overlap/support).
+- «Статистически значимо» не равно «безопасно для прод-раскатки».
+
+## 3) Почему diagnostics нужны вместе с инференсом
+
+Даже если CI выглядит «хорошо», OPE может быть хрупким при плохом overlap.
+Поэтому смотреть нужно на diagnostics:
+
+- replay overlap;
+- ESS / ESS ratio;
+- tail-метрики весов (heavy tails, extreme max weights);
+- clip/switch доли для методов с клиппингом/переключением.
+
+CI и diagnostics отвечают на **разные** вопросы:
+- CI/p-value: статистическая неопределённость выбранного оценщика;
+- diagnostics: риск того, что сама постановка OPE нестабильна на этих логах.
+
+## 4) Что означают плохие diagnostics
+
+- **Низкий overlap / низкий replay support**: B часто выбирает действия вне области данных A.
+- **Низкий ESS**: фактически «мало эффективных наблюдений» после взвешивания.
+- **Тяжёлые хвосты весов**: оценка чувствительна к немногим объектам, рост variance/нестабильности.
+
+Практический вывод: такие результаты чаще подходят как **directional evidence** / screening, а не как финальное основание для крупного продуктового решения.
+
+## 5) `trust_level`: полезный сводный флаг, но не гарантия
+
+`trust_level` агрегирует warnings/риски в компактный сигнал (`ok`, `caution`, `elevated_concern`).
+
+Что это даёт:
+- быстрое ранжирование «насколько осторожно читать результат».
+
+Что это **не** даёт:
+- не сертифицирует «можно пропустить A/B-тест»;
+- не заменяет экспертную проверку предпосылок и бизнес-контекста.
+
+## 6) Когда OPE достаточно, а когда нужен A/B
+
+OPE полезен для:
+- предварительного отбора кандидатов;
+- приоритизации гипотез;
+- отсева явно слабых политик до онлайн-теста.
+
+OPE обычно **недостаточно** как единственный аргумент, если:
+- ожидается крупный бизнес-риск;
+- overlap слабый или diagnostics тревожные;
+- решение необратимо/дорого.
+
+В таких случаях OPE + онлайн-эксперимент — более надёжная практика.
+
+## 7) Практический rule-of-thumb по выбору оценщика
+
+- **Replay**: baseline, сильно зависит от пересечения support.
+- **IPS / SNIPS**: взвешенные методы; чувствительны к overlap и хвостам весов.
+- **DM**: зависит от качества outcome-модели (model-dependent).
+- **DR**: частый practical default при приемлемом качестве nuisance-компонент.
+- **SNDR / Switch-DR**: полезные robustness-варианты при нестабильных весах.
+
+Стартовая рекомендация в большинстве прикладных кейсов:
+1. начать с `dr`;
+2. проверить diagnostics + `trust_level`;
+3. сравнить с `sndr` / `switch_dr` при признаках весовой нестабильности;
+4. трактовать итог как directional evidence, если риски высоки или overlap слабый.
+
+## 8) Мини-чеклист ответственной интерпретации
+
+Перед выводом «B лучше A» проверьте:
+
+1. `Delta` практически значим по масштабу?
+2. `Delta_CI` не слишком широкий?
+3. diagnostics без критичных warning?
+4. `trust_level` не сигналит elevated concern?
+5. есть план онлайн-верификации для high-stakes решений?
+
+Если ответы 3–5 отрицательные — усиливайте осторожность и не заменяйте A/B-тест одним OPE.