gitmost/docs/backlog/stt-providers-and-async.md

# STT: дополнительные провайдеры и переход на асинхронную схему

> Статус: беклог / план развития. Контекст — фича «голосовая диктовка» (STT,
> speech-to-text): кнопка-микрофон в чате агента и в редакторе, аудио
> распознаётся на сервере через AI-провайдер воркспейса. Документ фиксирует
> (1) какие ещё форматы STT-API имеет смысл поддержать и как, и (2) как в
> будущем перейти с текущей синхронной схемы (push-to-talk) на асинхронную.

## 1. Где мы сейчас

Распознавание построено как **синхронный запрос-ответ**:

- Клиент пишет звук (`MediaRecorder`), POST-ит blob → сервер распознаёт →
  возвращает `{ text }`, который вставляется в ввод. Никакого состояния задачи нет.
- Клиентская часть: `apps/client/src/features/dictation/` (`hooks/use-dictation.ts`,
  `components/mic-button.tsx`, `services/dictation-service.ts`).
- Эндпоинт: `POST /ai-chat/transcribe`
  (`apps/server/src/core/ai-chat/ai-chat.controller.ts`) — фича-гейт
  `settings.ai.dictation`, throttle, лимит 25 МБ, whitelist mime, вывод реальной
  ошибки провайдера (`describeProviderError`), формат контейнера выводится из mime.
- Тонкая обёртка: `apps/server/src/core/ai-chat/ai-transcription.service.ts` →
  делегирует в `AiService.transcribe(workspaceId, audio, format)`.
- Выбор кодировки запроса — **явное** поле `sttApiStyle`
  (`apps/server/src/integrations/ai/ai.types.ts`, `SttApiStyle`,
  `STT_API_STYLES`):
  - `multipart` — OpenAI-совместимый `POST /v1/audio/transcriptions` (form-data)
    через AI SDK (`createOpenAI(...).transcription()` + `experimental_transcribe`);
  - `json` — OpenRouter-стиль: `POST {baseURL}/audio/transcriptions`,
    `Content-Type: application/json`, тело `{ model, input_audio: { data:<base64>, format } }`,
    ответ `{ text }` (`AiService.transcribeJsonBase64`).
- Поле прокладывается как любой не-секрет: `resolve()` / `getMasked()` /
  whitelist в `AiSettingsService.update`
  (`apps/server/src/integrations/ai/ai-settings.service.ts`) **и** массив
  `ALLOWED` в `WorkspaceRepo.updateAiProviderSettings`
  (`apps/server/src/database/repos/workspace/workspace.repo.ts`).
- UI: селектор «Request format» на карточке Voice / STT
  (`apps/client/.../settings/components/ai-provider-settings.tsx`) +
  кнопка «Test endpoint» (бэкенд-проба — тихий WAV через тот же `transcribe`).

**Важно:** `multipart` уже покрывает почти всю экосистему — её реализуют OpenAI,
Azure OpenAI (Whisper), Groq, Together, Fireworks, DeepInfra, vLLM, LM Studio,
whisper.cpp/llama.cpp server, `speaches`, `faster-whisper-server`, WhisperX.
Для них **новый формат не нужен**, достаточно base URL + модель + ключ.
`json` покрывает OpenRouter. Ось `sttApiStyle` — это абстракция над
*контрактом запроса/ответа*: каждый реально иной контракт = одно значение enum
+ одна ветка-энкодер.

### Точки расширения для нового СИНХРОННОГО формата (чек-лист)

1. `ai.types.ts` — добавить значение в `SttApiStyle` и `STT_API_STYLES`.
2. `dto/update-ai-settings.dto.ts` — `@IsIn(STT_API_STYLES)` подхватит автоматически.
3. `ai.service.ts` — ветка в `transcribe()` + приватный энкодер
   (по образцу `transcribeJsonBase64`): сборка запроса, заголовок авторизации,
   `!res.ok` → бросок со статусом+телом (без утечки ключа), парс ответа в `text`.
4. Клиент: `ai-settings-service.ts` (тип `SttApiStyle`), опция в `<Select>`
   на карточке Voice / STT, i18n-строки.
