@singlestore/ai - npm Package Compare versions

Comparing version 0.0.20 to 0.0.21

dist/index.d.ts

@@ -7,2 +7,16 @@ import z$1, { z } from 'zod';
 
+/**
+ * Represents the function signature for a ChatCompletionTool's `call` method.
+ * This method is responsible for executing the tool's primary logic.
+ *
+ * @typeParam T - The name of the tool, represented as a string literal type.
+ * @typeParam U - A Zod object schema or undefined, representing the parameters the tool requires.
+ *                If undefined, no parameters are expected.
+ * @typeParam K - The return type of the `call` function, representing the value produced by the tool.
+ *
+ * @param params - The parameters passed to the tool, inferred from the Zod schema `U` if provided.
+ *                 If `U` is undefined, this parameter is void.
+ *
+ * @returns A Promise that resolves to an object containing the tool's name, the result value, and optionally the parameters.
+ */
 type ChatCompletionToolCall<T extends string, U extends z.AnyZodObject | undefined, K> = (params: U extends z.AnyZodObject ? z.infer<U> : void) => Promise<{
@@ -13,2 +27,14 @@ name: T;
 }>;
+/**
+ * Configuration object for initializing a ChatCompletionTool.
+ *
+ * @typeParam T - The name of the tool, represented as a string literal type.
+ * @typeParam U - A Zod object schema or undefined, representing the parameters the tool requires.
+ * @typeParam K - The function signature for the tool's `call` method.
+ *
+ * @property {T} name - The unique name of the tool.
+ * @property {string} description - A description of the tool's functionality.
+ * @property {U} [params] - Optional Zod schema defining the parameters for the tool.
+ * @property {K} call - The function that implements the tool's primary logic.
+ */
 interface ChatCompletionToolConfig<T extends string, U extends z.AnyZodObject | undefined, K extends ChatCompletionToolCall<T, U, any>> {
@@ -20,4 +46,27 @@ name: T;
 }
+/**
+ * Represents any ChatCompletionTool with generic types for name, parameters, and call signature.
+ * This type is useful for handling tools in a generic context.
+ *
+ * @typeParam T - The name of the tool, represented as a string.
+ * @typeParam U - A Zod object schema or undefined, representing the parameters the tool requires.
+ * @typeParam K - The function signature for the tool's `call` method.
+ */
 type AnyChatCompletionTool = ChatCompletionTool<string, z.AnyZodObject | undefined, ChatCompletionToolCall<string, any | undefined, any>>;
+/**
+ * Merges two arrays of ChatCompletionTools, preserving their types.
+ *
+ * @typeParam T - An array of ChatCompletionTools or undefined.
+ * @typeParam U - Another array of ChatCompletionTools or undefined.
+ *
+ * @returns An array containing all tools from both input arrays, or undefined if both inputs are undefined.
+ */
 type MergeChatCompletionTools<T extends AnyChatCompletionTool[] | undefined, U extends AnyChatCompletionTool[] | undefined> = T extends AnyChatCompletionTool[] ? U extends AnyChatCompletionTool[] ? [...T, ...U] : T : U extends AnyChatCompletionTool[] ? U : undefined;
+/**
+ * Represents a tool used in chat completions, encapsulating a name, description, optional parameters, and a call function.
+ *
+ * @typeParam T - The name of the tool, represented as a string literal type.
+ * @typeParam U - A Zod object schema or undefined, representing the parameters the tool requires.
+ * @typeParam K - The function signature for the tool's `call` method.
+ */
 declare class ChatCompletionTool<T extends string, U extends z.AnyZodObject | undefined, K extends ChatCompletionToolCall<T, U, any>> {
@@ -28,10 +77,32 @@ name: T;
     call: K;
+    /**
+     * Constructs a new ChatCompletionTool instance.
+     *
+     * @param {ChatCompletionToolConfig<T, U, K>} config - Configuration object for initializing the tool.
+     */
     constructor(config: ChatCompletionToolConfig<T, U, K>);
 }
 
+/**
+ * Represents a single chat completion with the generated content.
+ */
 interface ChatCompletion {
     content: string;
 }
