NEXIS / ChipAI — ИИ-консультант для ekt.kz

HackAlem AI 2026 · команда NEXIS · кейс №1 ТОО «Электрокомплект»

Чат для подбора электротехнической продукции: от вопроса о товаре или загруженной спецификации до списка закупки, подтверждённого покупателем.

Репозиторий · Архитектура · API-контракт · Реализация v3

1. Какую проблему решает проект

Частному покупателю или закупщику компании нужны характеристики, сертификаты, остатки по складам, аналоги и условия покупки. Обычно эти вопросы требуют обращения к менеджеру и замедляют выбор товара.

ChipAI объединяет консультацию и подготовку списка закупки в одном окне. Покупатель получает данные каталога и объяснение рекомендаций, а менеджер может сосредоточиться на сложных запросах. Снижение времени консультации и нагрузки на менеджеров — цель проекта; эти бизнес-показатели пока не измерялись.

Текущий результат: работающий frontend и backend с живым каталогом ekt.kz, обработкой документов и сохраняемой демонстрационной корзиной. Передача заказа в реальную корзину ekt.kz требует отдельного API партнёра.

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

Возможность	Что получает пользователь
Поиск товара	Поиск по ID, артикулу, штрихкоду, названию и электрическим параметрам; нормализация обозначений вроде 3х2,5 / 3×2.5; постоянный поисковый индекс
Карточка товара	Цена, артикул, характеристики, остатки по складам, время проверки, ссылка на товар и сертификат, если он есть в API
Контроль качества данных	Неизвестные значения остаются неизвестными; противоречия характеристик показываются предупреждением
Аналоги	Подбор по известным техническим параметрам, проверка наличия и краткое объяснение совпадений
База знаний	Условия покупки, технические объяснения и вопросы для уточнения подбора; 53 материала на RU/KK/EN со ссылками и статусами проверки
Продолжение диалога	Уточнения «нужно пять», «а в Алматы?», «подешевле», «второй вариант»; контекст кандидатов, параметров, количества, города и бюджета
Спецификации и изображения	PDF, TXT, DOCX, XLSX, XLS, JPEG, PNG, WEBP; найденные и неизвестные строки, количество и полная либо частичная смета
Подтверждаемая корзина	Добавление, изменение количества и удаление только после отдельного согласия; проверка цены, остатка и кратности
Сохранение результата	Корзина в SQLite, ссылка на её актуальное состояние; CSV-экспорт через API
Интерфейс	Чат, карточки, статусы выполненных действий, выбор количества, маскот ChipAI и панель корзины
Языки	Русские, казахские и английские ответы, подписи характеристик, ошибки, сметы и подтверждения; исходные названия товаров сохраняются

Быстрые вопросы отправляются в backend. Ошибки API не подменяются синтетическими ответами. Фоновая витрина интерфейса иллюстративная и подписана; её цены и товары не используются в консультации.

3. Как работает решение

1. Пользователь открывает чат и вводит вопрос, артикул или прикрепляет спецификацию.
2. Frontend получает анонимную серверную сессию и отправляет запрос в FastAPI.
3. Агент определяет сценарий: поиск, уточнение параметров, наличие в городе, аналог или условия покупки. Файлы проходят серверный разбор.
4. Backend запрашивает каталог и возвращает ответ, структурированные карточки, источники и статусы выполненных действий.
5. Для выбранного товара и количества сервер создаёт предложение. Пользователь видит название, цену, количество и предупреждения.
6. Только после явного подтверждения сервер повторно проверяет данные и меняет корзину. Токен предложения одноразовый и связан с сессией, товаром, количеством и ценой.
7. Пользователь открывает актуальную сохранённую корзину по ссылке.

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

4. Технологии и AI

