PromptAgents — подбор подрядчиков для мероприятий

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

Суть и преимущества

• Учитывает обязательные условия: город, категорию, свободную дату, бюджет, формат мероприятия, указанные язык и длительность. Занятые и неподходящие кандидаты исключаются до ранжирования.
• Помогает выбрать по предпочтениям: ненавязчивый ведущий, развлекательная программа, репортажная съёмка или минималистичный декор. Списки пожеланий зависят от категории: для зала не показываются критерии ведущего.
• Объясняет результат: показывает совпадения, противоречия, недостаток сведений и доказательства. Видно, почему предложен кандидат и почему исключены другие.
• Предлагает другую дату: если на выбранную дату никто не подходит, ищет ближайший день с доступным подрядчиком при сохранении остальных условий.
• Работает воспроизводимо: одинаковый запрос при одинаковых данных, признаках и правилах даёт одинаковый порядок.
• Запускается без API-ключа: локальные правила и проверенные цитаты позволяют использовать основной сценарий без внешнего сервиса.

Система различает три результата: matched — найдены подходящие; category_absent — в городе нет такой категории; no_match — кандидаты есть, но ни один не прошёл условия. Возвращаются общее число подходящих и максимум три карточки.

Если на выбранную дату никто не подходит

При no_match сервис проверяет календарь и предлагает одного подрядчика на ближайшую подходящую дату в пределах 23.09.2026–31.12.2026. Поиск идёт как вперёд, так и назад от выбранного дня; при одинаковом расстоянии выбирается более поздняя дата. На найденную дату кандидат выбирается по общей формуле ранжирования с учётом пожеланий.

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

Основной результат остаётся no_match, с нулём подходящих и пустым cards. Альтернатива возвращается в отдельном поле API alternative. Если подходящего варианта нет во всём окне календаря, предложение отсутствует. При matched и category_absent другая дата не подбирается.

Как используются OpenAI и пожелания

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

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

После обязательных фильтров порядок такой:

1. Соответствие пожеланиям: +1 за подтверждённое совпадение, −1 за явное противоречие, 0 при отсутствии или неоднозначности сведений.
2. Подтверждённая специализация на формате мероприятия.
3. Стартовая цена по возрастанию.
4. Строковый ID для разрешения равенства.

Формула: (-preference_score, -specialization, price_from_kzt, id). Один критерий учитывается один раз. Без пожеланий первый балл равен нулю. При равной цене признаки помогают различать кандидатов, но соответствие пожеланиям имеет приоритет и при разных ценах внутри бюджета.

AI не выставляет произвольный общий рейтинг и не может вернуть занятого подрядчика или ослабить бюджет. Структурированные поля важнее описания. Дата, бюджет или язык в свободном тексте не меняют форму молча: интерфейс просит уточнить условия. Это оценка соответствия заказу, а не качества человека.

Во время подбора внешняя модель не вызывается: используются сохранённые признаки, локальные правила и кэш. Без ключа, при ошибке API или отсутствии артефактов основной подбор работает. Режим источников можно проверить в ответе API (preference_mode, explanation_mode, diagnostics.warnings). Само добавление ключа в .env не создаёт AI-признаки — нужна команда подготовки ниже.

Устройство и технологии

Браузер / React → Vite proxy /api → FastAPI
                                   ↓
                     CSV + подготовленные признаки
                                   ↓
                  обязательные фильтры → ранжирование
                                   ↓
                  до 3 карточек + объяснения + причины исключений

Отдельный CLI → OpenAI API → проверка цитат → data/derived/

Часть	Технологии / расположение
Интерфейс	React 19.3, TypeScript 7, Vite 8, CSS — frontend/
API	Python 3.11, FastAPI, Pydantic, Uvicorn — backend/app/
Алгоритм	matching.py, preferences.py, preference_rules.py
Данные	CSV в памяти, без базы данных; загрузка и валидация — catalog.py
AI-подготовка	OpenAI Responses API через HTTPX — scripts/extract_preferences.py
Проверки	pytest, HTTPX, тестовый раннер Node.js — tests/, frontend/tests/
Контракт	docs/api-contract.md, Swagger /docs

Основные методы: GET /api/health, GET /api/options, GET /api/preference-options, POST /api/recommend.

Скачать и установить зависимости

Нужны Git, Python 3.11 и Node.js 24.15.0 с npm 11.12.1. Python и Node.js должны быть доступны в терминале. Установщики: Python, Node.js, Git.

Скачайте репозиторий и перейдите в его корень:

git clone https://github.com/BAITC-Hacks/hack-74b0d694-promptagents.git
cd hack-74b0d694-promptagents

