She++ Campaign Lab — агент тарифных кампаний

Решение кейса Beeline Tariff Marketing Campaigns для маркетингового аналитика. Агент исследует возможности смены тарифа, проводит пилоты и формирует план кампаний при ограниченных бюджете и числе контактов. Цель — увеличить ARPU с учётом затрат на коммуникацию и риска убыточных переходов.

Все данные кейса синтетические. Результаты не описывают реальный бизнес Beeline. Условия задачи: ТЗ организаторов.

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

• Автономный интерфейс Agent.act(env) -> list[dict], работающий без сети и внешних API.
• Сегментация по текущему тарифу и ARPU; дополнительные фильтры потребления для ограничения размера аудитории.
• Ранжирование гипотез по публичной истории переходов и адаптация решений по результатам текущих пилотов.
• Выбор пилотов, повторных проверок и каналов с учётом ресурсов и неопределённости наблюдений.
• Формирование непересекающихся финальных сегментов с учётом остатков после пилотов.
• Независимый аудит схемы, фильтров, контактов и расходов; тесты агента и валидатора.
• Сравнение с шаблоном организаторов на одинаковых seed, журнал решений и локальный HTML-отчёт.
• Задачи VS Code для запуска проверок, подготовки CSV и демонстрации.

Ограничения задачи: 1–10 финальных кампаний, до 5000 абонентов на кампанию, до 15 000 контактов и 100 000 у.е. вместе с пилотами; до 20 пилотов по 10–200 абонентов.

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

1. Среда передаёт агенту профиль аудитории, доступные тарифы, каналы и остатки ресурсов.
2. Агент формирует сегменты и ранжирует переходы по data/change_tariff.csv. История относится к другой выборке и используется как источник гипотез.
3. Через env.run_pilot агент проверяет гипотезы на небольших выборках. Наблюдаемый эффект влияет на следующие действия; пилоты расходуют общий бюджет и контакты.
4. По собранным свидетельствам агент выбирает финальные кампании. Для каждой указывает фильтры аудитории, целевой тариф и канал. Причины решений доступны в Agent.last_report.
5. Официальный оценщик рассчитывает эффект и расходы, включая пилоты. Скрипт make_submission.py создаёт файл сдачи; отдельный инструмент строит отчёт для аналитика.

Технологии

Python, pandas 2.3.3, NumPy 2.0.2; unittest для тестов. HTML/CSS и небольшой JavaScript используются для локального отчёта с поиском по кампаниям. Среда проверена на Python 3.9.6; версии зависимостей зафиксированы в requirements.txt, полный состав проверенного окружения — в requirements-lock.txt.

LLM, облачные AI-модели, платные API и реальные сервисы рассылки не подключены. Агентность реализована программным циклом «наблюдение → выбор эксперимента → обновление решения».

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

Компонент	Назначение
agent.py	Гипотезы, адаптивные пилоты, оценки неопределённости, выбор финального плана
plan_validation.py	Независимый аудит по публичным данным; не импортирует агент и скоринг
local_eval.py, make_submission.py	Оригинальные инструменты организаторов: оценка и генерация CSV
tools/check_package.py	Наличие исходных файлов и обязательных колонок профиля
tools/benchmark.py	Сравнение с шаблоном на одинаковых seed, сохранение всех результатов
tools/build_report.py	Запуск агента, аудит, HTML-отчёт и JSON с журналом решений
tests/	Проверки поведения агента и ручные контрольные примеры для валидатора
.vscode/, docs/	Команды редактора, совместная работа, демонстрация и условия приёмки

Поток данных: публичные CSV → среда → агент ↔ пилоты → финальный план → оценка / аудит / отчёт. Оригинальные файлы пакета сохранены без изменений; их контрольные суммы находятся в docs/organizer_files.sha256.json.

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

Нужны Git, Python и доступ к закрытому командному репозиторию. В VS Code откройте Terminal → New Terminal / Терминал → Создать терминал:

git clone https://github.com/BAITC-Hacks/hack-acbb98e4-she.git
cd hack-acbb98e4-she

Если репозиторий уже открыт, повторное клонирование не требуется.

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Windows, PowerShell:

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Если PowerShell запрещает активацию, вместо python используйте .\.venv\Scripts\python.exe; менять системную политику для запуска не требуется. Для воспроизведения полного набора зависимостей замените requirements.txt на requirements-lock.txt. Установка зависимостей требует доступа к индексу пакетов; последующая работа агента — офлайн.

В VS Code выберите File → Open Folder / Файл → Открыть папку и папку репозитория. Через палитру команд выберите Python: Select Interpreter → .venv. Откройте Terminal → Run Task / Терминал → Запустить задачу: доступны пронумерованные проверки комплекта, агента, устойчивости, тестов, сравнения, генерации CSV и HTML. Задачи используют интерпретатор .venv напрямую и не требуют активированной оболочки.

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

