EKT AI Assistant

Рабочий MVP ИИ-консультанта для ekt.kz. Он использует реальный API каталога, показывает актуальные цены и остатки, ищет аналоги, разбирает вложения и изменяет демонстрационную корзину только после явного подтверждения.

Главная демонстрационная функция — Procurement Control Tower / Spec to Cart. Пользователь загружает PDF, DOCX, XLSX или фотографию спецификации, после чего система:

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

Архитектура

Browser chat
    │
    ▼
FastAPI ── OpenAI Responses API
    ├──── EKT catalog API (Basic Auth, read only)
    ├──── file extraction (PDF, DOCX, XLSX, images)
    ├──── purchase terms JSON
    └──── two-phase cart adapter
              prepare → explicit confirmation → commit

Specification → extraction → confidence gate → live stock → warehouse plan → reviewed cart

ИИ отвечает за понимание естественного языка и формулировку ответа. Цена, остаток, свойства и рекомендации всегда приходят из backend-инструментов. Корзина защищена серверной проверкой; prompt не является единственной линией защиты.

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

Требуется Python 3.11 или новее.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

В .env задайте OPENAI_API_KEY. Доступ к каталогу уже настроен локально, а файл .env исключён из Git.

uvicorn app.main:app --reload --port 8000

Откройте http://localhost:8000. API-документация: http://localhost:8000/docs.

Без OPENAI_API_KEY приложение работает в ограниченном режиме: поиск товара по тексту/ID, карточка товара и условия покупки. Для естественного диалога, изображений и вызова инструментов нужен ключ.

Как устроен запрос

1. Браузер отправляет сообщение и идентификатор сессии в POST /api/chat.
2. Модель выбирает строго описанный инструмент: поиск, detail, аналоги, условия или подготовку корзины.
3. Backend вызывает ekt.kz и возвращает модели JSON.
4. Модель формирует ответ только из полученных данных.
5. prepare_cart проверяет остаток и создаёт временную операцию на 10 минут, но не меняет корзину.
6. Кнопка вызывает отдельный POST /api/cart/confirm; backend повторно проверяет остаток и идемпотентно фиксирует изменение.

Spec to Cart API

• POST /api/spec/analyze — multipart-загрузка спецификации и полный procurement-анализ.
• POST /api/spec/prepare-cart — подготовка выбранных безопасных строк к подтверждению.

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

Подключение реальной корзины ekt.kz

Сейчас используется DemoCartService с хранением в памяти процесса, поскольку предоставлены только read-only endpoints каталога. После получения API корзины:

1. Создайте EktCartService с методами prepare, commit и get_cart.
2. В commit используйте серверную авторизацию пользователя или безопасный cart token — не Basic Auth каталога в браузере.
3. Перед фактическим запросом ещё раз получите detail товара и проверьте остаток.
4. Передавайте idempotency key, равный pending_id.
5. Верните настоящий URL корзины в cart_url.
6. Замените создание DemoCartService в app/main.py.

Для production временные операции и корзины следует хранить в Redis/PostgreSQL.

Данные и безопасность

• Учётные данные ekt.kz находятся только в .env, исключённом из Git.
• Frontend никогда не получает Basic Auth.
• OpenAI вызывается с store=False.
• Платёжные данные не запрашиваются и не хранятся.
• Файлы ограничены по размеру и не сохраняются на диск.
• Условия в data/purchase_terms.json пока демонстрационные и требуют подтверждения партнёра.

Для production добавьте авторизацию, rate limiting, антивирусную проверку файлов, Redis, аудит действий и очистку логов.

Тесты

pytest -q

Тесты проверяют явное подтверждение, идемпотентность commit и запрет количества выше остатка.

Структура

app/main.py                    HTTP endpoints
app/services/assistant.py      OpenAI tools and safety prompt
app/services/ekt_client.py     catalog adapter and analog search
app/services/cart.py           two-phase safe cart
app/services/files.py          PDF, DOCX, XLSX and image handling
app/static/                    responsive chat and cart UI
data/purchase_terms.json       editable purchase conditions
tests/                         safety tests

Что ещё запросить у партнёра

• API создания/чтения корзины и способ связать её с web-сессией.
• Официальные условия оплаты, доставки и минимальной партии.
• Серверный поиск каталога, если он поддерживается.
• Источник сертификатов или отдельное поле/endpoint.
• Правила, какие склады считать доступными для онлайн-заказа.