Beeline Tariff Marketing Campaign Agent

SapaTech · HackAlem AI 2026 · трек 04 «Телекоммуникации»

Агент планирует кампании смены тарифа для 23 441 синтетического абонента: изучает профиль и историю переходов, проводит пилоты, учитывает их результаты и выбирает до 10 кампаний. Цель — максимизировать прирост ARPU за вычетом стоимости контактов, соблюдая ограничения бюджета и охвата.

Основной пользователь — маркетинговый аналитик, планирующий кампании на следующий месяц. На входе — аудитория и история смены тарифов; на выходе — план с целевыми сегментами, тарифами и каналами коммуникации в submission.csv.

Решение запускается в терминале и реализует официальный интерфейс Agent.act(env) -> list[dict]. Используется локальная статистическая стратегия; ключи API, внешние модели, GPU и веб-сервер не требуются.

Технологии и данные

• Python 3.11+ — агент, управление пилотами и проверки.
• pandas 3.0.1 — чтение CSV и обработка профилей и истории переходов.
• NumPy 2.3.5 — численные расчёты оценок и портфеля кампаний.
• unittest из стандартной библиотеки — автоматические тесты.

Версии сторонних библиотек зафиксированы в requirements.txt. Официальная среда предоставляет профиль из customer_profile.csv, тарифы из data/dict_tariff.csv и параметры каналов. Агент отдельно читает data/change_tariff.csv для исторических оценок. Все эти данные поставляются организаторами в ZIP кейса; внешние источники данных и API не используются.

Что нужно для запуска

• Git и доступ к этому репозиторию.
• Python 3.11 или новее с поддержкой venv и pip; проверен Python 3.13.7 на macOS.
• Интернет для клонирования и установки зависимостей. После установки агент работает локально.
• Официальный beeline_case_participants.zip от организаторов. В нём находятся данные, среда, evaluator и генератор CSV. Эти файлы не хранятся в Git. Судьям нужен исходный пакет кейса Beeline; если его нет, запросите его у организаторов.

Клонируйте полный репозиторий, включая папку strategy/. Файлы strategy/__init__.py и strategy/core.py нужны для запуска командной стратегии; evals/ и scripts/ — для описанных ниже проверок и установки материалов. Передачи одного agent.py недостаточно для воспроизведения нашего результата: при отсутствии strategy/ он использует резервный шаблон организаторов, который генерирует другой CSV.

Используйте новый клон: команда make_submission.py заново создаст в нём submission.csv. Установщик перенесёт из ZIP только 13 необходимых файлов без изменения их содержимого. В командах ниже замените путь к архиву на свой; кавычки позволяют использовать путь с пробелами. Запускайте команды по порядку из корня клона и переходите к следующей только после успешного завершения предыдущей.

Официальный интерфейс проверки

По ТЗ проверка выполняется через python local_eval.py, а CSV создаётся через python make_submission.py. Оба скрипта из пакета организаторов импортируют Agent из agent.py и вызывают Agent().act(env) с подготовленной средой. Этот интерфейс используется и для работы агента со скрытой средой судейства. Самостоятельный запуск python agent.py в текущей версии не проводит оценку: используйте последовательность ниже. После установки Agent.act(env) работает без интернета и не устанавливает зависимости.

Запуск на macOS / Linux

Убедитесь, что python3 --version показывает Python 3.11+. Если установлено несколько версий, используйте подходящую команду, например python3.13, вместо python3 при создании окружения. Активация venv не нужна.

git clone https://github.com/BAITC-Hacks/hack-6e2e5c8b-sapatech.git beeline_check
cd beeline_check
git switch main
python3 --version
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python scripts/prepare_case.py '/absolute/path/to/beeline_case_participants.zip'
.venv/bin/python -m unittest scripts.test_agent strategy.tests.test_core strategy.tests.test_robustness evals.test_contract_checks evals.test_compare_isolated -v
.venv/bin/python local_eval.py
.venv/bin/python evals/check_agent.py --agent agent.py --package .
.venv/bin/python evals/check_agent.py --agent agent.py --package . --feedback-check
.venv/bin/python make_submission.py
git diff --exit-code --ignore-space-at-eol -- submission.csv

Запуск на Windows / PowerShell

Убедитесь, что py -3 --version показывает Python 3.11+. Команды используют Python Launcher (py); если его нет, используйте python вместо py -3, предварительно проверив версию. Активация venv и изменение ExecutionPolicy не нужны.

git clone https://github.com/BAITC-Hacks/hack-6e2e5c8b-sapatech.git beeline_check
cd beeline_check
git switch main
py -3 --version
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe scripts/prepare_case.py 'C:\path\to\beeline_case_participants.zip'
.\.venv\Scripts\python.exe -m unittest scripts.test_agent strategy.tests.test_core strategy.tests.test_robustness evals.test_contract_checks evals.test_compare_isolated -v
.\.venv\Scripts\python.exe local_eval.py
.\.venv\Scripts\python.exe evals/check_agent.py --agent agent.py --package .
.\.venv\Scripts\python.exe evals/check_agent.py --agent agent.py --package . --feedback-check
.\.venv\Scripts\python.exe make_submission.py
git diff --exit-code --ignore-space-at-eol -- submission.csv