5. Проба «Test endpoint» работает автоматически (идёт через тот же `transcribe`).

## 2. Кандидаты на новые синхронные форматы

Ранжировано по польза/трудозатраты. Все — синхронные (request→response),
вписываются в текущую модель без переделки.

### 2.1. Deepgram — самый сильный кандидат
- `POST https://api.deepgram.com/v1/listen`, аудио **сырыми байтами в теле**
  (`Content-Type: audio/*`) или JSON `{ "url": ... }`; параметры (`model`,
  `language`, `smart_format`) — в query.
- Авторизация: заголовок `Authorization: Token <key>` (не `Bearer`).
- Ответ — свой JSON: `results.channels[0].alternatives[0].transcript`.
- Значение enum: `deepgram`. Энкодер шлёт байты + Token-заголовок и вынимает
  transcript из вложенной структуры.

### 2.2. Gemini (нативно) — переиспользует существующий драйвер
- У воркспейса уже может быть драйвер `gemini`. Транскрипция = `generateContent`
  с инлайн-аудио (`inlineData: { mimeType, data:<base64> }`) и промптом
  «transcribe verbatim».
- Плюс: один ключ на чат + STT. Минус: это LLM, а не STT-эндпоинт — латентность
  и качество отличаются, формат ответа надо чистить (модель может «болтать»).
- Значение enum: `gemini` (или ветка по `cfg.driver === 'gemini'`).

### 2.3. ElevenLabs Scribe — ниша, растёт
- `POST https://api.elevenlabs.io/v1/speech-to-text`, multipart, заголовок
  `xi-api-key: <key>` (не `Authorization`), поле `model_id`, свой ответ.
- Значение enum: `elevenlabs`.

### Groq — отдельный формат НЕ нужен
OpenAI-совместимый multipart. Работает уже сейчас: поставить base URL Groq и
модель `whisper-large-v3` при `sttApiStyle = multipart`.

## 3. Что НЕ влезает в синхронную модель (и почему)

Эти провайдеры **по своей природе асинхронные** (upload → poll/webhook) или
батч-ориентированные; их нельзя дождаться одним коротким HTTP-ответом, поэтому
они требуют именно асинхронной схемы из раздела 4 (а не ещё одного значения
`sttApiStyle`):

- **AssemblyAI** — upload → создать job → polling статуса / webhook.
- **AWS Transcribe** — job на основе S3, long-running.
- **Google Cloud Speech-to-Text** — `longrunningrecognize` (operation polling).
- **Azure Speech (batch transcription)** — job + polling.
- **Gladia, Speechmatics, Rev.ai** — job + polling/webhook.

Их подключение = новая фича с очередью и состоянием задачи, а не маленькая ветка.

## 4. Будущая асинхронная схема (целевая архитектура)

Зачем переходить (драйверы):
- **Длинная диктовка / батч**: запись > 25 МБ или длиннее пары минут не лезет
  в один синхронный запрос (см. лимит в контроллере) и держит HTTP-соединение.
- **Async-провайдеры** (раздел 3) вообще не поддаются синхронной модели.
- **Живая транскрипция** (промежуточный текст по мере речи) — отдельная, но
  смежная цель.
- Устойчивость: ретраи, наблюдаемость, разъединение клиента и провайдера.

### 4.1. Модель задачи (job-based)

Ввести сущность «задача транскрипции» и гонять её через очередь (у нас уже есть
BullMQ на Redis и `AI_QUEUE` — по образцу RAG-индексатора в
`apps/server/src/core/ai-chat/embedding/`):

1. Клиент загружает аудио → сервер кладёт его во временное хранилище
   (`StorageService`: local/S3/Azure) и создаёт запись задачи в новой таблице
   `transcription_jobs` (миграция только добавляет таблицу — см. правила в
   CLAUDE.md): `id, workspaceId, userId, status (queued|processing|done|error),
   provider/sttApiStyle, audioRef, resultText, errorText, createdAt, updatedAt`.
