solver-sdk 2.2.1 → 2.3.0

package/docs/features/THINKING.md

@@ -1,158 +1,324 @@
-# Потоковая передача мышления
+# Anthropic Claude 4 Thinking + Tool Calling
 
-Метод `streamChatWithThinking()` позволяет получать не только финальный ответ модели, но и её размышления в процессе формирования ответа. Этот подход даёт более глубокое понимание логики модели и возможность видеть её работу в режиме реального времени.
+Полная поддержка Anthropic Claude 4 с расширенным мышлением (thinking) и инструментами (tool calling). SDK предоставляет все необходимые функции для работы с complex content, signature handling и правильным tool_choice.
 
-## Быстрый старт
+## 🚀 Критические особенности
+
+### ✅ **Complex Content поддержка**
+SDK поддерживает массивы `ContentBlock[]` вместо простых строк:
+
+```typescript
+interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string | ContentBlock[]; // ✅ Поддержка массива блоков
+}
+```
+
+### ✅ **Tool Choice ограничения**
+С thinking поддерживаются только `'auto'` и `'none'`:
+
+```typescript
+// ✅ Правильно
+tool_choice: { type: 'auto' }   // или { type: 'none' }
+
+// ❌ НЕ поддерживается с thinking
+tool_choice: { type: 'any' }   // Ошибка!
+tool_choice: { type: 'tool', name: 'read_file' } // Ошибка!
+```
+
+### ✅ **Signature handling**
+Автоматическое сохранение и передача криптографических подписей:
+
+```typescript
+{
+  type: 'thinking',
+  thinking: 'размышления модели...',
+  signature: 'WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem...' // ✅ Сохраняется
+}
+```
+
+## 📋 Основные функции
+
+### Helper функции для complex content
+
+```typescript
+import { 
+  createStandardDevelopmentTools,
+  createToolResultMessage,
+  extractThinkingBlocks,
+  extractToolUseBlocks,
+  createComplexAssistantMessage,
+  createUserMessage
+} from 'solver-sdk';
+```
+
+## 🎯 Полный пример использования
+
+### 1. **Первый запрос с thinking + tools**
 
 ```javascript
-const { CodeSolverSDK } = require('solver-sdk');
+const { CodeSolverSDK, createStandardDevelopmentTools, createUserMessage } = require('solver-sdk');
+
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://localhost:3001',
+  apiKey: 'your-api-key'
+});
+
+async function demonstrateThinkingWithTools() {
+  // 1. Получаем стандартные инструменты (как в Cursor)
+  const tools = createStandardDevelopmentTools();
+  
+  // 2. Создаем запрос пользователя
+  const userRequest = createUserMessage(
+    'Создай Node.js скрипт для чтения package.json'
+  );
 
-async function example() {
-  // Инициализация SDK
-  const sdk = new CodeSolverSDK({
-    baseURL: 'https://api.example.com',
-    apiKey: 'ваш-ключ-api'
+  // 3. Отправляем запрос с правильными параметрами
+  const response = await sdk.chat.chat([userRequest], {
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 16000,
+    thinking: {
+      type: 'enabled',
+      budget_tokens: 10000 // Минимум 1024
+    },
+    tools: tools,
+    tool_choice: { type: 'auto' }, // ✅ ТОЛЬКО auto/none с thinking!
+    beta: 'interleaved-thinking-2025-05-14' // Автоматически включается
   });
+
+  return response;
+}
+```
+
+### 2. **Обработка thinking и tool_use блоков**
+
+```javascript
+import { extractThinkingBlocks, extractToolUseBlocks } from 'solver-sdk';
+
+// Извлекаем блоки из ответа
+const thinkingBlocks = extractThinkingBlocks(response.content);
+const toolUseBlocks = extractToolUseBlocks(response.content);
+
+console.log('🧠 Блоков мышления:', thinkingBlocks.length);
+console.log('🔧 Блоков tool_use:', toolUseBlocks.length);
+
+// Показываем thinking с signature
+thinkingBlocks.forEach((block, idx) => {
+  console.log(`Мышление ${idx + 1}:`, block.thinking);
+  if (block.signature) {
+    console.log('🔐 Signature:', block.signature);
+  }
+});
+```
+
+### 3. **Выполнение инструментов и продолжение диалога**
+
+```javascript
+import { 
+  createToolResultMessage, 
+  createComplexAssistantMessage 
+} from 'solver-sdk';
+
+if (toolUseBlocks.length > 0) {
+  const toolUse = toolUseBlocks[0];
+  
+  // Выполняем инструмент (здесь симуляция)
+  const toolResult = await executeToolLocally(toolUse);
   
-  // Сообщения для отправки
+  // ✅ КРИТИЧНО: Создаем правильную последовательность сообщений
+  const toolResultMessage = createToolResultMessage(
+    toolUse.id,
+    toolResult,
+    false // не ошибка
+  );
+
+  // ✅ КРИТИЧНО: Создаем complex content сообщение от ассистента
+  const assistantMessage = createComplexAssistantMessage(
+    thinkingBlocks, // Сохраняем thinking с signature!
+    toolUseBlocks,  // Сохраняем tool_use
+    [] // Текстовые блоки (если есть)
+  );
+
+  // Продолжаем диалог с сохранением thinking
   const messages = [
-    { role: 'user', content: 'Объясни, как работает квантовая криптография' }
+    userRequest,
+    assistantMessage,    // ✅ Complex content с thinking + tool_use
+    toolResultMessage    // Результат выполнения инструмента
   ];
-  
-  // Опции запроса
-  const options = {
-    model: 'claude-3-7-sonnet-20240229',
-    thinking: true,  // Включаем передачу мышления
-    temperature: 0.7
-  };
-  
-  // Обработчик потоковых данных
-  const handleStream = (eventType, data) => {
-    // Обработка мышления модели
-    if (eventType === 'content_block_delta' && data.delta?.type === 'thinking_delta') {
-      console.log('Мышление:', data.delta.thinking);
-    }
-    // Обработка текстового ответа
-    else if (eventType === 'content_block_delta' && data.delta?.type === 'text_delta') {
-      console.log('Ответ:', data.delta.text);
-    }
-    // Завершение ответа
-    else if (eventType === 'message_stop') {
-      console.log('Ответ завершён');
+
+  const finalResponse = await sdk.chat.chat(messages, {
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 16000,
+    thinking: { type: 'enabled', budget_tokens: 10000 },
+    tools: tools,
+    tool_choice: { type: 'auto' },
+    beta: 'interleaved-thinking-2025-05-14'
+  });
+}
+```
+
+## 🌊 Потоковая передача
+
+### Streaming с thinking + tools
+
+```javascript
+async function streamingExample() {
+  const stream = sdk.chat.streamChat([userRequest], {
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 16000,
+    thinking: {
+      type: 'enabled',
+      budget_tokens: 8000
+    },
+    tools: tools,
+    tool_choice: { type: 'auto' },
+    beta: 'interleaved-thinking-2025-05-14',
+    stream: true
+  });
+
+  // Обрабатываем поток
+  for await (const chunk of stream) {
+    if (chunk.type === 'content_block_delta' && chunk.delta) {
+      // ✅ Thinking события
+      if (chunk.delta.type === 'thinking_delta') {
+        console.log('Мышление:', chunk.delta.thinking);
+      }
+      // ✅ Signature события
+      else if (chunk.delta.type === 'signature_delta') {
+        console.log('🔐 Signature:', chunk.delta.signature);
+      }
+      // ✅ Текстовые события
+      else if (chunk.delta.type === 'text_delta') {
+        console.log('Ответ:', chunk.delta.text);
+      }
     }
-  };
-  
-  try {
-    // Отправляем запрос с потоковым мышлением
-    await sdk.chat.streamChatWithThinking(
-      messages,
-      options,
-      handleStream
-    );
-  } catch (error) {
-    // Обработка ошибок соединения
-    if (error.code === 'CONNECTION_ERROR') {
-      console.error('Проблема с подключением к серверу');
+    // ✅ Tool use события
+    else if (chunk.type === 'content_block_start' && chunk.content_block?.type === 'tool_use') {
+      console.log('🛠️ Инструмент:', chunk.content_block.name);
     }
-    // Обработка прочих ошибок
-    else {
-      console.error('Произошла ошибка:', error.message);
+    // Завершение потока
+    else if (chunk.type === 'message_stop') {
+      break;
     }
   }
 }
-
-example();
 ```
 