Полный чистый запуск подтверждён на macOS. Для Linux и Windows приведены соответствующие команды; в последней независимой проверке эти ОС не запускались.

Как понять, что проверка прошла

Шаг	Ожидаемый результат
Установка ZIP	Installed 13 unchanged files
Unit-тесты	Ran 54 tests, затем OK
local_eval.py	Статус: PASS, чистый результат около +253 392 на seed 42
check_agent.py	"errors": [], 7 финальных кампаний и 20 пилотов
--feedback-check	"feedback_changes_campaigns": true; errors пуст в обоих сценариях
make_submission.py	submission.csv с 7 строками кампаний и заголовком
Последний git diff	Нет вывода и код завершения 0: CSV совпал с версией в Git с учётом различий LF/CRLF

На seed 42 суммарно используются 11 558 контактов и 99 998 из 100 000 единиц бюджета. Выполнение Agent.act в проверке на macOS заняло около 2 секунд. Строка evaluator «Кампаний: 27» включает 20 пилотов и 7 финальных кампаний. Предупреждения о cap 5 000, частичном охвате и повторных контактах допустимы; проверка исходного ответа через check_agent.py должна завершиться без ошибок.

Проверка на нескольких сценариях

После установки выполните:

.venv/bin/python local_eval.py --runs 10

В PowerShell используйте .\.venv\Scripts\python.exe local_eval.py --runs 10. В независимой проверке все 10 прогонов завершились: 9 прибыльных, 1 убыточный; медиана +622 922, минимум −70 362, максимум +1 349 809.

Текущая версия включает стратегию T-10. На одинаковых проверочных seed 100–199 она сравнивалась с предыдущей версией в отдельных процессах и каталогах:

Показатель, 100 прогонов	Предыдущая версия	Текущая T-10
Средний net	+286 700.61	+629 492.15
Убыточных прогонов	27	5
Худший net	−742 519.79	−389 787.24

Независимое повторение на macOS подтвердило все 200 результатов, отсутствие ошибок исходного ответа, нарушений лимитов и перехода на резервный шаблон. T-10 лучше в 76 из 100 пар. На демонстрационном seed 42 результат снизился с +327 917.04 до +253 391.73; улучшение на каждом запуске не гарантируется. Подробности и воспроизводимые данные: отчёт T-10 и результаты по seed. Старые отчёты T-04/T-05 и аудиты в docs/planning/ относятся к прежней стратегии.

Данные синтетические и не описывают реальных клиентов или показатели Beeline. Mock-среда проверяет механику, но её эффекты отличаются от скрытого судейства: эти числа не предсказывают итоговый балл и не гарантируют прибыль.

Как работает решение

1. agent.py читает публичные данные и историю, управляет пилотами, временем и ресурсами, проверяет формат финального ответа.
2. strategy/ строит кандидатов по текущему тарифу и ARPU-сегменту, уточняет исторические оценки по результатам пилотов и выбирает портфель кампаний. После восьми пилотов приоритет получают повторные проверки перспективных кандидатов. Наблюдения объединяются по каналу; повторные push-пилоты снижают шум измерений, сохраняя неопределённость переноса на платные каналы.
3. evals/ проверяет исходный ответ до исправлений официального evaluator, соблюдение лимитов, влияние обратной связи и воспроизводимость.
4. Официальный make_submission.py запускает агента на seed 42 и создаёт CSV.

Ограничения: 1–10 финальных кампаний, до 5 000 абонентов на кампанию, 15 000 контактов и 100 000 бюджета вместе с пилотами; до 20 пилотов с запросом 10–200 абонентов. Каналы: push, sms, digital_ads, call. Один абонент даёт только лучший эффект, но повторные контакты расходуют ресурсы.

История переходов не доказывает причинный эффект кампании. Перенос оценок бесплатных push-пилотов на платные каналы — приближение без прямой проверки пилотами на этих каналах. Подробнее: описание стратегии и разбор рисков.

Если запуск не удался

Сообщение / ситуация	Что проверить
Repository not found при клонировании	Доступ вашей учётной записи GitHub к командному репозиторию
Ошибка установки numpy/pandas	Версию Python (3.11+), наличие pip и доступ к PyPI; используйте зафиксированный requirements.txt
Не найден local_eval.py, mock_environment или CSV	Успешно ли выполнен scripts/prepare_case.py; текущий каталог должен быть корнем клона
FileNotFoundError при установке ZIP	Заменён ли пример пути на существующий архив
KeyError при установке ZIP	Используется ли исходный ZIP кейса: установщик ожидает официальную структуру файлов
Refusing to overwrite different file	Используйте новый клон: установщик сохраняет уже существующие отличающиеся файлы