EventMatch: подбор event-подрядчиков

Заказчик мероприятия вводит город, дату, формат, категорию и бюджет и получает до трёх свободных подрядчиков из каталога. У каждой карточки своя причина попасть в тройку и объяснение с конкретными фактами: доля бюджета, языки, часы, деталь из описания. Цена показывается как в каталоге, без «от»: поле price_from_kzt датасета это стартовая цена за мероприятие, и на карточке это одно число, а не диапазон. Если подходящих меньше трёх или нет совсем, сервис говорит словами, кто и почему не прошёл, и предлагает соседнюю дату, бюджет или город.

Демо: https://ui-production-d923.up.railway.app · API: https://app-production-b973.up.railway.app/health

Задача хакатона: docs/hackathon/TASK.md. Пайплайн подбора шаг за шагом: docs/PIPELINE.md. Предметная область и схемы API: docs/DOMAIN.md.

Требования → статус

Требование	Статус	Где в коде
Вход: город, дата, тип мероприятия, категория, бюджет; опционально длительность и язык	✅	RecommendIn в app/src/schemas.py
Выход: до 3 карточек с именем, категорией, городом, ценой и объяснением в 1–2 предложения без общих фраз	✅	app/src/facts.py, app/src/explain.py, промпт app/src/explain_prompt.md, стоп-лист фраз BANNED_PHRASES
Занятый на дату не попадает в выдачу, площадки идут тем же фильтром	✅	get_rejection_reasons в app/src/recommend.py
Подходящих меньше трёх: показать сколько есть и почему меньше	✅	passed_count, rejections и suggestions в RecommendOut, экран ui/src/components/SearchHints.tsx
Детерминизм: тот же запрос, тот же порядок карточек	✅	pick_role_vendors: баллы, цена, id; LLM порядок не меняет
Три исхода различимы явно	✅	outcome в RecommendOut, три экрана в results.tsx
Ответ до 10 секунд	✅	таймауты: БД 5 с, LLM 8 с без ретраев, при сбое шаблон
Объяснения не взаимозаменяемы	✅	роли карточек, get_distinctions и get_alternative_reason в facts.py
Видно, где настоящий профиль, а где синтетический	✅	флаг synthetic в карточке, бэдж в ui/src/components/VendorCard.tsx

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

1. Пул. Из базы берутся подрядчики нужного города и категории. Пусто → исход «в этом городе такой категории нет» и список городов, где она есть.
2. Фильтры. Занят на дату, не берёт формат, дороже бюджета, мало часов, нет языка. Каждый отсеянный считается по первой причине, счётчики уходят в ответ. Никто не прошёл → исход «кандидаты есть, но не проходят».
3. Баллы и роли. Прошедшие получают баллы за упоминание формата в описании, близость описания к заказу по смыслу (эмбеддинги OpenAI, три ближайших получают 3, 2 и 1 балл), лишние языки, запас часов, настоящий профиль, точную цену и цену до 80% бюджета. Три карточки это три роли: лучшее совпадение, самая низкая цена, самый дорогой в бюджете. Если один подрядчик выиграл две роли, место уходит следующему по баллам, и его объяснение называет конкретный разрыв с первым: цена, оценочная цена, синтетический профиль или формат не упомянут в описании. Ничьи решает цена, потом id, поэтому порядок стабилен.
4. Объяснения. Факты считает код: доля и остаток бюджета, дата, формат, языки, часы, чем отличается от соседей по выдаче, сколько в категории заняты на дату. OpenAI формулирует их в 1–2 предложения по правилу «факт → что это даёт заказчику». Ответ проверяется: не больше двух предложений, каждое число есть в фактах карточки или в описании подрядчика, языки только те, на которых он работает, нет общих фраз и служебных слов вроде «карточка», нет латиницы внутри русских слов, нет выдуманной «оценочной цены». Шаблон тоже ровно два предложения. Не прошёл или модель недоступна → шаблон из тех же фактов, поле explanation_source показывает источник.
5. Подсказки. Если прошло меньше трёх, в ответе соседние даты в пределах трёх дней, бюджет и длительность, при которых кандидатов больше. Если не прошёл никто, ещё и города, где подрядчики этой категории проходят все условия заказа. Фронт перезапускает подбор по подсказке в один клик.

