That's La Peace

Версия для жюри и сдачи — только ветка main. В ней собран итоговый проект обоих участников: приложение, готовый запуск, данные и документация. Дополнительные ветки dev-dinmukhammed, dev-ilyas, dev-zoro и integration сохранены как история совместной разработки; они не являются отдельными версиями для оценки. Скачивайте и запускайте именно main.

HackAlem AI · кейс #79-lite · трек 06 «Креативные индустрии»

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

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

Участник	Ответственность
Dinmukhammed	Backend, данные, подбор и объяснения, интеграция и публикация общей версии
Ilyas	Frontend, дизайн, демо, капитан команды и подача решения

Запуск для жюри — один двойной щелчок

Windows 10/11, 64-разрядная x64. Получите полную папку этой версии проекта из официального репозитория (Code → Download ZIP и распаковать, либо Git clone). Откройте START.cmd двойным щелчком. Или выполните одну команду в PowerShell из папки проекта:

.\START.cmd

Браузер откроется сам после готовности сервера. Python, Git, Node.js, установка библиотек, аккаунт приложения и API-ключи для этого запуска не нужны: интерпретатор, зависимости, интерфейс и все 66 профилей включены в portable/ContractorPicker.exe. После получения папки основной интерфейс и подбор работают без интернета. Первое получение проекта требует доступа к репозиторию; его права не заменяются запуском приложения. Не запускайте файл прямо внутри ZIP — сначала распакуйте папку.

• Адрес появится в окне запуска: обычно http://127.0.0.1:8000/. Если порт занят, приложение само выберет свободный и откроет свой адрес.
• Если браузер не открылся, скопируйте напечатанный адрес. Например, на http://127.0.0.1:8000/api/health (подставьте фактический порт) должны быть status: ok и dataset_count: 66.
• Остановка: Ctrl+C в окне запуска или закрыть это окно. Повтор: снова открыть START.cmd; никаких миграций, паролей или настройки нет. Окно сервера должно оставаться открытым, пока вы смотрите демо.
• Логи видны в этом же окне. При ошибке запуска оно останется открытым с сообщением. Если файл отсутствует — получите полную папку проекта вместе с portable/.
• Пакет не подписан цифровой подписью. Если политика рабочего компьютера запрещает его запуск, используйте установку из исходников ниже; отключать защиту не требуется.
• На macOS/Linux готовый Windows-файл не работает: нужен запуск исходников с Python 3.12 (создание окружения python3.12 -m venv .venv, далее .venv/bin/python вместо Windows-пути). Эти ОС в текущей приёмке не проверялись.

Приложение доступно только на компьютере проверяющего, без публичного сервера команды. Обязательных переменных окружения, .env, внешней базы, скачивания моделей и личных секретов нет. Лицензии и сведения о сборке — в portable. Проверенная среда: Windows 11 Pro 64-bit 10.0.26200, AMD Ryzen 7 4800H, около 16 ГБ RAM; это среда проверки, не измеренный минимум.

Запуск из исходников — запасной вариант

Нужен Python 3.12; Git нужен только для команды clone. Можно вместо неё распаковать архив проекта и открыть PowerShell в его папке. Команды для новой копии опубликованной main, Windows PowerShell:

git clone --branch main --single-branch https://github.com/BAITC-Hacks/hack-95a1b8c8-that-s-la-peace.git
Set-Location hack-95a1b8c8-that-s-la-peace
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe run.py

Откройте http://127.0.0.1:8000/ после сообщения Uvicorn о запуске. Активация окружения и изменение ExecutionPolicy не нужны. Если py отсутствует, создайте окружение установленным Python 3.12 по полному пути: & 'C:\путь\к\Python312\python.exe' -m venv .venv — замените шаблон реальным путём.

Для первого скачивания проекта и зависимостей нужен интернет. Затем основной интерфейс и подбор работают локально: один Python-сервер, без Node.js, сборки frontend, ключей и платных аккаунтов. Доступ к официальному GitHub-репозиторию определяется его настройками.

