Byteford United — агент управления тарифными кампаниями

Решение хакатонного кейса Beeline по выбору маркетинговых кампаний для смены тарифа в условиях ограниченного бюджета и неизвестного эффекта на текущей аудитории.

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

Краткое описание

Массовое предложение сменить тариф может принести дополнительный ARPU, не дать эффекта или привести к downsell. При этом каждый SMS, рекламный контакт или звонок расходует бюджет. Аналитику нужно выбрать небольшой набор кампаний среди множества сочетаний «аудитория → новый тариф → канал», не зная заранее их реального эффекта.

Наше решение — автономный Python-агент, который:

1. превращает исторические переходы в слабые первоначальные гипотезы;
2. проверяет гипотезы небольшими пилотами на текущей аудитории;
3. учитывает средний эффект и статистическую неопределённость;
4. возвращает портфель до 10 кампаний в пределах бюджета и лимита контактов.

Основная целевая метрика — чистый результат:

net = прирост ARPU − стоимость пилотных и финальных контактов

Проект предназначен для аналитиков и команд CRM-маркетинга, которым нужно автоматизировать разведку гипотез и распределение ресурсов между кампаниями.

Что реализовано

• обязательный класс Agent с методом act(env);
• генерация возможных переходов между тарифами для каждой пары «текущий тариф + ARPU-сегмент»;
• сглаженные исторические priors и fallback для переходов, которых нет в истории;
• до 10 первичных SMS-пилотов по 80 клиентов;
• до 10 адаптивных подтверждающих пилотов по наиболее ценным гипотезам;
• обновление оценки эффекта с учётом размера пилота и эффективности канала;
• консервативный отбор по нижней доверительной границе эффекта;
• выбор между push, sms и digital_ads для финальных кампаний;
• совместная оптимизация портфеля по чистому эффекту, бюджету, контактам и лимиту числа кампаний;
• безопасный fallback при недоступности или ошибке исторических priors;
• unit- и smoke-тесты контрактов, лимитов и воспроизводимости;
• локальная end-to-end оценка, проверка устойчивости на разных seed и A/B-сравнение стратегии с priors и без них;
• stress-бенчмарк со сдвинутыми эффектами, чтобы не оптимизироваться только под исторически благоприятную mock-модель;
• наглядный HTML-отчёт и построчный CSV-журнал контактов для ручной проверки;
• воспроизводимая генерация submission.csv;
• опциональный NVIDIA Brev workflow, который разворачивает окружение и сохраняет evidence проверки без секретов.

Основная стратегия не использует LLM и не зависит от внешнего API: числовое решение полностью воспроизводится локально.

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

История смен тарифов + справочник тарифов + текущая аудитория
                              │
                              ▼
              Сглаженные priors и fallback-гипотезы
                              │
                              ▼
               Первичная разведка разными пилотами
                              │
                              ▼
           Обновление среднего эффекта и неопределённости
                              │
                              ▼
                 Адаптивные уточняющие пилоты
                              │
                              ▼
        Консервативная оценка тарифов и каналов коммуникации
                              │
                              ▼
         Портфель до 10 кампаний под оставшиеся ограничения

Проверяющая среда создаёт Agent и вызывает Agent.act(env). Через env агент получает профиль аудитории, тарифы, каналы и остатки ресурсов. Узнавать эффект на текущей аудитории разрешено только через публичный env.run_pilot().

Первичные пилоты обеспечивают широкую разведку: агент проверяет как переходы с историей, так и несколько неизвестных сочетаний. Затем результаты пилотов нормализуются на эффективность канала и объединяются с первоначальной оценкой. Больший пилот имеет больший статистический вес. Штатный массовый финальный запуск разрешается только после двух наблюдений по гипотезе: stress-тесты показали, что это устойчивее единичного удачного пилота при сдвиге скрытых эффектов. Если подтверждённых прибыльных вариантов совсем нет, обязательный аварийный fallback возвращает одну синтаксически корректную бесплатную push-кампанию.

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

{
    "campaign_name": "main_1_tariff_4_mid_tariff_8_sms",
    "filter_arpu_segment": "MID",
    "filter_current_tariff": "tariff_4",
    "target_tariff": "tariff_8",
    "channel": "sms",
}

Технологии