Компонент	Технологии
Backend	Python, FastAPI, Uvicorn, Pydantic
Frontend	TypeScript, Vite 8, HTML/CSS, Tailwind CSS 4; React 19 используется для маскота ChipAI
AI-инструменты	OpenAI Python SDK, Function Calling; модель по умолчанию в конфигурации — gpt-4o-mini
Каталог	HTTPS API ekt.kz с Basic Auth, клиент на Requests, кеш с TTL
Хранение и поиск	SQLite: корзины, сессии, индекс знаний и отдельный индекс каталога; лексический и необязательный гибридный поиск
Документы	PyMuPDF, python-docx, openpyxl, xlrd
OCR	Tesseract, pytesseract, Pillow; языки rus, kaz и eng включены в Docker
Запуск	Docker Compose, nginx; общий Python launcher для локальной разработки
Проверки	Python unittest, FastAPI TestClient, Node.js test runner, TypeScript typecheck

Как устроен агент

В проекте один AgentService. В версии v3 маршрутизация запроса, контекст выбора, исполнение инструментов и сборка ответа разделены на небольшие модули. Агент различает вопросы об устройстве товара, условиях магазина и выборе конкретной позиции; может обрабатывать несколько намерений в одном запросе.

Модели доступны пять инструментов чтения: search_products, get_product_detail, find_analogs, query_knowledge_base и check_city_stock. Фактический ответ о товаре собирается сервером из полученных данных. Изменение корзины выполняется отдельным сервисом после проверки согласия.

Поиск товаров использует точные идентификаторы, лексическое ранжирование и фильтры электрических параметров. База знаний содержит 53 материала и 159 языковых фрагментов на русском, казахском и английском. Индекс SQLite хранит версии, хеши содержания, источники и статусы проверки. Лексический поиск работает без ключа модели; необязательные embeddings добавляют поиск по смыслу и объединение результатов. Отдельный сервер векторной базы не нужен.

Без OPENAI_API_KEY работают программные правила, лексический поиск знаний и тот же живой каталог. При настроенном ключе подключается модель; OPENAI_MODEL позволяет изменить её имя. Поддержка embeddings включается отдельно. В текущей проверенной конфигурации ключ отсутствовал: реальные вызовы модели и платные embeddings не выполнялись. Неподтверждённый модельный текст не используется как источник цен и наличия; пояснения собираются из найденных материалов.

Ответ содержит язык, request_id, источники, уточняющий вопрос при необходимости и диагностику режима/времени обработки. Статусы reasoning_steps показывают действия инструментов, а не внутренние рассуждения модели. Подробнее: корпус и происхождение материалов, реализация v3.

5. Архитектура проекта

flowchart TD
    UI["Браузер: чат и корзина"] -->|"HTTP /api, через nginx в Docker"| API["FastAPI"]
    API --> Agent["AgentService: сценарии и контекст"]
    Agent --> Catalog["EktClient: поиск и кеш"]
    Catalog --> CatalogDB["SQLite: индекс каталога"]
    Catalog -->|"HTTPS GET + Basic Auth"| EKT["Каталог ekt.kz"]
    Agent --> KB["SQLite: 53 материала RU/KK/EN"]
    KB -->|"Необязательные embeddings"| LLM["OpenAI API"]
    Agent -->|"Необязательный Function Calling"| LLM["OpenAI API"]
    API --> Cart["CartService: предложение и подтверждение"]
    Agent --> Cart
    Cart --> DB["SQLite"]
    API --> Parser["Разбор спецификации"]
    Parser --> Catalog
    Parser --> OCR["Tesseract OCR"]

