Агент для тарифных маркетинговых кампаний

Проект выбирает тарифные предложения и каналы связи для абонентов при ограниченном бюджете и лимите контактов. Агент получает профиль аудитории и историю смен тарифов, проводит небольшие пилотные кампании, обновляет оценку эффекта и возвращает до 10 финальных кампаний.

Это алгоритмический агент с последовательным выбором действий по результатам пилотов. В проекте нет LLM и внешнего AI API.

Состав проекта

Файл	Назначение
agent.py	Стратегия: исторический приоритет, пилоты, оценка эффекта и выбор кампаний. Это файл агента для сдачи.
environment.py	Интерфейс среды и проведение пилотов с ограничениями и шумом наблюдений.
mock_environment.py	Локальная модель эффектов на основе выданной истории.
scoring_core.py	Применение фильтров, лимитов, дедупликации и расчёт чистого результата.
local_eval.py	Один прогон или серия прогонов на локальной модели.
make_submission.py	Формирование воспроизводимого submission.csv с seed 42.
dashboard.py, web/	Локальный веб-дашборд для загрузки данных, запуска агента и просмотра результатов.
customer_profile.csv, data/*.csv	Профиль аудитории, история переходов и справочники.

Как работает стратегия

1. Агент группирует аудиторию по текущему тарифу и сегменту ARPU. Для каждой группы оценивает варианты целевого тарифа по истории data/change_tariff.csv. Если истории для пары нет, использует консервативную оценку по разнице цен.
2. Лучшие группы исследуются через env.run_pilot(): сначала 12 пилотов по 60 контактов в канале push, затем 6 уточняющих пилотов по 200 контактов. Оставшиеся попытки направляются на следующие группы. Пилоты тратят лимит контактов и входят в итоговый результат.
3. Наблюдения пилотов объединяются с исторической оценкой. При выборе применяется поправка на неопределённость mean - 0.6 × std.
4. Для каждой группы агент сравнивает ожидаемый прирост ARPU за вычетом стоимости контакта по доступным каналам. Кампании упорядочиваются по ожидаемому чистому эффекту с учётом бюджета и лимита охвата.

Финальные кампании задаются фильтрами filter_current_tariff и filter_arpu_segment, целевым тарифом target_tariff и каналом channel. Пилотные кампании учитываются отдельно и не входят в лимит 10 финальных кампаний.

Запуск и проверка

Запускайте команды из корня проекта. Нужны Python и зависимости из requirements.txt (локально проверено с Python 3.14.4, NumPy 2.5.3 и pandas 3.0.6).

python -m pip install -r requirements.txt
python local_eval.py
python local_eval.py --runs 30
python make_submission.py
python dashboard.py

После запуска dashboard.py откройте http://127.0.0.1:8000. Страница автоматически выполняет один прогон на данных проекта. Через блок «Входные данные» можно загрузить собственные CSV с теми же колонками, задать seed и число прогонов от 1 до 30. Исходные файлы проекта при этом не изменяются. В интерфейсе доступны метрики, график по прогонам, пилоты и кампании, а также скачивание финальной стратегии в CSV. Для пользовательских данных локальная мок-модель строится из загруженной истории переходов. Сервер работает локально и не обращается к внешним сервисам.

local_eval.py печатает чистый прирост ARPU, затраты, число пилотов, кампаний и контактов. --runs 30 использует seed от 0 до 29 и показывает устойчивость результата. make_submission.py записывает submission.csv с фиксированным seed 42. Для сдачи используйте agent.py и созданный submission.csv; если площадка требует явного списка зависимостей, добавьте requirements.txt.

Для проверки формата и воспроизводимости файла:

python -c "import pandas as pd; from scoring_core import validate_strategy; from make_submission import build_submission; from agent import Agent; saved=pd.read_csv('submission.csv'); validate_strategy(saved, pd.read_csv('data/dict_tariff.csv')); pd.testing.assert_frame_equal(saved.fillna(''), build_submission(Agent()).fillna(''), check_dtype=False); print('OK')"

Минимальные колонки для загрузки: профиль — ID_NUMBER, current_tariff, arpu_segment, data_segment, call_segment, predicted_arpu; история — ID_NUMBER, AVG_ARPU_PREV_3M, AVG_ARPU_NEXT_3M, tariff_plan_code_from, tariff_plan_code_to; справочник — tariff_plan_code, price_tariff. В профиле ID_NUMBER должен быть уникальным. Отсутствующие необязательные файлы берутся из проекта.

Проверка интеграции дашборда со скорингом:

python -m unittest discover -s tests -v

Лимиты и смысл результата

Среда разрешает до 20 пилотов размером 10–200 контактов; финальная стратегия содержит до 10 кампаний. Общий лимит составляет 15 000 контактов и 100 000 условных единиц затрат. Одна кампания охватывает не более 5 000 абонентов. Повторные контакты расходуют охват и бюджет, а эффект одного абонента учитывается один раз, по лучшей кампании. Основная метрика: суммарный прирост ARPU минус затраты на коммуникацию.

На локальной мок-модели серия из 30 прогонов дала положительный результат в 30 случаях: медиана чистого прироста 1 822 343, минимум 1 037 367, максимум 1 937 148. Эти числа проверяют работу кода и механики скоринга. На судействе используется другая модель эффектов, поэтому локальный балл не является прогнозом итогового результата.

Практическое применение и развитие

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