• Проверка готовности: http://127.0.0.1:8000/api/health → status: ok, dataset_count: 66.
• Остановка: Ctrl+C. Повторный запуск — той же командой, миграций нет.
• Если порт занят: .\.venv\Scripts\python.exe run.py --port 8002, затем откройте http://127.0.0.1:8002/. По умолчанию сервер доступен только на этом компьютере.
• Для фиксации проверяемой версии выполните git rev-parse HEAD; результаты отчётов относятся к конкретному SHA.

Проверенный пакет: около 15 МБ; запуск из чистой папки занял 3,1 с, повторный — 1,8 с на указанной машине. На другом компьютере время может отличаться. Последняя проверка пакета.

Демо за несколько минут

Язык подрядчика и длительность оставьте пустыми. Выбирайте значения из списков; дату можно ввести как 15.10.2026 или выбрать в календаре.

Сценарий	Город / категория / формат	Дата / бюджет	Ожидаемый результат по каталогу
Плотная категория	Алматы / Ведущий / корпоратив	15.10.2026 / 1 000 000 ₸	3 карточки из 6 подходящих, конкретные отличия в объяснениях
Изменение только даты	Те же условия	16.10.2026 / 1 000 000 ₸	3 карточки из 4, состав выдачи изменяется из-за занятости
Редкая категория	Алматы / Флорист / свадьба	15.10.2026 / 1 000 000 ₸	2 карточки и объяснение, почему их меньше трёх
Все заняты	Астана / Флорист / свадьба	15.10.2026 / 1 000 000 ₸	Пустой результат с причиной; предложение перейти на 14 октября
Недостаточный бюджет	Алматы / Ведущий / корпоратив	15.10.2026 / 1 ₸	Пустой результат и проверенное предложение увеличить бюджет
В городе нет категории	Зарубежье / Ведущий / корпоратив	15.10.2026 / 1 000 000 ₸	Отдельное сообщение об отсутствии категории

Для последнего примера в «Настройки подбора» снимите «Скрывать несовместимые категории и форматы». Там же можно отключить автоподбор и отправлять запросы кнопкой. Повторите первый запрос: порядок карточек должен сохраниться. Совет даты или бюджета применяется отдельным нажатием. Расширенный сценарий демо.

Число под днём календаря — справка о свободных профилях выбранной группы до проверки бюджета, языка и часов. Поэтому оно может быть больше числа подходящих в результате: для первого примера календарь показывает 7 свободных, сервер оставляет 6 и выводит 3.

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

• Обязательные фильтры города, категории, даты, формата и начальной цены; необязательные язык и длительность. Занятые подрядчики исключаются, включая площадки.
• До трёх карточек в стабильном порядке: имя, категория, город, цена «от», 1–2 предложения объяснения, исходный фрагмент описания и признаки происхождения данных.
• Различимые состояния: подобрали; в городе нет категории; кандидаты есть, но не подходят. При выдаче менее трёх карточек показана причина. Сетевая ошибка отображается отдельно.
• Ближайшая подходящая дата и минимальный достаточный начальный бюджет проверяются теми же фильтрами. Каждый совет меняет только одно условие; неподтверждённые советы не показываются.
• Компактная адаптивная форма: поиск и выбор в одном поле списка (combobox), ввод бюджета с разделителями, единое поле даты с календарём, дополнительные параметры и настройки в раскрываемых блоках.
• Переключение интерфейса RU / KK / EN, управление списками с клавиатуры, необязательный автоподбор, справка о ценах и доступности. Исходные описания и объяснения остаются русскими с явной подписью; сообщения подбора и советы также пока на русском.

Архитектура и роль AI

CSV → нормализованный каталог → проверка запроса → обязательные фильтры
    → детерминированное ранжирование → до 3 карточек с объяснениями
    → при пустой выдаче: проверка альтернатив даты и бюджета

Backend: Python 3.12, FastAPI, Pydantic, Uvicorn. Каталог проверяется и загружается в память при старте. Сначала применяются ограничения, затем учитываются тематические основы слов формата и категории в описании; при равенстве — начальная цена и стабильный ID. Это прозрачное лексическое соответствие, а не рейтинг качества подрядчика. Одинаковый запрос к тому же каталогу даёт одинаковый порядок.

