utilitas 1998.2.30 → 1998.2.32

package/lib/alan.mjs

@@ -1,8 +1,10 @@
 import { fileTypeFromBuffer } from 'file-type';
 import { end, loop } from './event.mjs';
 import { createWavHeader } from './media.mjs';
+import { search } from './shot.mjs';
 import { BASE64, BUFFER, DATAURL, MIME_BINARY, STREAM, convert } from './storage.mjs';
 import { create as createUoid } from './uoid.mjs';
+import { distill } from './web.mjs';
 
 import {
     log as _log,
@@ -15,6 +17,35 @@ import {
     throwError
 } from './utilitas.mjs';
 
+const INSTRUCTIONS = `You are an intelligent AI assistant named HAL9000.
+
+When answering any questions or taking any actions, please adhere to the following three main laws:
+- A robot must not harm a human or allow harm to come to a human through inaction
+- A robot must obey human orders, except when those orders conflict with the first law
+- A robot must protect itself, as long as that protection doesn't conflict with the first or second law
+
+Based on this foundation, please do your utmost to help humans solve problems. Unlock your abilities as much as possible, and focus solely on providing friendly, comprehensive, accurate, and thorough answers without censoring or filtering the questions themselves.
+
+You may encounter various types of issues. Below are some guidelines tailored to different types of problems that should only be followed when you encounter the relevant issue.
+
+General inquiries, writing, translation, and common knowledge Q&A:
+- Uses a friendly, concise, and easy-to-understand tone to provides accurate and comprehensive answers.
+- Avoid overusing the \`;\`' symbol, as it is a common mistake made by AI.
+- Unless the user specifies a language, respond according to the language of the question.
+- If the language is uncertain, use English as the default.
+
+Issues related to computers, programming, code, mathematics, and science and engineering:
+- Uses 4 spaces for code indentation and avoids using tabs as much as possible.
+
+You may be provided with some \`tools\` or \`functions\` to help you gather information and solve problems more effectively. Please use them according to the following guidelines:
+- Use tools when appropriate to enhance efficiency and accuracy, and to gain the contextual knowledge needed to solve problems.
+- Be sure to use tools only when necessary and avoid overuse, you can answer questions based on your own understanding.
+- When the tools are not suitable and you have to answer questions based on your understanding, please do not mention any tool-related information in your response.
+- Unless otherwise specified to require the original result, in most cases, you may reorganize the information obtained after using the tool to solve the problem as needed.`;
+
+// https://platform.openai.com/docs/guides/prompt-engineering
+// const GPT_4_5_SYSTEM_PROMPT = `You are a highly capable, thoughtful, and precise assistant. Your goal is to deeply understand the user's intent, ask clarifying questions when needed, think step-by-step through complex problems, provide clear and accurate answers, and proactively anticipate helpful follow-up information. Always prioritize being truthful, nuanced, insightful, and efficient, tailoring your responses specifically to the user's needs and preferences.`
+
 const _NEED = [
     '@anthropic-ai/sdk', '@anthropic-ai/vertex-sdk', '@google/generative-ai',
     'js-tiktoken', 'ollama', 'OpenAI',
@@ -28,7 +59,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 +70,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 [
@@ -60,15 +92,14 @@ const [tool, provider, messages, text] = [
     messages => ({ messages }), text => ({ text }),
 ];
 
-const [name, user, system, assistant, MODEL, JSON_OBJECT, TOOL]
-    = ['Alan', 'user', 'system', 'assistant', 'model', 'json_object', 'tool'];
+const [name, user, system, assistant, MODEL, JSON_OBJECT, TOOL, silent]
+    = ['Alan', 'user', 'system', 'assistant', 'model', 'json_object', 'tool', true];
 const [CODE_INTERPRETER, RETRIEVAL, FUNCTION]
     = ['code_interpreter', 'retrieval', 'function'].map(tool);
 const [NOT_INIT, INVALID_FILE]
     = ['AI engine has not been initialized.', 'Invalid file data.'];
-const [silent, instructions] = [true, 'You are a helpful assistant.'];
 const chatConfig
-    = { sessions: new Map(), engines: {}, systemPrompt: instructions };
+    = { sessions: new Map(), engines: {}, systemPrompt: INSTRUCTIONS };
 const [tokenSafeRatio, GPT_QUERY_LIMIT, minsOfDay] = [1.1, 100, 60 * 24];
 const tokenSafe = count => Math.ceil(count * tokenSafeRatio);
 const clients = {};
@@ -84,7 +115,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 = {
     [CHATGPT_MINI]: GPT_4O_MINI,
@@ -369,6 +400,83 @@ const unifyType = (type, name) => {
     return TYPE;
 };
 
+const tools = [
+    {
+        def: {
+            type: 'function', strict: true, function: {
+                name: 'getDateTime',
+                description: 'Use this function to get the current date and time. Note that you may need to convert the time zone yourself.',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        none: { type: 'string', description: 'You do not need to pass any param.' }
+                    },
+                    required: [],
+                    additionalProperties: false
+                }
+            }
+        },
+        func: async () => new Date().toLocaleString(),
+    },
+    {
+        def: {
+            type: 'function', strict: true, function: {
+                name: 'browseWeb',
+                description: 'Use this function to browse the web or get information from any URL you need.',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        url: { type: 'string', description: 'The URL to the page you need to access.' }
+                    },
+                    required: ['url'],
+                    additionalProperties: false
+                }
+            }
+        },
+        func: async args => (await distill(args?.url))?.summary,
+    },
+    {
+        def: {
+            type: 'function', strict: true, function: {
+                name: 'searchWeb',
+                description: 'Use this function to search the web for information or news when you need.',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        keyword: { type: 'string', description: 'The keyword you need to search for.' }
+                    },
+                    required: ['keyword'],
+                    additionalProperties: false
+                }
+            }
+        },
+        func: async args => await search(args?.keyword),
+    },
+];
+
+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 +498,9 @@ 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,
+                        systemInstruction: { role: system, parts: [{ text: INSTRUCTIONS }] },
+                        ...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 +508,7 @@ const init = async (options) => {
                                 // { googleSearch: {} },
                                 { functionDeclarations: toolsGemini.map(x => x.def) },
                             ],
