HackAlem Track 04: tariff campaign agent

Офлайн-агент Agent.act(env) исследует тарифные переходы пилотами и возвращает 1–10 кампаний. История используется как подсказка; финальный план состоит только из проверенных пилотами комбинаций. Агент не читает модель эффектов, не использует сеть, LLM или секреты среды.

Запуск

Python 3.12+; зависимости закреплены в requirements.txt. Из корня репозитория:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python -m pytest -q
python local_eval.py
python local_eval.py --runs 10
python make_submission.py
sha256sum submission.csv

make_submission.py использует seed 42. Повторный запуск создаёт тот же CSV. Указанное официальным evaluator число кампаний включает пилоты; лимит 10 применяется к возвращённому финальному списку.

Проверено перед финальной сдачей на штатном mock:

seed 0–9: 10 из 10 результатов положительны
медиана: 3,399,849
минимум: 2,507,992
максимум: 3,564,974
seed 42 submission.csv SHA-256:
4198927766416446991f4090f4071759a3c5dac3bceac9c0066eaed6a8272022

Это воспроизводимый локальный результат на синтетическом evaluator, а не гарантия скрытого judge или реального бизнес-эффекта.

Как принимаются решения

1. Публичный профиль разбивается на непересекающиеся текущий тариф × ARPU сегменты. Группы больше 5000 дополнительно делятся по data/call segment.
2. История ранжирует переходы и каналы. Первые 16 наблюдений сохраняют историческую разведку baseline, включая повторное измерение текущего лидера. Исторический shortlist задаёт начало порядка, но остальные допустимые комбинации сохраняются.
3. Последние четыре пилота выбираются по приближённой ценности информации: ожидаемому улучшению относительно лучшего измеренного варианта для того же сегмента, с учётом затрат и ожидаемого отрицательного эффекта самого пилота. Можно уточнить пограничную кампанию, исследовать новый переход или остановиться. Новая гипотеза получает 100 контактов, повторная — до 200; call — до 50.
4. Средний эффект взвешивается по числу контактов и стягивается к нулю с весом 80 условных наблюдений. Малые выборки получают дополнительный штраф за неопределённость; при отрицательном среднем результате разведки штраф сохраняется и для больших выборок. Это эвристика риска, а не доверительный интервал или гарантия статистической значимости.
5. Планировщик оценивает добавочный эффект финальной кампании после пилотов. При частичном охвате он использует ожидаемое пересечение независимых случайных выборок; повторный полный охват уже проверенного сегмента не даёт новый lift.
6. Точный поиск портфеля среди не более 20 измеренных комбинаций выбирает максимум суммарного оценённого эффекта с ограничениями бюджета, контактов, десяти кампаний и одного варианта на сегмент. Порядок выдачи детерминирован.

Перед каждым пилотом проверяются публичные остатки ресурсов; резерв сохраняет возможность хотя бы одной финальной кампании. На пилоты уходит не более 25% начального денежного бюджета. Ошибка пилота останавливает разведку без повтора вызова. Если прибыльных оценок нет, агент по возможности измеряет небольшой бесплатный сегмент и возвращает наименее убыточный измеренный вариант, поскольку контракт требует хотя бы одну кампанию. Бесплатный канал всё равно может снижать ARPU и расходует контакты.

Agent.trace содержит запросы и результаты пилотов, остатки ресурсов и финальные решения. final_selected.estimated_score — оценка добавочного эффекта после дедупликации с пилотами. Точное пересечение ID и истинный результат считает только официальный scorer.

Воспроизводимое сравнение с b70e366

python scripts/compare_candidate.py --seeds 10 --out reports/candidate-standard.json
python scripts/compare_candidate.py --start 100 --seeds 10 --model-seed 20261001 --out reports/candidate-holdout.json
python scripts/compare_candidate.py --start 200 --seeds 10 --model-seed 20261002 --scenarios weak sparse dense saturated --out reports/candidate-holdout2.json
python scripts/compare_candidate.py --start 300 --seeds 10 --model-seed 20261003 --scenarios weak sparse dense saturated --out reports/candidate-final-validation.json
python scripts/compare_candidate.py --start 42 --seeds 1 --scenarios mock --out reports/candidate-seed42.json

Нужна Git-история с b70e366: runner загружает четыре исходных модуля baseline в отдельные пространства имён, не переключает ветки и не изменяет файлы. Для обоих агентов используются одинаковые данные, модель и seed шума. Собственные модели живут только в evaluator и передаются публичной make_environment; агент получает исключительно env. В JSON сохраняются все результаты, нарушения, время и SHA-256 проверенных исходников.

