# AI Avatar Platform (Golova) — Техническое задание

**Статус:** Production-ready, в продакшене
**Production:** https://golova.wpmix.net
**Admin:** https://golova.wpmix.net/admin
**Demo виджет:** https://golova.wpmix.net/widget/?tenant=19b71055-9724-4fde-b854-f3bfb1514b3c
**Demo на сайте:** https://demo-qr.wpmix.net

---

## 1. Описание продукта

**Golova (Avatrix)** — B2B SaaS платформа для создания AI-ассистентов с видео-аватарами, встраиваемых на любой сайт через iframe-виджет или embed-скрипт. Компании загружают PDF-документы или текст, настраивают аватара через админ-панель, и виджет отвечает на вопросы **строго по загруженным документам** с цитированием источников (anti-hallucination).

### Ключевые характеристики

- **Мультитенантность** — каждый клиент (тенант) имеет изолированную базу знаний, свой аватар, свои API-ключи
- **Два режима общения** — текстовый чат (REST API) и голосовой чат (WebRTC, ~0.5с задержки)
- **RAG (Retrieval Augmented Generation)** — семантический поиск по чанкам через embeddings
- **OCR** — загрузка PDF с автоматическим распознаванием текста
- **Anti-hallucination** — LLM обязан цитировать источник; без источника отвечает "не знаю"
- **Embed на любой сайт** — один тег `<script>`, lazy loading, работает на любом домене
- **495 backend тестов** (Vitest), полный CI/CD

---

## 2. Роли пользователей

### Конечный пользователь (анонимный)
- Открывает виджет на стороннем сайте (через `<script src="embed.js">` или прямой iframe)
- Ведёт текстовый или голосовой диалог с аватаром
- Оценивает ответы (thumbs up/down с комментарием)
- Не требует авторизации

### Admin (tenant-admin)
- Управляет одним тенантом (своей компанией)
- Загружает документы в базу знаний (PDF, текст, Google Docs URL)
- Настраивает аватара (имя, пол, роль, стиль, кастомный промпт)
- Просматривает диалоги и аналитику
- Не видит других тенантов

### Superadmin
- Создаёт и удаляет тенантов
- Видит всех тенантов, управляет любым
- Управляет шаблонами аватаров
- Все права admin + создание tenant-admin аккаунтов

---

## 3. Функциональные модули

### 3.1. Embed-виджет
- `embed.js` — лоадер: один `<script>` тег на сайте клиента
- Vanilla JS/HTML iframe (~50KB, без фреймворков)
- Lazy loading — загружается только при первом клике
- Конфигурация: `window.GolovaConfig = { tenant, color, position }`
- Видео-аватар (MP4, два состояния: `talking` / `silent`)
- Кнопки переключения текст/голос
- CSP настроен: встройка на любой домен

### 3.2. Текстовый чат
- REST API с историей сессий
- Промпт строится модульно: идентификация аватара → правила anti-hallucination → кастомный промпт → база знаний
- Флаг `flagged: true` — потенциальная галлюцинация (LLM не указал источник)
- Подсчёт токенов и стоимости в каждом ответе

### 3.3. Голосовой чат

**Режим 1: OpenAI Realtime (по умолчанию)**
- WebRTC SDP-обмен через OpenAI Realtime API
- Задержка ~0.5 с
- Транскрипт записывается в реальном времени

**Режим 2: Open-Source pipeline**
- WebSocket соединение
- Pipeline: ASR (Whisper-large-v3 через Together AI) → LLM → TTS (OpenAI / MiniMax)
- VAD: silence detection с настраиваемым таймаутом
- Idle promo: озвучивание промо-текста при бездействии пользователя

### 3.4. База знаний
- Три источника: PDF (с автоматическим OCR), прямой текст, публичный Google Doc URL
- OCR pipeline: PDF → Z.AI GLM-5 API → Markdown
- Авто-индексация после OCR
- Кастомный текст KB (`_custom.md`)
- Восстановление застрявших документов при рестарте сервера

### 3.5. RAG (Векторный поиск)
- Модель: OpenAI `text-embedding-3-small`
- Чанкер: разбивка по параграфам, максимум 1024 токена, overlap 20%
- Поиск: cosine similarity (in-memory)
- Кэш векторов per-tenant с автоинвалидацией
- Режимы: `auto` (авто-переключение при большой KB), `always`, `disabled`
- ragTopK: 3–20 чанков (по умолчанию 5)

### 3.6. LLM Router
Поддерживаемые провайдеры (настраиваемые per-tenant):
- **OpenAI** — GPT-4o, GPT-4.1, GPT-5.4-mini
- **Google Gemini** — Gemini 2.5 Pro
- **OpenAI-compatible** — любой совместимый endpoint (HuggingFace, Groq, DeepInfra)
- **Groq** — через openai-compatible адаптер

Приоритет API-ключа: per-tenant ключ → глобальная env-переменная.

### 3.7. Диалоги и аналитика
- Сохранение всех сессий с сообщениями, токенами, стоимостью
- Фидбэк: rating (up/down), comment (обязателен при down)
- Admin: список диалогов с пагинацией, просмотр полной сессии
- Статистика: количество диалогов, сообщений, токенов, стоимость

