solver-sdk/docs/thinking/THINKING_ARCHITECTURE.md

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

# Архитектура системы потоковой передачи мышления

Этот документ описывает техническую архитектуру системы потоковой передачи мышления в SDK и взаимодействие между клиентом, сервером и API Anthropic.

## Общая схема взаимодействия

```
Client (SDK) <--WebSocket--> NestJS Server <--HTTP Stream--> Anthropic API
```

## Компоненты системы

### 1. Клиент (SDK)

SDK предоставляет API для:
- Инициации WebSocket соединения
- Отправки запросов с активированным режимом мышления
- Обработки событий через callback-функцию
- Управления соединениями и сессиями

### 2. Сервер (NestJS)

Сервер выполняет несколько ключевых функций:
- Обрабатывает HTTP-запросы от SDK
- Создает и управляет WebSocket соединениями
- Отправляет запросы к Anthropic API
- Преобразует и перенаправляет события от Anthropic API клиентам

### 3. Anthropic API

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

## Порядок работы системы

1. **Инициализация WebSocket соединения:**
   - SDK вызывает метод подключения WebSocket
   - Сервер создает соединение и назначает `socketId`
   - SDK сохраняет `socketId` для использования в запросах

2. **Отправка запроса на обработку:**
   - SDK отправляет запрос с параметром `thinking: true` и указанным `socketId`
   - Сервер создает сессию рассуждения и связывает ее с WebSocket соединением
   - Сервер инициирует потоковый запрос к Anthropic API

3. **Обработка потока данных:**
   - Anthropic API отправляет потоковые события (SSE) серверу
   - Сервер преобразует SSE события в WebSocket события
   - Сервер отправляет события соответствующим клиентам

4. **Завершение обработки:**
   - Anthropic API отправляет финальное событие `message_stop`
   - Сервер пересылает событие клиенту и завершает сессию
   - SDK вызывает обработчик `message_stop` и может закрыть соединение

## Потоки данных и события

### События от Anthropic API

Anthropic API отправляет следующие основные типы событий:

```
1. message_start
2. content_block_start (thinking block)
3. content_block_delta (thinking_delta) x N
4. content_block_stop
5. content_block_start (text block)
6. content_block_delta (text_delta) x M
7. content_block_stop
8. message_stop
```

### Преобразование событий

Сервер преобразует события от Anthropic API в формат WebSocket:

| Событие Anthropic API | WebSocket событие | Данные |
|----------------------|-------------------|--------|
| message_start | message_start | { id, model, type } |
| content_block_start (thinking) | thinking_block_start | { index, type } |
| content_block_delta (thinking_delta) | thinking_delta + thinking_block_delta | { text, thinking, index } |
| content_block_stop (thinking) | thinking_block_stop | { index, type } |
| content_block_start (text) | content_block_start | { index, type } |
| content_block_delta (text_delta) | text_delta + content_block_delta | { text, index } |
| content_block_stop (text) | content_block_stop | { index, type } |
| message_stop | message_stop | { type } |

## Особенности реализации

### 1. WebSocket архитектура

- Используется Socket.IO для WebSocket коммуникации
- Соединения организованы по namespace `/reasoning`
- Используется корректный path `/socket.io` без завершающего слеша

### 2. Обработка событий мышления

- События мышления (`thinking_delta`) передаются в двух форматах:
  1. `thinking_delta` с полями `text` и `thinking` для совместимости с различными клиентами
  2. `thinking_block_delta` с полем `delta` для совместимости с SDK тестами

### 3. Потоки данных

Система поддерживает два параллельных потока данных:
- Поток мышления (отображает процесс рассуждения модели)
- Поток ответа (финальный ответ модели после рассуждения)

### 4. Работа с многопроцессными средами

При использовании SDK в многопроцессных средах:
- WebSocket соединение должно быть инициализировано в одном процессе
- События должны передаваться между процессами через IPC
- Необходима буферизация событий для предотвращения потери данных

## Диагностика и устранение проблем

### Типичные проблемы и их решение

| Проблема | Возможные причины | Решение |
|----------|-------------------|---------|
| Нет подключения WebSocket | Неверный URL, CORS, блокировка порта | Проверьте сетевые настройки, логи сервера |
| Не приходят события thinking_delta | Проблема с socketId, неверный формат запроса | Проверьте передачу socketId, включение параметра thinking |
| Отключение в середине потока | Таймаут, ошибка сервера | Используйте механизм переподключения, проверьте логи сервера |
| Неправильный формат данных | Несоответствие между версиями клиента и сервера | Обновите SDK или сервер до последней версии |

### Диагностические инструменты

- Подробные логи на серверной стороне
- Индикация полученных событий в клиентской части
- Мониторинг состояния WebSocket соединений

## Рекомендации по оптимизации

### Клиентская сторона

- Используйте буферизацию событий для экономии ресурсов UI
- Применяйте дедупликацию и фильтрацию повторяющихся событий
- Добавьте индикаторы прогресса для длительных операций

### Серверная сторона

- Оптимизируйте структуру данных для минимизации трафика
- Используйте пулинг WebSocket соединений для высоконагруженных систем
- Применяйте компрессию данных для больших объемов текста

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

### Базовый пример

```javascript
// Инициализация SDK и WebSocket
const sdk = new CodeSolverSDK({ baseURL: 'https://api.example.com' });
const wsClient = sdk.getWebSocketClient();
await wsClient.connect();

// Обработчик событий
const handleEvent = (eventType, data) => {
  if (eventType === 'thinking_delta') {
    console.log('Thinking:', data.text || data.thinking);
  } else if (eventType === 'text_delta') {
    console.log('Response:', data.text);
  }
};

// Отправка запроса с thinking
const response = await sdk.chat.streamChatWithThinking(
  [{ role: 'user', content: 'Explain quantum computing' }],
  { 
    model: 'claude-3-7-sonnet-20240229',
    thinking: true
  },
  handleEvent
);
```

### Расширенный пример с обработкой ошибок

```javascript
// Инициализация с обработкой ошибок
try {
  const wsClient = sdk.getWebSocketClient();
  await wsClient.connect();
  
  // Обработчик с поддержкой ошибок
  const handleEvent = (eventType, data) => {
    switch(eventType) {
      case 'thinking_delta':
        updateThinkingUI(data.text || data.thinking);
        break;
      case 'text_delta':
        updateResponseUI(data.text);
        break;
      case 'error':
        showError(`Error: ${data.message}`);
        break;
      case 'disconnect':
        showWarning('Connection lost, attempting to reconnect...');
        reconnect();
        break;
    }
  };
  
  // Отправка запроса
  const response = await sdk.chat.streamChatWithThinking(
    messages,
    options,
    handleEvent
  );
} catch (error) {
  console.error('Failed to connect:', error);
  showFatalError(error.message);
}
```

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

- [Документация Anthropic по потоковой передаче](https://docs.anthropic.com/en/api/messages-streaming)
- [Streaming Thinking Guide](./streaming-thinking-guide.md)
- [WebSocket Documentation](./WEBSOCKET.md)