+/**
+ * Represents a stream of chat completions, which can be asynchronously generated.
+ * The stream yields `ChatCompletion` objects.
+ */
 type ChatCompletionStream = AsyncGenerator<ChatCompletion>;
+/**
+ * Callback function type for handling individual chunks of a chat completion stream.
+ *
+ * @param chunk - A chunk of chat completion content.
+ *
+ * @returns A Promise that resolves when the chunk is processed, or void if no async operation is needed.
+ */
 type OnChatCompletionChunk = (chunk: ChatCompletion) => Promise<void> | void;
+/**
+ * Represents a message in a chat completion, including the role (system, assistant, user) and content.
+ */
 interface ChatCompletionMessage {
@@ -41,2 +112,19 @@ role: Extract<ChatCompletionMessageParam["role"], "system" | "assistant" | "user">;
 }
+/**
+ * Parameters for creating a chat completion.
+ *
+ * @typeParam T - Indicates whether the completion should be streamed (boolean).
+ * @typeParam U - An array of tools that can be used during the chat completion.
+ *
+ * @property {string} [prompt] - The initial prompt to generate the chat completion.
+ * @property {string} [model] - The model to use for generating the completion.
+ * @property {string} [systemRole] - The role of the system in the conversation.
+ * @property {T} [stream] - Whether the completion should be streamed.
+ * @property {ChatCompletionMessage[]} [messages] - An array of previous messages in the conversation.
+ * @property {U} [tools] - An array of tools that can be used during the completion.
+ *
+ * @property {Record<string, (tool: AnyChatCompletionTool, params: any) => Promise<void>>} [toolCallHandlers] - Optional handlers for when a tool is called during the completion.
+ *
+ * @property {Record<string, (tool: AnyChatCompletionTool, result: any, params: any) => Promise<void>>} [toolCallResultHandlers] - Optional handlers for when a tool returns a result during the completion.
+ */
 interface CreateChatCompletionParams<T extends boolean | undefined, U extends AnyChatCompletionTool[] | undefined> {
@@ -56,45 +144,198 @@ prompt?: string;
 }
+/**
+ * The result of creating a chat completion.
+ *
+ * @typeParam T - Indicates whether the result is a stream or a single completion.
+ *
+ * @returns If T is true, returns a `ChatCompletionStream`, otherwise returns a single `ChatCompletion`.
+ */
 type CreateChatCompletionResult<T extends boolean | undefined> = T extends true ? ChatCompletionStream : ChatCompletion;
+/**
+ * Abstract class representing a chat completions generator, capable of handling various tools.
+ *
+ * @typeParam T - An array of tools that can be used during the chat completion.
+ */
 declare abstract class ChatCompletions<T extends AnyChatCompletionTool[] | undefined> {
+    /**
+     * The tools that can be used during chat completion. Initialized to undefined.
+     */
     tools: T;
+    /**
+     * Initializes the tools to be used in chat completion.
+     *
+     * @param tools - An array of tools to be used in the chat completion.
+     */
     initTools(tools: T): void;
+    /**
+     * Retrieves the models available for generating chat completions.
+     *
+     * @returns A promise that resolves to an array of model names or an array of model names directly.
+     */
     abstract getModels(): Promise<string[]> | string[];
+    /**
+     * Handles a stream of chat completions, optionally processing each chunk.
+     *
+     * @param stream - The stream of chat completions.
+     * @param onChunk - Optional callback function to handle each chunk as it is received.
+     *
+     * @returns A promise that resolves to the final chat completion, with all chunks combined.
+     */
     handleStream(stream: ChatCompletionStream, onChunk?: OnChatCompletionChunk): Promise<ChatCompletion>;
+    /**
+     * Creates a chat completion based on the provided parameters.
+     *
+     * @param params - Parameters for creating the chat completion, including the prompt, model, messages, tools, and handlers.
+     *
+     * @returns A promise that resolves to either a single chat completion or a stream of chat completions, depending on the `stream` parameter.
+     */
     abstract create(params: CreateChatCompletionParams<any, any>): Promise<CreateChatCompletionResult<any>>;
 }
 
+/**
+ * Represents the model type used in OpenAI chat completions.
+ */
 type OpenAIChatCompletionModel = ChatCompletionCreateParamsBase["model"];
+/**
+ * Internal interface that extends the base parameters for creating an OpenAI chat completion,
+ * excluding properties already defined in `CreateChatCompletionParams`.
+ */
 interface _OpenAICreateChatCompletionParams extends Omit<Partial<ChatCompletionCreateParamsBase>, keyof CreateChatCompletionParams<any, any>> {
 }
+/**
+ * Parameters for creating an OpenAI chat completion.
+ *
+ * @typeParam T - Indicates whether the completion should be streamed (boolean).
+ * @typeParam U - An array of tools that can be used during the chat completion.
+ *
+ * @property {OpenAIChatCompletionModel} [model] - The model to use for generating the completion.
+ */
 interface OpenAICreateChatCompletionParams<T extends boolean | undefined, U extends AnyChatCompletionTool[] | undefined> extends CreateChatCompletionParams<T, U>, _OpenAICreateChatCompletionParams {
     model?: OpenAIChatCompletionModel;
 }
+/**
+ * Class representing chat completions using OpenAI's API, with support for tools and streaming.
+ *
+ * @typeParam T - An array of tools that can be used during the chat completion.
+ */
 declare class OpenAIChatCompletions<T extends AnyChatCompletionTool[] | undefined> extends ChatCompletions<T> {
     private _openai;
     constructor(_openai: OpenAI);
+    /**
+     * Retrieves the list of models available for OpenAI chat completions.
+     *
+     * @returns An array of model names.
+     */
     getModels(): OpenAIChatCompletionModel[];
+    /**
+     * Creates a chat completion using OpenAI's API, with optional support for streaming and tool integration.
+     *
+     * @typeParam U - Indicates whether the completion should be streamed (boolean).
+     * @typeParam K - An array of tools that can be used during the chat completion.
+     *
+     * @param {OpenAICreateChatCompletionParams<U, MergeChatCompletionTools<T, K>>} params - Parameters for creating the chat completion, including prompt, system role, messages, tools, and handlers.
+     *
+     * @returns A promise that resolves to either a single chat completion or a stream of chat completions, depending on the `stream` parameter.
+     */
     create<U extends boolean | undefined = false, K extends AnyChatCompletionTool[] | undefined = undefined>({ prompt, systemRole, messages, tools, toolCallHandlers, toolCallResultHandlers, ...params }: OpenAICreateChatCompletionParams<U, MergeChatCompletionTools<T, K>>): Promise<CreateChatCompletionResult<U>>;
 }
 
+/**
+ * Represents a single embedding vector as an array of numbers.
+ */
 type Embedding = number[];
+/**
+ * Parameters for creating embeddings.
+ *
+ * @property {string} [model] - The model to use for creating embeddings. If not provided, a default model may be used.
+ */
 interface CreateEmbeddingsParams {
     model?: string;
 }
+/**
+ * Abstract class representing an embeddings generator.
+ * Implementations must provide methods to get available models and create embeddings.
+ */
 declare abstract class Embeddings {
+    /**
+     * Returns a list of available models that can be used for creating embeddings.
+     *
+     * @returns {string[]} - Array of model names.
+     */
     abstract getModels(): string[];
+    /**
+     * Creates embeddings from input data using the specified model.
+     *
+     * @param {string | string[]} input - The input text or array of texts to create embeddings for.
+     * @param {CreateEmbeddingsParams} [params] - Optional parameters for embedding creation.
+     * @returns {Promise<Embedding[]>} - A promise that resolves to an array of embedding vectors.
+     */
     abstract create(input: string | string[], params?: CreateEmbeddingsParams): Promise<Embedding[]>;
 }
 
+/**
+ * A type that omits specific properties from EmbeddingCreateParams
+ * to allow for partial customization when creating embeddings.
+ *
+ * @typeParam _OpenAICreateEmbeddingsParams - Partial EmbeddingCreateParams excluding "input" and any properties defined in CreateEmbeddingsParams.
+ */
 type _OpenAICreateEmbeddingsParams = Omit<Partial<EmbeddingCreateParams>, "input" | keyof CreateEmbeddingsParams>;
+/**
+ * Represents the possible models that can be used with OpenAI embeddings.
+ *
+ * @type OpenAIEmbeddingModel - The model name from EmbeddingCreateParams.
+ */
 type OpenAIEmbeddingModel = EmbeddingCreateParams["model"];
+/**
+ * Parameters for creating embeddings with OpenAI, extending the base CreateEmbeddingsParams
+ * and additional OpenAI-specific options.
+ *
+ * @extends CreateEmbeddingsParams - Inherits the base parameters for embedding creation.
+ * @property {OpenAIEmbeddingModel} [model] - The OpenAI model to use for creating embeddings. Defaults to a model if not provided.
+ */
 interface OpenAICreateEmbeddingsParams extends CreateEmbeddingsParams, _OpenAICreateEmbeddingsParams {
     model?: OpenAIEmbeddingModel;
 }
+/**
+ * A class that implements the Embeddings interface using OpenAI's API.
+ * This class allows for the creation of embeddings via OpenAI's models.
+ *
+ * @class OpenAIEmbeddings
+ * @extends Embeddings - Inherits the abstract class for embedding generation.
+ *
+ * @param {OpenAI} _openai - An instance of the OpenAI API client.
+ */
 declare class OpenAIEmbeddings extends Embeddings {
     private _openai;
     constructor(_openai: OpenAI);
+    /**
+     * Returns a list of supported OpenAI models that can be used to generate embeddings.
+     *
+     * @returns {OpenAIEmbeddingModel[]} - An array of model names supported by OpenAI.
+     */
     getModels(): OpenAIEmbeddingModel[];
+    /**
+     * Creates embeddings using the specified input and OpenAI model.
+     * The input can be a single string or an array of strings.
+     *
+     * @param {string | string[]} input - The input text or array of texts to generate embeddings for.
+     * @param {OpenAICreateEmbeddingsParams} [params] - Optional parameters, including the OpenAI model to use.
+     * @returns {Promise<Embedding[]>} - A promise that resolves to an array of embedding vectors generated by OpenAI.
+     *
+     * @throws {Error} - Throws an error if the OpenAI API call fails.
+     */
     create(input: string | string[], params?: OpenAICreateEmbeddingsParams): Promise<Embedding[]>;
 }
 
+/**
+ * Configuration object for initializing the `AI` class.
+ *
+ * @typeParam T - The type of `Embeddings` to be used, defaulting to `OpenAIEmbeddings`.
+ * @typeParam U - An array of tools that can be used during chat completions, or undefined.
+ * @typeParam K - The type of `ChatCompletions` to be used, defaulting to `OpenAIChatCompletions`.
+ *
+ * @property {string} [openAIApiKey] - The API key for authenticating with the OpenAI API.
+ * @property {T} [embeddings] - An instance of `Embeddings` used for generating embeddings. Defaults to `OpenAIEmbeddings`.
+ * @property {K} [chatCompletions] - An instance of `ChatCompletions` used for generating chat completions. Defaults to `OpenAIChatCompletions`.
+ * @property {U} [chatCompletionTools] - An optional array of tools that can be used during chat completions.
+ */
 interface AIConfig<T extends Embeddings, U extends AnyChatCompletionTool[] | undefined, K extends ChatCompletions<U>> {
@@ -106,6 +347,25 @@ openAIApiKey?: string;
 }
+/**
+ * Represents any `AI` instance with generic types for embeddings, tools, and chat completions.
+ * This type is useful for handling `AI` instances in a generic context.
+ */
 type AnyAI = AI<Embeddings, AnyChatCompletionTool[] | undefined, ChatCompletions<any>>;