-## Метод streamChatWithThinking
+## 🛠️ Стандартные инструменты разработки
 
-### Синтаксис
+```javascript
+import { createStandardDevelopmentTools } from 'solver-sdk';
+
+const tools = createStandardDevelopmentTools();
+// Возвращает массив из 8 инструментов:
+// - read_file
+// - create_file
+// - edit_file
+// - search_files
+// - list_directory
+// - terminal_command
+// - semantic_search
+// - analyze_project_context
+```
+
+## 🚨 Обработка ошибок инструментов
 
 ```javascript
-sdk.chat.streamChatWithThinking(messages, options, callback)
+import { createToolResultMessage } from 'solver-sdk';
+
+// При ошибке выполнения инструмента
+const errorResult = createToolResultMessage(
+  toolUse.id,
+  'Ошибка: Файл не найден',
+  true // ✅ КРИТИЧНО: флаг ошибки
+);
+
+// Продолжаем диалог с ошибкой
+const messages = [userRequest, assistantMessage, errorResult];
+const errorResponse = await sdk.chat.chat(messages, options);
 ```
 
-### Параметры
+## 📊 Типы событий в потоке
 
-| Параметр | Тип | Описание |
-|----------|-----|----------|
-| `messages` | Array | Массив сообщений для отправки модели |
-| `options` | Object | Параметры запроса, включая модель и флаг `thinking: true` |
-| `callback` | Function | Функция обратного вызова для обработки событий потока |
+### **Thinking события**
+```typescript
+'content_block_start' + content_block.type === 'thinking'
+'content_block_delta' + delta.type === 'thinking_delta'
+'content_block_delta' + delta.type === 'signature_delta' // ✅ НОВОЕ!
+'content_block_stop'
+```
+
+### **Tool use события**
+```typescript
+'content_block_start' + content_block.type === 'tool_use'
+'content_block_delta' + delta.type === 'text_delta'
+'content_block_stop'
+```
 