Категория	Используется
Язык	Python
Работа с таблицами	pandas
Численные расчёты	NumPy
Тестирование	стандартный модуль unittest
Формат данных	CSV, pandas DataFrame
Модель принятия решений	сглаженные исторические оценки, последовательное вероятностное обновление, консервативная оценка и beam-search портфеля
AI/LLM	не используется
Внешние API	не используются агентом
Облачная среда	NVIDIA Brev — опционально, только для воспроизводимого запуска и evidence

Текущая версия проверена в локальном окружении Python 3.14. Диапазоны версий зависимостей зафиксированы в requirements.txt.

Архитектура проекта

Компонент	Назначение
agent.py	Минимальная обязательная точка входа Agent.act(env).
priors.py	Очистка истории, сглаживание, fallback и первичный рейтинг гипотез.
strategy.py	Политика пилотов, обновление оценок, выбор каналов и портфеля.
mock_environment.py	Локальная имитация среды и шумных пилотов.
scoring_core.py	Проверка кампаний, дедупликация клиентов и расчёт результата.
local_eval.py	Один полный прогон или серия прогонов на разных seed.
benchmark.py	Сравнение полного агента и fallback без priors на одинаковых seed.
stress_benchmark.py	Проверка устойчивости при расхождении истории и скрытых эффектов.
tuning_benchmark.py	Честное A/B-сравнение конфигураций на одинаковых stress-сценариях.
visual_report.py	HTML-дашборд и CSV-расшифровка одного mock-прогона.
make_submission.py	Генерация воспроизводимого submission.csv.
tests/	Unit- и smoke-тесты стратегии и priors.
scripts/brev_setup.sh	Развёртывание и полный проверочный прогон на NVIDIA Brev.
scripts/brev_verify.py	Сбор версий, GPU, результатов тестов и SHA-256 submission в evidence-отчёт.

agent.py зависит только от стабильного интерфейса CampaignStrategy. strategy.py получает кандидатов через контракт priors.build_candidates(...). Поэтому модель подготовки гипотез можно заменить, не меняя внешний интерфейс агента и проверяющей среды.

Подробное описание алгоритма и пути масштабирования находится в PROJECT_GUIDE.md.

Установка и запуск

Windows PowerShell или CMD

git clone https://github.com/BAITC-Hacks/hack-033bf26b-byteford-united.git
cd hack-033bf26b-byteford-united
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -X utf8 local_eval.py

Точка перед именем .venv обязательна.

Linux или macOS

git clone https://github.com/BAITC-Hacks/hack-033bf26b-byteford-united.git
cd hack-033bf26b-byteford-united
python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -r requirements.txt
./.venv/bin/python local_eval.py

NVIDIA Brev

На подготовленной Brev VM из корня репозитория:

bash scripts/brev_setup.sh

Скрипт создаёт .venv, устанавливает зависимости, запускает unit-тесты, local_eval, benchmark и генерацию submission. Отчёт и логи сохраняются в .brev-evidence/, который исключён из Git. GPU фиксируется как evidence окружения, но вычисления агента остаются CPU-bound и от GPU не зависят. Подробная инструкция находится в BREV.md.

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

1. Автоматические тесты

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

Результат OK подтверждает, что агент импортируется, возвращает корректные кампании, соблюдает доступные ресурсы, работает без внешних priors и воспроизводимо строит таблицу гипотез. Это проверка корректности кода, а не гарантия прибыли на скрытой выборке.

2. Один end-to-end прогон

.\.venv\Scripts\python.exe -X utf8 local_eval.py

Жюри может проверить:

• Статус: PASS;
• наличие проведённых пилотов;
• неотрицательные остатки бюджета и контактов;
• отсутствие отброшенных кампаний;
• итоговый net_arpu_gain на мок-среде.

Для более наглядной проверки:

.\.venv\Scripts\python.exe -X utf8 visual_report.py
start .agent-report\report.html

HTML показывает использование бюджета и контактов, экономический результат, пилоты, финальные кампании и пример охваченных абонентов. Рядом создаются:

• contact_ledger.csv — одна строка на каждый фактический контакт;
• subscriber_summary.csv — все 23 441 абонента и их итоговый вклад;
• campaign_summary.csv — сводка пилотов и финальных кампаний.

