BIMteam — «Той таңдау»

Сервис помогает выбрать event-подрядчика для мероприятия в Казахстане. Пользователь задаёт условия и получает до трёх подходящих кандидатов с конкретными объяснениями выбора.

Проект разработан для HackAlem AI, задача №79-lite «Умный подбор подрядчиков».

Основной принцип: сначала проверить обязательные условия, затем объяснить выбор. Если подходящих подрядчиков нет, сервис сообщает причину, а не показывает пустой экран.

Быстрый запуск

Нужны Python 3.11+, Git и доступ к репозиторию. Для первой установки зависимостей потребуется интернет. Node.js и API-ключи для базового запуска не нужны.

Актуальная общая версия находится в ветке main: новый бэкенд, интерфейс «Той таңдау» и документация запуска собраны вместе.

Windows — PowerShell:

git clone --branch main https://github.com/BAITC-Hacks/hack-873d221c-bimteam.git
cd hack-873d221c-bimteam
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/start.ps1

Linux / macOS:

git clone --branch main https://github.com/BAITC-Hacks/hack-873d221c-bimteam.git
cd hack-873d221c-bimteam
sh scripts/start.sh

Скрипт создаёт отдельное окружение Python, устанавливает зависимости, запускает сервер и открывает браузер. Первая установка может занять несколько минут.

Сайт: http://127.0.0.1:8000.

Документация API: http://127.0.0.1:8000/docs.

Первый пользовательский сценарий — около минуты:

1. На сайте выберите Алматы, 10.10.2026, корпоратив, «Ведущий» и бюджет 1 000 000 ₸. Язык и длительность оставьте необязательными.
2. Нажмите «Подобрать подрядчиков». Появятся три карточки с ценой «от», свободной датой и объяснением. Откройте «Подробнее — выдержка из профиля».
3. Нажмите «На день позже» — подбор пересчитается для новой даты. Кнопка-пример «Без совпадений» показывает причины пустой выдачи.
4. Нажмите «Площадки на карте» для трёх рекомендованных площадок. Отдельная кнопка «Все площадки города и цены на карте» показывает обзор цен: он не проверяет дату и бюджет. Вернуться к подбору можно кнопкой «Проверить по моим условиям».

Оставьте терминал открытым. Для остановки сервера нажмите Ctrl+C. Файл index.html отдельно открывать не нужно: интерфейс работает через сервер.

Если команда py не найдена, установите Python 3.11+ с python.org, включите добавление Python в PATH и откройте терминал заново. Python 2.6 не подходит. На Linux может потребоваться пакет python3-venv.

Без Git можно скачать ZIP текущей версии, распаковать его и выполнить команду запуска из папки с README. Для закрытого репозитория необходим вход в GitHub.

Что делает сервис

Обязательные параметры: город, дата мероприятия, формат мероприятия, категория подрядчика и бюджет в тенге.

Дополнительные параметры: язык и длительность. API также принимает пожелания; в текущей форме сайта отдельного поля для них нет.

Сервис:

• исключает подрядчиков, не проходящих обязательные условия;
• проверяет календарь занятости, включая площадки;
• возвращает не больше трёх карточек;
• показывает имя, категорию, город, начальную цену и объяснение;
• объясняет, почему результатов меньше трёх или нет совсем;
• отмечает синтетические профили и дополненные поля исходных данных.

Различаются три результата. Ниже — сокращённые реальные ответы демонстрационных сценариев.

Подходящий подрядчик найден:

{"status":"found","message":"Подходящих профилей: 1; показано: 1. В каталоге для «Флорист» и города Астана профилей всего: 1.","cards":[{"id":"HK-90002","name":"Хаку"}]}

В городе нет нужной категории:

{"status":"no_category","message":"Категории «Декоратор» в городе Астана нет. Профили этой категории есть в других городах: Алматы: 3.","cards":[]}

Категория есть, но никто не подходит:

{"status":"all_filtered","message":"Из 10 профилей «Ведущий» в городе Алматы не подошёл ни один: 5 — не берут формат «конференция»; 4 — заняты 05.12.2026; 1 — дороже 250 000 ₸.","cards":[]}

Архитектура и технологии

Бэкенд написан на Python с FastAPI. Pydantic проверяет входные данные. Интерфейс использует HTML, CSS и JavaScript. Каталог хранится в CSV; отдельная база данных для текущих 66 профилей не требуется.

