@iyio/convo-lang/src/lib/convo-lib.d.ts

A conversational language.

import { ConvoBaseType, ConvoDocumentReference, ConvoFlowController, ConvoMessage, ConvoMessageTemplate, ConvoMetadata, ConvoPrintFunction, ConvoScope, ConvoScopeError, ConvoScopeFunction, ConvoStatement, ConvoTag, ConvoThreadFilter, ConvoTokenUsage, ConvoType, FlatConvoMessage, OptionalConvoValue, convoObjFlag } from "./convo-types";
export declare const convoBodyFnName = "__body";
export declare const convoArgsName = "__args";
export declare const convoResultReturnName = "__return";
export declare const convoResultErrorName = "__error";
export declare const convoDisableAutoCompleteName = "__disableAutoComplete";
export declare const convoStructFnName = "struct";
export declare const convoNewFnName = "new";
export declare const convoMapFnName = "map";
export declare const convoArrayFnName = "array";
export declare const convoJsonMapFnName = "jsonMap";
export declare const convoJsonArrayFnName = "jsonArray";
export declare const convoSwitchFnName = "switch";
export declare const convoCaseFnName = "case";
export declare const convoDefaultFnName = "default";
export declare const convoTestFnName = "test";
export declare const convoPipeFnName = "pipe";
export declare const convoLocalFunctionModifier = "local";
export declare const convoCallFunctionModifier = "call";
export declare const convoGlobalRef = "convo";
export declare const convoEnumFnName = "enum";
export declare const convoMetadataKey: unique symbol;
export declare const convoCaptureMetadataTag = "captureMetadata";
export declare const defaultConvoTask = "default";
export declare const convoRoles: {
    readonly user: "user";
    readonly assistant: "assistant";
    readonly rag: "rag";
    /**
     * Used to define a prefix to add to rag messages
     */
    readonly ragPrefix: "ragPrefix";
    /**
     * Used to define a suffix to add to rag messages
     */
    readonly ragSuffix: "ragSuffix";
};
export declare const convoFunctions: {
    readonly queryImage: "queryImage";
    readonly getState: "getState";
};
/**
 * reserved system variables
 */
