Умный подбор event-подрядчиков

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

Состав проекта

.
├── server.py             # HTTP-сервер, фильтры, эмбеддинги и генерация объяснений
├── index.html            # форма и карточки результатов; без frontend-библиотек
├── DataProviders.csv     # исходный каталог из 66 записей
├── smoke_check.py        # автономная проверка основных сценариев
├── .env.example          # названия переменных для API
└── .gitignore

Технологии

• Python 3.9+ и стандартная библиотека: http.server, csv, urllib; зависимости устанавливать не нужно.
• HTML, CSS и JavaScript без сборщика и внешних frontend-пакетов.
• OpenAI-compatible API, если задать OPENAI_API_KEY: [скрыто] используется для семантического порядка среди уже прошедших фильтры кандидатов, gpt-4o-mini — для формулировки объяснений по фактам каталога.
• Без ключа приложение работает локально: применяет те же ограничения и выводит короткие объяснения по полям каталога. Запросы к внешнему API не выполняются.

Запуск локально

Из корневой папки проекта:

python3 --version
python3 server.py

Откройте http://localhost:8000. Остановить сервер можно сочетанием Ctrl+C в терминале.

Если порт 8000 занят, задайте другой перед запуском:

PORT=8001 python3 server.py

Подключение LLM и эмбеддингов

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

export OPENAI_API_KEY="ваш-ключ"
export EMBEDDING_MODEL="text-embedding-3-small"
export LLM_MODEL="gpt-4o-mini"
python3 server.py

Для совместимого провайдера можно также задать OPENAI_BASE_URL, указав адрес API с окончанием /v1. Ключ не добавляйте в код или CSV. Первый запрос может занять больше времени: описания подрядчиков отправляются в API эмбеддингов и сохраняются в локальном .cache/embeddings.json; повторные запросы используют кэш. Объяснения LLM каждый раз строятся только по карточкам, прошедшим фильтры. Если API недоступен, приложение возвращается к объяснениям по правилам.

Как формируется рекомендация

1. Отбираются записи по городу и категории; синтетические записи исключаются.
2. Кандидат исключается, если дата есть в busy_dates, цена выше бюджета, формат не указан в event_formats или не совпадает, а также если заданные язык или длительность не подтверждаются данными карточки.
3. Если кандидатов нет в городе и категории, API возвращает no_catalog. Если исходные кандидаты есть, но условиям не соответствует ни один — no_match со списком причин. Иначе возвращается recommendations с максимум тремя карточками.
4. При настроенном API эмбеддинги влияют только на порядок прошедших фильтры кандидатов. При равных оценках порядок определяется ценой и ID. Без API порядок также стабилен: сначала цена, затем ID.
5. Признаки price_imputed и city_imputed отображаются как ориентировочные значения. Площадки представлены обычными категориями, с тем же календарным фильтром.

Бронирования, заявки и уведомления подрядчикам не выполняются. В исходной строке Ани Форджер добавлена занятая дата 2026-09-25 для сценария проверки календаря.

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

В отдельном терминале из корневой папки выполните:

python3 smoke_check.py

Скрипт отключает API для проверки, поэтому не расходует токены и работает офлайн. Он проверяет три состояния (recommendations, no_catalog, no_match), максимум три карточки, стабильность порядка и исключение Ани Форджер на 25 сентября 2026 года.

Также API можно вызвать напрямую. Пример запроса, для которого в каталоге есть фотографы:

curl -s http://localhost:8000/api/recommend \
  -H 'Content-Type: application/json' \
  -d '{"city":"Алматы","event_date":"2026-09-24","event_type":"свадьба","category":"Фотограф","budget_kzt":500000}'

Форма автоматически загружает доступные города, категории, форматы и языки через GET /api/options. Рекомендации возвращаются через POST /api/recommend.

Данные и ограничения

Каталог содержит 66 анкет, категорий, площадок, цен и занятых дат. Занятость задаётся датами ISO (YYYY-MM-DD), разделёнными символом |. Чтобы обновить наличие, меняйте DataProviders.csv и перезапускайте сервер: CSV считывается при запуске. Данные и календарь учебные, поэтому перед реальным бронированием их нужно сверить с подрядчиком — само приложение бронь не оформляет.