Beyonder

Подбор event-подрядчиков, который объясняет свой выбор

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

Быстрый старт · Как проверить · Архитектура · API · Сценарии и ответы

_{Кнопка «Фотографы в Алматы»: воронка отбора и три карточки с объяснениями. Запуск без ключа API.}

[!NOTE] Ключ API не нужен. Без ключа работают подбор, «План Б», разбор фразы и смысловая оценка описаний: эмбеддинги для каталога и шести форматов уже сохранены в data/embeddings.json и сравниваются локально. Объяснения собираются по данным каталога (метка «Объяснение по данным»); результаты ниже проверены без ключа. С ключом OpenAI или NVIDIA модель дополнительно редактирует текст объяснений — это необязательно.

Описание решения и назначение

Трек 06 «Креативные индустрии», задача «Умный подбор подрядчиков» (#79-lite). Заказчик уже выбрал тип мероприятия и видит каталог своего города; ему нужно выбрать, а не листать длинный список. Он задаёт город, дату, формат, категорию и бюджет в тенге (по желанию — длительность и язык) — формой или одной фразой.

Каталог организаторов — data/hackathon-dataset-anonymized.csv: 66 анонимизированных профилей, 13 из них синтетические (помечены в выдаче), у части профилей оценочная цена или восстановленный город (тоже помечены). Календарь занятости — 23 сентября — 31 декабря 2026. Это подбор, а не бронирование: цены «от», доступность — по календарю каталога.

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

Нужны Git и Python 3.10 или новее. Ключ API не нужен.

✅ Проверено запуском с нуля 23.09.2026 (Windows 11): чистый git clone → venv → установка зависимостей за 56 с → scripts/demo.py — PASS: 8 ответов, 0 ошибок, pytest — все тесты проходят, аудит — «Нарушений не найдено». Docker: контейнер healthy, demo.py 8/8, тесты внутри контейнера (Linux, Python 3.12) проходят.

Инструкции по установке

Windows PowerShell

git clone https://github.com/BAITC-Hacks/hack-774a9321-beyonder.git
cd hack-774a9321-beyonder
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

macOS / Linux

git clone https://github.com/BAITC-Hacks/hack-774a9321-beyonder.git
cd hack-774a9321-beyonder
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

_{Если в Windows нет команды py, используйте python -m venv .venv. На macOS проверьте python3 --version. Активировать окружение не нужно, все команды выполняются из корня репозитория.}

Инструкции по запуску

.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000

.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Откройте http://localhost:8000. Там же — Swagger и метаданные каталога. Остановка — Ctrl+C. Если порт занят, используйте --port 8001. HTML через file:// не откроется: странице нужен API.

Альтернатива: Docker

Если установлен Docker с Compose, из корня репозитория запустите одну команду (одинакова в PowerShell, macOS и Linux):

docker compose up --build

Откройте http://localhost:8000. Ключ API не нужен. Для первой сборки нужна сеть, чтобы загрузить базовый образ и Python-зависимости; каталог и эмбеддинги уже входят в собранный образ. Остановка — Ctrl+C, затем docker compose down.

Порядок проверки основного сценария

В браузере — всё проверяется кнопками-сценариями над формой:

Фраза для шага 4:

Нужен ведущий на казахскую свадьбу 14 ноября в Алматы, бюджет до 800 тысяч, часов на 6

Скриншот: сравнение дат и «План Б»

В терминале — во втором окне, пока сервер работает:

.\.venv\Scripts\python.exe scripts/demo.py
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe scripts/audit_explanations.py --strict

.venv/bin/python scripts/demo.py
.venv/bin/python -m pytest -q
.venv/bin/python scripts/audit_explanations.py --strict

_{Если сервер запущен на другом порту: scripts/demo.py --base-url http://127.0.0.1:8001.}

Соответствие Definition of Done

Архитектура

flowchart TD
  T[Фраза: POST /api/parse или /api/ask] --> P[Разбор правилами: город, дата, формат, категория, бюджет, часы, язык]
  P -->|все обязательные поля найдены| B
  P -->|чего-то нет| MS[missing: интерфейс просит уточнить]
  A[Форма или POST /api/match] --> B[Валидация запроса и календаря]
  B --> C[Пул по категории и городу]
  C --> D[Фильтры: дата → бюджет → формат → язык → длительность]
  D --> FN[funnel: сколько осталось после каждого фильтра]
  D --> E[Прошедшие: взвешенный рейтинг, затем id]
  S[Локальные эмбеддинги каталога и 6 форматов] --> E
  D --> F[Не прошедшие: все причины в excluded]
  E --> G[До 3 карточек: сравнительные объяснения по фактам]
  G --> L{Задан ключ OpenAI или NVIDIA?}
  L -- да --> LLM[LLM редактирует тексты → проверка → кэш]
  L -- нет / ошибка / таймаут --> N[Объяснения по данным]
  F --> H[Исход и подсказки]
  FN --> H
  LLM --> H
  N --> H
  H --> I[Ответ API → интерфейс]

API

Интерактивная документация — http://localhost:8000/docs. Ответы отдаются как application/json; charset=utf-8.

Почему так устроено

• Решение принимает детерминированный алгоритм — фильтры и рейтинг: задание требует «тот же запрос — тот же порядок». LLM используется там, где он безопасен: переписывает объяснения из уже проверенных фактов; валидатор отклоняет выдуманные числа, цитаты и общие фразы, при отказе остаются объяснения по данным.
• Вес бюджета 0.40: цена в каталоге указана «от», поэтому запас бюджета снижает риск выйти за него. Все веса видны в карточке — «Как посчитан рейтинг».
• Смысл описания доступен без ключа. Для каждого предложения в 66 профилях и каждого из шести форматов векторы рассчитаны заранее и сохранены в репозитории. При старте код строит локальную таблицу косинусной близости; она влияет только на порядок кандидатов, прошедших жёсткие фильтры. Свободная фраза сначала разбирается правилами до полей формы: дополнительные слова не превращаются в отдельный семантический запрос.

Агентный подход

Модель не принимает решение сама — она работает в цикле с проверяемыми инструментами:

• Генерация → проверка → исправление → fallback. LLM пишет объяснения по фактам; код проверяет каждое (выдуманные числа и цитаты, общие фразы, одинаковые тексты); при ошибках модель получает их список и исправляет ответ; если и вторая попытка не прошла — показываются объяснения по данным (app/explain_llm.py).
• «План Б» сам ищет решение. Если на дату подходит меньше трёх, сервис перебирает соседние даты теми же фильтрами и рейтингом и предлагает лучшие; если мешает не дата — прямо говорит, что изменить (app/alternatives.py).
• Фраза → задача. Свободный текст превращается в параметры запроса с указанием источника каждого поля; неясное и противоречивое возвращается человеку, а не угадывается (app/nl_parse.py).
• API как набор инструментов. /api/parse, /api/match, /api/alternatives детерминированы и покрыты тестами — их может вызывать внешний LLM-агент (function calling), не получая возможности выдумать подрядчика или цену.

Что сделано иначе

Только то, что есть в коде и проверяется тестами или демо-сценарием.

Используемые технологии

Зависимости

Все зависимости — в requirements.txt (с верхними границами версий): fastapi, uvicorn — сервис; openai — необязательный LLM-слой, импортируется только при обращении к модели; python-dotenv — чтение .env через --env-file; pytest, httpx — тесты. Готовый индекс эмбеддингов работает без сети и ключа. Интернет нужен для установки зависимостей, необязательной LLM-редактуры и только если заново создавать индекс.

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

Все переменные необязательны: без них сервис полностью работает на объяснениях по данным.

Ключ хранится только в окружении или в локальном .env, который исключён из Git.

Необязательно: AI-объяснения с ключом

Для проверки решения ключ не нужен. С ключом модель редактирует текст объяснений по проверенным фактам; отбор, порядок карточек и все исходы остаются теми же.

Copy-Item .env.example .env

cp .env.example .env

.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --env-file .env

.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --env-file .env

.\.venv\Scripts\python.exe scripts/demo.py

.venv/bin/python scripts/demo.py

Ограничения

• Календарь известен только с 23.09 по 31.12.2026; цена «от» — не окончательная смета; бронирования и уведомлений нет.
• Разбор текста работает по правилам и поддерживает один язык; редкие формулировки попадают в missing, и поле заполняется в форме.
• У полностью одинаковых по данным профилей отличия не выдумываются. Качество перефразирования моделью зависит от модели; проверка фактов не заменяет полную семантическую проверку.

Масштабирование и развитие

Планы, а не реализованные функции:

• Живые календари — синхронизация занятости с подрядчиками вместо CSV; фильтры, рейтинг и «План Б» уже работают с датами.
• Больше городов и категорий — города и категории берутся из данных (/api/meta); при росте каталога — база данных с индексом по городу, категории и дате.
• Семантика свободной фразы — сейчас локальный индекс сравнивает описания с шестью фиксированными форматами; будущий шаг — использовать дополнительные пожелания заказчика из фразы при ранжировании и обновлять индекс с каталогом.
• Обратная связь — отметки «подошло / не подошло» для настройки весов рейтинга на реальных выборах.
• Встраивание — API без состояния: подбор можно встроить виджетом на сайт агрегатора или площадки.
• Казахский интерфейс — разбор текста уже понимает казахские формулировки («той»).

Команда