README_GUI.md

# Trans for Doctors - Медицинский транскрибер с GUI

## 🎯 Основные возможности

- 🎤 **STT (Speech-to-Text)** - транскрибация аудио с помощью Whisper
- 📚 **Knowledge Base** - специальная база медицинских терминов
- 🤖 **LLM Коррекция** - умное исправление ошибок через OpenRouter API
  - Google Gemini (рекомендуется для скорости)
  - OpenAI GPT-4o (лучшее качество)
  - Anthropic Claude (отличный баланс)
  - И 50+ других моделей через OpenRouter
- 📄 **Report Generation** - автоматическая генерация DOCX отчётов
- 🖥️ **GUI Приложение** - удобный интерфейс для Windows (.exe)

## 🚀 Быстрый старт

### Вариант 1: Windows .exe приложение (Рекомендуется)

**Для конечного пользователя:**

```bash
# 1. Скачайте dist/MedicalTranscriber.exe
# 2. Двойной клик для запуска
# Готово! Никакой установки не требуется
```

**Для разработчика (собрать .exe):**

```bash
# Установить зависимости
pip install -r requirements.txt

# Собрать Windows приложение
python build_exe.py

# Результат: dist/MedicalTranscriber.exe (~500 МБ - 1.5 ГБ)
```

📖 Подробная инструкция: [BUILD_EXE.md](BUILD_EXE.md)

### Вариант 2: GUI через Python

```bash
# Установить зависимости
pip install -r requirements.txt

# Запустить GUI
python run_gui.py
```

### Вариант 3: CLI (Command Line)

После `uv sync` доступен CLI-скрипт `transmed` для запуска пайплайна:

```bash
# Установка зависимостей
uv sync
uv pip install .[llm]  # для LLM-коррекции (OpenRouter)

# Запуск пайплайна
uv run transmed \
  --audio test_sound_ru.wav \
  --model . \
  --terms medical_terms.txt \
  --llm \
  --save-original --save-corrected --generate-report
```

Параметры CLI:
- `--audio`: путь к .wav
- `--model`: папка с локальной Whisper-моделью
- `--terms`: файл терминов (Knowledge Base)
- `--llm` / `--no-llm`: включить/выключить LLM коррекцию
- `--openrouter-key`: ключ OpenRouter (или из переменной окружения)
- `--generate-report`: создать DOCX отчёт
- `--results-dir`, `--logs-dir`: папки для сохранения

## 📖 Документация

### Для пользователей:
- **[USER_GUIDE.md](USER_GUIDE.md)** - 📘 Полное руководство по использованию GUI приложения ⭐
- **[BUILD_EXE.md](BUILD_EXE.md)** - Инструкции по сборке Windows .exe

### Для разработчиков:
- **[APP_ARCHITECTURE.md](APP_ARCHITECTURE.md)** - Архитектура и структура кода
- **[corrector/OPENROUTER.md](corrector/OPENROUTER.md)** - Интеграция с OpenRouter
- **[stt/README.md](stt/README.md)** - Модуль транскрибирования
- **[knowledge_base/README.md](knowledge_base/README.md)** - База медицинских терминов

## 🎨 GUI Приложение - Быстрый старт

### Как использовать:

1. **Запустить приложение**
   ```bash
   python run_gui.py
   # или запустить dist\MedicalTranscriber.exe (после сборки)
   ```

2. **Выбрать аудиофайл** - вкладка "Транскрибирование" → кнопка "Обзор..."

3. **Заполнить данные пациента** - кнопка "Заполнить данные пациента..."

4. **Выбрать опции** - включить LLM коррекцию и генерацию отчёта

5. **Нажать "▶ Начать транскрибирование"**

6. **Дождаться результатов** - обычно 2-5 минут

7. **Получить DOCX отчёт** - в папке `results/reports/`

📖 **Полное руководство**: [USER_GUIDE.md](USER_GUIDE.md)

## 🏗️ Архитектура проекта

```
Trans_for_doctors/
├── 🖥️ GUI Application
│   ├── run_gui.py                     # Точка входа GUI
│   ├── app/gui_app.py                 # Главное окно (PyQt6)
│   ├── build_exe.py                   # Сборка Windows .exe ⭐
│   └── build_windows.spec             # PyInstaller конфиг
│
├── 🔄 Pipeline (Ядро обработки)
│   ├── pipeline/medical_pipeline.py    # Оркестрация всех компонентов
│   ├── stt/whisper_transcriber.py      # STT модуль (транскрибирование)
│   ├── knowledge_base/                 # База медицинских терминов
│   ├── corrector/                      # LLM коррекция через OpenRouter
│   └── corrector/report_generator.py   # DOCX генератор отчётов
│
├── 📚 CLI Interface (через uv)
│   └── Поддержка команды `uv run transmed`
│
└── 📖 Documentation
    ├── USER_GUIDE.md                   # ⭐ Руководство для пользователей
    ├── BUILD_EXE.md                    # Сборка приложения
    ├── APP_ARCHITECTURE.md             # Техническая архитектура
    └── README.md                       # Этот файл
```

## 📋 Требования

