Хакатон-задача: умный подбор подрядчиков

1. Описание решения

Сервис помогает организатору мероприятия в Казахстане выбрать до трёх подрядчиков из существующего каталога. Он проверяет город, категорию, дату, бюджет, формат, а при необходимости — язык и длительность. Пользователь получает карточки с начальной ценой и конкретными объяснениями либо сообщение, почему подходящих вариантов нет.

Единая рабочая сборка находится в корне репозитория, в ветке main. Выполняйте все команды рядом с app.py и requirements.txt. Ядро, ранжирование и интерфейс объединены; отдельная копия приложения не требуется.

Путь ready_project/ сохранён для совместимости и запускает те же корневые файлы; самостоятельной копии приложения там нет. Для передачи нужен весь репозиторий.

Маршрут для жюри: установка — раздел 6 → запуск — раздел 9 → пять готовых проверок — раздел 10. Редактировать файлы не требуется.

2. Основной сценарий работы

1. Выберите готовый пример или самостоятельно заполните параметры мероприятия.
2. Нажмите «Подобрать подрядчиков».
3. Система исключит неподходящих кандидатов и сравнит оставшихся.
4. На экране появятся максимум три карточки с объяснениями, число допустимых кандидатов и причины исключения остальных.

Если подходят один или два подрядчика, список не дополняется. Отсутствие категории в городе и отсутствие кандидатов, прошедших условия, показаны как разные результаты. Готовые входные данные и точные ответы приведены в разделе 10.

3. Архитектура

Форма → валидация → город и категория → обязательные фильтры
      → ранжирование допустимых → первые 3 → объяснения → экран

Компонент	Назначение
app.py	Форма Streamlit, готовые примеры и отображение ответа без повторной сортировки
contracts.py	Проверка структуры профилей и запросов, допустимых дат и значений
data_loader.py	Чтение и проверка CSV/JSONL; ошибки файла и записей не скрываются
recommender.py	Обязательные фильтры, статистика причин, вызов ранжирования и ограничение до трёх
ranking.py, scoring.py	Устойчивый порядок допустимых кандидатов
explanations.py, semantic.py	Подтверждающие факты и буквальные цитаты; дополнительный режим сравнения по embeddings
run_demo.py	Запуск настоящего подбора из терминала и сравнение с сохранёнными ответами

Компактная структура рабочей части репозитория:

hack-6b3754fc-oyan-ai/
├── README.md
├── app.py
├── contracts.py
├── data_loader.py
├── recommender.py
├── ranking.py / scoring.py
├── explanations.py / semantic.py
├── requirements.txt / requirements.lock
├── demo_queries.json
├── run_demo.py
├── BUILD_SOURCES.json
├── docs/
│   ├── hackathon dataset anonymized .csv
│   ├── demo_responses.json
│   ├── demo.md
│   └── acceptance.md
└── tests/

Данные. Включён официальный CSV с 66 профилями. Из них 13 синтетических, у 8 город и у 18 цена проставлены при подготовке данных. Календарь ограничен 23.09.2026–31.12.2026. UI показывает соответствующие подписи; synthetic=false не называется независимой проверкой подрядчика.

Обязательные фильтры. После выбора города и категории проверки идут в порядке: занятость → начальная цена → формат → указанный язык → указанная длительность. Равенство цены бюджету и длительности максимуму проходит. max_hours=null означает непривязанность к присутствию, а не бесконечное время. Хорошее описание не позволяет обойти фильтры. В итоговой статистике каждый исключённый учтён один раз, по первой причине.

Ранжирование и повторяемость. По умолчанию используется baseline: score = round(-float(price_from_kzt), 6). Сортировка: score по убыванию → начальная цена по возрастанию → строковый ID. Это выбор по начальной цене среди допустимых, не оценка качества. При одинаковых запросе, данных и режиме порядок сохраняется; это проверено повтором, перестановкой входного списка и отдельным процессом.

Объяснения. Карточка содержит цену и разницу с лимитом, сведения о формате, запрошенных условиях и цитату из описания. Для фактов сохраняются поля-источники; цитаты проверяются как буквальные фрагменты. Если приведённые факты совпадают, модуль сообщает об этом вместо выдумывания различий.

4. Используемые технологии

