@celljs/ai-openai 3.4.4

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@celljs/ai-openai",
+  "version": "3.4.4",
+  "description": "OpenAI models support",
+  "main": "lib/common/index.js",
+  "typings": "lib/common/index.d.ts",
+  "dependencies": {
+    "@celljs/ai-core": "3.4.4",
+    "@celljs/core": "3.4.4",
+    "@celljs/http": "3.4.4",
+    "class-transformer": "^0.5.1",
+    "rxjs": "^6.6.0",
+    "tslib": "^2.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "cell-component"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cellbang/cell.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cellbang/cell/issues"
+  },
+  "homepage": "https://github.com/cellbang/cell",
+  "files": [
+    "lib",
+    "src",
+    "cell.yml"
+  ],
+  "scripts": {
+    "lint": "cell-component lint",
+    "build": "cell-component build",
+    "watch": "cell-component watch",
+    "clean": "cell-component clean",
+    "test": "cell-component test:js"
+  },
+  "devDependencies": {
+    "@celljs/component": "3.4.4"
+  },
+  "gitHead": "5d4a2384da3a67b3c16de24d4692bf754acfeda1"
+}

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

@@ -0,0 +1,51 @@
+import { Observable } from 'rxjs';
+import { ChatCompletionRequest } from './chat-request';
+import { ChatCompletion, ChatCompletionChunk } from './chat-response';
+import { EmbeddingResponse } from './embeddings-response';
+import { EmbeddingRequest } from './embeddings-request';
+import { ResponseEntity } from '@celljs/http';
+
+export const OpenAIAPIOptions = Symbol('OpenAIAPIOptions');
+export const OpenAIAPI = Symbol('OpenAIAPI');
+
+export interface OpenAIAPIOptions {
+    baseUrl?: string;
+    apiKey: string;
+    completionsPath?: string;
+    embeddingsPath?: string;
+}
+
+/**
+ * Interface representing the OpenAI API.
+ */
+export interface OpenAIAPI {
+    /**
+     * Creates a model response for the given chat conversation.
+     * @param chatRequest - The chat completion request.
+     * @param additionalHttpHeader - Optional, additional HTTP headers to be added to the request.
+     * @returns A promise that resolves to the chat completion response.
+     */
+    chat(chatRequest: ChatCompletionRequest, additionalHttpHeader?: Record<string, string>): Promise<ResponseEntity<ChatCompletion>>;
+
+    /**
+     * Creates a streaming chat response for the given chat conversation.
+     * @param chatRequest - The chat completion request. Must have the stream property set to true.
+     * @param additionalHttpHeader - Optional, additional HTTP headers to be added to the request.
+     * @returns A promise that resolves to an observable of chat completion chunks.
+     */
+    streamingChat(chatRequest: ChatCompletionRequest, additionalHttpHeader?: Record<string, string>): Promise<Observable<ResponseEntity<ChatCompletionChunk>>>;
+
+    /**
+     * Creates an embedding vector representing the input text or token array.
+     * @param embeddingsRequest - The embedding request.
+     * @typeParam T - Type of the entity in the data list. Can be a string or list of tokens (e.g., integers).
+     * For embedding multiple inputs in a single request, you can pass a list of strings or a list of lists of tokens.
+     * @example
+     * ```typescript
+     * embed(List.of("text1", "text2", "text3"));
+     * embed(List.of(List.of(1, 2, 3), List.of(3, 4, 5)));
+     * ```
+     * @returns A promise that resolves to an embedding response containing a list of embeddings.
+     */
+    embed<T>(embeddingsRequest: EmbeddingRequest<T>): Promise<ResponseEntity<EmbeddingResponse>>;
+}

package/src/common/api/chat-request.ts

