solver-sdk 1.7.3 → 1.7.5

package/docs/thinking/thinking-mode.md

@@ -1,366 +0,0 @@
-# Руководство по интеграции функциональности мышления (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)