Совпало

«Совпало» - веб-сервис для точного подбора подрядчиков на мероприятия. Вместо длинного каталога пользователь получает до трёх подходящих вариантов с объяснением, почему каждый из них соответствует параметрам события.

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

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

Пользователь может указать город, дату, тип мероприятия, категорию подрядчика и бюджет, а при необходимости уточнить длительность и язык работы (RU, KZ или EN). Города, категории и форматы загружаются из backend, поэтому значения формы соответствуют текущему датасету. Сервис строго фильтрует кандидатов по всем условиям, рассчитывает детерминированную оценку, сохраняет стабильный порядок результатов и позволяет сортировать их по релевантности или цене.

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

Объяснения могут формироваться через OpenAI Responses API. Если интеграция выключена или внешний запрос завершается ошибкой, backend возвращает локальное фактологическое объяснение. Также реализованы адаптивная вёрстка, REST API и интерактивная документация OpenAPI/Swagger.

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

При открытии страницы frontend запрашивает GET /api/meta и заполняет форму значениями из датасета. После отправки формы параметры события передаются в POST /api/recommendations. Backend сначала формирует пул подрядчиков нужной категории в выбранном городе, а затем исключает тех, кто занят в указанную дату, превышает бюджет, не работает с нужным форматом или языком либо не может обеспечить требуемую длительность.

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

Технологии

Backend написан на Python 3.13+ и использует FastAPI, Uvicorn, Pydantic и python-dotenv. Frontend построен на HTML5, CSS3 и JavaScript ES Modules без UI-фреймворка; его раздаёт небольшой Node.js-сервер на встроенных модулях node:http, node:fs/promises и node:path. Каталог читается из CSV стандартным модулем Python csv.

AI-часть использует OpenAI Python SDK и Responses API; модель по умолчанию - gpt-4.1-mini. Интеграция опциональна: в стандартной конфигурации OPENAI_ENABLED=false, поэтому проект полностью работает без API-ключа. Для оформления интерфейса подключены Google Fonts и тематические изображения Unsplash.

Архитектура

Пользователь
    │
    ▼
Frontend (HTML / CSS / JavaScript)
    │  GET /api/meta
    │  POST /api/recommendations
    ▼
FastAPI
    ├── ContractorRepository ─────► dataset/dataset.csv
    ├── RecommendationService
    │     ├── строгая фильтрация
    │     ├── скоринг и сортировка
    │     └── выбор до 3 кандидатов
    └── ExplanationService
          ├── локальное объяснение
          └── OpenAI Responses API (опционально)

Точка входа FastAPI, настройка CORS и маршруты находятся в backend/src/main.py, а конфигурация из переменных окружения - в backend/src/config.py. Модуль repository.py читает CSV и формирует каталог, recommendations.py отвечает за фильтрацию, скоринг, сортировку и статусы результата, explanations.py создаёт локальные или AI-объяснения, а models.py валидирует входной REST-запрос через Pydantic.

На клиентской стороне frontend/app.js взаимодействует с API и отрисовывает карточки и состояния, frontend/styles.css содержит адаптивное оформление, а frontend/server.mjs раздаёт статические файлы и формирует runtime-конфигурацию адреса API.

REST API

Метод	Путь	Назначение
GET	/	краткая информация о сервисе
GET	/api/health	состояние API, размер каталога и режим объяснений
GET	/api/meta	города, категории, типы мероприятий и языки
POST	/api/recommendations	подбор до трёх подрядчиков

Backend возвращает один из трёх статусов: MATCHED, если подходящие кандидаты найдены; CATEGORY_NOT_FOUND, если в городе нет выбранной категории; NO_MATCH, если категория представлена, но все кандидаты отсеяны условиями.

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

Требования

Для запуска нужны Python 3.13 или новее, uv для установки Python-зависимостей, а также Node.js и npm для frontend. API-ключ OpenAI требуется только при включении AI-объяснений.

1. Клонировать репозиторий

git clone https://github.com/BAITC-Hacks/hack-99690795-spectra.git
cd hack-99690795-spectra

2. Настроить backend

Скопируйте пример конфигурации:

cp backend/.env.example backend/.env

В PowerShell эквивалентная команда:

Copy-Item backend/.env.example backend/.env

Установите зависимости и запустите API из корня проекта:

uv sync
uv run python main.py

Backend будет доступен по адресу http://localhost:8000, Swagger UI - http://localhost:8000/docs.

3. Настроить и запустить frontend

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

cp frontend/.env.example frontend/.env
cd frontend
npm run dev

Для PowerShell:

