@promptbook/node 0.89.0-8 → 0.89.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/node`
 
 - Promptbooks are [divided into several](#-packages) packages, all are published from [single monorepo](https://github.com/webgptorg/promptbook).
@@ -248,6 +244,10 @@ But unlike programming languages, it is designed to be understandable by non-pro
 
 
 
+## 🔒 Security
+
+For information on reporting security vulnerabilities, see our [Security Policy](./SECURITY.md).
+
 ## 📦 Packages _(for developers)_
 
 This library is divided into several packages, all are published from [single monorepo](https://github.com/webgptorg/promptbook).
@@ -304,7 +304,7 @@ The following glossary is used to clarify certain concepts:
 ### General LLM / AI terms
 
 -   **Prompt drift** is a phenomenon where the AI model starts to generate outputs that are not aligned with the original prompt. This can happen due to the model's training data, the prompt's wording, or the model's architecture.
--   **Pipeline, workflow or chain** is a sequence of tasks that are executed in a specific order. In the context of AI, a pipeline can refer to a sequence of AI models that are used to process data.
+-   [**Pipeline, workflow scenario or chain** is a sequence of tasks that are executed in a specific order. In the context of AI, a pipeline can refer to a sequence of AI models that are used to process data.](https://github.com/webgptorg/promptbook/discussions/88)
 -   **Fine-tuning** is a process where a pre-trained AI model is further trained on a specific dataset to improve its performance on a specific task.
 -   **Zero-shot learning** is a machine learning paradigm where a model is trained to perform a task without any labeled examples. Instead, the model is provided with a description of the task and is expected to generate the correct output.
 -   **Few-shot learning** is a machine learning paradigm where a model is trained to perform a task with only a few labeled examples. This is in contrast to traditional machine learning, where models are trained on large datasets.
@@ -312,10 +312,6 @@ The following glossary is used to clarify certain concepts:
 -   **Retrieval-augmented generation** is a machine learning paradigm where a model generates text by retrieving relevant information from a large database of text. This approach combines the benefits of generative models and retrieval models.
 -   **Longtail** refers to non-common or rare events, items, or entities that are not well-represented in the training data of machine learning models. Longtail items are often challenging for models to predict accurately.
 
-
-
-
-
 _Note: This section is not complete dictionary, more list of general AI / LLM terms that has connection with Promptbook_
 
 
@@ -429,6 +425,8 @@ See [TODO.md](./TODO.md)
 
 ## 🖋️ Contributing
 
-We are open to pull requests, feedback, and suggestions.
+You can also ⭐ star the project, [follow us on GitHub](https://github.com/hejny) or [various other social networks](https://www.pavolhejny.com/contact/).We are open to [pull requests, feedback, and suggestions](./CONTRIBUTING.md).
+
+## 📞 Support
 
-You can also ⭐ star the project, [follow us on GitHub](https://github.com/hejny) or [various other social networks](https://www.pavolhejny.com/contact/).
+If you need help or have questions, please check our [Support Resources](./SUPPORT.md).

package/esm/index.es.js

@@ -30,7 +30,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.89.0-8';
+const PROMPTBOOK_ENGINE_VERSION = '0.89.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
@@ -76,6 +76,7 @@ const ADMIN_EMAIL = 'pavol@ptbk.io';
  * @public exported from `@promptbook/core`
  */
 const ADMIN_GITHUB_NAME = 'hejny';
+//            <- TODO: [🐊] Pick the best claim
 /**
  * When the title is not provided, the default title is used
  *
@@ -120,6 +121,7 @@ const VALUE_STRINGS = {
     infinity: '(infinity; ∞)',
     negativeInfinity: '(negative infinity; -∞)',
     unserializable: '(unserializable value)',
+    circular: '(circular JSON)',
 };
 /**
  * Small number limit
@@ -159,7 +161,7 @@ const DEFAULT_MAX_PARALLEL_COUNT = 5; // <- TODO: [🤹‍♂️]
  */
 const DEFAULT_MAX_EXECUTION_ATTEMPTS = 10; // <- TODO: [🤹‍♂️]
 // <- TODO: [🕝] Make also `BOOKS_DIRNAME_ALTERNATIVES`
-// TODO: !!!!!! Just .promptbook dir, hardocode others
+// TODO: Just `.promptbook` in config, hardcode subfolders like `download-cache` or `execution-cache`
 /**
  * Where to store the temporary downloads
  *
@@ -339,6 +341,54 @@ function $deepFreeze(objectValue) {
  * TODO: [🧠] Is there a way how to meaningfully test this utility
  */
 
+/**
+ * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
+ *
+ * @public exported from `@promptbook/core`
+ */
+class WrappedError extends Error {
+    constructor(whatWasThrown) {
+        const tag = `[🤮]`;
+        console.error(tag, whatWasThrown);
+        super(spaceTrim$1(`
+                Non-Error object was thrown
+
+                Note: Look for ${tag} in the console for more details
+                Please report issue on ${ADMIN_EMAIL}
+            `));
+        this.name = 'WrappedError';
+        Object.setPrototypeOf(this, WrappedError.prototype);
+    }
+}
+
+/**
+ * Helper used in catch blocks to assert that the error is an instance of `Error`
+ *
+ * @param whatWasThrown Any object that was thrown
+ * @returns Nothing if the error is an instance of `Error`
+ * @throws `WrappedError` or `UnexpectedError` if the error is not standard
+ *
+ * @private within the repository
+ */
+function assertsError(whatWasThrown) {
+    // Case 1: Handle error which was rethrown as `WrappedError`
+    if (whatWasThrown instanceof WrappedError) {
+        const wrappedError = whatWasThrown;
+        throw wrappedError;
+    }
+    // Case 2: Handle unexpected errors
+    if (whatWasThrown instanceof UnexpectedError) {
+        const unexpectedError = whatWasThrown;
+        throw unexpectedError;
+    }
+    // Case 3: Handle standard errors - keep them up to consumer
+    if (whatWasThrown instanceof Error) {
+        return;
+    }
+    // Case 4: Handle non-standard errors - wrap them into `WrappedError` and throw
+    throw new WrappedError(whatWasThrown);
+}
+
 /**
  * Checks if the value is [🚉] serializable as JSON
  * If not, throws an UnexpectedError with a rich error message and tracking
@@ -430,9 +480,7 @@ function checkSerializableAsJson(options) {
                 JSON.stringify(value); // <- TODO: [0]
             }
             catch (error) {
-                if (!(error instanceof Error)) {
-                    throw error;
-                }
+                assertsError(error);
                 throw new UnexpectedError(spaceTrim((block) => `
                             \`${name}\` is not serializable
 
@@ -1119,6 +1167,9 @@ function isValidFilePath(filename) {
 /**
  * Function isValidJsonString will tell you if the string is valid JSON or not
  *
+ * @param value The string to check
+ * @returns True if the string is a valid JSON string, false otherwise
+ *
  * @public exported from `@promptbook/utils`
  */
 function isValidJsonString(value /* <- [👨‍⚖️] */) {
@@ -1127,9 +1178,7 @@ function isValidJsonString(value /* <- [👨‍⚖️] */) {
         return true;
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         if (error.message.includes('Unexpected token')) {
             return false;
         }
@@ -1661,7 +1710,7 @@ class PipelineExecutionError extends Error {
     }
 }
 /**
- * TODO: !!!!!! Add id to all errors
+ * TODO: [🧠][🌂] Add id to all errors
  */
 
 /**
@@ -1798,6 +1847,19 @@ class NotYetImplementedError extends Error {
     }
 }
 
+/**
+ * Error thrown when a fetch request fails
+ *
+ * @public exported from `@promptbook/core`
+ */
+class PromptbookFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PromptbookFetchError';
+        Object.setPrototypeOf(this, PromptbookFetchError.prototype);
+    }
+}
+
 /**
  * Index of all custom errors
  *
@@ -1818,7 +1880,10 @@ const PROMPTBOOK_ERRORS = {
     PipelineExecutionError,
     PipelineLogicError,
     PipelineUrlError,
+    AuthenticationError,
+    PromptbookFetchError,
     UnexpectedError,
+    WrappedError,
     // TODO: [🪑]> VersionMismatchError,
 };
 /**
@@ -1835,7 +1900,6 @@ const COMMON_JAVASCRIPT_ERRORS = {
     TypeError,
     URIError,
     AggregateError,
-    AuthenticationError,
     /*
   Note: Not widely supported
   > InternalError,
@@ -1958,8 +2022,8 @@ function createTask(options) {
                 updatedAt = new Date();
                 errors.push(...executionResult.errors);
                 warnings.push(...executionResult.warnings);
-                // <- TODO: !!! Only unique errors and warnings should be added (or filtered)
-                // TODO: [🧠] !!! errors, warning, isSuccessful  are redundant both in `ExecutionTask` and `ExecutionTask.currentValue`
+                // <- TODO: [🌂] Only unique errors and warnings should be added (or filtered)
+                // TODO: [🧠] !! errors, warning, isSuccessful  are redundant both in `ExecutionTask` and `ExecutionTask.currentValue`
                 //            Also maybe move `ExecutionTask.currentValue.usage` -> `ExecutionTask.usage`
                 //            And delete `ExecutionTask.currentValue.preparedPipeline`
                 assertsTaskSuccessful(executionResult);
@@ -1969,6 +2033,7 @@ function createTask(options) {
                 partialResultSubject.next(executionResult);
             }
             catch (error) {
+                assertsError(error);
                 status = 'ERROR';
                 errors.push(error);
                 partialResultSubject.error(error);
@@ -2114,13 +2179,19 @@ function valueToString(value) {
             return value.toISOString();
         }
         else {
-            return JSON.stringify(value);
+            try {
+                return JSON.stringify(value);
+            }
+            catch (error) {
+                if (error instanceof TypeError && error.message.includes('circular structure')) {
+                    return VALUE_STRINGS.circular;
+                }
+                throw error;
+            }
         }
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         console.error(error);
         return VALUE_STRINGS.unserializable;
     }
@@ -2292,9 +2363,7 @@ function extractVariablesFromJavascript(script) {
             }
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         throw new ParseError(spaceTrim$1((block) => `
                     Can not extract variables from the script
                     ${block(error.stack || error.message)}
