@ibgib/web-gib 0.0.1

package/src/witness/agent/gemini/gemini-agent-factory.mts

@@ -0,0 +1,135 @@
+import {
+    clone, extractErrorMsg, getUUID,
+} from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { AgentWitnessAny, AgentWitnessData_V1, AgentWitnessIbGib_V1, AgentWitnessRel8ns_V1, DEFAULT_AGENT_DATA_V1, DEFAULT_AGENT_REL8NS_V1, } from '../agent-one-file.mjs';
+import { AgentWitnessGemini_V1 } from './agent-witness-gemini-v1.mjs';
+import { storageGet } from '../../../storage/storage-helpers.web.mjs';
+import { CreateConcreteAgentWitnessFactory, CreateNewAgentArg } from '../agent-types.mjs';
+import type { AgentsService_V1 } from '../agents-service-v1.mjs';
+import { getGlobalDbName, getGlobalIndexedDbKey_APIKey, getGlobalStoreName } from '../../../helpers.web.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * factory class to create gemini api agents.
+ *
+ * This doesn't need to be instantiated necessarily, as this is used via the
+ * more general factory function {@link AgentsService_V1.createNewAgent}
+ */
+export class CreateConcreteAgentWitnessFactory_Gemini
+    implements CreateConcreteAgentWitnessFactory {
+    private lc: string = `[${CreateConcreteAgentWitnessFactory_Gemini.name}]`;
+
+    private arg: CreateNewAgentArg;
+
+    constructor(arg: CreateNewAgentArg) {
+        this.arg = arg;
+    }
+
+    async createInitialData(superSpace: IbGibSpaceAny): Promise<AgentWitnessData_V1> {
+        const lc = `${this.lc}[${this.createInitialData.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: f4c8ac488804666077cfc2237972d625)`); }
+
+            const { name, api, model, type, availableFunctions, } = this.arg;
+            if (!model) { throw new Error(`(UNEXPECTED) model falsy? (E: ee7286c772a37fa86236c85f96233625)`); }
+            if (!superSpace.data) { throw new Error(`(UNEXPECTED) superSpace.data falsy? (E: 858d5950b9ef7a0175482a51caaf9c25)`); }
+            if (!superSpace.data.uuid) { throw new Error(`(UNEXPECTED) superSpace.data.uuid falsy? (E: 08867535db1b254d73c050bd5086e525)`); }
+
+            const data = clone(DEFAULT_AGENT_DATA_V1) as AgentWitnessData_V1;
+            if (name) { data.name = name; }
+            data.uuid = await getUUID();
+            data.superSpaceId = superSpace.data.uuid;
+            data.api = api;
+            data.model = model;
+            data.type = type;
+            data.availableFunctionNameOrIds = availableFunctions.map(x => x.nameOrId);
+            data.classname = AgentWitnessGemini_V1.name;
+
+            // if (model) { data.model = model; }
+
+            return data;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+    async createInitialRel8ns(): Promise<AgentWitnessRel8ns_V1 | undefined> {
+        const lc = `${this.lc}[${this.createInitialRel8ns.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 2d4933ea3761bd7df701d8d306fb2825)`); }
+
+            const rel8ns = !!DEFAULT_AGENT_REL8NS_V1 ?
+                clone(DEFAULT_AGENT_REL8NS_V1) as AgentWitnessRel8ns_V1 :
+                undefined;
+
+            return rel8ns;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+    async createWitness(): Promise<AgentWitnessAny> {
+        const lc = `[${this.createWitness.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 36709dfa0c398d63d64c4f6ba9055625)`); }
+            const { api, model } = this.arg;
+            if (api === 'gemini') {
+                // model is ignored atow 1/2025
+                const witness = new AgentWitnessGemini_V1();
+                await witness.initialized;
+                return witness;
+            } else {
+                throw new Error(`(UNEXPECTED) unknown api: ${api}? only 'gemini' currently implemented (E: 2d1cb22ce787c6c42d4532c260320125)`);
+            }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+
+    }
+
+}
+
+/**
+ * Takes an incoming {@link agentIbGib} (dto), creates a new agent witness,
+ * initializes it and loads that {@link agentIbGib} dto into it.
+ *
+ * @returns the full agent witness
+ */
+export async function agentIbGibDtoToWitness({
+    agentIbGib,
+}: {
+    agentIbGib: AgentWitnessIbGib_V1,
+}): Promise<AgentWitnessAny> {
+    const lc = `[${agentIbGibDtoToWitness.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 5a4efefba9e4bdfb942afbe7919fff25)`); }
+        const agentWitness = new AgentWitnessGemini_V1();
+        await agentWitness.initialized;
+        await agentWitness.loadIbGibDto(agentIbGib);
+        agentWitness.fnGetAPIKey = async () => {
+            let apiKey = await storageGet({
+                dbName: getGlobalDbName(),
+                storeName: await getGlobalStoreName(),
+                key: await getGlobalIndexedDbKey_APIKey(),
+            });
+            return apiKey ?? '';
+        }
+        return agentWitness;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}

