From 19d6fcb7a3086c355175909b0856d7c0da351827 Mon Sep 17 00:00:00 2001
From: alex_z46 <alex@bot4b.ru>
Date: Tue, 4 Aug 2026 19:17:35 +0000
Subject: [PATCH] Add comprehensive README with architecture, API docs, and
 comparison tables

---
 README.md | 135 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 134 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d103559..8291989 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,135 @@
-# stt-pipeline-v3
+# Smart STT Pipeline v3
 
+Умный пайплайн распознавания речи (Speech-to-Text) для русского языка с автоматическим выбором движка и пунктуацией.
+
+## 🚀 Возможности
+
+- **Два STT-движка**: T-one (быстрый) + GigaAM-v2 (точный)
+- **Автоматический роутинг**: выбор движка по длительности аудио
+- **Пунктуация через LLM**: Qwen3.5-4B
+- **Поддержка форматов**: OGG, WAV, MP3 и другие (через ffmpeg)
+
+## 📊 Сравнение движков
+
+| Движок | Время STT | Точность | Русский |
+|--------|-----------|----------|---------|
+| **T-one** | ~3 сек | Высокая | ✅ |
+| **GigaAM-v2** | ~7 сек | Очень высокая | ✅ |
+
+## 🔄 Логика роутинга
+
+```
+Аудио < 10 сек  → GigaAM-v2 (точнее для коротких)
+Аудио ≥ 10 сек  → T-one (быстрее для длинных)
+T-one fail      → GigaAM (fallback)
+```
+
+## 🛠️ Установка
+
+```bash
+docker build -t stt-pipeline-v3 .
+docker run -d --name stt-pipeline-v3 --network host stt-pipeline-v3
+```
+
+## 📡 API
+
+### POST /transcribe
+
+Распознать аудиофайл с автоматическим выбором движка.
+
+**Request:**
+```bash
+curl -X POST http://localhost:8005/transcribe \
+  -F "file=@voice_message.ogg"
+```
+
+**Response:**
+```json
+{
+  "original": "какие докеры у нас еще остались",
+  "punctuated": "Какие докеры у нас еще остались?",
+  "duration_sec": 2.7,
+  "stt_time_sec": 7.14,
+  "punct_time_sec": 0.87,
+  "server_used": "178.17.143.46:8080",
+  "stt_engine": "gigaam"
+}
+```
+
+### GET /health
+
+Проверка статуса сервиса.
+
+```bash
+curl http://localhost:8005/health
+# {"status":"ok","service":"stt-pipeline-v3"}
+```
+
+## 🏗️ Архитектура
+
+```
+Аудиофайл
+    │
+    ▼
+┌─────────────┐
+│ FFmpeg      │ ← Конвертация в WAV (16kHz mono)
+└─────┬───────┘
+      │
+      ▼
+┌─────────────┐
+│ Определяем  │ ← Длительность аудио
+│ длительность│
+└─────┬───────┘
+      │
+      ▼
+┌─────────────────────────────────┐
+│     Smart STT Router            │
+│  ┌─────────┐  ┌──────────────┐  │
+│  │ < 10 сек │  │ ≥ 10 сек    │  │
+│  │ GigaAM   │  │ T-one       │  │
+│  └─────────┘  └──────┬───────┘  │
+│                      │          │
+│                      ▼          │
+│              ┌──────────────┐   │
+│              │ T-one fail?  │   │
+│              └──────┬───────┘   │
+│                     │           │
+│                     ▼           │
+│              ┌──────────────┐   │
+│              │ GigaAM       │   │
+│              │ (fallback)   │   │
+│              └──────────────┘   │
+└─────────────────────────────────┘
+      │
+      ▼
+┌─────────────┐
+│ Qwen3.5-4B  │ ← Пунктуация (178.17.143.46:8080)
+└─────┬───────┘
+      │
+      ▼
+   JSON ответ
+```
+
+## 📁 Структура проекта
+
+```
+stt-pipeline-v3/
+├── app.py              # FastAPI приложение
+├── Dockerfile          # Контейнеризация
+├── requirements.txt    # Зависимости
+└── README.md           # Документация
+```
+
+## 🔧 Зависимости
+
+- Python 3.12
+- FastAPI 0.115
+- Uvicorn 0.32
+- FFmpeg (конвертация аудио)
+- T-one STT (localhost:8003)
+- GigaAM-v2 STT (localhost:8001)
+- Qwen3.5-4B (178.17.143.46:8080)
+
+## 📝 Лицензия
+
+MIT