solver-sdk 1.7.2 → 1.7.4

package/docs/thinking/thinking-mode.md

@@ -0,0 +1,366 @@
+# Руководство по интеграции функциональности мышления (Thinking Mode)
+
+В этом документе описывается полный процесс интеграции функциональности мышления в клиентские приложения с использованием SDK версии 1.7.2.
+
+## Обзор функциональности
+
+**Режим мышления** (Thinking Mode) - это расширенная функциональность, которая позволяет получать доступ к промежуточным рассуждениям языковой модели в процессе формирования ответа. Это дает следующие преимущества:
+
+- Прозрачность в процессе генерации ответа
+- Отладка и улучшение качества ответов
+- Возможность показать пользователю как модель пришла к своему решению
+- Поэтапное отображение процесса мышления в реальном времени (через WebSocket)
+
+## Архитектура взаимодействия
+
+```
+Client (SDK) <--WebSocket--> NestJS Server <--HTTP Stream--> Anthropic API
+```
+
+Существует два способа работы с функциональностью мышления:
+
+1. **REST API** - синхронный режим, где ответ возвращается после завершения генерации
+2. **WebSocket** - потоковый режим, с получением событий мышления в реальном времени
+
+## Интеграция через REST API
+
+Простейший способ получить доступ к мышлению модели - использовать REST API:
+
+```javascript
+const response = await sdk.chat.chat([
+  { role: 'user', content: 'Как работает алгоритм быстрой сортировки?' }
+], {
+  model: 'claude-3-7-sonnet-20240229',
+  thinking: true
+});
+
+// Ход мыслей доступен в свойстве thinking первого элемента choices
+const thinking = response.choices[0].thinking;
+```
+
+## Интеграция через WebSocket (рекомендуемый подход)
+
+Интеграция через WebSocket позволяет получать события мышления в реальном времени и показывать пользователю как модель формирует ответ шаг за шагом.
+
+### Шаг 1: Инициализация SDK и подключение WebSocket
+
+```javascript
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'ваш-ключ-api'
+});
+
+// Подключаем WebSocket
+await sdk.chat.connectWebSocket();
+```
+
+### Шаг 2: Определение обработчика событий
+
+```javascript
+// Функция обработки событий
+function handleEvent(eventType, data) {
+  switch(eventType) {
+    case 'thinking_delta':
+      // Новый фрагмент мышления
+      console.log('Мышление:', data.text);
+      break;
+    
+    case 'text_delta':
+      // Новый фрагмент ответа
+      console.log('Ответ:', data.text);
+      break;
+      
+    case 'message_start':
+      console.log('Начало сообщения');
+      break;
+      
+    case 'message_stop':
+      console.log('Завершение ответа');
+      break;
+  }
+}
+```
+
+### Шаг 3: Отправка запроса с потоковой передачей мышления
+
+```javascript
+// Сообщения для отправки
+const messages = [
+  { role: 'user', content: 'Как реализовать алгоритм сортировки слиянием?' }
+];
+
+// Опции запроса
+const options = {
+  model: 'claude-3-7-sonnet-20240229',
+  thinking: true,           // Активируем режим мышления
+  temperature: 0.7
+};
+
+// Отправляем запрос с потоковым мышлением
+const response = await sdk.chat.streamChatWithThinking(
+  messages,
+  options,
+  handleEvent
+);
+
+console.log(`Запрос успешно отправлен. Socket ID: ${response.socketId}`);
+```
+
+### Шаг 4: Отключение от сервера после использования
+
+```javascript
+// Отключаемся от WebSocket сервера
+await sdk.chat.disconnectWebSocket();
+```
+
+## Полный пример интеграции в клиентское приложение
+
+```javascript
+class ThinkingModeIntegration {
+  constructor(apiKey, baseURL) {
+    this.sdk = new CodeSolverSDK({
+      baseURL,
+      apiKey
+    });
+    
+    this.thinkingText = '';
+    this.responseText = '';
+    this.isProcessing = false;
+  }
+  
+  // Инициализация и подключение к WebSocket
+  async connect() {
+    const response = await this.sdk.chat.connectWebSocket();
+    return response.socketId;
+  }
+  
+  // Отправка запроса с мышлением
+  async sendWithThinking(messages, options = {}) {
+    this.isProcessing = true;
+    this.thinkingText = '';
+    this.responseText = '';
+    
+    // Настраиваем опции по умолчанию
+    const defaultOptions = {
+      model: 'claude-3-7-sonnet-20240229',
+      thinking: true,
+      temperature: 0.7
+    };
+    
+    const mergedOptions = { ...defaultOptions, ...options };
+    
+    try {
+      // Отправляем запрос с обработчиком событий
+      const response = await this.sdk.chat.streamChatWithThinking(
+        messages,
+        mergedOptions,
+        this.handleEvent.bind(this)
+      );
+      
+      return response;
+    } catch (error) {
+      console.error('Ошибка при отправке запроса:', error);
+      this.isProcessing = false;
+      throw error;
+    }
+  }
+  
+  // Обработчик событий WebSocket
+  handleEvent(eventType, data) {
+    switch(eventType) {
+      case 'thinking_delta':
+        this.thinkingText += data.text || '';
+        
+        // Вызываем колбэк для обновления UI мышления
+        if (this.onThinkingUpdate) {
+          this.onThinkingUpdate(this.thinkingText);
+        }
+        break;
+      
+      case 'text_delta':
+        this.responseText += data.text || '';
+        
+        // Вызываем колбэк для обновления UI ответа
+        if (this.onResponseUpdate) {
+          this.onResponseUpdate(this.responseText);
+        }
+        break;
+        
+      case 'message_stop':
+        this.isProcessing = false;
+        
+        // Вызываем колбэк завершения
+        if (this.onComplete) {
+          this.onComplete({
+            thinking: this.thinkingText,
+            response: this.responseText
+          });
+        }
+        break;
+        
+      case 'error':
+        this.isProcessing = false;
+        
+        // Вызываем колбэк ошибки
+        if (this.onError) {
+          this.onError(data);
+        }
+        break;
+    }
+  }
+  
+  // Отключение от сервера
+  async disconnect() {
+    await this.sdk.chat.disconnectWebSocket();
+  }
+  
+  // Регистрация обработчиков событий
+  registerCallbacks({
+    onThinkingUpdate,
+    onResponseUpdate,
+    onComplete,
+    onError
+  }) {
+    this.onThinkingUpdate = onThinkingUpdate;
+    this.onResponseUpdate = onResponseUpdate;
+    this.onComplete = onComplete;
+    this.onError = onError;
+  }
+}
+
+// Пример использования
+async function main() {
+  const thinkingMode = new ThinkingModeIntegration(
+    'ваш-ключ-api',
+    'https://api.example.com'
+  );
+  
+  // Подключаемся к WebSocket
+  await thinkingMode.connect();
+  
+  // Регистрируем обработчики
+  thinkingMode.registerCallbacks({
+    onThinkingUpdate: (thinking) => {
+      console.log('Обновление мышления');
+      document.getElementById('thinkingOutput').innerHTML = thinking;
+    },
+    onResponseUpdate: (response) => {
+      console.log('Обновление ответа');
+      document.getElementById('finalAnswer').innerHTML = response;
+    },
+    onComplete: (result) => {
+      console.log('Завершено!');
+      document.getElementById('status').textContent = 'Готово';
+    },
+    onError: (error) => {
+      console.error('Ошибка:', error);
+      document.getElementById('status').textContent = 'Ошибка: ' + error.message;
+    }
+  });
+  
+  // Отправляем запрос
+  const messages = [
+    { role: 'user', content: 'Объясни, как работает алгоритм быстрой сортировки?' }
+  ];
+  
+  document.getElementById('status').textContent = 'Обработка...';
+  
+  await thinkingMode.sendWithThinking(messages);
+  
+  // После завершения работы
+  // await thinkingMode.disconnect();
+}
+```
+
+## Рекомендации по интеграции в UI
+
+При интеграции функциональности мышления в пользовательский интерфейс рекомендуется:
+
+1. **Показывать индикатор загрузки** пока идет инициализация соединения
+2. **Выделять шаги мышления** визуально отдельно от окончательного ответа
+3. **Предусмотреть автоскроллинг** для длинных цепочек рассуждений
+4. **Добавить возможность скрыть/показать** ход мыслей для пользователей
+5. **Обеспечить обработку отключения** от сервера (например, при закрытии вкладки/приложения)
+
+### Пример HTML/CSS структуры для отображения мышления
+
+```html
+<div class="thinking-container">
+  <div class="thinking-header">
+    <h3>Ход мыслей модели</h3>
+    <button id="toggleThinking">Скрыть</button>
+    <span id="status">Готово</span>
+  </div>
+  
+  <div id="thinkingOutput" class="thinking-steps">
+    <!-- Шаги мышления будут добавляться здесь -->
+  </div>
+  
+  <div class="final-answer">
+    <h3>Ответ модели</h3>
+    <div id="finalAnswer">
+      <!-- Финальный ответ будет здесь -->
+    </div>
+  </div>
+</div>
+```
+
+## Отладка и устранение проблем
+
+### Распространенные проблемы и их решения
+
+1. **Нет соединения WebSocket**
+   - Проверьте, правильно ли указан baseURL
+   - Убедитесь, что порт не блокируется фаерволом
+   - Проверьте наличие CORS ограничений
+   - Используйте метод `sdk.getWebSocketClient().diagnoseConnection()` для диагностики
+
+2. **Не приходят события мышления**
+   - Убедитесь, что активирован параметр `thinking: true`
+   - Проверьте, что соединение WebSocket активно
+   - Убедитесь, что используется поддерживаемая модель
+
+3. **Разрыв соединения в процессе работы**
+   - Увеличьте timeout в настройках WebSocket
+   - Включите механизм ping/pong для поддержания соединения
+   - Используйте опцию `websocket.reconnect: true` в настройках SDK
+
+### Включение расширенной диагностики
+
+В SDK версии 1.7.2 добавлены мощные инструменты для диагностики WebSocket соединений:
+
+```javascript
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'ваш-ключ-api',
+  websocket: {
+    debug: true,                 // Включаем подробное логирование
+    reconnect: true,             // Автоматическое переподключение
+    reconnectAttempts: 5,        // Количество попыток переподключения
+    reconnectDelay: 1000         // Задержка перед переподключением (мс)
+  }
+});
+
+// Включаем механизм ping/pong для поддержания соединения
+const wsClient = sdk.getWebSocketClient();
+wsClient.enablePingPong(30000, 3);
+
+// Диагностика состояния соединения
+const diagnostics = wsClient.diagnoseConnection();
+console.log('Диагностика соединения:', diagnostics);
+```
+
+## Версии и совместимость
+
+Функциональность мышления поддерживается в:
+- SDK версии 1.5.0 и выше
+- Потоковая передача мышления (streaming) полностью поддерживается с версии 1.7.2
+- Backend API версии 1.5.0 и выше
+- Совместима с моделями Claude 3 Opus, Claude 3 Sonnet и Claude 3 Haiku
+
+## Дополнительные ресурсы
+
+- [Архитектура потоковой передачи мышления](../THINKING_ARCHITECTURE.md)
+- [Руководство по потоковой передаче мышления](../streaming-thinking-guide.md)
+- [WebSocket API](../WEBSOCKET.md)
+- [Документация Anthropic по потоковой передаче](https://docs.anthropic.com/en/api/messages-streaming) 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solver-sdk",
-  "version": "1.7.2",
+  "version": "1.7.4",
   "description": "SDK для интеграции с Code Solver Backend API (совместимо с браузером и Node.js), с поддержкой функциональности мышления (Thinking Mode)",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -24,7 +24,8 @@
   "files": [
     "dist/**/*",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs/**/*"
   ],
   "scripts": {
     "clean": "rimraf dist",