Cerebrum — агент тарифных маркетинговых кампаний

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

Агент проверяет гипотезы небольшими пилотами, уточняет оценки эффекта и возвращает план из 1–10 кампаний. Результат можно изучить в локальной панели и выгрузить в submission.csv официального формата.

Для жюри: базовый режим работает без API-ключа и аккаунта внешнего сервиса. Нужны Python 3.11+, официальный пакет участников и интернет для первой установки зависимостей. Данные синтетические; локальная оценка не предсказывает балл на скрытой судейской среде.

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

• Группы клиентов по текущему тарифу и сегментам ARPU, потребления данных и звонков. ARPU — средний доход от абонента.
• Приоритеты тарифных гипотез по открытой истории смен тарифов и ценам.
• Пилоты через публичный env.run_pilot(): небольшая начальная выборка, повторные измерения для уточнения перспективных гипотез.
• Сравнение каналов push, sms, digital_ads, call с учётом стоимости контакта и результатов пилотов. Доступные каналы берутся из среды.
• Финальный план по нижней оценке чистого эффекта с учётом неопределённости и остатка ресурсов.
• Веб-панель: кампании, история пилотов, решения агента, метрики, результаты серии проверок и скачивание CSV.
• Проверка seed 42 и 0–9, независимый подсчёт расходов и контактов, сопоставление с официальным evaluator и повторяемость экспорта.
• Опциональное LLM-ранжирование гипотез с проверкой ответа и возвратом к локальному алгоритму при ошибке.

Ограничение официального сценария	Лимит
Финальные кампании	1–10
Аудитория одной кампании	Не более 5 000 абонентов
Контакты, включая пилоты	Не более 15 000
Бюджет всех контактов	100 000 у.е.
Пилоты	Не более 20, по 10–200 абонентов
Время работы агента	Не более 600 секунд

Источники контракта: руководство участников и описание ограничений.

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

1. Пользователь указывает ZIP или каталог официального пакета. Запуск проверяет SHA-256 файлов по манифесту и импортирует входные CSV в рабочую копию.
2. Официальная мок-среда предоставляет профили клиентов, тарифы, каналы и лимиты. Пользователь запускает агента из панели или командной строки.
3. Агент формирует группы и варианты переходов. История другой выборки помогает выбрать порядок экспериментов. Опциональная LLM может изменить этот порядок по агрегатам групп.
4. Агент проводит пилоты, обновляет оценки и уточняет гипотезы дополнительными измерениями. Пилотные контакты входят в общий расход ресурсов.
5. Агент возвращает кампании с фильтрами аудитории, тарифом и каналом. Официальный evaluator считает прирост ARPU за вычетом расходов.
6. Пользователь изучает план и ход экспериментов. Для сдачи официальный экспортёр повторно запускает агента с seed 42 и записывает submission.csv.

История не даёт готового эффекта для текущих клиентов. Финальные решения опираются на наблюдения пилотов; скрытая модель среды агенту недоступна.

Технологии

Компонент	Используется в проекте
Язык и среда	Python 3.11+, стандартная библиотека, venv, unittest
Обработка данных	numpy==2.3.5, pandas==3.0.1 — две прямые зависимости
Интерфейс	HTML, CSS, JavaScript; сервер на http.server
Оценка	Официальные environment.py, mock_environment.py, scoring_core.py, local_eval.py
Опциональная LLM	OpenAI Responses API через urllib.request; модель по умолчанию в коде — gpt-4.1-mini-2025-04-14
Артефакты	CSV для сдачи, JSON для локальных отчётов

Для запуска не нужны Node.js, Docker или отдельная база данных. Обучение собственной нейросети не выполняется; predicted_arpu предоставлен в пакете.

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

run.py / start.cmd
  ├─ .venv + requirements.txt
  ├─ scripts/import_participant_package.py → проверка пакета, импорт CSV
  ├─ preview_server.py + web/index.html → локальная панель
  └─ jury_eval.py → дочерние процессы оценки и отчёт проверки
        └─ local_eval.py → Agent.act(env)
                            ├─ candidates.py → группы и тарифные гипотезы
                            ├─ llm_advisor.py → опциональный порядок гипотез
                            └─ env.run_pilot() → наблюдения → финальный план

make_submission.py → Agent.act(env), seed 42 → submission.csv