### Для использования .exe приложения:
- **Windows 10+** (или Linux/macOS для Python версии)
- **4+ ГБ** оперативной памяти
- **2+ ГБ** свободного места на диске
- Интернет для OpenRouter API (опционально)

### Для разработки:
- Python 3.9+
- pip или uv
- Git

## 🔧 Установка для разработки

```bash
# Клонировать репозиторий
git clone <repo>
cd Trans_for_doctors

# Установить зависимости
pip install -r requirements.txt

# Для работы с uv (опционально)
pip install uv
uv sync
```

## 🚀 Запуск приложения

### Запуск GUI из Python:
```bash
python run_gui.py
```

### Запуск скомпилированного .exe:
```bash
dist\MedicalTranscriber.exe
```

### Собрать новый .exe:
```bash
# Автоматическая сборка (рекомендуется)
python build_exe.py

# Или вручную через PyInstaller
pyinstaller --onefile --windowed --name=MedicalTranscriber build_windows.spec
```

## 💾 Результаты и сохранение

### Папка структура после обработки:
```
results/
├── result_20260116_120530.json              # Оригинальная транскрипция (JSON)
├── result_20260116_120530_corrected.json    # Скорректированная версия (JSON)
└── reports/
    └── report_20260116_120530.docx          # Финальный DOCX отчёт ⭐

logs/
└── transcription_20260116_120530.log        # Логи обработки
```

### Содержание DOCX отчёта:
- 📌 Заголовок (название исследования)
- 👤 Информация о пациенте (ФИО, дата рождения, номер исследования)
- 📝 Протокол обследования (полная транскрипция)
- ✏️ Заключение (итоговое заключение врача)
- 💡 Рекомендации
- 🖊️ Подпись врача и дата

## 🔑 OpenRouter API

Для включения умной LLM коррекции:

1. Зарегистрируйтесь на https://openrouter.ai
2. Получите API ключ в Settings → Keys
3. Вставьте ключ в GUI приложение (вкладка "Настройки")
4. Выберите модель (GPT-4, Claude, Gemini и т.д.)

**Стоимость:** ~5-10 рублей за 1000 слов при коррекции

**Доступные модели:**
- `gpt-4o` - лучшее качество, дороже
- `claude-3-opus` - отличное качество, экономнее
- `gemini-pro` - хорошее качество, быстро
- `gpt-4-turbo` - баланс качества и цены

## 🎯 Примеры использования

### Пример 1: Базовая транскрибирование (без коррекции)
1. Запустить приложение
2. Выбрать аудиофайл
3. Отключить "Использовать LLM-коррекцию"
4. Запустить обработку

### Пример 2: Полная обработка с отчётом
1. Запустить приложение
2. Выбрать аудиофайл
3. Заполнить данные пациента (ФИО, дата рождения, врач)
4. Включить "LLM-коррекцию" и "Создать отчёт"
5. Запустить обработку
6. Получить готовый DOCX отчёт в папке `results/reports/`

### Пример 3: Пакетная обработка (CLI)
```bash
for file in *.wav; do
  uv run transmed \
    --audio "$file" \
    --model . \
    --llm \
    --generate-report
done
```

## 🐛 Решение проблем

### Проблема: Модель не найдена
**Решение:** Скачайте модель Whisper и укажите путь в настройках
```bash
huggingface-cli download openai/whisper-base-ru --local-dir ./whisper_model
```

### Проблема: API ключ неверный
**Решение:** Проверьте ключ на https://openrouter.ai, убедитесь в наличии кредитов

### Проблема: Чёрный экран при запуске
**Решение:** Подождите 30-60 секунд (загрузка модели), проверьте консоль

📖 **Полный гайд по проблемам**: [USER_GUIDE.md](USER_GUIDE.md#-решение-проблем)

## 📞 Техническая поддержка

- Проверьте логи в папке `logs/`
- Смотрите `USER_GUIDE.md` для типичных проблем
- Проверьте `BUILD_EXE.md` для проблем со сборкой
- Смотрите консоль при запуске через `python run_gui.py`

## 📝 История изменений

### v1.0 (Январь 2026)
- ✅ GUI приложение на PyQt6
- ✅ Интеграция с Whisper STT
- ✅ LLM коррекция через OpenRouter
- ✅ Автогенерация DOCX отчётов
- ✅ Сборка Windows .exe файла
- ✅ Полная документация для пользователей и разработчиков

---

## 🎉 Начните работу прямо сейчас!

### Для пользователя:
1. Скачайте [USER_GUIDE.md](USER_GUIDE.md)
2. Скачайте/собака .exe из `dist/MedicalTranscriber.exe`
3. Запустите и наслаждайтесь!

### Для разработчика:
1. Прочитайте [APP_ARCHITECTURE.md](APP_ARCHITECTURE.md)
2. Изучите исходный код в папках `app/`, `pipeline/`, `corrector/`
3. Запустите `python run_gui.py` для разработки

---

**Приложение готово к использованию! 🚀**

Для вопросов и поддержки обратитесь к [USER_GUIDE.md](USER_GUIDE.md)