Sergeek Campaign Agent

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

Для проверки жюри: agent.py, submission.csv и requirements.txt находятся в папке beeline_case_participants (1). Интерфейс — вспомогательный инструмент для аналитика; агент запускается и проверяется отдельно от сайта. Все данные синтетические, суммы — в условных единицах.

Стек и архитектура

• Python 3.12, pandas и NumPy — агент и локальная оценка.
• FastAPI и Uvicorn — API, запускающий агента в официальной тестовой среде.
• React, TypeScript, Vite и Recharts — русский интерфейс аналитика.
• Docker Compose и Nginx — воспроизводимый запуск и единый адрес UI/API.

Браузер → Nginx → FastAPI → Agent.act(env) → пилоты → итоговый портфель. Агент использует только публичные методы и данные env. Внутренние результаты оценщика читает сервис демонстрации после выполнения агента, а не сам агент. LLM не используется, ключи OpenAI/NVIDIA и сетевой доступ для принятия решений не требуются. Агент реализует автономный цикл наблюдения, оценки и действия статистическим алгоритмом.

Задача

Для аудитории из 23 441 абонента требуется выбрать до 10 кампаний. Каждая кампания определяет:

1. сегмент аудитории;
2. целевой тариф;
3. канал коммуникации.

При этом действуют ограничения: бюджет 100 000 у.е., общий охват до 15 000 контактов, до 20 пилотов и до 5 000 абонентов в одной кампании. Эффекты целевой аудитории заранее неизвестны, поэтому статическая стратегия по историческим данным недостаточна.

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

Исторические данные
        ↓
15 приоритетных тарифных гипотез
        ↓
12 широких push-пилотов × 100 клиентов
        ↓
Повторная оценка и 5 подтверждающих пилотов × 160 клиентов
        ↓
Weighted mean + uncertainty-adjusted lower bound
        ↓
Удаление конфликтующих аудиторий
        ↓
Совместная оптимизация skip / push / SMS / digital ads / call
        ↓
До 5 финальных кампаний в рамках бюджета и охвата

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

Финальный оптимизатор перебирает допустимые комбинации каналов, учитывая:

• остаток бюджета после пилотов;
• остаток лимита контактов;
• стоимость контакта;
• множитель конверсии канала;
• размер и средний predicted ARPU сегмента;
• запрет на конкурирующие кампании для одной аудитории.

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

Допущения и ограничения подхода

История задаёт 15 стартовых гипотез; эффект и окончательный выбор определяются живыми пилотами. Гипотезы для подтверждения выбираются адаптивно, однако число и размеры пилотов фиксированы: 12 × 100 и 5 × 160. Полностью адаптивная остановка разведки пока не реализована.

Используется оценка weighted_mean − 0.75 × 0.804 / sqrt(n). Это штраф за неопределённость, а не калиброванный 95%-й доверительный интервал. Для звонков относительный множитель ограничен сверху 2.0 против push из-за насыщения конверсии. Финальные аудитории не пересекаются по паре «текущий тариф + ARPU-сегмент»; пилотные и финальные контакты могут пересекаться, и оценщик учитывает это.

Автоматический генератор гипотез со сглаживанием реализован в experiments/, но не включён в сдаваемый агент: в стресс-тестах он ухудшил часть сценариев. Результаты и решение описаны в отчёте эксперимента. Следующие улучшения — адаптивная остановка, объединение ручных и автоматически сгенерированных гипотез, калибровка неопределённости на новой аудитории.

Проверенные результаты

Результаты ниже получены на предоставленной организаторами локальной mock-модели. Они подтверждают механику и устойчивость агента, но не являются прогнозом результата на скрытой модели судейства.

Проверка	Результат
Прибыльные прогоны	100 / 100
Медианный net gain	3 414 203
Минимальный net gain	2 112 530
Максимальный net gain	4 039 759
Контрольный seed 42	2 702 002
Финальных кампаний	5
Пилотов	17

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

Финальная повторная проверка 23.09.2026 на seed 0–9: 10/10 прибыльных прогонов, медиана 3 305 739, минимум 2 213 979, максимум 4 039 759 у.е. Контрольный seed 42: 82 818 у.е. расходов, 4 190 контактов, 2 890 уникальных абонентов, 17 пилотов и 5 финальных кампаний. Строка «22 кампании» в отчёте оценщика включает пилоты и не нарушает лимит 10 финальных кампаний. Итоговый эффект учитывает дедупликацию между кампаниями, поэтому его нельзя получить простым сложением строк UI.