export declare const convoVars: {
    /**
     * In environments that have access to the filesystem __cwd defines the current working directory.
     */
    readonly __cwd: "__cwd";
    /**
     * When set to true debugging information will be added to conversations.
     */
    readonly __debug: "__debug";
    /**
     * Sets the default model
     */
    readonly __model: "__model";
    /**
     * Sets the default completion endpoint
     */
    readonly __endpoint: "__endpoint";
    /**
     * When set to true time tracking will be enabled.
     */
    readonly __trackTime: "__trackTime";
    /**
     * When set to true token usage tracking will be enabled.
     */
    readonly __trackTokenUsage: "__trackTokenUsage";
    /**
     * When set to true the model used as a completion provider will be tracked.
     */
    readonly __trackModel: "__trackModel";
    /**
     * When defined __visionSystemMessage will be injected into the system message of conversations
     * with vision capabilities. __visionSystemMessage will override the default vision
     * system message.
     */
    readonly __visionSystemMessage: "__visionSystemMessage";
    /**
     * The default system message used for completing vision requests. Vision requests are typically
     * completed in a separate conversation that supports vision messages. By default the system
     * message of the conversation that triggered the vision request will be used.
     */
    readonly __visionServiceSystemMessage: "__visionServiceSystemMessage";
    /**
     * Response used with the system is not able to generate a vision response.
     */
    readonly __defaultVisionResponse: "__defaultVisionResponse";
    /**
     * A reference to markdown vars.
     */
    readonly __md: "__md";
    /**
     * Enables retrieval augmented generation (RAG). The value of the __rag can either be true,
     * false or a number. The value indicates the number of rag results that should be sent to the
     * LLM by default all rag message will be sent to the LLM. When setting the number of rag
     * messages to a fixed number only the last N number of rag messages will be sent to the LLM.
     * Setting __rag to a fixed number can help to reduce prompt size.
     */
    readonly __rag: "__rag";
    /**
     * An object that will be passed to the rag callback of a conversation. If the value is not an
     * object it is ignored.
     */
    readonly __ragParams: "__ragParams";
    /**
     * The tolerance that determines if matched rag content should be included as contact.
     */
    readonly __ragTol: "__ragTol";
    /**
     * Sets the current thread filter. Can either be a string or a ConvoThreadFilter. If __threadFilter
     * is a string it will be converted into a filter that looks like `{includeThreads:[__threadId]}`.
     */
    readonly __threadFilter: "__threadFilter";
};
export declare const defaultConvoRagTol = 1.2;
export declare const convoTags: {
    /**
     * When applied to a function the return value of the function will not be used to generate a
     * new assistant message.
     */
    readonly disableAutoComplete: "disableAutoComplete";
    /**
     * Used to indicate that a message should be evaluated at the edge of a conversation with the
     * latest state. @edge is most commonly used with system message to ensure that all injected values
     * are updated with the latest state of the conversation.
     */
    readonly edge: "edge";
    /**
     * Used to track the time messages are created.
     */
    readonly time: "time";
    /**
     * Used to track the number of tokens a message used
     */
    readonly tokenUsage: "tokenUsage";
    /**
     * Used to track the model used to generate completions
     */
    readonly model: "model";
    /**
     * Sets the requested model to complete a message with
     */
    readonly responseModel: "responseModel";
    /**
     * Used to track the endpoint to generate completions
     */
    readonly endpoint: "endpoint";
    /**
     * Sets the requested endpoint to complete a message with
     */
    readonly responseEndpoint: "responseEndpoint";
    /**
     * Sets the format as message should be responded to with.
     */
    readonly responseFormat: "responseFormat";
    /**
     * Causes the response of the tagged message to be assigned to a variable
     */
    readonly responseAssign: "responseAssign";
    /**
     * When used with a message the json tag is short and for `@responseFormat json`
     */
    readonly json: "json";
    /**
     * The format of a message
     */
    readonly format: "format";
    /**
     * Used to assign the content or jsonValue of a message to a variable
     */
    readonly assign: "assign";
    /**
     * Used to enable capabilities. Only the first and last message in the conversation are used
     * to determine current capabilities. Multiple capability tags can be
     * applied to a message and multiple capabilities can be specified by separating them with a
     * comma.
     */
    readonly capability: "capability";
    /**
     * Shorthand for `@capability vision`
     */
    readonly enableVision: "enableVision";
    /**
     * Sets the task a message is part of. By default messages are part of the "default" task
     */
    readonly task: "task";
    /**
     * Sets the max number of non-system messages that should be included in a task completion
     */
    readonly maxTaskMessageCount: "maxTaskMessageCount";
    /**
     * Defines what triggers a task
     */
    readonly taskTrigger: "taskTrigger";
    /**
     * Defines a message as a template
     */
    readonly template: "template";
    /**
     * used to track the name of templates used to generate messages
     */
    readonly sourceTemplate: "sourceTemplate";
    /**
     * Used to mark a message as a component. The value of the tag is used as the component name.
     * If no value is provided then the component will be unnamed.
     */
    readonly component: "component";
    /**
     * When applied to a message the message should be rendered but not sent to LLMs
     */
    readonly renderOnly: "renderOnly";
    /**
     * Controls where a message is rendered. By default messages are rendered in the default chat
     * view, but applications can define different render targets.
     */
    readonly renderTarget: "renderTarget";
    readonly toolId: "toolId";
    /**
     * When applied to the last content or component messages auto scrolling will be disabled
     */
    readonly disableAutoScroll: "disableAutoScroll";
    /**
     * When applied to a message the content of the message will be parsed as markdown
     */
    readonly markdown: "markdown";
    /**
     * When applied to a message the content of the message will be parsed as markdown and the
     * elements of the markdown will be auto assigned to vars
     */
    readonly markdownVars: "markdownVars";
    /**
     * When applied to a message the message is conditionally added to the flattened view of a
     * conversation. When the condition is false the message will not be visible to the user
     * or the LLM.
     *
     * @note The example below uses (at) instead of the at symbol because of a limitation of jsdoc.
     *
     * The example below will only render and send the second system message to the LLM
     * @example
     *
     * ``` convo
     * > define
     * animal = 'dog'
     *
     * (at)condition animal frog
     * > system
     * You are a frog and you like to hop around.
     *
     * (at)condition animal dog
     * > system
     * You are a dog and you like to eat dirt.
     * ```
     */
    readonly condition: "condition";
    /**
     * A URL to the source of the message. Typically used with RAG.
     */
    readonly sourceUrl: "sourceUrl";
    /**
     * The ID of the source content of the message. Typically used with RAG.
     */
    readonly sourceId: "sourceId";
    /**
     * The name of the source content of the message. Typically used with RAG.
     */
    readonly sourceName: "sourceName";
    /**
     * When applied to a message the message becomes a clickable suggestion that when clicked will
     * add a new user message with the content of the message. If the suggestion tag defines a value
     * that value will be displayed on the clickable button instead of the message content but the
     * message content will still be used as the user messaged added to the conversation when clicked.
     * Suggestion message are render only and not seen by LLMs.
     */
    readonly suggestion: "suggestion";
    /**
     * Sets the threadId of the current message and all following messages. Using the `@thread` tag
     * without a value will clear the current thread id.
     */
    readonly thread: "thread";
    /**
     * Used to mark a function as a node output.
     */
    readonly output: "output";
    /**
     * Used to mark a function as an error callback
     */
    readonly errorCallback: "errorCallback";
    /**
     * Used to import external convo script code
     */
    readonly import: "import";
    /**
     * Causes a message to be concatenated with the previous message. Both the message the tag
     * is attached to and the previous message must be content messages or the tag is ignored.
     * When a message is concatenated to another message all other tags except the condition
     * tag are ignored.
     */
    readonly concat: "concat";
};
export declare const convoTaskTriggers: {
    /**
     * Triggers a text message is received. Function calls will to trigger.
     */
    readonly onResponse: "onResponse";
};
export declare const convoDateFormat = "yyyy-MM-dd'T'HH:mm:ssxxx";
export declare const defaultConvoRenderTarget = "default";
export declare const getConvoDateString: (date?: Date | number) => string;
export declare const defaultConvoVisionSystemMessage: string;
export declare const defaultConvoVisionResponse = "Unable to answer or respond to questions or requests for the given image or images";
export declare const allowedConvoDefinitionFunctions: readonly ["new", "struct", "map", "array", "enum", "jsonMap", "jsonArray", "getState"];
export declare const createOptionalConvoValue: (value: any) => OptionalConvoValue;
export declare const createConvoType: (typeDef: Omit<ConvoType, typeof convoObjFlag>) => ConvoType;
export declare const createConvoBaseTypeDef: (type: ConvoBaseType) => ConvoType;
export declare const makeAnyConvoType: <T>(type: ConvoBaseType, value: T) => T;
interface CreateConvoScopeFunctionOverloads {
    (): ConvoScopeFunction;
    (fn: ConvoScopeFunction): ConvoScopeFunction;
    (flowCtrl: ConvoFlowController, fn?: ConvoScopeFunction): ConvoScopeFunction;
}
export declare const createConvoScopeFunction: CreateConvoScopeFunctionOverloads;
export declare const setConvoScopeError: (scope: ConvoScope | null | undefined, error: ConvoScopeError | string) => void;
export declare const convoTagMapToCode: (tagsMap: Record<string, string | undefined>, append?: string, tab?: string) => string;
export declare const containsConvoTag: (tags: ConvoTag[] | null | undefined, tagName: string) => boolean;
export declare const getConvoTag: (tags: ConvoTag[] | null | undefined, tagName: string) => ConvoTag | undefined;
export declare const convoTagsToMap: (tags: ConvoTag[]) => Record<string, string | undefined>;
export declare const mapToConvoTags: (map: Record<string, string | undefined>) => ConvoTag[];
export declare const createConvoMetadataForStatement: (statement: ConvoStatement) => ConvoMetadata;
export declare const getConvoMetadata: (value: any) => ConvoMetadata | undefined;
export declare const convoLabeledScopeParamsToObj: (scope: ConvoScope) => Record<string, any>;
export declare const isReservedConvoRole: (role: string) => boolean;
export declare const isValidConvoRole: (role: string) => boolean;
export declare const isValidConvoIdentifier: (role: string) => boolean;
export declare const formatConvoMessage: (role: string, content: string, prefix?: string) => string;
export interface EscapeConvoMessageContentOptions {
    removeNewLines?: boolean;
}
export declare const escapeConvoMessageContent: (content: string, isStartOfMessage?: boolean, options?: EscapeConvoMessageContentOptions) => string;
export declare const spreadConvoArgs: (args: Record<string, any>, format?: boolean) => string;
export declare const defaultConvoPrintFunction: ConvoPrintFunction;
export declare const collapseConvoPipes: (statement: ConvoStatement) => number;
export declare const convoDescriptionToCommentOut: (description: string, tab: string | undefined, out: string[]) => void;
export declare const convoDescriptionToComment: (description: string, tab?: string) => string;
export declare const convoStringToCommentOut: (str: string, tab: string | undefined, out: string[]) => void;
export declare const convoStringToComment: (str: string, tab?: string) => string;
export declare const isValidConvoVarName: (name: string) => boolean;
export declare const isValidConvoFunctionName: (name: string) => boolean;
export declare const isValidConvoTypeName: (typeName: string) => boolean;
export declare const validateConvoVarName: (name: string) => void;
export declare const validateConvoFunctionName: (name: string) => void;
export declare const validateConvoTypeName: (name: string) => void;
export declare const convoUsageTokensToString: (usage: Partial<ConvoTokenUsage>) => string;
export declare const parseConvoUsageTokens: (str: string) => ConvoTokenUsage;
export declare const addConvoUsageTokens: (to: ConvoTokenUsage, from: ConvoTokenUsage | string) => void;
export declare const createEmptyConvoTokenUsage: () => ConvoTokenUsage;
export declare const resetConvoUsageTokens: (usage: ConvoTokenUsage) => void;
export declare const parseConvoJsonMessage: (json: string) => any;
export declare const removeDanglingConvoUserMessage: (code: string) => string;
export declare const concatConvoCode: (a: string, b: string) => string;
export declare const concatConvoCodeAndAppendEmptyUserMessage: (a: string, b: string) => string;
export declare const isConvoMessageIncludedInTask: (msg: ConvoMessage, task: string) => boolean;
export declare const parseConvoMessageTemplate: (msg: ConvoMessage, template: string) => ConvoMessageTemplate;
export declare const getConvoStatementSource: (statement: ConvoStatement, code: string) => string;
/**
 * If the value is empty, null or undefined true is returned, otherwise the Boolean
 * constructor is used to parse the value.
 */
export declare const parseConvoBooleanTag: (value: string | null | undefined) => boolean;
export declare const getFlatConvoTag: (message: FlatConvoMessage | null | undefined, tagName: string) => boolean;
export declare const shouldDisableConvoAutoScroll: (messages: FlatConvoMessage[]) => boolean;
export declare const convoRagDocRefToMessage: (doc: ConvoDocumentReference, role: string) => ConvoMessage;
export declare const escapeConvoTagValue: (value: string) => string;
export declare const convoMessageToString: (msg: ConvoMessage) => string;
export declare const getLastCompletionMessage: (messages: FlatConvoMessage[]) => FlatConvoMessage | undefined;
export declare const isConvoThreadFilterMatch: (filter: ConvoThreadFilter, tid: string | undefined | null) => boolean;
export {};