@ibgib/web-gib 0.0.4 → 0.0.5

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

@@ -1,6 +1,6 @@
-import { extractErrorMsg, } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { extractErrorMsg, getTimestampInTicks, pickRandom_Letters, } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
 import { getIbAndGib, getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
-import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+import { Ib, IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
 import { IbGib_V1, } from "@ibgib/ts-gib/dist/V1/types.mjs";
 import { MetaspaceService } from "@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs";
 import { SpaceId } from "@ibgib/core-gib/dist/witness/space/space-types.mjs";
@@ -15,15 +15,18 @@ import {
     GLOBAL_LOG_A_LOT, TAG_AGENT_DESCRIPTION, TAG_AGENT_IB, TAG_AGENT_ICON,
     TAG_AGENT_TEXT,
 } from "../../constants.mjs";
-import { AgentWitnessAny, AgentWitnessIbGib_V1 } from "./agent-one-file.mjs";
-import { AGENT_REL8N_NAME } from "./agent-constants.mjs";
+import { AgentWitnessAny, } from "./agent-one-file.mjs";
+import { AGENT_ATOM, AGENT_REL8N_NAME, isTextSource, TEXT_SOURCE_VALUES, TextSource } from "./agent-constants.mjs";
 import {
     coupleDomainIbGibWithLocalIbGibViaIndex, getIndexNameFromIbGib,
     getLocalCoupledIbGibForDomainIbGib, getTagsIbGib
 } from "../../helpers.mjs";
 import { getAgentsSvc } from "./agents-service-v1.mjs";
-import { CreateConcreteAgentWitnessFactory, CreateNewAgentArg } from "./agent-types.mjs";
+import { AddlMetadataTextForAgentTextInfo, AgentIbInfo, AgentWitnessData_V1, AgentWitnessIbGib_V1, CreateConcreteAgentWitnessFactory, CreateNewAgentArg } from "./agent-types.mjs";
 import { CreateConcreteAgentWitnessFactory_Gemini } from "./gemini/gemini-agent-factory.mjs";
+import { CommentIbGib_V1 } from "@ibgib/core-gib/dist/common/comment/comment-types.mjs";
+import { validateIbGibIntrinsically } from "@ibgib/ts-gib/dist/V1/validate-helper.mjs";
+import { isComment, parseCommentIb } from "@ibgib/core-gib/dist/common/comment/comment-helper.mjs";
 // import { updateSpecialIndex } from "../../api/timeline/timeline-api.mjs";
 
 const logalot = GLOBAL_LOG_A_LOT; // change this when you want to turn off verbose logging
@@ -679,3 +682,238 @@ export function getConcreteAgentFactory(arg: CreateNewAgentArg): CreateConcreteA
         if (logalot) { console.log(`${lc} complete.`); }
     }
 }