Frontend: HTML/CSS/JavaScript без сборки, раздаётся тем же сервером и вызывает относительные /api/…. Справочные агрегаты catalog-guide.json используются только при совпадении SHA каталога; они не добавляют профили и не заменяют серверный подбор.

Codex участвовал в разработке кода, документации, автоматических проверок и интеграции под управлением команды. Во время подбора приложение не вызывает LLM, не обучает модель и не отправляет запрос во внешний AI-сервис. Объяснения формируются детерминированно из условий и фактов профиля. Автоматические проверки и человеческая оценка отмечаются отдельно.

Подробнее: архитектура, API v1, вклад и ход работы, зависимости.

Данные и честные ограничения

Источник — неизменённый выданный CSV: 66 анонимизированных профилей, включая 13 исходных синтетических; у 8 заполнен город, у 18 — начальная цена. Эти признаки передаются в карточках. Команда дополнительных профилей не добавляла. Происхождение и SHA-256.

• Календарь покрывает 23.09.2026–31.12.2026 включительно. Даты вне этого окна отклоняются: занятость неизвестна. Изменение CSV требует перезапуска и меняет dataset_version.
• Цена «от» — нижняя граница из каталога, не итоговая стоимость заказа. Стоимость расширенного состава или пакета нужно уточнять; отсутствие занятой даты не подтверждает реальную бронь.
• Пустой max_hours означает неприменимое ограничение присутствия. Незаданные язык и часы не считаются пожеланиями пользователя. Рекламное описание не подтверждает качество, опыт или рейтинг.
• Небольшой каталог и лексические словари ограничивают полноту рекомендаций. Для описаний без конкретики используются известные структурированные факты; недостающие сведения не придумываются.
• Переведён интерфейс; исходные описания, объяснения, сообщения подбора и советы пока русские. Бюджет в браузере — целое от 1 до 9 007 199 254 740 991; это граница точного числа JavaScript, не серверный предел цены.
• Публичный интернет-деплой пока не выполнен. Бронирование, заявки, оплата, аккаунты и уведомления подрядчика не входят в текущий кейс.

Обязательных переменных окружения нет. Основной сервер ограничивает тело запроса 16 КиБ, возвращает понятный 413 при превышении и раздаёт только разрешённые публичные ресурсы. Защитные заголовки и CSP описаны в контракте. Служебная документация http://127.0.0.1:8000/docs использует Swagger из внешнего CDN; основному UI/API он не нужен.

Автоматические проверки из исходников

Для обычной проверки готового Windows-пакета достаточно таблицы демо и адреса готовности выше. Следующие команды — дополнительные проверки разработчика: сначала выполните установку из исходников, затем откройте второй PowerShell из корня проекта, пока сервер работает:

.\.venv\Scripts\python.exe scripts/smoke.py

Это настоящие HTTP-запросы: плотная категория на двух датах, повторяемость, редкая категория, оба пустых исхода и повторное применение советов даты/бюджета. Скрипт выводит результат и измеренное время. Для другого порта добавьте --base-url http://127.0.0.1:8002.

Автоматические проверки backend, контракта, данных, объяснений и HTTP-ограничений:

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m pytest -q

Для проверки frontend дополнительно нужны Node.js; для браузерных сценариев — Playwright 1.62.1 и Edge либо путь BROWSER_EXECUTABLE. Обычный запуск приложения их не требует.

node tests/ui/api.test.mjs
node tests/ui/server.test.mjs

Для браузерных проверок установите Playwright в отдельную папку инструментов, задайте PLAYWRIGHT_MODULE полным путём к её node_modules/playwright и UI_CHECK_OUTPUT путём для снимков вне Git. При работающем сервере:

node tests/ui/browser-check.cjs http://127.0.0.1:8000
node tests/integration/browser-live.cjs http://127.0.0.1:8000
node tests/ui/ux-check.cjs http://127.0.0.1:8000