package/src/witness/agent/gemini/gemini-constants.mts

@@ -0,0 +1,79 @@
+import { AGENT_NAME_REGEXP } from "../agent-constants.mjs";
+
+export const GEMINI_ERROR_STATUS_MODEL_OVERLOADED = 503;
+export const GEMINI_ERROR_STATUS_RATE_QUOTA_EXCEEDED = 429;
+
+/**
+ * the path error.errorDetails is an array of error info objects.
+ */
+export const GEMINI_ERROR_DETAILS_TYPE_QUOTA_FAILURE = "type.googleapis.com/google.rpc.QuotaFailure";
+export const GEMINI_ERROR_DETAILS_TYPE_RETRY_INFO = "type.googleapis.com/google.rpc.RetryInfo";
+export const GEMINI_ERROR_DETAILS_TYPE_RETRY_INFO_RETRY_DELAY_KEY = 'retryDelay';
+
+
+// #region GeminiModel enum
+/**
+ * @see {@link GeminiModel.GEMINI_2_0_FLASH}
+ */
+const GEMINI_MODEL_GEMINI_2_0_FLASH = 'gemini-2.0-flash';
+const GEMINI_MODEL_GEMINI_2_0_FLASH_LITE = 'gemini-2.0-flash-lite';
+// const GEMINI_MODEL_GEMINI_2_0_FLASH = 'gemini-2.0-flash-exp';
+// /**
+//  * @see {@link GeminiModel.GEMINI_1_5_FLASH}
+//  */
+// const GEMINI_MODEL_GEMINI_1_5_FLASH = 'gemini-1.5-flash';
+// /**
+//  * @see {@link GeminiModel.GEMINI_1_5_FLASH_8B}
+//  */
+// const GEMINI_MODEL_GEMINI_1_5_FLASH_8B = 'gemini-1.5-flash-8b';
+// /**
+//  * @see {@link GeminiModel.GEMINI_1_5_PRO}
+//  */
+// const GEMINI_MODEL_GEMINI_1_5_PRO = 'gemini-1.5-pro';
+
+/**
+ * Enum of Gemini models that are available to the agent.
+ */
+export type GeminiModel =
+    | typeof GEMINI_MODEL_GEMINI_2_0_FLASH
+    | typeof GEMINI_MODEL_GEMINI_2_0_FLASH_LITE
+    // | typeof GEMINI_MODEL_GEMINI_1_5_FLASH
+    // | typeof GEMINI_MODEL_GEMINI_1_5_FLASH_8B
+    // | typeof GEMINI_MODEL_GEMINI_1_5_PRO
+    ;
+
+/**
+ * @see {@link GeminiModel}
+ */
+export const GeminiModel = {
+    /**
+     * @see {@link GEMINI_MODEL_GEMINI_2_0_FLASH}
+     */
+    GEMINI_2_0_FLASH: GEMINI_MODEL_GEMINI_2_0_FLASH as GeminiModel,
+    /**
+     * @see {@link GEMINI_MODEL_GEMINI_2_0_FLASH_LITE}
+     */
+    GEMINI_2_0_FLASH_LITE: GEMINI_MODEL_GEMINI_2_0_FLASH_LITE as GeminiModel,
+    // /**
+    //  * @see {@link GEMINI_MODEL_GEMINI_1_5_FLASH}
+    //  */
+    // GEMINI_1_5_FLASH: GEMINI_MODEL_GEMINI_1_5_FLASH as GeminiModel,
+    // /**
+    //  * @see {@link GEMINI_MODEL_GEMINI_1_5_FLASH_8B}
+    //  */
+    // GEMINI_1_5_FLASH_8B: GEMINI_MODEL_GEMINI_1_5_FLASH_8B as GeminiModel,
+    // /**
+    //  * @see {@link GEMINI_MODEL_GEMINI_1_5_PRO}
+    //  */
+    // GEMINI_1_5_PRO: GEMINI_MODEL_GEMINI_1_5_PRO as GeminiModel,
+} satisfies { [key: string]: GeminiModel };
+
+export const GEMINI_MODEL_VALUES = Object.freeze(Object.values(GeminiModel));
+export function isGeminiModel(str: string): str is GeminiModel {
+    return !!str && GEMINI_MODEL_VALUES.includes(str as GeminiModel);
+}
+
+// #endregion GeminiModel enum
+
+export const GEMINI_BACKUP_MODEL_STR = GeminiModel.GEMINI_2_0_FLASH_LITE;
+export const GEMINI_MAX_TRY_COUNT = 5;

