BeeGrowth Agent

1. Название проекта

BeeGrowth Agent · HackAlem AI · Beeline Tariff Marketing Campaigns

2. Краткое описание

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

Целевая метрика — дополнительный ARPU по уникальным абонентам минус стоимость всех коммуникаций, включая пилоты. Исходная сумма predicted_arpu не является доходом агента.

Все данные синтетические. Приведённые числа — локальные результаты на мок-модели; они не описывают реальный бизнес Beeline и не гарантируют прибыль или балл скрытого судейства.

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

• Построение гипотез из профиля аудитории и истории смен тарифов.
• Последовательные пилоты через публичный env.run_pilot и обновление оценок по их наблюдениям.
• Выбор финальных кампаний с проверкой фильтров, пересечений аудиторий, бюджета и контактов.
• Генерация официального submission.csv штатным скриптом организаторов.
• Русскоязычное демо: аудитория, seed, пилоты, финальный план, прогнозы агента, локальная оценка и журнал объяснений; скачивание JSON и официального CSV.
• Внешняя раздельная диагностика: пилоты, те же пилоты вместе с финалом и разница двух результатов. Оценивание выполняется после завершения Agent.act(); результат оценщика не возвращается агенту.

Основная версия

Для сдачи используется корневой agent.py, восстановленный без изменения алгоритма. Контрольный SHA-256:

76deffc4d074b85f0453977e422dd64b7ab6257febb1f40f0f0f714734def1cc

submission.csv создан официальным make_submission.py этой версией. Эксперимент stage1 сохранён отдельно и не принят в качестве основной стратегии. Сведения для формы сдачи находятся в SUBMISSION.md, состав комплекта и состояние Git — в PACKAGING.md.

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

1. Среда передаёт профиль аудитории, тарифы, каналы и остатки ресурсов. В предоставленном профиле 23 441 абонент; размеры вычисляются из данных.
2. История смен тарифов другой выборки даёт начальные гипотезы о сочетаниях аудитории, тарифа и канала. Она не считается истинными эффектами текущей аудитории.
3. Агент проводит небольшие пилоты, получает шумные наблюдения и обновляет оценки для проверенных гипотез.
4. По обновлённым оценкам он выбирает непересекающиеся финальные аудитории под оставшиеся ресурсы и возвращает кампании с официальными фильтрами.
5. make_submission.py формирует submission.csv. В демо пользователь просматривает план и отдельно сравнивает прогноз агента с результатом локального оценщика.

5. Технологии

Технология	Фактическое применение
Python	Агент, среда, оценка, генератор CSV и проверки
NumPy	Численные оценки, работа с неопределённостью
pandas	Чтение CSV, обработка истории, группировка и фильтрация аудитории
Streamlit	Локальное демо; streamlit.testing.v1.AppTest для его проверок
Статистический алгоритм	Исторические начальные оценки, последовательное обновление по пилотам, поправка на риск и жадный выбор кампаний
unittest	Проверки контракта, поведения, диагностики и демо

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

6. Архитектура и алгоритм

Слой	Компоненты	Взаимодействие
Алгоритм	agent.py	Agent().act(env) -> list[dict]; использует публичные данные и ответы пилотов
Среда	environment.py, mock_environment.py	Предоставленные организаторами интерфейс, ресурсы, пилоты и фабрика локальной среды
Проверка	scoring_core.py, local_eval.py	Официальная локальная оценка после завершения агента
Выходной артефакт	make_submission.py	Запускает агента с seed=42 и создаёт официальный CSV
Демонстрация	demo_app.py	Запускает корневого агента и показывает отдельные прогнозы и оценку
Диагностика	split_eval.py	Внешнее сравнение пилотов и добавочного вклада финала

Агент не получает истинные эффекты оценщика или внутренние ID пилотов. Основная версия и демо не зависят от snapshots и experiments; эти каталоги нужны для исторических сравнений и архивных тестов.