Из корня проекта с установленными зависимостями выполните:

python tools/check_package.py
python -m unittest discover -s tests -v
python local_eval.py
python local_eval.py --runs 10
python tools/benchmark.py --runs 10
python make_submission.py
python tools/build_report.py

Воспроизводимый сценарий для жюри:

1. Убедитесь, что комплект найден, тесты завершились с OK, а оценщик не сообщает об ошибках агента или отброшенных кампаниях.
2. Откройте созданный submission.csv: проверьте целевой тариф, канал и фильтры каждой кампании.
3. Откройте reports/campaign_report.html в браузере. Найдите кампанию по тарифу, сравните её аудиторию и расходы, затем раскройте журнал решений и соответствующие пилоты.
4. В reports/plan_audit.json проверьте audit.valid, бюджет и контакты вместе с пилотами. Повторный контакт расходует лимит повторно; уникальный охват указан отдельно.
5. Для сдачи используйте agent.py, сгенерированный официальным скриптом submission.csv и зависимости согласно процедуре организаторов. CSV не заполняется вручную.

Результаты

Проверка на комплекте организаторов, Python 3.9.6:

Показатель, seed 0–9	Шаблон организаторов	She++
Средний чистый прирост ARPU, у.е.	−480 836	+1 477 583
Минимальный результат, у.е.	−1 019 431	+1 100 796
Положительных прогонов	0 / 10	10 / 10

Отдельный запуск с seed 42: PASS, 5 финальных кампаний и 20 пилотов, 3838 контактов, расходы 99 364 у.е., чистый прирост +1 533 505 у.е. Строка оценщика «Кампаний: 25» включает 20 пилотов и не означает 25 финальных кампаний. Все 20 тестов прошли, включая три независимых стресс-теста агента. Полный вывод сохранён в reports/tests.txt. Повторная генерация submission.csv дала побайтово одинаковый файл; SHA-256 сохранён в reports/verification.json. Полный запуск с оценкой занимает на этом компьютере менее секунды (время зависит от устройства).

reports/benchmark.json содержит результаты каждого seed для агента и исходного шаблона, время, число пилотов, среднее, медиану, минимум и число положительных прогонов. После изменения кода пересоздайте benchmark, CSV и HTML: сохранённые отчёты относятся к версии, на которой выполнен запуск. Локальная мок-среда не предсказывает балл скрытой проверки.

Критерий из ТЗ	Максимум	Проверяемое подтверждение
Соответствие задаче и работоспособность	25	Официальный локальный запуск и submission.csv
Техническая реализация	25	Адаптивные пилоты, независимый аудит, тесты
README и воспроизводимость	25	Команды установки, проверок и формирования отчётов
Ценность и применимость	15	План для аналитика и фактический чистый результат оценщика
Потенциал и оригинальность	10	Работа с неопределённостью, журнал обоснований и границы применимости

Чек-лист: docs/ACCEPTANCE.md. Сценарий защиты: docs/DEMO.md. Порядок личного вклада двух участников со своих устройств: docs/TEAM_WORKFLOW.md.

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

Оригинальный синтетический пакет включён в закрытый репозиторий команды. customer_profile.csv содержит целевую аудиторию; data/change_tariff.csv — историю переходов; data/dict_tariff.csv, tariff_dictionary.csv и feature_dictionary.csv описывают тарифы и поля. data/traffic.csv и data/arpu_monthly.csv входят в пакет; агент не обучает на них отдельную модель. Доступ к среде осуществляется через публичные поля env и метод env.run_pilot. Сетевые интеграции, ключи API и реальные персональные данные для запуска не нужны.

Ограничения

• Исторические переходы не являются причинной оценкой эффекта для новой аудитории.
• Интервалы строятся на рабочей модели шума: это не гарантия статистического покрытия, доходности или победы. Пилоты и финальные кампании могут дать отрицательный результат.
• Идентификаторы участников пилотов недоступны агенту. Точное пересечение пилотов с финальным планом не определяется; дедупликацию эффекта выполняет официальный оценщик.
• При отсутствии убедительного прибыльного плана возможна резервная кампания с малой экспозицией. Она явно помечается в журнале и тоже может оказаться убыточной.
• Аудит консервативно отклоняет пустые аудитории, сегменты больше 5000 и превышение остатков после пилотов. Он проверяет корректность, но не рассчитывает истинный финансовый эффект.
• Нет рабочей интеграции с биллингом, CRM и отправкой сообщений. Оценка на реальных данных не проводилась.

Развёрнутая версия

Публичного развёртывания нет. Решение запускается локально через Agent.act(env); созданный HTML-отчёт открывается в браузере без сервера.