package/src/witness/agent/gemini/gemini-helpers.mts

@@ -0,0 +1,216 @@
+import { Content, FunctionCall, FunctionCallPart, FunctionResponse, FunctionResponsePart, TextPart } from "@google/generative-ai";
+import type { GoogleGenerativeAI, ModelParams } from "@google/generative-ai";
+
+import { extractErrorMsg, pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { isComment, } from "@ibgib/core-gib/dist/common/comment/comment-helper.mjs";
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { getAllFunctionInfos } from "../../../api/api-index.mjs";
+import { APIFunctionInfo } from "../../../api/api-types.mjs";
+import { PromptInfo, } from "../agent-one-file.mjs";
+import { FUNCTION_CALL_REQUEST_COMMENT_TAG, TextSource, } from "../agent-constants.mjs";
+import { FunctionResponsePart_ResponseWrapper, PromptInfoEntryGemini, PromptInfoGemini } from "./gemini-types.mjs";
+import { FunctionInfoIbGib_V1 } from "../function-info/function-info-one-file.mjs";
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+export function textSourceToGeminiRole(src: TextSource): string {
+    switch (src) {
+        case TextSource.HUMAN:
+            return 'user';
+        case TextSource.AI:
+            return 'model';
+        case TextSource.FUNCTION:
+            return 'function';
+        case TextSource.HARDCODED:
+            return 'user';
+        case TextSource.UNKNOWN:
+            return 'user';
+        default:
+            throw new Error(`(UNEXPECTED) src is not a valid TextSource? src: ${src} (E: 9d954fe0bc49cf4572a65b19b6173925)`);
+    }
+}
+// export function geminiRoleToTextSource(geminiRole: 'user' | 'model' | ''): TextSource {
+//     if (geminiRole === 'user') {
+//         return TextSource.HUMAN;
+//     } else if (geminiRole === 'model') {
+//         return TextSource.AI;
+//     } else {
+//         return TextSource.UNKNOWN;
+//     }
+// }
+
+export function isPromptInfoGemini(info: PromptInfo): info is PromptInfoGemini {
+    return info.api === 'gemini';
+}
+
+/**
+ * gemini api-specific helper that maps gemini function call returned from the
+ * model to our API function info interface
+ */
+export function geminiFunctionCallToAPIFunctionInfo({
+    functionCall,
+}: {
+    functionCall: FunctionCall
+}): { info: APIFunctionInfo, args: any } {
+    const lc = `[${geminiFunctionCallToAPIFunctionInfo.name}]`;
+    const functionInfo = getAllFunctionInfos().get(functionCall.name);
+    if (!functionInfo) {
+        throw new Error(`${lc} no APIFunctionInfo found matching name: ${functionCall.name} (E: 7c5c7c17988a666a86e72299630c7f25)`);
+    }
+    return {
+        info: functionInfo,
+        args: functionCall.args ?? undefined,
+    };
+}
+
+/**
+ * Takes 0 or more entries and combines them into a single {@link Content}
+ * object that Gemini API expects for `systemInstruction` when using the fn
+ * {@link GoogleGenerativeAI.getGenerativeModel} (@see {@link ModelParams}).
+ *
+ * @param entries for system instruction, probably from {@link AgentWitnessGemini_V1.systemPromptParts}
+ * @returns undefined if no entries, else single Gemini API Content object with role === "user" and combined parts from {@link systemPromptEntries}
+ */
+export function systemPromptEntriesToSystemInstructionContent({
+    systemPromptEntries,
+}: {
+    systemPromptEntries: PromptInfoEntryGemini[],
+}): Content | undefined {
+    const lc = `[${systemPromptEntriesToSystemInstructionContent.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 18693a97427939699285ef8c1a9cc425)`); }
+
+        if (systemPromptEntries.length === 0) { return undefined; /* <<<< returns early */ }
+        if (!systemPromptEntries.every(entry => entry.src === TextSource.HUMAN)) {
+            if (logalot) { console.warn(`${lc} not every system entry's src is human. We're still going to say that these are "user" origin in Gemini API. (W: 7115e2be876498ecb1e153c79a86e125)`); }
+        }
+        const sysInstructionContent: Content = {
+            role: "user",
+            parts: systemPromptEntries.flatMap(entry => entry.content.parts),
+        };
+        if (logalot) { console.log(`${lc} sysInstructionContent: ${pretty(sysInstructionContent)} (I: 011e5b865c23eb0b640df3f464ac2525)`); }
+        return sysInstructionContent;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * helper function (not a guard) that determines if the given ibgib has the
+ * expected shape of a Function Call Request comment (FCR).
+ *
+ * These objects are created when a model requests a function call.
+ *
+ * ATOW (01/2025) these FCRs should include both one or more infos for both
+ * function calls and function responses.
+ */
+export function isFunctionCallRequestComment({ ibGib }: { ibGib: IbGib_V1 }): boolean {
+    const lc = `[${isFunctionCallRequestComment.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 986d3edcd4f3aaf1d7eb0f8b59206b25)`); }
+
+        if (!ibGib) {
+            if (logalot) { console.warn(`${lc} ibGib falsy. (W: a70390e8bc3f420a92d3a84f4c78f12a)`); }
+            return false; /* <<<< returns early */
+        }
+        if (!isComment({ ibGib })) {
+            if (logalot) { console.log(`${lc} not a comment ibgib (I: 6a62c4f6e13776616855c4f237a5206b)`); }
+            return false; /* <<<< returns early */
+        }
+        if (!ibGib.data) {
+            if (logalot) { console.log(`${lc} ibGib.data falsy (I: 69eb86975640475395bb74944141a46d)`); }
+            return false; /* <<<< returns early */
+        }
+
+        const { text } = ibGib.data;
+        if (!text) {
+            if (logalot) { console.log(`${lc} text falsy (I: e348e38c841b4443b3f09e75c0215b24)`); }
+            return false; /* <<<< returns early */
+        }
+
+        if (text.includes(FUNCTION_CALL_REQUEST_COMMENT_TAG)) {
+            if (logalot) { console.log(`${lc} has tag. returning true. (I: 6d76b27d558d44f696582f41af561f29)`); }
+            return true;
+        }
+        // let { safeIbCommentMetadataText } = parseCommentIb({ ib: ibGib.ib });
+        // if (safeIbCommentMetadataText && safeIbCommentMetadataText.includes(FUNCTION_INFO_ATOM)) {
+        //  return true;
+        // }
+
+        if (logalot) { console.log(`${lc} no indicator found. returning false. (I: 815f181a0a08058362f76b08a8964674)`); }
+
+        return false;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+
+/**
+ * Helper function to create Gemini API FunctionCallPart and FunctionResponsePart
+ * objects from a FunctionInfoIbGib_V1.
+ *
+ * @param {object} arg - Arguments object.
+ * @param {FunctionInfoIbGib_V1} arg.functionInfoIbGib - The FunctionInfoIbGib_V1 instance containing function call details.
+ * @returns {{ call: FunctionCallPart; response: FunctionResponsePart }} - An object containing both FunctionCallPart and FunctionResponsePart objects.
+ * @throws {Error} If there's an error during the process, such as missing function name or arguments.
+ */
+export function getFunctionCallAndResponseParts({
+    functionInfoIbGib,
+}: {
+    functionInfoIbGib: FunctionInfoIbGib_V1,
+}): { call: FunctionCallPart, response: FunctionResponsePart } {
+    const lc = `[${getFunctionCallAndResponseParts.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 1a2b3c4d5e6f7a8b)`); }
+
+        if (!functionInfoIbGib) {
+            throw new Error(`${lc} functionInfoIbGib parameter is required. (E: 9c8f7a3b2d1e4a5b6c7d8e9f)`);
+        }
+        if (!functionInfoIbGib.data) {
+            throw new Error(`${lc} functionInfoIbGib.data is required. (E: 2b3c4d5e6f7a8b1c2d3e4f5a)`);
+        }
+
+        const { fnName, fnArgs, fnResult } = functionInfoIbGib.data;
+
+        if (!fnName) {
+            throw new Error(`${lc} functionInfoIbGib.data.fnName is required. (E: 6f7a8b1c2d3e4f5a6b7c8d9e)`);
+        }
+
+        // 1. Create FunctionCallPart
+        const functionCallPart: FunctionCallPart = {
+            functionCall: {
+                name: fnName,
+                args: fnArgs ?? {}, // Use empty object if fnArgs is not provided
+            } as FunctionCall,
+        } satisfies FunctionCallPart;
+
+
+        // 2. Create FunctionResponsePart
+        const responseWrapper: FunctionResponsePart_ResponseWrapper = {
+            value: fnResult,
+        };
+        const functionResponsePart: FunctionResponsePart = {
+            functionResponse: {
+                name: fnName,
+                response: responseWrapper, // Use empty object if fnResult is not provided
+            } as FunctionResponse,
+        } satisfies FunctionResponsePart;
+
+        return { call: functionCallPart, response: functionResponsePart };
+
+    } catch (error) {
+        console.error(`${lc} Error: ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}

package/src/witness/agent/gemini/gemini-types.mts

@@ -0,0 +1,88 @@
+import { Content, } from "@google/generative-ai";
+import type { StartChatParams, ChatSession, FunctionCallingMode, } from "@google/generative-ai";
+import { PromptInfo, } from "../agent-one-file.mjs";
+import { TextSource } from "../agent-constants.mjs";
+
+export interface PromptInfoEntryGemini {
+    /**
+     * The source of the text, in terms of our code definition.
+     *
+     * I say this because the Gemini API only considers "user" and "model" but
+     * we keep more information (and more accurate information) than this.
+     *
+     * For example, the Gemini API expects function responses to be role "user".
+     * But we would store this src as {@link TextSource.FUNCTION}
+     */
+    src: TextSource;
+    // /**
+    //  * the raw text of an entry
+    //  */
+    // text?: string;
+    /**
+     * the shape of the entry that the Gemini API would expect
+     */
+    content: Content;
+};
+/**
+ * Information required specifically for the Gemini API.
+ */
+export interface PromptInfoGemini extends PromptInfo {
+    /**
+     * The system instructions' parts that we'll concatenate into system prompt.
+     */
+    systemPromptEntries: PromptInfoEntryGemini[];
+    /**
+     * The history of the chat, i.e., the contents of the chat sans the most
+     * recent.
+     *
+     * NOTE: We will be using this for the gemini api's "chat" function.
+     *
+     * @see {@link StartChatParams.history}
+     */
+    chatPromptHistoryParts: PromptInfoEntryGemini[];
+    /**
+    * The most recent chat message
+    *
+    * @see {@link ChatSession.sendMessage}
+    */
+    chatPromptCurrent: PromptInfoEntryGemini;
+    /**
+     * if truthy, this will override the default function calling mode when
+     * prompting the LLM.
+     *
+     * if falsy, will use the default (FunctionCallingMode.ANY)
+     *
+     * @see {@link FunctionCallingMode}
+     *
+     * ## notes
+     *
+     * I'm adding this for custom prompt. right now, it works better when
+     * forcing the model to call a function, but I am now wanting the use case
+     * to just ask the model a "normal" chat llm question (for translating some
+     * text).
+     */
+    overrideFunctionCallingMode?: FunctionCallingMode;
+}
+
+/**
+ * Gemini returns either function calls or raw text atow (01/2025)
+ */
+export type PromptAPIResult_Gemini =
+    | {
+        /**
+         * raw strings of function calls requested returned by the underlying
+         * API's model (right now Gemini)
+         */
+        functionCalls: string[]
+    }
+    | { text: string };
+
+/**
+ * This is a "kluge" IMO because it wraps the response part to be able to handle
+ * all responses of functions. This is a limitation of the Gemini API which requires an
+ * object as the response part's value. So if a function returns "undefined" or an array,
+ * it throws an error. So this is a wrapper.
+ */
+export interface FunctionResponsePart_ResponseWrapper {
+    value: any | undefined;
+}