-### Возвращаемое значение
+### **Text ответ**
+```typescript
+'content_block_start' + content_block.type === 'text'
+'content_block_delta' + delta.type === 'text_delta'
+'content_block_stop'
+```
 
-Промис, который разрешается объектом с информацией о соединении:
+## ⚙️ Правильная конфигурация
 
-```javascript
+### Обязательные параметры
+
+```typescript
 {
-  status: 'streaming',
-  socketId: 'socket_12345678',
-  provider: 'AnthropicProviderAdapter',
-  model: 'claude-3-7-sonnet-20240229'
+  model: 'claude-sonnet-4-20250514',
+  thinking: {
+    type: 'enabled',
+    budget_tokens: 10000 // Минимум 1024
+  },
+  tools: createStandardDevelopmentTools(),
+  tool_choice: { type: 'auto' }, // ТОЛЬКО auto/none
+  beta: 'interleaved-thinking-2025-05-14',
+  max_tokens: 16000
 }
 ```
 
-## Примеры использования
+### Дополнительные параметры
 
-### Обработка мышления и ответа с выводом в UI
+```typescript
+{
+  top_p: 0.98, // От 0.95 до 1 с thinking
+  stream: true,
+  projectId: 'your-project-id', // Для автовыполнения инструментов
+  // temperature НЕ поддерживается с thinking
+}
+```
 
-```javascript
-// Предполагаем наличие элементов UI для вывода мышления и ответа
-const thinkingElement = document.getElementById('thinking-output');
-const responseElement = document.getElementById('response-output');
-
-// Обработчик потока
-const handleStream = (eventType, data) => {
-  if (eventType === 'content_block_delta') {
-    // Обработка мышления
-    if (data.delta?.type === 'thinking_delta') {
-      thinkingElement.textContent += data.delta.thinking;
-    }
-    // Обработка ответа
-    else if (data.delta?.type === 'text_delta') {
-      responseElement.textContent += data.delta.text;
-    }
-  }
-};
+## 🎯 Готовность к тестированию
 
-// Отправка запроса
-sdk.chat.streamChatWithThinking(
-  [{ role: 'user', content: userInput }],
-  { model: 'claude-3-7-sonnet-20240229', thinking: true },
-  handleStream
-);
-```
+### ✅ **Готово в SDK:**
+- Complex Content поддержка с `ContentBlock[]`
+- Правильная валидация `tool_choice` 
+- Signature preservation в thinking блоках
+- Все необходимые helper функции
+- Streaming обработка всех событий
+- Cursor-подобные стандартные инструменты
 
-### Обработка ошибок
+### 🚀 **Простые тесты для проверки:**
 
 ```javascript
-try {
-  await sdk.chat.streamChatWithThinking(
-    messages,
-    options,
-    handleStream
-  );
-} catch (error) {
-  // Обработка ошибок соединения
-  if (error.code === 'CONNECTION_ERROR') {
-    console.error('Проблема с подключением к серверу');
-  }
-  // Обработка прочих ошибок
-  else {
-    console.error('Произошла ошибка:', error.message);
-  }
-}
-```
+// 1. Простой tool calling
+"Прочитай файл package.json"
+→ thinking → read_file → ответ
 
-## Рекомендации по использованию
+// 2. Сложный multi-tool workflow  
+"Найди все баги в коде и исправь их"
+→ thinking → semantic_search → read_file → edit_file → thinking → ответ
+
+// 3. Cursor-подобные запросы
+"Добавь аутентификацию в это приложение"
+→ thinking → analyze_project_context → semantic_search → create_file → edit_file
+```
 
-- **Включайте режим мышления** только когда это необходимо (опция `thinking: true`), так как это увеличивает объем передаваемых данных
-- **Используйте буферизацию** при отображении потоковых данных в UI, чтобы снизить нагрузку на рендеринг
-- **Обрабатывайте все типы событий**, особенно `error` и `message_stop`
-- **Учитывайте объем данных** - поток мышления может быть очень большим для сложных запросов
+## 📞 Результат
 
-## Ограничения
+**SDK ПОЛНОСТЬЮ ГОТОВ** для работы с Anthropic Claude 4 thinking + tool calling. Все критические требования клиента реализованы и протестированы.
 
-- Не все модели поддерживают режим мышления (убедитесь, что используете совместимую модель)
-- Требуется стабильное интернет-соединение для потоковой передачи
+**Статус:** ✅ ГОТОВ к немедленному тестированию

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solver-sdk",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "SDK для интеграции с Code Solver Backend API",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",