Умный подбор подрядчиков

Проект команды OZGE для хакатона HackAlem AI (23.09.2026), трек «Креативные индустрии», задание «Умный подбор подрядчиков».

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

---

Какую задачу решаем

На креативном рынке заказчик и подрядчик не находят друг друга, потому что говорят на разных языках:

• Боль заказчика — он не умеет формулировать задачу. Приходит с фразой «хочу видео для инстаграма, что-нибудь красивое» — без формата, объёма, сроков и бюджета.
• Боль подрядчика — он получает кривой бриф и заказчиков не по бюджету. Время уходит на переписку, которая ничем не кончается.

Обычный каталог подрядчиков эту проблему не решает: он требует от заказчика уже знать, что искать. Наше приложение сначала достраивает запрос до брифа, и только потом ищет.

Что делает приложение

В приложении три вкладки: по одной на каждую сторону рынка и одна со сводкой.

🙍 Вкладка «Я заказчик»

1. Собирает бриф из свободного запроса: услуга, город, бюджет, срок, формат, стиль, язык, цель, объём. Понимает запросы и на русском, и на казахском — включая «мың» как тысячи, «күн» и «апта» как сроки, и сам определяет язык по буквам алфавита.
2. Показывает, чего в брифе не хватает, и задаёт заказчику конкретные вопросы («Какой у вас бюджет?», «К какой дате нужен результат?»).
3. Принимает ответы прямо на странице. Под вопросами стоят поля нужного типа: бюджет — счётчиком в тенге, срок — в днях, услуга и город — списками. Заказчик отвечает на то, что знает, нажимает «Дополнить бриф и пересчитать подбор» — бриф дозаполняется, подбор пересчитывается, а над брифом появляется «было 86 %, +14 п.п. после ваших ответов». Отвечать на все вопросы не обязательно.
4. Честно показывает, что домыслило за заказчика, — чтобы он мог поправить.
5. Подбирает топ-5 подрядчиков и по каждому объясняет, почему подходит и на что обратить внимание (другой город, не успевает по сроку, не хватает бюджета).
6. Отдаёт готовый текст брифа, который можно скопировать или скачать и отправить подрядчику.

Нереальные запросы приложение не скрывает: на запрос «ТВ-ролик как у больших брендов за 50 000 ₸» оно прямо пишет, что бюджета не хватает, и показывает ближайшие реальные варианты.

🎥 Вкладка «Я подрядчик»

1. Подрядчик выбирает свой профиль из базы — приложение подставляет его услугу, город, вилку цен и обычный срок.
2. Видит входящие заявки, отсортированные по совпадению со своим профилем.
3. По каждой заявке — три светофора: бюджет (по бюджету заказчик или нет и какая разница), срок (успевает или нет), качество брифа (полный / неполный / сырой запрос).
4. Фильтры: скрыть заказчиков не по бюджету, показывать только заявки с полным брифом, минимальный процент совпадения.
5. По каждой заявке — готовый черновик ответа заказчику, который подставляется сам: «взять в работу», «уточнить детали» (с конкретными вопросами по пустым полям) или «отказать: не мой бюджет» (с объяснением и вариантами, что можно сделать за эти деньги).
6. Кнопка «Отправить ответ и записать сделку» фиксирует результат: заявка помечается статусом (взято в работу / уточняются детали / отказ по бюджету), сверху считается счёт — сколько ответов отправлено и на какую сумму работы взято. Сделки сохраняются на диск (data/deals.json) и переживают перезагрузку страницы. Есть фильтр «скрыть заявки, на которые уже ответил», история всех сделок таблицей и кнопка сброса демо-данных.

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

📊 Вкладка «Рынок»

Сводка по всем данным сразу — то, что не видно из одной заявки. Все цифры пересчитываются из данных при каждом открытии, ничего не вписано руками.

Ключевые показатели на демонстрационных данных:

