utilitas 1998.2.23 → 1998.2.25

package/lib/alan.mjs

@@ -7,9 +7,12 @@ import { create as createUoid } from './uoid.mjs';
 import {
     log as _log,
     renderText as _renderText,
-    base64Encode, ensureArray, ensureString, extract, ignoreErrFunc,
+    base64Encode, ensureArray, ensureString, extract,
+    ignoreErrFunc,
+    insensitiveCompare,
+    isSet,
     need, parseJson,
-    throwError,
+    throwError
 } from './utilitas.mjs';
 
 const _NEED = [
@@ -82,6 +85,7 @@ 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 DEFAULT_MODELS = {
     [CHATGPT_MINI]: GPT_4O_MINI,
     [CHATGPT_REASONING]: GPT_O3_MINI,
@@ -123,7 +127,7 @@ const MODELS = {
         trainingData: 'Oct 2023',
         json: true,
         vision: true,
-        reasoning: false,
+        tools: true,
         audio: 'gpt-4o-mini-audio-preview',
         supportedMimeTypes: [
             png, jpeg, gif, webp,
@@ -142,7 +146,7 @@ const MODELS = {
         trainingData: 'Oct 2023',
         json: true,
         vision: true,
-        reasoning: false,
+        tools: true,
         audio: 'gpt-4o-audio-preview',
         supportedMimeTypes: [
             png, jpeg, gif, webp,
@@ -162,6 +166,7 @@ const MODELS = {
         json: true,
         reasoning: true,
         vision: true,
+        tools: true,
         // audio: 'gpt-4o-audio-preview', // fallback to GPT-4O to support audio
         supportedMimeTypes: [
             png, jpeg, gif, webp,
@@ -181,6 +186,7 @@ const MODELS = {
         json: true,
         reasoning: true,
         vision: true,
+        tools: true,
         // audio: 'gpt-4o-mini-audio-preview', // fallback to GPT-4O-MINI to support audio
         supportedMimeTypes: [
             png, jpeg, gif, webp,
@@ -213,6 +219,7 @@ const MODELS = {
         trainingData: 'August 2024',
         vision: true,
         json: true,
+        tools: true,
         supportedMimeTypes: [
             png, jpeg, mov, mpeg, mp4, mpg, avi, wmv, mpegps, flv, pdf, aac,
             flac, mp3, m4a, mpga, opus, pcm, wav, webm, tgpp,
@@ -231,7 +238,6 @@ const MODELS = {
         requestLimitsRPD: 1500,
         tokenLimitsTPM: 4 * 1000000,
         trainingData: 'August 2024',
-        json: false,
         vision: true,
         reasoning: true,
         supportedMimeTypes: [
@@ -262,8 +268,6 @@ const MODELS = {
         maxOutputTokens: 32768,
         requestLimitsRPM: Infinity,
         tokenLimitsTPM: Infinity,
-        json: false,
-        vision: false,
         reasoning: true,
     },
     [TEXT_EMBEDDING_3_SMALL]: {
@@ -300,6 +304,7 @@ const MODELS = {
         tokenLimitsITPM: 40000,
         tokenLimitsOTPM: 8000,
         trainingData: 'Apr 2024',
+        tools: true,
         supportedMimeTypes: [
             png, jpeg, gif, webp, pdf,
         ],
@@ -319,6 +324,7 @@ const MODELS = {
         tokenLimitsOTPM: 8000,
         trainingData: 'Apr 2024', // ?
         reasoning: true,
+        tools: true,
         supportedMimeTypes: [
             png, jpeg, gif, webp, pdf,
         ],
@@ -382,19 +388,17 @@ const init = async (options) => {
                 const { GoogleGenerativeAI } = await need('@google/generative-ai');
                 const genAi = new GoogleGenerativeAI(options.apiKey);
                 const genModel = options?.model || DEFAULT_MODELS[GEMINI];
-                const tools = options?.tools || { google: true, code: false };
                 clients[provider] = {
                     generative: genAi.getGenerativeModel({
-                        model: genModel,
-                        tools: [
-                            // @todo: https://cloud.google.com/vertex-ai/generative-ai/docs/gemini-v2?hl=en#search-tool
-                            ...tools.code ? [{
-                                codeExecution: tools.code === true ? {} : tools.code
-                            }] : [],
-                            ...tools.google ? [{
-                                googleSearch: tools.google === true ? {} : tools.code,
-                            }] : [],
-                        ],
+                        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
+                                // { codeExecution: {} },
+                                // { googleSearch: {} },
+                                { functionDeclarations: toolsGemini.map(x => x.def) },
+                            ],
+                        }) : {},
                     }),
                     embedding: genAi.getGenerativeModel({
                         model: DEFAULT_MODELS[GEMINI_EMEDDING],
@@ -451,6 +455,50 @@ 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,
@@ -630,12 +678,12 @@ 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?.text                              // Claude
-        || resp?.message?.content || '';                    // Ollama
-    const audio = resp?.choices?.[0]?.message?.audio?.data; // ChatGPT audio mode
+    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
     if (options?.raw) { return resp; }
     else if (options?.simple && options?.jsonMode) { return parseJson(text); }
     else if (options?.simple && options?.audioMode) { return audio; }
@@ -645,6 +693,61 @@ const packGptResp = async (resp, options) => {
     return await packResp({ text, audio, references: resp?.references }, options);
 };
 
+const handleToolsCall = async (msg, options) => {
+    let content = [], preRes = [], input, packMsg;
+    if (msg?.tool_calls?.length) {
+        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;
+            case CHATGPT: default: preRes.push({ role: 'assistant', ...msg });
+        }
+        for (const fn of msg.tool_calls) {
+            switch (options?.flavor) {
+                case CLAUDE:
+                    input = fn.input = parseJson(fn?.input);
+                    packMsg = (content, is_error) => ({
+                        type: 'tool_result', tool_use_id: fn.id, content, is_error,
+                    });
+                    break;
+                case GEMINI:
+                    input = fn.args;
+                    packMsg = (t, e) => ({
+                        functionResponse: {
+                            name: fn.name, response: {
+                                name: fn.name,
+                                content: e ? `[Error] ${t}` : JSON.stringify(t),
+                            }
+                        }
+                    });
+                    break;
+                case CHATGPT: default:
+                    input = parseJson(fn?.function?.arguments);
+                    packMsg = (t, e) => ({
+                        role: 'tool', tool_call_id: fn.id, [e ? 'error' : 'content']: t
+                    });
+            }
+            const name = fn?.function?.name || fn?.name;
+            const func = tools.find(x => insensitiveCompare(
+                x.def?.function?.name || x?.def?.name, name
+            ))?.func;
+            if (!func) {
+                content.push(packMsg(`Function call failed, invalid function name: ${name}`, true));
+                continue;
+            }
+            try {
+                content.push(packMsg(await func(input)));
+            } catch (err) {
+                content.push(packMsg(`Function call failed: ${err.message}`, true));
+            }
+        }
+        switch (options?.flavor) {
+            case CLAUDE: content = [{ role: 'user', content }]; break;
+            case GEMINI: content = [{ role: 'user', parts: content }]; break;
+        }
+    }
+    return [...preRes, ...content];
+};
+
 const promptChatGPT = async (content, options = {}) => {
     const { client } = await getOpenAIClient(options);
     // https://github.com/openai/openai-node?tab=readme-ov-file#streaming-responses
@@ -674,45 +777,65 @@ const promptChatGPT = async (content, options = {}) => {
     let format;
     [format, options.audioMimeType, options.suffix]
         = options?.stream ? ['pcm16', pcm16, 'pcm.wav'] : [WAV, wav, WAV];
-    let [resp, resultText, resultAudio, chunk] = [
+    let [resp, resultText, resultAudio, chunk, resultTools] = [
         await client.chat.completions.create({
             modalities, audio: options?.audio || (
                 modalities?.find?.(x => x === AUDIO) && {
                     voice: DEFAULT_MODELS[OPENAI_VOICE], format
                 }
-            ), ...messages([...options?.messages || [], message]),
-            ...options?.jsonMode ? {
+            ), ...messages([
+                ...options?.messages || [], message,
+                ...options?.toolsResult || [],
+            ]), ...MODELS[options.model]?.tools ? {
+                tools: options?.tools ?? tools.map(x => x.def),
+            } : {}, ...options?.jsonMode ? {
                 response_format: { type: JSON_OBJECT }
-            } : {}, model: options.model, stream: !!options?.stream,
-        }), '', Buffer.alloc(0), null
+            } : {}, model: options.model, stream: !!options?.stream, store: true,
+        }), '', Buffer.alloc(0), null, [],
     ];
-    if (!options?.stream) {
-        return await packGptResp(resp, options);
-    }
-    for await (chunk of resp) {
-        const deltaText = chunk.choices[0]?.delta?.content
-            || chunk.choices[0]?.delta?.audio?.transcript || '';
-        const deltaAudio = chunk.choices[0]?.delta?.audio?.data ? await convert(
-            chunk.choices[0].delta.audio.data, { input: BASE64, expected: BUFFER }
-        ) : Buffer.alloc(0);
-        if (deltaText === '' && !deltaAudio.length) { continue; }
-        resultText += deltaText;
-        resultAudio = Buffer.concat([resultAudio, deltaAudio]);
-        const respAudio = options?.delta ? deltaAudio : resultAudio;
+    if (options?.stream) {
+        for await (chunk of resp) {
+            const deltaText = chunk.choices[0]?.delta?.content
+                || chunk.choices[0]?.delta?.audio?.transcript || '';
+            const deltaAudio = chunk.choices[0]?.delta?.audio?.data ? await convert(
+                chunk.choices[0].delta.audio.data, { input: BASE64, expected: BUFFER }
+            ) : Buffer.alloc(0);
+            const deltaFunc = chunk.choices[0]?.delta?.tool_calls || [];
+            for (const x in deltaFunc) {
+                let curFunc = resultTools.find(z => z.index === deltaFunc[x].index);
+                curFunc || (resultTools.push(curFunc = {}));
+                isSet(deltaFunc[x].index, true) && (curFunc.index = deltaFunc[x].index);
+                deltaFunc[x].id && (curFunc.id = deltaFunc[x].id);
+                deltaFunc[x].type && (curFunc.type = deltaFunc[x].type);
+                curFunc.function || (curFunc.function = { name: '', arguments: '' });
+                if (deltaFunc[x].function) {
+                    deltaFunc[x].function.name && (curFunc.function.name += deltaFunc[x].function.name);
+                    deltaFunc[x].function.arguments && (curFunc.function.arguments += deltaFunc[x].function.arguments);
+                }
+            }
+            if (deltaText === '' && !deltaAudio.length) { continue; }
+            resultText += deltaText;
+            resultAudio = Buffer.concat([resultAudio, deltaAudio]);
+            const respAudio = options?.delta ? deltaAudio : resultAudio;
+            chunk.choices[0].message = {
+                content: options?.delta ? deltaText : resultText,
+                ...respAudio.length ? { audio: { data: respAudio } } : {},
+            };
+            await ignoreErrFunc(async () => await options?.stream?.(
+                await packGptResp(chunk, { ...options || {}, processing: true })
+            ), LOG);
+        }
+        chunk.choices?.[0] || (chunk.choices = [{}]); // handle empty choices for Azure APIs
         chunk.choices[0].message = {
-            content: options?.delta ? deltaText : resultText,
-            ...respAudio.length ? { audio: { data: respAudio } } : {},
+            content: resultText, tool_calls: resultTools,
+            ...resultAudio.length ? { audio: { data: resultAudio } } : {},
         };
-        await ignoreErrFunc(async () => await options?.stream?.(
-            await packGptResp(chunk, { ...options || {}, processing: true })
-        ), LOG);
+        resp = chunk;
     }
-    chunk.choices?.[0] || (chunk.choices = [{}]); // handle empty choices for Azure APIs
-    chunk.choices[0].message = {
-        content: resultText,
-        ...resultAudio.length ? { audio: { data: resultAudio } } : {},
-    };
-    return await packGptResp(chunk, options);
+    const toolsResult = await handleToolsCall(resp?.choices?.[0]?.message);
+    return await (toolsResult.length ? promptChatGPT(
+        content, { ...options || {}, toolsResult }
+    ) : packGptResp(resp, options));
 };
 
 const promptAzure = async (content, options = {}) => await promptChatGPT(
@@ -749,33 +872,55 @@ const promptClaude = async (content, options = {}) => {
     const resp = await client.messages.create({
         model: options.model, max_tokens: MODELS[options.model].maxOutputTokens,
         messages: [
-            ...options?.messages || [], buildClaudeMessage(content, options)
+            ...options?.messages || [], buildClaudeMessage(content, options),
+            ...options?.toolsResult || [],
         ], stream: !!options?.stream, ...reasoning ? {
             thinking: options?.thinking || { type: 'enabled', budget_tokens: 1024 },
-        } : {} // https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking
+        } : {}, // https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking
+        ...MODELS[options.model]?.tools ? {
+            tools: options?.tools ?? toolsClaude.map(x => x.def),
+        } : {},
     });
-    let [event, result, thinkEnd] = [null, '', ''];
+    let [event, txtResult, thinking, signature, result, thinkEnd, tool_calls]
+        = [null, '', '', '', '', '', []];
     if (options?.stream) {
         for await (event of resp) {
             let [thkDelta, txtDelta] = [
                 event?.content_block?.thinking || event?.delta?.thinking || '',
                 event?.content_block?.text || event?.delta?.text || '',
             ];
+            txtResult += txtDelta;
+            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`);
             }
+            if (event?.content_block?.type === 'tool_use') {
+                tool_calls.push({ ...event?.content_block, input: '' });
+            } else if (event?.delta?.partial_json) {
+                tool_calls[tool_calls.length - 1].input += event?.delta?.partial_json;
+            }
             const delta = thkDelta + txtDelta;
             if (delta === '') { continue; }
             result += delta;
-            event.content = { 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 })
             ), LOG);
         }
-        event.content = { text: result };
+        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') || [];
     }
-    return await packGptResp(options?.stream ? event : resp, options);
+    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 uploadFile = async (input, options) => {
@@ -829,9 +974,10 @@ const packGeminiReferences = (chunks, supports) => {
 
 const handleGeminiResponse = async (resp, options) => {
     const _resp = await resp;
-    let [result, references] = ['', null];
+    let [result, references, functionCalls] = ['', null, null];
     if (options?.stream) {
         for await (const chunk of _resp.stream) {
+            functionCalls || (functionCalls = chunk.functionCalls);
             const delta = chunk?.text?.() || '';
             const rfc = packGeminiReferences(
                 chunk.candidates[0]?.groundingMetadata?.groundingChunks,
@@ -848,14 +994,19 @@ const handleGeminiResponse = async (resp, options) => {
         }
     }
     const __resp = await _resp.response;
-    return await packGptResp(options?.stream ? {
+    const toolsResult = await handleToolsCall({
+        tool_calls: (functionCalls || __resp.functionCalls)()
+    }, { flavor: GEMINI });
+    return await (toolsResult.length ? promptGemini(
+        options?.content, { ...options || {}, toolsResult }
+    ) : packGptResp(options?.stream ? {
         __resp, text: () => result, references
     } : {
         ...__resp, references: packGeminiReferences(
             __resp.candidates[0]?.groundingMetadata?.groundingChunks,
             __resp.candidates[0]?.groundingMetadata?.groundingSupports
         )
-    }, options);
+    }, options));
 };
 
 const promptGemini = async (content, options) => {
@@ -867,15 +1018,20 @@ const promptGemini = async (content, options) => {
         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 : [],
+        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'](
-        buildGeminiMessage(content, options)
+        options?.toolsResult ? options?.toolsResult[1].parts : buildGeminiMessage(content, options)
     );
     return await handleGeminiResponse(
-        resp, { ...options || {}, model: genModel }
+        resp, { ...options || {}, content, model: genModel }
     );
 };
 

package/lib/manifest.mjs

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

package/lib/utilitas.mjs

@@ -1,10 +1,10 @@
-import { assertPath, decodeBase64DataURL, readJson } from './storage.mjs';
-import { basename as _basename, dirname, join, sep } from 'path';
 import { fileURLToPath } from 'node:url';
+import { basename as _basename, dirname, join, sep } from 'path';
 import { promisify } from 'util';
 import { validate as verifyUuid } from 'uuid';
 import * as boxes from './boxes.mjs';
 import color from './color.mjs';
+import { assertPath, decodeBase64DataURL, readJson } from './storage.mjs';
 
 const call = (f, ...a) => promisify(Array.isArray(f) ? f[0].bind(f[1]) : f)(...a);
 const invalidTime = 'Invalid time.';
@@ -923,5 +923,5 @@ export {
     verifyUrl,
     verifyUuid,
     voidFunc,
-    which,
+    which
 };

package/package.json

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