Файл или каталог	Назначение
frontend/src/main.ts, frontend/src/chat/	Чат, API-клиент, карточки, загрузка и подтверждения
backend/main.py	HTTP API, валидация, CORS, лимиты и обработка ошибок
backend/agent_service.py, backend/agent/	Оркестрация, маршрутизация, состояние, инструменты и сборка ответа
backend/dialogue_context.py	Ограниченный контекст выбора в RAM, без полной истории
backend/localization.py	Языки RU/KK/EN для API, корзины, сметы и ошибок
backend/ekt_client.py	Данные ekt.kz, кеш, поиск и аналоги
backend/cart_service.py	SQLite, предложения, подтверждения и ссылки корзины
backend/spec_parser.py	Извлечение текста, OCR и сопоставление строк
backend/knowledge_base.py, backend/retrieval/	Индексы знаний и каталога, поиск и метаданные источников
database/knowledge/articles.json	Редактируемый корпус из 53 материалов на трёх языках
backend/scripts/index_knowledge.py, backend/scripts/import_catalog.py	Индексация знаний и возобновляемый импорт каталога
backend/evals/	72 локальных сценария разработки и регрессий
backend/tests/, frontend/tests/	Автоматические проверки
compose.yaml	Общий запуск двух контейнеров и постоянного хранилища

API v3 сохраняет /api/session, /api/agent/chat, /api/agent/upload-spec, /api/cart/offer, /api/cart/add, /api/cart/change-offer, /api/cart/change и /api/cart. Добавлены языковые поля и диагностика источников; схемы, ошибки и остальные маршруты описаны в контракте и Swagger.

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

Вариант A — Docker, включая OCR

Нужны Git, Docker с Compose и доступ в интернет. На Windows используется Docker Desktop в режиме Linux containers. Все дальнейшие команды выполняются из корня проекта.

1. Получите код:

git clone https://github.com/BAITC-Hacks/hack-80299a21-nexis.git
cd hack-80299a21-nexis

2. Создайте .env из шаблона, сохранив уже настроенный файл.

PowerShell:

if (!(Test-Path -LiteralPath .env)) { Copy-Item .env.example .env }

Linux/macOS:

test -f .env || cp .env.example .env

3. Заполните настройки в .env:

Переменная	Значение
EKT_API_BASE	https://ekt.kz/api — уже указано в шаблоне
EKT_API_USER, EKT_API_PASS	Учётные данные API, предоставленные организаторами или партнёром; обязательны для живого каталога
OPENAI_API_KEY	Необязательно: оставьте пустым для запуска по правилам
OPENAI_MODEL	gpt-4o-mini по умолчанию; используется при включённой модели
EKT_CATALOG_PAGES	4 по умолчанию; начальная выборка страниц при пустом постоянном индексе
NEXIS_EMBEDDINGS_ENABLED	false по умолчанию; true разрешает поиск с готовыми embeddings и запросы векторизации вопросов
NEXIS_EMBEDDING_MODEL	text-embedding-3-small по умолчанию; должна совпадать с моделью построенного индекса
NEXIS_PUBLIC_URL	Необязательно для Docker: публичный адрес frontend при размещении; локально используется http://localhost:5173

Секреты остаются в .env на backend. Этот файл исключён из Git; во frontend их передавать не нужно. Полный список настроек находится в .env.example.

4. Соберите и запустите приложение:

docker compose up --build -d
docker compose ps

Адрес	Назначение
http://localhost:5173	Приложение с чатом
http://localhost:8000/docs	Swagger API
http://localhost:5173/api/health	Состояние сервиса и конфигурация возможностей

Первый запуск загружает образы и зависимости. Backend должен перейти в состояние healthy. Health показывает конфигурацию; успешный доступ к каталогу проверяется запросом товара.

5. Логи и остановка:

docker compose logs --tail=100 backend frontend
docker compose down

Обычная остановка сохраняет SQLite в именованном Docker volume. Порты 5173 и 8000 должны быть свободны. Если каталог недоступен, проверьте настройки API и сообщение об ошибке в чате. Подробнее: Docker и OCR.

Вариант B — локальная разработка без Docker

Проверенное окружение: Windows, Python 3.14 и Node.js 24 с npm. Получите репозиторий и заполните .env по шагам выше.

Первый запуск устанавливает зависимости и запускает оба сервера:

python backend/scripts/dev.py --install

Повторный запуск:

python backend/scripts/dev.py

