@promptbook/utils 0.92.0-9 → 0.93.0

package/umd/index.umd.js

@@ -22,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-9';
+    const PROMPTBOOK_ENGINE_VERSION = '0.93.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
@@ -78,7 +78,7 @@
     const SMALL_NUMBER = 0.001;
     // <- TODO: [🧜‍♂️]
     /**
-     * @@@
+     * Default settings for parsing and generating CSV files in Promptbook.
      *
      * @public exported from `@promptbook/core`
      */
@@ -93,6 +93,48 @@
      * TODO: [🧠][🧜‍♂️] Maybe join remoteServerUrl and path into single value
      */
 
+    /**
+     * Orders JSON object by keys
+     *
+     * @returns The same type of object as the input re-ordered
+     * @public exported from `@promptbook/utils`
+     */
+    function orderJson(options) {
+        const { value, order } = options;
+        const orderedValue = {
+            ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
+            ...value,
+        };
+        return orderedValue;
+    }
+
+    /**
+     * Freezes the given object and all its nested objects recursively
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
+     * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
+     *
+     * @returns The same object as the input, but deeply frozen
+     * @public exported from `@promptbook/utils`
+     */
+    function $deepFreeze(objectValue) {
+        if (Array.isArray(objectValue)) {
+            return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
+        }
+        const propertyNames = Object.getOwnPropertyNames(objectValue);
+        for (const propertyName of propertyNames) {
+            const value = objectValue[propertyName];
+            if (value && typeof value === 'object') {
+                $deepFreeze(value);
+            }
+        }
+        Object.freeze(objectValue);
+        return objectValue;
+    }
+    /**
+     * TODO: [🧠] Is there a way how to meaningfully test this utility
+     */
+
     /**
      * Make error report URL for the given error
      *
@@ -148,7 +190,7 @@
                     ${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)}
@@ -162,158 +204,447 @@
     }
 
     /**
-     * @@@
+     * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
      *
-     * @param text @@@
-     * @param _isFirstLetterCapital @@@
-     * @returns @@@
-     * @example 'helloWorld'
-     * @example 'iLovePromptbook'
-     * @public exported from `@promptbook/utils`
+     * @public exported from `@promptbook/core`
      */