Файл или каталог	Назначение
agent.py	Пилоты, обновление оценок, контроль ресурсов и финальный план
candidates.py	Подготовка таблиц и приоритеты гипотез по публичным данным
llm_advisor.py	Запрос к LLM, проверка перестановки гипотез, запасная логика
jury_eval.py	Проверка решений и согласованности с официальным подсчётом
preview_server.py, web/	HTTP API и интерфейс для демонстрации
scripts/	Импорт пакета, манифест SHA-256, preflight и аудит репозитория
analysis/profile_data.py	Профилирование CSV и отчёт о качестве данных
tests/	Проверки агента, контрактов, импорта, LLM и защитных проверок
tests/support/	Вспомогательная среда и синтетические фикстуры для тестов
docs/	Контракт, архитектура, отчёты и инструкции для сдачи

Официальные скрипты, PARTICIPANT_GUIDE.md и входные CSV сохраняются без изменений. Фикстуры команды не заменяют пакет организаторов. Подробнее — архитектура.

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

1. Подготовьте проект и пакет

Установите Python 3.11 или новее. Скачайте доступную вам копию репозитория или клонируйте её и откройте терминал в корне проекта, где находится run.py. Официальный ZIP или распакованный каталог участников храните вне репозитория.

python --version

Если Windows открывает Microsoft Store, используйте py -3 вместо python или свой установленный интерпретатор. На Linux/macOS используйте python3. Git не нужен для демонстрации из ZIP. Для полного набора тестов, preflight.py и security_audit.py нужна Git-копия проекта и Git в PATH.

2. Создайте окружение и проверьте пакет

python run.py --package "..\beeline_case_participants.zip" --check

Замените путь на местоположение своего официального ZIP или каталога. Конкретное имя файла и абсолютный путь участника не требуются. На Linux/macOS:

python3 run.py --package ../beeline_case_participants.zip --check

Команда создаёт .venv, устанавливает зависимости из requirements.txt, проверяет целостность пакета, импортирует семь CSV и проверяет агента с воспроизводимым экспортом. Активация окружения не нужна. Отличающиеся локальные данные не перезаписываются: импорт завершится ошибкой проверки.

При успехе появляются artifacts/validation.json, artifacts/latest.json и проверенный submission.csv. Повторить проверку:

python run.py --check

--check всегда отключает LLM, запускает seed 42 и 0–9, дважды вызывает официальный экспортёр и сравнивает CSV побайтно. Нарушение проверки или неположительный результат серии приводит к ненулевому коду возврата. Каждый процесс оценки ограничен 600 секундами.

3. Откройте локальную панель

python run.py

Откроется Cerebrum на localhost. После первой установки базовый режим работает без интернета, ключа и .env.

На Windows можно дважды нажать start.cmd: он выберет Python, подготовит окружение и при необходимости спросит путь к пакету. Повторно используется готовая .venv. Для проверки через эту обёртку: start.cmd --check.

• Если порт занят: python run.py --port 8766.
• Если браузер не нужен: python run.py --no-browser.
• Остановить сервер: Ctrl+C в терминале запуска.
• Использовать готовое окружение с нужными версиями: python run.py --use-current-env.

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

Сценарий в интерфейсе

1. Выполните установку и --check по инструкции выше, затем запустите панель.
2. Оставьте seed 42 и нажмите «Запустить агента».
3. Во вкладке «Кампании» проверьте тариф, канал, размер и фильтры аудитории.
4. Во вкладках «История пилотов» и «Решения агента» изучите наблюдения, расходы, этапы экспериментов и статус LLM или локального алгоритма.
5. Откройте «Соответствие ТЗ»: там показан отчёт последнего --check. При изменении кода агента панель отмечает сохранённый отчёт устаревшим.
6. Повторите запуск с seed 0 и сравните кампании и метрики.
7. Скачайте CSV. Он относится к последнему запуску панели; для сдачи создайте официальный submission.csv командой ниже с отключённой LLM.

Официальные команды и тесты

Из корня проекта в подготовленном окружении Windows PowerShell:

$env:CEREBRUM_LLM = "0"
.\.venv\Scripts\python.exe local_eval.py
.\.venv\Scripts\python.exe local_eval.py --runs 10
.\.venv\Scripts\python.exe make_submission.py
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe scripts/import_participant_package.py --check
.\.venv\Scripts\python.exe scripts/preflight.py
.\.venv\Scripts\python.exe scripts/security_audit.py
.\.venv\Scripts\python.exe -m pip check

На Linux/macOS путь к интерпретатору — .venv/bin/python, а отключение LLM: export CEREBRUM_LLM=0. При активированном окружении первая команда оценки выглядит как python local_eval.py.

Проверяйте текст отчёта, а не только код завершения: официальный evaluator может напечатать FAIL и вернуть код 0. Не должно быть ошибок агента или отброшенных кампаний. Поле «Кампаний» в отчёте evaluator включает пилоты; лимит 10 относится только к финальному плану.