Приложение доступно на localhost:5173, API — на localhost:8000. Для других портов:

python backend/scripts/dev.py --api-port 8002 --ui-port 5174

Launcher согласует API-адрес и CORS; остановка — Ctrl+C. Для фото и сканов в нативном режиме отдельно установите Tesseract с языками rus/eng/kaz и при необходимости задайте TESSERACT_CMD. Текстовые PDF, Word, Excel и TXT не требуют OCR.

Индексы знаний и каталога

Корпус входит в репозиторий и backend-образ. Его лексический индекс создаётся автоматически при первом обращении; подготовить его явно без сетевых запросов можно так:

docker compose run --rm --no-deps backend python backend/scripts/index_knowledge.py

Для расширения каталога выполните ограниченный импорт. Повтор команды продолжает с сохранённой страницы; --restart начинает новое обновление:

docker compose run --rm --no-deps backend python backend/scripts/import_catalog.py --max-pages 100

Нужны учётные данные ekt.kz. Импорт выполняет GET-запросы, а не записывает товары партнёру. В текущих локальном и Docker-прогонах загружены 11 страниц / 220 товаров, следующая страница — 12; это не полный каталог. В Docker индекс сохраняется на постоянном volume. Эти SQLite-данные не входят в Git или образ: новая установка формирует собственный индекс. Статус и охват доступны в /api/health.

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

docker compose run --rm --no-deps backend python backend/scripts/index_knowledge.py --embeddings

После построения укажите NEXIS_EMBEDDINGS_ENABLED=true в .env и пересоздайте backend через docker compose up -d backend. Без ключа, готовых векторов или при ошибке используется лексический поиск; фактический режим и причина перехода возвращаются в метаданных. Для нативного режима используйте те же скрипты через Python из .venv. Подробности — в инструкции корпуса.

7. Как проверить решение жюри

Сценарий на 5–7 минут

Начните с пустой демонстрационной корзины. Каталог живой: цены и остатки могут измениться, поэтому сравнивайте ответ с текущей карточкой, а не с фиксированными числами в примере.

Шаг	Действие	Ожидаемый результат
1	Откройте приложение → ChipAI → быстрый вопрос «Товар 515291»	Реальная карточка, характеристики и остатки. Если сохраняется расхождение тока 160/250 А в API, оно показано предупреждением
2	Напишите «А в Алматы?»	Ответ про склады города для выбранного товара; корзина не меняется
3	Нажмите «Проверить и добавить» у доступного товара	Отдельное окно с товаром, количеством, свежей ценой и предупреждениями
4	Нажмите «Отмена»	Корзина остаётся пустой
5	Повторите выбор и нажмите «Да, подтверждаю»	Товар появляется в серверной корзине; количество не превышает остаток
6	Откройте корзину, измените количество и подтвердите действие	Новое количество записывается после согласия; ссылка открывает актуальное состояние
7	Перезагрузите страницу	Корзина восстанавливается из серверного хранилища
8	Загрузите docs/sample_specification.pdf или docs/sample_specification.txt	Артикул 200300285_ найден с количеством 2; неизвестная строка показана отдельно; смета неполная, корзина не меняется
9	Спросите «Какие условия оплаты и доставки?»	Содержательный ответ со ссылками на источники
10	Переключите язык на KZ и повторите вопрос об условиях	Казахский ответ без ошибки несовместимого кода языка
11	Переключите язык на EN и спросите «What is the difference between an RCD and an RCBO?»	Английское объяснение из базы знаний со ссылками на источники

Если товар 515291 недоступен, выберите другую доступную карточку для шагов с корзиной. Конфликт характеристик требует уточнения у менеджера; этот сценарий проверяет локальную демо-корзину и не оформляет покупку.

Текстовое подтверждение. Откройте приложение в приватном окне браузера с новой сессией. До выбора города отправьте «Артикул 030300435_, нужно 2 шт». Этот артикул использовался в браузерной приёмке. Если текущий остаток достаточен и нет предупреждений, агент предложит добавление. Ответьте «Да, добавь»: добавятся 2 штуки. Повторное «Да, добавь» без нового предложения не должно добавить их ещё раз. При изменении данных каталога используйте другой доступный товар без противоречий.

