@celljs/ai-core 3.0.0

package/src/common/chat/message/abstract-message.ts

@@ -0,0 +1,13 @@
+import { Media, Message, MessageType } from './message-protocol';
+
+export abstract class AbstractMessage implements Message {
+    static MESSAGE_TYPE = 'messageType';
+
+    constructor(
+        readonly messageType: MessageType,
+        readonly content: string,
+        readonly media: Media[] = [],
+        readonly metadata: Record<string, any> = {}) {
+        this.metadata[AbstractMessage.MESSAGE_TYPE] = messageType;
+    }
+}

package/src/common/chat/message/assistant-message.ts

@@ -0,0 +1,12 @@
+import { AbstractMessage } from './abstract-message';
+import { Media, MessageType } from './message-protocol';
+
+export class AssistantMessage extends AbstractMessage {
+
+    constructor(
+        override readonly content: string,
+        override readonly media: Media[] = [],
+        override readonly metadata: Record<string, any> = {}) {
+        super(MessageType.ASSISTANT, content, media, metadata);
+    }
+}

package/src/common/chat/message/function-message.ts

@@ -0,0 +1,12 @@
+import { AbstractMessage } from './abstract-message';
+import { Media, MessageType } from './message-protocol';
+
+export class FunctionMessage extends AbstractMessage {
+
+    constructor(
+        override readonly content: string,
+        override readonly media: Media[] = [],
+        override readonly metadata: Record<string, any> = {}) {
+        super(MessageType.FUNCTION, content, media, metadata);
+    }
+}

package/src/common/chat/message/index.ts

@@ -0,0 +1,6 @@
+export * from './message-protocol';
+export * from './abstract-message';
+export * from './user-message';
+export * from './system-message';
+export * from './assistant-message';
+export * from './function-message';

package/src/common/chat/message/message-protocol.ts

@@ -0,0 +1,49 @@
+import { MediaType } from '@celljs/http';
+import { Content } from '../../model/model-protocol';
+
+/**
+ * The Media class represents the data and metadata of a media attachment in a message. It
+ * consists of a MIME type and the raw data.
+ *
+ * This class is used as a parameter in the constructor of the UserMessage class.
+ *
+ */
+export interface Media {
+
+    readonly mediaType: MediaType;
+
+    /**
+     * Get the media data object
+     */
+    readonly data: any;
+
+}
+
+/**
+ * The MessageType enum represents the type of a message in a chat application. It can be
+ * one of the following: USER, ASSISTANT, SYSTEM, FUNCTION.
+ */
+export enum MessageType {
+    USER = 'user',
+    ASSISTANT = 'assistant',
+    SYSTEM = 'system',
+    FUNCTION = 'function'
+}
+
+/**
+ * The Message interface represents a message that can be sent or received in a chat
+ * application. Messages can have content, media attachments, properties, and message
+ * types.
+ *
+ * @see Media
+ * @see MessageType
+ */
+export interface Message extends Content {
+    readonly messageType: MessageType;
+}
+
+export namespace Message {
+    export function isMessage(obj: any): obj is Message {
+        return obj && obj.messageType !== undefined;
+    }
+}

package/src/common/chat/message/system-message.ts

@@ -0,0 +1,12 @@
+import { AbstractMessage } from './abstract-message';
+import { Media, MessageType } from './message-protocol';
+
+export class SystemMessage extends AbstractMessage {
+
+    constructor(
+        override readonly content: string,
+        override readonly media: Media[] = [],
+        override readonly metadata: Record<string, any> = {}) {
+        super(MessageType.SYSTEM, content, media, metadata);
+    }
+}

package/src/common/chat/message/user-message.ts

@@ -0,0 +1,12 @@
+import { AbstractMessage } from './abstract-message';
+import { Media, MessageType } from './message-protocol';
+
+export class UserMessage extends AbstractMessage {
+
+    constructor(
+        override readonly content: string,
+        override readonly media: Media[] = [],
+        override readonly metadata: Record<string, any> = {}) {
+        super(MessageType.USER, content, media, metadata);
+    }
+}

package/src/common/chat/metadata/index.ts

@@ -0,0 +1 @@
+export * from './metadata-protocol';

package/src/common/chat/metadata/metadata-protocol.ts