@@ -0,0 +1,258 @@
+import { Expose, Type } from 'class-transformer';
+import { ChatCompletionMessage } from './message';
+import { ResponseFormat } from './response-format';
+
+export class StreamOptions {
+    static INCLUDE_USAGE = new StreamOptions(true);
+
+    constructor(
+        /**
+         * includeUsage If set, an additional chunk will be streamed
+         * before the data: [DONE] message. The usage field on this chunk
+         * shows the token usage statistics for the entire request, and
+         * the choices field will always be an empty array. All other chunks
+         * will also include a usage field, but with a null value.
+         */
+        public includeUsage: boolean
+    ) {
+    }
+}
+
+/**
+ * Function definition.
+ */
+export class Function {
+    description: string;
+    name: string;
+    parameters: Record<string, any>;
+    strict?: boolean;
+
+    static create(description: string, name: string, parameters: Record<string, any>, strict?: boolean): Function {
+        const func = new Function();
+        func.description = description;
+        func.name = name;
+        func.parameters = parameters;
+        func.strict = strict;
+        return func;
+    }
+}
+
+export enum ToolType {
+    /**
+     * Function tool type.
+     */
+    FUNCTION = 'function'
+}
+
+export class FunctionTool {
+    /**
+     * The type of the tool. Currently, only 'function' is supported.
+     */
+    type: ToolType;
+
+    /**
+     * The function definition.
+     */
+    function: Function;
+
+    static create(func: Function): FunctionTool {
+        const tool = new FunctionTool();
+        tool.type = ToolType.FUNCTION;
+        tool.function = func;
+        return tool;
+    }
+}
+
+/**
+ * The type of modality for the model completion.
+ */
+export enum OutputModality {
+    AUDIO = 'audio',
+    TEXT = 'text',
+}
+
+export enum Voice {
+    ALLOY = 'alloy',
+    ECHO = 'echo',
+    FABLE = 'fable',
+    ONYX = 'onyx',
+    NOVA = 'nova',
+    SHIMMER = 'shimmer'
+}
+
+export enum AudioResponseFormat {
+    MP3 = 'mp3',
+    FLAC = 'flac',
+    OPUS = 'opus',
+    PCM16 = 'pcm16',
+    WAV = 'wav'
+}
+
+export class AudioParameters {
+    /**
+     * Specifies the voice type.
+     */
+    voice?: Voice;
+    /**
+     * Specifies the output audio format.
+     */
+    format?: AudioResponseFormat;
+}
+
+/**
+ * Creates a model response for the given chat conversation.
+ */
+export class ChatCompletionRequest {
+    /**
+     * A list of messages comprising the conversation so far.
+     */
+    messages: ChatCompletionMessage[];
+
+    /**
+     * ID of the model to use.
+     */
+    model: string;
+    /**
+     * Whether to store the output of this chat completion request for use in OpenAI's model distillation or evals products.
+     */
+    store?: boolean;
+
+    /**
+     * Developer-defined tags and values used for filtering completions in the OpenAI's dashboard.
+     */
+    metadata?: Record<string, any>;
+
+    /**
+     * Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far,
+     * decreasing the model's likelihood to repeat the same line verbatim.
+     */
+    @Expose({ name: 'frequency_penalty' })
+    frequencyPenalty?: number;
+
+    /**
+     * Modify the likelihood of specified tokens appearing in the completion.
+     * Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100.
+     */
+    @Expose({ name: 'logit_bias' })
+    logitBias?: Record<string, number>;
+
+    /**
+     * Whether to return log probabilities of the output tokens or not.
+     */
+    logprobs?: boolean;
+
+    /**
+     * An integer between 0 and 5 specifying the number of most likely tokens to return at each token position, each with an associated log probability.
+     */
+    @Expose({ name: 'top_logprobs' })
+    topLogprobs?: number;
+
+    /**
+     * @deprecated The maximum number of tokens that can be generated in the chat completion. This value can be used to control costs for text generated via API.
+     */
+    maxTokens?: number;
+
+    /**
+     * An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens.
+     */
+    @Expose({ name: 'max_completion_tokens' })
+    maxCompletionTokens?: number;
+
+    /**
+     * How many chat completion choices to generate for each input message.
+     */
+    n?: number;
+
+    /**
+     * Output types that you would like the model to generate for this request.
+     */
+    @Expose({ name: 'output_modalities' })
+    outputModalities?: OutputModality[];
+
+    /**
+     * Parameters for audio output. Required when audio output is requested with outputModalities: ["audio"].
+     */
+    @Expose({ name: 'audio_parameters' })
+    @Type(() => AudioParameters)
+    audioParameters?: AudioParameters;
+
+    /**
+     * Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far,
+     * increasing the model's likelihood to talk about new topics.
+     */
+    @Expose({ name: 'presence_penalty' })
+    presencePenalty?: number;
+
+    /**
+     * An object specifying the format that the model must output.
+     */
+    @Expose({ name: 'response_format' })
+    @Type(() => ResponseFormat)
+    responseFormat?: ResponseFormat;
+
+    /**
+     * If specified, our system will make a best effort to sample deterministically,
+     * such that repeated requests with the same seed and parameters should return the same result.
+     */
+    seed?: number;
+
+    /**
+     * Specifies the latency tier to use for processing the request.
+     */
+    @Expose({ name: 'service_tier' })
+    serviceTier?: string;
+
+    /**
+     * Up to 4 sequences where the API will stop generating further tokens.
+     */
+    stop?: string[];
+
+    /**
+     * Options for streaming response.
+     */
+    stream?: boolean;
+
+    /**
+     * The format to return the response in. Currently, the only accepted value is "json".
+     */
+    @Expose({ name: 'stream_options' })
+    @Type(() => StreamOptions)
+    streamOptions?: StreamOptions;
+
+    /**
+     * What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random,
+     * while lower values like 0.2 will make it more focused and deterministic.
+     */
+    temperature?: number;
+
+    /**
+     * An alternative to sampling with temperature, called nucleus sampling,
+     * where the model considers the results of the tokens with top_p probability mass.
+     */
+    @Expose({ name: 'top_p' })
+    topP?: number;
+
+    /**
+     * A list of tools the model may call. Currently, only functions are supported as a tool.
+     */
+    @Type(() => FunctionTool)
+    tools?: FunctionTool[];
+
+    /**
+     * Controls which (if any) function is called by the model.
+     */
+    @Expose({ name: 'tool_choice' })
+    toolChoice?: Record<string, any>;
+
+    /**
+     * If set to true, the model will call all functions in the tools list in parallel. Otherwise,
+     * the model will call the functions in the tools list in the order they are provided.
+     */
+    @Expose({ name: 'parallel_tool_calls' })
+    parallelToolCalls?: boolean;
+
+    /**
+     * A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.
+     */
+    user?: string;
+}