LLM участвует только в шаге 4 и только как редактор текста. Подробности и отвергнутые варианты: docs/PIPELINE.md.

Архитектура

ui (React + Vite, Railway) ──HTTP/JSON──▶  app (FastAPI, Railway)  ──▶  Postgres (Railway)
                                              │
                                              └──▶ OpenAI API

Бэкенд app/src/:

• main.py роутеры, CORS, /health. catalog.py словари фильтров GET /catalog/options и каталог GET /vendors.
• recommend.py POST /recommend: пул, баллы, роли. filters.py жёсткие фильтры и счётчики отказов. embeddings.py косинусная близость описаний к заказу. suggestions.py подсказки: даты, бюджет, часы, города. facts.py факты для карточки: роль, доля бюджета, отличия от соседей. explain.py вызов LLM, проверка ответа, шаблон. llm.py клиент OpenAI с таймаутом.
• schemas.py схемы входа и выхода и словари value ↔ label. models.py таблица vendors, миграции в app/migrations/. seed.py загрузка app/data/vendors.csv.

Фронтенд ui/src/:

• routes/index.tsx форма фильтров и каталог. routes/results.tsx результат подбора: загрузка, три исхода, причины отказа, подсказки, фильтры без возврата на главную. components/ResultsFilters.tsx сводка выбранных фильтров и раскрываемая форма. components/VendorCard.tsx карточка с ролью и бэджем синтетического профиля.
• api.ts все запросы через openapi-fetch, типы в api-types.ts сгенерированы из /openapi.json.

Технологии и данные

• Бэкенд: Python 3.12, FastAPI, SQLAlchemy 2 (async), Alembic, Pydantic v2, asyncpg, openai, uv; pytest для проверок основного сценария API.
• Фронтенд: React 19, TypeScript, Vite 7, TanStack Router и Query, Tailwind CSS v4, shadcn на Base UI, Lingui (ru / kk / en), yarn.
• База: PostgreSQL 17. Инфраструктура: Railway, конфигурация в .railway/railway.ts.
• Модели: OPENAI_MODEL, по умолчанию gpt-5.4-mini, вызов с seed и response_format: json_object; OPENAI_EMBEDDING_MODEL, по умолчанию text-embedding-3-small, 256 измерений, векторы описаний лежат в колонке vendors.description_embedding и считаются один раз при сиде.
• Данные: каталог организатора, 66 профилей, app/data/vendors.csv. Загружается командой python -m src.seed, upsert по id, затем эмбеддинги для описаний без вектора; повторный запуск безопасен. В compose это делает сервис seed после миграций, на Railway preDeployCommand. К 13 синтетическим профилям датасета добавлены 10 своих (HK-90014 – HK-90023, synthetic: True) в категории, где было по одному-два подрядчика: флористы, ведущие церемоний, фото- и видеобудки, подарки, зал и отель в Астане, видеограф, инструменталист. Занятые даты у них сгенерированы по сезонности задачи: 40% дней осенью, 75% в декабре и 90% на декабрьских выходных. На карточке синтетический профиль помечен бэджем.

Запуск

Нужны Docker Desktop или Podman Desktop с Compose и Python 3.9+.

python dev.py

Скрипт проверит инструменты, создаст .env из .env.example, включит git-хуки, подберёт свободные порты, соберёт контейнеры и дождётся /health. Compose поднимает Postgres, применяет миграции, загружает каталог, затем стартует API и фронтенд. Адреса: UI http://localhost:5173, API http://localhost:8000/docs.

После первого запуска вписать в .env OPENAI_API_KEY и повторить python dev.py. Без ключа всё работает: объяснения шаблонные, поиск по смыслу описания отключён, остаётся поиск формата в тексте.

Другие команды: python dev.py down остановить (down -v также удалит базу), python dev.py logs app логи, python dev.py status состояние контейнеров. Без скрипта то же самое делает docker compose up --build.

Разработка без Docker

