@robota-sdk/agent-provider 3.0.0-beta.64

package/src/qwen/provider.ts

@@ -0,0 +1,293 @@
+import OpenAI from 'openai';
+import { AbstractAIProvider, SilentLogger } from '@robota-sdk/agent-core';
+import type { IChatOptions, TTextDeltaCallback, TUniversalMessage } from '@robota-sdk/agent-core';
+import {
+  assembleOpenAICompatibleStream,
+  convertToOpenAICompatibleMessages,
+  convertToOpenAICompatibleTools,
+  observeProviderNativeRawPayloadStream,
+  OpenAICompatibleResponseParser,
+} from '../shared/openai-compatible/index.js';
+import type { IOpenAICompatibleError } from '../shared/openai-compatible/index.js';
+import {
+  DEFAULT_QWEN_PROVIDER_BASE_URL,
+  DEFAULT_QWEN_PROVIDER_RESPONSES_BASE_URL,
+} from './defaults';
+import { hasQwenBuiltInWebTools } from './responses-converter';
+import { chatStreamWithQwenResponsesApi, chatWithQwenResponsesApi } from './responses-chat';
+import { getQwenProviderCapabilities } from './provider-capabilities';
+import { qwenChatWithStreamingAssembly } from './provider-streaming-assembly';
+import type { IQwenProviderOptions } from './types';
+
+export class QwenProvider extends AbstractAIProvider {
+  override readonly name = 'qwen';
+  override readonly version = '1.0.0';
+
+  private readonly client?: OpenAI;
+  private readonly responsesClient?: OpenAI;
+  private readonly options: IQwenProviderOptions;
+  private readonly responseParser: OpenAICompatibleResponseParser;
+
+  onTextDelta?: TTextDeltaCallback;
+
+  constructor(options: IQwenProviderOptions) {
+    super(options.logger || SilentLogger);
+    this.options = options;
+
+    if (options.executor) {
+      this.executor = options.executor;
+    }
+
+    if (!this.executor) {
+      if (options.client) {
+        this.client = options.client;
+        this.responsesClient = options.client;
+      } else if (options.apiKey) {
+        this.client = new OpenAI({
+          apiKey: options.apiKey,
+          baseURL: options.baseURL ?? DEFAULT_QWEN_PROVIDER_BASE_URL,
+          ...(options.timeout !== undefined && { timeout: options.timeout }),
+        });
+        this.responsesClient = new OpenAI({
+          apiKey: options.apiKey,
+          baseURL: options.responsesBaseURL ?? DEFAULT_QWEN_PROVIDER_RESPONSES_BASE_URL,
+          ...(options.timeout !== undefined && { timeout: options.timeout }),
+        });
+      } else {
+        throw new Error('Either Qwen client, apiKey, or executor is required');
+      }
+    }
+
+    this.responseParser = new OpenAICompatibleResponseParser({ logger: this.logger });
+  }
+
+  override async chat(
+    messages: TUniversalMessage[],
+    options?: IChatOptions,
+  ): Promise<TUniversalMessage> {
+    this.validateMessages(messages);
+    this.validateNativeWebTools(options?.nativeWebTools);
+
+    if (this.executor) {
+      return this.chatViaExecutor(messages, options);
+    }
+
+    if (this.shouldUseResponsesApi()) {
+      return this.chatViaResponsesApi(messages, options, this.getResponsesClient());
+    }
+
+    return this.chatViaChatCompletions(messages, options, this.getClient());
+  }
+
+  private async chatViaExecutor(
+    messages: TUniversalMessage[],
+    options: IChatOptions | undefined,
+  ): Promise<TUniversalMessage> {
+    try {
+      return await this.executeViaExecutorOrDirect(messages, options);
+    } catch (error) {
+      this.logger.error(
+        'Qwen Provider executor chat error:',
+        error instanceof Error ? error.message : String(error),
+      );
+      throw error;
+    }
+  }
+
+  private async chatViaResponsesApi(
+    messages: TUniversalMessage[],
+    options: IChatOptions | undefined,
+    client: OpenAI,
+  ): Promise<TUniversalMessage> {
+    this.validateTools(options?.tools);
+    return chatWithQwenResponsesApi({
+      client,
+      messages,
+      chatOptions: options,
+      defaultModel: this.options.defaultModel,
+      builtInWebTools: this.options.builtInWebTools,
+      onTextDelta: this.onTextDelta,
+    });
+  }
+
+  private async chatViaChatCompletions(
+    messages: TUniversalMessage[],
+    options: IChatOptions | undefined,
+    client: OpenAI,
+  ): Promise<TUniversalMessage> {
+    try {
+      const requestParams = this.buildRequestParams(messages, options);
+      const textDeltaCb = options?.onTextDelta ?? this.onTextDelta;
+      if (textDeltaCb) {
+        return qwenChatWithStreamingAssembly(
+          client,
+          { ...requestParams, stream: true },
+          { ...options, onTextDelta: textDeltaCb },
+        );
+      }
+
+      options?.onProviderNativeRawPayload?.({
+        provider: 'qwen',
+        apiSurface: 'chat-completions',
+        payloadKind: 'request',
+        payload: requestParams,
+      });
+      const response = await client.chat.completions.create(requestParams);
+      options?.onProviderNativeRawPayload?.({
+        provider: 'qwen',
+        apiSurface: 'chat-completions',
+        payloadKind: 'response',
+        payload: response,
+      });
+      return this.responseParser.parseResponse(response);
+    } catch (error) {
+      const qwenError = error as IOpenAICompatibleError;
+      const errorMessage = qwenError.message || 'Qwen API request failed';
+      throw new Error(`Qwen chat failed: ${errorMessage}`);
+    }
+  }
+
+  override async *chatStream(
+    messages: TUniversalMessage[],
+    options?: IChatOptions,
+  ): AsyncIterable<TUniversalMessage> {
+    this.validateMessages(messages);
+    this.validateNativeWebTools(options?.nativeWebTools);
+
+    if (this.executor) {
+      try {
+        yield* this.executeStreamViaExecutorOrDirect(messages, options);
+        return;
+      } catch (error) {
+        this.logger.error(
+          'Qwen Provider executor stream error:',
+          error instanceof Error ? error.message : String(error),
+        );
+        throw error;
+      }
+    }
+
+    if (!this.client) {
+      throw new Error(
+        'Qwen client not available. Either provide a client/apiKey or use an executor.',
+      );
+    }
+
+    if (this.shouldUseResponsesApi()) {
+      this.validateTools(options?.tools);
+      yield* chatStreamWithQwenResponsesApi({
+        client: this.responsesClient,
+        messages,
+        chatOptions: options,
+        defaultModel: this.options.defaultModel,
+        builtInWebTools: this.options.builtInWebTools,
+        onTextDelta: this.onTextDelta,
+      });
+      return;
+    }
+
+    try {
+      const requestParams = this.buildStreamingRequestParams(messages, options);
+      options?.onProviderNativeRawPayload?.({
+        provider: 'qwen',
+        apiSurface: 'chat-completions',
+        payloadKind: 'request',
+        payload: requestParams,
+      });
+      const stream = await this.client.chat.completions.create(requestParams);
+
+      const observedStream = observeProviderNativeRawPayloadStream(stream, {
+        provider: 'qwen',
+        apiSurface: 'chat-completions',
+        onProviderNativeRawPayload: options?.onProviderNativeRawPayload,
+      });
+
+      for await (const chunk of this.streamWithAbort(observedStream, options?.signal)) {
+        const universalMessage = this.responseParser.parseStreamingChunk(chunk);
+        if (universalMessage) {
+          yield universalMessage;
+        }
+      }
+    } catch (error) {
+      const qwenError = error as IOpenAICompatibleError;
+      const errorMessage = qwenError.message || 'Qwen API request failed';
+      throw new Error(`Qwen stream failed: ${errorMessage}`);
+    }
+  }
+
+  override supportsTools(): boolean {
+    return true;
+  }
+
+  override getCapabilities() {
+    return getQwenProviderCapabilities(this.options);
+  }
+
+  override validateConfig(): boolean {
+    return (
+      !!this.client && !!this.options && (!this.shouldUseResponsesApi() || !!this.responsesClient)
+    );
+  }
+
+  override async dispose(): Promise<void> {
+    // OpenAI-compatible Qwen clients do not need explicit cleanup.
+  }
+
+  private buildRequestParams(
+    messages: TUniversalMessage[],
+    options: IChatOptions | undefined,
+  ): OpenAI.Chat.ChatCompletionCreateParamsNonStreaming {
+    this.validateTools(options?.tools);
+    const model = options?.model ?? this.options.defaultModel;
+    if (!model) {
+      throw new Error(
+        'Model is required in chat options. Please specify a model in defaultModel configuration.',
+      );
+    }
+
+    const requestParams = {
+      model,
+      messages: convertToOpenAICompatibleMessages(messages),
+      ...(options?.temperature !== undefined && { temperature: options.temperature }),
+      ...(options?.maxTokens !== undefined && { max_tokens: options.maxTokens }),
+      ...(options?.tools && {
+        tools: convertToOpenAICompatibleTools(options.tools),
+        tool_choice: 'auto' as const,
+      }),
+    };
+
+    return requestParams as OpenAI.Chat.ChatCompletionCreateParamsNonStreaming;
+  }
+
+  private buildStreamingRequestParams(
+    messages: TUniversalMessage[],
+    options: IChatOptions | undefined,
+  ): OpenAI.Chat.ChatCompletionCreateParamsStreaming {
+    return {
+      ...this.buildRequestParams(messages, options),
+      stream: true,
+    } as OpenAI.Chat.ChatCompletionCreateParamsStreaming;
+  }
+
+  private shouldUseResponsesApi(): boolean {
+    return hasQwenBuiltInWebTools(this.options.builtInWebTools);
+  }
+
+  private getClient(): OpenAI {
+    if (!this.client) {
+      throw new Error(
+        'Qwen client not available. Either provide a client/apiKey or use an executor.',
+      );
+    }
+
+    return this.client;
+  }
+
+  private getResponsesClient(): OpenAI {
+    if (!this.responsesClient) {
+      throw new Error('Qwen Responses client not available for built-in web tools.');
+    }
+
+    return this.responsesClient;
+  }
+}