Технология	Назначение
Python 3.12	Логика загрузки, отбора, ранжирования и проверки
Streamlit 1.58.0	Веб-интерфейс и автоматические проверки действий на экране
Pydantic 2.13.5	Строгая валидация профилей и запросов
pytest 9.1.1 и стандартный unittest	Модульные и сквозные тесты
CSV и JSON	Исходный каталог, запросы и сохранённые ответы

AI в основном запуске: нейросетевой inference не используется. В baseline выбор цитат лексический, а объяснения формируются шаблонами из фактов.

В коде сохранён дополнительный semantic-режим с косинусной близостью заранее подготовленных embeddings. Для подготовки используется sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2, ревизия e8f8c211226b894fcb81acc59f3b34ba3efd5f42. Команда offline-подготовки кэша v2 включена в semantic.py; веса модели и готовый кэш остаются вне Git. Режим не является частью описанного ниже baseline-запуска. На запросе код читает кэш, а не вызывает внешнюю модель. Подробнее — документация модуля.

5. Требования для запуска

• Python 3.12 с venv и pip. Проверенная версия — 3.12.13 на macOS; результаты проверки итоговой сборки — в протоколе приёмки.
• Git для клонирования и современный браузер для интерфейса. При получении архива Git не нужен.
• Интернет для первоначальной установки пакетов; для локального baseline-подбора внешний сервис не требуется.
• Доступ к GitHub-репозиторию при клонировании. Жюри можно передать архив всего репозитория без .git и локального окружения.

API-ключи, Docker, база данных, GPU и дополнительные сервисы для основного запуска не нужны. Итоговая проверка установки описана для macOS. Windows-инструкция приведена отдельно; повторная приёмка этой итоговой сборки на Windows не выполнена. Отдельный минимальный объём RAM или диска не измерялся.

6. Установка

Получить проект

Для SSH-клонирования нужен настроенный доступ GitHub. Публичный доступ жюри без учётной записи не подтверждён; при отсутствии доступа передайте архив итогового коммита.

git clone --branch main [email protected]:BAITC-Hacks/hack-6b3754fc-oyan-ai.git

cd hack-6b3754fc-oyan-ai

Если получили архив, распакуйте его и откройте терминал в корне проекта, рядом с requirements.txt.

macOS / Linux

python3.12 -m venv .venv

source .venv/bin/activate

python -m pip install -r requirements.lock

Windows PowerShell

py -3.12 -m venv .venv

.\.venv\Scripts\python.exe -m pip install -r requirements.lock

Готовые команды Windows из корня:

.\.venv\Scripts\python.exe -m streamlit run app.py --server.address 127.0.0.1 --server.headless true --browser.gatherUsageStats false --server.port 8504
.\.venv\Scripts\python.exe run_demo.py --verify

В следующих командах для Windows замените python на .\.venv\Scripts\python.exe; активация окружения не нужна.

7. Зависимости

Прямые зависимости и их версии находятся в requirements.txt. Команда установки приведена выше. requirements.lock фиксирует полный состав зависимостей, первоначально собранный для Windows/Python 3.12. Установка этого lock также проверена в новом окружении macOS/Python 3.12.13; совместимость с другими платформами не заявляется.

Проверка согласованности установленного окружения:

python -m pip check

Ожидаемый результат: No broken requirements found; фактический протокол итоговой проверки — в docs/acceptance.md. Лицензии ключевых компонентов: Streamlit — Apache-2.0, Pydantic и pytest — MIT. Каталог предоставлен организатором; отдельная лицензия на его последующее публичное распространение в репозитории не указана.

8. Параметры окружения

Для локального запуска дополнительные переменные окружения не требуются. Файл .env не нужен и автоматически приложением не загружается. Реальные секреты для запуска отсутствуют.

Переменная	Обязательна	Назначение	Пример
CONTRACTORS_DATA	Нет	Другой путь к CSV/JSONL для UI; по умолчанию включённый CSV в docs	docs/hackathon dataset anonymized .csv
RANKING_MODE	Нет	Режим фиксируется при старте; по умолчанию baseline	baseline
RANKING_SEMANTIC_CACHE	Только для semantic	Путь к заранее подготовленному кэшу; он не включён в сборку	embeddings.json
RANKING_SEMANTIC_SHA256	Только для semantic	Контрольная сумма именно этого кэша	SHA-256 подготовленного файла, 64 шестнадцатеричных символа

