# Инструкция по разметке relevance set v1

## Цель

Набор проверяет, находит ли поиск нужные документы по реальным формулировкам
пользователей. Он не должен подгоняться под текущую выдачу: сначала фиксируются
запросы и релевантные документы, затем считается baseline и меняется
ранжирование.

## Подготовка

Создайте игнорируемую Git рабочую копию:

```bash
mkdir -p data/search
cp backend/search/relevance-set-v1.template.json data/search/relevance-set-v1.json
```

Сохраните идентификаторы `ru-01`–`ru-25` и `ky-01`–`ky-25`. Заполняйте
`query` и `relevant_document_codes`; остальные поля и структуру JSON не меняйте.

## Выбор запросов

- Используйте 25 русских и 25 кыргызских запросов, реально заданных или
  сформулированных носителем языка для практической юридической задачи.
- Не переводите русский набор дословно на кыргызский: оба набора должны
  отражать естественные формулировки своего языка.
- Записывайте исходную формулировку без улучшения под поисковик. Допустимы
  разговорные слова, распространённые сокращения и опечатки.
- Не используйте персональные данные, закрытые материалы и сведения, которых
  нет в публичном корпусе Минюста.
- Не включайте запрос, если нельзя установить хотя бы один релевантный документ.
- Не повторяйте один информационный запрос в нескольких близких формулировках.

Проверьте разнообразие набора: названия и номера актов, вопросы по жизненной
или рабочей ситуации, короткие тематические запросы, органы принятия, статусы и
даты. Это ориентир, а не квота: реальные запросы важнее искусственного баланса.

## Критерий релевантности

Документ релевантен, если его текст или реквизиты непосредственно отвечают
информационной потребности запроса. Добавляйте все такие документы, а не только
первый результат.

Не отмечайте документ релевантным только потому, что он:

- содержит отдельные слова запроса;
- упоминает нужный акт без ответа на запрос;
- относится к близкой теме;
- является утратившей силу редакцией, когда запрос явно требует действующую
  норму, либо наоборот.

Если запрос допускает несколько самостоятельных правильных документов,
добавьте коды каждого из них. Код берите из поля `document_code`, а не из ID
фрагмента или редакции.

## Разметка одного запроса

1. Зафиксируйте исходную формулировку `query` и информационную потребность до
   оценки выдачи нашего поиска.
2. Юрист устанавливает релевантные акты по содержанию и реквизитам документов.
   Используйте ЦБД Минюста как авторитетный источник для проверки текста,
   статуса и редакции акта. Порядок выдачи ЦБД не является объектом оценки и не
   переносится в эталон.
3. Запишите уникальные `document_code` всех документов, которые прямо отвечают
   на запрос. Спорные документы передайте на независимую проверку.
4. Зафиксируйте согласованный набор до просмотра результатов OpenSearch и
   сохраните его отдельно от рабочих данных.
5. Проверьте запрос во внутренней лаборатории (`/review`): оцените фактические
   результаты OpenSearch в исходном порядке, сохраните снимок и комментарии.
   Лаборатория проверяет качество нашей поисковой системы, а не ЦБД Минюста.

Пример структуры (код условный):

```json
{
  "id": "ru-01",
  "language": "ru",
  "query": "как зарегистрировать общественное объединение",
  "relevant_document_codes": ["12345"]
}
```

## Проверка качества

Второй человек должен проверить формулировку, язык и полный список релевантных
документов для каждого запроса. Спорные случаи обсуждаются до единого решения;
результат голосования или непроверенную разметку в baseline не включайте.

Перед запуском убедитесь, что:

- заполнены ровно 50 записей: 25 `ru` и 25 `ky`;
- все запросы непустые и различаются по информационной потребности;
- у каждой записи есть хотя бы один уникальный `document_code`;
- язык запроса совпадает с `language`;
- JSON не содержит комментариев и дополнительных полей.

Оценщик дополнительно проверит структуру файла. После ручной проверки
зафиксируйте копию набора и не меняйте её при настройке поиска:

```bash
PYTHONPATH=backend python3 -m search.evaluate_relevance \
  data/search/relevance-set-v1.json \
  > data/search/baseline-v1.json
```

Разбирайте запросы с низкими Recall@10 и MRR@10 по отдельности. Меняйте веса,
анализаторы или словари только после сохранения исходного baseline.