### 3.8. Бенчмарки (LLM-as-judge)
- Набор вопросов с эталонными ответами
- LLM отвечает → другой LLM оценивает качество
- Оценки: correct / incorrect / partial
- Метрики: hallucinations, avgLatencyMs, totalCost, scorePercent

### 3.9. Шаблоны аватаров
- Superadmin создаёт шаблоны с видео (talking + silent MP4)
- Любой admin может применить шаблон к своему тенанту одним кликом
- MP4 валидация (проверка ftyp/moov/mdat box)

---

## 4. Админ-панель (React SPA)

| Страница | Описание |
|----------|----------|
| Login | Вход по email/password |
| Клиенты (Tenants) | Список тенантов, создание, удаление (superadmin) |
| База знаний | Загрузка PDF/текст/URL, статус OCR/векторизации, просмотр документов |
| Настройки | Имя тенанта, видео аватара, шаблоны, учётные данные, брендинг, языки |
| Диалоги | Просмотр всех диалогов с фильтрацией |
| Аналитика | Статистика: диалоги, сообщения, токены, стоимость |
| Бенчмарки | Управление бенчмарками, запуск, результаты |
| AI-провайдеры | LLM, TTS, ASR, OCR — ключи, модели, тестирование |
| Вставить на сайт | Готовый код для embed |
| Шаблоны аватаров | Управление шаблонами (superadmin) |

---

## 5. API-эндпоинты

### Публичные (без авторизации)

| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/api/health` | Health check |
| GET | `/api/widget/config?tenant=ID` | Конфиг тенанта для виджета |
| POST | `/api/chat` | Текстовый чат |
| GET | `/api/chat/:sessionId` | История диалога |
| POST | `/api/chat/:sessionId/feedback` | Оценка сообщения |
| POST | `/api/realtime?tenant=ID` | WebRTC SDP-обмен |
| GET | `/api/tenants/:id/avatar/:type` | Видео аватара (talking/silent) |
| GET | `/api/models` | Каталог моделей с ценами |

### Admin API (авторизация)

| Метод | Путь | Описание |
|-------|------|----------|
| POST | `/api/tenants` | Создать тенанта (superadmin) |
| GET/PUT/DELETE | `/api/tenants/:id` | CRUD тенанта |
| POST | `/api/tenants/:id/documents` | Загрузить PDF (async OCR) |
| POST | `/api/tenants/:id/documents/from-text` | Документ из текста |
| POST | `/api/tenants/:id/documents/from-url` | Из Google Doc URL |
| GET | `/api/tenants/:id/documents` | Список документов |
| POST | `/api/tenants/:id/documents/:docId/index` | Запуск RAG-индексации |
| GET | `/api/tenants/:id/dialogs` | Список диалогов |
| GET | `/api/tenants/:id/feedback` | Сообщения с оценками |
| POST | `/api/tenants/:id/benchmarks` | Создать бенчмарк |
| POST | `/api/tenants/:id/benchmarks/:id/run` | Запустить бенчмарк |

---

## 6. Интеграции

| Сервис | Назначение |
|--------|------------|
| OpenAI API | LLM (GPT-4o/4.1/5), Embeddings, TTS, Realtime WebRTC |
| Google Gemini | LLM (Gemini 2.5 Pro) |
| Z.AI (GLM-5) | OCR PDF-документов |
| Together AI | ASR (Whisper-large-v3) |
| MiniMax | TTS через WebSocket стриминг |
| Groq | LLM/ASR через openai-compatible |
| Google Docs | Импорт документов по публичному URL |
| poppler-utils | Системная утилита: pdfinfo, pdftoppm |

---

## 7. Техстек

| Слой | Технология |
|------|-----------|
| Backend | Node.js, Express, TypeScript |
| Frontend (Admin) | React, TypeScript, CSS |
| Widget | Vanilla JS/HTML (~50KB) |
| Хранилище | Файловая система (JSON + Markdown, без БД) |
| Тесты | Vitest (495 тестов), GitHub Actions CI |
| Деплой | PM2, nginx |
| Безопасность | CORS, CSRF (Origin/Referer), SSRF protection, CSP, bcrypt, prototype pollution guard |

---

## 8. Нетривиальные решения

1. **Файловая система вместо БД** — JSON + Markdown файлы, без SQL/NoSQL
2. **Векторный поиск без векторной БД** — cosine similarity in-memory
3. **Anti-hallucination промптов** — строгий порядок секций, кастомный промпт ПОСЛЕ правил
4. **RAG Auto-mode** — если KB > 80% контекст-окна → RAG, иначе full-context
5. **OCR с очередью** — последовательная обработка per-tenant, восстановление при рестарте
6. **Двухрежимный голос** — OpenAI Realtime (WebRTC) vs open-source pipeline (ASR→LLM→TTS)
7. **Lazy-loading виджета** — iframe создаётся только при клике

---

## 9. Объём работ

| Модуль | Объём | Тестов |
|--------|-------|--------|
| Backend (TypeScript) | ~8000 строк | 495 |
| Admin (React SPA) | ~17000 строк | — |
| Widget (Vanilla JS) | ~50KB | E2E |

**Время разработки:** 4–6 недель (MVP production-ready)

---

## 10. Ограничения

- Векторный поиск in-memory: при 1000+ документах потребляет больше RAM
- Файловое хранилище: не подходит для multi-instance деплоя (горизонтальное масштабирование)
- Видео-аватар: статичный MP4, загружается вручную (без генерации)