@ibgib/web-gib 0.0.4 → 0.0.6

package/src/witness/agent/agent-one-file.mts

@@ -1,16 +1,11 @@
-import {
-    clone,
-    delay,
-    extractErrorMsg, getTimestampInTicks, pickRandom_Letters, pretty
-} from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { delay, extractErrorMsg, pickRandom_Letters, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { UUID_REGEXP } from '@ibgib/helper-gib/dist/constants.mjs';
-import { Ib, IbGibAddr, TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
-import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { IbGibAddr, TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
+import { IbGib_V1, } from '@ibgib/ts-gib/dist/V1/types.mjs';
 import { rel8 } from '@ibgib/ts-gib/dist/V1/transforms/rel8.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 import { GIB, IB, ROOT, ROOT_ADDR } from '@ibgib/ts-gib/dist/V1/constants.mjs';
 import { mut8 } from '@ibgib/ts-gib/dist/V1/transforms/mut8.mjs';
-import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
 import { getGibInfo } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
 import { WitnessData_V1, WitnessRel8ns_V1, } from '@ibgib/core-gib/dist/witness/witness-types.mjs';
 import { CommentIbGib_V1 } from '@ibgib/core-gib/dist/common/comment/comment-types.mjs';
@@ -25,9 +20,9 @@ import { execInSpaceWithLocking, } from '@ibgib/core-gib/dist/witness/space/spac
 
 import { GLOBAL_LOG_A_LOT } from '../../constants.mjs';
 import {
-    AGENT_ATOM, AGENT_DESC_REGEXP, AGENT_NAME_REGEXP, AGENT_REL8N_NAME, DEFAULT_DESCRIPTION_AGENT,
-    DEFAULT_NAME_AGENT, DEFAULT_UUID_AGENT, FUNCTION_CALL_REQUEST_COMMENT_TAG,
-    isTextSource, TEXT_SOURCE_VALUES, TextSource,
+    AGENT_ATOM, AGENT_DESC_REGEXP, AGENT_NAME_REGEXP,
+    DEFAULT_DESCRIPTION_AGENT, DEFAULT_NAME_AGENT, DEFAULT_UUID_AGENT,
+    FUNCTION_CALL_REQUEST_COMMENT_TAG, TextSource,
 } from './agent-constants.mjs';
 import { APIFunctionInfo } from '../../api/api-types.mjs';
 import { getAllFunctionInfos, } from '../../api/api-index.mjs';
@@ -35,474 +30,14 @@ import { FUNCTION_INFO_REL8N_NAME, FunctionInfoIbGib_V1, createFunctionInfoIbGib
 import { GeminiModel } from './gemini/gemini-constants.mjs';
 import { PromptAPIResult_Gemini } from './gemini/gemini-types.mjs';
 import { getGlobalMetaspace_waitIfNeeded } from '../../helpers.mjs';
-import { updateAgentIndex } from './agent-helpers.mjs';
+import { getAddlMetadataTextForAgentText, parseAddlMetadataTextForAgentText, taggifyForPrompt, updateAgentIndex } from './agent-helpers.mjs';
 import { getAgentsSvc } from './agents-service-v1.mjs';
 import { LiveProxyIbGib } from '../live-proxy-ibgib/live-proxy-ibgib-one-file.mjs';
-import { AgentAPI, AgentModel } from './agent-types.mjs';
+import { AddTextsOpts, AgentAPI, AgentModel, AgentWitnessData_V1, AgentWitnessIbGib_V1, AgentWitnessRel8ns_V1, PromptAPIResult, PromptInfo, PromptOneOffOpts, SetActiveContextOpts } from './agent-types.mjs';
 import { AGENT_SPECIAL_IBGIB_TYPE_PRIMARYAGENT } from '../../agent-texts/primary-agent-texts.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
 
-export const DEFAULT_AGENT_DATA_V1: AgentWitnessData_V1 = {
-    version: '1',
-    uuid: DEFAULT_UUID_AGENT,
-    name: DEFAULT_NAME_AGENT,
-    description: DEFAULT_DESCRIPTION_AGENT,
-    classname: `AgentWitness_V1`,
-    icon: 'happy', // arbitrary
-    persistOptsAndResultIbGibs: false,
-    allowPrimitiveArgs: true,
-    catchAllErrors: true,
-    trace: false,
-
-    // agent-specific props
-    subSpaceId: '',
-    // purpose: '',
-    superSpaceId: '',
-    availableFunctionNameOrIds: [],
-    model: GeminiModel.GEMINI_2_0_FLASH,
-    // model: GeminiModel.GEMINI_1_5_PRO,
-    api: 'gemini',
-    type: AGENT_SPECIAL_IBGIB_TYPE_PRIMARYAGENT,
-    "@currentContextTjpAddr": ROOT_ADDR,
-}
-/**
- * don't init with an empty obj. use undefined or factory_v1.firstGen blows up.
- */
-export const DEFAULT_AGENT_REL8NS_V1: AgentWitnessRel8ns_V1 | undefined = undefined;
-
-
-/**
- * @interface AgentWitnessData - Data interface for the AgentWitness.
- * @extends WitnessData_V1
- */
-export interface AgentWitnessData_V1 extends WitnessData_V1 {
-    /**
-     * this id corresponds to what space the agent has access to as its own "internal" space.
-     *
-     * TODO: implement initialization code to create/get this space when the
-     * agent is created/initialized.
-     *
-     * TODO: implement an APIFunctionInfo for the agent
-     *
-     * it is possible that we will add access to other spaces in the future.
-     */
-    subSpaceId: SpaceId;
-    /**
-     * The space in which the agent's ibgib itself is saved. This is often
-     * (always?) different than the super space in which the agent itself
-     * resides.
-     */
-    superSpaceId: SpaceId;
-    /**
-     * nameOrId corresponding to the function info
-     */
-    availableFunctionNameOrIds: string[];
-    /**
-     * @see {@link AgentAPI}
-     */
-    api: AgentAPI;
-    /**
-     * @see {@link AgentModel}
-     */
-    model: AgentModel;
-    /**
-     * A more fine-grained discriminator.
-     */
-    type: string;
-    /**
-     * soft link to the current context ibgib. May be out of date, so should use
-     * get latest on the space (often can do this via metaspace with this
-     * agent's {@link superSpaceId}).
-     *
-     * This defaults to ib^gib (ROOT_ADDR), so if this is the value, then this
-     * has not been initialized yet and the agent needs to have their context
-     * set.
-     */
-    "@currentContextTjpAddr": IbGibAddr; // string
-}
-
-/**
- * @interface AgentWitnessRel8ns - Rel8ns interface for the AgentWitness.
- * @extends IbGibRel8ns_V1
- */
-export interface AgentWitnessRel8ns_V1 extends WitnessRel8ns_V1 {
-    /**
-     * @property chat - Relationships to comment ibgibs representing chat
-     * history for this agent.
-     *
-     * These are expected to be comment ibgibs with special additional metadata
-     * text in the ib that pertains to the agents {@link AgentWitness_V1}.
-     *
-     * @see {@link system}
-     */
-    chat?: IbGibAddr[];
-    /**
-     * @property system - Relationships to comment ibgibs representing the
-     * system prompt.
-     *
-     * This is a Gemini-specific construct that I don't know if it exists in
-     * other APIs. But the intent is that these are comment ibgibs to be used in
-     * composing any meta text that is not part of a "chat" between one or more
-     * users and one or more models.
-     *
-     * These are expected to be comment ibgibs with special additional metadata
-     * text in the ib that pertains to the agents {@link AgentWitness_V1}.
-     *
-     * @see {@link system}
-     */
-    system?: IbGibAddr[];
-}
-
-/**
- * @interface AgentWitnessIbGib_V1 - Interface for an agent ibgib.
- *
- * @see {@link AgentWitness_V1}
- */
-export interface AgentWitnessIbGib_V1 extends IbGib_V1<AgentWitnessData_V1, AgentWitnessRel8ns_V1> {
-}
-
-export interface AddTextInfo {
-    /**
-     * @property text - raw comment text string to add
-     * @optional
-     */
-    text?: string;
-    /**
-     * @optional @property commentIbGib - existing comment to add
-     */
-    commentIbGib?: CommentIbGib_V1;
-    // textSrc: 'hardcoded' | 'human' | 'ai' | 'unknown';
-    textSrc: TextSource;
-    /**
-     * @property isSystem - If true, adds the text to the system prompt instead of chat history.
-     * @default false
-     */
-    isSystem?: boolean;
-}
-
-/**
- * @interface AddTextsOpts - Options for adding multiple text comments.
- */
-export interface AddTextsOpts {
-    infos: AddTextInfo[];
-}
-
-export interface PromptOneOffOpts {
-    text: string;
-    /**
-     * ad hoc system instructions for the one off call.
-     */
-    systemInstructions: string;
-}
-
-/**
- * an agent can only have one active context at any time.
- *
- * Really this is a timeline, so the key thing of this context ibgib is its
- * temporal junction point (tjp).
- */
-export interface SetActiveContextOpts {
-    contextIbGib: IbGib_V1;
-    /**
-     * for debug purposes
-     */
-    loggingInfo?: string;
-}
-
-/**
- * When composing the prompt to send to the model, this is the information that
- * we build up.
- */
-export interface PromptInfo {
-    /**
-     * discriminator of what concrete info is contained in this object.
-     */
-    api: AgentAPI;
-}
-
-
-/**
- * @interface {@link PromptAPIResult} - shape of the result when calling into an
- * api-specific model. In general, the api will either return a string or a
- * function call request with optional arg(s)
- * @see {@link AgentWitness_V1.callTextAPI}
- */
-export type PromptAPIResult = | PromptAPIResult_Gemini;
-
-/**
- * info object containing information in an agent ib schema.
- */
-export interface AgentIbInfo {
-    /**
-     * should be {@link AGENT_ATOM}
-     */
-    atom: string,
-    name: string,
-    uuid: string,
-    type: string,
-}
-
-/**
- * information encoded in the addlMetadataText part of a comment ibgib that is
- * part of an agent's chat/system text.
- *
- * notes: long name...
- */
-export interface AddlMetadataTextForAgentTextInfo {
-    /**
-     * @see {@link AddTextInfo.textSrc}
-     */
-    textSrc: TextSource;
-    timestampInTicks: number;
-    /**
-     * if there are additional underscore-delimited metadata texts, they will be here.
-     */
-    other?: string[];
-    errorMsg?: string;
-}
-
-// #region helpers
-
-/**
- * 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.`); }
-    }
-}
-
-
-
-// #endregion helpers
-
-
 /**
  * @extends LightWitnessBase_V1<AgentWitnessData_V1, AgentWitnessRel8ns_V1>
  *