package/src/common/api/chat-response.ts

@@ -0,0 +1,218 @@
+import { Expose, Type } from 'class-transformer';
+import { ChatCompletionFinishReason, ChatCompletionMessage } from './message';
+import { Usage } from './usage';
+
+/**
+ * The most likely tokens and their log probability, at this token position.
+ */
+export class TopLogProbs {
+    /**
+     * The token.
+     */
+    token: string;
+    /**
+     * The log probability of the token.
+     */
+    logprob: number;
+    /**
+     * A list of integers representing the UTF-8 bytes
+     * representation of the token. Useful in instances where characters are represented by multiple
+     * tokens and their byte representations must be combined to generate the correct
+     * text representation. Can be null if there is no bytes representation for the
+     * token.
+     */
+    @Expose({ name: 'bytes' })
+    probBytes: number[];
+}
+
+/**
+ * Message content tokens with log probability information.
+ */
+export class Content {
+    /**
+     * The token.
+     */
+    token: string;
+    /**
+     * The log probability of the token.
+     */
+    logprob: number;
+    /**
+     * A list of integers representing the UTF-8 bytes representation
+     * of the token. Useful in instances where characters are represented by multiple
+     * tokens and their byte representations must be combined to generate the correct
+     * text representation. Can be null if there is no bytes representation for the
+     * token.
+     */
+    @Expose({ name: 'bytes' })
+    probBytes: number[];
+    /**
+     * List of the most likely tokens and their log probability, at
+     * this token position. In rare cases, there may be fewer than the number of
+     * requested top_logprobs returned.
+     */
+    @Expose({ name: 'top_logprobs' })
+    topLogprobs: TopLogProbs[];
+}
+
+/**
+ * Log probability information for the choice.
+ */
+export class LogProbs {
+    /**
+     * Message content tokens with log probability information.
+     */
+    @Type(() => Content)
+    content: Content[];
+    /**
+     * Message refusal tokens with log probability information.
+     */
+    @Type(() => Content)
+    refusal: Content[];
+}
+
+/**
+ * Chat completion choice.
+ */
+export class Choice {
+    /**
+     * The reason the model stopped generating tokens.
+     */
+    @Expose({ name: 'finish_reason' })
+    finishReason: ChatCompletionFinishReason;
+    /**
+     * The index of the choice in the list of choices.
+     */
+    index: number;
+    /**
+     * A chat completion message generated by the model.
+     */
+    @Type(() => ChatCompletionMessage)
+    message: ChatCompletionMessage;
+    /**
+     * Log probability information for the choice.
+     */
+    logprobs: LogProbs;
+}
+
+/**
+ * Represents a chat completion response returned by model, based on the provided
+ * input.
+ */
+export class ChatCompletion {
+    /**
+     * A unique identifier for the chat completion.
+     */
+    id: string;
+    /**
+     * A list of chat completion choices. Can be more than one if n is
+     * greater than 1.
+     */
+    @Type(() => Choice)
+    choices: Choice[];
+    /**
+     * The Unix timestamp (in seconds) of when the chat completion was
+     * created.
+     */
+    created: number;
+    /**
+     * The model used for the chat completion.
+     */
+    model: string;
+    /**
+     * The service tier used for processing the request. This field is
+     * only included if the service_tier parameter is specified in the request.
+     */
+    @Expose({ name: 'service_tier' })
+    serviceTier: string;
+    /**
+     * This fingerprint represents the backend configuration that
+     * the model runs with. Can be used in conjunction with the seed request parameter to
+     * understand when backend changes have been made that might impact determinism.
+     */
+    @Expose({ name: 'system_fingerprint' })
+    systemFingerprint: string;
+    /**
+     * The object type, which is always chat.completion.
+     */
+    object: string;
+    /**
+     * Usage statistics for the completion request.
+     */
+    @Type(() => Usage)
+    usage: Usage;
+}
+
+/**
+ * Chat completion choice.
+ */
+export class ChunkChoice {
+    /**
+     * The reason the model stopped generating tokens.
+     */
+    @Expose({ name: 'finish_reason' })
+    finishReason: ChatCompletionFinishReason;
+    /**
+     * The index of the choice in the list of choices.
+     */
+    index: number;
+    /**
+     * A chat completion delta generated by streamed model responses.
+     */
+    @Type(() => ChatCompletionMessage)
+    delta: ChatCompletionMessage;
+    /**
+     * Log probability information for the choice.
+     */
+    @Type(() => LogProbs)
+    logprobs: LogProbs;
+}
+
+/**
+ * Represents a streamed chunk of a chat completion response returned by model, based
+ * on the provided input.
+ */
+export class ChatCompletionChunk {
+    /**
+     * A unique identifier for the chat completion. Each chunk has the same ID.
+     */
+    id: string;
+    /**
+     * A list of chat completion choices. Can be more than one if n is
+     * greater than 1.
+     */
+    @Type(() => ChunkChoice)
+    choices: ChunkChoice[];
+    /**
+     * The Unix timestamp (in seconds) of when the chat completion was
+     * created. Each chunk has the same timestamp.
+     */
+    created: number;
+    /**
+     * The model used for the chat completion.
+     */
+    model: string;
+    /**
+     * The service tier used for processing the request. This field is
+     * only included if the service_tier parameter is specified in the request.
+     */
+    @Expose({ name: 'service_tier' })
+    serviceTier: string;
+    /**
+     * This fingerprint represents the backend configuration that
+     * the model runs with. Can be used in conjunction with the seed request parameter to
+     * understand when backend changes have been made that might impact determinism.
+     */
+    @Expose({ name: 'system_fingerprint' })
+    systemFingerprint: string;
+    /**
+     * The object type, which is always 'chat.completion.chunk'.
+     */
+    object: string;
+    /**
+     * Usage statistics for the completion request. Present in the last chunk
+     * only if the StreamOptions.includeUsage is set to true.
+     */
+    @Type(() => Usage)
+    usage: Usage;
+}

