Агент для тарифных маркетинговых кампаний

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

Сайт — локальная демонстрация агента. Введите seed, запустите расчёт и получите показатели и таблицу кампаний. Расчёт выполняется на вашем компьютере в тестовой mock-среде с синтетическими эффектами.

Если проект уже установлен

Откройте PowerShell в папке проекта, где лежат этот README и папка .venv-web, и выполните:

.\.venv-web\Scripts\python.exe -m webapp.app

Затем откройте http://127.0.0.1:8000 в браузере.

Терминал оставьте открытым. Для остановки сервера нажмите Ctrl+C. Если сервер уже работает, запускать второй не нужно — просто откройте сайт.

Если папки .venv-web ещё нет, выполните установку ниже.

1. Что понадобится для первого запуска

• Компьютер с Windows и PowerShell — инструкции ниже написаны для них.
• Python с модулями pip и venv.
• Git — если скачиваете проект командой git clone.
• Браузер.
• Интернет для скачивания проекта и первоначальной установки библиотек.

Проверенная конфигурация: Windows 11, Python 3.14.3, Flask 3.1.3. Другие версии и операционные системы отдельно не проверялись.

Для работы сайта не нужны Node.js, Docker, ключи API, платные сервисы или запущенная языковая модель. После установки сам расчёт не использует интернет.

Откройте терминал PowerShell. В VS Code: меню Терминал → Создать терминал. Проверьте Python:

python --version

Если команда не найдена, попробуйте py --version. Если работает только py, используйте его вместо python при создании окружения ниже. Если не работает ни одна команда, установите Python с pip и venv, добавьте его в PATH и заново откройте терминал.

Копируйте только команды из блоков. Строку приглашения вроде PS C:\...> копировать не нужно. Выполняйте команды по очереди; если появилась ошибка, исправьте её до следующего шага.

2. Откройте папку с общей сборкой

Если проект ещё не скачан

Из папки, в которой хотите сохранить проект, выполните:

git clone --branch main https://github.com/BAITC-Hacks/hack-b177ad85-temka.git hack-web-demo
Set-Location -LiteralPath ".\hack-web-demo"

Здесь выбрана main — ветка опубликованной общей сборки. Если GitHub запросит авторизацию, используйте свою учётную запись с доступом к репозиторию. Не добавляйте токены в файлы.

Если папка hack-web-demo уже существует, не удаляйте её: используйте существующую копию или выберите другое имя для нового клонирования.

Если проект уже есть на компьютере

Перейдите в его папку. Замените пример ниже своим настоящим путём:

Set-Location -LiteralPath "C:\путь\к\папке\проекта"

Название папки может быть любым. Важно, чтобы внутри находились requirements-web.txt, start_web.ps1, webapp и данные проекта.

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

Get-Location
Test-Path .\requirements-web.txt
Test-Path .\webapp\app.py
git branch --show-current
git status --short

Обе команды Test-Path должны показать True. Для этой сборки используется ветка main; в отдельной ветке проверки должен быть код общей сборки. Если нужных файлов нет, не продолжайте установку из неправильной папки.

Не переключайте ветку в папке работающего сервера. При незакоммиченных изменениях не удаляйте их и не делайте принудительный сброс ради запуска.

3. Установите зависимости — один раз

Рекомендуемый ручной способ не требует активации окружения, прав администратора или изменения политики PowerShell.

Создайте отдельное окружение Python

Из корня проекта:

python -m venv .venv-web

Если .venv-web уже создана для этой копии проекта, пропустите эту команду. Не удаляйте существующее окружение. Папка хранит библиотеки отдельно от глобального Python и не добавляется в Git.

Установите библиотеки

.\.venv-web\Scripts\python.exe -m pip install -r requirements-web.txt

Дождитесь завершения. Файл подключает зависимости агента из requirements.txt и Flask для сайта.

Проверьте установку

.\.venv-web\Scripts\python.exe -m pip check

Ожидаемый ответ: No broken requirements found. При ошибке установки не переходите к запуску — сохраните текст ошибки.

4. Запустите сервер и откройте сайт

Из той же папки выполните:

.\.venv-web\Scripts\python.exe -m webapp.app

При успешном запуске в терминале появится:

Running on http://127.0.0.1:8000
Press CTRL+C to quit

Откройте в браузере http://127.0.0.1:8000.

• Используйте http, не https.
• Это адрес на вашем компьютере, а не ссылка для публичного доступа.
• Терминал занят сервером — это нормально. Другие команды вводите в новом терминале.
• Предупреждение This is a development server не означает ошибку. Этот режим подходит для локальной демонстрации, но не для публичного размещения.

5. Проверьте работу сайта

1. Введите 42 в поле seed.
2. Нажмите кнопку запуска оценки.
3. Дождитесь завершения расчёта, не отправляя много запросов подряд.
4. Проверьте, что появились метрики и таблица финальных кампаний.
5. Повторите запуск с тем же seed, затем попробуйте, например, 7.

Seed — целое число от 0 до 2147483647, задающее случайность тестовой среды. При одинаковом seed, версии кода и окружении результаты воспроизводимы; время выполнения может отличаться.

На сайте отображаются:

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

В одном экземпляре сервера одновременно выполняется одна оценка. Ответ 409 означает, что предыдущая оценка ещё идёт: дождитесь её завершения.

6. Остановка и повторный запуск

