AI-CONNECT: Autonomous Tariff Campaign Agent

Что делает проект

Проект реализует автономного агента для телеком-случая с таргетированными маркетинговыми кампаниями по смене тарифа. Его задача — анализировать профиль абонентов, выявлять сегменты, у которых переход на другой тариф может увеличивать ARPU, запускать ограниченные пилоты и формировать итоговый план кампаний до 10 решений.

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

---

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

В репозитории уже есть:

• Python-агент в agent.py с методом Agent.act(env);
• среда выполнения и логика пилотных кампаний в environment.py;
• локальная мок-среда для отладки в mock_environment.py;
• Streamlit-интерфейс в main.py;
• утилиты local_eval.py и make_submission.py;
• контейнеризация через Dockerfile и docker-compose.yml;
• набор синтетических данных в customer_profile.csv и каталоге data/;
• базовая документация по задаче в PARTICIPANT_GUIDE.md.

Сейчас проект поддерживает сценарий:

1. загрузка аудитории и справочников;
2. формирование гипотез;
3. запуск пилотов на ограниченной выборке;
4. оценка результатов по шумной метрике;
5. формирование списка финальных кампаний для запуска.

---

Используемые технологии и архитектура

Технологии

• Python 3.11+
• pandas — обработка данных и сегментация
• Streamlit — веб-интерфейс
• OpenAI API / NVIDIA API — опциональная работа через LLM
• python-dotenv — загрузка переменных окружения
• Docker / Docker Compose — запуск в контейнере
• FastAPI / Uvicorn — в проекте присутствуют зависимости, но основная логика UI и агентской задачи реализована в Python/Streamlit

Архитектура

Проект построен как агентный рабочий поток:

CSV данные / справочники
         |
         v
Agent.act(env)
         |
         +--> анализ сегментов и тарифов
         +--> формирование гипотез
         +--> запуск env.run_pilot(...)
         +--> оценка результата пилотов
         +--> выбор финальных кампаний
         |
         v
Streamlit UI / локальная валидация / submission

Основная логика отделена от среды исполнения: агент видит только публичный интерфейс среды и не должен обходить её внутренние замыкания и скрытые данные.

---

Порядок установки и запуска

Локальная установка

python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\activate
# Linux/macOS
# source .venv/bin/activate

pip install -r requirements.txt

Запуск приложения

streamlit run main.py --server.port 8000 --server.address 0.0.0.0

Приложение открывается по адресу:

http://localhost:8000

Запуск через Docker

docker compose up --build

Или:

docker build -t ai-connect-app .
docker run -p 8000:8000 --env-file .env ai-connect-app

---

Пример проверки

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

python local_eval.py

Генерация файла для сабмита

python make_submission.py

Проверка интерфейса

Открыть в браузере:

http://localhost:8000

В интерфейсе доступен запуск автономного агента и вывод результатов по сгенерированным кампаниям.

---

Используемые данные и внешние сервисы

Данные

В проекте используются синтетические данные, соответствующие задаче хакатона:

• customer_profile.csv — профили абонентов, текущие тарифы, сегменты ARPU, данные, звонки и прогноз ARPU;
• data/change_tariff.csv — история переходов между тарифами и изменение ARPU после смены;
• data/traffic.csv — показатели трафика, минут, SMS и других метрик;
• data/arpu_monthly.csv — ежемесячная выручка по абонентам;
• data/dict_tariff.csv — справочник параметров тарифов;
• feature_dictionary.csv и tariff_dictionary.csv — словари признаков и тарифных планов.

Внешние сервисы

• OpenAI API — опциональный источник рекомендаций для генерации гипотез;
• NVIDIA API — альтернативная интеграция LLM;
• переменные окружения из .env для ключей доступа.

Если API-ключи не заданы, агент использует fallback-эвристику, чтобы не падать и продолжать работу.

---

Известные ограничения

В проекте и в задаче есть ограничения, которые важно учитывать:

• максимум 10 финальных кампаний;
• максимум 5000 абонентов на одну кампанию;
• суммарно до 15000 контактов;
• бюджет до 100000 у.е.;
• не более 20 пилотов;
• каждый абонент должен участвовать не более чем в одной кампании;
• нельзя обходить среду через __closure__, gc или чтение скрытых данных;
• оценки на мок-среде не равны реальной продакшен-модели;
• LLM может быть недоступен или возвращать некорректный ответ, поэтому нужен fallback.

---

Ссылка на развёрнутую версию

На текущем этапе в репозитории и проектной конфигурации нет подтверждённой публичной ссылки на развёрнутую production-версию приложения. Если deployment появится позже, здесь нужно будет разместить ссылку вида:

https://your-deployed-app.example.com

---

Краткий итог

Этот проект объединяет:

• анализ данных и сегментацию аудитории;
• агентную логику выбора кампаний;
• пилотный экспериментальный подход для уменьшения неопределённости;
• визуализацию в Streamlit;
• контейнерный запуск и локальную валидацию.

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