Можно также скачать ZIP репозитория, распаковать и открыть терминал в папке, где лежит этот README. Все дальнейшие команды выполняются из этой папки. CSV уже включён в репозиторий; скачивать или преобразовывать его отдельно не нужно.

Windows PowerShell:

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend/requirements.txt
npm.cmd --prefix frontend ci

Linux / macOS:

python3.11 -m venv .venv
.venv/bin/python -m pip install -r backend/requirements.txt
npm --prefix frontend ci

Команды используют Python виртуального окружения напрямую; активировать его не требуется. Python-зависимости закреплены в backend/requirements.txt, JavaScript-зависимости — в frontend/package-lock.json.

Создать и заполнить .env

Создайте файл .env в корне проекта, рядом с README, скопировав шаблон. Не перезаписывайте существующий .env, если он уже настроен.

Windows PowerShell:

Copy-Item .env.example .env
notepad .env

Linux / macOS:

cp .env.example .env
nano .env

Содержимое для запуска с возможностью AI-подготовки:

DATA_PATH="hackathon dataset anonymized .csv"
DERIVED_PATH=data/derived/features.json
PREFERENCES_PATH=data/derived/preferences
OPENAI_API_KEY=вставьте_свой_ключ
OPENAI_MODEL=gpt-4o-mini-2024-07-18

Переменная	Назначение
DATA_PATH	Путь к исходному CSV относительно корня проекта
DERIVED_PATH	Необязательный файл подготовленных специализаций
PREFERENCES_PATH	Каталог файлов с признаками для пожеланий
OPENAI_API_KEY	Ваш ключ для отдельного запуска AI-подготовки
OPENAI_MODEL	Точный snapshot модели для подготовки признаков

Для работы без AI удалите строку OPENAI_API_KEY или оставьте значение пустым. Сам .env тоже необязателен: стандартные пути уже заданы в коде. Файл исключён из Git; реальный ключ не включайте в README или коммиты. Сохраните именно .env, а не .env.txt. После изменения настроек перезапустите backend.

Подготовить AI-признаки — необязательный шаг

После установки зависимостей и заполнения ключа выполните:

.\.venv\Scripts\python.exe -X utf8 -m scripts.extract_preferences

На Linux/macOS замените исполняемый файл на .venv/bin/python. Скрипт отправляет описания, категории и форматы в OpenAI API. Вызовы могут расходовать средства API. Сначала можно проверить один профиль, добавив --limit 1. Успешные файлы сохраняются в data/derived/preferences/; при повторном запуске они пропускаются. Для обновления ранее созданных файлов используйте --overwrite.

Отдельно можно подготовить специализации на форматах:

.\.venv\Scripts\python.exe -X utf8 -m scripts.extract_features

Этот скрипт создаёт data/derived/features.json и использует OPENAI_MODEL из .env. После подготовки перезапустите backend: артефакты читаются при старте. Предел ожидания API — 30 секунд на профиль для extract_preferences и 60 секунд для extract_features. Подготовка выполняется отдельно и не задерживает пользовательский запрос. При ошибке готовые признаки пожеланий сохраняются, остальные профили обрабатываются локальными правилами. Подробности форматов и проверок — data/derived/README.md.

Запустить проект

Нужны два терминала, оба открытые в корне проекта.

Терминал 1 — backend, Windows:

.\.venv\Scripts\python.exe -X utf8 -m scripts.validate_data
.\.venv\Scripts\python.exe -m uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000

Терминал 2 — frontend, Windows:

npm.cmd --prefix frontend run dev

Linux / macOS, терминал 1:

.venv/bin/python -m scripts.validate_data
.venv/bin/python -m uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000

Linux / macOS, терминал 2:

npm --prefix frontend run dev

Откройте приложение. Проверка backend должна показывать dataset_status: "ready", profile_count: 66, recommendation_implemented: true. Swagger позволяет отправлять запросы вручную. Vite перенаправляет /api на backend с портом 8000. Для остановки нажмите Ctrl+C в каждом терминале. Публичная размещённая версия пока не указана.

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

1. Откройте форму и нажмите демо для ведущего в Алматы на 10.10.2026: корпоратив, бюджет 1 000 000 ₸, русский язык, 6 часов. Ожидаются matched, 4 подходящих и 3 карточки.
2. Посмотрите объяснения, цитаты и раскрываемый разбор порядка.
3. Сравните кнопки «Ненавязчивая подача» и «Только развлечения и танцы». Множество подходящих сохраняется, но приоритеты меняются.
4. Повторите запрос: порядок должен совпасть. Смените дату на 11.10.2026: состав меняется по календарю, занятый кандидат не возвращается.
5. Проверьте «Астана + Декоратор» (category_absent) и «Алматы + Ведущий + 12.12.2026» (no_match). Во втором случае проверьте отдельную карточку «Ближайшая подходящая дата»: исходный результат должен остаться нулевым. Сверьте предложенную дату с календарными доказательствами и убедитесь, что бюджет и остальные условия сохранены. Повторите запрос — предложение должно совпасть. Если во всём календарном окне подходящих нет, альтернативная карточка не показывается.
6. Через Swagger задайте дату вне 23.09.2026–31.12.2026: ожидается HTTP 422. Проверьте работу без ключа — основной сценарий остаётся доступен.