Показатель	Значение	О чём говорит
Полнота исходного запроса	45 %	столько заказчик заполняет сам
Полнота после разбора	89 %	столько получается после обработки запроса
Прирост	+44 п.п.	это подрядчику больше не нужно вытягивать перепиской
Заявок без бюджета	3 из 12 (25 %)	главная дыра в брифах
Заявок без срока	3 из 12 (25 %)	вторая дыра
Профильных пар «подрядчик — заявка»	100	профиль подходит
Из них тупиковые по бюджету	22 (22 %)	каждая пятая переписка закончится ничем
Рынок закрывает заявок	9 из 12	остальные три — заказчики не назвали бюджет

Плюс два графика: полнота брифа до и после разбора по каждой заявке и спрос против предложения по 18 услугам (где дефицит подрядчиков, а где конкуренция). У каждого графика есть табличный вид.

Внизу — воронка «что стало с заявками»: сколько заявок получили ответ, сколько взято в работу, сколько отклонено по бюджету и на какую сумму подрядчики взяли работы. Появляется, как только вы запишете первую сделку на вкладке «Я подрядчик».

Выгрузка данных

Из приложения выгружается всё, что оно посчитало — CSV открывается в Excel и Google Таблицах без плясок с кодировкой (разделитель ;, BOM в начале, поэтому кириллица не ломается).

Где	Кнопка	Что выгружается
🙍 Я заказчик	Скачать бриф файлом	готовый текст брифа для подрядчика (.txt)
🙍 Я заказчик	Скачать подбор в CSV	топ-5 подрядчиков: баллы, цены, сроки, причины и риски по каждому
🎥 Я подрядчик	Скачать эти заявки в CSV	входящие заявки с учётом фильтров: совпадение, полнота брифа, вердикты по бюджету и сроку
🎥 Я подрядчик	Скачать ответ файлом	текст ответа конкретному заказчику (.txt)
🎥 Я подрядчик	Скачать сделки в CSV	история сделок: кто, кому, когда, с каким статусом и текстом ответа
📊 Рынок	Скачать сводку в CSV	все показатели рынка одной таблицей
📊 Рынок	Скачать в CSV (в таблицах)	полнота брифов по заявкам и спрос/предложение по услугам

Версия для браузера — без установки

В папке web/ лежит самостоятельная HTML-страница: весь проект одним файлом, без Python, без сервера и без установки. Её можно открыть двойным щелчком, отправить ссылкой или посмотреть с телефона.

open web/index.html          # macOS

Подбор на странице считает тот же алгоритм, что и приложение на Streamlit, и те же данные — цифры совпадают до процента. Чего на странице нет: разбора запроса через OpenAI, сохранения сделок и выгрузки в CSV — это есть в полном приложении ниже.

Пересобрать страницу после изменения данных:

python3 web/build.py

Системные требования

• macOS, Windows или Linux
• Python 3.11 или новее. Проверить свою версию: python3 --version (на Windows — python --version). Проверялось на Python 3.11 и macOS.
• Интернет нужен только для установки зависимостей. Само приложение в демо-режиме работает офлайн.

Установка

Шаг 1. Проверьте версию Python — нужна 3.11 или новее:

python3 --version

Если версия подходит, дальше везде используйте python3. Если она старее (частый случай на macOS, где python3 — это 3.9), подставьте вместо python3 конкретную версию: python3.11, python3.12 и так далее.

Шаг 2. Склонируйте репозиторий и поставьте зависимости:

git clone https://github.com/BAITC-Hacks/hack-0ba3e8ce-ozge.git
cd hack-0ba3e8ce-ozge
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

На Windows отличаются две команды: вместо python3 -m venv .venv — py -3.11 -m venv .venv, вместо source .venv/bin/activate — .venv\Scripts\activate.

Запуск

streamlit run app.py

Streamlit сам откроет браузер на http://localhost:8501. Если этого не произошло — откройте адрес вручную. Остановить приложение: Ctrl+C в терминале.