@@ -0,0 +1,154 @@
+import { IllegalArgumentError } from '@celljs/core';
+import { ResponseMetadata } from '../../model/model-protocol';
+
+/**
+ * Abstract Data Type (ADT) encapsulating metadata on the usage of an AI provider's API
+ * per AI request.
+ */
+export interface Usage {
+
+    /**
+     * The number of tokens used in the prompt of the AI request.
+     */
+    readonly promptTokens: number;
+
+    /**
+     * The number of tokens returned in the generation (aka completion)
+     * of the AI's response.
+     */
+    readonly generationTokens: number;
+
+    /**
+     * The total number of tokens from both the prompt of an AI request
+     * and generation of the AI's response.
+     */
+    readonly totalTokens: number;
+
+}
+
+/**
+ * Abstract Data Type (ADT) encapsulating metadata from an AI provider's API rate limits
+ * granted to the API key in use and the API key's current balance.
+ */
+export interface RateLimit {
+
+    /**
+     * The maximum number of requests that are permitted before exhausting the
+     * rate limit.
+     */
+    readonly requestsLimit: number;
+
+    /**
+     * The remaining number of requests that are permitted before exhausting the
+     * requestsLimit rate limit.
+     */
+    readonly requestsRemaining: number;
+
+    /**
+     * The duration time until the rate limit (based on requests) resets
+     * to its requestsLimit initial state.
+     */
+    readonly requestsReset: number;
+
+    /**
+     * The maximum number of tokens that are permitted before exhausting the rate
+     * limit.
+     */
+    readonly tokensLimit: number;
+
+    /**
+     * The remaining number of tokens that are permitted before exhausting the
+     * tokensLimit rate limit.
+     */
+    readonly tokensRemaining: number;
+
+    /**
+     * The duration time until the rate limit (based on tokens) resets to
+     * its tokensLimit initial state.
+     */
+    readonly tokensReset: number;
+
+}
+
+/**
+ * Abstract Data Type (ADT) modeling filter metadata for all prompts sent during an AI
+ * request.
+ */
+export interface PromptFilterMetadata<T = any> {
+
+    /**
+     * Index of the prompt filter metadata contained in the AI response.
+     */
+    readonly promptIndex: number;
+
+    /**
+     * Returns the underlying AI provider metadata for filtering applied to prompt
+     * content.
+     * @param <T> {@link Class Type} used to cast the filtered content metadata into
+     * the AI provider-specific type.
+     * @return the underlying AI provider metadata for filtering applied to prompt
+     * content.
+     */
+    readonly contentFilterMetadata: T;
+
+}
+
+/**
+ * Abstract Data Type (ADT) modeling metadata gathered by the AI during request
+ * processing.
+ */
+export type PromptMetadata = PromptFilterMetadata[];
+
+export namespace PromptMetadata {
+    /**
+     * Returns an Optional {@link PromptFilterMetadata} at the given index.
+     * @param promptIndex index of the {@link PromptFilterMetadata} contained in this
+     * {@link PromptMetadata}.
+     * @return Optional {@link PromptFilterMetadata} at the given index.
+     * @throws IllegalArgumentError if the prompt index is less than 0.
+     */
+    export function findByPromptIndex(promptMetadata: PromptMetadata, promptIndex: number): PromptFilterMetadata | undefined {
+
+        if (promptIndex < 0) {
+            throw new IllegalArgumentError(`Prompt index [${promptIndex}] must be greater than equal to 0`);
+        }
+
+        return promptMetadata.find(promptFilterMetadata => promptFilterMetadata.promptIndex === promptIndex);
+    }
+}
+
+export interface ChatResponseMetadata extends ResponseMetadata {
+    /**
+     * AI provider specific metadata on rate limits.
+     * @see RateLimit
+     */
+    readonly rateLimit: RateLimit;
+
+    /**
+     * AI provider specific metadata on API usage.
+     * @see Usage
+     */
+    readonly usage: Usage;
+
+    readonly promptMetadata: PromptMetadata;
+
+}
+
+export namespace ChatResponseMetadata {
+    export const EMPTY = {
+        rateLimit: {
+            requestsLimit: 0,
+            requestsRemaining: 0,
+            requestsReset: 0,
+            tokensLimit: 0,
+            tokensRemaining: 0,
+            tokensReset: 0
+        },
+        usage: {
+            promptTokens: 0,
+            generationTokens: 0,
+            totalTokens: 0
+        },
+        promptMetadata: [] as PromptMetadata
+    } as ChatResponseMetadata;
+}

