@celljs/ai-core 3.2.0 → 3.3.0

package/src/common/chat/message/tool-response-message.ts

@@ -0,0 +1,40 @@
+import { AbstractMessage } from './abstract-message';
+import { MessageType } from './message-protocol';
+
+/**
+ * Represents a tool response.
+ */
+export interface ToolResponse {
+    /**
+     * The unique identifier for the tool.
+     */
+    id: string;
+
+    /**
+     * The name of the tool.
+     */
+    name: string;
+
+    /**
+     * The response data from the tool.
+     */
+    responseData: string;
+}
+
+/**
+ * The ToolResponseMessage class represents a message with a function content in a chat
+ * application.
+ */
+export class ToolResponseMessage extends AbstractMessage {
+
+    /**
+     * Creates an instance of ToolResponseMessage.
+     * @param responses The list of tool responses.
+     * @param metadata Additional metadata.
+     */
+    constructor(
+        readonly responses: ToolResponse[], metadata: Record<string, any> = {}) {
+        super(MessageType.TOOL, '', [], metadata);
+        this.responses = responses;
+    }
+}

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

@@ -0,0 +1,38 @@
+import { ResultMetadata } from '../../model/model-protocol';
+
+/**
+ * Abstract Data Type (ADT) encapsulating information on the completion choices in the AI
+ * response.
+ */
+export interface ChatGenerationMetadata extends ResultMetadata {
+
+    /**
+     * The reason this choice completed for the generation.
+     */
+    readonly contentFilterMetadata?: any;
+
+    /**
+     * The reason this choice completed for the generation.
+     */
+    readonly finishReason?: string;
+}
+
+export class ChatGenerationMetadata {
+
+    static EMPTY: ChatGenerationMetadata = ChatGenerationMetadata.from();
+
+    /**
+     * Factory method used to construct a new {@link ChatGenerationMetadata} from the
+     * given finish reason and content filter metadata.
+     *
+     * @param finishReason The reason for completion.
+     * @param contentFilterMetadata The content filter metadata.
+     * @returns A new instance of {@link ChatGenerationMetadata}.
+     */
+    static from(finishReason?: string, contentFilterMetadata?: any): ChatGenerationMetadata {
+        return {
+            finishReason, contentFilterMetadata
+        };
+    }
+}
+

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

@@ -1 +1,2 @@
 export * from './metadata-protocol';
+export * from './chat-generation-metadata';

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