-    function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
-        let charType;
-        let lastCharType = null;
-        let normalizedName = '';
-        for (const char of text) {
-            let normalizedChar;
-            if (/^[a-z]$/.test(char)) {
-                charType = 'LOWERCASE';
-                normalizedChar = char;
-            }
-            else if (/^[A-Z]$/.test(char)) {
-                charType = 'UPPERCASE';
-                normalizedChar = char.toLowerCase();
-            }
-            else if (/^[0-9]$/.test(char)) {
-                charType = 'NUMBER';
-                normalizedChar = char;
-            }
-            else {
-                charType = 'OTHER';
-                normalizedChar = '';
-            }
-            if (!lastCharType) {
-                if (_isFirstLetterCapital) {
-                    normalizedChar = normalizedChar.toUpperCase(); //TODO: DRY
-                }
-            }
-            else if (charType !== lastCharType &&
-                !(charType === 'LOWERCASE' && lastCharType === 'UPPERCASE') &&
-                !(lastCharType === 'NUMBER') &&
-                !(charType === 'NUMBER')) {
-                normalizedChar = normalizedChar.toUpperCase(); //TODO: [🌺] DRY
-            }
-            normalizedName += normalizedChar;
-            lastCharType = charType;
+    class WrappedError extends Error {
+        constructor(whatWasThrown) {
+            const tag = `[🤮]`;
+            console.error(tag, whatWasThrown);
+            super(spaceTrim$1.spaceTrim(`
+                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);
         }
-        return normalizedName;
     }
-    /**
-     * TODO: [🌺] Use some intermediate util splitWords
-     */
 
     /**
-     * Removes emojis from a string and fix whitespaces
+     * Helper used in catch blocks to assert that the error is an instance of `Error`
      *
-     * @param text with emojis
-     * @returns text without emojis
-     * @public exported from `@promptbook/utils`
+     * @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 removeEmojis(text) {
-        // Replace emojis (and also ZWJ sequence) with hyphens
-        text = text.replace(/(\p{Extended_Pictographic})\p{Modifier_Symbol}/gu, '$1');
-        text = text.replace(/(\p{Extended_Pictographic})[\u{FE00}-\u{FE0F}]/gu, '$1');
-        text = text.replace(/(\p{Extended_Pictographic})(\u{200D}\p{Extended_Pictographic})*/gu, '$1');
-        text = text.replace(/\p{Extended_Pictographic}/gu, '');
-        return text;
+    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);
     }
 
     /**
-     * Tests if given string is valid URL.
+     * Checks if the value is [🚉] serializable as JSON
+     * If not, throws an UnexpectedError with a rich error message and tracking
      *
-     * Note: This does not check if the file exists only if the path is valid
+     * - Almost all primitives are serializable BUT:
+     * - `undefined` is not serializable
+     * - `NaN` is not serializable
+     * - Objects and arrays are serializable if all their properties are serializable
+     * - Functions are not serializable
+     * - Circular references are not serializable
+     * - `Date` objects are not serializable
+     * - `Map` and `Set` objects are not serializable
+     * - `RegExp` objects are not serializable
+     * - `Error` objects are not serializable
+     * - `Symbol` objects are not serializable
+     * - And much more...
+     *
+     * @throws UnexpectedError if the value is not serializable as JSON
      * @public exported from `@promptbook/utils`
      */
-    function isValidFilePath(filename) {
-        if (typeof filename !== 'string') {
-            return false;
+    function checkSerializableAsJson(options) {
+        const { value, name, message } = options;
+        if (value === undefined) {
+            throw new UnexpectedError(`${name} is undefined`);
         }
-        if (filename.split('\n').length > 1) {
-            return false;
+        else if (value === null) {
+            return;
         }
-        if (filename.split(' ').length >
-            5 /* <- TODO: [🧠][🈷] Make some better non-arbitrary way how to distinct filenames from informational texts */) {
-            return false;
+        else if (typeof value === 'boolean') {
+            return;
         }
-        const filenameSlashes = filename.split('\\').join('/');
-        // Absolute Unix path: /hello.txt
-        if (/^(\/)/i.test(filenameSlashes)) {
-            // console.log(filename, 'Absolute Unix path: /hello.txt');
-            return true;
+        else if (typeof value === 'number' && !isNaN(value)) {
+            return;
         }
-        // Absolute Windows path: /hello.txt
-        if (/^([A-Z]{1,2}:\/?)\//i.test(filenameSlashes)) {
-            // console.log(filename, 'Absolute Windows path: /hello.txt');
-            return true;
+        else if (typeof value === 'string') {
+            return;
         }
-        // Relative path: ./hello.txt
-        if (/^(\.\.?\/)+/i.test(filenameSlashes)) {
-            // console.log(filename, 'Relative path: ./hello.txt');
-            return true;
+        else if (typeof value === 'symbol') {
+            throw new UnexpectedError(`${name} is symbol`);
         }
-        // Allow paths like foo/hello
-        if (/^[^/]+\/[^/]+/i.test(filenameSlashes)) {
-            // console.log(filename, 'Allow paths like foo/hello');
-            return true;
+        else if (typeof value === 'function') {
+            throw new UnexpectedError(`${name} is function`);
         }
-        // Allow paths like hello.book
-        if (/^[^/]+\.[^/]+$/i.test(filenameSlashes)) {
-            // console.log(filename, 'Allow paths like hello.book');
-            return true;
+        else if (typeof value === 'object' && Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+                checkSerializableAsJson({ name: `${name}[${i}]`, value: value[i], message });
+            }
         }
-        return false;
-    }
-    /**
-     * TODO: [🍏] Implement for MacOs
-     */
+        else if (typeof value === 'object') {
+            if (value instanceof Date) {
+                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
+                        \`${name}\` is Date
 
-    /**
-     * Tests if given string is valid URL.
-     *
-     * Note: Dataurl are considered perfectly valid.
-     * Note: There are two simmilar functions:
-     * - `isValidUrl` which tests any URL
-     * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
-     *
-     * @public exported from `@promptbook/utils`
-     */
-    function isValidUrl(url) {
-        if (typeof url !== 'string') {
-            return false;
-        }
-        try {
-            if (url.startsWith('blob:')) {
-                url = url.replace(/^blob:/, '');
+                        Use \`string_date_iso8601\` instead
+
+                        Additional message for \`${name}\`:
+                        ${block(message || '(nothing)')}
+                    `));
             }
-            const urlObject = new URL(url /* because fail is handled */);
-            if (!['http:', 'https:', 'data:'].includes(urlObject.protocol)) {
-                return false;
+            else if (value instanceof Map) {
+                throw new UnexpectedError(`${name} is Map`);
             }
-            return true;
-        }
-        catch (error) {
-            return false;
-        }
-    }
+            else if (value instanceof Set) {
+                throw new UnexpectedError(`${name} is Set`);
+            }
+            else if (value instanceof RegExp) {
+                throw new UnexpectedError(`${name} is RegExp`);
+            }
+            else if (value instanceof Error) {
+                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
+                        \`${name}\` is unserialized Error
 
-    const defaultDiacriticsRemovalMap = [
-        {
-            base: 'A',
-            letters: '\u0041\u24B6\uFF21\u00C0\u00C1\u00C2\u1EA6\u1EA4\u1EAA\u1EA8\u00C3\u0100\u0102\u1EB0\u1EAE\u1EB4\u1EB2\u0226\u01E0\u00C4\u01DE\u1EA2\u00C5\u01FA\u01CD\u0200\u0202\u1EA0\u1EAC\u1EB6\u1E00\u0104\u023A\u2C6F',
-        },
-        { base: 'AA', letters: '\uA732' },
-        { base: 'AE', letters: '\u00C6\u01FC\u01E2' },
+                        Use function \`serializeError\`
+
+                        Additional message for \`${name}\`:
+                        ${block(message || '(nothing)')}
+
+                    `));
+            }
+            else {
+                for (const [subName, subValue] of Object.entries(value)) {
+                    if (subValue === undefined) {
+                        // Note: undefined in object is serializable - it is just omited
+                        continue;
+                    }
+                    checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
+                }
+                try {
+                    JSON.stringify(value); // <- TODO: [0]
+                }
+                catch (error) {
+                    assertsError(error);
+                    throw new UnexpectedError(spaceTrim__default["default"]((block) => `
+                            \`${name}\` is not serializable
+
+                            ${block(error.stack || error.message)}
+
+                            Additional message for \`${name}\`:
+                            ${block(message || '(nothing)')}
+                        `));
+                }
+                /*
+                TODO: [0] Is there some more elegant way to check circular references?
+                const seen = new Set();
+                const stack = [{ value }];
+                while (stack.length > 0) {
+                    const { value } = stack.pop()!;
+                    if (typeof value === 'object' && value !== null) {
+                        if (seen.has(value)) {
+                            throw new UnexpectedError(`${name} has circular reference`);
+                        }
+                        seen.add(value);
+                        if (Array.isArray(value)) {
+                            stack.push(...value.map((value) => ({ value })));
+                        } else {
+                            stack.push(...Object.values(value).map((value) => ({ value })));
+                        }
+                    }
+                }
+                */
+                return;
+            }
+        }
+        else {
+            throw new UnexpectedError(spaceTrim__default["default"]((block) => `
+                    \`${name}\` is unknown type
+
+                    Additional message for \`${name}\`:
+                    ${block(message || '(nothing)')}
+                `));
+        }
+    }
+    /**
+     * TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
+     * TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
+     * Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
+     */
+
+    /**
+     * 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) {
+        return JSON.parse(JSON.stringify(objectValue));
+        /*
+        TODO: [🧠] Is there a better implementation?
+        > const propertyNames = Object.getOwnPropertyNames(objectValue);
+        > for (const propertyName of propertyNames) {
+        >     const value = (objectValue as really_any)[propertyName];
+        >     if (value && typeof value === 'object') {
+        >         deepClone(value);
+        >     }
+        > }
+        > return Object.assign({}, objectValue);
+        */
+    }
+    /**
+     * TODO: [🧠] Is there a way how to meaningfully test this utility
+     */
+
+    /**
+     * Utility to export a JSON object from a function
+     *
+     * 1) Checks if the value is serializable as JSON
+     * 2) Makes a deep clone of the object
+     * 2) Orders the object properties
+     * 2) Deeply freezes the cloned object
+     *
+     * Note: This function does not mutates the given object
+     *
+     * @returns The same type of object as the input but read-only and re-ordered
+     * @public exported from `@promptbook/utils`
+     */
+    function exportJson(options) {
+        const { name, value, order, message } = options;
+        checkSerializableAsJson({ name, value, message });
+        const orderedValue = 
+        // TODO: Fix error "Type instantiation is excessively deep and possibly infinite."
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        order === undefined
+            ? deepClone(value)
+            : orderJson({
+                value: value,
+                // <- Note: checkSerializableAsJson asserts that the value is serializable as JSON
+                order: order,
+            });
+        $deepFreeze(orderedValue);
+        return orderedValue;
+    }
+    /**
+     * TODO: [🧠] Is there a way how to meaningfully test this utility
+     */
+
+    /**
+     * Nonce which is used for replacing things in strings
+     *
+     * @private within the repository
+     */
+    const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
+    /**
+     * 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
+     */
+    const RESERVED_PARAMETER_RESTRICTED = 'RESTRICTED-' + REPLACING_NONCE;
+    /**
+     * The names of the parameters that are reserved for special purposes
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const RESERVED_PARAMETER_NAMES = exportJson({
+        name: 'RESERVED_PARAMETER_NAMES',
+        message: `The names of the parameters that are reserved for special purposes`,
+        value: [
+            'content',
+            'context',
+            'knowledge',
+            'examples',
+            'modelName',
+            'currentDate',
+            // <- TODO: list here all command names
+            // <- TODO: Add more like 'date', 'modelName',...
+            // <- TODO: Add [emoji] + instructions ACRY when adding new reserved parameter
+        ],
+    });
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
+    /**
+     * Normalizes a given text to camelCase format.
+     *
+     * @param text The text to be normalized.
+     * @param _isFirstLetterCapital Whether the first letter should be capitalized.
+     * @returns The camelCase formatted string.
+     * @example 'helloWorld'
+     * @example 'iLovePromptbook'
+     * @public exported from `@promptbook/utils`
+     */
+    function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
+        let charType;
+        let lastCharType = null;
+        let normalizedName = '';
+        for (const char of text) {
+            let normalizedChar;
+            if (/^[a-z]$/.test(char)) {
+                charType = 'LOWERCASE';
+                normalizedChar = char;
+            }
+            else if (/^[A-Z]$/.test(char)) {
+                charType = 'UPPERCASE';
+                normalizedChar = char.toLowerCase();
+            }
+            else if (/^[0-9]$/.test(char)) {
+                charType = 'NUMBER';
+                normalizedChar = char;
+            }
+            else {
+                charType = 'OTHER';
+                normalizedChar = '';
+            }
+            if (!lastCharType) {
+                if (_isFirstLetterCapital) {
+                    normalizedChar = normalizedChar.toUpperCase(); //TODO: DRY
+                }
+            }
+            else if (charType !== lastCharType &&
+                !(charType === 'LOWERCASE' && lastCharType === 'UPPERCASE') &&
+                !(lastCharType === 'NUMBER') &&
+                !(charType === 'NUMBER')) {
+                normalizedChar = normalizedChar.toUpperCase(); //TODO: [🌺] DRY
+            }
+            normalizedName += normalizedChar;
+            lastCharType = charType;
+        }
+        return normalizedName;
+    }
+    /**
+     * TODO: [🌺] Use some intermediate util splitWords
+     */
+
+    /**
+     * Removes emojis from a string and fix whitespaces
+     *
+     * @param text with emojis
+     * @returns text without emojis
+     * @public exported from `@promptbook/utils`
+     */
+    function removeEmojis(text) {
+        // Replace emojis (and also ZWJ sequence) with hyphens
+        text = text.replace(/(\p{Extended_Pictographic})\p{Modifier_Symbol}/gu, '$1');
+        text = text.replace(/(\p{Extended_Pictographic})[\u{FE00}-\u{FE0F}]/gu, '$1');
+        text = text.replace(/(\p{Extended_Pictographic})(\u{200D}\p{Extended_Pictographic})*/gu, '$1');
+        text = text.replace(/\p{Extended_Pictographic}/gu, '');
+        return text;
+    }
+
+    /**
+     * Tests if given string is valid URL.
+     *
+     * Note: This does not check if the file exists only if the path is valid
+     * @public exported from `@promptbook/utils`
+     */
+    function isValidFilePath(filename) {
+        if (typeof filename !== 'string') {
+            return false;
+        }
+        if (filename.split('\n').length > 1) {
+            return false;
+        }
+        if (filename.split(' ').length >
+            5 /* <- TODO: [🧠][🈷] Make some better non-arbitrary way how to distinct filenames from informational texts */) {
+            return false;
+        }
+        const filenameSlashes = filename.split('\\').join('/');
+        // Absolute Unix path: /hello.txt
+        if (/^(\/)/i.test(filenameSlashes)) {
+            // console.log(filename, 'Absolute Unix path: /hello.txt');
+            return true;
+        }
+        // Absolute Windows path: /hello.txt
+        if (/^([A-Z]{1,2}:\/?)\//i.test(filenameSlashes)) {
+            // console.log(filename, 'Absolute Windows path: /hello.txt');
+            return true;
+        }
+        // Relative path: ./hello.txt
+        if (/^(\.\.?\/)+/i.test(filenameSlashes)) {
+            // console.log(filename, 'Relative path: ./hello.txt');
+            return true;
+        }
+        // Allow paths like foo/hello
+        if (/^[^/]+\/[^/]+/i.test(filenameSlashes)) {
+            // console.log(filename, 'Allow paths like foo/hello');
+            return true;
+        }
+        // Allow paths like hello.book
+        if (/^[^/]+\.[^/]+$/i.test(filenameSlashes)) {
+            // console.log(filename, 'Allow paths like hello.book');
+            return true;
+        }
+        return false;
+    }
+    /**
+     * TODO: [🍏] Implement for MacOs
+     */
+
+    /**
+     * Tests if given string is valid URL.
+     *
+     * Note: Dataurl are considered perfectly valid.
+     * Note: There are two similar functions:
+     * - `isValidUrl` which tests any URL
+     * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    function isValidUrl(url) {
+        if (typeof url !== 'string') {
+            return false;
+        }
+        try {
+            if (url.startsWith('blob:')) {
+                url = url.replace(/^blob:/, '');
+            }
+            const urlObject = new URL(url /* because fail is handled */);
+            if (!['http:', 'https:', 'data:'].includes(urlObject.protocol)) {
+                return false;
+            }
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+
+    const defaultDiacriticsRemovalMap = [
+        {
+            base: 'A',
+            letters: '\u0041\u24B6\uFF21\u00C0\u00C1\u00C2\u1EA6\u1EA4\u1EAA\u1EA8\u00C3\u0100\u0102\u1EB0\u1EAE\u1EB4\u1EB2\u0226\u01E0\u00C4\u01DE\u1EA2\u00C5\u01FA\u01CD\u0200\u0202\u1EA0\u1EAC\u1EB6\u1E00\u0104\u023A\u2C6F',
+        },
+        { base: 'AA', letters: '\uA732' },
+        { base: 'AE', letters: '\u00C6\u01FC\u01E2' },
         { base: 'AO', letters: '\uA734' },
         { base: 'AU', letters: '\uA736' },
         { base: 'AV', letters: '\uA738\uA73A' },
@@ -552,10 +883,10 @@
     */
 
     /**
-     * @@@
+     * 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) {
@@ -569,10 +900,10 @@
      */
 
     /**
-     * @@@
+     * Converts a given text to kebab-case format.
      *
-     * @param text @@@
-     * @returns @@@
+     * @param text The text to be converted.
+     * @returns The kebab-case formatted string.
      * @example 'hello-world'
      * @example 'i-love-promptbook'
      * @public exported from `@promptbook/utils`
@@ -620,11 +951,11 @@
      */
 
     /**
-     * @@@
+     * Converts a title string into a normalized name.
      *
-     * @param value @@@
-     * @returns @@@
-     * @example @@@
+     * @param value The title string to be converted to a name.
+     * @returns A normalized name derived from the input title.
+     * @example 'Hello World!' -> 'hello-world'
      * @public exported from `@promptbook/utils`
      */
     function titleToName(value) {
@@ -652,21 +983,63 @@
      */
     function renderPromptbookMermaid(pipelineJson, options) {
         const { linkTask = () => null } = options || {};
+        const MERMAID_PREFIX = 'pipeline_';
+        const MERMAID_KNOWLEDGE_NAME = MERMAID_PREFIX + 'knowledge';
+        const MERMAID_RESERVED_NAME = MERMAID_PREFIX + 'reserved';
+        const MERMAID_INPUT_NAME = MERMAID_PREFIX + 'input';
+        const MERMAID_OUTPUT_NAME = MERMAID_PREFIX + 'output';
         const parameterNameToTaskName = (parameterName) => {
+            if (parameterName === 'knowledge') {
+                return MERMAID_KNOWLEDGE_NAME;
+            }
+            else if (RESERVED_PARAMETER_NAMES.includes(parameterName)) {
+                return MERMAID_RESERVED_NAME;
+            }
             const parameter = pipelineJson.parameters.find((parameter) => parameter.name === parameterName);
             if (!parameter) {
                 throw new UnexpectedError(`Could not find {${parameterName}}`);
-                // <- TODO: !!6 This causes problems when {knowledge} and other reserved parameters are used
+                // <- TODO: This causes problems when {knowledge} and other reserved parameters are used
             }
             if (parameter.isInput) {
-                return 'input';
+                return MERMAID_INPUT_NAME;
             }
             const task = pipelineJson.tasks.find((task) => task.resultingParameterName === parameterName);
             if (!task) {
                 throw new Error(`Could not find task for {${parameterName}}`);
             }
-            return task.name || normalizeTo_camelCase('task-' + titleToName(task.title));
+            return MERMAID_PREFIX + (task.name || normalizeTo_camelCase('task-' + titleToName(task.title)));
         };
+        const inputAndIntermediateParametersMermaid = pipelineJson.tasks
+            .flatMap(({ title, dependentParameterNames, resultingParameterName }) => [
+            `${parameterNameToTaskName(resultingParameterName)}("${title}")`,
+            ...dependentParameterNames.map((dependentParameterName) => `${parameterNameToTaskName(dependentParameterName)}--"{${dependentParameterName}}"-->${parameterNameToTaskName(resultingParameterName)}`),
+        ])
+            .join('\n');
+        const outputParametersMermaid = pipelineJson.parameters
+            .filter(({ isOutput }) => isOutput)
+            .map(({ name }) => `${parameterNameToTaskName(name)}--"{${name}}"-->${MERMAID_OUTPUT_NAME}`)
+            .join('\n');
+        const linksMermaid = pipelineJson.tasks
+            .map((task) => {
+            const link = linkTask(task);
+            if (link === null) {
+                return '';
+            }
+            const { href, title } = link;
+            const taskName = parameterNameToTaskName(task.resultingParameterName);
+            return `click ${taskName} href "${href}" "${title}";`;
+        })
+            .filter((line) => line !== '')
+            .join('\n');
+        const interactionPointsMermaid = Object.entries({
+            [MERMAID_INPUT_NAME]: 'Input',
+            [MERMAID_OUTPUT_NAME]: 'Output',
+            [MERMAID_RESERVED_NAME]: 'Other',
+            [MERMAID_KNOWLEDGE_NAME]: 'Knowledge',
+        })
+            .filter(([MERMAID_NAME]) => (inputAndIntermediateParametersMermaid + outputParametersMermaid).includes(MERMAID_NAME))
+            .map(([MERMAID_NAME, title]) => `${MERMAID_NAME}((${title})):::${MERMAID_NAME}`)
+            .join('\n');
         const promptbookMermaid = spaceTrim$1.spaceTrim((block) => `
 
             %% 🔮 Tip: Open this on GitHub or in the VSCode website to see the Mermaid graph visually
@@ -674,37 +1047,27 @@
             flowchart LR
               subgraph "${pipelineJson.title}"
 
+                  %% Basic configuration
                   direction TB
 
-                  input((Input)):::input
-                  ${block(pipelineJson.tasks
-        .flatMap(({ title, dependentParameterNames, resultingParameterName }) => [
-        `${parameterNameToTaskName(resultingParameterName)}("${title}")`,
-        ...dependentParameterNames.map((dependentParameterName) => `${parameterNameToTaskName(dependentParameterName)}--"{${dependentParameterName}}"-->${parameterNameToTaskName(resultingParameterName)}`),
-    ])
-        .join('\n'))}
-
-                  ${block(pipelineJson.parameters
-        .filter(({ isOutput }) => isOutput)
-        .map(({ name }) => `${parameterNameToTaskName(name)}--"{${name}}"-->output`)
-        .join('\n'))}
-                  output((Output)):::output
-
-                  ${block(pipelineJson.tasks
-        .map((task) => {
-        const link = linkTask(task);
-        if (link === null) {
-            return '';
-        }
-        const { href, title } = link;
-        const taskName = parameterNameToTaskName(task.resultingParameterName);
-        return `click ${taskName} href "${href}" "${title}";`;
-    })
-        .filter((line) => line !== '')
-        .join('\n'))}
-
-                  classDef input color: grey;
-                  classDef output color: grey;
+                  %% Interaction points from pipeline to outside
+                  ${block(interactionPointsMermaid)}
+
+                  %% Input and intermediate parameters
+                  ${block(inputAndIntermediateParametersMermaid)}
+
+
+                  %% Output parameters
+                  ${block(outputParametersMermaid)}
+
+                  %% Links
+                  ${block(linksMermaid)}
+
+                  %% Styles
+                  classDef ${MERMAID_INPUT_NAME} color: grey;
+                  classDef ${MERMAID_OUTPUT_NAME} color: grey;
+                  classDef ${MERMAID_RESERVED_NAME} color: grey;
+                  classDef ${MERMAID_KNOWLEDGE_NAME} color: grey;
 
               end;
 
@@ -763,7 +1126,7 @@
     }
 
     /**
-     * This error indicates that the pipeline collection cannot be propperly loaded
+     * This error indicates that the pipeline collection cannot be properly loaded
      *
      * @public exported from `@promptbook/core`
      */
@@ -784,774 +1147,444 @@
         constructor(message) {
             super(message);
             this.name = 'EnvironmentMismatchError';
-            Object.setPrototypeOf(this, EnvironmentMismatchError.prototype);
-        }
-    }
-
-    /**
-     * This error occurs when some expectation is not met in the execution of the pipeline
-     *
-     * @public exported from `@promptbook/core`
-     * Note: Do not throw this error, its reserved for `checkExpectations` and `createPipelineExecutor` and public ONLY to be serializable through remote server
-     * Note: Always thrown in `checkExpectations` and catched in `createPipelineExecutor` and rethrown as `PipelineExecutionError`
-     * Note: This is a kindof subtype of PipelineExecutionError
-     */
-    class ExpectError extends Error {
-        constructor(message) {
-            super(message);
-            this.name = 'ExpectError';
-            Object.setPrototypeOf(this, ExpectError.prototype);
-        }
-    }
-
-    /**
-     * This error indicates that the promptbook can not retrieve knowledge from external sources
-     *
-     * @public exported from `@promptbook/core`
-     */
-    class KnowledgeScrapeError extends Error {
-        constructor(message) {
-            super(message);
-            this.name = 'KnowledgeScrapeError';
-            Object.setPrototypeOf(this, KnowledgeScrapeError.prototype);
-        }
-    }
-
-    /**
-     * This error type indicates that some limit was reached
-     *
-     * @public exported from `@promptbook/core`
-     */
-    class LimitReachedError extends Error {
-        constructor(message) {
-            super(message);
-            this.name = 'LimitReachedError';
-            Object.setPrototypeOf(this, LimitReachedError.prototype);
-        }
-    }
-
-    /**
-     * This error type indicates that some tools are missing for pipeline execution or preparation
-     *
-     * @public exported from `@promptbook/core`
-     */
-    class MissingToolsError extends Error {
-        constructor(message) {
-            super(spaceTrim$1.spaceTrim((block) => `
-                    ${block(message)}
-
-                    Note: You have probbably forgot to provide some tools for pipeline execution or preparation
-
-                `));
-            this.name = 'MissingToolsError';
-            Object.setPrototypeOf(this, MissingToolsError.prototype);
-        }
-    }
-
-    /**
-     * This error indicates that promptbook not found in the collection
-     *
-     * @public exported from `@promptbook/core`
-     */
-    class NotFoundError extends Error {
-        constructor(message) {
-            super(message);
-            this.name = 'NotFoundError';
-            Object.setPrototypeOf(this, NotFoundError.prototype);
-        }
-    }
-
-    /**
-     * This error type indicates that some part of the code is not implemented yet
-     *
-     * @public exported from `@promptbook/core`
-     */
-    class NotYetImplementedError extends Error {
-        constructor(message) {
-            super(spaceTrim$1.spaceTrim((block) => `
-                    ${block(message)}
-
-                    Note: This feature is not implemented yet but it will be soon.
-
-                    If you want speed up the implementation or just read more, look here:
-                    https://github.com/webgptorg/promptbook
-
-                    Or contact us on pavol@ptbk.io
-
-                `));
-            this.name = 'NotYetImplementedError';
-            Object.setPrototypeOf(this, NotYetImplementedError.prototype);
-        }
-    }
-
-    /**
-     * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
-     *
-     * @public exported from `@promptbook/core`
-     */
-    class ParseError extends Error {
-        constructor(message) {
-            super(message);
-            this.name = 'ParseError';
-            Object.setPrototypeOf(this, ParseError.prototype);
-        }
-    }
-    /**
-     * TODO: Maybe split `ParseError` and `ApplyError`
-     */
-
-    /**
-     * Generates random token
-     *
-     * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
-     *
-     * @private internal helper function
-     * @returns secure random token
-     */
-    function $randomToken(randomness) {
-        return crypto.randomBytes(randomness).toString('hex');
-    }
-    /**
-     * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
-     */
-
-    /**
-     * This error indicates errors during the execution of the pipeline
-     *
-     * @public exported from `@promptbook/core`
-     */
-    class PipelineExecutionError extends Error {
-        constructor(message) {
-            // Added id parameter
-            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   */)}`;
-            Object.setPrototypeOf(this, PipelineExecutionError.prototype);
+            Object.setPrototypeOf(this, EnvironmentMismatchError.prototype);
         }
     }
-    /**
-     * TODO: [🧠][🌂] Add id to all errors
-     */
 
     /**
-     * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
+     * This error occurs when some expectation is not met in the execution of the pipeline
      *
      * @public exported from `@promptbook/core`
+     * Note: Do not throw this error, its reserved for `checkExpectations` and `createPipelineExecutor` and public ONLY to be serializable through remote server
+     * Note: Always thrown in `checkExpectations` and catched in `createPipelineExecutor` and rethrown as `PipelineExecutionError`
+     * Note: This is a kindof subtype of PipelineExecutionError
      */
-    class PipelineLogicError extends Error {
+    class ExpectError extends Error {
         constructor(message) {
             super(message);
-            this.name = 'PipelineLogicError';
-            Object.setPrototypeOf(this, PipelineLogicError.prototype);
+            this.name = 'ExpectError';
+            Object.setPrototypeOf(this, ExpectError.prototype);
         }
     }
 
     /**
-     * This error indicates errors in referencing promptbooks between each other
+     * This error indicates that the promptbook can not retrieve knowledge from external sources
      *
      * @public exported from `@promptbook/core`
      */
-    class PipelineUrlError extends Error {
+    class KnowledgeScrapeError extends Error {
         constructor(message) {
             super(message);
-            this.name = 'PipelineUrlError';
-            Object.setPrototypeOf(this, PipelineUrlError.prototype);
+            this.name = 'KnowledgeScrapeError';
+            Object.setPrototypeOf(this, KnowledgeScrapeError.prototype);
         }
     }
 
     /**
-     * Error thrown when a fetch request fails
+     * This error type indicates that some limit was reached
      *
      * @public exported from `@promptbook/core`
      */
-    class PromptbookFetchError extends Error {
+    class LimitReachedError extends Error {
         constructor(message) {
             super(message);
-            this.name = 'PromptbookFetchError';
-            Object.setPrototypeOf(this, PromptbookFetchError.prototype);
+            this.name = 'LimitReachedError';
+            Object.setPrototypeOf(this, LimitReachedError.prototype);
         }
     }
 
     /**
-     * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
+     * This error type indicates that some tools are missing for pipeline execution or preparation
      *
      * @public exported from `@promptbook/core`
      */
-    class WrappedError extends Error {
-        constructor(whatWasThrown) {
-            const tag = `[🤮]`;
-            console.error(tag, whatWasThrown);
-            super(spaceTrim$1.spaceTrim(`
-                Non-Error object was thrown
+    class MissingToolsError extends Error {
+        constructor(message) {
+            super(spaceTrim$1.spaceTrim((block) => `
+                    ${block(message)}
 
-                Note: Look for ${tag} in the console for more details
-                Please report issue on ${ADMIN_EMAIL}
-            `));
-            this.name = 'WrappedError';
-            Object.setPrototypeOf(this, WrappedError.prototype);
+                    Note: You have probably forgot to provide some tools for pipeline execution or preparation
+
+                `));
+            this.name = 'MissingToolsError';
+            Object.setPrototypeOf(this, MissingToolsError.prototype);
         }
     }
 
     /**
-     * Index of all custom errors
+     * This error indicates that promptbook not found in the collection
      *
      * @public exported from `@promptbook/core`
      */
-    const PROMPTBOOK_ERRORS = {
-        AbstractFormatError,
-        CsvFormatError,
-        CollectionError,
-        EnvironmentMismatchError,
-        ExpectError,
-        KnowledgeScrapeError,
-        LimitReachedError,
-        MissingToolsError,
-        NotFoundError,
-        NotYetImplementedError,
-        ParseError,
-        PipelineExecutionError,
-        PipelineLogicError,
-        PipelineUrlError,
-        AuthenticationError,
-        PromptbookFetchError,
-        UnexpectedError,
-        WrappedError,
-        // TODO: [🪑]> VersionMismatchError,
-    };
-    /**
-     * Index of all javascript errors
-     *
-     * @private for internal usage
-     */
-    const COMMON_JAVASCRIPT_ERRORS = {
-        Error,
-        EvalError,
-        RangeError,
-        ReferenceError,
-        SyntaxError,
-        TypeError,
-        URIError,
-        AggregateError,
-        /*
-      Note: Not widely supported
-      > InternalError,
-      > ModuleError,
-      > HeapError,
-      > WebAssemblyCompileError,
-      > WebAssemblyRuntimeError,
-      */
-    };
-    /**
-     * Index of all errors
-     *
-     * @private for internal usage
-     */
-    const ALL_ERRORS = {
-        ...PROMPTBOOK_ERRORS,
-        ...COMMON_JAVASCRIPT_ERRORS,
-    };
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
-
-    /**
-     * Deserializes the error object
-     *
-     * @public exported from `@promptbook/utils`
-     */
-    function deserializeError(error) {
-        const { name, stack, id } = error; // Added id
-        let { message } = error;
-        let ErrorClass = ALL_ERRORS[error.name];
-        if (ErrorClass === undefined) {
-            ErrorClass = Error;
-            message = `${name}: ${message}`;
-        }
-        if (stack !== undefined && stack !== '') {
-            message = spaceTrim__default["default"]((block) => `
-                ${block(message)}
-
-                Original stack trace:
-                ${block(stack || '')}
-            `);
+    class NotFoundError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = 'NotFoundError';
+            Object.setPrototypeOf(this, NotFoundError.prototype);
         }
-        const deserializedError = new ErrorClass(message);
-        deserializedError.id = id; // Assign id to the error object
-        return deserializedError;
     }
 
     /**
-     * Serializes an error into a [🚉] JSON-serializable object
+     * This error type indicates that some part of the code is not implemented yet
      *
-     * @public exported from `@promptbook/utils`
+     * @public exported from `@promptbook/core`
      */
-    function serializeError(error) {
-        const { name, message, stack } = error;
-        const { id } = error;
-        if (!Object.keys(ALL_ERRORS).includes(name)) {
-            console.error(spaceTrim__default["default"]((block) => `
-
-                    Cannot serialize error with name "${name}"
+    class NotYetImplementedError extends Error {
+        constructor(message) {
+            super(spaceTrim$1.spaceTrim((block) => `
+                    ${block(message)}
 
-                    Authors of Promptbook probably forgot to add this error into the list of errors:
-                    https://github.com/webgptorg/promptbook/blob/main/src/errors/0-index.ts
+                    Note: This feature is not implemented yet but it will be soon.
 
+                    If you want speed up the implementation or just read more, look here:
+                    https://github.com/webgptorg/promptbook
 
-                    ${block(stack || message)}
+                    Or contact us on pavol@ptbk.io
 
                 `));
+            this.name = 'NotYetImplementedError';
+            Object.setPrototypeOf(this, NotYetImplementedError.prototype);
         }
-        return {
-            name: name,
-            message,
-            stack,
-            id, // Include id in the serialized object
-        };
     }
 
     /**
-     * Async version of Array.forEach
+     * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
      *
-     * @param array - Array to iterate over
-     * @param options - Options for the function
-     * @param callbackfunction - Function to call for each item
-     * @public exported from `@promptbook/utils`
-     * @deprecated [🪂] Use queues instead
+     * @public exported from `@promptbook/core`
      */
-    async function forEachAsync(array, options, callbackfunction) {
-        const { maxParallelCount = Infinity } = options;
-        let index = 0;
-        let runningTasks = [];
-        const tasks = [];
-        for (const item of array) {
-            const currentIndex = index++;
-            const task = callbackfunction(item, currentIndex, array);
-            tasks.push(task);
-            runningTasks.push(task);
-            /* not await */ Promise.resolve(task).then(() => {
-                runningTasks = runningTasks.filter((t) => t !== task);
-            });
-            if (maxParallelCount < runningTasks.length) {
-                await Promise.race(runningTasks);
-            }
+    class ParseError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = 'ParseError';
+            Object.setPrototypeOf(this, ParseError.prototype);
         }
-        await Promise.all(tasks);
     }
+    /**
+     * TODO: Maybe split `ParseError` and `ApplyError`
+     */
 
     /**
-     * Helper used in catch blocks to assert that the error is an instance of `Error`
+     * Generates random token
      *
-     * @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
+     * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
      *
-     * @private within the repository
+     * @private internal helper function
+     * @returns secure random token
      */
-    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);
+    function $randomToken(randomness) {
+        return crypto.randomBytes(randomness).toString('hex');
     }
+    /**
+     * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
+     */
 
     /**
-     * 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
+     * This error indicates errors during the execution of the pipeline
      *
-     * @public exported from `@promptbook/utils`
+     * @public exported from `@promptbook/core`
      */
-    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;
+    class PipelineExecutionError extends Error {
+        constructor(message) {
+            // Added id parameter
+            super(message);
+            this.name = 'PipelineExecutionError';
+            // TODO: [🐙] DRY - Maybe $randomId
+            this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid similar char conflicts   */)}`;
+            Object.setPrototypeOf(this, PipelineExecutionError.prototype);
         }
     }
+    /**
+     * TODO: [🧠][🌂] Add id to all errors
+     */
 
     /**
-     * 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
+     * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
      *
-     * @public exported from `@promptbook/utils`
+     * @public exported from `@promptbook/core`
      */
-    function isValidJsonString(value /* <- [👨‍⚖️] */) {
-        try {
-            JSON.parse(value);
-            return true;
-        }
-        catch (error) {
-            assertsError(error);
-            if (error.message.includes('Unexpected token')) {
-                return false;
-            }
-            return false;
+    class PipelineLogicError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = 'PipelineLogicError';
+            Object.setPrototypeOf(this, PipelineLogicError.prototype);
         }
     }
 
     /**
-     * Converts a JavaScript Object Notation (JSON) string into an object.
-     *
-     * Note: This is wrapper around `JSON.parse()` with better error and type handling
+     * This error indicates errors in referencing promptbooks between each other
      *
-     * @public exported from `@promptbook/utils`
+     * @public exported from `@promptbook/core`
      */
-    function jsonParse(value) {
-        if (value === undefined) {
-            throw new Error(`Can not parse JSON from undefined value.`);
-        }
-        else if (typeof value !== 'string') {
-            console.error('Can not parse JSON from non-string value.', { text: value });
-            throw new Error(spaceTrim__default["default"](`
-                    Can not parse JSON from non-string value.
-
-                    The value type: ${typeof value}
-                    See more in console.
-                `));
-        }
-        try {
-            return JSON.parse(value);
-        }
-        catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
-            throw new Error(spaceTrim__default["default"]((block) => `
-                    ${block(error.message)}
-            
-                    The JSON text:
-                    ${block(value)}
-                `));
+    class PipelineUrlError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = 'PipelineUrlError';
+            Object.setPrototypeOf(this, PipelineUrlError.prototype);
         }
     }
-    /**
-     * TODO: !!!! Use in Promptbook.studio
-     */
 
     /**
-     * Function to check if a string is valid XML
-     *
-     * @param value
-     * @returns True if the string is a valid XML string, false otherwise
+     * Error thrown when a fetch request fails
      *
-     * @public exported from `@promptbook/utils`
+     * @public exported from `@promptbook/core`
      */
-    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;
+    class PromptbookFetchError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = 'PromptbookFetchError';
+            Object.setPrototypeOf(this, PromptbookFetchError.prototype);
         }
     }
 
     /**
-     * Orders JSON object by keys
+     * Index of all custom errors
      *
-     * @returns The same type of object as the input re-ordered
-     * @public exported from `@promptbook/utils`
+     * @public exported from `@promptbook/core`
      */
-    function orderJson(options) {
-        const { value, order } = options;
-        const orderedValue = {
-            ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
-            ...value,
-        };
-        return orderedValue;
-    }
-
+    const PROMPTBOOK_ERRORS = {
+        AbstractFormatError,
+        CsvFormatError,
+        CollectionError,
+        EnvironmentMismatchError,
+        ExpectError,
+        KnowledgeScrapeError,
+        LimitReachedError,
+        MissingToolsError,
+        NotFoundError,
+        NotYetImplementedError,
+        ParseError,
+        PipelineExecutionError,
+        PipelineLogicError,
+        PipelineUrlError,
+        AuthenticationError,
+        PromptbookFetchError,
+        UnexpectedError,
+        WrappedError,
+        // TODO: [🪑]> VersionMismatchError,
+    };
     /**
-     * Freezes the given object and all its nested objects recursively
+     * Index of all javascript errors
      *
-     * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
-     * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
+     * @private for internal usage
+     */
+    const COMMON_JAVASCRIPT_ERRORS = {
+        Error,
+        EvalError,
+        RangeError,
+        ReferenceError,
+        SyntaxError,
+        TypeError,
+        URIError,
+        AggregateError,
+        /*
+      Note: Not widely supported
+      > InternalError,
+      > ModuleError,
+      > HeapError,
+      > WebAssemblyCompileError,
+      > WebAssemblyRuntimeError,
+      */
+    };
+    /**
+     * Index of all errors
      *
-     * @returns The same object as the input, but deeply frozen
-     * @public exported from `@promptbook/utils`
+     * @private for internal usage
      */
-    function $deepFreeze(objectValue) {
-        if (Array.isArray(objectValue)) {
-            return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
-        }
-        const propertyNames = Object.getOwnPropertyNames(objectValue);
-        for (const propertyName of propertyNames) {
-            const value = objectValue[propertyName];
-            if (value && typeof value === 'object') {
-                $deepFreeze(value);
-            }
-        }
-        Object.freeze(objectValue);
-        return objectValue;
-    }
+    const ALL_ERRORS = {
+        ...PROMPTBOOK_ERRORS,
+        ...COMMON_JAVASCRIPT_ERRORS,
+    };
     /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
+     * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
     /**
-     * Checks if the value is [🚉] serializable as JSON
-     * If not, throws an UnexpectedError with a rich error message and tracking
-     *
-     * - Almost all primitives are serializable BUT:
-     * - `undefined` is not serializable
-     * - `NaN` is not serializable
-     * - Objects and arrays are serializable if all their properties are serializable
-     * - Functions are not serializable
-     * - Circular references are not serializable
-     * - `Date` objects are not serializable
-     * - `Map` and `Set` objects are not serializable
-     * - `RegExp` objects are not serializable
-     * - `Error` objects are not serializable
-     * - `Symbol` objects are not serializable
-     * - And much more...
+     * Deserializes the error object
      *
-     * @throws UnexpectedError if the value is not serializable as JSON
      * @public exported from `@promptbook/utils`
      */
-    function checkSerializableAsJson(options) {
-        const { value, name, message } = options;
-        if (value === undefined) {
-            throw new UnexpectedError(`${name} is undefined`);
-        }
-        else if (value === null) {
-            return;
-        }
-        else if (typeof value === 'boolean') {
-            return;
-        }
-        else if (typeof value === 'number' && !isNaN(value)) {
-            return;
-        }
-        else if (typeof value === 'string') {
-            return;
-        }
-        else if (typeof value === 'symbol') {
-            throw new UnexpectedError(`${name} is symbol`);
-        }
-        else if (typeof value === 'function') {
-            throw new UnexpectedError(`${name} is function`);
-        }
-        else if (typeof value === 'object' && Array.isArray(value)) {
-            for (let i = 0; i < value.length; i++) {
-                checkSerializableAsJson({ name: `${name}[${i}]`, value: value[i], message });
-            }
+    function deserializeError(error) {
+        const { name, stack, id } = error; // Added id
+        let { message } = error;
+        let ErrorClass = ALL_ERRORS[error.name];
+        if (ErrorClass === undefined) {
+            ErrorClass = Error;
+            message = `${name}: ${message}`;
         }
-        else if (typeof value === 'object') {
-            if (value instanceof Date) {
-                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                        \`${name}\` is Date
-
-                        Use \`string_date_iso8601\` instead
+        if (stack !== undefined && stack !== '') {
+            message = spaceTrim__default["default"]((block) => `
+                ${block(message)}
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
-                    `));
-            }
-            else if (value instanceof Map) {
-                throw new UnexpectedError(`${name} is Map`);
-            }
-            else if (value instanceof Set) {
-                throw new UnexpectedError(`${name} is Set`);
-            }
-            else if (value instanceof RegExp) {
-                throw new UnexpectedError(`${name} is RegExp`);
-            }
-            else if (value instanceof Error) {
-                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                        \`${name}\` is unserialized Error
+                Original stack trace:
+                ${block(stack || '')}
+            `);
+        }
+        const deserializedError = new ErrorClass(message);
+        deserializedError.id = id; // Assign id to the error object
+        return deserializedError;
+    }
 
-                        Use function \`serializeError\`
+    /**
+     * Serializes an error into a [🚉] JSON-serializable object
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    function serializeError(error) {
+        const { name, message, stack } = error;
+        const { id } = error;
+        if (!Object.keys(ALL_ERRORS).includes(name)) {
+            console.error(spaceTrim__default["default"]((block) => `
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
+                    Cannot serialize error with name "${name}"
 
-                    `));
-            }
-            else {
-                for (const [subName, subValue] of Object.entries(value)) {
-                    if (subValue === undefined) {
-                        // Note: undefined in object is serializable - it is just omited
-                        continue;
-                    }
-                    checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
-                }
-                try {
-                    JSON.stringify(value); // <- TODO: [0]
-                }
-                catch (error) {
-                    assertsError(error);
-                    throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                            \`${name}\` is not serializable
+                    Authors of Promptbook probably forgot to add this error into the list of errors:
+                    https://github.com/webgptorg/promptbook/blob/main/src/errors/0-index.ts
 
-                            ${block(error.stack || error.message)}
 
-                            Additional message for \`${name}\`:
-                            ${block(message || '(nothing)')}
-                        `));
-                }
-                /*
-                TODO: [0] Is there some more elegant way to check circular references?
-                const seen = new Set();
-                const stack = [{ value }];
-                while (stack.length > 0) {
-                    const { value } = stack.pop()!;
-                    if (typeof value === 'object' && value !== null) {
-                        if (seen.has(value)) {
-                            throw new UnexpectedError(`${name} has circular reference`);
-                        }
-                        seen.add(value);
-                        if (Array.isArray(value)) {
-                            stack.push(...value.map((value) => ({ value })));
-                        } else {
-                            stack.push(...Object.values(value).map((value) => ({ value })));
-                        }
-                    }
-                }
-                */
-                return;
-            }
-        }
-        else {
-            throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                    \`${name}\` is unknown type
+                    ${block(stack || message)}
 
-                    Additional message for \`${name}\`:
-                    ${block(message || '(nothing)')}
                 `));
         }