# бэкенд, нужен запущенный Postgres, например `docker compose up db`
cd app && uv sync && uv run alembic upgrade head && uv run python -m src.seed && uv run python -m src

# фронтенд
cd ui && yarn install && yarn dev

После изменения схем на бэкенде перегенерировать типы фронтенда: yarn api:types в ui/ при запущенном API, файл ui/src/api-types.ts коммитится. Проверки перед коммитом: uv run pytest и uv run ruff check . && uv run ruff format --check . в app/, yarn lint в ui/. Хук на сообщения коммитов: git config core.hooksPath .githooks.

Как проверить основной сценарий

Через интерфейс:

1. Открыть http://localhost:5173, выбрать город, дату, формат, категорию и бюджет. Язык и длительность в блоке «Дополнительные условия». Под формой загружается каталог, «Показать всех подрядчиков» раскрывает весь список.
2. Нажать «Подобрать»: откроется /results с фильтрами в URL. Появятся карточки с ролями и объяснениями или один из двух пустых исходов с причинами и подсказками. При пустом исходе форма раскрыта прямо под сообщением, при успешном скрыта за кнопкой «Изменить фильтры»: новый подбор происходит на той же странице.
3. Нажать «Скопировать ссылку» и открыть её в новой вкладке: тот же подбор загрузится без формы, порядок карточек тот же.

Через API, три запроса из Definition of Done:

# плотная категория на осеннюю дату: 3 карточки, 5 из 10 ведущих заняты
curl -X POST http://localhost:8000/recommend -H 'content-type: application/json' \
  -d '{"city":"almaty","event_date":"2026-10-17","event_format":"wedding","category":"host","budget_kzt":1500000,"duration_hours":6,"languages":["ru","kk"]}'

# редкая категория: 1 карточка из 3, два флориста заняты
curl -X POST http://localhost:8000/recommend -H 'content-type: application/json' \
  -d '{"city":"almaty","event_date":"2026-10-20","event_format":"wedding","category":"florist","budget_kzt":400000}'

# кандидаты есть, но никто не проходит: все три фотографа не берут корпоратив
curl -X POST http://localhost:8000/recommend -H 'content-type: application/json' \
  -d '{"city":"astana","event_date":"2026-10-10","event_format":"corporate","category":"photographer","budget_kzt":600000}'

Первый запрос на 2026-12-19 вместо 2026-10-17 даёт одну карточку вместо трёх, в объяснении сказано, что 9 из 10 заняты. Полная таблица проверок: docs/PIPELINE.md.

Переменные окружения

Имя	Назначение	Пример
OPENAI_API_KEY	ключ OpenAI, без него объяснения шаблонные	sk-...
OPENAI_MODEL	модель для объяснений	gpt-5.4-mini
OPENAI_EMBEDDING_MODEL	модель эмбеддингов описаний	text-embedding-3-small
CORS_ORIGINS	разрешённые origin через запятую	https://<ui>.up.railway.app
DATABASE_URL	строка подключения к Postgres	postgresql+asyncpg://app:app@db:5432/app
VITE_API_URL	адрес API для фронтенда, вшивается при сборке	https://<app>.up.railway.app

Деплой

Railway, проект hurricane, окружение production, сервисы app, ui и плагин Postgres. Автодеплоя нет: railway up из app/ и из ui/, миграции и сид выполняет preDeployCommand. Подробно: DEPLOYMENT.md.

Известные ограничения

• Порядок и состав карточек детерминированы, формулировки объяснений от LLM между запусками могут немного отличаться. Примерно треть текстов модели не проходит проверку (третье предложение, число не из фактов) и заменяется шаблоном из тех же фактов; причина пишется в лог, источник виден в explanation_source.
• Эмбеддинги описаний считаются при сиде один раз: если поменять description в CSV, вектор не пересчитается, пока колонку не обнулить. Эмбеддинг запроса считается на каждый подбор, ранги округляются до тысячных, поэтому порядок карточек стабилен.
• Каталог на главной показывает первые шесть карточек до нажатия «Показать всех подрядчиков».

Команда

• Шорин Алихан, капитан, бэкенд: GitHub, LinkedIn
• Альпеисов Диас, фронтенд: GitHub, LinkedIn