package/src/qwen/responses-chat.ts

@@ -0,0 +1,194 @@
+import { randomUUID } from 'node:crypto';
+import type OpenAI from 'openai';
+import type { IChatOptions, TTextDeltaCallback, TUniversalMessage } from '@robota-sdk/agent-core';
+import {
+  observeProviderNativeRawPayloadStream,
+  type IOpenAICompatibleError,
+} from '../shared/openai-compatible/index.js';
+import {
+  buildQwenResponsesTools,
+  convertToQwenResponsesInput,
+  getQwenBuiltInWebToolNames,
+} from './responses-converter';
+import { assembleQwenResponsesStream, parseQwenResponsesResponse } from './responses-parser';
+import type {
+  IQwenBuiltInWebToolsOptions,
+  IQwenResponsesRequestNonStreaming,
+  IQwenResponsesRequestStreaming,
+  TQwenResponsesStreamEvent,
+} from './types';
+
+export interface IQwenResponsesChatOptions {
+  client?: OpenAI;
+  messages: TUniversalMessage[];
+  chatOptions?: IChatOptions;
+  defaultModel?: string;
+  builtInWebTools?: IQwenBuiltInWebToolsOptions;
+  onTextDelta?: TTextDeltaCallback;
+}
+
+export async function chatWithQwenResponsesApi(
+  input: IQwenResponsesChatOptions,
+): Promise<TUniversalMessage> {
+  const textDeltaCb = input.chatOptions?.onTextDelta ?? input.onTextDelta;
+  if (textDeltaCb) {
+    return chatWithQwenResponsesStreamingAssembly({
+      ...input,
+      chatOptions: {
+        ...input.chatOptions,
+        onTextDelta: textDeltaCb,
+      },
+    });
+  }
+
+  if (!input.client) {
+    throw new Error('Qwen Responses client not available for built-in web tools.');
+  }
+
+  try {
+    const requestParams = buildResponsesRequestParams(input);
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'qwen',
+      apiSurface: 'responses',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const response = await input.client.responses.create(
+      requestParams as OpenAI.Responses.ResponseCreateParamsNonStreaming,
+      input.chatOptions?.signal ? { signal: input.chatOptions.signal } : undefined,
+    );
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'qwen',
+      apiSurface: 'responses',
+      payloadKind: 'response',
+      payload: response,
+    });
+    return parseQwenResponsesResponse(response, {
+      enabledBuiltInTools: getQwenBuiltInWebToolNames(input.builtInWebTools),
+    });
+  } catch (error) {
+    const qwenError = error as IOpenAICompatibleError;
+    const errorMessage = qwenError.message || 'Qwen Responses API request failed';
+    throw new Error(`Qwen responses failed: ${errorMessage}`);
+  }
+}
+
+export async function* chatStreamWithQwenResponsesApi(
+  input: IQwenResponsesChatOptions,
+): AsyncIterable<TUniversalMessage> {
+  const deltas: TUniversalMessage[] = [];
+  const result = await chatWithQwenResponsesStreamingAssembly({
+    ...input,
+    chatOptions: {
+      ...input.chatOptions,
+      onTextDelta: (delta) => {
+        input.chatOptions?.onTextDelta?.(delta);
+        deltas.push(createStreamDeltaMessage(delta));
+      },
+    },
+  });
+
+  for (const delta of deltas) {
+    yield delta;
+  }
+  yield {
+    ...result,
+    content: '',
+    metadata: {
+      ...result.metadata,
+      isStreamChunk: true,
+      isComplete: true,
+    },
+  };
+}
+
+async function chatWithQwenResponsesStreamingAssembly(
+  input: IQwenResponsesChatOptions,
+): Promise<TUniversalMessage> {
+  if (!input.client) {
+    throw new Error('Qwen Responses client not available for built-in web tools.');
+  }
+
+  try {
+    const requestParams = buildResponsesStreamingRequestParams(input);
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'qwen',
+      apiSurface: 'responses',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const stream = await input.client.responses.create(
+      requestParams as OpenAI.Responses.ResponseCreateParamsStreaming,
+      input.chatOptions?.signal ? { signal: input.chatOptions.signal } : undefined,
+    );
+    return assembleQwenResponsesStream({
+      stream: observeProviderNativeRawPayloadStream(
+        stream as AsyncIterable<TQwenResponsesStreamEvent>,
+        {
+          provider: 'qwen',
+          apiSurface: 'responses',
+          onProviderNativeRawPayload: input.chatOptions?.onProviderNativeRawPayload,
+        },
+      ),
+      enabledBuiltInTools: getQwenBuiltInWebToolNames(input.builtInWebTools),
+      onTextDelta: input.chatOptions?.onTextDelta,
+      signal: input.chatOptions?.signal,
+    });
+  } catch (error) {
+    const qwenError = error as IOpenAICompatibleError;
+    const errorMessage = qwenError.message || 'Qwen Responses streaming request failed';
+    throw new Error(`Qwen responses stream failed: ${errorMessage}`);
+  }
+}
+
+function buildResponsesRequestParams(
+  input: IQwenResponsesChatOptions,
+): IQwenResponsesRequestNonStreaming {
+  const model = input.chatOptions?.model ?? input.defaultModel;
+  if (!model) {
+    throw new Error(
+      'Model is required in chat options. Please specify a model in defaultModel configuration.',
+    );
+  }
+
+  const enabledBuiltInTools = getQwenBuiltInWebToolNames(input.builtInWebTools);
+  const tools = buildQwenResponsesTools(enabledBuiltInTools, input.chatOptions?.tools);
+
+  return {
+    model,
+    input: convertToQwenResponsesInput(input.messages),
+    ...(tools !== undefined && { tools }),
+    ...(input.chatOptions?.temperature !== undefined && {
+      temperature: input.chatOptions.temperature,
+    }),
+    ...(input.chatOptions?.maxTokens !== undefined && {
+      max_output_tokens: input.chatOptions.maxTokens,
+    }),
+    ...(input.builtInWebTools?.enableThinking !== undefined && {
+      enable_thinking: input.builtInWebTools.enableThinking,
+    }),
+  };
+}
+
+function buildResponsesStreamingRequestParams(
+  input: IQwenResponsesChatOptions,
+): IQwenResponsesRequestStreaming {
+  return {
+    ...buildResponsesRequestParams(input),
+    stream: true,
+  };
+}
+
+function createStreamDeltaMessage(delta: string): TUniversalMessage {
+  return {
+    id: randomUUID(),
+    role: 'assistant',
+    content: delta,
+    state: 'complete',
+    timestamp: new Date(),
+    metadata: {
+      isStreamChunk: true,
+      isComplete: false,
+    },
+  };
+}