Гипотезы. Базовая ячейка — current_tariff × arpu_segment. Слишком большие аудитории разбиваются разрешёнными фильтрами по данным и звонкам. Историческое изменение ARPU сглаживается 30 псевдонаблюдениями слабой гипотезы по цене. На ячейку выбираются три целевых тарифа и рассматриваются доступные каналы. Частота состоявшихся переходов не используется как вероятность отклика.

Обновление. Начальная вероятность отклика 0.15 — слабое предположение, а не измеренная конверсия. Для каждой гипотезы ведётся отдельная нормальная оценка с начальным std=0.20. Пилот обновляет её с дисперсией наблюдения 0.804² / n, где n — фактически возвращённое число абонентов. Коэффициент канала применяется к начальной гипотезе; наблюдаемый эффект уже включает канал. Критерий mean - std — поправка на риск, не гарантия прибыли.

Поиск. Сначала исследуются до шести разных ячеек, затем — преимущественно неоднозначные повторы и краткая проверка других каналов лидеров. Начальный пилот рассчитан на 100 человек, повторный размер зависит от неопределённости и ограничивается аудиторией и ресурсами. Внутренний потолок — 16 пилотов, до трёх на гипотезу. Перед вызовом сохраняется резерв на целую финальную кампанию.

Финал. Прогноз полного охвата равен mean × сумма predicted_arpu − стоимость контактов. Жадный выбор учитывает поправку на риск, бюджет, контакты и пересечение финальных аудиторий. При отсутствии положительной оценки используется допустимый резервный план с возможным убытком. Прогноз не скорректирован на пересечения с пилотами.

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

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

Для закреплённых зависимостей нужен Python ≥ 3.12. Проверенная конфигурация: Python 3.14.6, NumPy 2.5.3, pandas 3.0.6, Streamlit 1.64.0. Откройте PowerShell в корне репозитория:

py -3.14 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip check

Если установленный Python доступен как python, первая команда может быть python -m venv .venv. Активация окружения не требуется. Существующее рабочее .venv пересоздавать не нужно. Установка пакетов требует доступа к PyPI; после установки агент, оценщик и демо работают локально. Виртуальное окружение не переносится между машинами и не включается в Git.

Для запуска нужны исходники из таблицы архитектуры, requirements.txt, customer_profile.csv, data/change_tariff.csv и data/dict_tariff.csv. Все они входят в комплект. Остальные прямые импорты относятся к стандартной библиотеке Python или модулям репозитория.

Решение проблем

Если python выдаёт The file cannot be accessed by the system, причиной может быть недоступный Windows alias. Используйте установленный интерпретатор или launcher py. На машине разработки рабочий Python находился в D:\anaconda\python.exe; это особенность машины, не зависимость проекта.

При недоступности PyPI нужен сетевой доступ для установки пакетов в локальное .venv. Все команды выполняйте из корня репозитория: официальные скрипты используют относительные пути к данным. Установка на другой ОС отдельно не проверялась.

Старый verify_artifacts.py читает исходный манифест с абсолютными Windows-путями. Он не входит в обязательный сценарий запуска; переносимая загрузка приложения не требует этого скрипта, архивов или личных путей.

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

Последовательно выполните официальную одиночную проверку, десять прогонов и генерацию CSV:

.\.venv\Scripts\python.exe local_eval.py
.\.venv\Scripts\python.exe local_eval.py --runs 10
.\.venv\Scripts\python.exe make_submission.py
Get-Content .\submission.csv

Одиночный прогон использует seed=42, десять прогонов — seed 0–9. Генератор создаёт submission.csv в корне; вручную его редактировать не нужно. Для запуска демонстрации выполните команду из пункта 11 и пройдите двухминутный сценарий DEMO.md.

Общие проверки основной версии и демо:

.\.venv\Scripts\python.exe -m unittest tests.test_agent tests.test_demo -v