Ключ API для запуска не нужен. Без ключа приложение запускается в демо-режиме и работает полностью.

✅ Проверено 23.09 в 16:24 на финальной версии. Репозиторий склонирован в чистую папку, шаги из разделов «Установка» и «Запуск» выполнены дословно, файла .env не было. На проверочной машине python3 оказался версии 3.9 — по инструкции взяли python3.11, и всё поставилось. Приложение запустилось в демо-режиме; пройдены все шаги раздела «Как проверить», включая запись сделки и перезагрузку страницы. Ошибок в консоли браузера нет.

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

Быстрая проверка — 2 минуты

1. Запустите streamlit run app.py.
2. В левой колонке должно быть написано «ДЕМО-РЕЖИМ (ключ API не нужен)», а ниже — Подрядчиков 40 и Заявок 12.
3. На вкладке «🙍 Я заказчик» нажмите пример «Хочу что-нибудь для инстаграма», затем кнопку «Собрать бриф и подобрать подрядчиков». Ожидаемый результат: «Бриф заполнен на 86 %», услуга «Видеомонтаж», город «Астана», бюджет «не указан». Ниже — блок «Ответьте на вопросы» с вопросом про бюджет и топ-5 подрядчиков, первый — «Reels Factory», совпадение 94 %.
4. Перейдите на вкладку «📊 Рынок». Ожидаемый результат: «Запрос как есть — 45 %», «После разбора — 89 %» с приростом +44 п.п., «Тупик по бюджету — 22» и пометка «22 % впустую». Ниже — два графика и таблицы под ними.

Если эти четыре шага прошли — проект работает.

Полная проверка — 7 минут

5. Вернитесь на «🙍 Я заказчик» и нажмите пример «Подрядчик не по бюджету» → «Собрать бриф и подобрать подрядчиков». Ожидаемый результат: первым идёт «Студия „Кадр“» с совпадением 87 %, и в блоке «На что обратить внимание» прямо написано «бюджета не хватает: у них от 250 000 ₸» и «может не успеть». Вторым — аэросъёмка, которая в бюджет 50 000 ₸ укладывается.
6. Снова нажмите пример «Хочу что-нибудь для инстаграма» → «Собрать бриф и подобрать подрядчиков». В блоке «Ответьте на вопросы» в поле «Какой у вас бюджет в тенге?» введите 300000 и нажмите «Дополнить бриф и пересчитать подбор». Ожидаемый результат: полоса сверху меняется на «Бриф заполнен на 100% (было 86%, +14 п.п. после ваших ответов)», появляется «Бриф полный — подрядчику можно отправлять как есть», а подбор пересобирается: первым становится «Айдос Ж.» со 100 % и причиной «бюджета хватает с запасом».
7. Перейдите на вкладку «🎥 Я подрядчик» (профиль по умолчанию — «Ozge-like Media — Видеопродакшн, Астана»). Ожидаемый результат: список входящих заявок, вверху «Онлайн-школа „Білім+“» с совпадением 87 %. У заявки «ТОО „Астык Трейд“» — два красных светофора: «Бюджет 50 000 ₸ не тянет: ваш минимум 120 000 ₸» и «Не успеваете».
8. Раскройте у «ТОО „Астык Трейд“» блок «Бриф заказчика и черновик ответа». Ожидаемый результат: переключатель ответа автоматически стоит на «Отказать: не мой бюджет», ниже — готовое вежливое письмо с тремя вариантами, что реально сделать за эти деньги.
9. У заявки «Онлайн-школа „Білім+“» раскройте тот же блок и нажмите «Отправить ответ и записать сделку». Ожидаемый результат: вверху в блоке «Ваши сделки» появляется «Ответов отправлено: 1», «🟢 Взято в работу: 1» и «В работе на сумму: 400 000 ₸», а на карточке заявки — зелёная плашка «Вы ответили … : Взято в работу».
10. Обновите страницу в браузере. Ожидаемый результат: сделка на месте — она сохранена на диск, а не в памяти вкладки.
11. Вернитесь на «📊 Рынок» и прокрутите вниз. Ожидаемый результат: появился блок «🤝 Воронка: что стало с заявками» — «Заявок всего 12», «Получили ответ 1», «🟢 Взято в работу 1».
12. Нажмите любую кнопку «Скачать … в CSV». Ожидаемый результат: файл скачивается и открывается в Excel с нормальной кириллицей и разбивкой по колонкам.
13. Напишите свой запрос в поле на вкладке «🙍 Я заказчик», например: Нужно смонтировать 10 рилсов для инстаграма, Астана, бюджет 200 тысяч, срочно за 3 дня, на казахском Ожидаемый результат: бриф заполняется сам — услуга «Видеомонтаж», город «Астана», бюджет 200 000 ₸, срок 3 дн., язык каз, — и подбор пересчитывается. Это работает на любом тексте, не только на готовых примерах.
14. Проверьте запрос на казахском: маған Астанада бейне түсіру керек, бюджет 200 мың теңге, 5 күн ішінде Ожидаемый результат: услуга «Видеопродакшн», город «Астана», бюджет 200 000 ₸, срок 5 дн., язык каз.
15. Введите в поле бессмыслицу — например ыпаоывдлапо фыва — и нажмите кнопку. Ожидаемый результат: приложение не делает вид, что поняло: «Бриф заполнен на 0 %», и над списком подрядчиков красным написано, что из запроса ничего не удалось понять и доверять списку нельзя.