Copy-Item frontend/.env.example frontend/.env
Set-Location frontend
npm run dev

Откройте http://localhost:5173.

В package.json нет сторонних frontend-зависимостей, поэтому выполнять npm install для текущей версии не требуется.

4. Опционально включить OpenAI

Измените backend/.env:

OPENAI_ENABLED=true
OPENAI_API_KEY=your_api_key
OPENAI_MODEL=gpt-4.1-mini

Если запрос к OpenAI завершится ошибкой, сервис автоматически использует локально сформированные объяснения.

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

Backend:

Переменная	Значение по умолчанию	Назначение
APP_NAME	Совпало API	название API
APP_HOST	127.0.0.1	адрес backend
APP_PORT	8000	порт backend
DATASET_PATH	../dataset/dataset.csv	путь к CSV относительно backend/
ALLOWED_ORIGINS	локальные адреса frontend на порту 5173	разрешённые CORS origins
OPENAI_ENABLED	false	включить AI-объяснения
OPENAI_API_KEY	пусто	API-ключ OpenAI
OPENAI_MODEL	gpt-4.1-mini	модель для объяснений
OPENAI_TIMEOUT_SECONDS	10	тайм-аут запроса к OpenAI

Frontend:

Переменная	Значение по умолчанию	Назначение
FRONTEND_PORT	5173	порт frontend-сервера
API_URL	http://localhost:8000/api	базовый URL REST API

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

После запуска backend и frontend откройте http://localhost:5173 и повторите сценарий:

Поле	Значение
Город	Алматы
Дата	18.10.2026
Тип мероприятия	свадьба
Категория	Ведущий
Бюджет	1 200 000 ₸
Длительность	6 часов
Язык	RU
Сортировка	сначала точное совпадение

Нажмите «Найти подрядчиков». В текущем датасете условиям соответствуют четыре профиля, а интерфейс должен показать три наиболее релевантные карточки. В каждой карточке будут цена, язык, описание, совпавшие параметры и конкретное объяснение выбора.

Для проверки API без frontend можно выполнить:

curl -X POST http://localhost:8000/api/recommendations \
  -H "Content-Type: application/json" \
  -d '{
    "city": "Алматы",
    "date": "2026-10-18",
    "event_type": "свадьба",
    "category": "Ведущий",
    "budget": 1200000,
    "duration": 6,
    "language": "ru",
    "sort": "relevance"
  }'

Дополнительно можно проверить отрицательные сценарии. Если выбрать сочетание города и категории, отсутствующее в каталоге, интерфейс сообщит, что в этом городе такой категории нет. Если категория существует, но бюджет слишком мал или все кандидаты заняты в указанную дату, пользователь увидит сообщение о том, что кандидаты есть, но ни один не проходит условия, а также конкретные причины отсева.

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

Каталог подрядчиков

Файл dataset/dataset.csv содержит 66 профилей: 50 из Алматы, 15 из Астаны и один с местоположением «Зарубежье». Для каждого профиля хранятся идентификатор, анонимизированное имя, категории, город, цена, форматы мероприятий, языки, максимальная длительность, занятые даты и описание. Поля synthetic и price_imputed позволяют явно обозначать синтетические профили и восстановленные значения цены.

CSV загружается в память при старте backend. Путь к другому файлу можно передать через DATASET_PATH, если он соответствует ожидаемой структуре.

OpenAI

При включённой интеграции backend отправляет параметры запроса и данные уже отобранных кандидатов в OpenAI Responses API. Модель возвращает краткие объяснения на русском языке. Решение о допуске кандидата и его позиция формируются локально до обращения к модели.

Ресурсы интерфейса

Google Fonts загружает семейства Inter, Manrope и Playfair Display, а Unsplash используется для тематических изображений карточек. Если внешнее изображение загрузить не удаётся, интерфейс показывает локальный файл frontend/assets/event-fallback.svg.

Ограничения текущей версии

Каталог хранится в статическом CSV и не обновляется через интерфейс. Занятость также берётся из этого файла: синхронизации с календарями подрядчиков нет. В текущей версии не реализованы регистрация, авторизация, личные кабинеты, отправка заявки, бронирование, оплата и прямая связь с подрядчиком. Сервис всегда возвращает максимум три карточки, даже если условиям соответствует больше кандидатов.

Изображения назначаются по категории и идентификатору и не являются фотографиями конкретных подрядчиков. AI-объяснения требуют отдельного API-ключа и доступа к OpenAI, а Google Fonts и изображения Unsplash - подключения к интернету. Автоматические тесты, Docker-конфигурация и production-инфраструктура в репозитории отсутствуют.

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

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