Свежие результаты и PASS/FAIL по пунктам интеграционной проверки приведены в release checklist.

Файл сдачи

make_submission.py перезаписывает submission.csv в корне проекта. Это 1–10 строк кампаний и заголовок из семи столбцов:

campaign_name,filter_arpu_segment,filter_data_segment,filter_call_segment,filter_current_tariff,target_tariff,channel

Пустой фильтр означает отсутствие соответствующего ограничения. Файл содержит фильтры групп, а не список идентификаторов абонентов. Проверьте CSV и включите его в сдачу вместе с agent.py, candidates.py, llm_advisor.py и requirements.txt. Проверенный submission.csv включается в Git; входные CSV и локальные отчёты исключены через .gitignore.

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

Используется официальный синтетический пакет Beeline. Источник и SHA-256 зафиксированы в манифесте.

Данные	Роль
customer_profile.csv	Целевая аудитория: текущий тариф, сегменты, predicted_arpu
data/change_tariff.csv	История другой выборки для приоритетов гипотез; также вход официальной мок-среды
data/dict_tariff.csv	Тарифы и параметры для официальной мок-среды
tariff_dictionary.csv, feature_dictionary.csv	Справочники тарифов и признаков пакета
data/traffic.csv, data/arpu_monthly.csv	Дополнительная история; текущим алгоритмом агента напрямую не используется

Все семь CSV проверяются при импорте. Подробнее — профиль пакета. Упоминание IBM Telco в архивном отчёте относится к отдельной проверке профилировщика: этот набор не является входом текущего агента и не входит в сдачу.

Опциональная LLM

Передайте OPENAI_API_KEY через окружение процесса и запустите:

python run.py --llm

Этот режим требует доступа к OpenAI API. Модель по умолчанию задана в llm_advisor.py; OPENAI_MODEL позволяет указать другую совместимую модель. При прямом запуске официальных скриптов LLM включается через CEREBRUM_LLM=1. .env автоматически не загружается. Не записывайте ключ в код, команды с буквальным секретом, README, CSV или логи.

В API отправляются агрегаты не более 20 групп: фильтры, размеры, средний ARPU и варианты тарифов. Строки клиентов и их ID не передаются. Ответ может только переставить допустимые гипотезы; финальные кампании выбирает агент после пилотов. На запуск выполняется максимум один запрос с ожиданием до 8 секунд. При отсутствии ключа, таймауте или неверном ответе сохраняется локальный порядок. Воспроизводимый экспорт выполняйте без LLM.

Ограничения / Known limitations

• Проверки используют мок-эффекты организаторов. Они подтверждают работу на выданном пакете, но не оптимальность плана или результат на скрытых данных.
• Оценка неопределённости эвристическая, не калиброванный доверительный интервал. Если все наблюдения плохие, агент всё равно пытается вернуть одну допустимую кампанию с минимальной экспозицией, поскольку это требует контракт.
• Преимущество LLM по прибыли не доказано; её ответы могут меняться. Базовый алгоритм и сдача не требуют LLM.
• Без официального пакета основной сценарий не запускается. Импорт принимает только файлы, совпадающие с манифестом; новый пакет организаторов потребует отдельной проверки совместимости.
• Пропуски и дубли входных данных отражены в отчёте о пакете. Исходные файлы не исправляются и не подменяются для улучшения оценки.
• Подтверждённая платформа проверки — Windows с Python 3.12.14. Команды для Linux/macOS приведены, но отдельный прогон на этих ОС не выполнен.
• Закреплены прямые зависимости; полного lock-файла транзитивных зависимостей нет.
• Жёсткий таймаут обеспечивают jury_eval.py и запуск из панели/--check. Сам агент проверяет время между пилотами и не может прервать зависший вызов среды.
• Панель предназначена для локальной демонстрации. Интеграции с реальной CRM, отправки сообщений абонентам и многопользовательского доступа нет.

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

В репозитории не указана подтверждённая публичная deployed-версия. Демонстрация запускается локально: http://127.0.0.1:8765/. Адрес доступен на компьютере, где запущен проект; это не публичный сайт.

Документация и сдача

• Финальная интеграционная проверка.
• Чек-лист сдачи и уточнение дедлайна.
• Подробная архитектура и контракт.
• Безопасность, источники и права использования.
• Отчёт о доработке запуска и опциональных возможностей.

Отдельной лицензии кода команды нет. Права на распространение официального пакета уточняются у организаторов.