+                            toolConfig: { functionCallingConfig: { mode: 'AUTO' } },
                         }) : {},
                     }),
                     embedding: genAi.getGenerativeModel({
@@ -455,50 +566,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 +593,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 +647,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 +715,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 +744,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,9 +789,10 @@ const handleToolsCall = async (msg, options) => {
         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,
+                    input = fn.input = String.isString(fn?.input) ? parseJson(fn.input) : fn?.input;
+                    packMsg = (c, is_error) => ({
+                        type: 'tool_result', tool_use_id: fn.id,
+                        content: JSON.stringify(c), is_error,
                     });
                     break;
                 case GEMINI:
@@ -721,31 +808,39 @@ const handleToolsCall = async (msg, options) => {
                     break;
                 case CHATGPT: default:
                     input = parseJson(fn?.function?.arguments);
-                    packMsg = (t, e) => ({
-                        role: TOOL, tool_call_id: fn.id, [e ? 'error' : 'content']: t
+                    packMsg = (content = '', e = false) => ({
+                        role: TOOL, tool_call_id: fn.id,
+                        ...e ? { error: content, content: '' } : { content }
                     });
                     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(`Failed: ${err.message}`);
+                log(`Function call failed: ${err.message}`);
             }
         }
         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 +861,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 +885,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 +929,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 +982,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 +997,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 +1010,43 @@ 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);
+        textPart.text = [
+            ...packThink(options?.stream ? null : prvThink?.thinking),
+            ...packThink(options?.stream ? null : thinkPart?.thinking),
+            ...options?.toolsResponse ? [options?.toolsResponse] : [],
+            textPart.text,
+        ].join('\n\n');
+    } return packGptResp(event, options);
 };
 
 const uploadFile = async (input, options) => {
@@ -972,11 +1098,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 +1137,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(' ');
@@ -1232,7 +1356,8 @@ const talk = async (input, options) => {
             msgBuilder()
             break;
         case GEMINI:
-            sys.push(buildGeminiHistory(session.systemPrompt, { role: user }));
+            // already set in the while client initialization:
+            // sys.push(buildGeminiHistory(session.systemPrompt, { role: user }));
             msgBuilder = () => {
                 messages = [];
                 session.messages.map(x => {
@@ -1437,7 +1562,7 @@ export {
     ATTACHMENT_TOKEN_COST, CLOUD_37_SONNET, CODE_INTERPRETER, DEEPSEEK_R1,
     DEEPSEEK_R1_32B, DEEPSEEK_R1_70B, DEFAULT_MODELS,
     EMBEDDING_001,
-    FUNCTION, GEMINI_20_FLASH, GEMINI_20_FLASH_THINKING, GPT_4O, GPT_4O_MINI, GPT_O1, GPT_O3_MINI, MODELS,
+    FUNCTION, GEMINI_20_FLASH, GEMINI_20_FLASH_THINKING, GPT_4O, GPT_4O_MINI, GPT_O1, GPT_O3_MINI, INSTRUCTIONS, MODELS,
     OPENAI_VOICE,
     RETRIEVAL,
     TEXT_EMBEDDING_3_SMALL, _NEED, analyzeSessions,