+        return {
+            name: name,
+            message,
+            stack,
+            id, // Include id in the serialized object
+        };
     }
-    /**
-     * TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
-     * TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
-     * Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
-     */
 
     /**
-     * @@@
+     * Async version of Array.forEach
      *
+     * @param array - Array to iterate over
+     * @param options - Options for the function
+     * @param callbackfunction - Function to call for each item
      * @public exported from `@promptbook/utils`
+     * @deprecated [🪂] Use queues instead
      */
-    function deepClone(objectValue) {
-        return JSON.parse(JSON.stringify(objectValue));
-        /*
-        TODO: [🧠] Is there a better implementation?
-        > const propertyNames = Object.getOwnPropertyNames(objectValue);
-        > for (const propertyName of propertyNames) {
-        >     const value = (objectValue as really_any)[propertyName];
-        >     if (value && typeof value === 'object') {
-        >         deepClone(value);
-        >     }
-        > }
-        > return Object.assign({}, objectValue);
-        */
+    async function forEachAsync(array, options, callbackfunction) {
+        const { maxParallelCount = Infinity } = options;
+        let index = 0;
+        let runningTasks = [];
+        const tasks = [];
+        for (const item of array) {
+            const currentIndex = index++;
+            const task = callbackfunction(item, currentIndex, array);
+            tasks.push(task);
+            runningTasks.push(task);
+            /* not await */ Promise.resolve(task).then(() => {
+                runningTasks = runningTasks.filter((t) => t !== task);
+            });
+            if (maxParallelCount < runningTasks.length) {
+                await Promise.race(runningTasks);
+            }
+        }
+        await Promise.all(tasks);
     }
-    /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
-     */
 
     /**
-     * Utility to export a JSON object from a function
-     *
-     * 1) Checks if the value is serializable as JSON
-     * 2) Makes a deep clone of the object
-     * 2) Orders the object properties
-     * 2) Deeply freezes the cloned object
+     * Function to check if a string is valid CSV
      *
-     * Note: This function does not mutates the given object
+     * @param value The string to check
+     * @returns `true` if the string is a valid CSV string, false otherwise
      *
-     * @returns The same type of object as the input but read-only and re-ordered
      * @public exported from `@promptbook/utils`
      */
-    function exportJson(options) {
-        const { name, value, order, message } = options;
-        checkSerializableAsJson({ name, value, message });
-        const orderedValue = 
-        // TODO: Fix error "Type instantiation is excessively deep and possibly infinite."
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        order === undefined
-            ? deepClone(value)
-            : orderJson({
-                value: value,
-                // <- Note: checkSerializableAsJson asserts that the value is serializable as JSON
-                order: order,
-            });
-        $deepFreeze(orderedValue);
-        return orderedValue;
+    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;
+        }
     }