Для остановки нажмите Ctrl+C в терминале сервера. Закрытие вкладки браузера само по себе сервер не останавливает.

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

.\.venv-web\Scripts\python.exe -m webapp.app

Заново создавать окружение и устанавливать библиотеки каждый раз не нужно. После изменения зависимостей повторите установку из раздела 3.

Альтернатива: запуск скриптом

Вместо ручной установки и запуска можно использовать:

.\start_web.ps1

Скрипт создаёт отсутствующую .venv-web, устанавливает зависимости при первом запуске и запускает сервер её Python. Он также работает из другой папки, если вызвать его полным путём в кавычках.

После изменения зависимостей:

.\start_web.ps1 -Reinstall

Если Windows запрещает запуск ps1, используйте ручной способ из разделов 3–4. Менять глобальную ExecutionPolicy не требуется.

Частые ошибки

Что произошло	Что делать
python не найден или открывается магазин	Проверьте py --version. Если Python отсутствует, установите его и заново откройте терминал.
requirements-web.txt не найден	Вы находитесь не в корне общей сборки. Проверьте Get-Location и раздел 2.
Путь к python.exe не найден	Проверьте наличие .venv-web и точное написание команды: она начинается с .\.venv-web, не с ..venv-web.
No module named flask / numpy / pandas	Установите requirements-web.txt через Python именно из .venv-web.
No module named webapp	Перейдите в корень проекта и запускайте -m webapp.app, а не файл app.py напрямую.
running scripts is disabled	Используйте ручной запуск без ps1 и без активации окружения.
Port 8000 is already in use / WinError 10048	Возможно, ваш сервер уже запущен. Проверьте его терминал. Останавливайте только свой сервер через Ctrl+C; не завершайте неизвестные процессы.
Браузер пишет «Не удаётся получить доступ»	Убедитесь, что сервер ещё работает, адрес — http://127.0.0.1:8000, и в терминале нет ошибки.
Ответ 400	Проверьте seed: нужен целый неотрицательный номер в допустимом диапазоне.
Ответ 409	Оценка уже выполняется. Подождите и повторите запрос.
Ответ 500 / EVALUATION_FAILED	Сохраните seed и полный текст ошибки из терминала. Не исправляйте данные или скоринг наугад.
fatal: not a git repository	Перейдите в саму папку репозитория, а не в её родительскую папку.

Для диагностики занятости порта можно выполнить:

Get-NetTCPConnection -LocalPort 8000 -State Listen

Эта команда только показывает слушающий процесс, не останавливая его.

Проверки для разработчиков

Обычному пользователю сайта запускать тесты не обязательно. Для проверки сборки откройте второй терминал в корне проекта:

.\.venv-web\Scripts\python.exe -m pip check
.\.venv-web\Scripts\python.exe -X utf8 -m unittest discover -s tests -v

В конце тестов должно быть OK. Часть тестов специально имитирует ошибки; смотрите итоговый статус, а не только отдельный traceback в журнале.

Для проверки агента без сайта:

.\.venv-web\Scripts\python.exe -X utf8 local_eval.py

Для серии из 10 прогонов:

.\.venv-web\Scripts\python.exe -X utf8 local_eval.py --runs 10

Перед оценкой прочитайте .codex/skills/hackathon-eval/SKILL.md. Эти команды приведены как инструкции: фактически выполненные проверки и их результаты перечислены в docs/HANDOFF_INTEGRATION.md. HTTP-тесты и тестовый клиент Flask не заменяют проверку сайта в браузере.

Ограничения и официальная сдача

• До 20 пилотов, 15 000 контактов и 100 000 бюджета.
• От 1 до 10 финальных кампаний, до 5 000 клиентов на каждую.
• Пилоты тоже расходуют бюджет и контакты. Например, 22 записи в отчёте могут означать 20 пилотов и 2 финальные кампании, а не нарушение лимита.
• Mock-среда использует синтетические эффекты. Положительный локальный результат не гарантирует результат скрытой проверки организаторов.
• Веб-приложение не создаёт и не обновляет submission.csv.
• Официальная сдача — отдельный процесс по PARTICIPANT_GUIDE.md. make_submission.py не входит в запуск сайта; его выполняют отдельно при подготовке сдачи, учитывая, что он обновляет артефакт submission.

Команда и документы

Все участники равноправно пишут код, тестируют и коммитят изменения.

Участник	Зона координации
Наурызбай	Серверная часть, подключение агента и интеграция.
Асан	Интерфейс и браузерные проверки.
Султанали	Установка, запуск и автоматические проверки.

• AGENTS.md — правила работы с репозиторием.
• PROJECT_STATE.md — текущее состояние и следующие задачи.
• docs/WEB_CONTRACT.md — договор компонентов и формат API.
• docs/HANDOFF_INTEGRATION.md — источники сборки, проверки и ограничения.
• docs/LOCAL_WEB.md — дополнительные технические инструкции.
• PARTICIPANT_GUIDE.md — правила кейса и официальной сдачи.

Перед изменениями проверьте git status и git log -3 --oneline. Не удаляйте чужую работу, не применяйте force-push, не коммитьте окружения, секреты, кэш или логи. Не меняйте одновременно одни и те же файлы. Каждый обновляет отчёт своего направления; PROJECT_STATE — интегратор. История участников сохраняется обычными merge. Объединение в main — отдельное согласованное действие после общей проверки.