Создание адаптера для ИИ-ассистента

// Библиотека OpenAI доступна для импорта. Дополнительной установки пакетов для неё не требуется.
const OpenAI = require('openai');

// Адаптер с поддержкой собственного tool: LLM может вызвать внешний API,
// а результат вернуть в диалог и (опционально) прикрепить ссылки в relatedContent.
class CustomToolAdapter {
  // Кеш OpenAI-клиентов по apiKey. Нужен, чтобы не создавать клиент на каждый запрос.
  clients = new Map();

  // Максимальное число раундов «модель → tool → модель».
  maxToolRounds = 10;

  // Получение или создание OpenAI-клиента для указанного ключа и URL-адреса.
  getClient(apiKey, baseURL) {
    const client = this.clients.get(apiKey);
    if (client) {
      return client;
    }

    const newClient = new OpenAI({
      apiKey,
      baseURL,
    });
    this.clients.set(apiKey, newClient);
    return newClient;
  }

  // Приведение ответа к формату, который ожидает сервер чата.
  mapResponse(outputText, relatedContent, totalTokens) {
    return {
      outputText,
      relatedContent,
      totalTokens,
      output: [
        {
          role: 'assistant',
          content: [{ type: 'text', text: outputText }],
          status: 'completed',
        },
      ],
    };
  }

  // Вызов внешнего tool по HTTP. URL-адрес и формат ответа настраиваются под ваш сервис.
  async callTool(content) {
    const response = await fetch(<CUSTOM_TOOL_URL>, {
      method: 'POST',
      body: JSON.stringify({ question: content }),
    });
    const data = await response.json();
    return data;
  }

  // Извлечение аргумента question из JSON, который модель передала в tool call
  getArgForTool(toolCall) {
    try {
      const parsedArgs = JSON.parse(toolCall.function.arguments);
      return parsedArgs.question ?? '';
    } catch {
      return '';
    }
  }

  // Оставляем только function tool calls, отбрасывая прочие типы.
  getFunctionToolCalls(toolCalls) {
    return toolCalls.filter((item) => item.type === 'function');
  }

  // Сборка messages для chat.completions: system prompt + история диалога.
  getChatMessages(params) {
    const inputMessages = params.input.map((item) => ({
      role: item.role,
      content: item.content,
    }));

    if (!params.systemPrompt) {
      return inputMessages;
    }

    return [
      {
        role: 'system',
        content: params.systemPrompt,
      },
      ...inputMessages,
    ];
  }

  // Описание tool для модели. Замените заглушки на реальные name и description.
  getTools() {
    return [
      {
        type: 'function',
        function: {
          name: <TOOL NAME>,
          description: <CUSTOM DESC>,
          strict: true,
          parameters: {
            type: 'object',
            properties: {
              question: {
                type: 'string',
                description: <CUSTOM DESC>,
              },
            },
            required: ['question'],
            additionalProperties: false,
          },
        },
      },
    ];
  }

  // Имя адаптера. Именно на него ориентируется сервер чата в настройках проекта.
  getName() {
    return 'custom-tool';
  }

  // Список моделей для выбора в настройках (опциональный метод)
  getModels() {
    return ['gpt-oss-20b/latest', 'gpt-oss-120b/latest'];
  }

  // Получение ответа от LLM без SSE, с циклом tool calling
  async getCompletion(params) {
    const client = this.getClient(params.apiKey, params.apiUrl);
    let messages = this.getChatMessages(params);
    let lastAssistantText = '';

    // Ссылки на документы, которые вернул tool (попадут в relatedContent.links)
    const answerRelatedContent = {
      links: [],
    };

    // Суммарное число токенов по всем раундам диалога.
    let totalTokens = 0;

    for (let round = 0; round < this.maxToolRounds; round++) {
      // Запрос к модели с описанием доступных tools.
      const completion = await client.chat.completions.create(
        {
          model: params.model,
          messages,
          tools: this.getTools(),
          parallel_tool_calls: true,
          stream: false,
        },
        // abortSignal позволяет прервать запрос снаружи.
        { signal: params.abortSignal },
      );

      // Накапливаем токены из usage очередного ответа модели.
      totalTokens += completion.usage?.total_tokens || 0;

      const assistantMessage = completion.choices[0].message;
      lastAssistantText = assistantMessage.content ?? lastAssistantText;

      const toolCalls = this.getFunctionToolCalls(
        assistantMessage.tool_calls ?? [],
      );

      // Модель вернула финальный текст без вызова tools — завершаем.
      if (toolCalls.length === 0) {
        const result = this.mapResponse(
          assistantMessage.content ?? '',
          answerRelatedContent,
          totalTokens,
        );
        return result;
      }

      // Выполняем каждый tool call и собираем ответы для следующего раунда.
      const toolOutputs = [];
      for (const item of toolCalls) {
        if (item.function.name === <TOOL NAME>) {
          const question = this.getArgForTool(item);
          const toolResponse = await this.callTool(question);

          // Добавляем ссылки из ответа tool, если они есть
          answerRelatedContent.links?.push(...toolResponse.useddocs);

          toolOutputs.push({
            role: 'tool',
            tool_call_id: item.id,
            content: toolResponse.answer,
          });
        }
      }

      // Дописываем в историю: сообщение ассистента с tool_calls и ответы tools.
      messages = [
        ...messages,
        {
          role: 'assistant',
          content: assistantMessage.content ?? null,
          tool_calls: toolCalls,
        },
        ...toolOutputs,
      ];
    }

    // Если исчерпали maxToolRounds — возвращаем последний известный текст.
    if (!lastAssistantText.trim()) {
      throw new Error(
        'Completion not generated: max tool rounds exceeded without answer',
      );
    }

    const result = this.mapResponse(
      lastAssistantText,
      answerRelatedContent,
      totalTokens,
    );
    return result;
  }