Только дополнительные тесты читают SEMANTIC_TEST_MODEL_DIR, SEMANTIC_DEMO_CACHE, SEMANTIC_DEMO_CACHE_SHA256 и P2_CORE_DIR. Для обычных тестов их задавать не нужно: проверки без модели/кэша явно пропускаются. Режим semantic с отсутствующим или неверным кэшем завершится ошибкой, без скрытого переключения алгоритма.

9. Запуск проекта

Основной способ — веб-интерфейс. Выполняйте из корня репозитория в активированном окружении:

python -m streamlit run app.py --server.address 127.0.0.1 --server.headless true --browser.gatherUsageStats false --server.port 8504

Не закрывая терминал, откройте http://127.0.0.1:8504 в браузере на том же компьютере. Сначала видна форма; карточки появятся после нажатия «Подобрать подрядчиков». Остановка сервера — Ctrl+C. Для следующих команд используйте второй терминал с тем же окружением.

Альтернатива без браузера — выполнить основной demo-запрос и вывести полный JSON-ответ:

python run_demo.py --case dense

10. Проверка основного сценария: за 2 минуты

Шаг 1. Запустить

Запустите веб-интерфейс командой из раздела 9 и откройте его адрес. Для терминального варианта используйте python run_demo.py --case dense — он выполняет тот же настоящий recommend(), без тестового адаптера.

Шаг 2. Ввести данные

В списке «Готовый пример для проверки» выберите «1. Ведущие: выбор трёх из нескольких». Поля заполнятся автоматически. Полный запрос:

{
  "city": "Алматы",
  "date": "2026-10-06",
  "event_type": "корпоратив",
  "category": "Ведущий",
  "budget": 1000000,
  "duration": 6,
  "language": "русский"
}

Шаг 3. Выполнить действие

Нажмите «Подобрать подрядчиков». Выбор примера только заполняет форму: ответ вычисляется ядром при нажатии кнопки.

Шаг 4. Сверить результат

Должно появиться сообщение «Условия проходят 6, показываем 3.» и карточки в порядке из следующего раздела. Повторное нажатие с теми же параметрами сохраняет порядок.

Дополнительные готовые проверки

Для всех строк ниже язык — русский, длительность — 6 часов. Все пять запросов прогнаны через ядро и Streamlit AppTest на включённом CSV.

Пример	Город, дата, формат, категория, бюджет	Фактический результат в порядке выдачи
dense	Алматы; 06.10.2026; корпоратив; Ведущий; 1 000 000 ₸	Куррапика → Мицури Канроджи → Аня Форджер
date_b	Алматы; 08.10.2026; корпоратив; Ведущий; 1 000 000 ₸	Аня Форджер → Сон Гоку → Буллма
rare	Алматы; 09.10.2026; свадьба; Флорист; 300 000 ₸	Тони Тони Чоппер → Тихиро Огино; всего 2, второй синтетический
no_match	Алматы; 09.10.2026; корпоратив; Ведущий; 100 000 ₸	no_matching_candidates: сначала исключены 4 занятых, затем 6 по бюджету
missing_category	Астана; 09.10.2026; корпоратив; Инструменталист; 1 000 000 ₸	category_not_found: такой категории в городе нет

В интерфейсе этим проверкам соответствуют пункты списка:

Команда / пример	Что выбрать в «Готовый пример для проверки»
dense	1. Ведущие: выбор трёх из нескольких
date_b	2. Те же условия, другая дата
rare	3. Флористы: честные два варианта
no_match	4. Никто не проходит условия
missing_category	5. Категории нет в городе

После каждого выбора нажмите «Подобрать подрядчиков». В сценарии 3 проверьте подпись «Синтетический профиль» у Тихиро Огино и отметку о проставленной цене у Тони Тони Чоппера. В сценариях 4 и 5 карточек быть не должно; сообщения должны объяснять разные причины отсутствия результата.

Каждый пример также можно запустить отдельно из терминала, без открытого веб-приложения:

python run_demo.py --case dense

python run_demo.py --case date_b

python run_demo.py --case rare

python run_demo.py --case no_match

python run_demo.py --case missing_category

Команда печатает JSON: смотрите response.status, response.message и упорядоченный список response.results. У каждой карточки есть anon_name, price_from_kzt и explanation. elapsed_seconds может отличаться при каждом запуске.

В паре dense / date_b меняется только дата. Куррапика и Мицури Канроджи исчезают из тройки: 8 октября присутствует в их busy_dates. Причины видны в блоке «Почему остальные не показаны».