-    /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
-     */
 
     /**
-     * Nonce which is used for replacing things in strings
+     * Function isValidJsonString will tell you if the string is valid JSON or not
      *
-     * @private within the repository
-     */
-    const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
-    /**
-     * @@@
+     * @param value The string to check
+     * @returns `true` if the string is a valid JSON string, false otherwise
      *
-     * @private within the repository
+     * @public exported from `@promptbook/utils`
      */
-    const RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
+    function isValidJsonString(value /* <- [👨‍⚖️] */) {
+        try {
+            JSON.parse(value);
+            return true;
+        }
+        catch (error) {
+            assertsError(error);
+            if (error.message.includes('Unexpected token')) {
+                return false;
+            }
+            return false;
+        }
+    }
+
     /**
-     * @@@
+     * Converts a JavaScript Object Notation (JSON) string into an object.
      *
-     * @private within the repository
-     */
-    const RESERVED_PARAMETER_RESTRICTED = 'RESTRICTED-' + REPLACING_NONCE;
-    /**
-     * The names of the parameters that are reserved for special purposes
+     * Note: This is wrapper around `JSON.parse()` with better error and type handling
      *
-     * @public exported from `@promptbook/core`
+     * @public exported from `@promptbook/utils`
      */
-    exportJson({
-        name: 'RESERVED_PARAMETER_NAMES',
-        message: `The names of the parameters that are reserved for special purposes`,
-        value: [
-            'content',
-            'context',
-            'knowledge',
-            'examples',
-            'modelName',
-            'currentDate',
-            // <- TODO: list here all command names
-            // <- TODO: Add more like 'date', 'modelName',...
-            // <- TODO: Add [emoji] + instructions ACRY when adding new reserved parameter
-        ],
-    });
+    function jsonParse(value) {
+        if (value === undefined) {
+            throw new Error(`Can not parse JSON from undefined value.`);
+        }
+        else if (typeof value !== 'string') {
+            console.error('Can not parse JSON from non-string value.', { text: value });
+            throw new Error(spaceTrim__default["default"](`
+                    Can not parse JSON from non-string value.
+
+                    The value type: ${typeof value}
+                    See more in console.
+                `));
+        }
+        try {
+            return JSON.parse(value);
+        }
+        catch (error) {
+            if (!(error instanceof Error)) {
+                throw error;
+            }
+            throw new Error(spaceTrim__default["default"]((block) => `
+                    ${block(error.message)}
+
+                    The JSON text:
+                    ${block(value)}
+                `));
+        }
+    }
+
     /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