package/src/qwen/responses-converter.ts

@@ -0,0 +1,104 @@
+import type { IAssistantMessage, IToolSchema, TUniversalMessage } from '@robota-sdk/agent-core';
+import type {
+  IQwenBuiltInWebToolsOptions,
+  IQwenResponsesFunctionTool,
+  IQwenResponsesMessageInput,
+  TQwenBuiltInWebToolName,
+  TQwenResponsesInputItem,
+  TQwenResponsesTool,
+} from './types';
+
+export function getQwenBuiltInWebToolNames(
+  options: IQwenBuiltInWebToolsOptions | undefined,
+): TQwenBuiltInWebToolName[] {
+  const tools: TQwenBuiltInWebToolName[] = [];
+  if (options?.webSearch === true || options?.webFetch === true) {
+    tools.push('web_search');
+  }
+  if (options?.webFetch === true) {
+    tools.push('web_extractor');
+  }
+  return tools;
+}
+
+export function hasQwenBuiltInWebTools(options: IQwenBuiltInWebToolsOptions | undefined): boolean {
+  return getQwenBuiltInWebToolNames(options).length > 0;
+}
+
+export function convertToQwenResponsesInput(
+  messages: TUniversalMessage[],
+): TQwenResponsesInputItem[] {
+  return messages.flatMap((message) => convertMessage(message));
+}
+
+export function buildQwenResponsesTools(
+  builtInWebTools: readonly TQwenBuiltInWebToolName[],
+  localTools: IToolSchema[] | undefined,
+): TQwenResponsesTool[] | undefined {
+  const tools: TQwenResponsesTool[] = [
+    ...builtInWebTools.map((type) => ({ type })),
+    ...convertToQwenResponsesFunctionTools(localTools),
+  ];
+  return tools.length > 0 ? tools : undefined;
+}
+
+function convertToQwenResponsesFunctionTools(
+  tools: IToolSchema[] | undefined,
+): IQwenResponsesFunctionTool[] {
+  return (
+    tools?.map((tool) => ({
+      type: 'function',
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    })) ?? []
+  );
+}
+
+function convertMessage(message: TUniversalMessage): TQwenResponsesInputItem[] {
+  if (message.role === 'user') {
+    return [createMessageInput('user', message.content)];
+  }
+  if (message.role === 'system') {
+    return [createMessageInput('system', message.content)];
+  }
+  if (message.role === 'tool') {
+    return [
+      {
+        type: 'function_call_output',
+        call_id: message.toolCallId,
+        output: message.content || '',
+      },
+    ];
+  }
+  return convertAssistantMessage(message);
+}
+
+function convertAssistantMessage(message: IAssistantMessage): TQwenResponsesInputItem[] {
+  const items: TQwenResponsesInputItem[] = [];
+  if (message.content && message.content.length > 0) {
+    items.push(createMessageInput('assistant', message.content));
+  }
+  for (const toolCall of message.toolCalls ?? []) {
+    items.push({
+      type: 'function_call',
+      call_id: toolCall.id,
+      name: toolCall.function.name,
+      arguments: toolCall.function.arguments,
+    });
+  }
+  if (items.length === 0) {
+    items.push(createMessageInput('assistant', ''));
+  }
+  return items;
+}
+
+function createMessageInput(
+  role: IQwenResponsesMessageInput['role'],
+  content: string | null,
+): IQwenResponsesMessageInput {
+  return {
+    role,
+    content: content ?? '',
+  };
+}