Multimodal STO Assistant

Telegram-бот для малого автосервиса / СТО, который принимает текст, голос, фото и PDF/документы, анализирует обращение через OpenAI и формирует:

• короткий ответ клиенту;
• структурированную заявку для администратора.

Проект собран как отдельное standalone-приложение в корне репозитория.

Какую задачу решает

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

Этот бот нужен, чтобы превратить мультимодальное обращение в понятный результат для двух сторон:

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

Что делает решение

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

Что получает бизнес на выходе

• меньше ручной рутины на первичном разборе обращений;
• более структурированные заявки от клиентов;
• единый intake-канал для типовых сервисных сценариев;
• базу для дальнейшего расширения в CRM, календарь или web-интерфейс.

Proof: sample intake flow

client message / voice / photo / PDF
  -> Telegram bot
  -> STT or vision analysis when needed
  -> fact extraction
  -> service classification
  -> ticket assembly
  -> safety cleanup and missing-data check
  -> short client reply + structured admin ticket

Proof: sample scenarios

1. Голосовое сообщение про плохой запуск и Check Engine

   • ожидаемый тип обращения: диагностика
   • missing data: марка, модель, год, VIN, удобное время визита

2. Фото поврежденного бампера после ДТП

   • ожидаемый тип обращения: кузовной ремонт
   • в ответе не обещается точная стоимость до осмотра

3. Фото VIN и запрос на тормозные колодки

   • ожидаемый тип обращения: подбор запчастей
   • бот уточняет оригинал или аналог

Что умеет MVP

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

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

.
|- main.py
|- config.py
|- openai_client.py
|- handlers/
|- services/
|- utils/
|- tests/
|- docs/
|- Dockerfile
|- compose.yml
|- .dockerignore
|- .env.example
\- requirements.txt

Переменные окружения

Скопируйте .env.example в .env и заполните:

• TELEGRAM_BOT_TOKEN
• OPENAI_API_KEY
• ADMIN_CHAT_ID

Опционально:

• OPENAI_API_BASE
• OPENAI_GPT_MODEL
• OPENAI_VISION_MODEL
• OPENAI_STT_MODEL
• OPENAI_TTS_MODEL
• OPENAI_TTS_VOICE
• LOG_LEVEL
• ENABLE_TTS

Локальный запуск

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

Docker-запуск

Требования:

• установлен Docker;
• установлен Docker Compose plugin;
• рядом с compose.yml есть заполненный .env.

Сборка и запуск:

docker build -t sto-as-bot .
docker compose up --build

Проверка статуса и логов:

docker compose ps
docker compose logs bot

Остановка:

docker compose down

Naming Convention Docker

• имя compose project: sto-as
• имя контейнера: sto-as-bot
• image tag: sto-as-bot

Все Docker-сущности, которые задаются проектом явно, должны начинаться с sto-as.

Полезные логи

При LOG_LEVEL=DEBUG полезно смотреть такие этапы:

• startup приложения: [main.main]
• валидация env: [config.validate_required_settings]
• STT / Vision / ticket / reply вызовы: [openai_client.*]
• orchestration intake: [intake_service.*]
• нормализация и safety: [safety_service.*]
• отправка клиенту и администратору: [handlers.*]

Smoke-сценарии

1. Голос: клиент говорит, что машина плохо заводится и горит Check Engine.
2. Фото повреждения: клиент отправляет фото бампера после ДТП.
3. VIN + запчасти: клиент отправляет фото VIN и пишет про тормозные колодки.
4. Текст: клиент просит записать на мойку или диагностику.

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

• без БД;
• без CRM;
• без календаря и оплат;
• без web-интерфейса;
• TTS опционален и включается только через ENABLE_TTS=true.