EventMatch: умный подбор event-подрядчиков (#79-lite)

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

Главный принцип: ценность в объяснении, а не в сортировке. OpenAI API при настройке ключа выбирает подтверждённые основания и формулирует объяснение для каждой выбранной карточки. Код проверяет, что текст не содержит утверждений за пределами фактов профиля и точной цитаты. Модель не может объявить занятого подрядчика свободным или добавить кандидата из другого города.

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

• Подбор по городу, дате, типу мероприятия, категории и бюджету в тенге; язык и длительность необязательны.
• Один механизм для людей и площадок: банкетный зал проверяется по такому же календарю, как ведущий.
• Жёсткие фильтры по занятости, цене «от», формату, языку и длительности; максимум три карточки в стабильном порядке.
• Карточки с ценой, происхождением данных и основанием выбора из структурированных полей и описания подрядчика. Цитата относится именно к показанному профилю; рекламные заявления из описания не выдаются за независимую проверку.
• Три различимых исхода: matched (подобрали), no_category_in_city (такой категории нет в городе), no_match (профили есть, но не проходят условия). Отдельно возвращается ошибка валидации некорректного запроса.
• Причины исключения, число допустимых кандидатов и проверяемые подсказки по другой дате или бюджету для пустой выдачи.
• Сравнение двух дат с указанием кандидатов, исключённых из-за занятости; чат с уточнением заказа при наличии OpenAI API.
• HTTP API, локальная веб-форма, CLI, тесты, SQLite-хранилище заказов, решений OpenAI и журнала действий.
• Финальная верссия проекта находится в зип архиве под названием final-version

Как работает подбор

1. Заказчик указывает город, дату, формат, категорию и бюджет. Например: ведущий в Алматы на корпоратив 12 октября 2026 года, бюджет 1 300 000 ₸, 6 часов, русский язык.
2. Сервис валидирует запрос и выделяет только профили этой категории в указанном городе. Если таких профилей нет, возвращает no_category_in_city.
3. Для каждого профиля проверяются календарь busy_dates, цена price_from_kzt, event_formats, а при запросе языка или длительности также languages и max_hours. Если ни один не проходит, возвращается no_match с причинами.
4. Допустимые профили упорядочиваются детерминированно: в режиме по умолчанию учитывается лексическое соответствие описания формату, затем цена «от» и id. Это не рейтинг качества подрядчика. В выдачу попадает не более трёх.
5. Для выбранных профилей сервис подготавливает проверенные факты и дословные фрагменты их описаний. При настроенном OpenAI API модель выбирает 1–2 факта и, при наличии содержательного фрагмента, цитату, составляет персональное объяснение; backend проверяет принадлежность источников профилю и наличие только подтверждённого текста. Непрошедший проверку ответ модели не публикуется.
6. Результат содержит карточки, объяснение количества и исключений, метки synthetic, city_imputed, price_imputed, сведения о режиме работы. Подтверждённое решение OpenAI сохраняется: повторный запрос с той же версией данных, моделью и условиями использует тот же текст. Без ключа или при сбое API доступен явно помеченный шаблонный fallback.

max_hours=null означает, что ограничение времени присутствия неприменимо, например для флориста; это не обещание неограниченной работы. Цена «от» является нижней границей, а не окончательной сметой.

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

Компонент	Назначение
Python 3.11+, стандартная библиотека	Бизнес-логика, локальный HTTP-сервер (http.server), CLI, валидация, тесты (unittest), SQLite (sqlite3). Для основного сценария pip install не требуется.
eventmatch/models.py, catalog.py	Схемы запроса и профиля, загрузка JSONL, контроль целостности по SHA-256.
eventmatch/engine.py, service.py	Фильтрация и устойчивый порядок, диагностика отказов, подготовка фактов и проверка объяснений.
eventmatch/agent.py, providers.py	OpenAI Responses API с function calling: разбор чата и написание проверяемых объяснений по уже выбранным профилям. Модель по умолчанию: gpt-4.1-mini-2025-04-14; задаётся через OPENAI_MODEL.
eventmatch/semantic.py	Необязательное семантическое ранжирование на предварительно подготовленном артефакте NVIDIA (nvidia/llama-3.2-nv-embedqa-1b-v2); онлайн-вызовов NVIDIA при подборе нет. Без артефакта работает детерминированный baseline.
eventmatch/storage.py, server.py, web/index.html	SQLite для диалога, результатов, кеша объяснений и аудита; локальный HTTP API и адаптивная страница на обычных HTML/CSS/JavaScript без фронтенд-фреймворка.
eventmatch/integrations/google_calendar.py	Необязательное создание и удаление событий в личном Google Calendar через OAuth; не бронирование подрядчика. Для подбора не используется.

Пайплайн: форма или чат -> валидация -> каталог города/категории -> жёсткие фильтры -> устойчивый top-3 -> OpenAI для объяснений (либо помеченный fallback) -> проверка источников -> ответ и журнал SQLite. OpenAI получает только выбранные карточки с разрешёнными фактами и цитатами, а не все 66 профилей. Неправильный id, чужая цитата и неподтверждённые слова отклоняются. Режим виден в metadata.explanation_mode; записи вызовов доступны в actions.

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

Команды ниже выполняются из корня репозитория, где лежат eventmatch/ и examples/. Нужен Python 3.11+. Основной подбор не требует установки пакетов, Docker, NVIDIA или ключей API.

1. Запустите локальный сервер:

   python -m eventmatch serve
   

2. Откройте http://127.0.0.1:8000. Форма и демонстрационные кнопки работают без ключей, но в этом случае объяснения будут помечены template explanation fallback, а свободный текст в чате недоступен. Остановка сервера: Ctrl+C; другой порт: python -m eventmatch serve --port 8080.

3. Чтобы OpenAI API действительно писал объяснения, задайте серверу OPENAI_API_KEY. Например, в bash перед запуском:

   export OPENAI_API_KEY="<ваш ключ>"
   python -m eventmatch serve
   

   Альтернатива: локальный .env в корне проекта со строкой OPENAI_API_KEY=... (загрузчик читает его только для команд serve и agent). Ключ не передаётся в браузер; .env сейчас не исключён из Git, не добавляйте его в коммиты. OPENAI_MODEL необязателен. В metadata.explanation_mode ищите validated OpenAI grounded explanation или cached validated OpenAI explanation, а в metadata.openai и actions проверяйте фактический режим вызова. Наличие ключа само по себе не доказывает, что API ответил успешно.

Для локальной проверки без браузера:

python -X utf8 -m eventmatch recommend --request examples/01-dense.json  # ядро без OpenAI
python -X utf8 -m eventmatch agent --request examples/01-dense.json      # агент с OpenAI при наличии ключа
python -X utf8 -m tools.demo                                               # семь запросов, пересчёт на месте

-X utf8 полезен для отображения кириллицы на Windows. Для опционального режима NVIDIA потребуются NVIDIA_API_KEY, подготовка python -X utf8 -m tools.prepare_semantics --output data/nvidia-artifact.json и EVENTMATCH_RANKER=nvidia перед запуском; детали в инструкции по провайдерам. Готового артефакта в репозитории нет; отсутствие или повреждение артефакта при EVENTMATCH_RANKER=nvidia останавливает запуск вместо незаметной подмены результата.

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

Откройте страницу и нажмите следующие кнопки над формой: это живые запросы, а не показ сохранённых ответов.

Сценарий	Что проверить
«Ведущий · 12 окт.»	Алматы, корпоратив, 1 300 000 ₸, 6 ч, русский: 7 допустимых из 10 в городе/категории; показаны 3 карточки с различающимися цитатами и ценами.
«Та же заявка · 13 окт.»	Состав top-3 меняется: Сон Гоку был занят 12 октября и попадает в выдачу 13 октября; причины исключения на каждую дату видны в сводке.
«Флорист · редкая категория»	Показаны ровно 2 профиля из 2; видны метки исходного и синтетического профилей и объяснение, почему третьего нет.
«Заняты на дату»	no_match на 12 декабря: профили в городе и категории есть, но все кандидаты, проходящие остальные условия, заняты. Сервис объясняет пустую выдачу.
«Нет такой категории»	no_category_in_city для категории «Декоратор» в Астане, без подстановки подрядчиков из Алматы.
«Банкетный зал»	Проверяется календарь площадки на 14 ноября, применяются те же правила, что для ведущих.

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

curl -sS http://127.0.0.1:8000/recommend \
  -H 'Content-Type: application/json' \
  --data-binary @examples/01-dense.json

Коды исходов matched, no_match, no_category_in_city возвращаются с HTTP 200; ошибка в параметрах запроса (например, дата вне календаря) даёт HTTP 422. Полный контракт: docs/API.md.

Данные и внешние сервисы

• Канонический каталог: data/raw/hackathon-dataset-anonymized.jsonl, 66 профилей в 17 категориях: 53 с synthetic=false, 13 с synthetic=true. Команда не добавляла новых профилей. Данные преобразованы из CSV организаторов; шаги и хеши указаны в манифесте. Имена анонимизированы.
• Календарь дат в каталоге: 23.09.2026–31.12.2026 включительно (100 дней). Сервис не знает доступность за его пределами и отклоняет такие даты; повышенная занятость в декабре является свойством данных.
• OpenAI Responses API (https://api.openai.com/v1/responses) вызывается только при наличии ключа для написания объяснений и обработки чата. В этом окружении ключ не предоставлен, поэтому живую генерацию здесь подтвердить нельзя; тесты OpenAI используют тестовые ответы.
• NVIDIA Embeddings API (https://integrate.api.nvidia.com/v1/embeddings) необязателен и используется только при подготовке локального семантического артефакта. В обычном запуске дополнительных сетевых запросов для ранжирования нет.
• Google Calendar API является отдельной необязательной интеграцией. Для него нужны пакеты google-api-python-client, google-auth, google-auth-oauthlib, локальный credentials.json и OAuth-авторизация (token.json создаётся локально); они не входят в pyproject.toml и не нужны для сценария рекомендации. Кнопка добавляет событие в календарь пользователя, а не бронирует подрядчика.

Ограничения и состояние проверок

• Состав top-3 и порядок определяет backend; OpenAI не выбирает подрядчиков. Смысловые рекомендации зависят от качества описаний; цитата доказывает лишь наличие фразы в профиле, а не истинность рекламного заявления. Лексические эвристики не дают полноценного понимания отрицаний и сложных связей.
• Цена «от» не гарантирует итоговую стоимость; сервис не бронирует, не отправляет заявки и не уведомляет подрядчиков. Нет рейтингов, подтверждённой вместимости каждой площадки и расписания по часам.
• Локальный сервер слушает 127.0.0.1; публичный деплой и эксплуатационные гарантии времени ответа не настроены. Запрос к OpenAI ограничен общим deadline 10 секунд и может перейти на помеченный fallback.
• Команда python -X utf8 -m tools.demo проверена на текущем каталоге. Часть сохранённых ответов examples/responses/ устарела относительно текущего движка; tools.check_repository и полный unittest discover сейчас не проходят (в том числе из-за устаревших проверок разметки и Google Calendar). Не используйте снимки как доказательство текущего ответа: запускайте реальные запросы. Проверка агента и основных HTTP-исходов: python -X utf8 -m unittest tests.test_agent tests.test_http.HTTPTest.test_real_request tests.test_http.HTTPTest.test_valid_empty_result_uses_200 -q.
• Безопасность перед публикацией: в Git отслеживается credentials.json.json с OAuth client secret. Этот файл не используется подбором; перед передачей репозитория третьим лицам секрет нужно отозвать/перевыпустить у провайдера и удалить из истории репозитория. Новый credentials.json и token.json не следует публиковать.

Публичная версия

Подтверждённой ссылки на deployed-версию нет. Для демонстрации запустите локальный сервер по инструкции выше. Ссылка на исходный репозиторий не является ссылкой на работающий деплой.

Дополнительно: анализ данных, архитектура, сценарий демонстрации, настройка провайдеров.