+     * 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;
+        }
+    }
 
     /**
      * Format either small or big number
@@ -1988,7 +2021,7 @@
         PAGES: countPages,
     };
     /**
-     * TODO: [🧠][🤠] This should be probbably as part of `TextFormatDefinition`
+     * TODO: [🧠][🤠] This should be probably as part of `TextFormatParser`
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
@@ -2011,10 +2044,10 @@
     }
 
     /**
-     * @@@
+     * 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`
@@ -2099,11 +2132,11 @@
     }
 
     /**
-     * @@@
+     * Converts a name string into a URI-compatible format.
      *
-     * @param name @@@
-     * @returns @@@
-     * @example @@@
+     * @param name The string to be converted to a URI-compatible format.
+     * @returns A URI-compatible string derived from the input name.
+     * @example 'Hello World' -> 'hello-world'
      * @public exported from `@promptbook/utils`
      */
     function nameToUriPart(name) {
@@ -2117,11 +2150,11 @@
     }
 
     /**
-     * @@@
+     * Converts a given name into URI-compatible parts.
      *
-     * @param name @@@
-     * @returns @@@
-     * @example @@@
+     * @param name The name to be converted into URI parts.
+     * @returns An array of URI-compatible parts derived from the name.
+     * @example 'Example Name' -> ['example', 'name']
      * @public exported from `@promptbook/utils`
      */
     function nameToUriParts(name) {
@@ -2143,10 +2176,10 @@
     }
 
     /**
-     * @@@
+     * 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`
@@ -2198,7 +2231,7 @@
      */
 
     /**
-     * @@@
+     * Searches set of keywords for a specific keyword
      *
      * @param haystack
      * @param needle
@@ -2213,6 +2246,9 @@
         }
         return true;
     }
+    /**
+     * TODO: Rename to `isKeywordInKeywords`
+     */
 
     /**
      * Adds suffix to the URL
@@ -2324,9 +2360,9 @@
     /**
      * Removes quotes from a string
      *
-     * Tip: This is very usefull for post-processing of the result of the LLM model
+     * Tip: This is very useful for post-processing of the result of the LLM model
      * Note: This function removes only the same quotes from the beginning and the end of the string
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `removeQuotes` which removes only bounding quotes
      * - `unwrapResult` which removes whole introduce sentence
      *
@@ -2338,22 +2374,23 @@
         if (text.startsWith('"') && text.endsWith('"')) {
             return text.slice(1, -1);
         }
-        if (text.startsWith('\'') && text.endsWith('\'')) {
+        if (text.startsWith("'") && text.endsWith("'")) {
             return text.slice(1, -1);
         }
         return text;
     }
 
     /**
-     * @@@
+     * Creates a deep clone of a PipelineJson object, copying all properties explicitly.
      *
-     * Note: It is usefull @@@
+     * Note: It is useful for ensuring that modifications to the returned pipeline do not affect the original.
      *
-     * @param pipeline
+     * @param pipeline The pipeline to clone.
+     * @returns A new PipelineJson object with the same properties as the input.
      * @public exported from `@promptbook/utils`
      */
     function clonePipeline(pipeline) {
-        // Note: Not using spread operator (...) because @@@
+        // Note: Not using spread operator (...) because it does not deeply copy nested objects and may miss non-enumerable properties.
         const { pipelineUrl, sourceFile, title, bookVersion, description, formfactorName, parameters, tasks, knowledgeSources, knowledgePieces, personas, preparations, sources, } = pipeline;
         return {
             pipelineUrl,
@@ -2502,7 +2539,7 @@
     /**
      * Function trimCodeBlock will trim starting and ending code block from the string if it is present.
      *
-     * Note: This is usefull for post-processing of the result of the chat LLM model
+     * Note: This is useful for post-processing of the result of the chat LLM model
      *       when the model wraps the result in the (markdown) code block.
      *
      * @public exported from `@promptbook/utils`
@@ -2521,7 +2558,7 @@
     /**
      * Function trimEndOfCodeBlock will remove ending code block from the string if it is present.
      *
-     * Note: This is usefull for post-processing of the result of the completion LLM model
+     * Note: This is useful for post-processing of the result of the completion LLM model
      *       if you want to start code block in the prompt but you don't want to end it in the result.
      *
      * @public exported from `@promptbook/utils`
@@ -2536,9 +2573,9 @@
     /**
      * Removes quotes and optional introduce text from a string
      *
-     * Tip: This is very usefull for post-processing of the result of the LLM model
+     * Tip: This is very useful for post-processing of the result of the LLM model
      * Note: This function trims the text and removes whole introduce sentence if it is present
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `removeQuotes` which removes only bounding quotes
      * - `unwrapResult` which removes whole introduce sentence
      *
@@ -2639,10 +2676,10 @@
      */
 
     /**
-     * @@@
+     * Checks if the given value is a valid JavaScript identifier name.
      *
-     * @param javascriptName @@@
-     * @returns @@@
+     * @param javascriptName The value to check for JavaScript identifier validity.
+     * @returns `true` if the value is a valid JavaScript name, false otherwise.
      * @public exported from `@promptbook/utils`
      */
     function isValidJavascriptName(javascriptName) {
@@ -2655,7 +2692,7 @@
     /**
      * Tests if given string is valid semantic version
      *
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `isValidSemanticVersion` which tests any semantic version
      * - `isValidPromptbookVersion` *(this one)* which tests just Promptbook versions
      *
@@ -2677,7 +2714,7 @@
      *
      * @see https://www.npmjs.com/package/promptbook?activeTab=versions
      * Note: When you are using for example promptbook 2.0.0 and there already is promptbook 3.0.0 it don`t know about it.
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `isValidSemanticVersion` which tests any semantic version
      * - `isValidPromptbookVersion` *(this one)* which tests just Promptbook versions
      *
@@ -2697,7 +2734,7 @@
     /**
      * Checks if an URL is reserved for private networks or localhost.
      *
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `isUrlOnPrivateNetwork` which tests full URL
      * - `isHostnameOnPrivateNetwork` *(this one)* which tests just hostname
      *
@@ -2730,7 +2767,7 @@
     /**
      * Checks if an IP address or hostname is reserved for private networks or localhost.
      *
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `isUrlOnPrivateNetwork` *(this one)* which tests full URL
      * - `isHostnameOnPrivateNetwork` which tests just hostname
      *
@@ -2748,7 +2785,7 @@
     /**
      * Tests if given string is valid pipeline URL URL.
      *
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `isValidUrl` which tests any URL
      * - `isValidPipelineUrl` *(this one)* which tests just pipeline URL
      *