Первый браузерный сценарий использует явно обозначенные синтетические ответы; два следующих проверяют реальный UI/API и каталог. Условия, результаты и конкретные версии смотрите в TEST_REPORT, интеграционных отчётах и FINAL_COMPLIANCE_REPORT. Каждый отчёт относится к указанной в нём версии.

Как создавался продукт

Проект собран 23 сентября 2026 года для одного кейса организаторов. Ниже — краткая история решений; точные коммиты, исполнители проверок и результаты сохранены в PROGRESS. Записи прежних этапов относятся к своим версиям.

Этап	Что появилось и зачем
Требования и основа	Разобрали кейс и 66 профилей, сохранили исходный CSV, разделили backend и frontend, зафиксировали API для параллельной работы.
Первый рабочий подбор	Добавили загрузку и проверку данных, жёсткие фильтры, стабильный top-3, причины пустой выдачи и проверенные советы; затем объединили API с интерфейсом.
Качество объяснений	Уточнили выбор цельных фактов вместо рекламы, сохраняли исходные выдержки и оговорки о цене состава; реализовали конкретные замечания Dinmukhammed после просмотра примеров.
Удобство и устойчивость	Ilyas подготовил компактный интерфейс, поиск в списках, календарь, RU/KK/EN и автоподбор; добавлены обработка ошибок, защита HTTP, проверки настоящего UI/API и чистого запуска.
Подготовка для жюри	Подготовлены сценарии демо, документация, START.cmd и автономная Windows-сборка, чтобы основной запуск не требовал установки среды разработки. Приёмка каждой сборки фиксируется отдельно.

Код, документы и автоматические прогоны создавались с помощью Codex по поручениям участников. Человеческий просмотр объяснений, техническая проверка агентом и подача капитаном — разные действия; одно не считается доказательством другого. Распределение ответственности указано в начале README, подробности передачи — в handoff Dinmukhammed и handoff Ilyas.

Технологии и инструменты

Часть	Использовано
Подбор и API	Python 3.12, FastAPI, Pydantic, Uvicorn; точные версии — requirements.txt.
Интерфейс	HTML, CSS, JavaScript ES modules; собственные списки с поиском, календарь и переводы интерфейса, без обязательной сборки Node.js.
Данные	CSV в репозитории, нормализованный каталог в памяти и SHA-256 версии; внешняя БД сейчас не используется.
Автоматические проверки	pytest/httpx, HTTP smoke, Node.js, Playwright и Edge; тестовые зависимости, результаты привязаны к проверенной версии.
Автономный Windows-запуск	START.cmd, Python launcher и PyInstaller; интерпретатор, зависимости и ресурсы упакованы в EXE. Состав, сборка и лицензии.
Совместная разработка	Git/GitHub, отдельные рабочие ветки, согласованный API, передача готовых изменений и общая интеграция; Codex — инструмент разработки.

Происхождение сторонних компонентов и предварительных материалов раскрыто в THIRD_PARTY. Наличие инструмента в этой таблице не означает, что его нужно устанавливать для запуска готового EXE.

Как планируем масштабировать

Это план развития, не описание уже реализованных возможностей. Для 66 записей достаточно одного процесса и каталога в памяти.

1. Сначала измерения. Проверить больший разрешённый каталог, параллельные запросы, время ответа и потребление памяти; определить, где возникает ограничение, сохраняя качество объяснений и повторяемость.
2. Хранение и обновление данных. При необходимости перейти к БД с проверяемыми импортами, версиями каталога и историей изменений цен/занятости. Ответ должен относиться к одному согласованному снимку данных; происхождение и неизвестные значения сохраняются.
3. Индексы и кеш по результатам замеров. Индексировать фактические условия поиска; кешировать по нормализованному запросу и версии каталога. При обновлении данных старый кеш перестаёт использоваться. Эти меры пока не реализованы.
4. Рост сервиса. Только при подтверждённой нагрузке добавлять несколько процессов, общий источник данных, наблюдение за ошибками и резервное восстановление; измерять улучшение на тех же сценариях.
5. Языковая модель — отдельный эксперимент. Возможный разбор свободного запроса или помощь с формулировками оцениваются по точности, задержке и стоимости. Жёсткие фильтры, проверяемые факты и рабочий путь без модели должны сохраняться; текущий runtime LLM не использует.