package/src/common/chat/model/chat-protocol.ts

@@ -0,0 +1,22 @@
+import { Model, ModelResponse, ModelResult, StreamingModel } from '../../model/model-protocol';
+import { AssistantMessage } from '../message';
+import { Prompt } from '../prompt/prompt-protocol';
+
+/**
+ * Represents a response returned by the AI.
+ */
+export interface Generation extends ModelResult<AssistantMessage> {
+
+}
+
+export interface ChatResponse extends ModelResponse<Generation> {
+
+}
+
+export interface StreamingChatModel extends StreamingModel<Prompt, ChatResponse> {
+
+}
+
+export interface ChatModel extends Model<Prompt, ChatResponse>, StreamingChatModel {
+
+}

package/src/common/chat/model/index.ts

@@ -0,0 +1 @@
+export * from './chat-protocol';

package/src/common/chat/prompt/index.ts

@@ -0,0 +1,2 @@
+export * from './prompt-protocol';
+export * from './prompt';

package/src/common/chat/prompt/prompt-protocol.ts

@@ -0,0 +1,44 @@
+import { ModelOptions, ModelRequest } from '../../model/model-protocol';
+import { Media, Message } from '../message';
+
+/**
+ * The ChatOptions represent the common options, portable across different chat models.
+ */
+export interface ChatOptions extends ModelOptions {
+
+    readonly temperature?: number;
+    readonly topP?: number;
+    readonly topK?: number;
+
+}
+
+export interface Prompt extends ModelRequest<Message[]> {
+    readonly contents: string;
+    copy(): Prompt;
+}
+
+export interface PromptTemplateStringActions {
+
+    render(model?: Map<String, Object>): string;
+
+}
+
+export interface PromptTemplateActions extends PromptTemplateStringActions {
+
+    create(model: Map<String, Object>): Prompt;
+
+}
+
+export interface PromptTemplateChatActions {
+
+    createMessages(): Message[];
+    createMessages(model: Map<String, Object>): Message[];
+
+}
+
+export interface PromptTemplateMessageActions {
+
+    createMessage(mediaList: Media[]): Message;
+    createMessage(model: Map<String, Object>): Message;
+
+}

package/src/common/chat/prompt/prompt.ts

@@ -0,0 +1,57 @@
+import { IllegalArgumentError } from '@celljs/core';
+import { ModelOptions } from '../../model/model-protocol';
+import { Message, MessageType, UserMessage } from '../message';
+import { ChatOptions, Prompt } from './prompt-protocol';
+
+export class PromptImpl implements Prompt {
+
+    protected messages: Message[];
+
+    protected modelOptions: ChatOptions;
+    constructor(messages: Message[] | Message | string, modelOptions: ChatOptions = {}) {
+        this.modelOptions = modelOptions;
+        if (Array.isArray(messages)) {
+            this.messages = messages;
+        } else if (typeof messages === 'string') {
+            this.messages = [new UserMessage(messages)];
+        } else {
+            this.messages = [messages];
+        }
+    }
+
+    private instructionsCopy(): Message[] {
+        return this.messages.map(message => {
+            if (message.messageType === MessageType.USER) {
+                return new UserMessage(message.content);
+            } else if (message.messageType === MessageType.ASSISTANT) {
+                return new UserMessage(message.content);
+            } else if (message.messageType === MessageType.SYSTEM) {
+                return new UserMessage(message.content);
+            } else if (message.messageType === MessageType.FUNCTION) {
+                return new UserMessage(message.content);
+            } else {
+                throw new IllegalArgumentError(`Unsupported message type: ${message.messageType}`);
+            }
+        });
+    }
+    copy(): Prompt {
+        return new PromptImpl(this.instructionsCopy(), this.modelOptions);
+    }
+
+    get contents(): string {
+        let contents = '';
+        for (const message of this.messages) {
+            contents += message.content;
+        }
+        return contents;
+    }
+
+    get instructions(): Message[] {
+        return this.messages;
+    }
+
+    get options(): ModelOptions {
+        return this.modelOptions;
+    }
+}
+

