utilitas 1998.2.30 → 1998.2.31

package/lib/alan.mjs

@@ -28,7 +28,7 @@ const [
     TEXT_EMBEDDING_3_SMALL, TEXT_EMBEDDING_3_LARGE, CLAUDE_35_SONNET,
     CLAUDE_35_HAIKU, CLOUD_37_SONNET, AUDIO, WAV, CHATGPT_MINI, ATTACHMENTS,
     CHAT, OPENAI_VOICE, MEDIUM, LOW, HIGH, GPT_REASONING_EFFORT, THINK,
-    THINK_STR, THINK_END, AZURE,
+    THINK_STR, THINK_END, AZURE, TOOLS_STR, TOOLS_END, TOOLS, TEXT, THINKING,
 ] = [
         'OPENAI', 'GEMINI', 'CHATGPT', 'OPENAI_EMBEDDING', 'GEMINI_EMEDDING',
         'OPENAI_TRAINING', 'OLLAMA', 'CLAUDE', 'gpt-4o-mini', 'gpt-4o', 'o1',
@@ -39,7 +39,8 @@ const [
         'claude-3-5-sonnet-latest', 'claude-3-5-haiku-latest',
         'claude-3-7-sonnet@20250219', 'audio', 'wav', 'CHATGPT_MINI',
         '[ATTACHMENTS]', 'CHAT', 'OPENAI_VOICE', 'medium', 'low', 'high',
-        'medium', 'think', '<think>', '</think>', 'AZURE',
+        'medium', 'think', '<think>', '</think>', 'AZURE', '<tools>',
+        '</tools>', 'tools', 'text', 'thinking',
     ];
 
 const [
@@ -84,6 +85,7 @@ const renderText = (t, o) => _renderText(t, { extraCodeBlock: 0, ...o || {} });
 const log = (cnt, opt) => _log(cnt, import.meta.url, { time: 1, ...opt || {} });
 const CONTENT_IS_REQUIRED = 'Content is required.';
 const assertContent = content => assert(content.length, CONTENT_IS_REQUIRED);
+const packThink = thk => thk ? [`${THINK_STR}\n${thk}\n${THINK_END}`] : [];
 
 
 const DEFAULT_MODELS = {
@@ -369,6 +371,50 @@ const unifyType = (type, name) => {
     return TYPE;
 };
 
+const tools = [
+    {
+        def: {
+            type: 'function', strict: true, function: {
+                name: 'testFunctionCall',
+                description: 'This is a test function call',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        a: { type: 'string', description: 'AI created a random string, default "1"' },
+                        b: { type: 'string', enum: ['1', '2'], description: 'Enum parameter' }
+                    },
+                    required: ['a', 'b'],
+                    additionalProperties: false
+                }
+            }
+        },
+        func: async args => `OK: ${~~args.a + ~~args.b}`,
+    },
+];
+
+const toolsClaude = tools.map(x => ({
+    ...x, def: {
+        name: x.def.function.name,
+        description: x.def.function.description,
+        input_schema: x.def.function.parameters,
+    }
+}));
+
+const toolsGemini = tools.map(x => ({
+    ...x, def: {
+        name: x.def.function.name,
+        description: x.def.function.description,
+        parameters: {
+            type: 'object',
+            properties: x.def.function.parameters.properties,
+            required: x.def.function.parameters.required,
+        },
+        response: x.def.function?.response ?? {
+            type: 'string', description: 'It could be a string or JSON',
+        },
+    }
+}));
+
 const init = async (options) => {
     const provider = unifyProvider(options);
     switch (provider) {
@@ -390,7 +436,8 @@ const init = async (options) => {
                 const genModel = options?.model || DEFAULT_MODELS[GEMINI];
                 clients[provider] = {
                     generative: genAi.getGenerativeModel({
-                        model: genModel, ...MODELS[genModel]?.tools ? (options?.tools ?? {
+                        model: genModel,
+                        ...MODELS[genModel]?.tools ? (options?.tools ?? {
                             tools: [
                                 // @todo: Gemini will failed when using these tools together.
                                 // https://ai.google.dev/gemini-api/docs/function-calling
@@ -398,6 +445,9 @@ const init = async (options) => {
                                 // { googleSearch: {} },
                                 { functionDeclarations: toolsGemini.map(x => x.def) },
                             ],
+                            toolConfig: { functionCallingConfig: { mode: 'AUTO' } },
+                            // @todo
+                            // systemInstruction: { role: "system", parts: [{ text: 'only use function when needed' }] },
                         }) : {},
                     }),
                     embedding: genAi.getGenerativeModel({
@@ -455,50 +505,6 @@ const countTokens = async (input, options) => {
     );
 };
 
-const tools = [
-    {
-        def: {
-            type: 'function', strict: true, function: {
-                name: 'testFunctionCall',
-                description: 'This is a test function call',
-                parameters: {
-                    type: 'object',
-                    properties: {
-                        a: { type: 'string', description: 'AI created a random string, default "1"' },
-                        b: { type: 'string', enum: ['1', '2'], description: 'Enum parameter' }
-                    },
-                    required: ['a', 'b'],
-                    additionalProperties: false
-                }
-            }
-        },
-        func: async args => `OK: ${~~args.a + ~~args.b}`,
-    },
-];
-
-const toolsClaude = tools.map(x => ({
-    ...x, def: {
-        name: x.def.function.name,
-        description: x.def.function.description,
-        input_schema: x.def.function.parameters,
-    }
-}));
-
-const toolsGemini = tools.map(x => ({
-    ...x, def: {
-        name: x.def.function.name,
-        description: x.def.function.description,
-        parameters: {
-            type: 'object',
-            properties: x.def.function.parameters.properties,
-            required: x.def.function.parameters.required,
-        },
-        response: x.def.function?.response ?? {
-            type: 'string', description: 'It could be a string or JSON',
-        },
-    }
-}));
-
 const selectGptAudioModel = options => {
     assert(
         MODELS[options.model]?.audio,
@@ -526,7 +532,7 @@ const buildGptMessage = (content, options) => {
     alterModel && (options.model = alterModel);
     const message = String.isString(content) ? {
         role: options?.role || user,
-        content: content.length ? [{ type: 'text', text: content }] : [],
+        content: content.length ? [{ type: TEXT, text: content }] : [],
     } : content;
     message.content || (message.content = []);
     attachments.map(x => message.content.push(x));
@@ -580,7 +586,7 @@ const buildClaudeMessage = (text, options) => {
     });
     return String.isString(text) ? {
         role: options?.role || user,
-        content: [...attachments, { type: 'text', text }],
+        content: [...attachments, { type: TEXT, text }],
     } : text;
 };
 
@@ -648,21 +654,21 @@ const packResp = async (resp, options) => {
                 return `${i + 1}. [${x.title}](${x.uri})`;
             }).join('\n');
         }
-        // DeepSeek R1 {
         let lines = (richText || txt).split('\n');
-        const indexOfEnd = lines.indexOf(THINK_END);
-        if (lines[0] === THINK_STR) {
-            if (indexOfEnd === -1) {
-                lines.shift();
-            } else {
-                lines[0] = MD_CODE + THINK;
-                lines[indexOfEnd] = MD_CODE;
-                lines.slice(1, indexOfEnd).join('').trim()
-                    || (lines = lines.slice(indexOfEnd + 1));
+        for (let i in lines) {
+            switch (lines[i]) {
+                case THINK_STR:
+                    lines[i] = MD_CODE + THINK;
+                    break;
+                case TOOLS_STR:
+                    lines[i] = MD_CODE + TOOLS;
+                    break;
+                case THINK_END:
+                case TOOLS_END:
+                    lines[i] = MD_CODE;
             }
-            richText = lines.join('\n').trim();
         }
-        // }
+        richText = lines.join('\n').trim();
     }
     return {
         ...text(txt), ...options?.jsonMode && !(
@@ -677,24 +683,43 @@ const packResp = async (resp, options) => {
 };
 
 const packGptResp = async (resp, options) => {
-    const text = resp?.choices?.[0]?.message?.content        // ChatGPT
-        || resp?.choices?.[0]?.message?.audio?.transcript    // ChatGPT audio mode
-        || resp?.text?.()                                    // Gemini
-        || resp?.content?.find(x => x.type === 'text')?.text // Claude
-        || resp?.message?.content || '';                     // Ollama
-    const audio = resp?.choices?.[0]?.message?.audio?.data;  // ChatGPT audio mode
+    // simple mode is not recommended for streaming responses
+    let text = resp?.choices?.[0]?.message?.content                             // ChatGPT
+        || resp?.choices?.[0]?.message?.audio?.transcript                       // ChatGPT audio mode
+        || (Function.isFunction(resp?.text) ? resp.text() : resp?.text)         // Gemini
+        || resp?.content?.find(x => x.type === TEXT)?.text                      // Claude
+        || resp?.message?.content || '';                                        // Ollama
+    const audio = resp?.choices?.[0]?.message?.audio?.data;                     // ChatGPT audio mode
     if (options?.raw) { return resp; }
     else if (options?.simple && options?.jsonMode) { return parseJson(text); }
     else if (options?.simple && options?.audioMode) { return audio; }
-    else if (options?.simple && text.substr(0, THINK_STR.length) === THINK_STR) {
-        return text.substr(text.indexOf(THINK_END) + THINK_END.length).trim();
-    } else if (options?.simple) { return text; }
+    else if (options?.simple) {
+        for (const key of [[THINK_STR, THINK_END], [TOOLS_STR, TOOLS_END]]) {
+            const [findStr, findEnd] = key.map(x => text.indexOf(x));
+            if (findStr >= 0 && findEnd >= 0 && findStr < findEnd) {
+                text = text.split('')
+                text.splice(findStr, findEnd + THINK_END.length)
+                text = text.join('').trim();
+            }
+        }
+        return text;
+    }
     return await packResp({ text, audio, references: resp?.references }, options);
 };
 
 const handleToolsCall = async (msg, options) => {
-    let content = [], preRes = [], input, packMsg;
+    let [content, preRes, input, packMsg, toolsResponse] = [
+        [], [], [], null,
+        options?.currentResponse ? `${options?.currentResponse}\n` : '',
+    ];
+    const resp = async (msg) => {
+        toolsResponse = [...toolsResponse ? [toolsResponse] : [], msg].join('\n');
+        await ignoreErrFunc(async () => await options?.stream?.(await packGptResp({
+            choices: [{ message: { content: options?.delta ? msg : toolsResponse } }]
+        }, { ...options || {}, processing: true })), LOG);
+    };
     if (msg?.tool_calls?.length) {
+        await resp(TOOLS_STR);
         switch (options?.flavor) {
             case CLAUDE: preRes.push({ role: assistant, content: msg?.tool_calls }); break;
             case GEMINI: preRes.push({ role: MODEL, parts: msg?.tool_calls.map(x => ({ functionCall: x })) }); break;
@@ -703,7 +728,7 @@ const handleToolsCall = async (msg, options) => {
         for (const fn of msg.tool_calls) {
             switch (options?.flavor) {
                 case CLAUDE:
-                    input = fn.input = parseJson(fn?.input);
+                    input = fn.input = String.isString(fn?.input) ? parseJson(fn.input) : fn?.input;
                     packMsg = (content, is_error) => ({
                         type: 'tool_result', tool_use_id: fn.id, content, is_error,
                     });
@@ -727,25 +752,31 @@ const handleToolsCall = async (msg, options) => {
                     break;
             }
             const name = fn?.function?.name || fn?.name;
-            const func = tools.find(x => insensitiveCompare(
+            await resp(`\nName: ${name}`);
+            const f = tools.find(x => insensitiveCompare(
                 x.def?.function?.name || x?.def?.name, name
-            ))?.func;
-            if (!func) {
+            ));
+            if (!f?.func) {
                 content.push(packMsg(`Function call failed, invalid function name: ${name}`, true));
                 continue;
             }
+            const description = f.def?.function?.description || f.def?.description;
+            description && await resp(`Description: ${description}`);
             try {
-                content.push(packMsg((await func(input)) ?? 'OK'));
+                content.push(packMsg((await f?.func(input)) ?? 'OK'));
+                await resp(`Status: OK`);
             } catch (err) {
                 content.push(packMsg(`Function call failed: ${err.message}`, true));
+                await resp(`Status: Failed`);
             }
         }
         switch (options?.flavor) {
             case CLAUDE: content = [{ role: user, content }]; break;
             case GEMINI: content = [{ role: user, parts: content }]; break;
         }
+        await resp(`\n${TOOLS_END}`);
     }
-    return [...preRes, ...content];
+    return { toolsResult: [...preRes, ...content], toolsResponse };
 };
 
 const promptChatGPT = async (content, options = {}) => {
@@ -766,7 +797,7 @@ const promptChatGPT = async (content, options = {}) => {
         && (options.reasoning_effort = GPT_REASONING_EFFORT);
     const message = buildGptMessage(content, options);
     const modalities = options?.modalities || (
-        options?.audioMode ? ['text', AUDIO] : undefined
+        options?.audioMode ? [TEXT, AUDIO] : undefined
     );
     assert(!(
         options?.jsonMode && !MODELS[options.model]?.json
@@ -790,8 +821,10 @@ const promptChatGPT = async (content, options = {}) => {
                 tools: options?.tools ?? tools.map(x => x.def),
             } : {}, ...options?.jsonMode ? {
                 response_format: { type: JSON_OBJECT }
-            } : {}, model: options.model, stream: !!options?.stream, store: true,
-        }), '', Buffer.alloc(0), null, [],
+            } : {}, model: options.model, stream: !!options?.stream,
+            store: true, tool_choice: 'auto',
+        }), options?.toolsResponse ? `${options?.toolsResponse}\n\n` : '',
+        Buffer.alloc(0), null, [],
     ];
     if (options?.stream) {
         for await (chunk of resp) {
@@ -832,9 +865,15 @@ const promptChatGPT = async (content, options = {}) => {
         };
         resp = chunk;
     }
-    const toolsResult = await handleToolsCall(resp?.choices?.[0]?.message);
-    return await (toolsResult.length ? promptChatGPT(
-        content, { ...options || {}, toolsResult }
+    const { toolsResult, toolsResponse }
+        = await handleToolsCall(resp?.choices?.[0]?.message, options);
+    options?.toolsResponse && !options?.stream && (
+        resp.choices[0].message.content = [
+            options?.toolsResponse, resp.choices[0].message.content,
+        ].join('\n\n')
+    );
+    return await (toolsResult.length && !options?.toolsResult ? promptChatGPT(
+        content, { ...options || {}, toolsResult, toolsResponse }
     ) : packGptResp(resp, options));
 };
 
@@ -879,10 +918,11 @@ const promptClaude = async (content, options = {}) => {
         } : {}, // https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking
         ...MODELS[options.model]?.tools ? {
             tools: options?.tools ?? toolsClaude.map(x => x.def),
+            tool_choice: { type: 'auto' },
         } : {},
     });
     let [event, txtResult, thinking, signature, result, thinkEnd, tool_calls]
-        = [null, '', '', '', '', '', []];
+        = [null, '', '', '', options?.toolsResponse || '', '', []];
     if (options?.stream) {
         for await (event of resp) {
             let [thkDelta, txtDelta] = [
@@ -893,8 +933,10 @@ const promptClaude = async (content, options = {}) => {
             thinking += thkDelta;
             signature = signature || event?.content_block?.signature || event?.delta?.signature || '';
             if (reasoning) {
-                !result && thkDelta && (thkDelta = `${THINK_STR}\n${thkDelta}`);
-                result && txtDelta && !thinkEnd && (thinkEnd = thkDelta = `${thkDelta}\n${THINK_END}\n\n`);
+                thkDelta && (thkDelta === thinking)
+                    && (thkDelta = `${THINK_STR}\n${thkDelta}`);
+                thinking && txtDelta && !thinkEnd
+                    && (thinkEnd = thkDelta = `${thkDelta}\n${THINK_END}\n\n`);
             }
             if (event?.content_block?.type === 'tool_use') {
                 tool_calls.push({ ...event?.content_block, input: '' });
@@ -904,23 +946,42 @@ const promptClaude = async (content, options = {}) => {
             const delta = thkDelta + txtDelta;
             if (delta === '') { continue; }
             result += delta;
-            event.content = [{ type: 'text', text: options?.delta ? delta : result }];
+            event.content = [{ type: TEXT, text: options?.delta ? delta : result }];
             await ignoreErrFunc(async () => await options.stream(
-                await packGptResp(event, { ...options || {}, processing: true })
+                await packGptResp(event, { ...options, processing: true })
             ), LOG);
         }
-        event.content = [{ type: 'text', text: tool_calls.length ? txtResult : result }];
-        tool_calls.length && thinking && event.content.unshift({ type: 'thinking', thinking, signature });
+        event.content = [{
+            type: TEXT, text: tool_calls.length ? txtResult : result,
+        }];
+        tool_calls.length && thinking
+            && event.content.unshift({ type: THINKING, thinking, signature });
     } else {
         event = resp;
         tool_calls = resp?.content?.filter?.(x => x.type === 'tool_use') || [];
     }
-    const toolsResult = await handleToolsCall({ tool_calls }, { flavor: CLAUDE });
-    if (toolsResult.length) {
-        toolsResult[0].content.unshift(...event?.content.filter(x => x?.type !== 'tool_use'));
-        return await promptClaude(content, { ...options || {}, toolsResult });
-    }
-    return packGptResp(event, options);
+    const { toolsResult, toolsResponse } = await handleToolsCall(
+        { tool_calls }, { ...options, currentResponse: result, flavor: CLAUDE },
+    );
+    if (toolsResult.length && !options?.toolsResult) {
+        toolsResult[0].content.unshift(
+            ...event?.content.filter(x => x?.type !== 'tool_use')
+        );
+        return await promptClaude(content, {
+            ...options, toolsResult, toolsResponse,
+        });
+    } else {
+        const textPart = event.content.find(x => x.type == TEXT);
+        const thinkPart = event.content.find(x => x.type == THINKING);
+        const prvThink = options?.toolsResult?.find(
+            x => x?.content?.find(y => y?.type === THINKING)
+        )?.content?.find(x => x?.type === THINKING);
+        options?.stream || (textPart.text = [
+            ...packThink(prvThink?.thinking), ...packThink(thinkPart?.thinking),
+            ...options?.toolsResponse ? [options?.toolsResponse] : [],
+            textPart.text,
+        ].join('\n\n'));
+    } return packGptResp(event, options);
 };
 
 const uploadFile = async (input, options) => {
@@ -972,11 +1033,33 @@ const packGeminiReferences = (chunks, supports) => {
     return references;
 };
 
-const handleGeminiResponse = async (resp, options) => {
-    const _resp = await resp;
-    let [result, references, functionCalls] = ['', null, null];
+const promptGemini = async (content, options = {}) => {
+    const { generative, genModel } = await getGeminiClient(options);
+    // https://github.com/google/generative-ai-js/blob/main/samples/node/advanced-chat.js
+    // @todo: check this issue similar to Vertex AI:
+    // Google's bug: history is not allowed while using inline_data?
+    assert(!(
+        options?.jsonMode && MODELS[genModel]?.json == false
+    ), `This model does not support JSON output: ${genModel} `);
+    options.model = genModel;
+    const chat = generative.startChat({
+        history: [
+            ...options?.messages && !options?.attachments?.length
+                ? options.messages : [],
+            ...options?.toolsResult ? [{
+                role: user, parts: buildGeminiMessage(content, options)
+            }, options?.toolsResult[0]] : [],
+        ], ...generationConfig(options),
+    });
+    const resp = await chat[
+        options?.stream ? 'sendMessageStream' : 'sendMessage'
+    ](options?.toolsResult ?
+        options?.toolsResult[1].parts : buildGeminiMessage(content, options));
+    let [result, references, functionCalls] = [
+        options?.toolsResponse ? `${options?.toolsResponse}\n\n` : '', null, null
+    ];
     if (options?.stream) {
-        for await (const chunk of _resp.stream) {
+        for await (const chunk of resp.stream) {
             functionCalls || (functionCalls = chunk.functionCalls);
             const delta = chunk?.text?.() || '';
             const rfc = packGeminiReferences(
@@ -989,52 +1072,28 @@ const handleGeminiResponse = async (resp, options) => {
             await ignoreErrFunc(async () => await options.stream(
                 await packGptResp({
                     text: () => options?.delta ? delta : result, references,
-                }, { ...options || {}, processing: true })
+                }, { ...options, processing: true })
             ), LOG);
         }
     }
-    const __resp = await _resp.response;
-    const toolsResult = await handleToolsCall({
-        tool_calls: (functionCalls || __resp.functionCalls)()
-    }, { flavor: GEMINI });
-    return await (toolsResult.length ? promptGemini(
-        options?.content, { ...options || {}, toolsResult }
+    const _resp = await resp.response;
+    const { toolsResult, toolsResponse } = await handleToolsCall({
+        tool_calls: (functionCalls || _resp.functionCalls)()
+    }, { ...options, flavor: GEMINI });
+    options?.toolsResponse && !options?.stream
+        && (_resp.text = [options?.toolsResponse, _resp.text()].join('\n\n'));
+    return await (toolsResult.length && !options?.toolsResult ? promptGemini(
+        content, { ...options || {}, toolsResult, toolsResponse }
     ) : packGptResp(options?.stream ? {
-        __resp, text: () => result, references
+        _resp, text: () => result, references
     } : {
-        ...__resp, references: packGeminiReferences(
-            __resp.candidates[0]?.groundingMetadata?.groundingChunks,
-            __resp.candidates[0]?.groundingMetadata?.groundingSupports
+        ..._resp, references: packGeminiReferences(
+            _resp.candidates[0]?.groundingMetadata?.groundingChunks,
+            _resp.candidates[0]?.groundingMetadata?.groundingSupports
         )
     }, options));
 };
 
-const promptGemini = async (content, options) => {
-    const { generative, genModel } = await getGeminiClient(options);
-    // https://github.com/google/generative-ai-js/blob/main/samples/node/advanced-chat.js
-    // @todo: check this issue similar to Vertex AI:
-    // Google's bug: history is not allowed while using inline_data?
-    assert(!(
-        options?.jsonMode && MODELS[genModel]?.json == false
-    ), `This model does not support JSON output: ${genModel} `);
-    const chat = generative.startChat({
-        history: [
-            ...options?.messages && !options?.attachments?.length
-                ? options.messages : [],
-            ...options?.toolsResult ? [{
-                role: user, parts: buildGeminiMessage(content, options)
-            }, options?.toolsResult[0]] : [],
-        ], ...generationConfig(options),
-    });
-    const resp = chat[options?.stream ? 'sendMessageStream' : 'sendMessage'](
-        options?.toolsResult ?
-            options?.toolsResult[1].parts : buildGeminiMessage(content, options)
-    );
-    return await handleGeminiResponse(
-        resp, { ...options || {}, content, model: genModel }
-    );
-};
-
 const checkEmbeddingInput = async (input, model) => {
     assert(input, 'Text is required.', 400);
     const arrInput = input.split(' ');

package/lib/manifest.mjs

@@ -1,7 +1,7 @@
 const manifest = {
     "name": "utilitas",
     "description": "Just another common utility for JavaScript.",
-    "version": "1998.2.30",
+    "version": "1998.2.31",
     "private": false,
     "homepage": "https://github.com/Leask/utilitas",
     "main": "index.mjs",

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "utilitas",
     "description": "Just another common utility for JavaScript.",
-    "version": "1998.2.30",
+    "version": "1998.2.31",
     "private": false,
     "homepage": "https://github.com/Leask/utilitas",
     "main": "index.mjs",