Сценарии: официальный mock, нулевой эффект, все переходы убыточны, слабые эффекты, редкие прибыльные переходы, смешанные эффекты и насыщение конверсии. Это конечный набор синтетических проверок, а не оценка будущего балла. Подробные числа, регрессии и рекомендация интеграции — в отчёте кандидата. Предыдущие reports/development*, reserved* и integration.md относятся к старой версии и не подтверждают качество текущего кандидата. scripts/evaluate.py по-прежнему доступен для сравнения с официальным template, а не с b70e366.

Упаковка и ограничения

Для сдачи нужны agent.py, contracts.py, planning.py, policy.py, submission.csv и зависимости из requirements.txt; одним agent.py многомодульное решение не ограничивается. Положите рядом data/change_tariff.csv, чтобы воспроизвести историческое ранжирование. При отсутствии истории агент работает с публичными профилем и тарифами, но его решения и score могут отличаться. Полный репозиторий содержит также официальную среду, данные и команды воспроизведения.

Первые 16 пилотов ещё зависят от истории. Четыре поздних пилота не гарантируют обнаружения редкой прибыльной комбинации. Гауссовская оценка использует опубликованный масштаб шума 0.804; она не калибрована для другого шума или адаптивного отбора. Модель ожидаемого пересечения предполагает равномерные независимые пилотные выборки. Точный подбор максимизирует оценку, а не неизвестный истинный эффект.

Все исходные файлы организаторов и данные сохранены по SHA-256 из provenance.json; атрибуция — в THIRD_PARTY.md. Никаких гарантий положительного результата на скрытом judge или реальной базе нет.

Объяснение одного запуска

python scripts/explain_run.py --out reports/explanation

Команда вызывает Agent.act ровно один раз через официальный evaluate_agent. Сохраняет plan.json, trace.json, local_evaluator.json, facts.json, explanation.json и русский explanation.md. Числа берутся только из Python; неизвестные и нечисловые значения представлены null / «неизвестно» (включая бесконечный ROI в сохранённом evaluator). Идентификатор c01 означает первую кампанию plan.json, eN — событие trace с step=N. История, шумные наблюдения пилотов, эвристические оценки агента и локальный результат разделены.

По умолчанию используется детерминированный офлайн-шаблон. Обычные local_eval.py и make_submission.py всегда остаются офлайн, даже при наличии API-переменных. Объяснение не меняет план, пилоты, ресурсы или CSV.

Опциональный режим требует официального Python SDK, который не нужен агенту:

pip install openai
cp .env.example .env
# Заполните .env локально: новый ключ и доступная вам модель Responses API.
set -a
. ./.env
set +a
python scripts/explain_run.py --llm --out reports/explanation

Не используйте ключи из переписки; создайте новый ключ локально. Секреты не печатайте и не добавляйте в Git. .env и .env.* игнорируются, .env.example содержит только пустые переменные. Файл .env автоматически не загружается: конфигурация читается исключительно из окружения и только при --llm. OPENAI_API_KEY и OPENAI_EXPLANATION_MODEL обязательны для LLM. OPENAI_EXPLANATION_TIMEOUT_SECONDS по умолчанию 20 (допустимо >0 и <=120), OPENAI_EXPLANATION_MAX_OUTPUT_TOKENS по умолчанию 2000 (1–8000).

Выполняется максимум один запрос Responses, max_retries=0, store=False, без tools и web search. Используется официальный формат Responses text.format. Payload ограничен 48000 байт и содержит только разрешённые агрегированные факты, без CSV, строк абонентов и ID_NUMBER. Ссылки проверяются не только на существование, но и на принадлежность кампании. Свободный текст LLM намеренно запрещён: структурированный русский JSON использует закрытый словарь проверенных фраз, чтобы модель не добавляла числа, кампании и неподтверждённые утверждения.

Нет ключа/модели/SDK, неверные настройки, timeout, 401/429/5xx, неполный ответ, невалидный JSON или ссылки — сохраняется офлайн-шаблон с безопасным кодом fallback. Тексты исключений и сырые ответы модели не сохраняются. Общий deadline работает через POSIX timer в главном потоке; на неподдерживаемой платформе, в другом потоке или при уже активном timer выполняется fallback до запроса. Все данные синтетические; локальный результат не гарантирует скрытый балл или реальный бизнес-эффект.