solver-sdk/docs/REGIONS.md

SDK для интеграции с Code Solver Backend API (совместимо с браузером и Node.js), с поддержкой функциональности мышления (Thinking Mode)

# Работа с региональными эндпоинтами Anthropic API

SDK поддерживает работу с различными региональными эндпоинтами Anthropic API, что позволяет:
- Улучшить производительность для пользователей в разных регионах
- Обеспечить отказоустойчивость при перегрузке одного из регионов
- Соблюдать законодательные требования по обработке данных в конкретных регионах

## Содержание

- [Поддерживаемые регионы](#поддерживаемые-регионы)
- [Настройка региона](#настройка-региона)
- [Автоматическое переключение между регионами](#автоматическое-переключение-между-регионами)
- [Примеры использования](#примеры-использования)
- [Ограничения](#ограничения)

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

SDK поддерживает следующие регионы Anthropic API:

| Регион | Код | Расположение | Доступность |
|--------|-----|--------------|-------------|
| US East (N. Virginia) | `us-east-1` | США | Основной регион |
| EU West (Ireland) | `eu-west-1` | Евросоюз | Соответствует GDPR |
| Asia Pacific (Sydney) | `ap-southeast-2` | Австралия | Для пользователей в APAC |

Каждый регион имеет собственный эндпоинт и характеристики производительности.

## Настройка региона

Регион для запросов можно настроить несколькими способами:

### 1. В глобальных настройках SDK

```javascript
const sdk = new CodeSolverSDK({
  baseURL: 'https://api.example.com',
  apiKey: 'your-api-key',
  providers: {
    anthropic: {
      region: 'eu-west-1' // Использовать европейский регион для всех запросов
    }
  }
});
```

### 2. В параметрах конкретного запроса

```javascript
// Для чата
const response = await sdk.chat.chat([
  { role: 'user', content: 'Привет! Как дела?' }
], {
  model: 'claude-3-sonnet-20240229',
  region: 'ap-southeast-2' // Использовать азиатско-тихоокеанский регион для этого запроса
});

// Для рассуждений
const reasoning = await sdk.reasoning.createReasoning({
  projectId: 'my-project',
  query: 'Как оптимизировать этот код?',
  options: {
    region: 'us-east-1' // Использовать американский регион для этого рассуждения
  }
});
```

## Автоматическое переключение между регионами

SDK (версия 1.7.1+) поддерживает автоматическое переключение между регионами при получении ошибки перегрузки (код 529) от Anthropic API.

### Для чата

```javascript
// Использует автоматическое переключение между регионами
const response = await sdk.chat.chatWithRegionFailover([
  { role: 'user', content: 'Привет! Как дела?' }
], {
  model: 'claude-3-sonnet-20240229',
  region: 'us-east-1' // Начинаем с этого региона, но можем переключиться на другие
});
```

### Для рассуждений

```javascript
// Использует автоматическое переключение между регионами
const reasoning = await sdk.reasoning.createReasoningWithRegionFailover({
  projectId: 'my-project',
  query: 'Как оптимизировать этот код?',
  options: {
    region: 'eu-west-1' // Начинаем с этого региона, но можем переключиться на другие
  }
});
```

### Как работает переключение между регионами

1. Запрос отправляется в указанный регион
2. Если регион возвращает ошибку перегрузки (код 529), SDK автоматически пробует следующий доступный регион
3. Если все регионы перегружены, возвращается ошибка

Порядок переключения: регионы проверяются в порядке, начиная с указанного в параметрах, затем по кругу.

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

### Базовый пример переключения регионов

```javascript
try {
  const response = await sdk.chat.chatWithRegionFailover([
    { role: 'user', content: 'Привет! Расскажи о переключении регионов Anthropic API.' }
  ], {
    model: 'claude-3-sonnet-20240229'
  });
  
  console.log('Ответ:', response.choices[0].message.content);
} catch (error) {
  console.error('Все регионы недоступны:', error);
}
```

### Пример с настройкой порядка регионов

```javascript
// Запрос с указанием предпочтительного региона 
// (остальные будут проверены в порядке следования после него)
const response = await sdk.chat.chatWithRegionFailover([
  { role: 'user', content: 'Привет!' }
], {
  model: 'claude-3-sonnet-20240229',
  region: 'ap-southeast-2' // Сначала пробуем AP регион, затем US и EU
});
```

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

- Переключение работает только для ошибки перегрузки (код 529)
- Другие ошибки (аутентификация, формат запроса и т.д.) не вызывают переключение
- При переключении между регионами может быть заметная задержка
- Цены и квоты могут отличаться в разных регионах