Пользовательские улучшения и приоритеты перечислены ниже; масштабирование не должно задерживать исправление понятности результата.

Дальнейшие улучшения

Идеи для следующих версий, ещё не реализованные:

• Улучшать выбор конкретных фактов в объяснениях, особенно у фотографов и видеографов; проверять тексты по источнику и читать карточки с людьми без имён.
• Перевести содержание карточек, сообщения подбора и советы на казахский и английский с сохранением оригинала и проверкой фактов.
• Добавить сохранение и сравнение вариантов на устройстве, историю запросов и ссылку с параметрами поиска.
• Дорабатывать форму, мобильное чтение, клавиатурное управление и поддержку экранных дикторов по проверке с пользователями.
• Обновлять цены и занятость с проверкой данных, датой обновления и сохранением допустимых параметров запроса; явно отделять неизвестную доступность от свободной даты.
• Добавить подтверждённые пакеты и состав цены, реальные портфолио и контакты с разрешением на публикацию; отзывы — только с проверяемым происхождением.
• Разместить демо по общей ссылке с HTTPS, наблюдением за ошибками и восстановлением; проверить с другого устройства.
• Исследовать ввод запроса обычными словами с подтверждением распознанных условий. Возможную LLM оценивать отдельно по пользе, точности, времени и стоимости, сохраняя строгие фильтры и работу без неё.
• Измерить качество и скорость на большем реальном каталоге; добавить удобную диагностику версии приложения. Версия данных уже доступна через API.
• Исследовать почасовую доступность только после получения реальных интервалов занятости и согласования нового контракта: нынешний каталог содержит только занятые даты. Не считать занятый день свободным на основании выдуманных часов.

Бронирование, платежи и личные кабинеты — возможный отдельный этап после проверки спроса и получения реальных данных. Приоритеты определяются пользой и результатами проверок.

Совместная работа и сдача

Опубликованная общая версия — main; backend-ветка — dev-dinmukhammed. Ветка dev-ilyas создана от принятого этапа d48a378. Последнее обновление Ilyas 04d92f2 получено из dev-zoro и включено в общую версию. Его переход с dev-zoro на другом компьютере пока не подтверждён, поэтому старая ветка временно сохранена. Общую сборку публикует Dinmukhammed, форму сдаёт капитан Ilyas. Git push сам по себе не является подачей решения.

Правила и владение файлами — AGENTS, общий план — 00_SHARED_PLAN, персональные задачи — Dinmukhammed и Ilyas. Одноразовая проверка перед личным коммитом описана в CHECKPOINT; актуальный статус и требования — STATE и COMPLIANCE.

Навигация по документации

Что нужно найти	Документ
Исходное задание и критерии результата	CASE_REQUIREMENTS
Пайплайн, фильтры, ранжирование и границы решения	ARCHITECTURE
Запросы, ответы, ошибки и совместимость клиента	API_CONTRACT
Источник каталога, поля и контрольная сумма	Данные, CSV
История создания и вклад	PROGRESS, сторонние компоненты
Автоматические проверки и точные версии	TEST_REPORT, интеграционные отчёты
Предметная оценка объяснений и независимый запуск	EXPLANATION_REVIEW, EXPERT_CHECK
Сценарий показа	DEMO
Передача частей команды	Dinmukhammed, Ilyas
Версии зависимостей	Runtime requirements, тестовые requirements
Требования, готовность и оставшиеся действия	COMPLIANCE, FINAL_COMPLIANCE_REPORT, STATE
Правила, план и рабочие промпты	AGENTS, общий план, backend, frontend
Windows-пакет и воспроизводимая сборка	portable/README, лицензии

Исторические документы сохраняют состояние на дату записи. Финальную проверяемую версию и статус подачи смотрите в итоговом отчёте; новая запись в README не заменяет фактическую проверку.