Дополнительные компоненты: NumPy для смыслового сравнения описаний, OpenAI SDK для обращения к выбранному AI-провайдеру, pytest для автоматических тестов.

Для карты площадок используется локально включённая Leaflet 1.9.4 и подложка OpenStreetMap. Интернет нужен для фона карты, но не для локального подбора. Координаты в текущей поставке демонстрационные, а не реальные адреса; цены и состав точек берутся из ответа сервера.

Обработка запроса состоит из следующих шагов:

1. Проверка запроса. Проверяются обязательные поля, допустимые значения, бюджет, длительность и границы календаря.
2. Фильтрация. Последовательно применяются категория и город, формат, дата, бюджет, язык и длительность.
3. Ранжирование. Подходящие кандидаты получают баллы; выбираются первые три.
4. Подготовка фактов. Собираются подтверждённые сведения о цене, формате, языке, длительности и занятости, а также короткая цитата из профиля.
5. Объяснение. Настроенная языковая модель выбирает и соединяет факты. Без модели используются шаблоны.
6. Ответ. API возвращает карточки, причины отсева, проверенные подсказки и время обработки.

Основные части репозитория:

Папка	Назначение
app/	Фильтры, ранжирование, объяснения, настройки и API
api/	Совместимость с прежней командой запуска
web/	Пользовательский интерфейс
data/	Каталог и демонстрационные запросы
scripts/	Запуск, подготовка демо, эмбеддингов и кэша
tests/	Автоматические проверки
docs/	Описание API, демо и работы команды

Почему выбран такой подход

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

Модель не управляет составом и порядком карточек. Её роль ограничена объяснением уже принятого решения на основании подготовленных фактов.

Для проверки ответа модели используются:

• соответствие идентификаторов выбранным карточкам;
• ограничение длины и числа предложений;
• наличие как минимум двух фактов и числовой конкретики;
• проверка чисел и целых утверждений по источнику;
• запрет общих рекламных фраз;
• проверка чрезмерного сходства объяснений между карточками.

Эти проверки снижают риск выдуманных утверждений, но не заменяют ручную оценку полезности объяснений.

При ошибке сети, неподходящем ответе или превышении времени ожидания сервис возвращает шаблонное объяснение. Результат сохраняется в кэше, включая запасной вариант.

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

Ранжирование

После фильтрации используется взвешенная сумма признаков.

Признак	Вес	Смысл
Соотношение цены и бюджета	0,30	max(0.4, price / budget)
Указанные форматы	0,25	Учитываются число форматов и положение запрошенного формата в списке
Языки	0,10	Запрошенный язык и наличие нескольких языков
Запас по длительности	0,10	Дополнительные часы относительно запроса
Смысловое сходство	0,25	Сходство запроса и описания при включённых эмбеддингах
Синтетический профиль	−0,03	Небольшая понижающая поправка
Дополненная цена	−0,02	Небольшая понижающая поправка

Это эвристики — заданные разработчиками правила, а не обученная оценка качества подрядчика.

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

Без смыслового индекса соответствующий признак равен нулю; остальные веса не пересчитываются.

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

Данные

Используется предоставленный организаторами каталог: 66 анонимизированных профилей. Новые профили командой не добавлялись.

Календарь доступен с 23 сентября по 31 декабря 2026 года.

В исходных данных:

• 13 синтетических профилей;
• 18 профилей с дополненной ценой;
• 8 профилей с дополненным городом;
• 9 профилей без ограничения длительности присутствия.

Флаги synthetic, price_imputed и city_imputed сохраняются в API и отображаются в карточках.

Значение max_hours=null означает, что ограничение времени присутствия неприменимо, а не что подрядчик работает ноль часов.

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

Смысловой поиск использует эмбеддинги — числовые представления описаний. Их подготовка предусмотрена отдельным скриптом, но готовый индекс в репозиторий не включён. Без него основной подбор продолжает работать.

Демонстрационные сценарии

Во всех пяти сценариях выбран формат «конференция», язык и длительность не ограничены.

№	Условия	Ожидаемый результат
1	Алматы, Ведущий, 10.10.2026, 1 300 000 ₸	Четыре подходящих кандидата, показаны три
2	Те же условия, дата 07.11.2026	Состав меняется из-за занятости: Сон Гоку заменяется Куррапикой
3	Астана, Флорист, 10.10.2026, 300 000 ₸	Один профиль и объяснение короткой выдачи
4	Астана, Декоратор, 10.10.2026, 1 300 000 ₸	Категории в городе нет
5	Алматы, Ведущий, 05.12.2026, 250 000 ₸	Никто не подходит; показаны причины отсева и подсказка бюджета