Два реальных запроса отличаются только preferences_text; остальные поля совпадают с пунктом 1. Проверенный порядок без подготовленных AI-файлов:

Пожелание	Первые три ID	Подходящих
Ненавязчивая подача	HK-77838 → HK-88430 → HK-29829	4
Только развлечения и танцы	HK-29829 → HK-88430 → HK-27222	4

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

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

Из корня проекта, Windows PowerShell:

.\.venv\Scripts\python.exe -X utf8 -m scripts.validate_data
.\.venv\Scripts\python.exe -X utf8 -m scripts.check_demos
.\.venv\Scripts\python.exe -X utf8 -m pytest -q
.\.venv\Scripts\python.exe -X utf8 -m pytest -q tests/integration_cases.py
npm.cmd --prefix frontend test
npm.cmd --prefix frontend run build

При запущенном backend дополнительно проверьте реальные HTTP-запросы:

.\.venv\Scripts\python.exe -X utf8 -m scripts.verify_api_demos
.\.venv\Scripts\python.exe -X utf8 -m scripts.verify_preferences

На Linux/macOS используйте .venv/bin/python и npm. Обычный pytest не включает файл integration_cases.py, поэтому он запускается отдельно.

Проверка объединённого проекта от 23.09.2026: 156 основных Python-тестов, 37 интеграционных, 27 тестов альтернативной даты, 24 frontend-теста и успешная сборка. Импортированы 66 валидных профилей; шесть базовых сценариев прошли offline-проверку. Альтернативная карточка проверена серверным рендерингом React, включая обе даты, evidence и балл пожелания. HTTP- и браузерный E2E-прогоны после этого слияния ещё не выполнялись. В более раннем прогоне на исходном CSV проверены шесть базовых сценариев и два запроса с пожеланиями, включая браузерную проверку. Тесты сложного ранжирования используют отдельные фикстуры в tests/fixtures/. Успешные ответы модели проверены на тестовых данных. Последняя реальная попытка AI-подготовки получила HTTP 401; заменённый после этого ключ ещё не проверялся, настоящие AI-артефакты пока не созданы. Полный отчёт — docs/preferences.md, базовые сценарии — docs/demo.md.

Если что-то не запускается

Симптом	Что проверить
python, py или npm не найдены	Установите нужную версию и откройте новый терминал
PowerShell запрещает npm.ps1	Используйте npm.cmd, как в инструкции
Ошибка доступа к npm-кешу	npm.cmd --prefix frontend ci --cache .npm-cache
Интерфейс не получает данные	Backend должен работать на 8000; проверьте /api/health
Порт занят	Остановите прежний процесс; Vite настроен на 5173, proxy — на 8000
HTTP 503 / каталог недоступен	Проверьте DATA_PATH и запустите scripts.validate_data
HTTP 422	Проверьте поля запроса и допустимое окно дат
OpenAI HTTP 401	Проверьте действительность OPENAI_API_KEY; перезапустите CLI
OpenAI HTTP 429	Проверьте квоту/лимиты API; основной подбор доступен без подготовки
Новые признаки не появились	Перезапустите backend; проверьте пути и diagnostics.warnings в API

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

В репозитории 66 анонимизированных профилей из исходного hackathon dataset anonymized .csv. Имена вымышленные; синтетические и восстановленные значения помечаются в карточках. CSV сохранён без изменений, SHA-256: 6a724b6b7dfb5973343e68ba18dadb60fc807d87e3d78f03ee86fb26cb089f7d.

• Календарь покрывает только 23.09.2026–31.12.2026.
• Цена «от» не гарантирует итоговую стоимость или включение дополнительных услуг.
• Анализ описаний консервативный: нераспознанные и спорные сведения остаются неизвестными, а не считаются недостатками кандидата.
• Подбор не включает бронирование, оплату, авторизацию или связь с подрядчиком.
• Изменение CSV и подготовленных файлов требует перезапуска backend.
• Нагрузочные испытания и публичный деплой не проводились.

Команда и материалы

• Biloshchytskyi Yevhenii
• Batyr Nursaya
• Biloshchytskyi Artem

Задание · API-контракт · Правила работы · Распределение задач · Проверка пожеланий · AI-подготовка