О проекте

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

Главное — не просто показать карточки, а объяснить, почему они подходят. Если вариантов мало или нет, пользователь узнает причину.

Проект решает кейс «Умный подбор подрядчиков (#79-lite)». Основной сценарий работает локально: без API-ключей, платных вызовов и базы данных.

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

• Подбор до трёх вариантов. Город, дата, категория, формат и бюджет; язык и длительность — по желанию.
• Индивидуальные объяснения. Особенность из профиля, соответствие запросу, стартовая цена и доступность на дату.
• Честная выдача. Занятые и неподходящие профили исключаются; редкие категории и пустые результаты объясняются словами.
• Описание события своими словами. «Опишу своё событие» разбирает русский текст по правилам, уточняет поля и предлагает подтвердить их перед подбором.
• Каталог и справочник. Поиск по имени или ID, фильтры, подробности профилей и локальная помощь по работе сайта.

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

Интерфейс поддерживает светлую и тёмную темы, RU / KK / EN и сохранение черновика формы. Описания профилей, объяснения и ответы помощника остаются на русском.

Соответствие критериям хакатона

Баллы ниже — веса критериев из задания, а не самооценка проекта.

Что показать жюри в первую очередь

1. Различия объяснений. На одном запросе сравнить факты в трёх карточках: почему конкретно этот профиль подходит, а не универсальную рекламную фразу.
2. Честную работу с занятостью и редкими категориями. Изменить только дату; затем показать двух флористов и объяснение отсутствия третьего варианта.
3. Понятный пустой результат. Уменьшить бюджет и показать причину отказа. Отдельно продемонстрировать отсутствие категории в городе.
4. Повторяемость и проверяемость. Повторить запрос, сопоставить ID и порядок с примером в репозитории; показать запуск qa/demo_check.py.

Эта последовательность соответствует приоритетам задачи: качество объяснений → корректная обработка редких, занятых и пустых категорий → скорость → интерфейс. Метрики скорости доступны в выводе локальной проверки; они не являются гарантией для другого компьютера или публичного хостинга.

Направления развития и границы готовности

Следующие шаги основаны на уже описанных в проекте ограничениях и не представлены как готовые функции:

• Проверить выбор фраз на реальном OpenAI API и вручную оценить пользу объяснений — процедура описана в AI.md.
• Перед публичным размещением добавить инфраструктурные ограничения, контроль доступа к платному AI и общие квоты между процессами — перечень находится в SECURITY.md.
• Для работы за пределами демо-календаря обновить источник данных и согласовать копию каталога на frontend. Текущая доступность подтверждается только предоставленным CSV в фиксированном диапазоне дат.

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

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

Параметры события
      ↓
Проверка ввода → город и категория → занятость и остальные условия
      ↓
Сортировка по стартовой цене, затем по ID
      ↓
До трёх карточек с объяснениями — или понятная причина отсутствия вариантов

Одинаковые параметры дают одинаковый порядок. Это сортировка по цене, а не рейтинг качества.

В объяснении сначала выделяется конкретный факт из профиля, затем показывается его соответствие заказу. Цитаты берутся из описаний, цены и занятость — из структурированных данных. Если отличительных сведений мало, сервис не выдумывает преимущества.

Подробные правила и обработка пограничных случаев — в описании пайплайна.

Технологии

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

Интеграция выключена в обычном сценарии. Настройки, модель и условия включения — в разделе «Данные и интеграции».

Архитектура

Один процесс FastAPI обслуживает сайт и API. Браузер передаёт параметры движку подбора, который работает с локальным каталогом. Текстовый помощник заполняет параметры для того же движка.

frontend/                   Форма, карточки, каталог, темы и справочник
contractor_assistant/       Разбор описаний событий и уточнение параметров
recommendation-logic/       API, движок подбора, данные, тесты и QA
docs/                       Демо-сценарии, пайплайн и отчёт приёмки

Основные маршруты: /recommendations — подбор, /assistant/chat — помощник, /filters — значения формы, /health — состояние сервера. Интерактивный контракт доступен по /docs после запуска.

Ответ подбора содержит карточки, объяснение результата и статистику. Три штатных исхода — matches, category_absent, no_match — возвращаются с HTTP 200; некорректные параметры отклоняются валидацией.

Полный контракт, примеры JSON и коды ошибок: Backend README · Интеграция frontend/backend.

Быстрый старт

Нужны Git и Python 3.10+. Проверено на Windows с Python 3.13.12. Node.js 22+ понадобится только для JavaScript-тестов; npm и сборка frontend не нужны.

1. Скачайте репозиторий

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

git clone https://github.com/BAITC-Hacks/hack-22efa0ed-codexflow.git
cd hack-22efa0ed-codexflow

2. Запустите сервер

Windows · PowerShell

cd recommendation-logic
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m uvicorn src.api:app --host 127.0.0.1 --port 8000

cd recommendation-logic
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m uvicorn src.api:app --host 127.0.0.1 --port 8000

3. Откройте сайт

Открыть «Повод» →

Swagger API · Состояние сервера — ожидается profiles_loaded: 66.

Не открывайте frontend/index.html двойным щелчком: сайту нужен работающий сервер. Остановка — Ctrl+C. Если порт занят, замените 8000, например, на 8013 в команде запуска и адресе браузера.

python3 -m http.server 5173 --bind 127.0.0.1 --directory frontend

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

Короткий маршрут для жюри

Откройте сайт без ?demo=1. В форме доступны быстрые примеры «Ведущий», «Флорист» и «Низкий бюджет». Выберите условия и нажмите «Подобрать подрядчиков».

Для трёх запросов ниже: Алматы · свадьба · длительность не задана.

Две контрольные проверки: повторите первый запрос — порядок должен сохраниться. Затем измените только его дату на 03.10.2026 — выдача станет пустой, а объяснение укажет занятость четырёх иначе подходящих профилей.

У флористов сравните факты в объяснениях: объём выполненных заказов у одного и работу с цветовой палитрой у другого. Метки синтетических профилей и ориентировочных данных должны быть видны.

Автоматические проверки

Проверено при подготовке этого README, 23.09.2026: срез 8fc152f, macOS, Python 3.12.2, Node.js 24.19.0. Прошли все 105 backend-тестов, 6 тестов помощника, 12 JavaScript-проверок, 7 живых HTTP-сценариев и повторный запрос с тем же порядком карточек. Проверены также раздача /ui/, документация API и разбор примера помощником. Реальные обращения к OpenAI не выполнялись.

Проверенный состав: 123 теста — 105 backend, 12 frontend и 6 помощника. Дополнительно: 7 живых API-кейсов с проверкой повторяемости; календарный тест перебирает 11 200 запросов и проверяет ограничения, порядок и объяснения.

# Backend, API, безопасность и календарь
.\.venv\Scripts\python.exe -m unittest discover -s tests -v

# Клиентские контракты и компоненты интерфейса (Node.js 22+)
node --test qa/frontend-integration.test.mjs

# Текстовый помощник
.\.venv\Scripts\python.exe -m unittest discover -s ../contractor_assistant -t .. -p test_chat.py -v

# Живой сервер: оставьте его запущенным, команду выполните в другом терминале
.\.venv\Scripts\python.exe qa/demo_check.py --base-url http://127.0.0.1:8000

# Нагрузка: скрипт сам запускает отдельный локальный сервер
.\.venv\Scripts\python.exe qa/stress_check.py --output qa-results.json

.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m unittest discover -s ../contractor_assistant -t .. -p test_chat.py -v
node --test qa/frontend-integration.test.mjs
.venv/bin/python qa/demo_check.py --base-url http://127.0.0.1:8000

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

Источник — providers.csv: 66 анонимизированных профилей, из них 13 синтетических. География — Алматы, Астана и «Зарубежье». Календарь — 23.09.2026–31.12.2026, 100 дней.

В каталоге 15 ведущих, 12 фотографов и 8 банкетных залов; в ряде редких категорий — по 3 профиля. Категории могут пересекаться: один подрядчик не превращается в несколько карточек.

Цена «от» — стартовая стоимость мероприятия, не окончательная смета. Синтетические профили, дополненный город и дополненная цена отмечаются независимо. Свободная дата в датасете не подтверждает бронирование.

Каталог интерфейса хранится в frontend/catalog-data.js; тест сверяет его поля с серверным CSV. При изменении данных нужно обновлять оба представления и перезапускать backend. Просмотр карточки в общем каталоге не подтверждает доступность на дату. max_hours = null означает, что услуга не привязана к часам присутствия, а не неограниченную работу. Причины в stats.rejected могут пересекаться, поэтому их сумму нельзя считать числом исключённых профилей.

Для основного сценария внешние API и отдельная БД не нужны; каталог и шрифты загружаются локально.

Ограничения

• Параметры подбора. Бюджет — только верхний предел. Минимальный бюджет, число гостей, теги и свободные заметки в контракт не входят.

• Контекст помощника. Клиент передаёт его с каждым запросом; серверного хранилища истории нет. Для даты без года помощник использует 2026 год.

• Учебный каталог. Анонимизированные данные и заявления профилей не являются проверенной информацией о реальных услугах. Даты вне указанного календаря не принимаются.

• Рекомендация, не заказ. Нет бронирования, оплаты, отправки заявок или уведомлений. «Связаться» показывает пояснение.

• Помощник по правилам. Он не гарантирует понимание произвольной речи; распознанные поля нужно подтвердить. Ручная форма всегда доступна.

• Демо, не готовый публичный сервис. Есть валидация и ограничения запросов, но перед размещением нужны HTTPS, ограничение частоты запросов, защита платного ИИ и проверка зависимостей. См. SECURITY.md.

• Границы проверки. Живой LLM и публичный хостинг не проверены. Локальные прогоны указаны выше; работа на всех поддерживаемых ОС не подтверждена. Зависимости заданы диапазонами, полного lock-файла нет.

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

Подтверждённой публичной версии пока нет. Для проверки используйте локальный сайт после запуска сервера.

127.0.0.1 доступен только на компьютере с запущенным сервером. Push в GitHub сохраняет исходный код, но не размещает сайт в интернете.

Документация

Для демонстрации: Демо-кейсы · Пайплайн · Чек-лист · Отчёт приёмки

Для разработки: Backend · Контракт интеграции · Опциональный ИИ · Безопасность · Нагрузка · Лицензии шрифтов