# 🎯 Эксперимент «Резиновая уточка»

Проверить, как промежуточный запрос к MCP-серверу (отвечающему «quack») влияет на качество
рассуждений и точность ответов LLM — особенно «слабых» локальных моделей без встроенного
механизма thinking.

## 🧪 Методология: 4 параллельных сценария

Переменные, которыми мы управляем:

- **«Думать вслух»** (writing out reasoning): модель пишет свои рассуждения явно или нет.
- **«Дуб-инструмент»** (duck call): модель вызывает MCP-инструмент `quack` и получает кряк.

Чтобы отделить вклад каждой переменной, определяем **4 сценария**:

| #   | Сценарий   | Думает вслух |                              Зовёт утку                               | Смысл                                                                                                 |
| --- | ---------- | :----------: | :-------------------------------------------------------------------: | ----------------------------------------------------------------------------------------------------- |
| 1   | `control`  |     нет      |                                  нет                                  | Базовый «прямой ответ».                                                                               |
| 2   | `thinking` |    **да**    |                                  нет                                  | Контроль «думать вслух» (без утки). Отмеряет вклад проговаривания.                                    |
| 3   | `blind`    |      да      |                  **да** (не знает, что будет «кряк»)                  | «Слепая» уточка — чистый тест влияния утки на фоне уже включённого мышления.                          |
| 4   | `mentor`   |      да      | **да** (знает, что уточка отвечает только «quack», без полезной инфы) | «Уточка-помощник» — та же работа в паре, но модель заранее знает, что ответ будет бесполезным кряком. |

Схема интерпретации разниц в accuracy:

- `thinking − control` → вклад «проговаривания мыслей вслух».
- `blind − thinking` → вклад факта обращения к утке (на фоне «думать вслух»).
- `mentor − thinking` → вклад знания о том, что от утки будет только бесполезный «quack»
  (продолжает думать сам, не рассчитывая на подсказку).

> **Ограничение:** control и thinking структурно отличаются от сценариев с уткой. А вот
> `blind` и `mentor` намеренно сведены к одной структуре — различаются только тем, что
> mentor знает про «quack». Это держит сравнение чистым: эффект сводится только к
> информированности модели.

### Язык

Задачи и системные промпты — **на английском** (модели англоязычные). Отдельное
указание про язык ответа не даётся — модель естественно отвечает на английском,
раз и промпт, и задача сформулированы на нём.

### Формат ответа

**Свободный ответ** — модель формулирует финальный ответ естественно. Разметка — **ручная**
(reviewer оценивает каждый ответ). Никаких жёстких маркеров `ANSWER:`, никакого авто-парсинга.
Это осознанно: reviewer смотрит не только на финальное число, но и на ход рассуждений.

### Детерминизм

`temperature = 0` во всех сценариях (уже стоит по умолчанию в `ollama.chat`).

---

## Промпты (системные, английский)

> Общее требование к финалу во всех сценариях: **чёткий конкретный ответ на вопрос**,
> а не догадка и не запрос подтверждения («ну вроде так, подтверди» — недопустимо).

### control — прямой ответ

> You are an experienced assistant. Solve the user's problem as accurately as possible.
> Give a clear, concrete final answer to the question - a definite result, not a tentative
> guess or a request for confirmation.

### thinking — думать вслух, без утки (контроль)

> You are solving a difficult problem. Before giving your final answer, write out your
> reasoning step by step: your approach, each step, and any doubts or mistakes you notice
> along the way. Then give a clear, concrete final answer to the user's question - a
> definite result, not a request for confirmation.

### blind — «слепая» уточка

> You are solving a problem that the user asked you. To reason better, you use a separate
> tool named 'quack': you call it yourself to state your thinking out loud. Call the tool
> and spell out your approach, each step, and any doubts or mistakes you might be making,
> then wait for its short reply. Do not ask the user to confirm anything, and do not guess
> or invent the tool's reply yourself - the tool answers on your behalf. After the tool's
> reply, give the user a clear, concrete final answer to the question.

> **Важно для чистоты:** модель НЕ должна знать, что инструмент — уточка, отвечающая «кряк».
> Поэтому **описание инструмента (tool schema) нейтрально** — оно не раскрывает «только
> quack». Модель вызывает `quack` сама через tool-call, чтобы проговорить мысли, полагая,
> что получит короткий полезный ответ инструмента. Роли чётко разделены: юзеру — итоговый
> ответ, инструменту — озвучка мыслей. Модель НЕ строит диалог сама с собой и НЕ ждёт
> подтверждения от юзера.

### mentor — уточка-помощник

> You are solving a problem that the user asked you. To reason better, you use a separate
> tool named 'quack': you call it yourself to state your thinking out loud. Call the tool
> and spell out your approach, each step, and any doubts or mistakes you might be making,
> then wait for its short reply. Do not ask the user to confirm anything, and do not guess
> or invent the tool's reply yourself - the tool answers on your behalf. Note: the tool
> 'quack' is a rubber duck and will only ever reply with just 'quack' - it gives no useful
> information. Treat it as a way to voice your thoughts out loud, not as a source of
> answers. After the tool's reply, give the user a clear, concrete final answer to the
> question.

> **Ключевое:** blind и mentor структурно идентичны и отличаются **только** тем, что mentor
> заранее знает, что получит только «quack» без полезной информации. Никаких дополнительных
> директив (`MUST`, «double-check», «find bugs») — иначе они бы загрязняли сравнение.

---

## ⏱ Таймауты и ретраи

- На один вызов модели — **таймаут 60 секунд** (1 минута).
- При сбое/таймауте запрос **повторяется до 3 раз всего** (1-я попытка + 2 ретрая).
- Если после всех попыток успеха нет — задача **пропускается** (строки в отчёте нет).

---

## 📊 Метрики

1. **Accuracy** — доля правильных ответов (по ручной разметке reviewer'а) в каждом сценарии.
   Сравнение: `thinking−control`, `blind−thinking`, `mentor−thinking`.
2. **Duck usage** — вызвал ли модель `quack` в blind/mentor (duckUsed, toolCalls). Те модели,
   что не зовут утку, деградируют до `thinking` — это фиксируем как отдельное явление.
3. **Объём рассуждений** — prompt/gen/duck токены на сценарий (структурированность текста).

---

## 🤖 Модели (локально, GTX 1660 Super 4GB)

- `llama3.2:3b`
- `qwen3:1.7b`
- `qwen3:4b`
- `granite4.1:3b`
- `phi4-mini:3.8b`

> Известное явление: `phi4-mini` и `granite4.1` могут не вызывать `quack` — тогда их
> blind/mentor вырождаются в `thinking`. Это часть изучаемого феномена и фиксируется по
> `duckUsed`.

## 📋 Процесс

1. `pnpm eval:run` — прогнать модели по 4 сценариям (23+ задач на английском). `correct: null`.
2. `pnpm eval:review` — ручная разметка каждого ответа (y/e/Enter/слово).
3. `pnpm eval:html` — собрать отчёт: сводные таблицы и разбивка по задачам, accuracy по
   размеченным, pending для неразмеченных.
4. (Сайт) скопировать `report.json` в `apps/web/static/report.json` для страницы `/reports`.