@promptbook/openai 0.92.0-8 → 0.92.0

package/README.md

@@ -23,10 +23,6 @@
 
 
 
-<blockquote style="color: #ff8811">
-    <b>⚠ Warning:</b> This is a pre-release version of the library. It is not yet ready for production use. Please look at <a href="https://www.npmjs.com/package/@promptbook/core?activeTab=versions">latest stable release</a>.
-</blockquote>
-
 ## 📦 Package `@promptbook/openai`
 
 - Promptbooks are [divided into several](#-packages) packages, all are published from [single monorepo](https://github.com/webgptorg/promptbook).
@@ -490,7 +486,7 @@ Or you can install them separately:
 -   **[@promptbook/legacy-documents](https://www.npmjs.com/package/@promptbook/legacy-documents)** - Read knowledge from legacy documents like `.doc`, `.rtf`,…
 -   **[@promptbook/website-crawler](https://www.npmjs.com/package/@promptbook/website-crawler)** - Crawl knowledge from the web
 -   **[@promptbook/editable](https://www.npmjs.com/package/@promptbook/editable)** - Editable book as native javascript object with imperative object API
--   **[@promptbook/templates](https://www.npmjs.com/package/@promptbook/templates)** - Usefull templates and examples of books which can be used as a starting point
+-   **[@promptbook/templates](https://www.npmjs.com/package/@promptbook/templates)** - Useful templates and examples of books which can be used as a starting point
 -   **[@promptbook/types](https://www.npmjs.com/package/@promptbook/types)** - Just typescript types used in the library
 -   ⭐ **[@promptbook/cli](https://www.npmjs.com/package/@promptbook/cli)** - Command line interface utilities for promptbooks
 -   🐋 **[Docker image](https://hub.docker.com/r/hejny/promptbook/)** - Promptbook server

package/esm/index.es.js

@@ -1,6 +1,7 @@
 import colors from 'colors';
 import spaceTrim$1, { spaceTrim } from 'spacetrim';
 import { randomBytes } from 'crypto';
+import Bottleneck from 'bottleneck';
 import OpenAI from 'openai';
 
 // ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
@@ -17,7 +18,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.92.0-8';
+const PROMPTBOOK_ENGINE_VERSION = '0.92.0';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -112,7 +113,7 @@ class PipelineExecutionError extends Error {
         super(message);
         this.name = 'PipelineExecutionError';
         // TODO: [🐙] DRY - Maybe $randomId
-        this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid simmilar char conflicts   */)}`;
+        this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid similar char conflicts   */)}`;
         Object.setPrototypeOf(this, PipelineExecutionError.prototype);
     }
 }
@@ -277,7 +278,7 @@ const VALUE_STRINGS = {
 const SMALL_NUMBER = 0.001;
 // <- TODO: [🧜‍♂️]
 /**
- * @@@
+ * Default settings for parsing and generating CSV files in Promptbook.
  *
  * @public exported from `@promptbook/core`
  */
@@ -287,6 +288,14 @@ Object.freeze({
     newline: '\n',
     skipEmptyLines: true,
 });
+/**
+ * Default rate limits (requests per minute)
+ *
+ * Note: Adjust based on the provider tier you are have
+ *
+ * @public exported from `@promptbook/core`
+ */
+const DEFAULT_MAX_REQUESTS_PER_MINUTE = 60;
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name
  * TODO: [🧠][🧜‍♂️] Maybe join remoteServerUrl and path into single value
@@ -362,7 +371,7 @@ class UnexpectedError extends Error {
                     ${block(message)}
 
                     Note: This error should not happen.
-                    It's probbably a bug in the pipeline collection
+                    It's probably a bug in the pipeline collection
 
                     Please report issue:
                     ${block(getErrorReportUrl(new Error(message)).href)}
@@ -562,8 +571,12 @@ function checkSerializableAsJson(options) {
  */
 
 /**
- * @@@
+ * Creates a deep clone of the given object
+ *
+ * Note: This method only works for objects that are fully serializable to JSON and do not contain functions, Dates, or special types.
  *
+ * @param objectValue The object to clone.
+ * @returns A deep, writable clone of the input object.
  * @public exported from `@promptbook/utils`
  */
 function deepClone(objectValue) {
@@ -625,13 +638,19 @@ function exportJson(options) {
  */
 const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
 /**
- * @@@
+ * Nonce which is used as string which is not occurring in normal text
+ *
+ * @private within the repository
+ */
+const SALT_NONCE = 'ptbkghhewbvruets21t54et5';
+/**
+ * Placeholder value indicating a parameter is missing its value.
  *
  * @private within the repository
  */
 const RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
 /**
- * @@@
+ * Placeholder value indicating a parameter is restricted and cannot be used directly.
  *
  * @private within the repository
  */
@@ -1168,10 +1187,10 @@ for (let i = 0; i < defaultDiacriticsRemovalMap.length; i++) {
 */
 
 /**
- * @@@
+ * Removes diacritic marks (accents) from characters in a string.
  *
- * @param input @@@
- * @returns @@@
+ * @param input The string containing diacritics to be normalized.
+ * @returns The string with diacritics removed or normalized.
  * @public exported from `@promptbook/utils`
  */
 function removeDiacritics(input) {
@@ -1222,14 +1241,18 @@ function computeUsageCounts(content) {
 /**
  * Make UncertainNumber
  *
- * @param value
+ * @param value value of the uncertain number, if `NaN` or `undefined`, it will be set to 0 and `isUncertain=true`
+ * @param isUncertain if `true`, the value is uncertain, otherwise depends on the value
  *
  * @private utility for initializating UncertainNumber
  */
-function uncertainNumber(value) {
+function uncertainNumber(value, isUncertain) {
     if (value === null || value === undefined || Number.isNaN(value)) {
         return UNCERTAIN_ZERO_VALUE;
     }
+    if (isUncertain === true) {
+        return { value, isUncertain };
+    }
     return { value };
 }
 
@@ -1246,7 +1269,7 @@ function computeUsage(value) {
 /**
  * List of available OpenAI models with pricing
  *
- * Note: Done at 2024-05-20
+ * Note: Done at 2025-05-06
  *
  * @see https://platform.openai.com/docs/models/
  * @see https://openai.com/api/pricing/
@@ -1507,7 +1530,7 @@ const OPENAI_MODELS = exportJson({
             modelName: 'text-embedding-3-large',
             modelDescription: "OpenAI's most capable text embedding model designed for high-quality embeddings for complex similarity tasks and information retrieval.",
             pricing: {
-                prompt: computeUsage(`$0.13  / 1M tokens`),
+                prompt: computeUsage(`$0.13 / 1M tokens`),
                 // TODO: [🏏] Leverage the batch API @see https://platform.openai.com/docs/guides/batch
                 output: 0, // <- Note: [🆖] In Embedding models you dont pay for output
             },
@@ -1600,8 +1623,8 @@ const OPENAI_MODELS = exportJson({
             modelName: 'gpt-4o-mini',
             modelDescription: 'Smaller, more cost-effective version of GPT-4o with good performance across text, vision, and audio tasks at reduced complexity.',
             pricing: {
-                prompt: computeUsage(`$3.00 / 1M tokens`),
-                output: computeUsage(`$9.00 / 1M tokens`),
+                prompt: computeUsage(`$0.15 / 1M tokens`),
+                output: computeUsage(`$0.60 / 1M tokens`),
             },
         },
         /**/
@@ -1623,7 +1646,7 @@ const OPENAI_MODELS = exportJson({
             modelTitle: 'o1-preview-2024-09-12',
             modelName: 'o1-preview-2024-09-12',
             modelDescription: 'September 2024 version of O1 preview with specialized reasoning capabilities for complex tasks requiring precise analytical thinking.',
-            //             <- TODO: [💩] Some better system to organize theese date suffixes and versions
+            //             <- TODO: [💩] Some better system to organize these date suffixes and versions
             pricing: {
                 prompt: computeUsage(`$15.00 / 1M tokens`),
                 output: computeUsage(`$60.00 / 1M tokens`),
@@ -1729,13 +1752,21 @@ resultContent, rawResponse) {
     }
     const inputTokens = rawResponse.usage.prompt_tokens;
     const outputTokens = ((_b = rawResponse.usage) === null || _b === void 0 ? void 0 : _b.completion_tokens) || 0;
-    const modelInfo = OPENAI_MODELS.find((model) => model.modelName === rawResponse.model);
+    let isUncertain = false;
+    let modelInfo = OPENAI_MODELS.find((model) => model.modelName === rawResponse.model);
+    if (modelInfo === undefined) {
+        // Note: Model is not in the list of known models, fallback to the family of the models and mark price as uncertain
+        modelInfo = OPENAI_MODELS.find((model) => (rawResponse.model || SALT_NONCE).startsWith(model.modelName));
+        if (modelInfo !== undefined) {
+            isUncertain = true;
+        }
+    }
     let price;
     if (modelInfo === undefined || modelInfo.pricing === undefined) {
         price = uncertainNumber();
     }
     else {
-        price = uncertainNumber(inputTokens * modelInfo.pricing.prompt + outputTokens * modelInfo.pricing.output);
+        price = uncertainNumber(inputTokens * modelInfo.pricing.prompt + outputTokens * modelInfo.pricing.output, isUncertain);
     }
     return {
         price,
@@ -1770,6 +1801,10 @@ class OpenAiExecutionTools {
          * OpenAI API client.
          */
         this.client = null;
+        // TODO: Allow configuring rate limits via options
+        this.limiter = new Bottleneck({
+            minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE),
+        });
     }
     get title() {
         return 'OpenAI';
@@ -1869,11 +1904,12 @@ class OpenAiExecutionTools {
             user: (_a = this.options.userId) === null || _a === void 0 ? void 0 : _a.toString(),
         };
         const start = $getCurrentDate();
-        let complete;
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
-        const rawResponse = await client.chat.completions.create(rawRequest).catch((error) => {
+        const rawResponse = await this.limiter
+            .schedule(() => client.chat.completions.create(rawRequest))
+            .catch((error) => {
             assertsError(error);
             if (this.options.isVerbose) {
                 console.info(colors.bgRed('error'), error);
@@ -1883,6 +1919,7 @@ class OpenAiExecutionTools {
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
         }
+        const complete = $getCurrentDate();
         if (!rawResponse.choices[0]) {
             throw new PipelineExecutionError('No choises from OpenAI');
         }
@@ -1891,8 +1928,6 @@ class OpenAiExecutionTools {
             throw new PipelineExecutionError('More than one choise from OpenAI');
         }
         const resultContent = rawResponse.choices[0].message.content;
-        // eslint-disable-next-line prefer-const
-        complete = $getCurrentDate();
         const usage = computeOpenAiUsage(content || '', resultContent || '', rawResponse);
         if (resultContent === null) {
             throw new PipelineExecutionError('No response message from OpenAI');
@@ -1946,11 +1981,12 @@ class OpenAiExecutionTools {
             user: (_a = this.options.userId) === null || _a === void 0 ? void 0 : _a.toString(),
         };
         const start = $getCurrentDate();
-        let complete;
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
-        const rawResponse = await client.completions.create(rawRequest).catch((error) => {
+        const rawResponse = await this.limiter
+            .schedule(() => client.completions.create(rawRequest))
+            .catch((error) => {
             assertsError(error);
             if (this.options.isVerbose) {
                 console.info(colors.bgRed('error'), error);
@@ -1960,6 +1996,7 @@ class OpenAiExecutionTools {
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
         }
+        const complete = $getCurrentDate();
         if (!rawResponse.choices[0]) {
             throw new PipelineExecutionError('No choises from OpenAI');
         }
@@ -1968,8 +2005,6 @@ class OpenAiExecutionTools {
             throw new PipelineExecutionError('More than one choise from OpenAI');
         }
         const resultContent = rawResponse.choices[0].text;
-        // eslint-disable-next-line prefer-const
-        complete = $getCurrentDate();
         const usage = computeOpenAiUsage(content || '', resultContent || '', rawResponse);
         return exportJson({
             name: 'promptResult',
@@ -2010,11 +2045,12 @@ class OpenAiExecutionTools {
             model: modelName,
         };
         const start = $getCurrentDate();
-        let complete;
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
-        const rawResponse = await client.embeddings.create(rawRequest).catch((error) => {
+        const rawResponse = await this.limiter
+            .schedule(() => client.embeddings.create(rawRequest))
+            .catch((error) => {
             assertsError(error);
             if (this.options.isVerbose) {
                 console.info(colors.bgRed('error'), error);
@@ -2024,12 +2060,11 @@ class OpenAiExecutionTools {
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
         }
+        const complete = $getCurrentDate();
         if (rawResponse.data.length !== 1) {
             throw new PipelineExecutionError(`Expected exactly 1 data item in response, got ${rawResponse.data.length}`);
         }
         const resultContent = rawResponse.data[0].embedding;
-        // eslint-disable-next-line prefer-const
-        complete = $getCurrentDate();
         const usage = computeOpenAiUsage(content || '', '', 
         // <- Note: Embedding does not have result content
         rawResponse);
@@ -2057,7 +2092,8 @@ class OpenAiExecutionTools {
      * Get the model that should be used as default
      */
     getDefaultModel(defaultModelName) {
-        const model = OPENAI_MODELS.find(({ modelName }) => modelName === defaultModelName);
+        // Note: Match exact or prefix for model families
+        const model = OPENAI_MODELS.find(({ modelName }) => modelName === defaultModelName || modelName.startsWith(defaultModelName));
         if (model === undefined) {
             throw new UnexpectedError(spaceTrim$1((block) => `
                             Cannot find model in OpenAI models with name "${defaultModelName}" which should be used as default.
@@ -2099,7 +2135,7 @@ class OpenAiExecutionTools {
 /**
  * Execution Tools for calling OpenAI API Assistants
  *
- * This is usefull for calling OpenAI API with a single assistant, for more wide usage use `OpenAiExecutionTools`.
+ * This is useful for calling OpenAI API with a single assistant, for more wide usage use `OpenAiExecutionTools`.
  *
  * @public exported from `@promptbook/openai`
  */
@@ -2112,6 +2148,7 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
     constructor(options) {
         super(options);
         this.assistantId = options.assistantId;
+        // TODO: [👱] Make limiter same as in `OpenAiExecutionTools`
     }
     get title() {
         return 'OpenAI Assistant';
@@ -2303,7 +2340,8 @@ const createOpenAiExecutionTools = Object.assign((options) => {
  */
 
 /**
- * @@@
+ * Safely retrieves the global scope object (window in browser, global in Node.js)
+ * regardless of the JavaScript environment in which the code is running
  *
  * Note: `$` is used to indicate that this function is not a pure function - it access global scope
  *
@@ -2314,10 +2352,10 @@ function $getGlobalScope() {
 }
 
 /**
- * @@@
+ * Normalizes a text string to SCREAMING_CASE (all uppercase with underscores).
  *
- * @param text @@@
- * @returns @@@
+ * @param text The text string to be converted to SCREAMING_CASE format.
+ * @returns The normalized text in SCREAMING_CASE format.
  * @example 'HELLO_WORLD'
  * @example 'I_LOVE_PROMPTBOOK'
  * @public exported from `@promptbook/utils`
@@ -2369,10 +2407,10 @@ function normalizeTo_SCREAMING_CASE(text) {
  */
 
 /**
- * @@@
+ * Normalizes a text string to snake_case format.
  *
- * @param text @@@
- * @returns @@@
+ * @param text The text string to be converted to snake_case format.
+ * @returns The normalized text in snake_case format.
  * @example 'hello_world'
  * @example 'i_love_promptbook'
  * @public exported from `@promptbook/utils`
@@ -2382,11 +2420,11 @@ function normalizeTo_snake_case(text) {
 }
 
 /**
- * Register is @@@
+ * Global registry for storing and managing registered entities of a given type.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it accesses and adds variables in global scope.
  *
- * @private internal utility, exported are only signleton instances of this class
+ * @private internal utility, exported are only singleton instances of this class
  */
 class $Register {
     constructor(registerName) {
@@ -2430,10 +2468,10 @@ class $Register {
 }
 
 /**
- * @@@
+ * Register for LLM tools.
  *
  * Note: `$` is used to indicate that this interacts with the global scope
- * @singleton Only one instance of each register is created per build, but thare can be more @@@
+ * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
  * @public exported from `@promptbook/core`
  */
 const $llmToolsRegister = new $Register('llm_execution_tools_constructors');
@@ -2452,9 +2490,9 @@ const $llmToolsRegister = new $Register('llm_execution_tools_constructors');
  */
 const _OpenAiRegistration = $llmToolsRegister.register(createOpenAiExecutionTools);
 /**
- * @@@ registration2
+ * Registration of the OpenAI Assistant provider
  *
- * Note: [🏐] Configurations registrations are done in @@@ BUT constructor @@@
+ * Note: [🏐] Configurations registrations are done in register-constructor.ts BUT constructor register-constructor.ts
  *
  * @public exported from `@promptbook/openai`
  * @public exported from `@promptbook/wizzard`