corrector/OPENROUTER.md

# OpenRouter Integration

Модуль для работы с OpenRouter.ai API, предоставляющий доступ к различным LLM моделям (Google Gemini, OpenAI, Anthropic и др.).

## Возможности

- ✅ Универсальный клиент для OpenRouter API
- ✅ Поддержка различных моделей (Gemini, GPT, Claude и др.)
- ✅ Автоматические повторные попытки при ошибках
- ✅ Поддержка режима reasoning для совместимых моделей
- ✅ Интеграция с существующей системой коррекции
- ✅ Примеры использования через Python и curl

## Установка

Добавьте необходимую зависимость:

```bash
pip install requests
```

## Конфигурация

Добавьте в файл `.env`:

```bash
# OpenRouter Configuration
OPENROUTER_API_KEY=your-openrouter-api-key-here
OPENROUTER_MODEL=google/gemini-3-flash-preview
OPENROUTER_TEMPERATURE=0.1
OPENROUTER_MAX_TOKENS=4000
```

### Получение API ключа

1. Зарегистрируйтесь на [OpenRouter.ai](https://openrouter.ai/)
2. Перейдите в раздел [Keys](https://openrouter.ai/keys)
3. Создайте новый API ключ
4. Скопируйте ключ в `.env` файл

## Использование

### Python API

#### Базовое использование

```python
from corrector.openrouter_client import OpenRouterClient

# Инициализация клиента
client = OpenRouterClient()

# Простой запрос
messages = [
    {"role": "user", "content": "How many r's are in strawberry?"}
]

response = client.chat_completion(messages=messages)
print(response)
```

#### Коррекция медицинского текста

```python
from corrector.openrouter_client import OpenRouterClient

client = OpenRouterClient()

transcription = "Пациент жалуется на боль в животе"
system_prompt = "Ты медицинский помощник. Исправь ошибки в транскрипции."

corrected_text = client.correct_text(
    text=transcription,
    system_prompt=system_prompt,
    temperature=0.1
)

print(f"Исправленный текст: {corrected_text}")
```

#### Использование через MedicalLLMCorrector

```python
from corrector import MedicalLLMCorrector
from knowledge_base import MedicalTermManager

# Загрузка медицинских терминов
term_manager = MedicalTermManager("medical_terms.txt")

# Инициализация корректора
corrector = MedicalLLMCorrector(term_manager=term_manager)

# Коррекция транскрипции
transcription = "Пациент жалуется на боль в животе"
corrected_text, corrections = corrector.correct_transcription(transcription)

print(f"Исправленный текст: {corrected_text}")
print(f"Количество исправлений: {len(corrections)}")
```

### Curl (командная строка)

#### Базовый запрос

```bash
# Установите переменную окружения
export OPENROUTER_API_KEY="your-key-here"

# Выполните запрос
curl https://openrouter.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
  "model": "google/gemini-3-flash-preview",
  "messages": [
    {
      "role": "user",
      "content": "How many r'\''s are in the word strawberry?"
    }
  ],
  "reasoning": {
    "enabled": true
  }
}'
```

#### Коррекция медицинского текста

```bash
curl https://openrouter.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
  "model": "google/gemini-3-flash-preview",
  "messages": [
    {
      "role": "system",
      "content": "Ты медицинский помощник. Исправь ошибки в транскрипции."
    },
    {
      "role": "user",
      "content": "Пациент жалуется на боль в животе"
    }
  ],
  "temperature": 0.1,
  "reasoning": {
    "enabled": true
  }
}'
```

#### Использование тестового скрипта

```bash
# Сделайте скрипт исполняемым
chmod +x test_openrouter_curl.sh

# Запустите с дефолтным текстом
./test_openrouter_curl.sh

# Или передайте свой текст
./test_openrouter_curl.sh "Пациент жалуется на сильную головную боль"
```

## Тестирование

### Python тесты

```bash
# Запустите тестовый скрипт
python test_openrouter.py
```

Этот скрипт выполнит:
- ✅ Базовый тест chat completion
- ✅ Тест коррекции медицинского текста
- ✅ Тест с медицинскими терминами
- ✅ Вывод информации о модели

### Curl тесты

```bash
# Базовый тест
./test_openrouter_curl.sh

# Тест с кастомным текстом
./test_openrouter_curl.sh "Пациент с диагнозом апендицит"
```

## Поддерживаемые модели

OpenRouter поддерживает множество моделей:

### Google
- `google/gemini-3-flash-preview` (рекомендуется)
- `google/gemini-pro`
- `google/gemini-pro-1.5`

### OpenAI
- `openai/gpt-4o`
- `openai/gpt-4-turbo`
- `openai/gpt-3.5-turbo`

### Anthropic
- `anthropic/claude-3.5-sonnet`
- `anthropic/claude-3-opus`
- `anthropic/claude-3-sonnet`

### Другие
- `meta-llama/llama-3.1-405b-instruct`
- `mistralai/mixtral-8x22b-instruct`

Полный список: [OpenRouter Models](https://openrouter.ai/models)

## API клиент

### Основные методы

#### `__init__(api_key, model, base_url, timeout, max_retries, retry_delay)`

Инициализация клиента.

**Параметры:**
- `api_key`: API ключ (по умолчанию из `OPENROUTER_API_KEY`)
- `model`: Модель (по умолчанию из `OPENROUTER_MODEL`)
- `base_url`: URL API (по умолчанию `https://openrouter.ai/api/v1`)
- `timeout`: Таймаут запроса в секундах (по умолчанию 120)
- `max_retries`: Максимальное количество попыток (по умолчанию 3)
- `retry_delay`: Задержка между попытками (по умолчанию 2 сек)

#### `chat_completion(messages, model, temperature, max_tokens, reasoning_enabled, stream, **kwargs)`

Выполнение chat completion запроса.

**Параметры:**
- `messages`: Список сообщений с 'role' и 'content'
- `model`: Переопределить модель по умолчанию
- `temperature`: Температура сэмплирования (0-2)
- `max_tokens`: Максимальное количество токенов
- `reasoning_enabled`: Включить режим reasoning (для Gemini)
- `stream`: Включить потоковую передачу
- `**kwargs`: Дополнительные параметры API

**Возвращает:** Словарь с ответом API

#### `correct_text(text, system_prompt, model, temperature)`

Исправление текста с использованием LLM.

**Параметры:**
- `text`: Текст для исправления
- `system_prompt`: Системный промпт
- `model`: Переопределить модель
- `temperature`: Температура

**Возвращает:** Исправленный текст

#### `get_model_info()`

Получение информации о текущей конфигурации.

**Возвращает:** Словарь с информацией о модели

## Обработка ошибок

Клиент автоматически обрабатывает:
- ⏱️ Таймауты
- 🔄 Rate limiting (429 ошибки)
- 🔁 Автоматические повторные попытки
- 📝 Детальное логирование

Пример:

```python
try:
    response = client.chat_completion(messages)
except Exception as e:
    print(f"Ошибка API: {e}")
```

## Интеграция с Pipeline

Для использования OpenRouter в полном pipeline:

```python
from pipeline import MedicalTranscriptionPipeline
from pipeline.pipeline_config import PipelineConfig

```python
from pipeline import MedicalTranscriptionPipeline
from pipeline.pipeline_config import PipelineConfig

# Создайте pipeline
config = PipelineConfig()
pipeline = MedicalTranscriptionPipeline(config)

# Обработайте аудио
result = pipeline.process_audio("audio.wav")
```

## Преимущества OpenRouter

- 🌐 **Множество моделей** - доступ к GPT, Claude, Gemini и др. через единый API
- 💰 **Гибкое ценообразование** - платите только за использованные токены
- 🚀 **Reasoning mode** - расширенные возможности для Gemini
- 🔄 **Автоматический retry** - встроенная обработка ошибок
- 📊 **Статистика использования** - отслеживание расходов на OpenRouter.ai

## Логирование

Клиент использует стандартное логирование Python:

```python
import logging

# Настройте логирование
logging.basicConfig(level=logging.DEBUG)

# Клиент будет логировать:
# - Инициализацию
# - API запросы
# - Ошибки и повторные попытки
# - Успешные ответы
```

## Troubleshooting

### Ошибка: "OpenRouter API key not found"

**Решение:** Установите `OPENROUTER_API_KEY` в `.env` файле или передайте в конструктор.

### Ошибка: Rate limit (429)

**Решение:** Клиент автоматически повторяет запрос с задержкой. Проверьте свой план на OpenRouter.

### Ошибка: Model not found

**Решение:** Проверьте название модели на [OpenRouter Models](https://openrouter.ai/models).

### Медленные ответы

**Решение:** 
- Уменьшите `max_tokens`
- Используйте более быструю модель (например, `gemini-3-flash-preview`)
- Увеличьте `timeout` если нужно

## Дополнительные ресурсы

- [OpenRouter Documentation](https://openrouter.ai/docs)
- [OpenRouter Models](https://openrouter.ai/models)
- [OpenRouter Pricing](https://openrouter.ai/models/pricing)
- [API Reference](https://openrouter.ai/docs/api-reference)

## Примеры кода

### Пример 1: Простая коррекция

```python
from corrector.openrouter_client import OpenRouterClient

client = OpenRouterClient(model="google/gemini-3-flash-preview")

text = "Пациент жалуется на боль в животе, тошнота и рвота"
system = "Исправь грамматические ошибки в медицинском тексте"

corrected = client.correct_text(text, system)
print(corrected)
```

### Пример 2: Batch обработка

```python
from corrector.openrouter_client import OpenRouterClient

client = OpenRouterClient()

transcriptions = [
    "Пациент 1: боль в животе",
    "Пациент 2: высокая температура",
    "Пациент 3: кашель и насморк"
]

for i, text in enumerate(transcriptions, 1):
    corrected = client.correct_text(
        text=text,
        system_prompt="Исправь медицинский текст"
    )
    print(f"{i}. {corrected}")
```

### Пример 3: Кастомные параметры

```python
from corrector.openrouter_client import OpenRouterClient

client = OpenRouterClient(
    model="google/gemini-3-flash-preview",
    timeout=180,
    max_retries=5,
    retry_delay=3
)

messages = [
    {"role": "system", "content": "Ты врач-терапевт"},
    {"role": "user", "content": "Какие симптомы у гриппа?"}
]

response = client.chat_completion(
    messages=messages,
    temperature=0.3,
    max_tokens=1000
)

print(client._extract_content(response))
```

## Лицензия

Этот модуль является частью проекта Trans_for_doctors.