Для проверки запустите сервер и откройте второй терминал в папке проекта.

Windows:

curl.exe -sS -H "Content-Type: application/json" --data-binary "@data/demo_requests/1.json" http://127.0.0.1:8000/api/recommend

Linux / macOS:

curl -sS -H "Content-Type: application/json" --data-binary "@data/demo_requests/1.json" http://127.0.0.1:8000/api/recommend

Замените 1.json на 2.json–5.json, чтобы проверить остальные сценарии. Файлы запросов позволяют избежать проблем с кириллицей и кавычками в терминале.

Сценарии и сохранённые ответы также доступны через GET /api/demo. Это демонстрационные снимки, а не доказательство подключения внешней модели.

Для проверки карты нажмите на сайте «Площадки на карте»: Алматы, банкетный зал, свадьба, 10.10.2026, бюджет 6 000 000 ₸. Карта показывает только найденные карточки, с пометкой об условных координатах. Переключатель «Список» возвращает обычный вид. Подробнее: Карта площадок.

Обзор «Все площадки города и цены на карте» — отдельный режим: семь площадок Алматы или одна Астаны, без отбора по дате и бюджету. Он не обещает доступность и не заменяет три рекомендации. Названия берутся дословно из описаний анонимизированного каталога; исходные имена профилей сохраняются.

Проверки и воспроизводимость

В проверенной версии на Windows с Python 3.12.14 проходят 107 тестов Python, отдельно проверяются 5 тестов данных карты.

23.09.2026 подтверждена установка в отдельной чистой копии: новое окружение, без личного .env и готового кэша. Сервер запустился, пять HTTP-сценариев совпали с сохранёнными ответами. Проверка выполнялась на том же Windows-компьютере, не на другом устройстве. Подробности и границы проверки: финальный отчёт.

Проверить установку без запуска сервера и открытия браузера:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/start.ps1 -Check

На Linux/macOS: sh scripts/start.sh --check. Проверка должна завершиться сообщением «Установка готова, профилей: 66». Затем запустите сайт обычной командой из раздела «Быстрый запуск».

Проверяются фильтры, календарь, стабильность порядка, три исхода подбора, короткая выдача, факты в объяснениях, кэш, подсказки и совместимость с интерфейсом.

Запуск тестов на Windows:

.\.venv\Scripts\python.exe -m pytest -q

Linux / macOS:

.venv/bin/python -m pytest -q

Тесты не читают личный .env, не требуют ключей и не расходуют API-квоту. Ответы внешних моделей в тестах заменяются контролируемыми примерами.

Для тестов карты нужен Node.js 24; для запуска самого сайта Node.js по-прежнему не нужен. Из корня проекта:

node --test tests/map-data.test.mjs

Если Windows сообщает об отсутствии доступа к временной папке pytest:

$env:PYTEST_DEBUG_TEMPROOT = (New-Item -ItemType Directory -Force cache/pytest).FullName
.\.venv\Scripts\python.exe -m pytest -q

Проверенные локальные HTTP-запросы без AI укладываются в ориентир ТЗ — до 10 секунд. Задержка с реальным AI-провайдером пока не измерена.

На 23.09.2026 автоматические проверки GitHub Actions не выполнились: зафиксирована блокировка запуска из-за billing issue. Это не успешный прогон тестов в GitHub. Полный запуск Linux/macOS также пока не подтверждён.

Настройка AI

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

Чтобы включить AI:

1. Создайте .env на основе .env.example, не перезаписывая существующий файл.
2. Выберите провайдера: openai или nvidia.
3. Укажите соответствующий API-ключ и имя доступной совместимой модели.
4. Перезапустите сервер.
5. Проверьте поле explanation_source в ответе подбора: значение llm подтверждает использование принятого ответа модели.

Основные параметры:

Параметр	Назначение
LLM_PROVIDER	none, openai или nvidia; по умолчанию none
OPENAI_API_KEY / NVIDIA_API_KEY	Ключ выбранного провайдера
OPENAI_MODEL / NVIDIA_MODEL	Имя модели для объяснений
LLM_TIMEOUT_S	Общий предел ожидания генерации, максимум 8 секунд
EMBEDDING_PROVIDER	Независимый провайдер смыслового поиска; по умолчанию none
EMBEDDING_MODEL	Имя модели эмбеддингов
EMBEDDING_TIMEOUT_S	Предел ожидания вектора запроса, максимум 1 секунда
CACHE_DIR	Папка кэша, по умолчанию cache

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