2. Сервер ставит job в очередь (новый `QueueJob.TRANSCRIBE` на `AI_QUEUE` или
   отдельная очередь) и сразу отвечает клиенту `{ jobId, status: 'queued' }`.
3. Консьюнер берёт job, читает аудио, вызывает провайдера:
   - **синхронные** провайдеры (multipart/json/deepgram/…) — просто выполняются
     внутри воркера и завершают job (тот же код `AiService.transcribe`, но без
     HTTP-таймаута запроса клиента);
   - **асинхронные** провайдеры (AssemblyAI и т.п.) — воркер сабмитит job
     провайдеру и либо поллит статус, либо ждёт webhook (нужен публичный
     callback-эндпоинт), затем дописывает результат.
4. Результат сохраняется в задачу; аудио **сразу удаляется** (или по TTL).

Главная мысль: **единая job-модель поглощает и sync-, и async-провайдеров** —
для синхронных воркер завершает задачу за один проход, для асинхронных ведёт её
до готовности. `sttApiStyle` остаётся осью выбора энкодера.

### 4.2. Доставка результата клиенту

Варианты (от простого к «живому»):
- **Polling**: клиент дёргает `POST /ai-chat/transcribe/status { jobId }` каждые
  N секунд до `done|error`. Просто, надёжно, первый шаг.
- **SSE / WebSocket push**: переиспользовать существующую Socket.IO/Redis-инфру
  (как у коллаборации) и слать обновление статуса в сессию пользователя.
- **Live-стриминг** (отдельная фаза): WebSocket-мост к realtime-API провайдера
  (Deepgram streaming, OpenAI Realtime) с промежуточным текстом. Это уже не
  job-модель, а постоянное соединение; держать как самостоятельный режим.

### 4.3. Путь миграции (без слома текущего UX)

- Сохранить нынешний синхронный `POST /ai-chat/transcribe` для **коротких**
  клипов (push-to-talk остаётся мгновенным) — это «быстрый путь».
- Добавить job-путь для **длинных/батч** записей и для async-провайдеров.
- Клиентский хук `use-dictation` получает развилку: короткая запись → sync,
  длинная (по длительности/размеру) → job + статус. UI: индикатор
  «распознаётся…» уже есть (`transcribing`), добавить состояние «в очереди».
- `sttApiStyle` расширяется теми же шагами из раздела 1; async-провайдеры
  добавляются только в job-путь.

### 4.4. На что обратить внимание при реализации

- **Хранение аудио**: временное, с обязательной очисткой (TTL/после job).
  Не логировать аудио и ключи (см. правило об ошибках в CLAUDE.md).
- **Безопасность**: job скоупится воркспейсом и пользователем (CASL), статус
  доступен только владельцу job; webhook-эндпоинт для async — с проверкой
  подписи/секрета и через `ssrf-guard`, если зовём наружу.
- **Лимиты/квоты**: throttle на постановку задач; ограничение длины/размера;
  бюджет на параллельные job.
- **Ошибки**: каждая неудача job пишет полную причину в лог и в `errorText`,
  пользователю показывается конкретное объяснение (а не «не получилось»).
- **Идемпотентность/ретраи**: BullMQ `jobId`, removeOnComplete/Fail, дедуп
  повторных постановок (как в RAG-реиндексе).
- **Миграции**: новая таблица только добавляется; следить за порядком
  таймстампов при мёрдже веток (см. CLAUDE.md → «Migration ordering»).

## 5. Рекомендация (приоритеты)

1. Оставить текущие `multipart` + `json` — этого хватает большинству, включая
   self-hosted.
2. Если нужен облачный не-OpenAI вариант — добавить **Deepgram** (синхронно,
   маленькая ветка).
3. **Gemini-нативный** — дёшево, раз драйвер `gemini` уже есть.
4. Async-схему (раздел 4) делать, когда появится реальная потребность в длинной
   диктовке / батче / async-провайдерах; начинать с job-модели + polling, затем
   push, и только потом live-стриминг.

> Перед реализацией любого провайдера — сверить актуальную форму запроса/ответа
> по его документации (API дрейфуют), затем добавить значение `sttApiStyle` +
> энкодер по чек-листу из раздела 1.