SURVAE · EKT Ассистент

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

Проект команды SURVAE для HackAlem AI, трек «Торговля», кейс ekt.kz / Электрокомплект. Разработка велась с OpenAI Codex. Нейросеть не обучалась; используется API готовой модели.

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

• Свободный диалог с контекстом и защитой от повторных вопросов; запросы вне профиля магазина обрабатываются отдельно.
• Поиск по артикулу, карточки с характеристиками, ценами, городскими остатками и доступными документами.
• Подбор подтверждённых аналогов по данным каталога; неизвестная совместимость не объявляется проверенной.
• Информация об оплате, доставке и минимальной партии выбранного товара.
• Подбор лампы с жёсткими условиями по цоколю, температуре и точной/максимальной мощности.
• Учебный комплект подсветки кухни: уточнения, состав, назначение и проверка компонентов.
• Разбор PDF, DOCX, XLSX/XLS, TXT/CSV; изображения обрабатываются при подключённом AI.
• Проверка всех распознанных строк спецификации; неизвестная строка блокирует частичное предложение.
• Список покупок → проверка цены/остатка → предложение → кнопка подтверждения → демо-корзина.
• Повторное подтверждение не дублирует заказ. Сессии изолированы, POST защищён CSRF.
• Адаптивный интерфейс, обработка ошибок, явные demo/fallback, новый диалог и прямая ссылка /cart.

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

Нужен Python 3.11+. Node.js нужен только для frontend-тестов; сайт не требует сборки.

Windows PowerShell

git clone https://github.com/BAITC-Hacks/hack-34b3d405-survae.git
cd hack-34b3d405-survae
py -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
if (-not (Test-Path .env)) { Copy-Item .env.example .env }
.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Linux / macOS

git clone https://github.com/BAITC-Hacks/hack-34b3d405-survae.git
cd hack-34b3d405-survae
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
test -e .env || cp .env.example .env
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Откройте приложение, корзину или API-документацию. Запускайте один процесс, без нескольких workers. Уже заполненный .env не перезаписывайте.

Режимы и ключи

По умолчанию работает demo-каталог из 15 синтетических позиций. Без ключа доступны локальный поиск и ограниченные правила — это не полноценная AI-консультация. Для AI задайте OPENAI_API_KEY в локальном .env и перезапустите сервер. OPENAI_MODEL по умолчанию gpt-4o-mini. Ключи не входят в репозиторий и не должны передаваться через браузерный JS или описание решения.

Для каталога партнёра: CATALOG_MODE=live, EKT_USERNAME и EKT_PASSWORD из материалов партнёра. CATALOG_PAGES=20 — ограниченная выборка, не весь ассортимент. Синтетические товары не подставляются в live. Недоступность данных блокирует подтверждение покупки. Для обычного запуска оставьте ALLOW_LOCAL_SETUP=0; публичный деплой не настроен.

Проверка для жюри за 3–5 минут

1. В режиме demo введите «Лампа E27 до 40 Вт 3000 К». Должна появиться DEMO-LED-W; товары 4000 К не подходят.
2. «Какая минимальная партия?» — ответ относится к выбранной лампе: 1 ед.
3. Новый диалог: «Нужна лампочка» → E27 → «Нужна ровно 40 Вт» → 3000 К. В demo такой позиции нет: 9 Вт не заменяет точные 40 Вт.
4. Новый диалог: «Хочу подсветку кухни» → «2 м» → «Есть розетка рядом» → «Сухое место, вдали от воды» → «Тёплый свет». Предложение: DEMO-BAR-W ×2 + DEMO-PSU-60 ×1, 10900 ₸.
5. До подтверждения корзина пуста. Текст «да» не добавляет товар. После кнопки подтверждения — две строки, count=3, сумма 10900 ₸. Повторное подтверждение не добавляет дубли.
6. Откройте /cart. Новый диалог сохраняет подтверждённую корзину.
7. Для спецификации загрузите Excel из двух столбцов: DEMO-C16-A | 2 и DEMO-LED-A | 3. Напишите «Подготовь предложение по спецификации»: обе строки должны попасть в предложение.
8. С подключённым AI спросите про камеру для дома, затем «Можно купить торт?»: старая подсветка не подставляется, ответ учитывает профиль магазина.

Дополнительно: DEMO-C16-Z — отсутствующий товар для проверки аналогов; DEMO-C16-A — характеристики и учебный документ. DEMO-документ не является настоящим сертификатом.

Архитектура и технологии

Python / FastAPI / Pydantic / HTTPX; OpenAI Responses API со структурированными ответами; HTML/CSS/JavaScript без frontend-фреймворка. Обработка файлов: pypdf, python-docx, openpyxl, xlrd, Pillow. Полные зависимости — requirements.txt и requirements-dev.txt.

• app/main.py — HTTP API, сессия, защита запросов и координация диалога.
• app/ai.py, dialogue.py — разбор намерения, история и общая консультация.
• app/catalog.py — demo/live данные, карточки, остатки и аналоги.
• app/lamps.py, kits.py — проверяемые ограничения и учебная комплектация.
• app/specifications.py, attachments.py — файлы и построчная проверка заказа.
• app/commerce.py — предложение, повторная проверка и атомарное подтверждение.
• static/ — интерфейс, работающий с тем же API.

Основные методы: GET /api/cart, POST /api/chat, POST /api/cart/confirm. Сначала GET выдаёт cookie сессии и CSRF; POST требует X-CSRF-Token. Подтверждение содержит proposal_id и confirmed:true. Полный контракт.

Проверки

python -m pytest -q
node --test tests/frontend_flow.test.cjs tests/frontend_consultation.test.cjs

Финальная интеграционная проверка: 173 Python-теста и 6 frontend-тестов. Исправленные R1/R2/R3/BE-02 проверяются как обычные regression-тесты, без xfail. Были выполнены также ограниченные проверки настоящего OpenAI с demo-каталогом; это не гарантия ответа на любой запрос. Отчёт финальной сборки.

Данные, внешние сервисы и ограничения

Реальный адаптер использует API ekt.kz/api/products и API карточек; опубликованные условия покупки — ekt.kz. data/demo_catalog.json и data/demo_kits.json — синтетические данные команды, явно обозначенные в интерфейсе.

Корзина демонстрационная: заказ на ekt.kz не оформляется, склад не резервируется. Полный ассортимент партнёра и универсальная совместимость оборудования не проверены. Проверенный комплект кухни не является проектом электромонтажа.

История (последние 32 сообщения), предложения и корзины находятся в памяти одного процесса. Перезапуск очищает их. Для production требуются постоянное хранилище, HTTPS, авторизация и разрешённая интеграция оформления заказа.

Предложение содержит до 12 строк. Excel: до 5 листов, 150 строк и 16 столбцов; извлечённый текст — до 16000 символов; файл — до 8 МБ. Слишком большие документы отклоняются, а не обрезаются молча. Произвольная верстка, сложные таблицы и распознавание фото могут требовать уточнения; сверяйте результат с исходником.

При подключённом AI сообщение, история и вложения отправляются в OpenAI API с store=false. Не загружайте персональные, платёжные и конфиденциальные данные. Секреты не публикуются. Деплой отсутствует; localhost — только компьютер, на котором запущен сервер.