@@ -2413,6 +2482,28 @@ const MANDATORY_CSV_SETTINGS = Object.freeze({
     // encoding: 'utf-8',
 });
 
+/**
+ * Function to check if a string is valid CSV
+ *
+ * @param value The string to check
+ * @returns True if the string is a valid CSV string, false otherwise
+ *
+ * @public exported from `@promptbook/utils`
+ */
+function isValidCsvString(value) {
+    try {
+        // A simple check for CSV format: at least one comma and no invalid characters
+        if (value.includes(',') && /^[\w\s,"']+$/.test(value)) {
+            return true;
+        }
+        return false;
+    }
+    catch (error) {
+        assertsError(error);
+        return false;
+    }
+}
+
 /**
  * Definition for CSV spreadsheet
  *
@@ -2423,7 +2514,7 @@ const CsvFormatDefinition = {
     formatName: 'CSV',
     aliases: ['SPREADSHEET', 'TABLE'],
     isValid(value, settings, schema) {
-        return true;
+        return isValidCsvString(value);
     },
     canBeValid(partialValue, settings, schema) {
         return true;
@@ -2577,6 +2668,30 @@ const TextFormatDefinition = {
  * TODO: [🏢] Allow to expect something inside each item of list and other formats
  */
 
+/**
+ * Function to check if a string is valid XML
+ *
+ * @param value
+ * @returns True if the string is a valid XML string, false otherwise
+ *
+ * @public exported from `@promptbook/utils`
+ */
+function isValidXmlString(value) {
+    try {
+        const parser = new DOMParser();
+        const parsedDocument = parser.parseFromString(value, 'application/xml');
+        const parserError = parsedDocument.getElementsByTagName('parsererror');
+        if (parserError.length > 0) {
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        assertsError(error);
+        return false;
+    }
+}
+
 /**
  * Definition for XML format
  *
@@ -2586,7 +2701,7 @@ const XmlFormatDefinition = {
     formatName: 'XML',
     mimeType: 'application/xml',
     isValid(value, settings, schema) {
-        return true;
+        return isValidXmlString(value);
     },
     canBeValid(partialValue, settings, schema) {
         return true;
@@ -2783,14 +2898,15 @@ class MultipleLlmExecutionTools {
                 }
             }
             catch (error) {
-                if (!(error instanceof Error) || error instanceof UnexpectedError) {
+                assertsError(error);
+                if (error instanceof UnexpectedError) {
                     throw error;
                 }
                 errors.push({ llmExecutionTools, error });
             }
         }
         if (errors.length === 1) {
-            throw errors[0];
+            throw errors[0].error;
         }
         else if (errors.length > 1) {
             throw new PipelineExecutionError(
@@ -3647,9 +3763,7 @@ async function executeAttempts(options) {
                                 break scripts;
                             }
                             catch (error) {
-                                if (!(error instanceof Error)) {
-                                    throw error;
-                                }
+                                assertsError(error);
                                 if (error instanceof UnexpectedError) {
                                     throw error;
                                 }
@@ -3719,9 +3833,7 @@ async function executeAttempts(options) {
                             break scripts;
                         }
                         catch (error) {
-                            if (!(error instanceof Error)) {
-                                throw error;
-                            }
+                            assertsError(error);
                             if (error instanceof UnexpectedError) {
                                 throw error;
                             }
@@ -4342,9 +4454,7 @@ async function executePipeline(options) {
         await Promise.all(resolving);
     }
     catch (error /* <- Note: [3] */) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         // Note: No need to rethrow UnexpectedError
         // if (error instanceof UnexpectedError) {
         // Note: Count usage, [🧠] Maybe put to separate function executionReportJsonToUsage + DRY [🤹‍♂️]
@@ -5047,17 +5157,22 @@ function titleToName(value) {
 /**
  * The built-in `fetch' function with a lightweight error handling wrapper as default fetch function used in Promptbook scrapers
  *
- * @private as default `fetch` function used in Promptbook scrapers
+ * @public exported from `@promptbook/core`
  */
-const scraperFetch = async (url, init) => {
+const promptbookFetch = async (urlOrRequest, init) => {
     try {
-        return await fetch(url, init);
+        return await fetch(urlOrRequest, init);
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
+        assertsError(error);
+        let url;
+        if (typeof urlOrRequest === 'string') {
+            url = urlOrRequest;
         }
-        throw new KnowledgeScrapeError(spaceTrim((block) => `
+        else if (urlOrRequest instanceof Request) {
+            url = urlOrRequest.url;
+        }
+        throw new PromptbookFetchError(spaceTrim((block) => `
                     Can not fetch "${url}"
 
                     Fetch error:
@@ -5078,7 +5193,7 @@ const scraperFetch = async (url, init) => {
 async function makeKnowledgeSourceHandler(knowledgeSource, tools, options) {
     // console.log('!! makeKnowledgeSourceHandler', knowledgeSource);
     var _a;
-    const { fetch = scraperFetch } = tools;
+    const { fetch = promptbookFetch } = tools;
     const { knowledgeSourceContent } = knowledgeSource;
     let { name } = knowledgeSource;
     const { rootDirname = null, 
@@ -5280,9 +5395,7 @@ async function prepareKnowledgePieces(knowledgeSources, tools, options) {
             knowledgePreparedUnflatten[index] = pieces;
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             console.warn(error);
             // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
         }
@@ -6080,6 +6193,8 @@ function parseNumber(value) {
  */
 
 /**
+import { WrappedError } from '../../errors/WrappedError';
+import { assertsError } from '../../errors/assertsError';
  * Parses the expect command
  *
  * @see `documentationUrl` for more details
@@ -6171,9 +6286,7 @@ const expectCommandParser = {
             };
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             throw new ParseError(spaceTrim((block) => `
                             Invalid FORMAT command
                             ${block(error.message)}:
@@ -9154,9 +9267,7 @@ async function locateAppOnLinux({ linuxWhich, }) {
         return result.trim();
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         return null;
     }
 }
@@ -9234,9 +9345,7 @@ async function locateAppOnMacOs({ macOsName, }) {
         return result.trim() + toExec;
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         return null;
     }
 }
@@ -9267,9 +9376,7 @@ async function locateAppOnWindows({ appName, windowsSuffix, }) {
         throw new Error(`Can not locate app ${appName} on Windows.`);
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw error;
-        }
+        assertsError(error);
         return null;
     }
 }
@@ -9558,21 +9665,15 @@ function $registeredLlmToolsMessage() {
  */
 
 /**
- * @@@
- *
- * @@@ .env
+ * Provides the path to the `.env` file
  *
- * It looks for environment variables:
- * - `process.env.OPENAI_API_KEY`
- * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
- * - ...
+ * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file
  *
- * @returns @@@
- * @public exported from `@promptbook/node`
+ * @private within the repository - for CLI utils
  */
-async function $provideLlmToolsConfigurationFromEnv() {
+async function $provideEnvFilename() {
     if (!$isRunningInNode()) {
-        throw new EnvironmentMismatchError('Function `$provideLlmToolsFromEnv` works only in Node.js environment');
+        throw new EnvironmentMismatchError('Function `$provideEnvFilename` works only in Node.js environment');
     }
     const envFilePatterns = [
         '.env',
@@ -9592,8 +9693,7 @@ async function $provideLlmToolsConfigurationFromEnv() {
             const envFilename = join(rootDirname, pattern);
             if (await isFileExisting(envFilename, $provideFilesystemForNode())) {
                 $setUsedEnvFilename(envFilename);
-                dotenv.config({ path: envFilename });
-                break up_to_root;
+                return envFilename;
             }
         }
         if (isRootPath(rootDirname)) {
@@ -9602,6 +9702,34 @@ async function $provideLlmToolsConfigurationFromEnv() {
         // Note: If the directory does not exist, try the parent directory
         rootDirname = join(rootDirname, '..');
     }
+    return null;
+}
+/**
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */
+
+/**
+ * @@@
+ *
+ * @@@ .env
+ * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file
+ *
+ * It looks for environment variables:
+ * - `process.env.OPENAI_API_KEY`
+ * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
+ * - ...
+ *
+ * @returns @@@
+ * @public exported from `@promptbook/node`
+ */
+async function $provideLlmToolsConfigurationFromEnv() {
+    if (!$isRunningInNode()) {
+        throw new EnvironmentMismatchError('Function `$provideLlmToolsFromEnv` works only in Node.js environment');
+    }
+    const envFilepath = await $provideEnvFilename();
+    if (envFilepath !== null) {
+        dotenv.config({ path: envFilepath });
+    }
     const llmToolsConfiguration = $llmToolsMetadataRegister
         .list()
         .map((metadata) => metadata.createConfigurationFromEnv(process.env))
@@ -9609,15 +9737,8 @@ async function $provideLlmToolsConfigurationFromEnv() {
     return llmToolsConfiguration;
 }
 /**
- * TODO: [🧠][🪁] Maybe do allow to do auto-install if package not registered and not found
- * TODO: Add Azure OpenAI
- * TODO: [🧠][🍛]
- * TODO: [🧠] Is there some meaningfull way how to test this util
  * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
- * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
- * TODO: This should be maybe not under `_common` but under `utils`
- * TODO: [🧠][⚛] Maybe pass env as argument
- * TODO: [®] DRY Register logic */
+ */
 
 /**
  * @@@
@@ -9676,6 +9797,7 @@ function createLlmToolsFromConfiguration(configuration, options = {}) {
  * Note: This function is not cached, every call creates new instance of `MultipleLlmExecutionTools`
  *
  * @@@ .env
+ * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file
  *
  * It looks for environment variables:
  * - `process.env.OPENAI_API_KEY`
@@ -10209,9 +10331,7 @@ class JavascriptEvalExecutionTools {
             }
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             if (error instanceof ReferenceError) {
                 const undefinedName = error.message.split(' ')[0];
                 /*
@@ -10486,9 +10606,7 @@ async function createCollectionFromDirectory(rootPath, tools, options) {
                 // ---
             }
             catch (error) {
-                if (!(error instanceof Error)) {
-                    throw error;
-                }
+                assertsError(error);
                 // TODO: [7] DRY
                 const wrappedErrorMessage = spaceTrim((block) => `
                             ${error.name} in pipeline ${fileName.split('\\').join('/')}⁠:
@@ -10579,9 +10697,7 @@ async function createCollectionFromDirectory(rootPath, tools, options) {
                 }
             }
             catch (error) {
-                if (!(error instanceof Error)) {
-                    throw error;
-                }
+                assertsError(error);
                 // TODO: [7] DRY
                 const wrappedErrorMessage = spaceTrim((block) => `
                             ${error.name} in pipeline ${fileName.split('\\').join('/')}⁠: