# Система разметки через GUI (автопрогоны)

Документ описывает практический контур, который используется оператором в интерфейсе
`История автопрогонов`: генерация вопросов, запуск прогонов, разметка ответов, закрытие кейсов и пост-анализ.

Дата актуализации: `2026-05-10`

---

## 1. Назначение

Цель системы:

1. Прогонять реалистичные пользовательские вопросы сериями.
2. Видеть фактические ответы ассистента в диалоговом формате.
3. Размечать качество ответов и управленческое решение по кейсу.
4. Формировать очередь фикс-пакетов без ручной выгрузки логов в чат.

---

## 2. Где находится источник истины

1. Канон поведения ассистента:
   - `docs/TECH/assistant_canon.md`
2. Реестр возможностей:
   - `docs/TECH/capabilities_registry.json`
3. Схема решений ручной разметки:
   - `docs/TECH/manual_case_decision_schema.json`

---

## 3. Основной сценарий оператора

### Шаг 1. Настройка генерации

Оператор задает:

1. режим генерации (`qwen_seed` / `codex_creative`);
2. количество вопросов;
3. "личность" автогенерации;
4. prompt выбранной личности;
5. автора генерации;
6. флаг сохранения кейс-сета в `eval_cases`.

Важно:

`qwen_seed` использует тот же активный LLM-контур, что и ответы ассистента
(тот же provider/model/baseUrl), но в роли генератора вопросов.

### Шаг 2. Генерация пачки

По кнопке "Сгенерировать пачку" создается generation record.

Запрос:

- `POST /api/autoruns/autogen/generate`

История доступна через:

- `GET /api/autoruns/autogen/history`

### Шаг 3. Ручная правка вопросов

Перед запуском оператор редактирует список "Вопросы к запуску":

1. удаляет нерелевантные;
2. правит формулировки;
3. оставляет итоговую пачку для прогона.

### Шаг 4. Запуск прогонов

Запуск идет асинхронно (на текущем этапе для `assistant_stage1`):

- `POST /api/eval/run-async/start`

В payload передается итоговый массив `questions[]`.

### Шаг 5. Live-мониторинг

Статус job обновляется polling-ом:

- `GET /api/eval/run-async/:job_id`

По мере обработки кейсов интерфейс подхватывает:

1. прогон;
2. кейсы;
3. сообщения вопрос/ответ в диалоге.

### Шаг 6. Разметка ответа

Размечается только сообщение `role=assistant`.

Через модалку задаются:

1. rating `1..5`;
2. comment;
3. `manual_case_decision`;
4. author.

Сохранение:

- `POST /api/autoruns/annotations`

### Шаг 7. Закрытие кейса

В комментариях доступен статус `resolved`:

- отметить выполненным;
- вернуть в открытые.

Запрос:

- `PATCH /api/autoruns/annotations/:annotation_id`

### Шаг 8. Фильтрация и пост-анализ

Доступно:

1. фильтр по `manual_case_decision`;
2. скрытие выполненных (`resolved=true`);
3. обновление пост-анализа и очередей фиксов.

Запросы:

- `GET /api/autoruns/annotations`
- `GET /api/autoruns/post-analysis`

---

## 4. Решения ручной разметки (`manual_case_decision`)

Текущее множество:

1. `covered_ok`
2. `covered_but_bad_answer`
3. `candidate_for_implementation`
4. `needs_routing_extension`
5. `out_of_scope_but_answer_softly`
6. `unsafe_question_limit_strictly`
7. `needs_dialog_policy_fix`
8. `needs_capability_registry_update`
9. `bad_test_case`

Queue mapping:

1. `covered_ok` -> `none`
2. `covered_but_bad_answer` -> `policy_fix`
3. `candidate_for_implementation` -> `routing_extension`
4. `needs_routing_extension` -> `routing_extension`
5. `out_of_scope_but_answer_softly` -> `soft_boundary`
6. `unsafe_question_limit_strictly` -> `safety_policy`
7. `needs_dialog_policy_fix` -> `policy_fix`
8. `needs_capability_registry_update` -> `capability_registry`
9. `bad_test_case` -> `testset_hygiene`

---

## 5. Хранилища данных

1. Аннотации:
   - `llm_normalizer/data/autorun_annotations/annotations.json`
2. История генерации:
   - `llm_normalizer/data/autorun_generators/history.json`
3. Кейс-сеты генератора:
   - `llm_normalizer/data/eval_cases/*.json`
4. Диалоги сессий:
   - `llm_normalizer/data/assistant_sessions/*.json`

---

## 6. API-карта раздела

### История прогонов

1. `GET /api/autoruns/history`
2. `GET /api/autoruns/history/:run_id`
3. `GET /api/autoruns/history/:run_id/case/:case_id/dialog`

### Разметка

1. `GET /api/autoruns/annotations`
2. `POST /api/autoruns/annotations`
3. `PATCH /api/autoruns/annotations/:annotation_id`
4. `GET /api/autoruns/manual-decision-schema`

### Пост-анализ

1. `GET /api/autoruns/post-analysis`

### Автогенерация

1. `GET /api/autoruns/autogen/personality-catalog`
2. `POST /api/autoruns/autogen/generate`
3. `GET /api/autoruns/autogen/history`

### Асинхронный запуск

1. `POST /api/eval/run-async/start`
2. `GET /api/eval/run-async/:job_id`

---

## 7. Тех-проверки после изменений

Минимальный чек:

1. Генерация пачки вопросов работает.
2. Async run запускается и отдает live-статус без падения.
3. В диалоге видны пары вопрос/ответ.
4. Аннотация сохраняется и редактируется повторно.
5. `resolved` переключается без рассинхрона в UI.
6. Фильтр "скрыть выполненные" корректно исключает `resolved=true`.
7. Пост-анализ показывает очереди и кандидатов.
8. Текст в интерфейсе читается без mojibake.
9. Старые сохраненные автопрогоны с C1-control mojibake в `history.json` и runtime job payload должны отдаваться через backend уже в восстановленной кириллице; контрольные примеры: `БОЛЬШОЙ ОБЩИЙ`, `АЛЬТЕРНАТИВА`.

Важно после правок encoding/autorun:

- перезапустить backend, чтобы UI получил новый repair-слой;
- обновить список автопрогонов в браузере;
- если replacement-character `U+FFFD` остается видимым, сравнить API payload `GET /api/autoruns/autogen/history` с состоянием frontend/browser cache.

---

## 8. Ограничения текущей версии

1. Async run ограничен `assistant_stage1`.
2. Качество live-данных зависит от заполнения session-файлов на стороне рантайма.
3. Пост-анализ основан на фактической ручной разметке; без нее очереди пустые.