3. Устойчивость к шуму пилотов

.\.venv\Scripts\python.exe -X utf8 local_eval.py --runs 10

Команда показывает минимум, медиану, максимум и число положительных запусков на разных seed. Для более строгой проверки можно использовать --runs 50.

4. Вклад исторических priors

.\.venv\Scripts\python.exe -X utf8 benchmark.py --runs 10

Benchmark запускает на одинаковых seed полный агент и вариант только с тарифным fallback. Он проверяет интеграцию priors.py, но не предсказывает будущий судейский балл: эффекты скрытой среды будут другими.

5. Устойчивость к сдвигу эффектов

.\.venv\Scripts\python.exe -X utf8 stress_benchmark.py --runs 10

Команда оставляет агенту исходную историю, но изменяет скрытую mock impact-модель: добавляет шум эффектов, сдвигает конверсии и меняет знак части переходов. Для сравнения стратегий важны p10_net, средний результат худших 20% запусков и минимум. Сценарии являются стресс-тестами, а не прогнозом судейских эффектов.

6. Финальный артефакт

.\.venv\Scripts\python.exe -X utf8 make_submission.py

Команда запускает настоящего агента с фиксированным seed и пересоздаёт submission.csv. Подробная инструкция и интерпретация метрик находятся в TESTING.md.

Данные и интеграции

Источник	Использование
customer_profile.csv	Текущая аудитория, тарифы, сегменты и predicted_arpu; на судействе передаётся через env.customer_profile.
data/change_tariff.csv	Исторические смены тарифов для построения слабых priors.
data/dict_tariff.csv	Параметры тарифов и fallback для неизвестных переходов; на судействе справочник доступен через env.tariffs.
data/traffic.csv	Данные потребления из официального набора; напрямую текущей стратегией не читаются.
data/arpu_monthly.csv	Месячная история ARPU из официального набора; напрямую текущей стратегией не читается.
tariff_dictionary.csv, feature_dictionary.csv	Описания тарифов и признаков.
env.run_pilot()	Единственная интеграция для получения нового наблюдения об эффекте на целевой аудитории.

Сеть, облачные сервисы, базы данных и сторонние API во время работы агента не используются. API-ключи не требуются и не хранятся в репозитории.

Ограничения текущей версии

• Результаты local_eval.py относятся только к синтетической мок-среде и не гарантируют такой же эффект на скрытом судействе.
• Финальная сегментация использует текущий тариф и ARPU-сегмент. Признаки потребления данных и звонков пока не используются как отдельные фильтры.
• Политика рассчитана на четыре канала и их названия из условий хакатона.
• Размеры пилотов, квоты и доверительный коэффициент заданы константами в strategy.py, а не внешней конфигурацией.
• Состояние пилотов не сохраняется между отдельными запусками процесса.
• Beam-search является ограниченным приближённым поиском, а не точным математическим оптимизатором.
• Нет веб-интерфейса: по условиям кейса результатом является Python-агент и список кампаний. HTML-отчёт является локальной диагностикой, а не отдельным приложением.
• Проект предназначен только для синтетических данных хакатона и не является готовой production-системой оператора.

План развития — конфигурация стратегии, универсальное подключение каналов, хранилище экспериментов, temporal backtesting, causal/uplift-модель, контейнеризация, CI и мониторинг — подробно описан в PROJECT_GUIDE.md.

Безопасность и соответствие правилам

• Агент использует только выданные данные и публичный интерфейс env.
• Доступ к скрытому состоянию через closure, gc, inspect и подобные обходы не используется.
• .env, ключи и credential-файлы исключены через .gitignore.
• Основная логика не требует LLM или секретов.

Deployed-версия

Публичная deployed-версия отсутствует. Решение запускается локально или внутри проверяющей Python-среды организаторов; отдельный веб-сервис условиями кейса не требуется.

Дополнительная документация

• PROJECT_GUIDE.md — полный разбор алгоритма, архитектуры, демонстрации и масштабирования.
• TESTING.md — пошаговая проверка и объяснение метрик.
• BREV.md — воспроизводимый запуск и evidence на NVIDIA Brev.
• PROGRESS.md — журнал этапов и локальных baseline-результатов.
• PARTICIPANT_GUIDE.md — исходное руководство организаторов.