@agentscope-ai/agentscope 0.0.2

package/src/model/base.ts

@@ -0,0 +1,226 @@
+import { z } from 'zod';
+
+import { ChatResponse, StructuredResponse } from './response';
+import { FormatterBase } from '../formatter';
+import { getTextContent, Msg } from '../message';
+import { ToolChoice, ToolInputSchema, ToolSchema } from '../type';
+
+export interface ChatModelOptions {
+    modelName: string;
+    stream?: boolean;
+    maxRetries?: number;
+    fallbackModelName?: string;
+    formatter?: FormatterBase;
+}
+
+// The chat model call options interface
+export interface ChatModelCallOptions {
+    messages: Msg[];
+    tools?: ToolSchema[];
+    toolChoice?: ToolChoice;
+
+    // The additional options can be added as needed
+    [key: string]: unknown;
+}
+
+export interface ChatModelCallStructuredOptions {
+    messages: Msg[];
+    schema: z.ZodObject;
+}
+
+// Internal API request options after formatting
+export interface ChatModelRequestOptions<T> {
+    messages: T[];
+    tools?: ToolSchema[];
+    toolChoice?: ToolChoice;
+
+    // The additional options can be added as needed
+    [key: string]: unknown;
+}
+
+/**
+ * The base class for chat models.
+ */
+export abstract class ChatModelBase {
+    public modelName: string;
+    public stream: boolean;
+    public maxRetries: number;
+    public fallbackModelName?: string;
+    public formatter?: FormatterBase;
+    /**
+     * Initializes a new instance of the ChatModelBase class.
+     *
+     * @param options - The chat model options, including model name, streaming option, max retries, fallback
+     *  model name, and formatter.
+     *
+     * @param options.modelName
+     * @param options.stream
+     * @param options.maxRetries
+     * @param options.fallbackModelName
+     * @param options.formatter
+     */
+    protected constructor({
+        modelName,
+        stream,
+        maxRetries,
+        fallbackModelName,
+        formatter,
+    }: ChatModelOptions) {
+        this.modelName = modelName;
+        this.stream = stream ?? true;
+        this.maxRetries = maxRetries ?? 0;
+        this.fallbackModelName = fallbackModelName;
+        this.formatter = formatter;
+    }
+
+    /**
+     * Calls the chat model with the given messages.
+     * This is the main method to interact with the model.
+     *
+     * @param options - The chat model call options.
+     * @returns A promise that resolves to the model's response.
+     */
+    async call(
+        options: ChatModelCallOptions
+    ): Promise<ChatResponse | AsyncGenerator<ChatResponse>> {
+        // Format messages using the formatter if available
+        let formattedMessages: unknown[];
+        if (this.formatter) {
+            formattedMessages = await this.formatter.format({ msgs: options.messages });
+        } else {
+            // If no formatter is provided, pass messages as-is
+            formattedMessages = options.messages as unknown[];
+        }
+
+        const requestOptions: ChatModelRequestOptions<unknown> = {
+            ...options,
+            messages: formattedMessages,
+        };
+
+        let lastError: unknown;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                return await this._callAPI(this.modelName, requestOptions);
+            } catch (error) {
+                lastError = error;
+                if (attempt === this.maxRetries) {
+                    throw error;
+                } else {
+                    console.log(
+                        `Attempt ${attempt + 1} failed for model ${this.modelName}. Retrying...`
+                    );
+                }
+            }
+        }
+
+        // Use the fallback model if specified
+        if (this.fallbackModelName) {
+            console.log(
+                `Using fallback model ${this.fallbackModelName} after ${this.maxRetries} failed attempts.`
+            );
+            return await this._callAPI(this.fallbackModelName, requestOptions);
+        }
+
+        // This line should never be reached, but it ensures TypeScript knows the function always returns
+        throw lastError;
+    }
+
+    /**
+     * Abstract method to call the underlying API with the given parameters.
+     */
+    protected abstract _callAPI(
+        modelName: string,
+        options: ChatModelRequestOptions<unknown>
+    ): Promise<ChatResponse | AsyncGenerator<ChatResponse>>;
+
+    /**
+     * Format the AgentScope tool choice parameter to the expected API format.
+     *
+     * @param toolChoice - The tool choice option.
+     * @returns The formatted tool choice.
+     */
+    abstract _formatToolChoice(toolChoice: ToolChoice): unknown;
+
+    /**
+     * A heuristic method to count the number of the tokens
+     * Note the multimodal content is ignored in the token counting
+     * @param options
+     * @param options.messages
+     * @param options.tools
+     * @returns The estimated number of tokens in the input messages and tools.
+     */
+    async countTokens(options: { messages: Msg[]; tools?: ToolSchema[] }): Promise<number> {
+        let accText: string = '';
+        for (const msg of options.messages) {
+            accText += getTextContent(msg) || '';
+        }
+        if (options.tools) {
+            accText += JSON.stringify(options.tools);
+        }
+        const chineseMatches =
+            accText.match(/[\u4e00-\u9fff\u3400-\u4dbf\u{20000}-\u{2a6df}]/gu)?.length ?? 0;
+        const englishMatches = accText.match(/[a-zA-Z]+/g)?.length ?? 0;
+
+        return chineseMatches * 2 + englishMatches * 1.5;
+    }
+
+    /**
+     * Format the tool schemas to the expected API format.
+     * @param tools
+     * @returns The formatted tool schemas.
+     */
+    abstract _formatToolSchemas(tools: ToolSchema[]): unknown[];
+
+    /**
+     * A default implementation of the structured call method. For those supporting structured output, the model should
+     * override this method.
+     * @param options
+     * @returns The structured response from the model, which should conform to the provided Zod schema.
+     */
+    async callStructured(options: ChatModelCallStructuredOptions): Promise<StructuredResponse> {
+        // Prepare a tool schema that wraps the provided Zod schema
+        const toolSchema: ToolSchema = {
+            type: 'function',
+            function: {
+                name: 'GenerateStructuredResponse',
+                description: 'Generate required structured response by this toll.',
+                parameters: options.schema.toJSONSchema({
+                    target: 'openapi-3.0',
+                }) as ToolInputSchema,
+            },
+        };
+
+        const res = await this.call({
+            messages: options.messages,
+            tools: [toolSchema],
+            toolChoice: 'GenerateStructuredResponse',
+        });
+
+        let completedResponse: ChatResponse;
+        if (this.stream) {
+            while (true) {
+                const { value, done } = await (res as AsyncGenerator<ChatResponse>).next();
+                if (done) {
+                    completedResponse = value;
+                    break;
+                }
+            }
+        } else {
+            completedResponse = res as ChatResponse;
+        }
+
+        // Find the tool call
+        for (const block of completedResponse.content) {
+            if (block.type === 'tool_call' && block.name === 'GenerateStructuredResponse') {
+                const structuredContent = JSON.parse(block.input);
+                return {
+                    ...completedResponse,
+                    content: structuredContent,
+                    type: 'structured',
+                } as StructuredResponse;
+            }
+        }
+
+        throw new Error(`Failed to generate the structured response`);
+    }
+}

