VERITAS • Умный подбор event-подрядчиков (#79-lite)

Разработано командой Veritas в рамках технологического хакатона HackAlem AI 2026 (Astana Hub).
Трек: Креативные индустрии • Владелец задачи: Firebird.

Сервис интеллектуального подбора event-подрядчиков в Казахстане (Алматы, Астана, Зарубежье). Система детерминированно фильтрует каталог и возвращает до 3 карточек, формируя для каждого кандидата фактологическое объяснение на основе профиля.

---

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

Проект не использует тяжёлые C-зависимости, pandas, numpy или сторонний OpenAI SDK. CSV обрабатывается стандартной библиотекой Python, запросы к OpenAI API выполняются через встроенный модуль urllib.

1. Клонирование и переход в директорию

git clone https://github.com/astanahub/hack-277a2398-veritas.git
cd hack-277a2398-veritas

2. Установка зависимостей

python -m pip install -r requirements.txt

3. Запуск приложения

python -m streamlit run app.py

(Также поддерживается стандартный вызов streamlit run app.py.)

После запуска приложение автоматически откроется в браузере по адресу: http://localhost:8501.

---

🏗 Архитектура решения

Решение состоит из трёх частей:

1. Детерминированная фильтрация и ранжирование:

   • Точное совпадение города (city) и категории (categories).
   • Проверка занятости на дату (busy_dates) в диапазоне 23.09.2026–31.12.2026.
   • Проверка бюджета (price_from_kzt), формата события (event_formats), выбранного языка и предельной длительности (max_hours). Если max_hours пуст, кандидат не исключается по длительности.
   • Кандидаты сортируются фиксированным скорингом: языковое соответствие — 35%, релевантность описания формату — 30%, близость цены к бюджету — 20%, соответствие длительности — 15%. Равные баллы разрешаются по ID и имени.

2. Фактологические объяснения через OpenAI GPT-4o:

   • Генерируются 2–3 предложения с аргументацией, индивидуальной для профиля.
   • Объяснение включает цену, экономию относительно бюджета, языки и конкретные факты из description.
   • Промпт запрещает выдумывать сведения и использовать клише. Параметр генерации — temperature=0.

3. Автономный fallback:

   • В автономном режиме и при ошибке OpenAI API используется детерминированный локальный генератор. Для обычного поиска в режиме GPT-4o нужен ключ; демосценарии без ключа автоматически переключаются на автономный режим.
   • Fallback показывает точную экономию, языки и форматы профиля и подходящее предложение или достижение из description.
   • В карточке отображается метка «Объяснение: Детерминированный Fallback (Offline)».

---

🔑 Режимы генерации и ключи API

В боковой панели доступны два режима; по умолчанию выбран ввод собственного ключа:

• 🔑 OpenAI GPT-4o (Ввести свой API Key): выбран по умолчанию; поиск доступен после ввода ключа.
• ⚡ Автономный режим (Offline Fallback): объяснения формируются локально, внешние запросы не отправляются.

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

---

🎯 Проверка сценариев жюри

В верхней части приложения доступны три кнопки пресетов:

1. Плотная категория (Алматы, Ведущий, 15.10.2026, Корпоратив, 1 000 000 ₸): демонстрация скоринга и выдачи до трёх кандидатов.
2. Редкая категория (Астана, Флорист, 05.11.2026, Свадьба, 350 000 ₸): демонстрация неполной выдачи; ожидаемый кандидат — Хаку.
3. Запрос без результата (Алматы, Ведущий, 25.12.2026, Той, 300 000 ₸): детальная сводка причин, по которым специалисты не прошли фильтры.

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

---

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

hack-277a2398-veritas/
├── app.py                            # Streamlit-приложение на стандартной библиотеке Python
├── requirements.txt                  # Единственная зависимость: Streamlit
├── hackathon-dataset-anonymized.csv  # Каталог подрядчиков (66 профилей)
└── README.md                         # Документация

Приложение ищет CSV рядом с app.py под именем hackathon-dataset-anonymized.csv или hackathon-dataset-anonymized .csv (пробел перед .csv). В списковых полях поддерживаются разделители ,, ;, | и строковое представление Python-списка.

---

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

Ожидаемые поля: id, anon_name, categories, city, price_from_kzt, event_formats, languages, max_hours, busy_dates, description. Метка «Синтетический» на карточке определяется значением поля synthetic в CSV.

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

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