Полный набор включает архивные сценарии и требует сохранённых снимка и эксперимента. Области тестов описаны в tests/README.md.

Подтверждённые проверки основной версии

Следующие результаты повторно получены в отдельном рабочем дереве объединённой версии для публикации, для контрольного SHA-256 из пункта 3. Это локальные результаты на синтетических данных. Протокол публикации содержит состав комплекта и область проверок; протокол команд — команды, время и логи. Исходный агент и алгоритм не изменялись.

Область	Подтверждённый результат
Общие тесты основной версии	9/9 PASS
Тесты демо	4/4 PASS
Фиксация известного ограничения основной версии	1/1 PASS; подтверждает остановку после шести отрицательных пилотов
Тесты архивной стратегии stage1	6/6 PASS; не относятся к основной стратегии
Раздельная диагностика	5/5 PASS
Лимиты на seed=42 и 0–9	Соблюдены; падений, отброшенных и обрезанных кампаний нет
Две официальные генерации CSV	Файлы совпали побайтово
pip check	Зависимости согласованы

Итого прошли 25 проверок разных областей. Это не 25 тестов алгоритма основной версии.

Показатель основной версии, seed=42	Локальное значение
Официальный статус	PASS
Net проведённых пилотов	+18 123.31
Net пилотов вместе с финалом	+13 741.73
Добавочный вклад финала: разница двух оценок	−4 381.58
Пилоты / финальные кампании	16 / 1
Аудитория финальной кампании	2950
Все контакты / лимит	4722 / 15 000
Расходы / лимит	8918 / 100 000

Источники: официальный одиночный лог, раздельная оценка и лимиты. На seed 0–9: медиана net 312 816, минимум 31 242, максимум 505 986, положительных прогонов 10/10 — официальный лог, округление до целых.

Прогноз агента и наблюдения пилотов — отдельные величины. Сохранённый отчёт стабилизации seed=42 той же основной версии содержит прогноз полного финала +1 328 482.80, прогноз с поправкой на риск +302 218.74 и локальную оценку финала самостоятельно, без пилотов, −7 081.57. Последнюю нельзя прибавлять к результату пилотов: аудитории пересекаются, оценщик учитывает лучший эффект по уникальному абоненту. Положительный общий net не доказывает прибыльность финальных кампаний.

SHA-256 официального submission.csv: e0531bbc31c53e86a3656dd0a1e7eb66c43cbddedd9312541478305a9446fa8e. Две генерации в рабочем дереве публикуемой версии совпали побайтово между собой и с ранее проверенным CSV. Подтверждение повторяемости находится в протоколе публикации.

Все четыре теста демо повторно прошли в рабочем дереве публикуемой версии. Проверка происхождения данных и модулей подтвердила загрузку из этого дерева, 13 410 допустимых строк истории и отсутствие fallback из-за недоступности истории.

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

Ранее отдельная копия минимального комплекта без snapshots и experiments прошла запуск демо и побайтово воспроизвела официальный CSV. Протокол комплектности.

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

Все исходные CSV предоставлены для синтетической задачи. Они сохранены без редактирования.

Файл	Назначение и использование
customer_profile.csv	Аудитория кампаний: текущий тариф, сегменты, поведение, predicted_arpu; используется средой, агентом и демо
data/change_tariff.csv	История смен тарифов и ARPU до/после на другой выборке; начальные оценки агента и построение локальной мок-модели
data/dict_tariff.csv	Параметры тарифов, цены и пакеты; используется средой и агентом
data/arpu_monthly.csv	Предоставленная месячная выручка по абонентам; сохранена, основной запуск её не читает
data/traffic.csv	Предоставленное потребление и характеристики устройств по месяцам; сохранены, основной запуск их не читает
tariff_dictionary.csv, feature_dictionary.csv	Описания тарифов и колонок для понимания исходных материалов и аудита
submission.csv	Выходной план кампаний в формате организаторов

