solver-sdk 1.7.4 → 1.7.6

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

@@ -1,164 +0,0 @@
-# Руководство: Потоковый чат с 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 соединение для нескольких запросов. 

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)