EventMatch AI

Рабочий репозиторий команды Nebula для трека 06 HackAlem AI: «Умный подбор подрядчиков».

Простая идея

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

Сервис показывает до трёх подходящих подрядчиков из выданного каталога и объясняет каждый выбор конкретными фактами:

• подрядчик работает в нужном городе;
• берёт нужный формат мероприятия;
• свободен в выбранную дату;
• его цена «от» укладывается в бюджет;
• при запросе проверяются язык и длительность.

Если подходящих нет, сервис объясняет причину: такой категории нет в городе или кандидаты не проходят условия.

Границы задачи

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

Цена в каталоге является ценой «от». Сервис не обещает окончательную стоимость услуги.

Данные каталога анонимизированы. Поля synthetic, city_imputed и price_imputed должны быть видны в карточке, когда они равны true.

Роли команды

Участник 1 — данные и алгоритм

• Добавляет исходный CSV в data/.
• Создаёт загрузчик и проверку структуры данных.
• Реализует фильтры: город, категория, формат, бюджет, дата, язык и длительность.
• Создаёт детерминированное ранжирование и объяснение причин пустой выдачи.
• Готовит тестовые сценарии из ТЗ.

Участник 2 — AI Agent и NVIDIA Brev

• Поднимает на Brev HTTP-сервис агента и модельный endpoint.
• Реализует поток: понять запрос на обычном языке → уточнить обязательное поле при необходимости → вызвать инструмент search_contractors → проверить структурированный ответ → объяснить результат.
• Агент вызывает единый API поиска /api/match; он не придумывает подрядчиков и не меняет порядок ранжирования.
• Возвращает подтверждённые причины для карточек и причину пустого результата.
• Настраивает защищённый HTTPS-вызов Brev со стороны Vercel; секреты не попадают в браузер и GitHub.

Участник 3 — generalist, интерфейс и Vercel

• Доводит форму и карточки до демо-сценария с текстовым запросом.
• Соединяет интерфейс с API агента и API поиска.
• Разворачивает приложение в Vercel из GitHub, проверяет Preview и Production URL.
• Обновляет README, фиксирует демо-запросы и готовит показ жюри.

План разработки

Этап 0. Старт проекта

Статус: сделано

• Создана структура плана.
• Зафиксирована задача и распределены роли.
• Добавлен сайт: index.html, styles.css, app.js.
• Добавлен контракт подключения данных: data/README.md.
• Каждый участник делает первый отдельный коммит в свой час работы.

Этап 1. Данные и базовый поиск

Цель: по форме получить корректный список доступных кандидатов.

• Добавлен исходный CSV как data/contractors.csv.
• Добавить браузерный checkpoint: проверка 13 обязательных колонок перед подключением CSV.
• Реализован checkpoint 13 колонок: ID, имя, категории, город, цена, форматы, языки, длительность, занятые даты, описание и флаги.
• Реализованы строгие фильтры в api/match.js.
• Занятый подрядчик исключается до ранжирования.
• API возвращает не более трёх кандидатов.
• Порядок фиксирован: score → цена → ID.

Готово, когда один и тот же запрос дважды возвращает одни и те же карточки в том же порядке.

Этап 2. Объяснимый подбор

Цель: у каждой карточки есть собственное объяснение, основанное на каталоге.

• Ввести понятный расчёт ранга: обязательные условия + число дополнительных совпадений.
• Сформировать для каждой карточки 1–2 конкретных предложения.
• Упомянуть только подтверждённые поля профиля.
• Объяснить, почему кандидатов меньше трёх.
• Считать исключения по причинам: нет формата, выше бюджета, занят, нет языка, недостаточная длительность.

Пример хорошего объяснения: «Свободен 15 октября, ведёт корпоративы, говорит на русском и английском; цена от 1 000 000 ₸ укладывается в ваш бюджет».

Этап 3. AI Agent на NVIDIA Brev

Цель: агент самостоятельно проводит ограниченный цикл поиска с инструментом, сохраняя правила трека.

• Поднять HTTP endpoint агента на Brev и проверить его доступность для Vercel по HTTPS.
• Принимать свободный текст; возвращать уточняющий вопрос, если не хватает обязательных полей.
• Вызвать инструмент search_contractors, связанный с /api/match.
• Использовать только результаты и причины, которые вернул каталог и matcher.
• При нулевой выдаче объяснять исключающие условия и предлагать возможные варианты изменения запроса.
• Не менять фильтры, карточки и порядок выдачи без явного ответа пользователя.
• Хранить ключ Brev в серверных переменных Vercel/Brev; не коммитить секреты.

Этап 4. Интерфейс

Цель: жюри может самостоятельно выполнить поиск без помощи разработчика.

• Сделать форму с обязательными полями и понятной валидацией.
• Показать максимум три карточки.
• Показать «от» перед ценой.
• Выделить занятость как причину исключения.
• Добавить метки synthetic / восстановленный город / восстановленная цена.
• Сделать ссылку или кнопку для загрузки трёх демо-запросов.

Этап 5. Обязательные демонстрации

• Плотная категория: Алматы, ведущий, корпоратив, 15.10.2026, бюджет 2 000 000 ₸.
• Тот же запрос на 25.12.2026: выдача должна измениться из-за занятости.
• Редкая категория: Алматы, флорист, свадьба, 15.10.2026, бюджет 1 000 000 ₸.
• В городе нет категории: Астана, декоратор.
• Кандидат есть, но не проходит условия: Астана, флорист, свадьба, 15.10.2026, бюджет 1 000 000 ₸.
• Запустить одинаковый запрос дважды и показать одинаковый порядок.