package/src/common/api/embeddings-request.ts

@@ -0,0 +1,92 @@
+import { Expose } from 'class-transformer';
+
+/**
+ * Represents an embedding vector returned by embedding endpoint.
+ */
+export class Embedding {
+    /**
+     * The index of the embedding in the list of embeddings.
+     */
+    index: number;
+
+    /**
+     * The embedding vector, which is a list of floats. The length of vector depends on the model.
+     */
+    embedding: number[];
+
+    /**
+     * The object type, which is always 'embedding'.
+     */
+    object: string;
+
+    constructor(index: number, embedding: number[], object: string = 'embedding') {
+        this.index = index;
+        this.embedding = embedding;
+        this.object = object;
+    }
+}
+
+/**
+ * Creates an embedding vector representing the input text.
+ */
+export class EmbeddingRequest<T> {
+    /**
+     * Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request,
+     * pass an array of strings or array of token arrays.
+     * The input must not exceed the max input tokens for the model (8192 tokens for text-embedding-ada-002),
+     * cannot be an empty string, and any array must be 2048 dimensions or less.
+     */
+    input: T;
+
+    /**
+     * ID of the model to use.
+     */
+    model: string;
+
+    /**
+     * The format to return the embeddings in. Can be either float or base64.
+     */
+    @Expose({ name: 'encoding_format' })
+    encodingFormat: string;
+
+    /**
+     * The number of dimensions the resulting output embeddings should have. Only supported in text-embedding-3 and later models.
+     */
+    dimensions?: number;
+
+    /**
+     * A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.
+     */
+    user?: string;
+
+    constructor(
+        input: T,
+        model: string,
+        encodingFormat: string = 'float',
+        dimensions?: number,
+        user?: string
+    ) {
+        this.input = input;
+        this.model = model;
+        this.encodingFormat = encodingFormat;
+        this.dimensions = dimensions;
+        this.user = user;
+    }
+
+    /**
+     * Create an embedding request with the given input, model and encoding format set to float.
+     * @param input Input text to embed.
+     * @param model ID of the model to use.
+     */
+    static fromInputAndModel<T>(input: T, model: string): EmbeddingRequest<T> {
+        return new EmbeddingRequest(input, model);
+    }
+
+    /**
+     * Create an embedding request with the given input. Encoding format is set to float and user is null and the model is set to 'text-embedding-ada-002'.
+     * @param input Input text to embed.
+     */
+    static fromInput<T>(input: T): EmbeddingRequest<T> {
+        return new EmbeddingRequest(input, 'text-embedding-ada-002');
+    }
+}

package/src/common/api/embeddings-response.ts

@@ -0,0 +1,44 @@
+import { Type } from 'class-transformer';
+import { Embedding } from './embeddings-request';
+import { Usage } from './usage';
+
+/**
+ * List of multiple embedding responses.
+ *
+ * @typeparam T Type of the entities in the data list.
+ */
+export class EmbeddingResponse {
+    /**
+     * Must have value "list".
+     */
+    object: string;
+
+    /**
+     * List of entities.
+     */
+    @Type(() => Embedding)
+    data: Embedding[];
+
+    /**
+     * ID of the model to use.
+     */
+    model: string;
+
+    /**
+     * Usage statistics for the completion request.
+     */
+    @Type(() => Usage)
+    usage: Usage;
+
+    constructor(
+        object: string,
+        data: Embedding[],
+        model: string,
+        usage: Usage
+    ) {
+        this.object = object;
+        this.data = data;
+        this.model = model;
+        this.usage = usage;
+    }
+}