Текущий клиент отправляет запросы Chat Completions с temperature=0 и JSON-ответом. Выбранная модель должна поддерживать эти параметры. Обычно выполняется один запрос для всех карточек; при ошибке проверки допускается одна корректирующая попытка в пределах общего времени ожидания.

Автоматического переключения между платными провайдерами нет. Без ключа или имени модели используются шаблоны.

Для подготовки смыслового индекса после настройки провайдера, модели и ключа:

.\.venv\Scripts\python.exe scripts/build_embeddings.py

Команда расходует API-квоту. После подготовки индекса перезапустите сервер. На Linux/macOS используйте .venv/bin/python.

Ключи нельзя добавлять в Git, отправлять во frontend или публиковать в README. .env, кэш и построенный индекс исключены из Git.

Запасные объяснения тоже кэшируются. Чтобы повторно проверить модель после восстановления доступа, укажите новую папку CACHE_DIR и перезапустите сервер.

В текущей проверенной конфигурации AI отключён. Реальные вызовы провайдеров и качество ответов ещё требуют отдельной проверки.

API и взаимодействие с интерфейсом

Метод	Адрес	Назначение
POST	/api/recommend	Подбор подрядчиков
GET	/api/options	Города, категории, форматы, языки и границы календаря
GET	/api/venues?city=Алматы	Обзор всех площадок города и цен, без проверки доступности
GET	/api/demo	Демонстрационные сценарии
GET	/api/health	Состояние сервиса и выбранный провайдер
GET	/docs	Интерактивная документация API

Основной запрос содержит city, date, event_type, category, budget_kzt; дополнительные поля — language, duration_hours, wishes.

Ответ содержит:

• status — результат подбора;
• cards — карточки;
• message — понятное пользователю сообщение;
• shortfall_reason — причину выдачи менее трёх карточек;
• funnel — количество кандидатов на каждом шаге отбора;
• hints — до двух проверенных предложений изменить условия;
• elapsed_ms — время обработки на сервере.

Текущий frontend использует прежние названия полей event_format и budget; сервер сохраняет этот формат обмена. Только прежний формат допускает нулевой бюджет для существующей демонстрационной кнопки. Основной формат API требует положительный бюджет.

Карточки и итоговая сводка отображаются в интерфейсе. Новые поля hints и funnel доступны через API, но отдельно в интерфейсе пока не представлены.

Ветка Рустема frontend объединена с main до коммита 8337b5e: поиск города, календарь, быстрые категории, сохранение условий, обновлённые карточки, демо-карта и обзор всех площадок города. Используется один текущий бэкенд app/; новый обзор адаптирован к нему, старый core/ не запускается. Сравнительные факты и совместимость обоих форматов API проверяются тестами.

/api/health показывает выбранную настройку провайдера, а не подтверждает доступность внешней модели.

Ограничения и развитие

Проект является локальным демонстрационным решением на небольшом каталоге.

Основные ограничения:

• данные и календарь ограничены набором организаторов;
• веса ранжирования пока не проверены на пользовательских оценках;
• объяснения могут звучать шаблонно, а цитаты — обрываться;
• сведения из описания являются заявлениями профиля, а не независимо проверенными фактами;
• кэш и объединение одинаковых запросов рассчитаны на один процесс сервера;
• часть зависимостей задана диапазонами версий, поэтому установка позднее может отличаться от проверенного окружения;
• реальные AI-вызовы, смысловой индекс и запуск на другом компьютере требуют дополнительной проверки.

Бронирование, оплата и отправка заявок подрядчикам не реализованы и не входят в задачу хакатона.

Дальнейшие направления: улучшение объяснений, проверка правил ранжирования на обратной связи, отображение подсказок в интерфейсе и совместный подбор нескольких категорий на одну дату.

Команда

Абзал — бэкенд: данные, фильтрация, ранжирование, API, интеграция AI, объяснения, тесты и документация серверной части.

Рустем — фронтенд: форма запроса, карточки результатов, адаптивность, состояния загрузки и ошибок, взаимодействие с API.

Совместная работа: проверка запуска, демонстрационные сценарии, итоговый README и подготовка защиты.