package/src/model/dashscope-model.test.ts

@@ -0,0 +1,335 @@
+import { DashScopeChatModel } from './dashscope-model';
+import { ChatResponse } from './response';
+import { createMsg } from '../message';
+
+// Mock fetch for streaming responses
+global.fetch = jest.fn();
+
+describe('DashScopeChatModel', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    test('Test stream generation with delta output', async () => {
+        // Mock streaming response with multiple chunks
+        // Chunk 1: First part of thinking
+        // Chunk 2: Second part of thinking
+        // Chunk 3: Tool call metadata (id, name) + first part of arguments
+        // Chunk 4: Second part of arguments
+        // Chunk 5: Usage info
+        const mockStreamChunks = [
+            'data:{"output":{"choices":[{"message":{"reasoning_content":"Mock thinking: Analyzing"}}]}}\n\n',
+            'data:{"output":{"choices":[{"message":{"reasoning_content":" the weather query for Beijing"}}]}}\n\n',
+            'data:{"output":{"choices":[{"message":{"tool_calls":[{"index":0,"id":"call-123","function":{"name":"get_current_weather","arguments":"{\\"location\\""}}]}}]}}\n\n',
+            'data:{"output":{"choices":[{"message":{"tool_calls":[{"index":0,"function":{"arguments":":\\"Beijing\\"}"}}]}}]}}\n\n',
+            'data:{"output":{"choices":[{"message":{}}]},"usage":{"input_tokens":100,"output_tokens":50}}\n\n',
+        ];
+
+        const mockReadableStream = new ReadableStream({
+            start(controller) {
+                mockStreamChunks.forEach(chunk =>
+                    controller.enqueue(new TextEncoder().encode(chunk))
+                );
+                controller.close();
+            },
+        });
+
+        (global.fetch as jest.Mock).mockResolvedValue({
+            ok: true,
+            body: mockReadableStream,
+        });
+
+        const model = new DashScopeChatModel({
+            modelName: 'qwen3.5-plus',
+            apiKey: 'test-api-key',
+            stream: true,
+            thinkingConfig: {
+                enableThinking: true,
+            },
+        });
+
+        const res = await model.call({
+            messages: [
+                createMsg({
+                    name: 'user',
+                    role: 'user',
+                    content: [
+                        {
+                            id: crypto.randomUUID(),
+                            type: 'text',
+                            text: "How's the weather today in Beijing?",
+                        },
+                    ],
+                }),
+            ],
+            tools: [
+                {
+                    type: 'function',
+                    function: {
+                        name: 'get_current_weather',
+                        description: 'Get the current weather in a given location',
+                        parameters: {
+                            type: 'object',
+                            properties: {
+                                location: {
+                                    type: 'string',
+                                    description: 'The city and state, e.g. San Francisco, CA',
+                                },
+                            },
+                            required: ['location'],
+                        },
+                    },
+                },
+            ],
+            toolChoice: 'get_current_weather',
+        });
+
+        const generator = res as AsyncGenerator<ChatResponse, ChatResponse>;
+        let completeResponse: ChatResponse | undefined;
+        const yieldedChunks: ChatResponse[] = [];
+
+        // Manual iteration to capture both yielded and returned values
+        while (true) {
+            const result = await generator.next();
+            if (result.done) {
+                completeResponse = result.value;
+                break;
+            }
+            yieldedChunks.push(result.value);
+        }
+
+        // Verify we received 5 yielded chunks (before the final return)
+        expect(yieldedChunks.length).toBe(5);
+
+        // Chunk 1: First part of thinking
+        expect(yieldedChunks[0].content.length).toBe(1);
+        expect(yieldedChunks[0].content[0]).toMatchObject({
+            type: 'thinking',
+            thinking: 'Mock thinking: Analyzing',
+        });
+
+        // Chunk 2: Second part of thinking (delta)
+        expect(yieldedChunks[1].content.length).toBe(1);
+        expect(yieldedChunks[1].content[0]).toMatchObject({
+            type: 'thinking',
+            thinking: ' the weather query for Beijing',
+        });
+
+        // Chunk 3: Tool call with first part of arguments
+        expect(yieldedChunks[2].content.length).toBe(1);
+        expect(yieldedChunks[2].content[0]).toMatchObject({
+            type: 'tool_call',
+            name: 'get_current_weather',
+            id: 'call-123',
+            input: '{"location"',
+        });
+
+        // Chunk 4: Tool call with second part of arguments (delta)
+        expect(yieldedChunks[3].content.length).toBe(1);
+        expect(yieldedChunks[3].content[0]).toMatchObject({
+            type: 'tool_call',
+            name: 'get_current_weather',
+            id: 'call-123',
+            input: ':"Beijing"}',
+        });
+
+        // Chunk 5: Empty content with usage info
+        expect(yieldedChunks[4].content.length).toBe(0);
+        expect(yieldedChunks[4].usage).toBeDefined();
+        expect(yieldedChunks[4].usage?.inputTokens).toBe(100);
+        expect(yieldedChunks[4].usage?.outputTokens).toBe(50);
+
+        // Verify the final complete response has correct structure
+        expect(completeResponse.content.length).toBe(2);
+
+        // Check thinking block - should be complete after accumulation
+        const thinkingBlock = completeResponse.content.find(b => b.type === 'thinking');
+        expect(thinkingBlock).toBeDefined();
+        expect(thinkingBlock).toMatchObject({
+            type: 'thinking',
+            thinking: 'Mock thinking: Analyzing the weather query for Beijing',
+        });
+
+        // Check tool_call block - input should be complete after accumulation
+        const toolCallBlock = completeResponse.content.find(b => b.type === 'tool_call');
+        expect(toolCallBlock).toBeDefined();
+        expect(toolCallBlock).toMatchObject({
+            type: 'tool_call',
+            name: 'get_current_weather',
+            id: 'call-123',
+            input: '{"location":"Beijing"}',
+        });
+
+        // Verify usage
+        expect(completeResponse.usage).toBeDefined();
+        expect(completeResponse.usage?.inputTokens).toBe(100);
+        expect(completeResponse.usage?.outputTokens).toBe(50);
+    }, 10000);
+
+    test('Test non-streaming generation', async () => {
+        // Mock non-streaming response
+        const mockResponse = {
+            output: {
+                choices: [
+                    {
+                        message: {
+                            reasoning_content:
+                                'Mock thinking: Analyzing the weather query for Beijing',
+                            tool_calls: [
+                                {
+                                    index: 0,
+                                    id: 'call-123',
+                                    function: {
+                                        name: 'get_current_weather',
+                                        arguments: '{"location":"Beijing"}',
+                                    },
+                                },
+                            ],
+                        },
+                    },
+                ],
+            },
+            usage: {
+                input_tokens: 100,
+                output_tokens: 50,
+            },
+        };
+
+        (global.fetch as jest.Mock).mockResolvedValue({
+            ok: true,
+            json: async () => mockResponse,
+        });
+
+        const model = new DashScopeChatModel({
+            modelName: 'qwen3.5-plus',
+            apiKey: 'test-api-key',
+            stream: false,
+            thinkingConfig: {
+                enableThinking: true,
+            },
+        });
+
+        const res = await model.call({
+            messages: [
+                createMsg({
+                    name: 'user',
+                    role: 'user',
+                    content: [
+                        {
+                            id: crypto.randomUUID(),
+                            type: 'text',
+                            text: "How's the weather today in Beijing?",
+                        },
+                    ],
+                }),
+            ],
+            tools: [
+                {
+                    type: 'function',
+                    function: {
+                        name: 'get_current_weather',
+                        description: 'Get the current weather in a given location',
+                        parameters: {
+                            type: 'object',
+                            properties: {
+                                location: {
+                                    type: 'string',
+                                    description: 'The city and state, e.g. San Francisco, CA',
+                                },
+                            },
+                            required: ['location'],
+                        },
+                    },
+                },
+            ],
+            toolChoice: 'get_current_weather',
+        });
+
+        const completeResponse = res as ChatResponse;
+
+        // Verify complete response structure
+        expect(completeResponse.content.length).toBe(2);
+
+        // Check thinking block
+        const thinkingBlock = completeResponse.content.find(b => b.type === 'thinking');
+        expect(thinkingBlock).toBeDefined();
+        expect(thinkingBlock).toMatchObject({
+            type: 'thinking',
+            thinking: 'Mock thinking: Analyzing the weather query for Beijing',
+        });
+
+        // Check tool_call block
+        const toolCallBlock = completeResponse.content.find(b => b.type === 'tool_call');
+        expect(toolCallBlock).toBeDefined();
+        expect(toolCallBlock).toMatchObject({
+            type: 'tool_call',
+            name: 'get_current_weather',
+            id: 'call-123',
+            input: '{"location":"Beijing"}',
+        });
+
+        // Verify usage
+        expect(completeResponse.usage).toBeDefined();
+        expect(completeResponse.usage?.inputTokens).toBe(100);
+        expect(completeResponse.usage?.outputTokens).toBe(50);
+    }, 10000);
+
+    test('Test formatToolChoice function', () => {
+        const model = new DashScopeChatModel({
+            modelName: 'qwen3.5-plus',
+            apiKey: 'test-api-key',
+            stream: false,
+        });
+
+        // Test 'auto' case
+        expect(model['_formatToolChoice']('auto')).toBe('auto');
+
+        // Test 'none' case
+        expect(model['_formatToolChoice']('none')).toBe('none');
+
+        // Test specific function name case
+        expect(model['_formatToolChoice']('get_current_weather')).toEqual({
+            type: 'function',
+            function: {
+                name: 'get_current_weather',
+            },
+        });
+
+        // Test undefined case (should default to 'auto')
+        expect(model['_formatToolChoice'](undefined)).toBe('auto');
+    });
+
+    test('Test formatToolSchemas function', () => {
+        const model = new DashScopeChatModel({
+            modelName: 'qwen3.5-plus',
+            apiKey: 'test-api-key',
+            stream: false,
+        });
+
+        const toolSchemas = [
+            {
+                type: 'function' as const,
+                function: {
+                    name: 'get_current_weather',
+                    description: 'Get the current weather in a given location',
+                    parameters: {
+                        type: 'object' as const,
+                        properties: {
+                            location: {
+                                type: 'string',
+                                description: 'The city and state, e.g. San Francisco, CA',
+                            },
+                        },
+                        required: ['location'],
+                    },
+                },
+            },
+        ];
+
+        // Test with tool schemas
+        expect(model['_formatToolSchemas'](toolSchemas)).toEqual(toolSchemas);
+
+        // Test with undefined (should return empty array)
+        expect(model['_formatToolSchemas'](undefined)).toEqual([]);
+    });
+});