Быстрый запуск

Требуется Docker Desktop с Docker Compose.

git clone https://github.com/BAITC-Hacks/hack-5c2118d3-sergeek.git
cd hack-5c2118d3-sergeek
docker compose up -d --build

Локальная проверка агента:

docker compose exec hackathon python local_eval.py
docker compose exec hackathon python local_eval.py --runs 10

Воспроизводимая генерация файла сдачи:

docker compose exec hackathon python make_submission.py

Контрактные smoke-тесты на десяти seed:

docker compose exec api python -m unittest discover -s tests -v

Робастность к сдвигу скрытой impact-модели:

docker compose exec api python experiments/stress_eval.py

После запуска API доступно по адресу http://localhost:8000, интерактивная OpenAPI-документация — http://localhost:8000/docs.

Аналитический dashboard доступен по адресу http://localhost:5173. Интерфейс полностью на русском. В Docker запросы /api/* проходят через Nginx к сервису API, поэтому браузеру достаточно одного адреса сайта. Кнопка «Запустить симуляцию» выполняет 10 новых локальных прогонов. Диапазон продолжается после последнего результата API: после 10–19 запускаются 20–29, после обновления страницы — 30–39. Текущий и следующий диапазоны показаны на странице. После перезапуска API история сбрасывается к стартовой сводке 0–99. Если API недоступен, интерфейс явно показывает «Демо-данные» и сохранённый результат; он не считается новым вычислением.

Проверка без Docker

Требуется Python 3.12; сайт и Node.js для проверки агента не нужны.

cd "beeline_case_participants (1)"
python -m pip install -r requirements.txt
python local_eval.py
python local_eval.py --runs 10
python make_submission.py

Основной сценарий аналитика

1. «Обзор» — проверить общий результат и расход лимитов.
2. «Портфель кампаний» — отфильтровать сегмент/канал, открыть детали предложения.
3. «Работа агента» — просмотреть 17 пилотов и нижние оценки эффекта.
4. «Симуляция» — запустить следующую десятку случайных выборок пилотов.
5. «Данные и лимиты» — проверить доступные ресурсы и экономику четырёх каналов.

Браузерная регрессия находится в tests/frontend_smoke.cjs: требует Playwright и установленного Edge, запускается node tests/frontend_smoke.cjs при работающем Docker. Проверяет также продолжение сценариев после обновления страницы, мобильную вёрстку и резервный режим без API.

API для dashboard

Метод	Endpoint	Назначение
GET	/api/health	Проверка доступности
GET	/api/dashboard	KPI, лимиты и каналы
GET	/api/campaigns?seed=42	Финальный портфель кампаний
GET	/api/pilots?seed=42	Результаты пилотных запусков
GET	/api/simulations/latest	Последняя сводка устойчивости
POST	/api/simulations/run	Запуск 1–100 mock-симуляций

Пример запуска симуляции:

curl -X POST http://localhost:8000/api/simulations/run \
  -H "Content-Type: application/json" \
  -d '{"runs": 10, "seed_start": 0}'

Структура проекта

.
├── api/                         # FastAPI для dashboard
├── frontend/                    # React + TypeScript dashboard
├── beeline_case_participants (1)/
│   ├── agent.py                 # сдаваемый адаптивный агент
│   ├── submission.csv           # воспроизводимый план кампаний
│   ├── local_eval.py            # официальный локальный evaluator
│   ├── make_submission.py       # генерация submission.csv
│   └── data/                    # данные организаторов
├── top_tariff_hypotheses.csv    # offline-анализ гипотез
└── compose.yaml                 # агент, API и frontend

Команда

• Рахман — агент, интеграция и инфраструктура;
• Медина — анализ данных и экономика каналов;
• Даурен — frontend и UX аналитического dashboard.

Сценарий трёхминутной демонстрации находится в docs/DEMO_SCRIPT.md, финальная проверка перед сдачей — в docs/FINAL_CHECKLIST.md.

Файлы сдачи

Обязательные файлы находятся в beeline_case_participants (1):

• agent.py;
• submission.csv.

Обязательные прогоны выполнены в отдельных контейнерах без локальных томов. Генерация submission.csv проверена; результат совпадает с файлом в репозитории. Сводка по критериям и ограничениям — FINAL_CHECKLIST.md. Оценку по 100-балльной шкале выставляет жюри; локальные проверки не предсказывают балл на скрытых эффектах.