+/**
+ * Main class for handling AI operations, including embeddings and chat completions.
+ *
+ * @typeParam T - The type of `Embeddings` to be used, defaulting to `OpenAIEmbeddings`.
+ * @typeParam U - An array of tools that can be used during chat completions, or undefined.
+ * @typeParam K - The type of `ChatCompletions` to be used, defaulting to `OpenAIChatCompletions`.
+ *
+ * @property {T} embeddings - An instance of `Embeddings` used for generating embeddings.
+ * @property {K} chatCompletions - An instance of `ChatCompletions` used for generating chat completions.
+ */
 declare class AI<T extends Embeddings = OpenAIEmbeddings, U extends AnyChatCompletionTool[] | undefined = undefined, K extends ChatCompletions<any> = OpenAIChatCompletions<U>> {
     embeddings: T;
     chatCompletions: K;
+    /**
+     * Constructs a new `AI` instance.
+     *
+     * @param {AIConfig<T, U, K>} config - The configuration object for initializing the `AI` instance.
+     */
     constructor(config: AIConfig<T, U, K>);
@@ -112,0 +372,0 @@ }

dist/index.js

@@ -43,6 +43,22 @@ "use strict";
 var ChatCompletions = class {
+  /**
+   * The tools that can be used during chat completion. Initialized to undefined.
+   */
   tools = void 0;
+  /**
+   * Initializes the tools to be used in chat completion.
+   *
+   * @param tools - An array of tools to be used in the chat completion.
+   */
   initTools(tools) {
     this.tools = tools;
   }
+  /**
+   * Handles a stream of chat completions, optionally processing each chunk.
+   *
+   * @param stream - The stream of chat completions.
+   * @param onChunk - Optional callback function to handle each chunk as it is received.
+   *
+   * @returns A promise that resolves to the final chat completion, with all chunks combined.
+   */
   async handleStream(stream, onChunk) {
@@ -65,2 +81,7 @@ let completion = { content: "" };
   }
+  /**
+   * Retrieves the list of models available for OpenAI chat completions.
+   *
+   * @returns An array of model names.
+   */
   getModels() {
@@ -86,2 +107,12 @@ return [
   }
+  /**
+   * Creates a chat completion using OpenAI's API, with optional support for streaming and tool integration.
+   *
+   * @typeParam U - Indicates whether the completion should be streamed (boolean).
+   * @typeParam K - An array of tools that can be used during the chat completion.
+   *
+   * @param {OpenAICreateChatCompletionParams<U, MergeChatCompletionTools<T, K>>} params - Parameters for creating the chat completion, including prompt, system role, messages, tools, and handlers.
+   *
+   * @returns A promise that resolves to either a single chat completion or a stream of chat completions, depending on the `stream` parameter.
+   */
   async create({
@@ -219,2 +250,7 @@ prompt,
   call;
+  /**
+   * Constructs a new ChatCompletionTool instance.
+   *
+   * @param {ChatCompletionToolConfig<T, U, K>} config - Configuration object for initializing the tool.
+   */
   constructor(config) {
@@ -238,5 +274,20 @@ this.name = config.name;
   }
+  /**
+   * Returns a list of supported OpenAI models that can be used to generate embeddings.
+   *
+   * @returns {OpenAIEmbeddingModel[]} - An array of model names supported by OpenAI.
+   */
   getModels() {
     return ["text-embedding-3-small", "text-embedding-3-large", "text-embedding-ada-002"];
   }
+  /**
+   * Creates embeddings using the specified input and OpenAI model.
+   * The input can be a single string or an array of strings.
+   *
+   * @param {string | string[]} input - The input text or array of texts to generate embeddings for.
+   * @param {OpenAICreateEmbeddingsParams} [params] - Optional parameters, including the OpenAI model to use.
+   * @returns {Promise<Embedding[]>} - A promise that resolves to an array of embedding vectors generated by OpenAI.
+   *
+   * @throws {Error} - Throws an error if the OpenAI API call fails.
+   */
   async create(input, params) {
@@ -253,2 +304,7 @@ const _input = Array.isArray(input) ? input : [input];
   chatCompletions;
+  /**
+   * Constructs a new `AI` instance.
+   *
+   * @param {AIConfig<T, U, K>} config - The configuration object for initializing the `AI` instance.
+   */
   constructor(config) {
@@ -255,0 +311,0 @@ const openai = new import_openai.OpenAI({ apiKey: config.openAIApiKey });

package.json

 {
   "name": "@singlestore/ai",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "license": "Apache-2.0",
@@ -5,0 +5,0 @@ "sideEffects": false,

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

124501

increased by80.52%

Lines of code

950

increased by64.36%

No dependency changes