HackAlem AI — подбор event-подрядчиков в Казахстане

О проекте

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

Это прототип для хакатон-задачи «Умный подбор event-подрядчиков в Казахстане». В текущей версии алгоритм подбора работает по правилам; фактическое состояние AI-компонента описано в разделе «Ограничения».

Что реализовано

• Адаптивная страница с тёмной темой и формой поиска.
• Фильтры: город, дата, формат мероприятия, категория подрядчика и максимальный бюджет в тенге; дополнительно — язык и длительность.
• Проверка доступности на дату, бюджета и соответствия формату, языку и длительности на сервере.
• До трёх карточек: анонимное имя, категория, город, стартовая цена и блок «Почему подходит».
• Состояния интерфейса для ожидания, загрузки, результатов, пустой выдачи и ошибки подключения; показ сообщения сервера.
• Метки для профилей с синтетическими или восстановленными при подготовке данных полями.

Как работает решение

1. Пользователь выбирает параметры мероприятия и нажимает «Подобрать».
2. Браузер отправляет JSON-запрос в FastAPI: POST http://localhost:8000/recommend.
3. Бэкенд загружает профили из CSV, оставляет нужные город и категорию, затем исключает занятых и не соответствующих остальным условиям подрядчиков.
4. Оставшиеся профили сортируются, для них формируются объяснения. Сервер возвращает максимум три карточки и сообщение о результате.
5. Интерфейс показывает карточки или причину, по которой подходящих вариантов нет. При сетевой ошибке предлагает повторить запрос.

Условия поиска не ослабляются автоматически, когда найдено меньше трёх подрядчиков.

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

Компонент	Технологии	Ответственность
index.html	HTML5, CSS3, JavaScript ES6+, Tailwind CSS через CDN	Форма, валидация, запросы API и карточки результатов
backend/main.py, backend/models.py	Python 3.10+, FastAPI, Pydantic, Uvicorn	HTTP API, проверка входных данных, настройки CORS
backend/loader.py, backend/service.py	Python, CSV	Загрузка профилей и фильтрация
backend/ranking.py	Python	Текущая сортировка по фиксированным правилам и шаблонные объяснения
backend/data/contractors.csv	CSV	66 анонимизированных профилей

В зависимостях бэкенда присутствуют openai и python-dotenv, а backend/openai_client.py содержит фабрику клиента OpenAI. Запросы к OpenAI из действующего маршрута /recommend не выполняются. Для запуска текущего проекта API-ключ не требуется.

Фронтенд — один HTML-файл без сборки и npm. Для отображения интерфейса используется CDN Tailwind; основной стиль также задан обычным CSS. По умолчанию браузер обращается к API по http://localhost:8000, а CORS бэкенда разрешает фронтенд на http://localhost:5173 и http://127.0.0.1:5173.

Установка и запуск

Требования: Windows и Python 3.10 или новее. Команды ниже можно выполнять в PowerShell, в том числе во встроенном терминале VS Code. Выполняйте команды из корня репозитория, где находятся index.html и backend/. Используйте два терминала.

Терминал 1 — бэкенд. При первом запуске создайте виртуальное окружение и установите зависимости:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend/requirements.txt

Запустите API:

.\.venv\Scripts\python.exe -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

Проверка API: http://localhost:8000/health. Интерактивная документация: http://localhost:8000/docs.

Терминал 2 — фронтенд:

py -m http.server 5173 --bind 127.0.0.1

Откройте http://localhost:5173. Не закрывайте терминалы во время проверки. Если команда py недоступна, замените её на python. Если .venv уже создана, не создавайте окружение заново. Двойной щелчок по index.html откроет страницу через file://, где запрос к API может блокироваться политикой CORS.

Как проверить решение

1. Убедитесь, что http://localhost:8000/health возвращает status: "ok" и profiles: 66.
2. Откройте http://localhost:5173.
3. Выберите Алматы → 2026-10-15 → Свадьба → Ведущий → 900000 ₸; язык и длительность оставьте пустыми.
4. Нажмите «Подобрать». На предоставленном CSV сервер возвращает три карточки с объяснениями.
5. Поменяйте бюджет на 500000 ₸ и повторите запрос: по этим условиям совпадений нет, интерфейс выводит сообщение о пустом результате.

Для отдельной проверки API используйте /docs и отправьте в POST /recommend:

{
  "city": "Алматы",
  "event_date": "2026-10-15",
  "event_type": "свадьба",
  "category": "Ведущий",
  "budget": 900000
}

Необязательные поля запроса: language — строка, duration — положительное число часов. Ответ содержит status, message, results, count, total_candidates, total_matches, exclusion_counts. Элементы results содержат name, category, city, price, explanation и признаки synthetic, city_imputed, price_imputed. Подробности контракта и дополнительные примеры — в backend/README.md.

При необходимости запустите тесты бэкенда:

.\.venv\Scripts\python.exe -m pip install -r backend/requirements-dev.txt
.\.venv\Scripts\python.exe -m pytest backend/tests -q

Данные и интеграции

Источник данных прототипа — локальный анонимизированный CSV backend/data/contractors.csv с 66 профилями. При запуске FastAPI загружает его в память; база данных и обращения к сервисам подрядчиков не используются. Для замены файла данных можно указать CONTRACTORS_CSV в окружении и перезапустить сервер.

Интеграция фронтенда с бэкендом — HTTP/JSON через /recommend. При локальном запуске внешняя AI-модель не вызывается; API-ключ OpenAI не нужен. Файл .env.example показывает формат будущих настроек. Не публикуйте настоящий .env и API-ключи в GitHub: .gitignore исключает .env, .venv/, .pytest_cache/ и __pycache__/.

Ограничения

• AI-рекомендация ещё не завершена: ranking.py использует фиксированный порядок, а объяснения собирает из шаблона. Код не отправляет запросов к OpenAI. Чтобы реализовать AI-часть кейса, требуется подключить модель к бэкенду и проверить качество объяснений.
• Доступность подрядчиков известна только для дат с 2026-09-23 по 2026-12-31; за пределами этого периода API отклоняет запрос.
• Стартовая цена из CSV не гарантирует окончательную цену мероприятия. Данные не синхронизируются с подрядчиками в реальном времени.
• Адрес API во фронтенде указан как http://localhost:8000/recommend; при размещении на другом сервере потребуется изменить API_URL в index.html и разрешённые CORS-адреса в настройках бэкенда.

Развёрнутая версия

Публичная ссылка на запущенное приложение пока не указана. Для демонстрации используйте локальный запуск из этого README.