Digital Yakuza — агент тарифных кампаний Beeline

Открыть демо →

API / Swagger · Результаты · Запуск · Проверка ТЗ

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

Проект команды Digital Yakuza для кейса Beeline на HackAlem AI. На выходе — план в CSV, результаты пилотов и отчёт для аналитика.

Файлы сдачи кейса: beeline_agent/agent.py (класс Agent, метод act(env)) и beeline_agent/submission.csv (из make_submission.py, seed 42).

Бизнес-задача и ценность решения

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

Цель кейса — чистый прирост ARPU после затрат на коммуникацию:

net_arpu_gain = прирост ARPU по уникальным абонентам − стоимость контактов

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

Все данные синтетические. Результаты — условные единицы симулятора, не измеренная выручка Beeline. Экономия времени аналитика отдельно не измерялась.

Пользовательский сценарий

1. Запустить расчёт. Аналитик открывает дашборд и запускает агента на предоставленной аудитории.
2. Проверить разведку. Агент проводит пилоты; аналитик видит их результаты и затраты.
3. Изучить план. Для финальных кампаний доступны аудитории, целевые тарифы, каналы и показатели результата.
4. Проверить основания. Отчёт связывает кампании с пилотами и содержит объяснение и предупреждения.
5. Скачать CSV. Аналитик получает воспроизводимый план для дальнейшего решения о запуске.

AI рекомендует — решает человек. Интеграции с реальной рассылкой абонентам нет. ИИ-объяснение показывается в дашборде в блоке «Почему такой план» с пометкой источника: «ИИ (luna)» или шаблон.

Что реализовано и как работает агент

История переходов + профиль аудитории
                  ↓
        Гипотезы и начальные оценки
                  ↓
      Выбор пилота → наблюдение результата
                  ↑             ↓
                  └── обновление оценки и погрешности
                                ↓
                  План с учётом риска и лимитов
                                ↓
                   CSV + факты + журнал решений
                                ↓
                     ИИ-объяснение → аналитик

• Исторические оценки. Начальный эффект и ошибка по связкам «текущий тариф × ARPU-сегмент → цель», с поправкой на неопределённость переноса.
• Последовательная разведка. Пилоты выбираются по предыдущим результатам. Байесовское обновление учитывает их размер и шум. Размер пока зависит от численности аудитории — 100 или 200; выбор размера по ожидаемой пользе не реализован.
• Планирование. Кампании ранжируются по консервативной оценке с учётом пересечений и ресурсов. Канал выбирается экономически: кампания начинает с бесплатного push и переходит на SMS, интернет-рекламу или звонок, только если доплата окупается по нижней границе оценки и помещается в остаток бюджета. Если ни одна кампания не прошла порог, используется небольшая запасная push-кампания с причиной в журнале. Прибыль не гарантируется.
• Проверяемый результат. Agent.act(env) возвращает 1–10 кампаний; пилоты, обновления оценок и решения записываются в trace.
• Приложение. Фоновый запуск, сохранение в PostgreSQL, показ кампаний и пилотов, скачивание CSV.

Пример из seed 42: кампания C1 для MID → tariff_8 связана с пилотами P5 и P6. Наблюдаемые эффекты SMS-пилотов — около 11,07% и 13,61%; финальная кампания содержит 4 108 контактов. Связь и значения можно проверить в report.json, а не принимать объяснение на веру.

Результаты и качество

Официальная mock-среда, seed 42:

Проверка переноса на другие эффекты: 135 контрольных миров, 9 сценариев × 15 seed (10 000–10 014). Все стратегии запускались на одинаковых мирах и seed. Контрольный набор использовался только для итоговых проверок, без настройки на нём: сначала для версии a631a16, затем для сдаваемой версии, чей выбор каналов уже был принят по 180 тренировочным мирам.

Как интерпретировать: агент улучшил результат относительно шаблона и выполнил проверяемые условия ТЗ во всех 135 мирах. У стратегии «только история» медиана выше, но нет обязательных пилотов и хуже минимальный результат. Сдаваемая версия превосходит её в 30% миров; в сценарии плохого переноса истории random медиана агента — 1,58 млн против 0,44 млн. Это показывает пользу проверки истории и одновременно цену осторожности.

Сдаваемая версия отличается от a631a16 только экономическим выбором каналов (dfcccc4). Он принят по 180 тренировочным мирам (медиана парной разницы +68 тыс. у.е., лучше в 71% миров) и затем один раз проверен на тех же 135 контрольных мирах: медиана парной разницы +127 тыс. у.е., лучше в 81% миров, хуже в 12%, медиана выше во всех 9 сценариях. Повторный пилот «только при неясном решении» (−16 тыс., лучше в 39%) и разведка тарифов без истории (−595 тыс., лучше в 18%) реализованы за переключателями и отклонены. Скрытая среда судейства неизвестна; отдельные контрольные миры остаются убыточными.

Методика и отклонённые варианты, включая совместную модель ячеек: EXPERIMENTS.md.

Роль ИИ, надёжность и стоимость

Модель gpt-5.6-luna через OpenAI API объясняет уже готовый план: связывает кампании с доказательствами, формулирует предупреждения и следующие действия аналитика. Статистический код выбирает пилоты и кампании; модель не меняет их и не редактирует CSV.

