solver-sdk 1.7.2 → 1.7.3

package/docs/thinking/THINKING_ARCHITECTURE.md

@@ -0,0 +1,221 @@
+# Архитектура системы потоковой передачи мышления
+
+Этот документ описывает техническую архитектуру системы потоковой передачи мышления в 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) 

package/docs/thinking/streaming-thinking-guide.md

@@ -0,0 +1,164 @@
+# Руководство: Потоковый чат с Thinking через SDK
+
+Это руководство объясняет, как использовать обновленный `solver-sdk` для получения потоковых ответов от языковой модели с поддержкой режима "thinking" через WebSocket. Это позволяет отображать ход мыслей модели и финальный ответ в реальном времени.
+
+## Основной метод: `streamChatWithThinking`
+
+Для потоковой передачи с thinking используйте новый метод `sdk.chat.streamChatWithThinking`.
+
+**Преимущества:**
+
+- **Автоматическое подключение WebSocket:** SDK сам создает и управляет WebSocket соединением.
+- **Простая обработка событий:** Вы просто предоставляете callback-функцию для обработки всех событий потока.
+- **Полная поддержка Anthropic:** Обрабатываются все актуальные события (`thinking_delta`, `text_delta`, `signature_delta`, `message_delta`, `ping` и т.д.).
+
+## Пример использования
+
+```javascript
+const { CodeSolverSDK } = require('solver-sdk'); // Или import { CodeSolverSDK } from 'solver-sdk';
+
+async function runStreamingExample() {
+  // 1. Инициализация SDK
+  const sdk = new CodeSolverSDK({
+    baseURL: 'https://your-backend-url.com', // URL вашего бэкенда
+    // apiKey: 'your-api-key' // Если требуется
+  });
+
+  // 2. Сообщения для отправки
+  const messages = [
+    { role: 'user', content: 'Объясни теорию относительности простыми словами.' }
+  ];
+
+  // 3. Опции запроса (включаем thinking)
+  const options = {
+    model: 'claude-3-7-sonnet-20240229', // Или другая модель с поддержкой thinking
+    thinking: true, // Обязательно для активации режима
+    temperature: 0.7
+  };
+
+  // 4. Обработчик событий WebSocket
+  const handleEvent = (eventType, data) => {
+    console.log(`[EVENT: ${eventType}]`, data); // Логирование всех событий для отладки
+
+    switch(eventType) {
+      // Начало потока
+      case 'connect':
+        console.log(`WebSocket подключен: ${data.socketId}`);
+        break;
+      case 'message_start':
+        console.log(`Начало ответа модели: ${data.model}`);
+        // Здесь можно инициализировать UI для отображения ответа
+        break;
+
+      // Поток размышлений
+      case 'thinking_start':
+        console.log('-- Начало размышлений --');
+        // Очистить/показать область для размышлений
+        break;
+      case 'thinking_delta':
+        process.stdout.write(data.text); // Выводим текст размышлений по мере поступления
+        // Добавить data.text в UI область размышлений
+        break;
+      case 'signature_delta':
+        console.log('[Подпись блока thinking получена]');
+        break;
+
+      // Поток основного ответа
+      case 'text_delta':
+        process.stdout.write(data.text); // Выводим текст ответа по мере поступления
+        // Добавить data.text в UI область ответа
+        break;
+
+      // Завершение блоков и сообщения
+      case 'content_block_stop':
+        // Блок (thinking или text) завершен
+        break;
+      case 'message_delta':
+        // Обновление статуса сообщения (например, stop_reason)
+        console.log(`Обновление сообщения: ${JSON.stringify(data.delta)}`);
+        break;
+      case 'message_stop':
+        console.log('-- Сообщение завершено --');
+        // Показать финальное состояние UI
+        break;
+
+      // Служебные события
+      case 'ping':
+        console.log('[Ping от сервера]');
+        break;
+      case 'retry':
+        console.warn(`Попытка переподключения ${data.retryCount} из-за перегрузки...`);
+        break;
+
+      // Ошибки и завершение
+      case 'error':
+        console.error(`Ошибка WebSocket: ${data.message} (Код: ${data.code})`);
+        // Показать сообщение об ошибке в UI
+        break;
+      case 'disconnect':
+        console.log('WebSocket отключен');
+        break;
+      case 'done':
+        console.log('Поток данных завершен.');
+        // Можно закрыть соединение или ожидать новых запросов
+        break;
+        
+      case 'unknown_event':
+        console.log(`Получено неизвестное событие: ${data.type}`);
+        break;
+    }
+  };
+
+  // 5. Вызов метода и ожидание потока
+  try {
+    console.log('Отправка запроса...');
+    const response = await sdk.chat.streamChatWithThinking(
+      messages,
+      options,
+      handleEvent // Передаем наш обработчик
+    );
+
+    console.log(`Запрос успешно отправлен. Используется Socket ID: ${response.socketId}`);
+    console.log('Ожидание событий через WebSocket...');
+    // В реальном приложении здесь будет основной цикл работы или ожидание
+
+  } catch (error) {
+    console.error('Ошибка при отправке запроса:', error);
+    // Обработка ошибки инициации запроса
+  }
+}
+
+// Запуск примера
+runStreamingExample();
+```
+
+## Ключевые моменты
+
+1.  **Включите `thinking: true`**: Это главный параметр для активации режима потокового мышления.
+2.  **Предоставьте обработчик `onEvent`**: Эта функция будет получать все события WebSocket.
+3.  **Обрабатывайте нужные события**: Как минимум, вам понадобятся `thinking_delta` (для размышлений) и `text_delta` (для основного ответа), а также `error` и `done`.
+4.  **SDK управляет соединением**: Вам не нужно вручную создавать `socketId` или подключаться к WebSocket – SDK сделает это автоматически.
+
+## (Опционально) Использование существующего `socketId`
+
+Если ваш клиент уже управляет WebSocket соединением и имеет `socketId`, вы можете передать его в опциях, чтобы SDK использовал существующее соединение:
+
+```javascript
+// Предположим, у вас есть connectResponse от sdk.chat.connectWebSocket()
+const existingSocketId = connectResponse.socketId;
+
+const options = {
+  model: 'claude-3-7-sonnet-20240229',
+  thinking: true,
+  socketId: existingSocketId // Передаем существующий ID
+};
+
+// SDK не будет создавать новое соединение, а использует указанное
+const response = await sdk.chat.streamChatWithThinking(
+  messages,
+  options,
+  handleEvent 
+);
+```
+
+Это полезно, если вы хотите использовать одно WebSocket соединение для нескольких запросов.