Отсутствующий товар и аналоги. Запросите позицию с нулевым текущим остатком. Агент проверяет технически подходящие альтернативы и объясняет совпадения. Если в доступной выборке подходящих вариантов нет, он сообщает об этом.

Уточнения v3. После нескольких найденных карточек выберите «второй вариант», затем спросите его характеристики или наличие в городе. Для широкого запроса «Нужен автомат» ожидается уточнение необходимых параметров. Объясняющий вопрос «Чем УЗО отличается от дифавтомата?» должен обращаться к базе знаний, а не подменяться случайной карточкой.

Автоматические проверки

Backend в Docker, без запросов к живому каталогу:

docker compose run --rm --no-deps backend python -m unittest discover -s backend/tests -p "test_*.py" -v

Локальный набор оценки агента на 72 сценариях: 24 задачи на трёх языках. Сеть, реальная LLM и embeddings в этом запуске отключены; каталог и хранилища изолированы:

docker compose run --rm --no-deps backend python -m backend.evals.run

Это набор разработки и регрессий, а не независимая оценка реальной модели или задержки живого API. Условия запуска и состав — в backend/evals/README.md.

Настоящий OCR на сгенерированном тестовом изображении:

docker compose run --rm --no-deps backend python backend/scripts/doctor.py --require-ocr --ocr-smoke

Живой API и изолированная временная демо-корзина; требуются действующие EKT credentials:

docker compose run --rm --no-deps backend python backend/scripts/smoke_live.py

Frontend, при установленном Node.js 24:

cd frontend
npm ci
npm run typecheck
npm test
npm run build
cd ..

Подтверждённая приёмка v3, 23 сентября 2026:

Проверка	Результат
Backend	160 тестов прошли на Windows и Linux в Docker
Frontend	44 теста прошли, включая ссылки корзины при смене языка; TypeScript и production-сборка успешны
Диалоги	72 сценария × 2 запуска = 144 успешных прогона, по 48 на RU/KK/EN
Поиск знаний	30/30 Top-1 и Recall@5, по 10 вопросов на язык
OCR в Docker	Реальное распознавание тестового изображения прошло; установлены rus/kaz/eng

Диалоги и retrieval проверены на наборах разработки и регрессий; это не независимая оценка реальной LLM. В браузере проверены ответы базы знаний и источники на RU/KK/EN, живая карточка 515291 и уточнение характеристик, отмена и подтверждённое добавление 2 штук, PDF с одной найденной и одной неизвестной строкой, восстановление корзины после перезапуска контейнера и её HTML-страница на казахском. Подробности текущей приёмки — в журнале v3; результаты предыдущей версии сохранены в историческом аудите.

8. Данные и интеграции

• Каталог партнёра: HTTPS GET https://ekt.kz/api/products, пагинация ?page=2 и карточка https://ekt.kz/api/products/detail?id=515291. Авторизация Basic Auth выполняется только backend.
• Данные товара: ID, артикул, название, цена, количество, склады, свойства, изображения, ссылки и документы, если они присутствуют в ответе API.
• Свежесть: страницы кешируются на 300 секунд, детали — на 30 секунд по умолчанию. Перед добавлением или изменением положительного количества цена и остаток проверяются заново.
• База знаний: 53 редакционных материала на RU/KK/EN со ссылками на ekt.kz, ABB и Schneider Electric; 159 фрагментов текущего индекса. Источник, версия, дата и статус проверки возвращаются вместе с результатом. Условия, требующие менеджера, и редакционные инженерные памятки выделены отдельными статусами; дата проверки не означает бессрочную гарантию. Происхождение корпуса.
• OpenAI: необязательная внешняя интеграция для выбора инструментов. При её включении ограниченная история и результаты инструментов передаются модели; загруженные документы ей не отправляются.
• Хранение: отдельные SQLite сохраняют корзины, индекс каталога и индекс знаний. Краткий контекст выбора хранится в RAM до 30 минут, максимум для 1024 сессий: выбранный товар, кандидаты, параметры, количество, город, бюджет, язык и ожидаемое уточнение. После перезапуска этот контекст теряется.
• Демонстрационные данные: синтетический транспорт используется в автотестах. Примеры PDF/TXT содержат один реальный артикул и одну намеренно неизвестную строку. Приложение не сохраняет загруженные файлы; временный multipart-файл закрывается после обработки.