@@ -118,6 +118,8 @@ export namespace PromptMetadata {
 }
 
 export interface ChatResponseMetadata extends ResponseMetadata {
+    readonly id?: string;
+    readonly model?: string;
     /**
      * AI provider specific metadata on rate limits.
      * @see RateLimit

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

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

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

@@ -1,15 +1,20 @@
 import { ModelOptions, ModelRequest } from '../../model/model-protocol';
-import { Media, Message } from '../message';
+import { Message, MessageType } from '../message/message-protocol';
+
+export const PromptTemplate = Symbol('PromptTemplate');
 
 /**
  * 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;
-
+    model?: string;
+    frequencyPenalty?: number;
+    maxTokens?: number;
+    presencePenalty?: number;
+    stopSequences?: string[];
+    temperature?: number;
+    topK?: number;
+    topP?: number;
 }
 
 export interface Prompt extends ModelRequest<Message[]> {
@@ -17,28 +22,13 @@ export interface Prompt extends ModelRequest<Message[]> {
     copy(): Prompt;
 }
 
-export interface PromptTemplateStringActions {
-
-    render(model?: Map<String, Object>): string;
-
+export interface PromptTemplateContext {
+    variables?: Record<string, any>;
+    chatOptions?: ChatOptions;
+    messageType?: MessageType;
 }
 
-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;
-
+export interface PromptTemplate {
+    render(template: string, ctx?: PromptTemplateContext): Promise<string>;
+    create(template: string, ctx?: PromptTemplateContext): Promise<Prompt>;
 }

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

@@ -0,0 +1,26 @@
+import { Autowired, Component, ExpressionHandler, IllegalArgumentError } from '@celljs/core';
+import { Prompt, PromptTemplate, PromptTemplateContext } from './prompt-protocol';
+import { PromptImpl } from './prompt';
+import { MessageType, SystemMessage } from '../message';
+
+@Component(PromptTemplate)
+export class PromptTemplateImpl implements PromptTemplate {
+
+    @Autowired(ExpressionHandler)
+    protected readonly expressionHandler: ExpressionHandler;
+
+    async render(template: string, ctx?: PromptTemplateContext): Promise<string> {
+        if (ctx?.variables) {
+            return this.expressionHandler.handle(template, ctx, { ignoreSpecialChar: true, bracketBegin: '{', bracketEnd: '}' });
+        }
+        return template;
+    }
+    async create(template: string, ctx?: PromptTemplateContext): Promise<Prompt> {
+        if (!ctx?.messageType || ctx?.messageType === MessageType.USER) {
+            return new PromptImpl(await this.render(template, ctx), ctx?.chatOptions);
+        } else if (ctx?.messageType === MessageType.SYSTEM) {
+            return new PromptImpl(new SystemMessage(await this.render(template, ctx)), ctx?.chatOptions);
+        }
+        throw new IllegalArgumentError(`Invalid message type: ${ctx?.messageType}`);
+    }
+}

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

@@ -4,6 +4,16 @@ import { Model, ModelOptions, ModelRequest, ModelResponse, ModelResult, Response
 
 export const EmbeddingModel = Symbol('EmbeddingModel');
 
+/**
+ * Enum representing the modality type of the source data.
+ */
+export enum ModalityType {
+    TEXT = 'TEXT',
+    IMAGE = 'IMAGE',
+    AUDIO = 'AUDIO',
+    VIDEO = 'VIDEO'
+}
+
 /**
  * Represents the metadata for an embedding result.
  */
@@ -29,14 +39,13 @@ export interface EmbeddingResultMetadata extends ResultMetadata {
     documentData: any;
 }
 
-/**
- * Enum representing the modality type of the source data.
- */
-export enum ModalityType {
-    TEXT = 'TEXT',
-    IMAGE = 'IMAGE',
-    AUDIO = 'AUDIO',
-    VIDEO = 'VIDEO'
+export namespace EmbeddingResultMetadata {
+    export const EMPTY: EmbeddingResultMetadata = {
+        modalityType: ModalityType.TEXT,
+        documentId: '',
+        mimeType: MimeTypeUtils.TEXT_PLAIN,
+        documentData: undefined
+    };
 }
 
 /**

package/src/common/error/error.ts

@@ -0,0 +1,7 @@
+import { CustomError } from '@celljs/core';
+
+export class AIError extends CustomError {
+    constructor(message: string) {
+        super(message);
+    }
+}

package/src/common/error/index.ts

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

package/src/common/index.ts

@@ -1,4 +1,6 @@
 export * from './chat';
 export * from './model';
 export * from './embedding';
+export * from './sse';
 export * from './utils';
+export * from './error';

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

@@ -25,12 +25,12 @@ export interface FunctionCallback {
     /**
      * 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
+     * @param functionArguments 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>;
+    call(functionArguments: string): Promise<string>;
 
 }
 

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

@@ -39,7 +39,9 @@ export interface ResultMetadata {}
  * object within the core domain, enhancing the understanding and management of AI model
  * responses in various applications.
  */
-export interface ResponseMetadata {}
+export interface ResponseMetadata {
+    readonly extra: Record<string, any>;
+}
 
 /**
  * This interface provides methods to access the main output of the AI model and the
@@ -182,6 +184,6 @@ export interface StreamingModel<TReq extends ModelRequest<any>, TResChunk extend
      * @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>;
+    stream(request: TReq): Promise<Observable<TResChunk>>;
 
 }

package/src/common/sse/index.ts

@@ -0,0 +1,3 @@
+export * from './line-decoder';
+export * from './sse-protocol';
+export * from './sse-decoder';

package/src/common/sse/line-decoder.ts

@@ -0,0 +1,65 @@
+import { Bytes, ByteUtil } from '@celljs/core';
+import { LineDecoder } from './sse-protocol';
+
+/**
+ * Line decoder.
+ */
+export class LineDecoderImpl implements LineDecoder {
+    private buffer: string[];
+    private trailingCR: boolean;
+
+    static readonly NEWLINE_CHARS = new Set(['\n', '\r', '\x0b', '\x0c', '\x1c', '\x1d', '\x1e', '\x85', '\u2028', '\u2029']);
+    static readonly NEWLINE_REGEXP = /\r\n|[\n\r\x0b\x0c\x1c\x1d\x1e\x85\u2028\u2029]/g;
+
+    constructor() {
+        this.buffer = [];
+        this.trailingCR = false;
+    }
+
+    decode(chunk: Bytes): string[] {
+        let text = ByteUtil.decode(chunk);
+
+        if (this.trailingCR) {
+            text = '\r' + text;
+            this.trailingCR = false;
+        }
+        if (text.endsWith('\r')) {
+            this.trailingCR = true;
+            text = text.slice(0, -1);
+        }
+
+        if (!text) {
+            return [];
+        }
+
+        const trailingNewline = LineDecoderImpl.NEWLINE_CHARS.has(text[text.length - 1] || '');
+        let lines = text.split(LineDecoderImpl.NEWLINE_REGEXP);
+
+        if (lines.length === 1 && !trailingNewline) {
+            this.buffer.push(lines[0]!);
+            return [];
+        }
+
+        if (this.buffer.length > 0) {
+            lines = [this.buffer.join('') + lines[0], ...lines.slice(1)];
+            this.buffer = [];
+        }
+
+        if (!trailingNewline) {
+            this.buffer = [lines.pop() || ''];
+        }
+
+        return lines;
+    }
+
+    flush(): string[] {
+        if (this.buffer.length === 0 && !this.trailingCR) {
+            return [];
+        }
+
+        const lines = [this.buffer.join('')];
+        this.buffer = [];
+        this.trailingCR = false;
+        return lines;
+    }
+}

package/src/common/sse/sse-decoder.ts

@@ -0,0 +1,88 @@
+import { EventDecoder, ServerSentEvent } from './sse-protocol';
+
+/**
+ * Server-sent event.
+ */
+export class SSEDecoder implements EventDecoder {
+    private event?: string;
+    private data: string[];
+    private chunks: string[];
+
+    constructor() {
+        this.event = undefined;
+        this.data = [];
+        this.chunks = [];
+    }
+
+    protected buildServerSentEvent(): ServerSentEvent {
+        const sse: ServerSentEvent = {
+            event: this.event,
+            data: this.data.join('\n'),
+            raw: this.chunks,
+        };
+
+        this.event = undefined;
+        this.data = [];
+        this.chunks = [];
+
+        return sse;
+    }
+
+    decode(line: string): ServerSentEvent | undefined {
+        if (line.endsWith('\r')) {
+            line = line.substring(0, line.length - 1);
+        }
+
+        if (!line) {
+            if (!this.event && this.data.length === 0) {
+                return;
+            }
+
+            return this.buildServerSentEvent();
+        }
+
+        this.chunks.push(line);
+
+        if (line.startsWith(':')) {
+            return;
+        }
+
+        if (line.startsWith('{') && line.endsWith('}')) {
+            this.data.push(line);
+            return this.buildServerSentEvent();
+        }
+
+        const [fieldName, , value] = this.partition(line, ':');
+
+        const trimmedValue = value.startsWith(' ') ? value.substring(1) : value;
+
+        if (fieldName === 'event') {
+            this.event = trimmedValue;
+        } else if (fieldName === 'data') {
+            this.data.push(trimmedValue);
+        }
+
+        return;
+    }
+
+    /**
+     * Partitions a string into three parts based on a delimiter.
+     * @param str The string to partition.
+     * @param delimiter The delimiter to partition the string by.
+     * @returns A tuple containing the three parts of the partitioned string.
+     * The first part is the string before the delimiter, the second part is the delimiter itself,
+     * and the third part is the string after the delimiter.
+     * If the delimiter is not found in the string, the first part is the entire string, the second part is an empty string, and the third part is an empty string.
+     * @example
+     * partition('hello,world', ',') // ['hello', ',', 'world']
+     * partition('hello,world', '.') // ['hello,world', '', '']
+     * partition('hello,world', 'l') // ['he', 'l', 'lo,world']
+     */
+    protected partition(str: string, delimiter: string): [string, string, string] {
+        const index = str.indexOf(delimiter);
+        if (index !== -1) {
+            return [str.substring(0, index), delimiter, str.substring(index + delimiter.length)];
+        }
+        return [str, '', ''];
+    }
+}

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

@@ -0,0 +1,25 @@
+import { Bytes } from '@celljs/core';
+
+/**
+ * Server-sent event.
+ */
+export interface ServerSentEvent {
+    event?: string;
+    data: string;
+    raw: string[];
+};
+
+/**
+ * Decoder for server-sent events.
+ */
+export interface EventDecoder {
+    decode(line: string): ServerSentEvent | undefined;
+}
+
+/**
+ * Decoder for line-based protocols.
+ */
+export interface LineDecoder {
+    decode(chunk: Bytes): string[];
+    flush(): string[];
+}

package/src/common/utils/index.ts

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

package/src/common/utils/sse-util.ts

@@ -0,0 +1,111 @@
+import { Observable, Subscriber } from 'rxjs';
+import { ServerSentEvent, SSEDecoder, LineDecoderImpl } from '../sse';
+import { Bytes } from '@celljs/core';
+
+/**
+ * SSE utility class.
+ */
+export class SSEUtil {
+
+    static toObservable<Item>(readableStream: ReadableStream, controller?: AbortController): Observable<Item> {
+        return new Observable<Item>(subscriber => {
+            (async () => {
+                const decoder = new SSEDecoder();
+                const lineDecoder = new LineDecoderImpl();
+
+                try {
+                    const iterable = this.readableStreamAsyncIterable<Bytes>(readableStream);
+                    for await (const chunk of iterable) {
+                        const lines = lineDecoder.decode(chunk);
+                        for (const line of lines) {
+                            const sse = decoder.decode(line);
+                            this.handleSSE(sse, subscriber, controller);
+                        }
+                    }
+
+                    const remainingLines = lineDecoder.flush();
+                    for (const line of remainingLines) {
+                        const sse = decoder.decode(line);
+                        if (sse) {
+                            this.handleSSE(sse, subscriber, controller);
+                        }
+                    }
+
+                    subscriber.complete();
+                } catch (e) {
+                    if (e instanceof Error && e.name === 'AbortError') {
+                        subscriber.complete();
+                    } else {
+                        subscriber.error(e);
+                    }
+                } finally {
+                    controller?.abort();
+                }
+
+            })();
+
+        });
+
+    }
+
+    private static handleSSE<Item>(sse: ServerSentEvent | undefined, subscriber: Subscriber<Item>, controller?: AbortController): void {
+        if (sse) {
+            if (sse.data.startsWith('[DONE]')) {
+                subscriber.complete();
+                controller?.abort();
+                return;
+            }
+
+            if (!sse.event || sse.event === 'error') {
+                let data;
+                try {
+                    data = JSON.parse(sse.data);
+                } catch (e) {
+                    console.error('Could not parse message into JSON:', sse.data);
+                    console.error('From chunk:', sse.raw);
+                    subscriber.error(e);
+                    return;
+                }
+
+                if (data && data.error) {
+                    subscriber.error(data.error);
+                    return;
+                }
+
+                subscriber.next(data);
+
+                if (data.done === true) {
+                    subscriber.complete();
+                    controller?.abort();
+                }
+            }
+        }
+    }
+
+    private static readableStreamAsyncIterable<T>(stream: any): AsyncIterableIterator<T> {
+        if (stream[Symbol.asyncIterator]) {return stream; }
+
+        const reader = stream.getReader();
+        return {
+            async next() {
+                try {
+                    const result = await reader.read();
+                    if (result?.done) {reader.releaseLock(); }
+                    return result;
+                } catch (e) {
+                    reader.releaseLock();
+                    throw e;
+                }
+            },
+            async return() {
+                const cancelPromise = reader.cancel();
+                reader.releaseLock();
+                await cancelPromise;
+                return { done: true, value: undefined };
+            },
+            [Symbol.asyncIterator]() {
+                return this;
+            },
+        };
+    }
+}