Этап 6. Сдача

• README содержит архитектуру, установку, запуск и пять демо-запросов.
• В репозитории есть исходные данные или инструкция их получения.
• В .env.example описаны необязательные переменные.
• Проект запускается одной командой без личных аккаунтов проверяющего.
• В истории GitHub есть прогресс минимум один раз в час.
• Последний коммит сделан до дедлайна.

Архитектура

Текущий работающий путь:

Форма сайта → Vercel /api/match → официальный CSV
                              → строгие фильтры
                              → детерминированная сортировка
                              → до 3 карточек или причина пустой выдачи

Целевой путь после подключения агента:

Текстовый запрос → Vercel /api/agent → AI Agent + модель на NVIDIA Brev
                                               ↓ search_contractors
Сайт ← объяснение по результатам ← Vercel /api/match ← CSV и правила

Результаты и их порядок принадлежат /api/match. Агент работает с запросом и объяснением, а не заменяет правила доступности.

AI Agent: граница ответственности

Состояние на сейчас: API детерминированного подбора реализован в api/match.js; агентный endpoint на Brev и его подключение к сайту — следующий этап. Пока Brev не подключён, проект следует показывать как работающий matcher с интерфейсом, а не как завершённый агент.

Целевой поток:

Браузер
  → Vercel: сайт и серверный gateway /api/agent
  → Brev: агент и модель
  → инструмент search_contractors
  → Vercel /api/match
  → data/contractors.csv и детерминированные правила
  → карточки и подтверждённое объяснение

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

Секрет доступа к Brev задаётся только в серверных переменных проекта Vercel, например BREV_AGENT_URL и BREV_AGENT_TOKEN. Не добавляйте секрет в app.js, HTML, публичные переменные окружения или коммиты. Для текущего rule-based приложения переменные не требуются.

Деплой в Vercel

GitHub остаётся главным источником кода, Vercel размещает сайт и API. Репозиторий проекта: BAITC-Hacks/hack-86169f09-nebula.

Настройки проекта

• Root Directory: корень репозитория.
• Framework Preset: Other (framework: null в vercel.json).
• Build Command: пустая команда; сайт состоит из HTML/CSS/JS без сборщика.
• Output Directory: корень репозитория.
• Vercel Functions: /api/match.js с CSV-каталогом из data/contractors.csv.
• Переменные окружения: rule-based поиск в /api/match не требует ключей.

server.js нужен для локального запуска. vercel build --yes --target preview локально собирает корректный Build Output: статический интерфейс, Node.js Function /api/match и CSV-каталог.

Текущий статус — 23 сентября 2026

• Проект eventmatch-ai создан в Vercel, но его workspace использует план Hobby.
• Vercel заблокировал Preview-деплой с причиной: автор Git-коммита не имеет права создавать deployments для проекта.
• Репозиторий приватный и находится в GitHub-организации BAITC-Hacks. Vercel Hobby не поддерживает deployments из приватного репозитория GitHub-организации. См. официальные правила Vercel для приватных Git-репозиториев.
• Production URL, созданный первым неудачным деплоем, пока не работает: запрос к серверу возвращает FUNCTION_INVOCATION_FAILED. Не используйте эту ссылку как демо.

Рабочий публичный URL: пока отсутствует. Не считать деплой завершённым, пока Preview и Production не пройдут проверку.

Что нужно решить для публикации

1. Сохранить репозиторий приватным и перевести проект в Vercel Pro; затем подключить GitHub-организацию, выдать Vercel доступ к репозиторию и добавить авторов коммитов в команду Vercel.
2. Открыть репозиторий для всех. Это сделает публичными исходный код и все данные, хранящиеся в GitHub; выбирайте этот вариант только если команда согласна на такую публикацию.

После устранения ограничения создайте Preview deployment, проверьте сайт и /api/match, затем публикуйте Production URL. Проверка API должна показать catalog_profiles: 66 и одно из состояний matched, category_not_found или no_match. Одинаковые запросы должны возвращать карточки в том же порядке.

Дальнейшие изменения

После готовности Brev добавьте BREV_AGENT_URL и BREV_AGENT_TOKEN в Project Settings → Environment Variables Vercel, затем создайте новый deployment. Секреты не добавляйте в README или GitHub. После успешной проверки впишите production URL выше.

Как запустить локально

Нужен Node.js 20 или новее.

node server.js

Откройте http://localhost:3000. Сервер отдаёт интерфейс, CSV и API /api/match без установки библиотек и без личного аккаунта.

Текущая архитектура

• data/contractors.csv — официальный каталог из 66 профилей.
• api/match.js — серверный подбор по правилам ТЗ.
• app.js — интерфейс, который обращается к API; при загрузке своего CSV использует локальный безопасный fallback.
• server.js — локальный запуск сайта и API одной командой.
• index.html и styles.css — пользовательский интерфейс.

Технологии

• Node.js без внешних зависимостей для локального запуска;
• CSV как единственный источник фактов о подрядчиках;
• HTML/CSS/JavaScript для интерфейса;
• NVIDIA Brev — планируемое место запуска AI Agent и модельного сервиса;
• Vercel — веб-интерфейс, публичный endpoint и серверный gateway к Brev;
• детерминированный matcher остаётся единственным источником результатов и порядка карточек;
• если Brev временно недоступен, интерфейс сохраняет обычный поиск по правилам.

Ссылки

• Техническое задание
• Каталог подрядчиков CSV
• Страница HackAlem AI