Решение не запрашивает платёжные реквизиты. История чата не сохраняется в БД. Ссылки корзины имеют временный токен чтения.

9. Ограничения текущей версии

1. Корзина демонстрационная. API партнёра предоставляет только чтение каталога. Товар не резервируется, заказ и оплата на ekt.kz не создаются. Нужны официальный API корзины и привязка к покупателю.
2. Каталог покрыт частично. Возобновляемый CLI умеет пройти все страницы, но текущий импорт — 220 товаров, не полный магазин. Только успешное достижение пустой страницы завершает снимок. Поиск использует постоянный индекс и уже загруженные страницы; при пустом индексе загружается выборка EKT_CATALOG_PAGES; прямой запрос ID доступен за её пределами. Индекс не служит источником актуальных цен и остатков.
3. Аналоги зависят от качества данных. Проверяются поддерживаемые семейства и известные параметры. Нельзя гарантировать подходящий аналог при неполных характеристиках или вне выборки.
4. OCR распознаёт читаемую маркировку. Определение точной модели по внешнему виду без текста не реализовано. Двоичный Word .doc нужно преобразовать в .docx.
5. Есть ограничения файлов: до 15 МиБ на файл, до 250 товарных строк; дополнительные ограничения страниц, архивов и изображений описаны в API-контракте.
6. Количество целочисленное. Дробный метраж кабеля требует расширения контракта единиц измерения.
7. Качество языков требует дальнейшей проверки. RU/KK/EN поддерживаются в ответах и сервисных сценариях. Казахский корпус требует вычитки носителем языка. Названия, бренды и значения свойств из API сохраняются как данные поставщика; это не обещание перевода каждой исходной строки.
8. Нет CRM и авторизации покупателя сайта. Вместо фиктивной заявки возвращаются официальные контакты. Есть анонимные сессии, но нет истории для авторизованных покупателей.
9. Прототип ещё требует эксплуатационной проверки. Реальная модель OpenAI, embeddings, нагрузка и SLA не проверены. 72 офлайн-сценария — набор разработки. Контекст диалога, оперативный кеш и лимитер локальны процессу; несколько воркеров требуют общего состояния. Потоковой выдачи ответа нет.
10. Проверка устройств неполная. Адаптивная вёрстка сохранена и desktop осмотрен; отдельная приёмка на настоящем телефоне остаётся в плане.

Следующие улучшения и внешние зависимости перечислены в плане развития агента и журнале реализации v3.

10. Deployed-версия и полезные ссылки

Публичная deployed-ссылка для текущей версии в репозитории не указана. Проверенная версия запускается локально: http://localhost:5173. Этот адрес доступен на компьютере, где запущен проект.

Для публичного размещения понадобятся HTTPS, публичный домен, настройки NEXIS_PUBLIC_URL/CORS и постоянное хранилище. Локальный Compose публикует порты только на 127.0.0.1; размещение на самом ekt.kz пока не выполнено.

• README backend
• README frontend
• API-контракт v3
• Архитектура
• Инструкция Docker и OCR
• Руководство интеграции
• Пример спецификации PDF
• Пример спецификации TXT
• Аудит frontend/backend
• План дальнейшего развития
• Реализация агента v3
• Корпус знаний и индексы
• Набор оценки агента