package/src/common/index.ts

@@ -0,0 +1,3 @@
+export * from './chat';
+export * from './model';
+export * from './utils';

package/src/common/model/function/function-protocol.ts

@@ -0,0 +1,58 @@
+import { ChatOptions } from '../../chat/prompt';
+
+/**
+ * Represents a model function call handler. Implementations are registered with the
+ * Models and called on prompts that trigger the function call.
+ */
+export interface FunctionCallback {
+
+    /**
+     * The Function name. Unique within the model.
+     */
+    readonly name: string;
+
+    /**
+     * The function description. This description is used by the model do
+     * decide if the function should be called or not.
+     */
+    readonly description: string;
+
+    /**
+     * The JSON schema of the function input type.
+     */
+    readonly inputTypeSchema: string;
+
+    /**
+     * Called when a model detects and triggers a function call. The model is responsible
+     * to pass the function arguments in the pre-configured JSON schema format.
+     * @param functionInput JSON string with the function arguments to be passed to the
+     * function. The arguments are defined as JSON schema usually registered with the the
+     * model.
+     * @return String containing the function call response.
+     */
+    call(functionInput: string): Promise<string>;
+
+}
+
+export interface FunctionCallingOptions {
+
+    /**
+     * Function Callbacks to be registered with the ChatClient. For Prompt Options the
+     * functionCallbacks are automatically enabled for the duration of the prompt
+     * execution. For Default Options the FunctionCallbacks are registered but disabled by
+     * default. You have to use "functions" property to list the function names from the
+     * ChatClient registry to be used in the chat completion requests.
+     */
+    functionCallbacks: FunctionCallback[];
+
+    /**
+     * List of function names from the ChatClient registry to be used in the next
+     * chat completion requests.
+     */
+    functions: Set<String>;
+}
+
+export interface PortableFunctionCallingOptions extends FunctionCallingOptions, ChatOptions {
+
+}
+

package/src/common/model/function/index.ts

@@ -0,0 +1 @@
+export * from './function-protocol';

package/src/common/model/index.ts

@@ -0,0 +1,2 @@
+
+export * from './model-protocol';

package/src/common/model/model-protocol.ts

