HACKALEM AI — Quant

ИИ-помощник-консультант для интернет-магазина электротехнической продукции ТОО «Электрокомплект» (ekt.kz).

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

Проект — MVP-прототип conversational shopping assistant. Каталог, цены, остатки и документы в демо синтетические и не являются данными ekt.kz.

Возможности

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

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

Запрос клиента
    ↓
Поиск по каталогу
    ↓
Ответ, карточки или аналог
    ↓
Подтверждение количества
    ↓
Проверка остатка на сервере
    ↓
Корзина и ссылка на оформление

Пример диалога:

Клиент: Есть ли автомат ВА47-29 2P C16?
Quant: Да, 42 шт. Цена — 1 850 ₸. Показать характеристики и сертификат?
Клиент: Добавь 2 штуки в корзину.
Quant: Добавить 2 шт.? Остаток — 42 шт.
Клиент: Да, добавь.
Quant: Товар добавлен. Открыть корзину?

Без отдельного подтверждения endpoint корзины отклоняет операцию.

Архитектура

┌─────────────────────────────────────────────┐
│ Frontend: чат, карточки, сравнение, корзина  │
│ visual-demo.html + demo.js + styles.css     │
└──────────────────────┬──────────────────────┘
                       │ HTTP JSON API
┌──────────────────────▼──────────────────────┐
│ FastAPI: chat, catalog, cart, health         │
└───────────────┬──────────────────┬───────────┘
                │                  │
       ┌────────▼────────┐ ┌───────▼────────┐
       │ CatalogService  │ │ CartService    │
       │ товары, поиск,  │ │ сессии, сумма, │
       │ аналоги         │ │ подтверждение  │
       └────────┬────────┘ └───────┬────────┘
                └──────────┬───────┘
                           ▼
                  backend/data/products.json

Технологии

• Backend: Python 3.11+, FastAPI, Uvicorn, Pydantic.
• Frontend: HTML, CSS и vanilla JavaScript без сборщика.
• Данные: JSON-каталог для MVP.
• Хранение корзины: память процесса, разделённая по session_id.
• LLM: в текущем MVP внешний LLM не требуется; ответы формируются локальной логикой.

API

Проверка состояния

GET /api/health

{"status":"ok","service":"ekt-assistant"}

Чат

POST /api/chat
Content-Type: application/json

{
  "message": "Есть ли автомат ВА47-29 2P C16?",
  "session_id": "demo-session-001"
}

Ответ содержит session_id, текстовое message, найденные products, а для операции добавления — requires_confirmation и action.

Каталог

GET /api/products

Возвращает элементы каталога из backend/data/products.json.

Корзина

GET  /api/cart/{session_id}
POST /api/cart/confirm

Тело запроса подтверждения:

{
  "session_id": "demo-session-001",
  "sku": "EK-VA4729-C16",
  "quantity": 2
}

POST /api/cart/confirm возвращает ошибку, если пользователь не подтвердил добавление в чате, товар не найден или количество превышает остаток.

Быстрый запуск

Требуется Python 3.11+.

git clone https://github.com/BAITC-Hacks/hack-6bd29a3e-2qwants.git
cd hack-6bd29a3e-2qwants

python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install -r backend/requirements.txt

uvicorn app.main:app --app-dir backend --reload

После запуска:

• интерфейс: http://127.0.0.1:8000;
• Swagger UI: http://127.0.0.1:8000/docs;
• health check: http://127.0.0.1:8000/api/health.

Автономное демо

UI без backend можно открыть напрямую:

open frontend/visual-demo.html       # macOS

Демо показывает сценарий работы Quant, карточки товаров, сравнение, подтверждение количества, историю чатов, корзину в рамках текущей вкладки и режимы desktop/mobile. Все данные в нём синтетические; оформление реального заказа не выполняется.

Тесты

pip install -r backend/requirements-dev.txt
pytest backend/tests

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

Для быстрой проверки frontend-демо на macOS:

/System/Library/Frameworks/JavaScriptCore.framework/Versions/A/Helpers/jsc frontend/demo-smoke.js

Структура проекта

.
├── backend/
│   ├── app/
│   │   ├── main.py          # FastAPI endpoints
│   │   ├── catalog.py       # каталог, поиск и аналоги
│   │   ├── chat.py          # диалоговая логика и подтверждение
│   │   └── cart.py          # корзина MVP
│   ├── data/products.json   # синтетический каталог
│   ├── requirements.txt
│   └── tests/test_smoke.py
├── frontend/
│   ├── index.html            # входная страница
│   ├── visual-demo.html      # автономное визуальное демо
│   ├── demo.js               # логика демо без API
│   ├── demo-smoke.js         # smoke-проверка frontend
│   ├── styles.css            # адаптивные стили
│   └── quant-icon.png        # иконка Quant
├── docs/                     # концепция, архитектура и планы
└── .env.example              # настройки окружения

Ограничения MVP

• каталог и остатки не подключены к реальному API ekt.kz;
• корзина хранится в памяти и очищается после перезапуска backend;
• авторизация, база данных и реальное оформление заказа не подключены;
• автономное визуальное демо не отправляет запросы в backend;
• сертификаты и медиафайлы в демо являются тестовыми материалами;
• неизвестные характеристики не должны выдумываться — в таком случае ассистент запрашивает уточнение.

Документация

• Концепция продукта
• Техническая архитектура
• План проекта
• План frontend и логики
• Передача frontend на интеграцию с backend
• Чек-лист демо
• Референсы Kasper и ekt.kz

Следующий этап

1. Подключить реальный каталог, остатки и цены ekt.kz.
2. Перенести сессии и корзины из памяти в БД или кэш.
3. Добавить авторизацию, аудит действий и безопасное оформление заказа.
4. Подключить RAG по каталогу, сертификатам и правилам покупки.
5. Добавить казахский язык, эскалацию менеджеру и продуктовые метрики.