История агента читается относительно agent.py: data/change_tariff.csv. Дубликаты удаляются только в памяти; строки с исходным ARPU ≤ 0 или недопустимыми значениями исключаются, относительное изменение ограничивается диапазоном [−1, 2]. Из 14 823 исходных строк остаются 13 410 допустимых. Аудит данных, проверка пути, хеша и загрузки истории.

Для работы не нужны внешние сервисы или API-ключи. PyPI нужен при установке зависимостей; GitHub используется для хранения и передачи исходников, а не для расчёта кампаний.

10. Ограничения

• Основная стратегия почти перестаёт исследовать новые гипотезы после шестой проверки. Она не проходит экспериментальное требование продолжать поиск после шести отрицательных пилотов; отдельный тест фиксирует это поведение.
• Исторический top-3 может пропустить хороший тариф. История относится к другой выборке; слабая вероятность отклика не измерена по маркетинговым предложениям.
• Каналы оцениваются независимо, финальный выбор жадный. Глобальный оптимум не гарантирован.
• Пилоты дают шумные наблюдения. Прогноз не учитывает пересечения с ними и может существенно расходиться с локальным эффектом; резервный и выбранный финальный план могут быть убыточными.
• Мок-оценка проверяет механику на синтетических эффектах. Изменение seed меняет шум и выборку внутри одной мок-модели, не создавая новую модель поведения. Результат скрытого судейства неизвестен.
• В guide указано 14 824 смены тарифа, фактически в CSV — 14 823. В данных есть пропуски и недопустимые исходные ARPU; обработка отражена в аудите.

Stage1: сохранён, но не принят

Эксперимент находится в experiments/stage1_expanded_search/. Его SHA-256: 43b88055a4f71af19b39ff49694b124b11873cd812ff9a0b9388e57867279658. Он продолжает поиск после шести отрицательных пилотов в контролируемом тесте, однако финансовые показатели проведённых сравнений ухудшились:

Исторический набор seed	Медиана общего net основной версии	Медиана stage1	Отрицательный вклад финала: основная → stage1
0–99	226 322	148 094	9/100 → 17/100
100–149	227 829	128 066	6/50 → 11/50

Это исторические результаты двух указанных хешей, а не новые эксперименты финальной подготовки. Отчёт сравнения, привязка результатов к версиям. Снимок snapshots/before_stage1, эксперимент и все подтверждающие отчёты сохранены.

11. Развёрнутая версия и демонстрация

Публичного размещения BeeGrowth Agent нет. Подтверждён только локальный запуск; адрес 127.0.0.1 доступен на компьютере, где запущен сервер, и не является публичной ссылкой.

Запустите из корня репозитория:

.\.venv\Scripts\python.exe -m streamlit run demo_app.py --server.address 127.0.0.1 --server.port 8501 --server.headless true --browser.gatherUsageStats false

Откройте http://127.0.0.1:8501 на этом компьютере и нажмите «Запустить агента». Команда отключает сбор статистики использования и автоматическое открытие браузера. Для остановки нажмите Ctrl+C в терминале.

Новый запуск использует корневой agent.py. Сохранённые результаты связаны с его SHA-256 и сбрасываются при смене версии. Переключение элементов страницы не запускает новые пилоты. Отчёт можно скачать в JSON; отдельная кнопка создаёт официальный CSV через make_submission.py и предлагает его скачивание. Добавочный вклад финала показывается из сохранённой раздельной диагностики — отдельной карточки в интерфейсе нет. Порядок двухминутного показа: DEMO.md.

Версия для сдачи — BeeGrowth Agent в ветке main репозитория команды. Подготовка публикации сохраняет историю команды и контрольный хеш агента; состав объединённой версии и её проверки описаны в протоколе публикации. Данные для формы «Сдать решение» подготовлены в SUBMISSION.md; отправка этой формы на платформе — отдельное действие, пока не подтверждённое. Подробности подготовки репозитория: PACKAGING.md.