Чтобы вернуть демо в исходное состояние: вкладка «🎥 Я подрядчик» → «История всех сделок» → «Сбросить демо-сделки».

Демо-режим (проверка без личных аккаунтов участника)

Приложение работает без ключа API и без каких-либо аккаунтов:

• разбор запроса идёт по правилам (модуль core.py, функция parse_request_offline) — работает на любом введённом тексте;
• подбор, баллы, причины и риски считает наш алгоритм — он вообще не зависит от ИИ;
• для трёх готовых примеров дополнительно показываются заранее сохранённые ответы модели (файл data/demo_examples.json), чтобы было видно, как выглядит результат в режиме с ИИ.

Режим определяется автоматически: если переменная OPENAI_API_KEY пустая — демо-режим. Текущий режим всегда написан в левой колонке приложения.

Как включить режим с ИИ (не обязательно)

cp .env.example .env
# впишите в .env свой ключ: OPENAI_API_KEY=sk-...
streamlit run app.py

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

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

Переменная	Обязательна	Значение по умолчанию	Назначение
OPENAI_API_KEY	нет	пусто	Ключ OpenAI. Пустой → демо-режим
OPENAI_MODEL	нет	gpt-4o-mini	Какая модель используется

Шаблон — в .env.example. Файл .env в репозиторий не попадает (.gitignore).

Данные

⚠️ Данные в data/contractors.json — демонстрационные и полностью вымышленные. 40 подрядчиков креативной индустрии (видеопродакшн, монтаж, фото, брендинг, дизайн, SMM, таргет, копирайтинг, сайты, моушн, звук, иллюстрация, 3D, студии, мероприятия, аэросъёмка, субтитры, подкасты) по городам Астана, Алматы, Шымкент, Караганда и онлайн. Названия студий и имена не соответствуют реальным компаниям и людям; цены, рейтинги и отзывы сгенерированы для демонстрации.

Поля карточки подрядчика: услуга, город, вилка цен и единица измерения, форматы работ, стили, языки, обычный срок, рейтинг, число отзывов, описание портфолио.

data/requests.json — 12 демонстрационных входящих заявок от заказчиков (свободный текст + разобранный бриф). Часть заявок намеренно неполные или не по бюджету — на них видно, как работает отсев.