+
+
+/**
+ * creates a begin/end tag composed of the {@link tagText} paired with an
+ * optional random id around the given {@link contentText}. The begin/end tags
+ * will be on their own line with {@link contentText} on the lines between.
+ *
+ * @example
+ * [MY_TAG|XBDWZ begin]
+ * contentText
+ * [MY_TAG|XBDWZ end]
+ * @returns
+ */
+export function taggifyForPrompt({
+    tagText,
+    contentText,
+    randomIdLength,
+}: {
+    /**
+     * the tag itself
+     */
+    tagText: string,
+    /**
+     * text to be surrounded by the tags' begin and end markers.
+     */
+    contentText: string,
+    /**
+     * length of random characters to pair with tag. if 0 or undefined, then no
+     * id will be generated.
+     */
+    randomIdLength?: number | undefined,
+}): string {
+    const lc = `[${taggifyForPrompt.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 94104ec059c89d4ba458d96580791d25)`); }
+        const fullTagText = !!randomIdLength ?
+            `${tagText}|${pickRandom_Letters({ count: randomIdLength })}` :
+            tagText;
+        return [
+            `[${fullTagText} begin]`,
+            contentText,
+            `[${fullTagText} end]`,
+        ].join('\n');
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * ATOW we specify if the text is from ai or human, as well as timestampInTicks.
+ * @returns metadata text to be included in the comment ibgib's ib.
+ * @see {@link parseAddlMetadataTextForAgentText}
+ */
+export function getAddlMetadataTextForAgentText({
+    textSrc,
+    other,
+}: {
+    /**
+     * @see {@link AddTextInfo.textSrc}
+     */
+    textSrc: TextSource,
+    /**
+     * if you have other underscore-delimited text, include that here.
+     */
+    other?: string,
+}): string {
+    const lc = `[${getAddlMetadataTextForAgentText.name}]`;
+    /**
+     * get and parse functions must **ALWAYS** match must match. If this array
+     * changes, change the other one.
+     */
+    return !!other ?
+        [textSrc, getTimestampInTicks(), other].join('_') :
+        [textSrc, getTimestampInTicks()].join('_');
+}
+
+/**
+ * ATOW we specify if the text is from ai or human, as well as timestampInTicks.
+ * @returns metadata text to be included in the comment ibgib's ib.
+ * @see {@link getAddlMetadataTextForAgentText}
+ */
+export function parseAddlMetadataTextForAgentText({
+    addlMetadataText,
+    ifError = 'warn',
+}: {
+    addlMetadataText: string,
+    ifError: 'throw' | 'warn' | 'ignore',
+}): AddlMetadataTextForAgentTextInfo {
+    const lc = `[${getAddlMetadataTextForAgentText.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 89b8b19a8d785b945fe0f816df762d25)`); }
+
+        /**
+         * get and parse functions must **ALWAYS** match must match. If this
+         * array changes, change the other one.
+         */
+        const [
+            textSrc,
+            timestampInTicksStr,
+            ...other
+        ] = addlMetadataText.split('_');
+        if (!textSrc) { throw new Error(`addlMetadataText.textSrc falsy (E: 40bbec4269c1688ab1390fa5d5440325)`); }
+        if (!isTextSource(textSrc)) { throw new Error(`addlMetadataText.textSrc (${textSrc}) is unexpected value. Expected one of ${TEXT_SOURCE_VALUES} (E: 02bae41275a39210e5737548747bd825)`); }
+        if (!timestampInTicksStr) { throw new Error(`addlMetadataText.timestampInTicks falsy (E: 03cbbc7515a1cff1fc7c12e3947c6825)`); }
+        const timestampInTicks = Number.parseInt(timestampInTicksStr);
+        if (Number.isNaN(timestampInTicks)) { throw new Error(`invalid timestampInTicks (${timestampInTicksStr}): value should be an integer but parse is NaN (E: 9d31e3563d972c02553ce18a19a19b25)`); }
+        return {
+            textSrc,
+            timestampInTicks,
+            other: other.length > 0 ? other : undefined,
+        };
+    } catch (error) {
+        const errorMsg = `${lc} ${extractErrorMsg(error)}`;
+        switch (ifError) {
+            case 'ignore':
+                return {
+                    textSrc: TextSource.UNKNOWN,
+                    timestampInTicks: 0,
+                    errorMsg: extractErrorMsg(error)
+                };
+            case 'warn':
+                console.warn(`${lc} ${errorMsg} (W: 3e1f4a98ad6461c9bd96462841c31b25)`)
+                return {
+                    textSrc: TextSource.UNKNOWN,
+                    timestampInTicks: 0,
+                    errorMsg: extractErrorMsg(error)
+                };
+            default:
+                console.error(`${lc} ${errorMsg} (E: 6396ed44947c52adf85788e1adc22825)`);
+                throw new Error(errorMsg);
+        }
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * builds the agent witness' ib based on given {@link data}
+ * @see {@link parseAgentIb}
+ */
+export function getAgentIb({
+    data,
+}: {
+    /** agent data, should be valid */
+    data: AgentWitnessData_V1,
+}): string {
+    const lc = `[${getAgentIb.name}]`;
+    const { name, uuid, type } = data;
+    if (!name) { throw new Error(`${lc} data.name falsy (E: 4c172c5b8a110ae26479b8c4006f3225)`); }
+    if (!uuid) { throw new Error(`${lc} data.uuid falsy (E: 67d2c79ac39e70e5ecfd1745e1fd3525)`); }
+    if (!type) { throw new Error(`${lc} data.type falsy (E: 53bf1f9a145a16be81296437682a7a25)`); }
+    const fields: string[] = [name, uuid, type];
+    if (fields.some(x => x.includes(' '))) { throw new Error(`invalid data. ib must not contain spaces in name, uuid, type. (E: 36a56e4685163848458be06f51d4ad25)`); }
+    /** getAgentIb must match parseAgentIb. If this array changes, change the other one. */
+    return [
+        AGENT_ATOM,
+        name,
+        uuid,
+        type,
+        // what else?
+    ].join(' ');
+}
+
+/**
+ * @returns parsed info from an ib
+ * @see {@link getAgentIb}
+ */
+export function parseAgentIb({
+    ib,
+}: {
+    ib: Ib,
+}): AgentIbInfo {
+    /** getAgentIb must match parseAgentIb. If this array changes, change the other one. */
+    const [
+        atom,
+        name,
+        uuid,
+        type,
+    ] = ib.split(' ');
+    if (atom !== AGENT_ATOM) { throw new Error(`invalid ib. first term expected to e an atom: ${AGENT_ATOM} (E: 3c01d42035d2e32c4bfd5c1bf363f725)`); }
+    if (!name) { throw new Error(`invalid ib. name falsy in agent ib (E: 8b494c544f05b8ef9c866078b761a725)`); }
+    if (!uuid) { throw new Error(`invalid ib. uuid falsy in agent ib (E: aba195db3ddcb000324ebed15351b725)`); }
+    if (!type) { throw new Error(`invalid ib. type falsy in agent ib (E: 8c814772394ae76342f95e885570c325)`); }
+    return { atom, name, uuid, type };
+}
+
+/**
+ * Validates a comment ibgib to ensure that it is usable in an agent witness
+ * context, especially that it includes the expected metadata format in its
+ * `ib`.
+ *
+ * @param {CommentIbGib_V1} ibGib - The comment ibgib to validate.
+ * @returns {string[]} An array of error messages if validation fails, or an empty array if no errors.
+ */
+export async function validateAgentWitnessCommentIbGib({
+    ibGib,
+}: {
+    ibGib: CommentIbGib_V1,
+}): Promise<string[]> {
+    const lc = `[${validateAgentWitnessCommentIbGib.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: f9a733a5a05b7f7494836d86a79e2d25)`); }
+
+        const errors: string[] = await validateIbGibIntrinsically({ ibGib }) ?? [];
+
+        if (!isComment({ ibGib })) {
+            errors.push(`${lc} not a comment ibgib (E: 08676d94c698c6e42e6c35e94a58f125)`);
+            return errors; /* returns early */
+        }
+
+        const { safeIbCommentMetadataText: addlMetadataText } = parseCommentIb({ ib: ibGib.ib });
+
+        if (addlMetadataText) {
+            const addlMetaInfo = parseAddlMetadataTextForAgentText({
+                addlMetadataText,
+                ifError: 'warn'
+            });
+            if (addlMetaInfo.errorMsg) {
+                errors.push(`${lc} could not parse addlMetadataText: ${addlMetaInfo.errorMsg} (E: e178265c33e5e94947a02c1f9d6a7425)`);
+            }
+        } else {
+            errors.push(`${lc} addlMetadataText falsy. this implies something is incorrect with the comment's ib, as we expect agent comments to have certain metadata (e.g. textSrc). See AgentWitness_V1 (and data interface) for more info. (E: 7c3c41c973a67256c432604666106b25)`);
+        }
+
+        return errors;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}