  // Потоковая генерация (SSE) с поддержкой tool calling.
  async *getCompletionStream(params) {
    const client = this.getClient(params.apiKey, params.apiUrl);
    let messages = this.getChatMessages(params);
    let lastAssistantText = '';

    const answerRelatedContent = {
      links: [],
    };

    // Суммарное число токенов по всем раундам диалога.
    let totalTokens = 0;

    for (let round = 0; round < this.maxToolRounds; round++) {
      const stream = await client.chat.completions.create(
        {
          model: params.model,
          messages,
          stream: true,
          // Без include_usage usage в стриме не приходит.
          stream_options: { include_usage: true },
          tools: this.getTools(),
          parallel_tool_calls: true,
        },
        { signal: params.abortSignal },
      );

      let finishReason = null;
      let content = '';
      // Собираем tool calls по индексу из stream-дельт.
      const toolCallsByIndex = new Map();

      for await (const event of stream) {
        // usage обычно приходит отдельным финальным событием с пустым choices,
        // поэтому считаем токены до проверки choice/continue.
        if (event.usage?.total_tokens !== undefined) {
          totalTokens += event.usage.total_tokens;
        }

        const choice = event.choices.at(0);
        if (!choice) {
          continue;
        }

        const delta = choice.delta;

        // Текстовые фрагменты ответа — отдаём клиенту как text_delta.
        if (delta.content) {
          content += delta.content;
          yield { type: 'text_delta', delta: delta.content };
        }

        // Постепенная сборка tool_calls из stream.
        if (delta.tool_calls) {
          for (const toolCallPart of delta.tool_calls) {
            const current = toolCallsByIndex.get(toolCallPart.index) ?? {
              id: toolCallPart.id ?? '',
              type: 'function',
              function: { name: '', arguments: '' },
            };

            if (toolCallPart.id) {
              current.id = toolCallPart.id;
            }
            if (toolCallPart.function?.name) {
              current.function.name = toolCallPart.function.name;
            }
            if (toolCallPart.function?.arguments) {
              current.function.arguments += toolCallPart.function.arguments;
            }

            toolCallsByIndex.set(toolCallPart.index, current);
          }
        }

        if (choice.finish_reason) {
          finishReason = choice.finish_reason;
        }
      }

      lastAssistantText = content || lastAssistantText;

      // Поток оборвался без finish_reason — выходим.
      if (!finishReason) {
        return;
      }

      const toolCalls = [...toolCallsByIndex.values()];

      // Финальный ответ без tools — завершаем stream событием completed.
      if (toolCalls.length === 0) {
        const response = this.mapResponse(
          content,
          answerRelatedContent,
          totalTokens,
        );
        yield {
          type: 'completed',
          response,
        };
        return;
      }

      // Выполняем tools и готовим следующий раунд диалога.
      const toolOutputs = [];
      for (const item of toolCalls) {
        if (item.function.name === <TOOL NAME>) {
          const question = this.getArgForTool(item);

          // Уведомляем UI о вызове инструмента (опционально).
          yield {
            type: 'tool_call',
            tool: 'doc',
          };

          const toolResponse = await this.callTool(question);
          answerRelatedContent.links?.push(...toolResponse.useddocs);

          toolOutputs.push({
            role: 'tool',
            tool_call_id: item.id,
            content: toolResponse.answer,
          });
        }
      }

      messages = [
        ...messages,
        {
          role: 'assistant',
          content: content || null,
          tool_calls: toolCalls,
        },
        ...toolOutputs,
      ];
    }

    // Запасной вариант, если достигнут лимит раундов.
    if (!lastAssistantText.trim()) {
      yield { type: 'failed' };
      return;
    }

    const result = this.mapResponse(
      lastAssistantText,
      answerRelatedContent,
      totalTokens,
    );
    yield {
      type: 'completed',
      response: result,
    };
  }
}

module.exports = { CustomToolAdapter };