data/demo_examples.json — три готовых примера запросов с сохранёнными ответами модели для демо-режима.

data/deals.json — сделки, которые создаются при работе с приложением. Файла в репозитории нет (он в .gitignore): при первом запуске сделок ноль, приложение создаёт файл само. Сбросить сделки можно кнопкой в истории на вкладке «Я подрядчик».

Как устроен подбор

Баллы (максимум 100) складываются из:

Критерий	Баллов	Логика
Совпадение услуги	40	точное совпадение профиля; смежная услуга — 18
Бюджет	25	попал в вилку — 25; хватает с запасом — 22; чуть ниже минимума — 12; сильно ниже — 0–4
Город	15	тот же город — 15; онлайн — 11; другой город — 2
Формат работы	10	совпадение с форматами и портфолио
Стиль	10	совпадение по словам о стиле
Срок	10	подрядчик успевает к дедлайну
Язык	5	работает на нужном языке
Репутация	10	рейтинг и количество отзывов

Если профиль подрядчика вообще не совпал с нужной услугой и не входит в список смежных (RELATED_SERVICES в core.py), его итоговый балл ограничен 45 % — чтобы фотограф не попадал в топ на заявку о логотипе только потому, что он в том же городе.

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

Если из запроса не удалось вытащить вообще ничего (ни услуги, ни города, ни бюджета, ни срока), приложение прямо говорит об этом и предупреждает, что список ниже собран по рейтингу, а не по задаче.

Та же функция оценки работает в обе стороны: во вкладке заказчика она ранжирует подрядчиков под бриф, во вкладке подрядчика — заявки под профиль, а во вкладке «Рынок» — считает, сколько пар вообще могут договориться.

Заявка считается закрытой рынком, если нашёлся хотя бы один подрядчик с совпадением ≥ 60 % и подходящим бюджетом (MATCH_THRESHOLD в core.py).

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

app.py                    веб-интерфейс (Streamlit): вкладки «Я заказчик»,
                          «Я подрядчик» и «Рынок»
core.py                   база, разбор запроса по правилам, алгоритм подбора,
                          сборка брифа, проверка бюджета, черновики ответов,
                          метрики рынка
ai.py                     слой OpenAI с автоматическим откатом на работу без ИИ
data/contractors.json     демонстрационная база подрядчиков (40 записей)
data/requests.json        демонстрационные входящие заявки (12 записей)
data/demo_examples.json   готовые примеры для демо-режима
data/deals.json           сделки (создаётся приложением, в репозиторий не попадает)
web/index.html            версия для браузера, одним файлом, без установки
web/template.html         шаблон этой страницы
web/build.py              сборка web/index.html из шаблона и данных
requirements.txt          зависимости с точными версиями
.env.example              шаблон переменных окружения
.streamlit/config.toml    настройки Streamlit
DEMO.md                   сценарий демонстрации проекта
CLAUDE.md                 правила разработки проекта

Использованные библиотеки и модели

Что	Версия	Зачем
Python	3.11	язык
Streamlit	1.64.0	веб-интерфейс
openai	3.19.0	обращение к модели
python-dotenv	1.2.3	чтение .env
pandas	3.0.6	таблицы для графиков
Altair	6.3.0	графики на вкладке «Рынок»
Модель gpt-4o-mini (OpenAI)	—	разбор свободного запроса в бриф и объяснение подбора

Готовые шаблоны и сторонний код не использовались. Весь код написан в ходе хакатона с помощью Claude Code.

Команда

OZGE — Акжаркын Коздибаева, основатель контент-студии Ozge media (Астана). Задача выбрана из собственной практики: студия одновременно и заказывает подрядчиков, и сама выступает подрядчиком.

Сценарий демонстрации

Пошаговый сценарий защиты с цифрами и ответами на типовые вопросы — в DEMO.md.

Правила разработки

Зафиксированы в CLAUDE.md.