ASA — умный подбор event-подрядчиков

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

Содержание

• Быстрый старт
• Как это работает
• Сравнение карточек
• Три исхода
• Демо-сценарии
• ИИ в пайплайне
• Проверка Definition of Done
• Структура проекта
• Программный интерфейс
• Данные

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

Нужен Python 3.10 или новее.

git clone https://github.com/BAITC-Hacks/hack-d5f21cdd-asa.git
cd hack-d5f21cdd-asa
python -m pip install -r requirements.txt
python -m streamlit run app.py

Откроется http://localhost:8501. Выберите «Быстрый сценарий» или заполните форму и нажмите «Найти TOP‑3».

Если Windows отвечает, что команда python не найдена, используйте py вместо python.

Ядро (matching.py, comparison.py, explanations.py, service.py) работает на стандартной библиотеке Python, без внешних зависимостей. Streamlit нужен только для интерфейса, оформление лежит в styles.css.

Как это работает

flowchart LR
    Q["Запрос<br/>город · дата · формат<br/>категория · бюджет"] --> P["1. Пул<br/>город + категория"]
    P -->|пусто| NF(["category_not_found<br/>+ где категория есть"])
    P --> F["2. Жёсткие фильтры<br/>дата · бюджет · формат<br/>длительность"]
    F -->|никто не прошёл| NM(["no_match<br/>+ что изменить"])
    F --> R["3. Ранжирование<br/>прозрачные баллы, TOP‑3"]
    R --> C["4. Сравнение<br/>плюсы и ограничения"]
    C --> E["5. Объяснение<br/>из проверенных фактов"]
    E --> M(["matched<br/>карточки + подсказки"])
    AI{{"ИИ: один запрос на весь TOP‑3<br/>выбирает, какие пункты показать"}} -.-> C

Как считаются баллы

Каждый, кто прошёл фильтры, получает базу 70. Сверху добавляются компоненты score_parts, их видно в режиме «Подробности подбора».

Цена баллов не добавляет. Дешевле не значит лучше: бюджет работает только как фильтр.

Сравнение карточек

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

Первым в объяснение попадает самый редкий плюс: уникальный язык → самая низкая цена → самый длинный лимит часов → цена ниже самой дорогой → цитата. Ограничения остаются в колонке «Что учесть».

Если у двух подрядчиков описания начинаются одинаково (в каталоге есть почти одинаковые лайв-бэнды), для каждого берётся первая фраза описания, которой нет у другого. Так объяснения не совпадают даже у «клонов».

Пометки о качестве данных показываются всегда: ИИ не может их скрыть. Если в выдаче одна карточка, сравнивать не с кем, и в плюсах показываются подтверждённые проверки: формат, свободная дата, бюджет.

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

Одна карточка: декабрь, почти все ведущие заняты

Три исхода

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

no_match: все банкетные залы заняты 6 декабря

category_not_found: лайв-бэнда нет в Астане

Демо-сценарии

Все сценарии проверены на реальном каталоге (demo_scenarios.py, тест test_integration.py) и есть в форме в списке «Быстрый сценарий». Любой сценарий открывается по ссылке, например http://localhost:8501/?scenario=2. Если добавить &debug=1, включатся подробности подбора.

Порядок показа жюри: 1 → 2 (занятость меняет выдачу) → 5 (редкая категория) → 7 (пусто, но с подсказкой) → 9 (нет категории) → снова 1 с переключателем «Имитировать сбой ИИ» в «Настройках демонстрации».

ИИ в пайплайне

ИИ не выбирает подрядчиков, не меняет порядок и не пишет текст. Это делает детерминированный код. Модель получает весь TOP‑3 одним запросом и для каждой карточки выбирает 1–2 плюса и до 2 ограничений из заранее подготовленных пунктов. Возвращает она только их id, а текст пунктов берётся из каталога. Поэтому модель не может выдумать цену, дату или заслугу.

Как запустить с ИИ

Вариант 1 — на один запуск. В том же окне PowerShell, где будете запускать приложение:

$env:OPENAI_API_KEY = "sk-..."
python -m streamlit run app.py

Вариант 2 — один раз для этой папки. Создайте файл .streamlit/secrets.toml:

OPENAI_API_KEY = "sk-..."

Файл указан в .gitignore и не попадёт в репозиторий. Приложение подхватит ключ при запуске.

Как понять, что ИИ работает: в раскрывающемся блоке «Настройки демонстрации» написано «ИИ сравнит варианты одним запросом», а под карточками — «ИИ сравнил варианты · по проверенным фактам». В терминале: python demo.py выводит у карточек сравнение: llm.

Модель задаётся через OPENAI_MODEL (по умолчанию gpt-4o-mini). Используется OpenAI Responses API со строгой JSON-схемой и temperature=0, чтобы одинаковый запрос давал одинаковый выбор. Тесты никогда не обращаются к настоящему API, даже если ключ задан в терминале.

Проверка Definition of Done

Структура проекта

├── app.py                 веб-интерфейс (Streamlit)
├── styles.css             оформление интерфейса
├── service.py             единая точка входа: run(request)
├── matching.py            загрузка CSV, фильтры, баллы, факты, заголовок и подсказки
├── comparison.py          плюсы и ограничения между карточками, выбор пунктов ИИ
├── explanations.py        короткое объяснение из проверенных фактов
├── demo_scenarios.py      демо-запросы, проверенные на каталоге
├── demo.py                прогон сценариев в терминале
├── test.py                модульные тесты
├── test_integration.py    сквозные проверки Definition of Done
├── data/providers.csv     каталог: 66 профилей
└── docs/screenshots/      скриншоты для README

Программный интерфейс

from service import run

response = run({
    "city": "Алматы",
    "date": "2026-10-15",          # ГГГГ-ММ-ДД, окно 23.09–31.12.2026
    "event_format": "корпоратив",  # свадьба · той · корпоратив · конференция · юбилей · день рождения
    "category": "Фотограф",
    "budget_kzt": 600_000,         # целое ≥ 0
    # необязательно: "duration_hours": 6, "language": "казахский"
})

{
  "status": "matched",
  "headline": "Подходят 2 из 8 подрядчиков категории «Фотограф» в городе Алматы на 15 октября.",
  "hints": [
    "2 подрядчика подходят по всем условиям, кроме даты: 15 октября у них занято. Ближайшие свободные дни: 16 октября (Шикамару Нара, Леорио Паради)."
  ],
  "results": [
    {
      "id": "HK-35913",
      "name": "Тохру",
      "price_from_kzt": 400000,
      "price_imputed": true,
      "synthetic": false,
      "score": 90,
      "score_parts": {"specialization": 10, "description": 10, "language": 0, "duration": 0},
      "comparison": {
        "pros": [
          {"id": "price_lowest", "text": "Самая низкая цена среди показанных: от 400 000 ₸ (часть цен оценочная)"},
          {"id": "profile", "text": "В описании профиля: «Тохру — ивент-фотограф с более чем 10-летним опытом и более 1000 реализованных съёмок»"}
        ],
        "cons": [
          {"id": "hours_shorter", "text": "Лимит 10 ч на 2 ч меньше максимума среди показанных с лимитом"},
          {"id": "price_estimated", "text": "Цена в каталоге оценочная: её добавили при подготовке данных"}
        ]
      },
      "comparison_source": "fallback",
      "reason": "Самая низкая цена среди показанных: от 400 000 ₸ (часть цен оценочная); в описании профиля: «Тохру — ивент-фотограф с более чем 10-летним опытом и более 1000 реализованных съёмок». Берёт корпоративы; дата 15 октября 2026 года в календаре свободна; оценочная цена от 400 000 ₸ укладывается в бюджет 600 000 ₸.",
      "reason_source": "fallback"
    }
  ]
}

Некорректный запрос (дата вне окна, отрицательный бюджет и т. п.) вызывает ValueError с понятным текстом на русском; интерфейс показывает его как подсказку.

Данные

data/providers.csv: 66 анонимизированных профилей (Алматы — 50, Астана — 15, Зарубежье — 1), календарь занятости с 23.09 по 31.12.2026. Многозначные поля разделены |.

price_from_kzt — нижняя граница цены, поэтому везде пишем «цена от … укладывается в бюджет», а не «стоит». Пустой max_hours (флористы, декор, сувениры) длительность не ограничивает.