Тестовый вызов команды: 2 909 входных / 1 188 выходных токенов, 12,2 с, около $0,00201 по использованным ценам. Токены, задержка и оплаченные попытки записываются в отчёт. Бюджет проверяется до запроса, но предварительная оценка токенов приблизительная: строгий финансовый потолок не гарантируется. USD API и у.е. кампаний — разные бюджеты.

Проверка ссылок и чисел не доказывает правильность каждой смысловой формулировки. Содержательную полезность объяснений для аналитика ещё предстоит измерить. Подробности workflow.

Архитектура и технологии

React / TypeScript → FastAPI → отдельный worker → Agent.act(env)
                        ↑              ↓
                        └────── PostgreSQL: план, пилоты, журнал
                                       ↓
                           explain_result: факты → LLM / шаблон
                                       ↓
                           объяснение того же сохранённого run_id

explain_result объясняет сохранённый запуск без повторных пилотов. Агент использует публичный интерфейс среды; истинные эффекты доступны оценщику. Mock-метрики отчёта рассчитываются после запуска.

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

Данные организаторов включены в beeline_agent; для базового запуска внешняя выгрузка не нужна.

Очистка оставляет 12 699 из 14 823 строк: удалены дубли и слишком малая база ARPU, рост ограничен по правилу среды. Подготовлены 451 связка с историей и 809 без неё в формате (q, q_se, n_obs): эффект, его ошибка и число наблюдений. Разведка связок без истории испытана и отклонена: при 20 пилотах она ухудшила результат (см. «Результаты и качество»). Методика.

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

Агент и отчёт без внешних сервисов

Нужен Python 3.12. Начните из корня репозитория:

python -m venv .venv

Активируйте созданное окружение: PowerShell — .\.venv\Scripts\Activate.ps1, Linux/macOS — source .venv/bin/activate.

cd beeline_agent
python -m pip install -r requirements-workflow.txt
python workflow.py --no-llm

Для сдаваемой версии ожидается 5 кампаний, net 5 165 453, объяснение template. В outputs/ появятся:

OPENAI_API_KEY=YOUR_API_KEY
AGENT_LLM=1
OPENAI_MODEL_FAST=gpt-5.6-luna
AGENT_LLM_RUN_BUDGET_USD=0.05

python workflow.py

cd backend
if (-not (Test-Path .env)) { Copy-Item .env.example .env }
docker compose up --build -d
docker compose exec backend alembic upgrade head

cd frontend
if (-not (Test-Path .env)) { Copy-Item .env.example .env }
npm install
npm run dev

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

Для демонстрации: откройте сайт по ссылке в начале, запустите агента с seed 42, изучите кампании и пилоты, скачайте CSV. Ожидается «seed 42 · агент 59547e1d», 5 кампаний, чистый эффект 5 165 452,81 у.е. и блок «Почему такой план» с пометкой «ИИ (luna)»; CSV совпадает с beeline_agent/submission.csv. Версию агента на хостинге можно сверить: GET /api/case/summary возвращает agent_sha256, у сдаваемой версии — 59547e1d…. Воспроизводимая локальная проверка выполняется из beeline_agent:

python local_eval.py
python make_submission.py
python -m eval.checks

Ожидаются PASS, 5 финальных кампаний и проверки без FAIL для зафиксированной версии. Официальный оценщик выводит 25 кампаний суммарно: 20 пилотов + 5 финальных. T4 в тренажёре — диагностика генератора, не прибыль агента.

python -m pip install pytest
python -m pytest -q tests
python local_eval.py --runs 10

Проходят 47 тестов (агент, workflow, выбор каналов) и 11 из 11 проверок тренажёра. local_eval.py --runs 10: 10 из 10 положительных, медиана +4,82 млн, минимум +3,01 млн у.е. Тесты API используют подмену и не требуют платных запросов.

Соответствие обязательным условиям ТЗ

Таймаут воркера — 600 секунд. Полное ТЗ. Результаты проверок относятся к испытанным сценариям.

Соответствие критериям HackAlem

python workflow.py --no-llm
python -c "from pathlib import Path; assert Path('submission.csv').read_bytes() == Path('outputs/submission.csv').read_bytes(); print('CSV совпадает')"

python -c "from pathlib import Path; from eval.run import run, summarize; s='mock,random,noise,flip,shift,stingy,unknown_rich,high_rich,resample'.split(','); df=run(15,s,'control',['template','history_only','agent','agent_pre2']); Path('eval/results').mkdir(exist_ok=True); df.to_csv('eval/results/readme_control135.csv',index=False); print(summarize(df).to_string()); print(df.groupby('strategy')['net'].agg(['count','median','min']))"

Ограничения и следующий этап

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

Команда и использованные материалы

Использованы синтетический пакет, среда (environment.py, mock_environment.py, scoring_core.py), локальный оценщик и шаблон агента организаторов; остальной код — командный, написан на хакатоне. Claude (Anthropic) и OpenAI Codex применялись при разработке и ревью вместе с локальными инструкциями и навыками; модель gpt-5.6-luna через OpenAI API используется только во время выполнения workflow для объяснения. Библиотеки перечислены в файлах зависимостей.

Зависимости: агент, workflow, бэкенд, фронтенд.