tiny-ai-api
Version:
A customizable and extensible client api for managing conversations and AI interactions, currently supporting the **Google Gemini** API — with flexibility to support any similar AI APIs.
938 lines (937 loc) • 45.6 kB
text/typescript
export default TinyAiInstance;
export type SessionDataContent = {
data: {
parts: Array<Record<"text" | "inlineData", string | {
mime_type: string;
data: string;
} | null>>;
role?: string | undefined;
finishReason?: string | number | undefined;
}[];
ids: string[];
tokens: {
data: Array<{
count: number | null;
hide?: boolean;
}>;
[key: string]: any;
};
hash: {
data: Array<string>;
[key: string]: any;
};
systemInstruction: string | null;
customList?: {
name: string;
type: string;
}[] | undefined;
model: string | null;
};
export type SessionData = Record<string, any> & SessionDataContent;
export type AiModel = {
_response: any;
index: number;
name: string | null;
id: string | null;
displayName: string | null;
version: string | null;
description: string | null;
inputTokenLimit: number | null;
outputTokenLimit: number | null;
temperature: number | null;
maxTemperature: number | null;
topP: number | null;
topK: number | null;
supportedGenerationMethods?: string[] | undefined;
};
export type AiCategory = {
category: string;
displayName: string;
index: number;
data: AiModel[];
};
/**
* @typedef {Object} SessionDataContent
* @property {AIContentData[]} data
* @property {string[]} ids
* @property {{ data: Array<TokenCount>; [key: string]: * }} tokens
* @property {{ data: Array<string>; [key: string]: * }} hash
* @property {string|null} systemInstruction
* @property {{ name: string; type: string; }[]} [customList]
* @property {string|null} model
*
*/
/**
* @typedef {Record<string, any> & SessionDataContent} SessionData
*/
/**
* @typedef {Object} AiModel
* @property {any} _response
* @property {number} index
* @property {string|null} name
* @property {string|null} id
* @property {string|null} displayName
* @property {string|null} version
* @property {string|null} description
* @property {number|null} inputTokenLimit
* @property {number|null} outputTokenLimit
* @property {number|null} temperature
* @property {number|null} maxTemperature
* @property {number|null} topP
* @property {number|null} topK
* @property {string[]} [supportedGenerationMethods]
*/
/**
* @typedef {Object} AiCategory
* @property {string} category
* @property {string} displayName
* @property {number} index
* @property {AiModel[]} data
*/
/**
* Tiny AI Server Communication API
* -----------------------------
* This class is responsible for managing AI session data, including models, history, and content generation.
* The script is designed to interact with the AI API, providing a complete structure for creating user interfaces (UI) or AI-powered chatbots.
* It implements a session management system to help handle multiple different bots.
* However, this script is not optimized for efficiently handling multiple AI instances simultaneously, which may be required for high-load scenarios or when running several AI instances at once.
*
* **Note**: This script does not automatically manage or track the token count for messages. Developers need to implement their own logic to monitor and manage token usage if necessary.
*
* Documentation written with the assistance of OpenAI's ChatGPT.
*/
declare class TinyAiInstance {
/**
* Creates an instance of the TinyAiInstance class.
* Initializes internal variables, sets up initial configurations for handling AI models,
* session history, and content generation, with the option to use a single or multiple instances.
*
* @param {boolean} [isSingle] - If true, configures the instance to handle a single session only.
*/
constructor(isSingle?: boolean);
/**
* Provides access to a secure internal EventEmitter for subclass use only.
*
* This method exposes a dedicated EventEmitter instance intended specifically for subclasses
* that extend the main class. It prevents subclasses from accidentally or intentionally using
* the primary class's public event system (`emit`), which could lead to unpredictable behavior
* or interference in the base class's event flow.
*
* For security and consistency, this method is designed to be accessed only once.
* Multiple accesses are blocked to avoid leaks or misuse of the internal event bus.
*
* @returns {EventEmitter} A special internal EventEmitter instance for subclass use.
* @throws {Error} If the method is called more than once.
*/
getSysEvents(): EventEmitter;
/**
* @typedef {(...args: any[]) => void} ListenerCallback
* A generic callback function used for event listeners.
*/
/**
* Sets the maximum number of listeners for the internal event emitter.
*
* @param {number} max - The maximum number of listeners allowed.
*/
setMaxListeners(max: number): void;
/**
* Emits an event with optional arguments.
* @param {string | symbol} event - The name of the event to emit.
* @param {...any} args - Arguments passed to event listeners.
* @returns {boolean} `true` if the event had listeners, `false` otherwise.
*/
emit(event: string | symbol, ...args: any[]): boolean;
/**
* Registers a listener for the specified event.
* @param {string | symbol} event - The name of the event to listen for.
* @param {ListenerCallback} listener - The callback function to invoke.
* @returns {this} The current class instance (for chaining).
*/
on(event: string | symbol, listener: (...args: any[]) => void): this;
/**
* Registers a one-time listener for the specified event.
* @param {string | symbol} event - The name of the event to listen for once.
* @param {ListenerCallback} listener - The callback function to invoke.
* @returns {this} The current class instance (for chaining).
*/
once(event: string | symbol, listener: (...args: any[]) => void): this;
/**
* Removes a listener from the specified event.
* @param {string | symbol} event - The name of the event.
* @param {ListenerCallback} listener - The listener to remove.
* @returns {this} The current class instance (for chaining).
*/
off(event: string | symbol, listener: (...args: any[]) => void): this;
/**
* Alias for `on`.
* @param {string | symbol} event - The name of the event.
* @param {ListenerCallback} listener - The callback to register.
* @returns {this} The current class instance (for chaining).
*/
addListener(event: string | symbol, listener: (...args: any[]) => void): this;
/**
* Alias for `off`.
* @param {string | symbol} event - The name of the event.
* @param {ListenerCallback} listener - The listener to remove.
* @returns {this} The current class instance (for chaining).
*/
removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
/**
* Removes all listeners for a specific event, or all events if no event is specified.
* @param {string | symbol} [event] - The name of the event. If omitted, all listeners from all events will be removed.
* @returns {this} The current class instance (for chaining).
*/
removeAllListeners(event?: string | symbol): this;
/**
* Returns the number of times the given `listener` is registered for the specified `event`.
* If no `listener` is passed, returns how many listeners are registered for the `event`.
* @param {string | symbol} eventName - The name of the event.
* @param {Function} [listener] - Optional listener function to count.
* @returns {number} Number of matching listeners.
*/
listenerCount(eventName: string | symbol, listener?: Function): number;
/**
* Adds a listener function to the **beginning** of the listeners array for the specified event.
* The listener is called every time the event is emitted.
* @param {string | symbol} eventName - The event name.
* @param {ListenerCallback} listener - The callback function.
* @returns {this} The current class instance (for chaining).
*/
prependListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
/**
* Adds a **one-time** listener function to the **beginning** of the listeners array.
* The next time the event is triggered, this listener is removed and then invoked.
* @param {string | symbol} eventName - The event name.
* @param {ListenerCallback} listener - The callback function.
* @returns {this} The current class instance (for chaining).
*/
prependOnceListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
/**
* Returns an array of event names for which listeners are currently registered.
* @returns {(string | symbol)[]} Array of event names.
*/
eventNames(): (string | symbol)[];
/**
* Gets the current maximum number of listeners allowed for any single event.
* @returns {number} The max listener count.
*/
getMaxListeners(): number;
/**
* Returns a copy of the listeners array for the specified event.
* @param {string | symbol} eventName - The event name.
* @returns {Function[]} An array of listener functions.
*/
listeners(eventName: string | symbol): Function[];
/**
* Returns a copy of the internal listeners array for the specified event,
* including wrapper functions like those used by `.once()`.
* @param {string | symbol} eventName - The event name.
* @returns {Function[]} An array of raw listener functions.
*/
rawListeners(eventName: string | symbol): Function[];
/** @type {Record<string|number, string|{ text: string, hide?: boolean }>} */ _errorCode: Record<string | number, string | {
text: string;
hide?: boolean;
}>;
/** @type {string|null} */ _nextModelsPageToken: string | null;
/** @type {(AiModel|AiCategory)[]} */ models: (AiModel | AiCategory)[];
/** @type {Object.<string, SessionData>} */ history: {
[x: string]: SessionData;
};
_isSingle: boolean;
/**
* Starts a new data session with the given session ID.
*
* @param {string} id - The session ID for the new data session.
* @param {boolean} [selected=false] - A flag to indicate whether this session should be selected as the active session.
* @returns {SessionData} The newly created session data, which includes an empty data array, an empty IDs array, and null values for system instruction and model.
*/
startDataId(id: string, selected?: boolean): SessionData;
/**
* Stop the data session associated with the provided ID.
* This will remove the session data from history and reset the selected session ID if necessary.
*
* @param {string} id - The session history ID to stop and remove from history.
* @returns {boolean} `true` if the session ID was found and successfully stopped, `false` otherwise.
*/
stopDataId(id: string): boolean;
/**
* Select a session history ID to set as the active session.
* If `null` is passed, it deselects the current session ID.
*
* @param {string|null} id - The session history ID to select, or `null` to deselect the current session.
* @returns {boolean} `true` if the session ID was successfully selected or deselected, `false` if the ID does not exist in history.
*/
selectDataId(id: string | null): boolean;
/**
* Sets a custom value in the selected session history.
*
* @param {string} name - The name of the custom value to set.
* @param {*} value - The value to be assigned to the custom key.
* @param {number} [tokenAmount] - The token amount associated with the custom value (optional).
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @throws {Error} If the custom value name is invalid (not a non-empty string) or conflicts with existing data.
* @returns {void} This method does not return a value.
*/
setCustomValue(name: string, value: any, tokenAmount?: number, id?: string): void;
/**
* Resets a custom value in the selected session history.
*
* @param {string} name - The name of the custom value to reset.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @throws {Error} If the custom value name is invalid or does not match an existing entry.
* @returns {void} This method does not return a value.
*/
resetCustomValue(name: string, id?: string): void;
/**
* Completely removes a custom value from the selected session history.
*
* @param {string} name - The name of the custom value to erase.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @throws {Error} If the custom value name is invalid or does not exist.
* @returns {void} This method does not return a value.
*/
eraseCustomValue(name: string, id?: string): void;
/**
* Retrieves a custom value from the selected session history.
*
* @param {string} name - The name of the custom value to retrieve.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {*} The value associated with the specified name, or `null` if it does not exist.
*/
getCustomValue(name: string, id?: string): any;
/**
* Retrieves the list of custom values from the selected session history.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {Array<*>} An array of custom values if available, or an empty array if no custom values exist.
*/
getCustomValueList(id?: string): Array<any>;
/**
* Set the maximum output tokens setting for an AI session.
*
* @param {number} value - The maximum number of output tokens to be set.
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {void} This function does not return a value.
*/
setMaxOutputTokens(value: number, id?: string): void;
/**
* Get the maximum output tokens setting for an AI session.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {number | null} The maximum output tokens value, or null if not set.
*/
getMaxOutputTokens(id?: string): number | null;
/**
* Set the AI temperature setting for a session.
*
* @param {number} value - The temperature value to be set.
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {void} This function does not return a value.
*/
setTemperature(value: number, id?: string): void;
/**
* Get the AI temperature setting for a session.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {number | null} The temperature value, or null if not set.
*/
getTemperature(id?: string): number | null;
/**
* Set the top-p (nucleus sampling) value in an AI session.
*
* @param {number} value - The top-p value to be set.
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {void} This function does not return a value.
*/
setTopP(value: number, id?: string): void;
/**
* Get the top-p (nucleus sampling) setting for an AI session.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {number | null} The top-p value, or null if not set.
*/
getTopP(id?: string): number | null;
/**
* Set the top-k setting for an AI session.
*
* @param {number} value - The top-k value to be set.
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {void} This function does not return a value.
*/
setTopK(value: number, id?: string): void;
/**
* Get the top-k setting for an AI session.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {number | null} The top-k value, or null if not set.
*/
getTopK(id?: string): number | null;
/**
* Set the presence penalty setting for an AI session.
*
* @param {number} value - The presence penalty value to be set.
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {void} This function does not return a value.
*/
setPresencePenalty(value: number, id?: string): void;
/**
* Get the presence penalty setting for an AI session.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {number | null} The presence penalty value, or null if not set.
*/
getPresencePenalty(id?: string): number | null;
/**
* Set the frequency penalty setting for an AI session.
*
* @param {number} value - The frequency penalty value to be set.
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {void} This function does not return a value.
*/
setFrequencyPenalty(value: number, id?: string): void;
/**
* Get the frequency penalty setting for an AI session.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {number | null} The frequency penalty value, or null if not set.
*/
getFrequencyPenalty(id?: string): number | null;
/**
* Set the setting for enabling enhanced civic answers in an AI session.
*
* @param {boolean} value - Whether to enable enhanced civic answers (true or false).
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {void} This function does not return a value.
*/
setEnabledEnchancedCivicAnswers(value: boolean, id?: string): void;
/**
* Get the setting for whether enhanced civic answers are enabled in an AI session.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {boolean | null} The value indicating whether enhanced civic answers are enabled, or null if not set.
*/
isEnabledEnchancedCivicAnswers(id?: string): boolean | null;
/**
* Set the model for an AI session.
*
* @param {string} data - The model to be set (must be a string).
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {void} This function does not return a value.
*/
setModel(data: string, id?: string): void;
/**
* Get the model for an AI session.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session will be used.
* @returns {string | null} The model, or null if not set.
*/
getModel(id?: string): string | null;
/**
* Build content data for an AI session.
*
* @param {Array<*>} [contents] - An optional array to which the built content data will be pushed.
* @param {Record<string, any>} item - The item containing content parts or a content object.
* @param {string|null} [role] - The role to be associated with the content (optional).
* @param {boolean} [rmFinishReason=false] - If true, removes the `finishReason` property from the content.
* @returns {AIContentData|number} The constructed content data object, or array length if pushed to an array.
*/
buildContents(contents?: Array<any>, item?: Record<string, any>, role?: string | null, rmFinishReason?: boolean): {
parts: Array<Record<"text" | "inlineData", string | {
mime_type: string;
data: string;
} | null>>;
role?: string | undefined;
finishReason?: string | number | undefined;
} | number;
/**
* Set the API key for the AI session.
*
* @param {string} apiKey - The API key to be set.
* @returns {void} This function does not return a value.
*/
setApiKey(apiKey: string): void;
/**
* Set the token for the next page of models in the AI session.
*
* @param {string} nextModelsPageToken - The token for the next models page.
* @returns {void} This function does not return a value.
*/
_setNextModelsPageToken(nextModelsPageToken: string): void;
/**
* Set the function to retrieve models for the AI session.
*
* @param {Function} getModels - The function to retrieve models.
* @returns {void} This function does not return a value.
*/
_setGetModels(getModels: Function): void;
/**
* Get a list of models for the AI session.
*
* @param {number} [pageSize=50] - The number of models to retrieve per page. Defaults to 50.
* @param {string|null} [pageToken=null] - The token for the next page of models, if available. Defaults to null.
* @returns {Array<*>} The list of models retrieved.
* @throws {Error} If no model list API function is defined.
*/
getModels(pageSize?: number, pageToken?: string | null): Array<any>;
/**
* Get the list of models for the AI session.
*
* @returns {(AiModel|AiCategory)[]} The list of models.
*/
getModelsList(): (AiModel | AiCategory)[];
/**
* Get model data from the list of models.
*
* @param {string} id - The model data id to search for in the models list.
* @returns {AiModel|null} The model data if found, otherwise null.
*/
getModelData(id: string): AiModel | null;
/**
* Check if a model exists in the model list.
*
* @param {string} id - The model id to check for in the models list.
* @returns {boolean} True if the model exists, false otherwise.
*/
existsModel(id: string): boolean;
/**
* Insert a new model into the AI session's models list.
* If the model already exists, it will not be inserted again.
*
* @param {Object} model - The model to insert.
* @param {*} model._response - The raw response.
* @param {number} model.index - The index position.
* @param {string} model.id - The unique identifier for the model.
* @param {string} [model.name] - The name of the model.
* @param {string} [model.displayName] - The display name of the model.
* @param {string} [model.version] - The version of the model.
* @param {string} [model.description] - A description of the model.
* @param {number} [model.inputTokenLimit] - The input token limit for the model.
* @param {number} [model.outputTokenLimit] - The output token limit for the model.
* @param {number} [model.temperature] - The temperature setting for the model.
* @param {number} [model.maxTemperature] - The maximum temperature setting for the model.
* @param {number} [model.topP] - The top P setting for the model.
* @param {number} [model.topK] - The top K setting for the model.
* @param {Array<string>} [model.supportedGenerationMethods] - The generation methods supported by the model.
* @param {Object} [model.category] - The category of the model.
* @param {string} model.category.id - The unique identifier for the category.
* @param {string} model.category.displayName - The display name of the category.
* @param {number} model.category.index - The index of the category.
* @returns {Record<string, any>|null} The inserted model data, or null if the model already exists.
*/
_insertNewModel(model: {
_response: any;
index: number;
id: string;
name?: string | undefined;
displayName?: string | undefined;
version?: string | undefined;
description?: string | undefined;
inputTokenLimit?: number | undefined;
outputTokenLimit?: number | undefined;
temperature?: number | undefined;
maxTemperature?: number | undefined;
topP?: number | undefined;
topK?: number | undefined;
supportedGenerationMethods?: string[] | undefined;
category?: {
id: string;
displayName: string;
index: number;
} | undefined;
}): Record<string, any> | null;
/**
* Sets a function to handle the count of tokens in the AI session.
* If a valid function is provided, it will be used to count tokens.
*
* @param {Function} countTokens - The function that will handle the token count.
* @throws {Error} Throws an error if the provided value is not a function.
* @returns {void}
*/
_setCountTokens(countTokens: Function): void;
/**
* Counts the tokens based on the provided data and model, using a defined token counting function.
* If the function to count tokens is not set, an error is thrown.
*
* @param {Record<string, any>} data - The data that needs to be tokenized.
* @param {string} [model] - The model to use for counting tokens. If not provided, the default model is used.
* @param {AbortController} [controller] - The controller that manages the process or settings for counting tokens.
* @throws {Error} Throws an error if no token counting function is defined.
* @returns {Record<string, any>} The count of tokens.
*/
countTokens(data: Record<string, any>, model?: string, controller?: AbortController): Record<string, any>;
/**
* @typedef {{ text: string, hide?: boolean }} ErrorCode
*/
/**
* Sets the error codes for the current session.
*
* @param {Record<string|number, string|ErrorCode>} errors - The error codes to set, typically an object containing error code definitions.
* @returns {void}
*/
_setErrorCodes(errors: Record<string | number, string | {
text: string;
hide?: boolean;
}>): void;
/**
* Get error details based on the provided error code.
*
* @param {string|number} code - The error code to look up.
* @returns {ErrorCode|null} An object containing the error message, or null if no error is found.
*/
getErrorCode(code: string | number): {
text: string;
hide?: boolean;
} | null;
/**
* Sets the content generation callback function for the AI session.
*
* @param {Function} callback - The callback function that handles content generation.
* @returns {void}
*/
_setGenContent(callback: Function): void;
/**
* Generates content for the AI session.
*
* @param {Record<string, any>} data - The data for content generation.
* @param {string} [model] - The model to be used for content generation. If not provided, the default model is used.
* @param {AbortController} [controller] - The controller managing the content generation process.
* @param {Function} [streamCallback] - The callback function for streaming content (optional).
* @returns {Record<string, any>} The generated content returned by the API.
* @throws {Error} If no content generator API script is defined.
*/
genContent(data: Record<string, any>, model?: string, controller?: AbortController, streamCallback?: Function): Record<string, any>;
/**
* Get the currently selected session history ID.
* If no ID is provided, it returns the default selected session history ID.
*
* @param {string} [id] - The session history ID to retrieve. If not provided, it uses the default selected ID.
* @returns {string|null} The selected session history ID, or `null` if no history ID is selected.
*/
getId(id?: string): string | null;
/**
* Get the data associated with a specific session history ID.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {SessionData|null} The data associated with the session ID, or `null` if no data exists for that ID.
*/
getData(id?: string): SessionData | null;
/**
* Calculates the total number of tokens used for messages in the session history.
*
* This method iterates over the `tokens` array in the session history and sums the `count` of tokens
* from each message, returning the total sum. If no valid session history is found or if token data is
* missing, it will return `null`.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {number|null} The total number of tokens used in the session history, or `null` if no data is available.
*/
getTotalTokens(id?: string): number | null;
/**
* Retrieves the token data for a specific message in the session history by its index.
*
* **Note**: This method does not manage the token count automatically. It assumes that token data has been added
* to the history using the `addData` method.
*
* @param {number} msgIndex - The index of the message in the session history.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {TokenCount|null} The token data associated with the message at the specified index, or `null` if the data is not found.
*/
getMsgTokensByIndex(msgIndex: number, id?: string): {
count: number | null;
hide?: boolean;
} | null;
/**
* Retrieves the token data for a specific message in the session history by its message ID.
*
* **Note**: This method does not manage the token count automatically. It assumes that token data has been added
* to the history using the `addData` method.
*
* @param {string} msgId - The unique ID of the message in the session history.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {TokenCount|null} The token data associated with the message with the given ID, or `null` if the message is not found.
*/
getMsgTokensById(msgId: string, id?: string): {
count: number | null;
hide?: boolean;
} | null;
/**
* Retrieves the hash of a message at a specified index in the selected session history.
*
* @param {number} msgIndex - The index of the message whose hash is being retrieved.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {string|null} The hash value of the message at the specified index, or null if the index is invalid or does not exist.
*/
getMsgHashByIndex(msgIndex: number, id?: string): string | null;
/**
* Retrieves the hash of a message based on its ID from the selected session history.
*
* @param {string} msgId - The ID of the message whose hash is being retrieved.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {string|null} The hash value of the message with the specified ID, or null if the message ID is invalid or does not exist.
*/
getMsgHashById(msgId: string, id?: string): string | null;
/**
* Checks if a specific index exists in the session history.
*
* **Note**: This method assumes that the history data is available and that the `getMsgByIndex` method is used
* to retrieve the index. If the `getMsgByIndex` method returns a valid index, this method will return `true`.
*
* @param {number} index - The index to check for existence in the session history.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {boolean} `true` if the index exists, otherwise `false`.
*/
indexExists(index: number, id?: string): boolean;
/**
* Retrieve a specific data entry by its index from the session history.
*
* @param {number} index - The index of the data entry to retrieve.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {AIContentData|null} The data entry at the specified index, or `null` if the index is out of bounds or no data exists for the given session ID.
*/
getMsgByIndex(index: number, id?: string): {
parts: Array<Record<"text" | "inlineData", string | {
mime_type: string;
data: string;
} | null>>;
role?: string | undefined;
finishReason?: string | number | undefined;
} | null;
/**
* Retrieves a specific message by its ID from the session history.
*
* @param {string} msgId - The ID of the message to retrieve.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {AIContentData|null} The message data associated with the given ID, or `null` if the message ID is invalid or does not exist.
*/
getMsgById(msgId: string, id?: string): {
parts: Array<Record<"text" | "inlineData", string | {
mime_type: string;
data: string;
} | null>>;
role?: string | undefined;
finishReason?: string | number | undefined;
} | null;
/**
* Retrieve the index of a specific message ID in the session history.
*
* @param {string} msgId - The message ID to search for.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {number} The index of the message ID in the session history, or `-1` if not found.
*/
getIndexOfId(msgId: string, id?: string): number;
/**
* Retrieve the message ID at a specific index in the session history.
*
* @param {number} index - The index of the data to retrieve.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {string|number} The message ID at the specified index, or `-1` if the index is out of bounds or not found.
*/
getIdByIndex(index: number, id?: string): string | number;
/**
* Delete a specific entry from the session history at the given index.
*
* @param {number} index - The index of the entry to delete.
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {boolean} `true` if the entry was successfully deleted, `false` if the index is invalid or the entry does not exist.
*/
deleteIndex(index: number, id?: string): boolean;
/**
* Replaces an entry at the specified index in the session history with new data.
*
* @param {number} index - The index of the entry to replace.
* @param {AIContentData} [data] - The new data to replace the existing entry (optional).
* @param {TokenCount} [tokens] - The token count associated with the new entry (optional).
* @param {string} [id] - The session ID (optional). If omitted, the currently selected session history ID will be used.
* @returns {boolean} `true` if the entry was successfully replaced, `false` if the index is invalid or the entry does not exist.
*/
replaceIndex(index: number, data?: {
parts: Array<Record<"text" | "inlineData", string | {
mime_type: string;
data: string;
} | null>>;
role?: string | undefined;
finishReason?: string | number | undefined;
}, tokens?: {
count: number | null;
hide?: boolean;
}, id?: string): boolean;
/**
* Retrieve the index of the last entry in the session history.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {number} The index of the last entry in the session history, or `-1` if the history is empty or invalid.
*/
getLastIndex(id?: string): number;
/**
* Retrieve the data of the last entry in the session history.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {AIContentData|null} The data of the last entry in the session history, or `null` if the history is empty or invalid.
*/
getLastIndexData(id?: string): {
parts: Array<Record<"text" | "inlineData", string | {
mime_type: string;
data: string;
} | null>>;
role?: string | undefined;
finishReason?: string | number | undefined;
} | null;
/**
* Check if the session history has at least one entry.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {boolean} `true` if the session history has at least one entry, `false` otherwise.
*/
existsFirstIndex(id?: string): boolean;
/**
* Retrieve the first entry in the session history.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {AIContentData|null} The first entry of the session history, or `null` if no entry exists.
*/
getFirstIndexData(id?: string): {
parts: Array<Record<"text" | "inlineData", string | {
mime_type: string;
data: string;
} | null>>;
role?: string | undefined;
finishReason?: string | number | undefined;
} | null;
/**
* Adds new data to the selected session history.
* If no session ID is provided, the currently selected session history ID will be used.
*
* **Note**: The `tokenData` parameter is optional and can be used to track token-related data associated with the new entry.
* This may include token counts, but this script does not manage token counting automatically. Developers must implement token management separately if necessary.
*
* @param {AIContentData} data - The data to be added to the session history.
* @param {TokenCount} [tokenData={count: null}] - Optional token-related data to be associated with the new entry. Defaults to `{count: null}`.
* @param {string} [id] - The session history ID. If omitted, the currently selected session ID will be used.
* @returns {number} The new ID of the added data entry.
* @throws {Error} If the provided session ID is invalid or the session ID does not exist in history.
*/
addData(data: {
parts: Array<Record<"text" | "inlineData", string | {
mime_type: string;
data: string;
} | null>>;
role?: string | undefined;
finishReason?: string | number | undefined;
}, tokenData?: {
count: number | null;
hide?: boolean;
}, id?: string): number;
/**
* Sets a prompt for the selected session history.
*
* @param {string} [promptData] - The prompt to be set for the session.
* @param {number} [tokenAmount] - The number of tokens associated with the prompt (optional).
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @throws {Error} If the provided session ID is invalid or the prompt data is not a string.
*/
setPrompt(promptData?: string, tokenAmount?: number, id?: string): void;
/**
* Retrieves the prompt of the selected session history.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {string|null} The prompt for the session if available, otherwise null.
*/
getPrompt(id?: string): string | null;
/**
* Sets the first dialogue for the selected session history.
*
* @param {string} [dialogue] - The dialogue to set as the first dialogue.
* @param {number} [tokenAmount] - The number of tokens associated with the dialogue (optional).
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @throws {Error} Throws an error if the session ID is invalid or the dialogue is not a string.
* @returns {void}
*/
setFirstDialogue(dialogue?: string, tokenAmount?: number, id?: string): void;
/**
* Retrieves the first dialogue from the selected session history.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {string|null} The first dialogue if it exists and is a non-empty string, or null if no first dialogue is set.
*/
getFirstDialogue(id?: string): string | null;
/**
* Sets file data for the selected session history.
*
* @param {string} [mime] - The MIME type of the file (e.g., 'text/plain', 'application/pdf').
* @param {string} [data] - The file content, either as a string or base64-encoded.
* @param {boolean} [isBase64=false] - A flag indicating whether the `data` is already base64-encoded. Defaults to false.
* @param {number} [tokenAmount] - The token count associated with the file data (optional).
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @throws {Error} If the session ID is invalid or data/mime is not a string.
* @returns {void}
*/
setFileData(mime?: string, data?: string, isBase64?: boolean, tokenAmount?: number, id?: string): void;
/**
* Removes file data from the selected session history.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @throws {Error} If the session history ID is invalid.
* @returns {void} This method does not return a value.
*/
removeFileData(id?: string): void;
/**
* Retrieves file data from the selected session history.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {{data: string, mime: string}|null} The file data, including MIME type and encoded content, or null if no file data is found.
* @throws {Error} If no valid session history ID is found.
*/
getFileData(id?: string): {
data: string;
mime: string;
} | null;
/**
* Sets a system instruction for the selected session history.
*
* @param {string} [data] - The system instruction to set.
* @param {number} [tokenAmount] - The token count associated with the system instruction (optional).
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @throws {Error} If the session history ID is invalid or the provided data is not a string.
* @returns {void}
*/
setSystemInstruction(data?: string, tokenAmount?: number, id?: string): void;
/**
* Retrieves the system instruction for the selected session history.
*
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {string|null} The system instruction for the selected session, or `null` if no instruction is set.
*/
getSystemInstruction(id?: string): string | null;
/**
* Retrieves the token count for a specific category within the selected session history.
*
* @param {string} where - The category from which to retrieve the token count (e.g., 'prompt', 'file', 'systemInstruction').
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {number|null} The token count if available, otherwise null.
*/
getTokens(where: string, id?: string): number | null;
/**
* Retrieves the hash value for a specific item in the selected session history.
*
* @param {string} where - The key representing the item whose hash value is being retrieved (e.g., 'prompt', 'file', 'systemInstruction').
* @param {string} [id] - The session ID. If omitted, the currently selected session history ID will be used.
* @returns {string|null} The hash value of the specified item, or null if the item does not exist.
*/
getHash(where: string, id?: string): string | null;
/**
* Destroys the instance by clearing history and removing all event listeners.
*
* This method resets the internal `history` object, effectively discarding any stored
* data or state associated with the instance's operations. It also removes all listeners
* from both `#events` and `#sysEvents` to ensure no further event handling occurs and to
* prevent memory leaks.
*
* This method should be called when the instance is no longer needed.
*
* @returns {void}
*/
destroy(): void;
#private;
}
import { EventEmitter } from 'events';