@@ -0,0 +1,184 @@
+/**
+ * Provides a set of interfaces and classes for a generic API designed to interact with
+ * various AI models. This package includes interfaces for handling AI model calls,
+ * requests, responses, results, and associated metadata. It is designed to offer a
+ * flexible and adaptable framework for interacting with different types of AI models,
+ * abstracting the complexities involved in model invocation and result processing. The
+ * use of generics enhances the API's capability to work with a wide range of models,
+ * ensuring a broad applicability across diverse AI scenarios.
+ */
+
+import { Media } from '../chat';
+import { Observable } from 'rxjs';
+
+/**
+ * Interface representing the customizable options for AI model interactions. This marker
+ * interface allows for the specification of various settings and parameters that can
+ * influence the behavior and output of AI models. It is designed to provide flexibility
+ * and adaptability in different AI scenarios, ensuring that the AI models can be
+ * fine-tuned according to specific requirements.
+ */
+export interface ModelOptions {}
+
+/**
+ * Interface representing metadata associated with the results of an AI model. This
+ * interface focuses on providing additional context and insights into the results
+ * generated by AI models. It could include information like computation time, model
+ * version, or other relevant details that enhance understanding and management of AI
+ * model outputs in various applications.
+ */
+export interface ResultMetadata {}
+
+/**
+ * Interface representing metadata associated with an AI model's response. This interface
+ * is designed to provide additional information about the generative response from an AI
+ * model, including processing details and model-specific data. It serves as a value
+ * object within the core domain, enhancing the understanding and management of AI model
+ * responses in various applications.
+ */
+export interface ResponseMetadata {}
+
+/**
+ * This interface provides methods to access the main output of the AI model and the
+ * metadata associated with this result. It is designed to offer a standardized and
+ * comprehensive way to handle and interpret the outputs generated by AI models, catering
+ * to diverse AI applications and use cases.
+ *
+ * @param <T> the type of the output generated by the AI model
+ */
+export interface ModelResult<T> {
+
+    /**
+     * Retrieves the output generated by the AI model.
+     * The output generated by the AI model
+     */
+    readonly output: T;
+
+    /**
+     * Retrieves the metadata associated with the result of an AI model.
+     * The metadata associated with the result
+     */
+    readonly metadata: ResultMetadata;
+
+}
+
+/**
+ * Interface representing a request to an AI model. This interface encapsulates the
+ * necessary information required to interact with an AI model, including instructions or
+ * inputs (of generic type T) and additional model options. It provides a standardized way
+ * to send requests to AI models, ensuring that all necessary details are included and can
+ * be easily managed.
+ *
+ * @param <T> the type of instructions or input required by the AI model
+ */
+export interface ModelRequest<T> {
+
+    /**
+     * Retrieves the instructions or input required by the AI model.
+     * The instructions or input required by the AI model
+     */
+    readonly instructions: T; // required input
+
+    /**
+     * Retrieves the customizable options for AI model interactions.
+     * The customizable options for AI model interactions
+     */
+    readonly options: ModelOptions;
+
+}
+
+/**
+ * Interface representing the response received from an AI model. This interface provides
+ * methods to access the main result or a list of results generated by the AI model, along
+ * with the response metadata. It serves as a standardized way to encapsulate and manage
+ * the output from AI models, ensuring easy retrieval and processing of the generated
+ * information.
+ *
+ * @param <T> the type of the result(s) provided by the AI model
+ */
+export interface ModelResponse<T extends ModelResult<any>> {
+
+    /**
+     * Retrieves the result of the AI model.
+     * The result generated by the AI model
+     */
+    readonly result: T;
+
+    /**
+     * Retrieves the list of generated outputs by the AI model.
+     * The list of generated outputs
+     */
+    readonly results: T[];
+
+    /**
+     * Retrieves the response metadata associated with the AI model's response.
+     * The response metadata
+     */
+    readonly metadata: ResponseMetadata;
+
+}
+
+/**
+ * The Model interface provides a generic API for invoking AI models. It is designed
+ * to handle the interaction with various types of AI models by abstracting the process of
+ * sending requests and receiving responses. The interface uses Java generics to
+ * accommodate different types of requests and responses, enhancing flexibility and
+ * adaptability across different AI model implementations.
+ *
+ * @param <TReq> the generic type of the request to the AI model
+ * @param <TRes> the generic type of the response from the AI model
+ */
+export interface Model<TReq extends ModelRequest<any>, TRes extends ModelResponse<any>> {
+
+    /**
+     * Executes a method call to the AI model.
+     * @param request the request object to be sent to the AI model
+     * @return the response from the AI model
+     */
+    call(request: TReq): Promise<TRes>;
+
+}
+
+/**
+ * Data structure that contains content and metadata.
+ */
+export interface Content {
+
+    /**
+     * Get the content of the message.
+     */
+    readonly content: string; // TODO consider getText
+
+    /**
+     * Get the media associated with the content.
+     */
+    readonly media: Media[];
+
+    /**
+     * return Get the metadata associated with the content.
+     */
+    readonly metadata: Record<string, any>;
+
+}
+
+/**
+ * The StreamingModel interface provides a generic API for invoking an AI models
+ * with streaming response. It abstracts the process of sending requests and receiving a
+ * streaming responses. The interface uses Java generics to accommodate different types of
+ * requests and responses, enhancing flexibility and adaptability across different AI
+ * model implementations.
+ *
+ * @param <TReq> the generic type of the request to the AI model
+ * @param <TResChunk> the generic type of a single item in the streaming response from the
+ * AI model
+ */
+export interface StreamingModel<TReq extends ModelRequest<any>, TResChunk extends ModelResponse<any>> {
+
+    /**
+     * Executes a method call to the AI model.
+     * @param request the request object to be sent to the AI model
+     * @return the streaming response from the AI model
+     */
+    stream(request: TReq): Observable<TResChunk>;
+
+}

package/src/common/module.ts

@@ -0,0 +1,4 @@
+import { autoBind } from '@celljs/core';
+import './index';
+
+export default autoBind();

package/src/common/utils/index.ts

@@ -0,0 +1 @@
+export * from './prompt-util';