Beeline Campaign

Hackathon team repository for Exodus

Beeline Campaign

О ПРОДУКТЕ

Сайт и агент предназначены для кейса HackAlem «Beeline Tariff Marketing Campaigns». Продукт помогает планировать тарифные маркетинговые кампании: выбирает сегмент абонентов, целевой тариф и канал коммуникации, проверяет гипотезы пилотами и показывает план с расходами и охватом.

Все данные, тарифы, суммы и эффекты кейса синтетические и приведены только для учебной задачи. Исторические данные описывают другую выборку, поэтому их нельзя считать результатами целевых абонентов или соединять с целевой аудиторией по ID.

КАК РАБОТАЕТ РЕШЕНИЕ

Агент группирует целевую аудиторию по текущему тарифу и ARPU-сегменту. По истории из data/change_tariff.csv он оценивает переходы на другие тарифы: учитывает среднее изменение ARPU, частоту перехода и число наблюдений. История служит предварительной оценкой для выбора гипотез, а не истинным эффектом на целевой аудитории. Если файл истории недоступен, агент возвращает пустой план. Агент ранжирует гипотезы по ожидаемому чистому результату и выбирает до 16 разных ячеек «текущий тариф × ARPU-сегмент» для пилотов. Пилот проводится через SMS, если для перехода ожидается положительный результат в этом канале; иначе используется Push. Для ячейки от 500 абонентов запрашивается выборка 160 человек, для меньшей — 100. Фактический размер ограничивается доступной аудиторией, контактами, бюджетом и лимитом пилотов. На пилоты агент выделяет не более 15% доступного на момент запуска бюджета. После пилота он делит наблюдаемый эффект на множитель проверенного канала и обновляет оценку того же перехода для доступных каналов. Историческая оценка имеет вес 60 условных наблюдений; результат пилота учитывается с весом, равным фактическому размеру его выборки. Это снижает влияние малого пилота, но агент не вычисляет отдельный доверительный интервал. Агент оценивает ожидаемый результат каждого подходящего перехода с учётом стоимости канала. При составлении плана он приблизительно учитывает абонентов, уже охваченных пилотом, чтобы не засчитывать их эффект повторно. В финальный отбор попадают варианты с положительным ожидаемым приростом за вычетом стоимости контактов; среди них могут быть переходы, которые не прошли отдельный пилот. Совместимые ячейки с одинаковыми ARPU-сегментом, целевым тарифом и каналом объединяются в кампании до 5 000 абонентов. Агент выбирает до 10 кампаний по ожидаемому чистому результату с учётом оставшихся бюджета и контактов. Одна ячейка «текущий тариф × ARPU-сегмент» не используется в двух итоговых кампаниях. ОГРАНИЧЕНИЯ КЕЙСА

• Не более 10 итоговых кампаний. • Не более 5 000 абонентов в одной кампании. • Не более 15 000 контактов суммарно, включая пилоты. • Бюджет — 100 000 у.е. на все контакты, включая пилоты. • Не более 20 пилотов; каждый проводится на 10–200 абонентах. • Абонент учитывается один раз — по лучшей кампании.

Стоимость и множители каналов: • Push — бесплатно, ×0,50. • SMS — 4 у.е. за контакт, ×0,65. • Digital ads — 22 у.е. за контакт, ×0,85. • Звонок — 160 у.е. за контакт, ×1,20.

Чистый результат кейса — прирост ARPU по уникальным абонентам за вычетом стоимости коммуникаций.

ТЕХНОЛОГИИ

• Python — агент, демонстрационный API и локальный веб-сервер. • pandas — чтение и обработка таблиц CSV, сегментация аудитории. • NumPy — численные расчёты и симуляция пилотных наблюдений в демо-среде. • Стандартная библиотека Python (http.server, json, pathlib) — HTTP-сервер и API без отдельного веб-фреймворка. • HTML, CSS и JavaScript без дополнительных frontend-фреймворков — пользовательский интерфейс сайта. • Формат данных — CSV.

ТРЕБОВАНИЯ

• Python 3.10 или новее. • Пакеты numpy и pandas. • Современный браузер.

ЗАПУСК САЙТА С АГЕНТОМ

Откройте сайт в Гитхабе КАК ПРОВЕРИТЬ РЕШЕНИЕ

Локальная проверка файлов:

Из корневой папки проекта выполните проверку синтаксиса: python -m py_compile backend\agent.py backend\server.py Запустите сайт по инструкции выше. Убедитесь, что в браузере открывается панель, отображаются рекомендации и результаты пилотов. В отдельном окне PowerShell проверьте API: (Invoke-RestMethod http://127.0.0.1:8001/api/recommendations).summary Проверьте, что план не превышает лимиты бюджета, числа контактов, размера одной кампании и количества кампаний. Официальная проверка по ТЗ:

Распакуйте архив участника HackAlem в отдельную папку. В ней должны быть local_eval.py, make_submission.py, environment.py и папка data. Поместите проверяемый agent.py в корневую папку распакованного пакета, заменив шаблонный файл. Сохраните предусмотренную архивом структуру data, включая data/change_tariff.csv. Установите зависимости, необходимые пакету участника. Из корневой папки распакованного пакета выполните: python local_eval.py python local_eval.py --runs 10 python make_submission.py Проверьте вывод local_eval.py: агент должен завершить запуск без ошибок, провести пилоты, вернуть от 1 до 10 корректных кампаний и не превысить лимиты. Убедитесь, что make_submission.py создал submission.csv. Используйте файл, сформированный официальным скриптом. Локальный сайт использует демонстрационную среду с упрощённой симуляцией эффекта пилотов. Она нужна для показа сценария работы сайта и не заменяет официальный оценщик. Успешное открытие сайта или ответа API не означает, что официальный local_eval.py пройден. Официальные команды оценки нужно запускать в распакованном пакете участника; сам веб-сайт submission.csv не создаёт.

Для запуска сайта локально нужен установленный Python 3.10 или новее.

1. Распакуйте архив сайта. В папке должны находиться index.html и папка backend с файлами server.py, agent.py и данными в data.
2. Откройте эту папку в Проводнике, в адресной строке введите powershell и нажмите Enter.
3. Установите библиотеки — для этого потребуется интернет: python -m pip install numpy pandas
4. Запустите сервер: $env:HOST = "127.0.0.1" python backend/server.py
5. Откройте в браузере http://127.0.0.1:8001/. Агент запускается автоматически при загрузке рекомендаций. Кнопка «Пересчитать рекомендации» повторяет расчёт. Оставляйте окно PowerShell открытым, пока пользуетесь сайтом. Для остановки нажмите Ctrl+C. При последующих запусках повторять установку библиотек не требуется. Если порт 8001 занят, запустите сайт на другом порту: $env:PORT = "8010" python backend/server.py Тогда адрес сайта будет http://127.0.0.1:8010/.

СТРУКТУРА ПРОЕКТА

beeline-campaign-copilot/ README.txt index.html backend/ agent.py server.py data/ customer_profile_optimized.csv dict_tariff.csv segment_baseline.csv change_tariff.csv

ФАЙЛЫ ДАННЫХ

• customer_profile_optimized.csv — подготовленные признаки целевой аудитории. • dict_tariff.csv — коды и параметры тарифов. • segment_baseline.csv — агрегированные данные по сегментам. • change_tariff.csv — история смен тарифов из отдельной выборки.

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