Проверить все сохранённые ответы одним запуском:

python run_demo.py --verify

Последняя строка успешной проверки: OK: 5 saved responses match the real core. Полные запросы, ответы и версия данных находятся в demo_queries.json; сценарий человеческой проверки — в docs/demo.md. Изменение датасета или режима может изменить ответ; команда сверки тогда завершится ошибкой, а не объявит старые ожидания верными.

11. Ожидаемый результат

Основной запрос возвращает status: success:

Порядок	Подрядчик	ID	Начальная цена
1	Куррапика	HK-88430	от 500 000 ₸
2	Мицури Канроджи	HK-44923	от 650 000 ₸
3	Аня Форджер	HK-29829	от 700 000 ₸

Реальное объяснение первой карточки:

Начальная цена — от 500 000 ₸, на 500 000 ₸ ниже лимита 1 000 000 ₸; в каталоге указан формат «корпоратив»; по календарю нет отметки о занятости на 2026-10-06; запрошенный язык «русский» указан в профиле; заявленные 6 ч покрывают запрошенные 6 ч. В описании указано: «Я, Куррапика — профессиональный ведущий мероприятий с современным подходом и тонким чувством аудитории».

Результат содержит status, query, results, stats, rejections, message и meta с версией алгоритма и hash нормализованных данных. Три бизнес-состояния: success — 1–3 карточки; category_not_found — группы нет; no_matching_candidates — группа есть, но все исключены. Ошибки данных и выполнения не маскируются этими статусами.

Цена «от» — не окончательная смета, доступность — только по данным каталога, не подтверждённая бронь. Сервис не бронирует, не отправляет заявки и не добавляет подрядчиков ради тройки.

Тесты и фактическая проверка

python -m pytest -q -rs

На macOS/Python 3.12.13 общий набор дал 193 passed, 5 skipped, 48 subtests passed. Установка lock в новом окружении и pip check прошли. Подробные результаты итогового набора тестов, установки и запуска записаны в docs/acceptance.md. Набор включает реальные фильтры, пустые выдачи, 1–3 карточки, буквальное evidence, повторяемость, новый процесс и все пять demo-запросов через интерфейс. Проверки модели и semantic-кэша требуют отдельных локальных артефактов и явно пропускаются без них.

UI показывает время каждого вызова. Это время подбора после загрузки каталога, без холодного запуска сервера; оно не является гарантией скорости на другом компьютере.

Автоматические проверки не заменяют человеческую оценку ясности объяснений. Текущий baseline сравнивает начальную цену, не качество исполнителя; неполные или одинаковые описания ограничивают различимость карточек.

12. Возможные проблемы при запуске

Проблема	Что проверить / исправить
Ошибка доступа при клонировании	Нужен доступ GitHub и настроенный SSH либо архив проекта от команды
requirements.txt не найден	Перейдите в корень репозитория рядом с app.py
No module named streamlit или pydantic	Активируйте .venv и установите зависимости через тот же python
Ошибка загрузки каталога	Проверьте файл docs/hackathon dataset anonymized .csv внутри сборки; уберите неверный CONTRACTORS_DATA
Ошибка семантического кэша	Для основного сценария уберите внешнюю настройку RANKING_MODE=semantic; по умолчанию работает baseline
Порт 8504 занят	Замените в команде запуска --server.port 8504 на --server.port 8505 и откройте http://127.0.0.1:8505
run_demo.py --verify сообщает расхождение	Сверьте данные и режим с сохранёнными ответами; не заменяйте ожидания без проверки причины

Историческое ревью P3 и статус исправлений: docs/REVIEW.md.

Команда и воспроизводимость

Участник 1 — контракты, загрузка, обязательные фильтры и общий ответ. Участник 2 — порядок, семантический модуль и объяснения. Участник 3 — интерфейс, приёмка, demo-сценарии и README. Исходные коммиты частей записаны в BUILD_SOURCES.json, проверки итоговой сборки — в docs/acceptance.md.

Проверка требований 5.4.15: назначение — §1; архитектура — §3; технологии — §4; требования и установка — §5–6; зависимости — §7; окружение — §8; запуск — §9; воспроизводимый сценарий и ожидаемый результат — §10–11. Все команды выполняются из явно указанной папки, реальные секреты не требуются.