@promptbook/node 0.92.0-9 → 0.92.0

package/umd/index.umd.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('fs/promises'), require('path'), require('spacetrim'), require('jszip'), require('prettier'), require('prettier/parser-html'), require('rxjs'), require('crypto'), require('waitasecond'), require('papaparse'), require('crypto-js/enc-hex'), require('crypto-js/sha256'), require('crypto-js'), require('mime-types'), require('child_process'), require('dotenv')) :
-    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'fs/promises', 'path', 'spacetrim', 'jszip', 'prettier', 'prettier/parser-html', 'rxjs', 'crypto', 'waitasecond', 'papaparse', 'crypto-js/enc-hex', 'crypto-js/sha256', 'crypto-js', 'mime-types', 'child_process', 'dotenv'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-node"] = {}, global.colors, global.promises, global.path, global.spaceTrim, global.JSZip, global.prettier, global.parserHtml, global.rxjs, global.crypto, global.waitasecond, global.papaparse, global.hexEncoder, global.sha256, global.cryptoJs, global.mimeTypes, global.child_process, global.dotenv));
-})(this, (function (exports, colors, promises, path, spaceTrim, JSZip, prettier, parserHtml, rxjs, crypto, waitasecond, papaparse, hexEncoder, sha256, cryptoJs, mimeTypes, child_process, dotenv) { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('fs/promises'), require('path'), require('spacetrim'), require('jszip'), require('prettier'), require('prettier/parser-html'), require('crypto'), require('rxjs'), require('waitasecond'), require('papaparse'), require('crypto-js/enc-hex'), require('crypto-js/sha256'), require('crypto-js'), require('mime-types'), require('child_process'), require('dotenv')) :
+    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'fs/promises', 'path', 'spacetrim', 'jszip', 'prettier', 'prettier/parser-html', 'crypto', 'rxjs', 'waitasecond', 'papaparse', 'crypto-js/enc-hex', 'crypto-js/sha256', 'crypto-js', 'mime-types', 'child_process', 'dotenv'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-node"] = {}, global.colors, global.promises, global.path, global.spaceTrim, global.JSZip, global.prettier, global.parserHtml, global.crypto, global.rxjs, global.waitasecond, global.papaparse, global.hexEncoder, global.sha256, global.cryptoJs, global.mimeTypes, global.child_process, global.dotenv));
+})(this, (function (exports, colors, promises, path, spaceTrim, JSZip, prettier, parserHtml, crypto, rxjs, waitasecond, papaparse, hexEncoder, sha256, cryptoJs, mimeTypes, child_process, dotenv) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -46,7 +46,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-9';
+    const PROMPTBOOK_ENGINE_VERSION = '0.92.0';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -56,7 +56,7 @@
      * Returns the same value that is passed as argument.
      * No side effects.
      *
-     * Note: It can be usefull for:
+     * Note: It can be useful for:
      *
      * 1) Leveling indentation
      * 2) Putting always-true or always-false conditions without getting eslint errors
@@ -117,6 +117,21 @@
      * @public exported from `@promptbook/core`
      */
     const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
+    /**
+     * Threshold value that determines when a dataset is considered "big"
+     * and may require special handling or optimizations
+     *
+     * For example, when error occurs in one item of the big dataset, it will not fail the whole pipeline
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const BIG_DATASET_TRESHOLD = 50;
+    /**
+     * Placeholder text used to represent a placeholder value of failed operation
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const FAILED_VALUE_PLACEHOLDER = '!?';
     // <- TODO: [🧠] Better system for generator warnings - not always "code" and "by `@promptbook/cli`"
     /**
      * The maximum number of iterations for a loops
@@ -211,7 +226,7 @@
     const DEFAULT_PIPELINE_COLLECTION_BASE_FILENAME = `index`;
     // <- TODO: [🧜‍♂️]
     /**
-     * @@@
+     * Default settings for parsing and generating CSV files in Promptbook.
      *
      * @public exported from `@promptbook/core`
      */
@@ -222,19 +237,19 @@
         skipEmptyLines: true,
     });
     /**
-     * @@@
+     * Controls whether verbose logging is enabled by default throughout the application.
      *
      * @public exported from `@promptbook/core`
      */
     let DEFAULT_IS_VERBOSE = false;
     /**
-     * @@@
+     * Controls whether auto-installation of dependencies is enabled by default.
      *
      * @public exported from `@promptbook/core`
      */
     const DEFAULT_IS_AUTO_INSTALLED = false;
     /**
-     * @@@
+     * Indicates whether pipeline logic validation is enabled. When true, the pipeline logic is checked for consistency.
      *
      * @private within the repository
      */
@@ -302,7 +317,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)}
@@ -344,15 +359,12 @@
             }
             throw new Error(spaceTrim__default["default"]((block) => `
                     ${block(error.message)}
-            
+
                     The JSON text:
                     ${block(value)}
                 `));
         }
     }
-    /**
-     * TODO: !!!! Use in Promptbook.studio
-     */
 
     /**
      * Orders JSON object by keys
@@ -583,8 +595,12 @@
      */
 
     /**
-     * @@@
+     * 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) {
@@ -666,13 +682,13 @@
      */
     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
      */
@@ -733,7 +749,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
      *
@@ -755,7 +771,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
      *
@@ -776,7 +792,7 @@
      * Tests if given string is valid URL.
      *
      * Note: Dataurl are considered perfectly valid.
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `isValidUrl` which tests any URL
      * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
      *
@@ -804,7 +820,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
      *
@@ -901,7 +917,7 @@
                     ${block(pipelineIdentification)}
                 `));
         }
-        // TODO: [🧠] Maybe do here some propper JSON-schema / ZOD checking
+        // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
         if (!Array.isArray(pipeline.parameters)) {
             // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
             throw new ParseError(spaceTrim.spaceTrim((block) => `
@@ -912,7 +928,7 @@
                     ${block(pipelineIdentification)}
                 `));
         }
-        // TODO: [🧠] Maybe do here some propper JSON-schema / ZOD checking
+        // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
         if (!Array.isArray(pipeline.tasks)) {
             // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
             throw new ParseError(spaceTrim.spaceTrim((block) => `
@@ -1223,7 +1239,7 @@
      * 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
+     * @returns `true` if the string is a valid JSON string, false otherwise
      *
      * @public exported from `@promptbook/utils`
      */
@@ -1335,7 +1351,7 @@
         if (bookVersion !== `undefined`) {
             commands.push(`BOOK VERSION ${bookVersion}`);
         }
-        // TODO: [main] !!5 This increases size of the bundle and is probbably not necessary
+        // TODO: [main] !!5 This increases size of the bundle and is probably not necessary
         pipelineString = prettifyMarkdown(pipelineString);
         for (const parameter of parameters.filter(({ isInput }) => isInput)) {
             commands.push(`INPUT PARAMETER ${taskParameterJsonToString(parameter)}`);
@@ -1545,7 +1561,7 @@
         /**
          * Constructs a pipeline collection from pipelines
          *
-         * @param pipelines @@@
+         * @param pipelines Array of pipeline JSON objects to include in the collection
          *
          * Note: During the construction logic of all pipelines are validated
          * Note: It is not recommended to use this constructor directly, use `createCollectionFromJson` *(or other variant)* instead
@@ -1659,7 +1675,7 @@
             super(spaceTrim.spaceTrim((block) => `
                     ${block(message)}
 
-                    Note: You have probbably forgot to provide some tools for pipeline execution or preparation
+                    Note: You have probably forgot to provide some tools for pipeline execution or preparation
 
                 `));
             this.name = 'MissingToolsError';
@@ -1675,15 +1691,18 @@
      * @public exported from `@promptbook/core`
      */
     function isPipelinePrepared(pipeline) {
-        // Note: Ignoring `pipeline.preparations` @@@
-        // Note: Ignoring `pipeline.knowledgePieces` @@@
+        // Note: Ignoring `pipeline.preparations`
+        // Note: Ignoring `pipeline.knowledgePieces`
         if (pipeline.title === undefined || pipeline.title === '' || pipeline.title === DEFAULT_BOOK_TITLE) {
+            // console.log('Pipeline is not prepared because title is undefined or empty', pipeline);
             return false;
         }
         if (!pipeline.personas.every((persona) => persona.modelsRequirements !== undefined)) {
+            // console.log('Pipeline is not prepared because personas are not prepared', pipeline.personas);
             return false;
         }
         if (!pipeline.knowledgeSources.every((knowledgeSource) => knowledgeSource.preparationIds !== undefined)) {
+            //console.log('Pipeline is not prepared because knowledge sources are not prepared', pipeline.knowledgeSources);
             return false;
         }
         /*
@@ -1704,70 +1723,6 @@
      *     - [♨] Are tasks prepared
      */
 
-    /**
-     * 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
-     */
-
-    /**
-     * Recursively converts JSON strings to JSON objects
-
-     * @public exported from `@promptbook/utils`
-     */
-    function jsonStringsToJsons(object) {
-        if (object === null) {
-            return object;
-        }
-        if (Array.isArray(object)) {
-            return object.map(jsonStringsToJsons);
-        }
-        if (typeof object !== 'object') {
-            return object;
-        }
-        const newObject = { ...object };
-        for (const [key, value] of Object.entries(object)) {
-            if (typeof value === 'string' && isValidJsonString(value)) {
-                newObject[key] = jsonParse(value);
-            }
-            else {
-                newObject[key] = jsonStringsToJsons(value);
-            }
-        }
-        return newObject;
-    }
-    /**
-     * TODO: Type the return type correctly
-     */
-
-    /**
-     * 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);
-        }
-    }
-    /**
-     * TODO: [🧠][🌂] Add id to all errors
-     */
-
     /**
      * This error indicates problems parsing the format value
      *
@@ -1812,7 +1767,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`
      */
@@ -1902,6 +1857,40 @@
         }
     }
 
+    /**
+     * 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 similar char conflicts   */)}`;
+            Object.setPrototypeOf(this, PipelineExecutionError.prototype);
+        }
+    }
+    /**
+     * TODO: [🧠][🌂] Add id to all errors
+     */
+
     /**
      * Error thrown when a fetch request fails
      *
@@ -1977,6 +1966,65 @@
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
+    /**
+     * 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) => `
+
+                    Cannot serialize error with name "${name}"
+
+                    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(stack || message)}
+
+                `));
+        }
+        return {
+            name: name,
+            message,
+            stack,
+            id, // Include id in the serialized object
+        };
+    }
+
+    /**
+     * Recursively converts JSON strings to JSON objects
+
+     * @public exported from `@promptbook/utils`
+     */
+    function jsonStringsToJsons(object) {
+        if (object === null) {
+            return object;
+        }
+        if (Array.isArray(object)) {
+            return object.map(jsonStringsToJsons);
+        }
+        if (typeof object !== 'object') {
+            return object;
+        }
+        const newObject = { ...object };
+        for (const [key, value] of Object.entries(object)) {
+            if (typeof value === 'string' && isValidJsonString(value)) {
+                newObject[key] = jsonParse(value);
+            }
+            else {
+                newObject[key] = jsonStringsToJsons(value);
+            }
+        }
+        return newObject;
+    }
+    /**
+     * TODO: Type the return type correctly
+     */
+
     /**
      * Deserializes the error object
      *
@@ -2051,8 +2099,9 @@
      */
     function createTask(options) {
         const { taskType, taskProcessCallback } = options;
+        let { title } = options;
         // TODO: [🐙] DRY
-        const taskId = `${taskType.toLowerCase().substring(0, 4)}-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid simmilar char conflicts   */)}`;
+        const taskId = `${taskType.toLowerCase().substring(0, 4)}-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid similar char conflicts   */)}`;
         let status = 'RUNNING';
         const createdAt = new Date();
         let updatedAt = createdAt;
@@ -2062,6 +2111,10 @@
         const partialResultSubject = new rxjs.Subject();
         // <- Note: Not using `BehaviorSubject` because on error we can't access the last value
         const finalResultPromise = /* not await */ taskProcessCallback((newOngoingResult) => {
+            if (newOngoingResult.title) {
+                title = newOngoingResult.title;
+            }
+            updatedAt = new Date();
             Object.assign(currentValue, newOngoingResult);
             // <- TODO: assign deep
             partialResultSubject.next(newOngoingResult);
@@ -2107,17 +2160,24 @@
         return {
             taskType,
             taskId,
+            get promptbookVersion() {
+                return PROMPTBOOK_ENGINE_VERSION;
+            },
+            get title() {
+                return title;
+                // <- Note: [1] These must be getters to allow changing the value in the future
+            },
             get status() {
                 return status;
-                // <- Note: [1] Theese must be getters to allow changing the value in the future
+                // <- Note: [1] --||--
             },
             get createdAt() {
                 return createdAt;
-                // <- Note: [1]
+                // <- Note: [1] --||--
             },
             get updatedAt() {
                 return updatedAt;
-                // <- Note: [1]
+                // <- Note: [1] --||--
             },
             asPromise,
             asObservable() {
@@ -2125,15 +2185,15 @@
             },
             get errors() {
                 return errors;
-                // <- Note: [1]
+                // <- Note: [1] --||--
             },
             get warnings() {
                 return warnings;
-                // <- Note: [1]
+                // <- Note: [1] --||--
             },
             get currentValue() {
                 return currentValue;
-                // <- Note: [1]
+                // <- Note: [1] --||--
             },
         };
     }
@@ -2143,33 +2203,72 @@
      */
 
     /**
-     * Serializes an error into a [🚉] JSON-serializable object
+     * Represents the uncertain value
      *
-     * @public exported from `@promptbook/utils`
+     * @public exported from `@promptbook/core`
+     */
+    const ZERO_VALUE = $deepFreeze({ value: 0 });
+    /**
+     * Represents the uncertain value
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const UNCERTAIN_ZERO_VALUE = $deepFreeze({ value: 0, isUncertain: true });
+    /**
+     * Represents the usage with no resources consumed
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const ZERO_USAGE = $deepFreeze({
+        price: ZERO_VALUE,
+        input: {
+            tokensCount: ZERO_VALUE,
+            charactersCount: ZERO_VALUE,
+            wordsCount: ZERO_VALUE,
+            sentencesCount: ZERO_VALUE,
+            linesCount: ZERO_VALUE,
+            paragraphsCount: ZERO_VALUE,
+            pagesCount: ZERO_VALUE,
+        },
+        output: {
+            tokensCount: ZERO_VALUE,
+            charactersCount: ZERO_VALUE,
+            wordsCount: ZERO_VALUE,
+            sentencesCount: ZERO_VALUE,
+            linesCount: ZERO_VALUE,
+            paragraphsCount: ZERO_VALUE,
+            pagesCount: ZERO_VALUE,
+        },
+    });
+    /**
+     * Represents the usage with unknown resources consumed
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const UNCERTAIN_USAGE = $deepFreeze({
+        price: UNCERTAIN_ZERO_VALUE,
+        input: {
+            tokensCount: UNCERTAIN_ZERO_VALUE,
+            charactersCount: UNCERTAIN_ZERO_VALUE,
+            wordsCount: UNCERTAIN_ZERO_VALUE,
+            sentencesCount: UNCERTAIN_ZERO_VALUE,
+            linesCount: UNCERTAIN_ZERO_VALUE,
+            paragraphsCount: UNCERTAIN_ZERO_VALUE,
+            pagesCount: UNCERTAIN_ZERO_VALUE,
+        },
+        output: {
+            tokensCount: UNCERTAIN_ZERO_VALUE,
+            charactersCount: UNCERTAIN_ZERO_VALUE,
+            wordsCount: UNCERTAIN_ZERO_VALUE,
+            sentencesCount: UNCERTAIN_ZERO_VALUE,
+            linesCount: UNCERTAIN_ZERO_VALUE,
+            paragraphsCount: UNCERTAIN_ZERO_VALUE,
+            pagesCount: UNCERTAIN_ZERO_VALUE,
+        },
+    });
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
      */
-    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}"
-
-                    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(stack || message)}
-
-                `));
-        }
-        return {
-            name: name,
-            message,
-            stack,
-            id, // Include id in the serialized object
-        };
-    }
 
     /**
      * Format either small or big number
@@ -2252,74 +2351,6 @@
         }
     }
 
-    /**
-     * Represents the uncertain value
-     *
-     * @public exported from `@promptbook/core`
-     */
-    const ZERO_VALUE = $deepFreeze({ value: 0 });
-    /**
-     * Represents the uncertain value
-     *
-     * @public exported from `@promptbook/core`
-     */
-    const UNCERTAIN_ZERO_VALUE = $deepFreeze({ value: 0, isUncertain: true });
-    /**
-     * Represents the usage with no resources consumed
-     *
-     * @public exported from `@promptbook/core`
-     */
-    const ZERO_USAGE = $deepFreeze({
-        price: ZERO_VALUE,
-        input: {
-            tokensCount: ZERO_VALUE,
-            charactersCount: ZERO_VALUE,
-            wordsCount: ZERO_VALUE,
-            sentencesCount: ZERO_VALUE,
-            linesCount: ZERO_VALUE,
-            paragraphsCount: ZERO_VALUE,
-            pagesCount: ZERO_VALUE,
-        },
-        output: {
-            tokensCount: ZERO_VALUE,
-            charactersCount: ZERO_VALUE,
-            wordsCount: ZERO_VALUE,
-            sentencesCount: ZERO_VALUE,
-            linesCount: ZERO_VALUE,
-            paragraphsCount: ZERO_VALUE,
-            pagesCount: ZERO_VALUE,
-        },
-    });
-    /**
-     * Represents the usage with unknown resources consumed
-     *
-     * @public exported from `@promptbook/core`
-     */
-    $deepFreeze({
-        price: UNCERTAIN_ZERO_VALUE,
-        input: {
-            tokensCount: UNCERTAIN_ZERO_VALUE,
-            charactersCount: UNCERTAIN_ZERO_VALUE,
-            wordsCount: UNCERTAIN_ZERO_VALUE,
-            sentencesCount: UNCERTAIN_ZERO_VALUE,
-            linesCount: UNCERTAIN_ZERO_VALUE,
-            paragraphsCount: UNCERTAIN_ZERO_VALUE,
-            pagesCount: UNCERTAIN_ZERO_VALUE,
-        },
-        output: {
-            tokensCount: UNCERTAIN_ZERO_VALUE,
-            charactersCount: UNCERTAIN_ZERO_VALUE,
-            wordsCount: UNCERTAIN_ZERO_VALUE,
-            sentencesCount: UNCERTAIN_ZERO_VALUE,
-            linesCount: UNCERTAIN_ZERO_VALUE,
-            paragraphsCount: UNCERTAIN_ZERO_VALUE,
-            pagesCount: UNCERTAIN_ZERO_VALUE,
-        },
-    });
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
-
     /**
      * Function `addUsage` will add multiple usages into one
      *
@@ -2528,7 +2559,7 @@
     }
 
     /**
-     * @@@
+     * Contains configuration options for parsing and generating CSV files, such as delimiters and quoting rules.
      *
      * @public exported from `@promptbook/core`
      */
@@ -2537,11 +2568,29 @@
         // encoding: 'utf-8',
     });
 
+    /**
+     * Converts a CSV string into an object
+     *
+     * Note: This is wrapper around `papaparse.parse()` with better autohealing
+     *
+     * @private - for now until `@promptbook/csv` is released
+     */
+    function csvParse(value /* <- TODO: string_csv */, settings, schema /* <- TODO: Make CSV Schemas */) {
+        settings = { ...settings, ...MANDATORY_CSV_SETTINGS };
+        // Note: Autoheal invalid '\n' characters
+        if (settings.newline && !settings.newline.includes('\r') && value.includes('\r')) {
+            console.warn('CSV string contains carriage return characters, but in the CSV settings the `newline` setting does not include them. Autohealing the CSV string.');
+            value = value.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+        }
+        const csv = papaparse.parse(value, settings);
+        return csv;
+    }
+
     /**
      * 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
+     * @returns `true` if the string is a valid CSV string, false otherwise
      *
      * @public exported from `@promptbook/utils`
      */
@@ -2565,7 +2614,7 @@
      * @public exported from `@promptbook/core`
      *                          <- TODO: [🏢] Export from package `@promptbook/csv`
      */
-    const CsvFormatDefinition = {
+    const CsvFormatParser = {
         formatName: 'CSV',
         aliases: ['SPREADSHEET', 'TABLE'],
         isValid(value, settings, schema) {
@@ -2577,12 +2626,12 @@
         heal(value, settings, schema) {
             throw new Error('Not implemented');
         },
-        subvalueDefinitions: [
+        subvalueParsers: [
             {
                 subvalueName: 'ROW',
-                async mapValues(value, outputParameterName, settings, mapCallback) {
-                    // TODO: [👨🏾‍🤝‍👨🏼] DRY csv parsing
-                    const csv = papaparse.parse(value, { ...settings, ...MANDATORY_CSV_SETTINGS });
+                async mapValues(options) {
+                    const { value, outputParameterName, settings, mapCallback, onProgress } = options;
+                    const csv = csvParse(value, settings);
                     if (csv.errors.length !== 0) {
                         throw new CsvFormatError(spaceTrim__default["default"]((block) => `
                                 CSV parsing error
@@ -2597,23 +2646,37 @@
                                 ${block(value)}
                             `));
                     }
-                    const mappedData = await Promise.all(csv.data.map(async (row, index) => {
+                    const mappedData = [];
+                    const length = csv.data.length;
+                    for (let index = 0; index < length; index++) {
+                        const row = csv.data[index];
                         if (row[outputParameterName]) {
                             throw new CsvFormatError(`Can not overwrite existing column "${outputParameterName}" in CSV row`);
                         }
-                        return {
+                        const mappedRow = {
                             ...row,
-                            [outputParameterName]: await mapCallback(row, index),
+                            [outputParameterName]: await mapCallback(row, index, length),
                         };
-                    }));
+                        mappedData.push(mappedRow);
+                        if (onProgress) {
+                            // Note: Report the CSV with all rows mapped so far
+                            /*
+                            // TODO: [🛕] Report progress with all the rows including the pending ones
+                              const progressData = mappedData.map((row, i) =>
+                                i > index ? { ...row, [outputParameterName]: PENDING_VALUE_PLACEHOLDER } : row,
+                            );
+                            */
+                            await onProgress(papaparse.unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS }));
+                        }
+                    }
                     return papaparse.unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS });
                 },
             },
             {
                 subvalueName: 'CELL',
-                async mapValues(value, outputParameterName, settings, mapCallback) {
-                    // TODO: [👨🏾‍🤝‍👨🏼] DRY csv parsing
-                    const csv = papaparse.parse(value, { ...settings, ...MANDATORY_CSV_SETTINGS });
+                async mapValues(options) {
+                    const { value, settings, mapCallback, onProgress } = options;
+                    const csv = csvParse(value, settings);
                     if (csv.errors.length !== 0) {
                         throw new CsvFormatError(spaceTrim__default["default"]((block) => `
                                 CSV parsing error
@@ -2629,9 +2692,9 @@
                             `));
                     }
                     const mappedData = await Promise.all(csv.data.map(async (row, rowIndex) => {
-                        return /* not await */ Promise.all(Object.entries(row).map(async ([key, value], columnIndex) => {
+                        return /* not await */ Promise.all(Object.entries(row).map(async ([key, value], columnIndex, array) => {
                             const index = rowIndex * Object.keys(row).length + columnIndex;
-                            return /* not await */ mapCallback({ [key]: value }, index);
+                            return /* not await */ mapCallback({ [key]: value }, index, array.length);
                         }));
                     }));
                     return papaparse.unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS });
@@ -2640,10 +2703,10 @@
         ],
     };
     /**
-     * TODO: [🍓] In `CsvFormatDefinition` implement simple `isValid`
-     * TODO: [🍓] In `CsvFormatDefinition` implement partial `canBeValid`
-     * TODO: [🍓] In `CsvFormatDefinition` implement `heal
-     * TODO: [🍓] In `CsvFormatDefinition` implement `subvalueDefinitions`
+     * TODO: [🍓] In `CsvFormatParser` implement simple `isValid`
+     * TODO: [🍓] In `CsvFormatParser` implement partial `canBeValid`
+     * TODO: [🍓] In `CsvFormatParser` implement `heal
+     * TODO: [🍓] In `CsvFormatParser` implement `subvalueParsers`
      * TODO: [🏢] Allow to expect something inside CSV objects and other formats
      */
 
@@ -2652,7 +2715,7 @@
      *
      * @private still in development [🏢]
      */
-    const JsonFormatDefinition = {
+    const JsonFormatParser = {
         formatName: 'JSON',
         mimeType: 'application/json',
         isValid(value, settings, schema) {
@@ -2664,28 +2727,28 @@
         heal(value, settings, schema) {
             throw new Error('Not implemented');
         },
-        subvalueDefinitions: [],
+        subvalueParsers: [],
     };
     /**
-     * TODO: [🧠] Maybe propper instance of object
+     * TODO: [🧠] Maybe proper instance of object
      * TODO: [0] Make string_serialized_json
      * TODO: [1] Make type for JSON Settings and Schema
      * TODO: [🧠] What to use for validating JSONs - JSON Schema, ZoD, typescript types/interfaces,...?
-     * TODO: [🍓] In `JsonFormatDefinition` implement simple `isValid`
-     * TODO: [🍓] In `JsonFormatDefinition` implement partial `canBeValid`
-     * TODO: [🍓] In `JsonFormatDefinition` implement `heal
-     * TODO: [🍓] In `JsonFormatDefinition` implement `subvalueDefinitions`
+     * TODO: [🍓] In `JsonFormatParser` implement simple `isValid`
+     * TODO: [🍓] In `JsonFormatParser` implement partial `canBeValid`
+     * TODO: [🍓] In `JsonFormatParser` implement `heal
+     * TODO: [🍓] In `JsonFormatParser` implement `subvalueParsers`
      * TODO: [🏢] Allow to expect something inside JSON objects and other formats
      */
 
     /**
      * Definition for any text - this will be always valid
      *
-     * Note: This is not useful for validation, but for splitting and mapping with `subvalueDefinitions`
+     * Note: This is not useful for validation, but for splitting and mapping with `subvalueParsers`
      *
      * @public exported from `@promptbook/core`
      */
-    const TextFormatDefinition = {
+    const TextFormatParser = {
         formatName: 'TEXT',
         isValid(value) {
             return typeof value === 'string';
@@ -2694,19 +2757,20 @@
             return typeof partialValue === 'string';
         },
         heal() {
-            throw new UnexpectedError('It does not make sense to call `TextFormatDefinition.heal`');
+            throw new UnexpectedError('It does not make sense to call `TextFormatParser.heal`');
         },
-        subvalueDefinitions: [
+        subvalueParsers: [
             {
                 subvalueName: 'LINE',
-                async mapValues(value, outputParameterName, settings, mapCallback) {
+                async mapValues(options) {
+                    const { value, mapCallback, onProgress } = options;
                     const lines = value.split('\n');
-                    const mappedLines = await Promise.all(lines.map((lineContent, lineNumber) => 
+                    const mappedLines = await Promise.all(lines.map((lineContent, lineNumber, array) => 
                     // TODO: [🧠] Maybe option to skip empty line
                     /* not await */ mapCallback({
                         lineContent,
                         // TODO: [🧠] Maybe also put here `lineNumber`
-                    }, lineNumber)));
+                    }, lineNumber, array.length)));
                     return mappedLines.join('\n');
                 },
             },
@@ -2716,10 +2780,10 @@
     /**
      * TODO: [1] Make type for XML Text and Schema
      * TODO: [🧠][🤠] Here should be all words, characters, lines, paragraphs, pages available as subvalues
-     * TODO: [🍓] In `TextFormatDefinition` implement simple `isValid`
-     * TODO: [🍓] In `TextFormatDefinition` implement partial `canBeValid`
-     * TODO: [🍓] In `TextFormatDefinition` implement `heal
-     * TODO: [🍓] In `TextFormatDefinition` implement `subvalueDefinitions`
+     * TODO: [🍓] In `TextFormatParser` implement simple `isValid`
+     * TODO: [🍓] In `TextFormatParser` implement partial `canBeValid`
+     * TODO: [🍓] In `TextFormatParser` implement `heal
+     * TODO: [🍓] In `TextFormatParser` implement `subvalueParsers`
      * TODO: [🏢] Allow to expect something inside each item of list and other formats
      */
 
@@ -2727,7 +2791,7 @@
      * Function to check if a string is valid XML
      *
      * @param value
-     * @returns True if the string is a valid XML string, false otherwise
+     * @returns `true` if the string is a valid XML string, false otherwise
      *
      * @public exported from `@promptbook/utils`
      */
@@ -2752,7 +2816,7 @@
      *
      * @private still in development [🏢]
      */
-    const XmlFormatDefinition = {
+    const XmlFormatParser = {
         formatName: 'XML',
         mimeType: 'application/xml',
         isValid(value, settings, schema) {
@@ -2764,17 +2828,17 @@
         heal(value, settings, schema) {
             throw new Error('Not implemented');
         },
-        subvalueDefinitions: [],
+        subvalueParsers: [],
     };
     /**
-     * TODO: [🧠] Maybe propper instance of object
+     * TODO: [🧠] Maybe proper instance of object
      * TODO: [0] Make string_serialized_xml
      * TODO: [1] Make type for XML Settings and Schema
      * TODO: [🧠] What to use for validating XMLs - XSD,...
-     * TODO: [🍓] In `XmlFormatDefinition` implement simple `isValid`
-     * TODO: [🍓] In `XmlFormatDefinition` implement partial `canBeValid`
-     * TODO: [🍓] In `XmlFormatDefinition` implement `heal
-     * TODO: [🍓] In `XmlFormatDefinition` implement `subvalueDefinitions`
+     * TODO: [🍓] In `XmlFormatParser` implement simple `isValid`
+     * TODO: [🍓] In `XmlFormatParser` implement partial `canBeValid`
+     * TODO: [🍓] In `XmlFormatParser` implement `heal
+     * TODO: [🍓] In `XmlFormatParser` implement `subvalueParsers`
      * TODO: [🏢] Allow to expect something inside XML and other formats
      */
 
@@ -2783,24 +2847,19 @@
      *
      * @private internal index of `...` <- TODO [🏢]
      */
-    const FORMAT_DEFINITIONS = [
-        JsonFormatDefinition,
-        XmlFormatDefinition,
-        TextFormatDefinition,
-        CsvFormatDefinition,
-    ];
+    const FORMAT_DEFINITIONS = [JsonFormatParser, XmlFormatParser, TextFormatParser, CsvFormatParser];
     /**
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
     /**
-     * Maps available parameters to expected parameters
+     * Maps available parameters to expected parameters for a pipeline task.
      *
      * The strategy is:
-     * 1) @@@
-     * 2) @@@
+     * 1) First, match parameters by name where both available and expected.
+     * 2) Then, if there are unmatched expected and available parameters, map them by order.
      *
-     * @throws {PipelineExecutionError} @@@
+     * @throws {PipelineExecutionError} If the number of unmatched expected and available parameters does not match, or mapping is ambiguous.
      * @private within the repository used in `createPipelineExecutor`
      */
     function mapAvailableToExpectedParameters(options) {
@@ -2823,7 +2882,7 @@
             else if (!availableParametersNames.has(parameterName) && expectedParameterNames.has(parameterName)) ;
         }
         if (expectedParameterNames.size === 0) {
-            // Note: [👨‍👨‍👧] Now we can freeze `mappedParameters` to prevent @@@
+            // Note: [👨‍👨‍👧] Now we can freeze `mappedParameters` to prevent accidental modifications after mapping
             Object.freeze(mappedParameters);
             return mappedParameters;
         }
@@ -2854,7 +2913,7 @@
         for (let i = 0; i < expectedParameterNames.size; i++) {
             mappedParameters[expectedParameterNamesArray[i]] = availableParameters[availableParametersNamesArray[i]];
         }
-        // Note: [👨‍👨‍👧] Now we can freeze `mappedParameters` to prevent @@@
+        // Note: [👨‍👨‍👧] Now we can freeze `mappedParameters` to prevent accidental modifications after mapping
         Object.freeze(mappedParameters);
         return mappedParameters;
     }
@@ -2876,29 +2935,40 @@
             return 'Multiple LLM Providers';
         }
         get description() {
-            return this.llmExecutionTools.map(({ title }, index) => `${index + 1}) \`${title}\``).join('\n');
+            const innerModelsTitlesAndDescriptions = this.llmExecutionTools
+                .map(({ title, description }, index) => {
+                const headLine = `${index + 1}) \`${title}\``;
+                if (description === undefined) {
+                    return headLine;
+                }
+                return spaceTrim__default["default"]((block) => `
+                        ${headLine}
+                        
+                          ${ /* <- Note: Indenting the description: */block(description)}
+                    `);
+            })
+                .join('\n\n');
+            return spaceTrim__default["default"]((block) => `
+                Multiple LLM Providers:
+
+                ${block(innerModelsTitlesAndDescriptions)}
+            `);
         }
         /**
          * Check the configuration of all execution tools
          */
         async checkConfiguration() {
-            // TODO: Maybe do it in parallel
-            for (const llmExecutionTools of this.llmExecutionTools) {
-                await llmExecutionTools.checkConfiguration();
-            }
+            // Note: Run checks in parallel
+            await Promise.all(this.llmExecutionTools.map((tools) => tools.checkConfiguration()));
         }
         /**
          * List all available models that can be used
          * This lists is a combination of all available models from all execution tools
          */
         async listModels() {
-            const availableModels = [];
-            for (const llmExecutionTools of this.llmExecutionTools) {
-                // TODO: [🪂] Obtain models in parallel
-                const models = await llmExecutionTools.listModels();
-                availableModels.push(...models);
-            }
-            return availableModels;
+            // Obtain all models in parallel and flatten
+            const modelArrays = await Promise.all(this.llmExecutionTools.map((tools) => tools.listModels()));
+            return modelArrays.flat();
         }
         /**
          * Calls the best available chat model
@@ -3054,8 +3124,8 @@
     /**
      * Extracts all code blocks from markdown.
      *
-     * Note: There are multiple simmilar function:
-     * - `extractBlock` just extracts the content of the code block which is also used as build-in function for postprocessing
+     * Note: There are multiple similar functions:
+     * - `extractBlock` just extracts the content of the code block which is also used as built-in function for postprocessing
      * - `extractJsonBlock` extracts exactly one valid JSON code block
      * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
      * - `extractAllBlocksFromMarkdown` extracts all code blocks with language of the code block
@@ -3105,7 +3175,7 @@
                 if (currentCodeBlock.content !== '') {
                     currentCodeBlock.content += '\n';
                 }
-                currentCodeBlock.content += line.split('\\`\\`\\`').join('```') /* <- TODO: Maybe make propper unescape */;
+                currentCodeBlock.content += line.split('\\`\\`\\`').join('```') /* <- TODO: Maybe make proper unescape */;
             }
         }
         if (currentCodeBlock !== null) {
@@ -3125,7 +3195,7 @@
      * - When there are multiple JSON code blocks the function throws a `ParseError`
      *
      * Note: It is not important if marked as ```json BUT if it is VALID JSON
-     * Note: There are multiple simmilar function:
+     * Note: There are multiple similar function:
      * - `extractBlock` just extracts the content of the code block which is also used as build-in function for postprocessing
      * - `extractJsonBlock` extracts exactly one valid JSON code block
      * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
@@ -3150,7 +3220,7 @@
     }
     /**
      * TODO: Add some auto-healing logic + extract YAML, JSON5, TOML, etc.
-     * TODO: [🏢] Make this logic part of `JsonFormatDefinition` or `isValidJsonString`
+     * TODO: [🏢] Make this logic part of `JsonFormatParser` or `isValidJsonString`
      */
 
     /**
@@ -3176,7 +3246,7 @@
      * Just says that the variable is not used but should be kept
      * No side effects.
      *
-     * Note: It can be usefull for:
+     * Note: It can be useful for:
      *
      * 1) Suppressing eager optimization of unused imports
      * 2) Suppressing eslint errors of unused variables in the tests
@@ -3603,10 +3673,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) {
@@ -3649,14 +3719,14 @@
         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
      */
 
     /**
      * Function checkExpectations will check if the expectations on given value are met
      *
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `checkExpectations` which throws an error if the expectations are not met
      * - `isPassingExpectations` which returns a boolean
      *
@@ -3677,13 +3747,17 @@
     }
     /**
      * TODO: [💝] Unite object for expecting amount and format
-     * TODO: [🧠][🤠] This should be part of `TextFormatDefinition`
+     * TODO: [🧠][🤠] This should be part of `TextFormatParser`
      * Note: [💝] and [🤠] are interconnected together
      */
 
     /**
-     * @@@
+     * Executes a pipeline task with multiple attempts, including joker and retry logic. Handles different task types
+     * (prompt, script, dialog, etc.), applies postprocessing, checks expectations, and updates the execution report.
+     * Throws errors if execution fails after all attempts.
      *
+     * @param options - The options for execution, including task, parameters, pipeline, and configuration.
+     * @returns The result string of the executed task.
      * @private internal utility of `createPipelineExecutor`
      */
     async function executeAttempts(options) {
@@ -3905,7 +3979,7 @@
                 if (task.format) {
                     if (task.format === 'JSON') {
                         if (!isValidJsonString($ongoingTaskResult.$resultString || '')) {
-                            // TODO: [🏢] Do more universally via `FormatDefinition`
+                            // TODO: [🏢] Do more universally via `FormatParser`
                             try {
                                 $ongoingTaskResult.$resultString = extractJsonBlock($ongoingTaskResult.$resultString || '');
                             }
@@ -4007,12 +4081,16 @@
      */
 
     /**
-     * @@@
+     * Executes a pipeline task that requires mapping or iterating over subvalues of a parameter (such as rows in a CSV).
+     * Handles format and subformat resolution, error handling, and progress reporting.
+     *
+     * @param options - Options for execution, including task details and progress callback.
+     * @returns The result of the subvalue mapping or execution attempts.
      *
      * @private internal utility of `createPipelineExecutor`
      */
     async function executeFormatSubvalues(options) {
-        const { task, jokerParameterNames, parameters, priority, csvSettings, pipelineIdentification } = options;
+        const { task, jokerParameterNames, parameters, priority, csvSettings, onProgress, pipelineIdentification } = options;
         if (task.foreach === undefined) {
             return /* not await */ executeAttempts(options);
         }
@@ -4043,16 +4121,16 @@
                     ${block(pipelineIdentification)}
                 `));
         }
-        const subvalueDefinition = formatDefinition.subvalueDefinitions.find((subvalueDefinition) => [subvalueDefinition.subvalueName, ...(subvalueDefinition.aliases || [])].includes(task.foreach.subformatName));
-        if (subvalueDefinition === undefined) {
+        const subvalueParser = formatDefinition.subvalueParsers.find((subvalueParser) => [subvalueParser.subvalueName, ...(subvalueParser.aliases || [])].includes(task.foreach.subformatName));
+        if (subvalueParser === undefined) {
             throw new UnexpectedError(
             // <- TODO: [🧠][🧐] Should be formats fixed per promptbook version or behave as plugins (=> change UnexpectedError)
             spaceTrim__default["default"]((block) => `
                     Unsupported subformat name "${task.foreach.subformatName}" for format "${task.foreach.formatName}"
 
                     Available subformat names for format "${formatDefinition.formatName}":
-                    ${block(formatDefinition.subvalueDefinitions
-            .map((subvalueDefinition) => subvalueDefinition.subvalueName)
+                    ${block(formatDefinition.subvalueParsers
+            .map((subvalueParser) => subvalueParser.subvalueName)
             .map((subvalueName) => `- ${subvalueName}`)
             .join('\n'))}
 
@@ -4064,55 +4142,85 @@
         let formatSettings;
         if (formatDefinition.formatName === 'CSV') {
             formatSettings = csvSettings;
-            // <- TODO: [🤹‍♂️] More universal, make simmilar pattern for other formats for example \n vs \r\n in text
-        }
-        const resultString = await subvalueDefinition.mapValues(parameterValue, task.foreach.outputSubparameterName, formatSettings, async (subparameters, index) => {
-            let mappedParameters;
-            // TODO: [🤹‍♂️][🪂] Limit to N concurrent executions
-            // TODO: When done [🐚] Report progress also for each subvalue here
-            try {
-                mappedParameters = mapAvailableToExpectedParameters({
-                    expectedParameters: Object.fromEntries(task.foreach.inputSubparameterNames.map((subparameterName) => [subparameterName, null])),
-                    availableParameters: subparameters,
-                });
-            }
-            catch (error) {
-                if (!(error instanceof PipelineExecutionError)) {
-                    throw error;
+            // <- TODO: [🤹‍♂️] More universal, make similar pattern for other formats for example \n vs \r\n in text
+        }
+        const resultString = await subvalueParser.mapValues({
+            value: parameterValue,
+            outputParameterName: task.foreach.outputSubparameterName,
+            settings: formatSettings,
+            onProgress(partialResultString) {
+                return onProgress(Object.freeze({
+                    [task.resultingParameterName]: partialResultString,
+                }));
+            },
+            async mapCallback(subparameters, index, length) {
+                let mappedParameters;
+                try {
+                    mappedParameters = mapAvailableToExpectedParameters({
+                        expectedParameters: Object.fromEntries(task.foreach.inputSubparameterNames.map((subparameterName) => [subparameterName, null])),
+                        availableParameters: subparameters,
+                    });
                 }
-                throw new PipelineExecutionError(spaceTrim__default["default"]((block) => `
-                        ${error.message}
+                catch (error) {
+                    if (!(error instanceof PipelineExecutionError)) {
+                        throw error;
+                    }
+                    const highLevelError = new PipelineExecutionError(spaceTrim__default["default"]((block) => `
+                            ${error.message}
 
-                        This is error in FOREACH command
-                        You have probbably passed wrong data to pipeline or wrong data was generated which are processed by FOREACH command
+                            This is error in FOREACH command when mapping ${formatDefinition.formatName} ${subvalueParser.subvalueName} data (${index + 1}/${length})
+                            You have probably passed wrong data to pipeline or wrong data was generated which are processed by FOREACH command
 
-                        ${block(pipelineIdentification)}
-                        Subparameter index: ${index}
-                    `));
-            }
-            const allSubparameters = {
-                ...parameters,
-                ...mappedParameters,
-            };
-            // Note: [👨‍👨‍👧] Now we can freeze `subparameters` because we are sure that all and only used parameters are defined and are not going to be changed
-            Object.freeze(allSubparameters);
-            const subresultString = await executeAttempts({
-                ...options,
-                priority: priority + index,
-                parameters: allSubparameters,
-                pipelineIdentification: spaceTrim__default["default"]((block) => `
-                        ${block(pipelineIdentification)}
-                        Subparameter index: ${index}
-                    `),
-            });
-            return subresultString;
+                            ${block(pipelineIdentification)}
+                        `));
+                    if (length > BIG_DATASET_TRESHOLD) {
+                        console.error(highLevelError);
+                        return FAILED_VALUE_PLACEHOLDER;
+                    }
+                    throw highLevelError;
+                }
+                const allSubparameters = {
+                    ...parameters,
+                    ...mappedParameters,
+                };
+                Object.freeze(allSubparameters);
+                try {
+                    const subresultString = await executeAttempts({
+                        ...options,
+                        priority: priority + index,
+                        parameters: allSubparameters,
+                        pipelineIdentification: spaceTrim__default["default"]((block) => `
+                            ${block(pipelineIdentification)}
+                            Subparameter index: ${index}
+                        `),
+                    });
+                    return subresultString;
+                }
+                catch (error) {
+                    if (length > BIG_DATASET_TRESHOLD) {
+                        console.error(spaceTrim__default["default"]((block) => `
+                              ${error.message}
+
+                              This is error in FOREACH command when processing ${formatDefinition.formatName} ${subvalueParser.subvalueName} data (${index + 1}/${length})
+
+                              ${block(pipelineIdentification)}
+                          `));
+                        return FAILED_VALUE_PLACEHOLDER;
+                    }
+                    throw error;
+                }
+            },
         });
         return resultString;
     }
 
     /**
-     * @@@
+     * Returns the context for a given task, typically used to provide additional information or variables
+     * required for the execution of the task within a pipeline. The context is returned as a string value
+     * that may include markdown formatting.
      *
+     * @param task - The task for which the context is being generated. This should be a deeply immutable TaskJson object.
+     * @returns The context as a string, formatted as markdown and parameter value.
      * @private internal utility of `createPipelineExecutor`
      */
     async function getContextForTask(task) {
@@ -4120,7 +4228,7 @@
     }
 
     /**
-     * @@@
+     * Retrieves example values or templates for a given task, used to guide or validate pipeline execution.
      *
      * @private internal utility of `createPipelineExecutor`
      */
@@ -4129,91 +4237,128 @@
     }
 
     /**
-     * @@@
+     * Computes the cosine similarity between two embedding vectors
+     *
+     * Note: This is helping function for RAG (retrieval-augmented generation)
+     *
+     * @param embeddingVector1
+     * @param embeddingVector2
+     * @returns Cosine similarity between the two vectors
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function computeCosineSimilarity(embeddingVector1, embeddingVector2) {
+        if (embeddingVector1.length !== embeddingVector2.length) {
+            throw new TypeError('Embedding vectors must have the same length');
+        }
+        const dotProduct = embeddingVector1.reduce((sum, value, index) => sum + value * embeddingVector2[index], 0);
+        const magnitude1 = Math.sqrt(embeddingVector1.reduce((sum, value) => sum + value * value, 0));
+        const magnitude2 = Math.sqrt(embeddingVector2.reduce((sum, value) => sum + value * value, 0));
+        return 1 - dotProduct / (magnitude1 * magnitude2);
+    }
+
+    /**
+     *
+     * @param knowledgePieces
+     * @returns
      *
-     * Here is the place where RAG (retrieval-augmented generation) happens
+     * @private internal utility of `createPipelineExecutor`
+     */
+    function knowledgePiecesToString(knowledgePieces) {
+        return knowledgePieces
+            .map((knowledgePiece) => {
+            const { content } = knowledgePiece;
+            return `- ${content}`;
+        })
+            .join('\n');
+        // <- TODO: [🧠] Some smarter aggregation of knowledge pieces, single-line vs multi-line vs mixed
+    }
+
+    /**
+     * Retrieves the most relevant knowledge pieces for a given task using embedding-based similarity search.
+     * This is where retrieval-augmented generation (RAG) is performed to enhance the task with external knowledge.
      *
      * @private internal utility of `createPipelineExecutor`
      */
     async function getKnowledgeForTask(options) {
-        const { tools, preparedPipeline, task } = options;
+        const { tools, preparedPipeline, task, parameters } = options;
         const firstKnowlegePiece = preparedPipeline.knowledgePieces[0];
         const firstKnowlegeIndex = firstKnowlegePiece === null || firstKnowlegePiece === void 0 ? void 0 : firstKnowlegePiece.index[0];
         // <- TODO: Do not use just first knowledge piece and first index to determine embedding model, use also keyword search
         if (firstKnowlegePiece === undefined || firstKnowlegeIndex === undefined) {
-            return 'No knowledge pieces found';
+            return ''; // <- Note: Np knowledge present, return empty string
         }
-        // TODO: [🚐] Make arrayable LLMs -> single LLM DRY
-        const _llms = arrayableToArray(tools.llm);
-        const llmTools = _llms.length === 1 ? _llms[0] : joinLlmExecutionTools(..._llms);
-        const taskEmbeddingPrompt = {
-            title: 'Knowledge Search',
-            modelRequirements: {
-                modelVariant: 'EMBEDDING',
-                modelName: firstKnowlegeIndex.modelName,
-            },
-            content: task.content,
-            parameters: {
-            /* !!!!!!!! */
-            },
-        };
-        const taskEmbeddingResult = await llmTools.callEmbeddingModel(taskEmbeddingPrompt);
-        const knowledgePiecesWithRelevance = preparedPipeline.knowledgePieces.map((knowledgePiece) => {
-            const { index } = knowledgePiece;
-            const knowledgePieceIndex = index.find((i) => i.modelName === firstKnowlegeIndex.modelName);
-            // <- TODO: Do not use just first knowledge piece and first index to determine embedding model
-            if (knowledgePieceIndex === undefined) {
+        try {
+            // TODO: [🚐] Make arrayable LLMs -> single LLM DRY
+            const _llms = arrayableToArray(tools.llm);
+            const llmTools = _llms.length === 1 ? _llms[0] : joinLlmExecutionTools(..._llms);
+            const taskEmbeddingPrompt = {
+                title: 'Knowledge Search',
+                modelRequirements: {
+                    modelVariant: 'EMBEDDING',
+                    modelName: firstKnowlegeIndex.modelName,
+                },
+                content: task.content,
+                parameters,
+            };
+            const taskEmbeddingResult = await llmTools.callEmbeddingModel(taskEmbeddingPrompt);
+            const knowledgePiecesWithRelevance = preparedPipeline.knowledgePieces.map((knowledgePiece) => {
+                const { index } = knowledgePiece;
+                const knowledgePieceIndex = index.find((i) => i.modelName === firstKnowlegeIndex.modelName);
+                // <- TODO: Do not use just first knowledge piece and first index to determine embedding model
+                if (knowledgePieceIndex === undefined) {
+                    return {
+                        content: knowledgePiece.content,
+                        relevance: 0,
+                    };
+                }
+                const relevance = computeCosineSimilarity(knowledgePieceIndex.position, taskEmbeddingResult.content);
                 return {
                     content: knowledgePiece.content,
-                    relevance: 0,
+                    relevance,
                 };
-            }
-            const relevance = computeCosineSimilarity(knowledgePieceIndex.position, taskEmbeddingResult.content);
-            return {
-                content: knowledgePiece.content,
-                relevance,
-            };
-        });
-        const knowledgePiecesSorted = knowledgePiecesWithRelevance.sort((a, b) => a.relevance - b.relevance);
-        const knowledgePiecesLimited = knowledgePiecesSorted.slice(0, 5);
-        console.log('!!! Embedding', {
-            task,
-            taskEmbeddingPrompt,
-            taskEmbeddingResult,
-            firstKnowlegePiece,
-            firstKnowlegeIndex,
-            knowledgePiecesWithRelevance,
-            knowledgePiecesSorted,
-            knowledgePiecesLimited,
-        });
-        return knowledgePiecesLimited.map(({ content }) => `- ${content}`).join('\n');
-        //                                                      <- TODO: [🧠] Some smart aggregation of knowledge pieces, single-line vs multi-line vs mixed
-    }
-    // TODO: !!!!!! Annotate + to new file
-    function computeCosineSimilarity(embeddingVector1, embeddingVector2) {
-        if (embeddingVector1.length !== embeddingVector2.length) {
-            throw new TypeError('Embedding vectors must have the same length');
+            });
+            const knowledgePiecesSorted = knowledgePiecesWithRelevance.sort((a, b) => a.relevance - b.relevance);
+            const knowledgePiecesLimited = knowledgePiecesSorted.slice(0, 5);
+            /*
+            console.log('`getKnowledgeForTask` Embedding', {
+                task,
+                taskEmbeddingPrompt,
+                taskEmbeddingResult,
+                firstKnowlegePiece,
+                firstKnowlegeIndex,
+                knowledgePiecesWithRelevance,
+                knowledgePiecesSorted,
+                knowledgePiecesLimited,
+            });
+            */
+            return knowledgePiecesToString(knowledgePiecesLimited);
+        }
+        catch (error) {
+            assertsError(error);
+            console.error('Error in `getKnowledgeForTask`', error);
+            // Note: If the LLM fails, just return all knowledge pieces
+            return knowledgePiecesToString(preparedPipeline.knowledgePieces);
         }
-        const dotProduct = embeddingVector1.reduce((sum, value, index) => sum + value * embeddingVector2[index], 0);
-        const magnitude1 = Math.sqrt(embeddingVector1.reduce((sum, value) => sum + value * value, 0));
-        const magnitude2 = Math.sqrt(embeddingVector2.reduce((sum, value) => sum + value * value, 0));
-        return 1 - dotProduct / (magnitude1 * magnitude2);
     }
     /**
-     * TODO: !!!! Verify if this is working
      * TODO: [♨] Implement Better - use keyword search
      * TODO: [♨] Examples of values
      */
 
     /**
-     * @@@
+     * Retrieves all reserved parameters for a given pipeline task, including context, knowledge, examples, and metadata.
+     * Ensures all reserved parameters are defined and throws if any are missing.
+     *
+     * @param options - Options including tools, pipeline, task, and context.
+     * @returns An object containing all reserved parameters for the task.
      *
      * @private internal utility of `createPipelineExecutor`
      */
     async function getReservedParametersForTask(options) {
-        const { tools, preparedPipeline, task, pipelineIdentification } = options;
+        const { tools, preparedPipeline, task, parameters, pipelineIdentification, isVerbose } = options;
         const context = await getContextForTask(); // <- [🏍]
-        const knowledge = await getKnowledgeForTask({ tools, preparedPipeline, task });
+        const knowledge = await getKnowledgeForTask({ tools, preparedPipeline, task, parameters });
         const examples = await getExamplesForTask();
         const currentDate = new Date().toISOString(); // <- TODO: [🧠][💩] Better
         const modelName = RESERVED_PARAMETER_MISSING_VALUE;
@@ -4225,6 +4370,9 @@
             currentDate,
             modelName,
         };
+        if (isVerbose) {
+            console.info('Reserved parameters for task:', { options, reservedParameters });
+        }
         // Note: Doublecheck that ALL reserved parameters are defined:
         for (const parameterName of RESERVED_PARAMETER_NAMES) {
             if (reservedParameters[parameterName] === undefined) {
@@ -4239,23 +4387,21 @@
     }
 
     /**
-     * @@@
+     * Executes a single task within a pipeline, handling parameter validation, error checking, and progress reporting.
+     *
+     * @param options - Options for execution, including the task, pipeline, parameters, and callbacks.
+     * @returns The output parameters produced by the task.
      *
      * @private internal utility of `createPipelineExecutor`
      */
     async function executeTask(options) {
         const { currentTask, preparedPipeline, parametersToPass, tools, onProgress, $executionReport, pipelineIdentification, maxExecutionAttempts, maxParallelCount, csvSettings, isVerbose, rootDirname, cacheDirname, intermediateFilesStrategy, isAutoInstalled, isNotPreparedWarningSupressed, } = options;
         const priority = preparedPipeline.tasks.length - preparedPipeline.tasks.indexOf(currentTask);
-        await onProgress({
-            outputParameters: {
-                [currentTask.resultingParameterName]: '', // <- TODO: [🧠] What is the best value here?
-            },
-        });
         // Note: Check consistency of used and dependent parameters which was also done in `validatePipeline`, but it’s good to doublecheck
         const usedParameterNames = extractParameterNamesFromTask(currentTask);
         const dependentParameterNames = new Set(currentTask.dependentParameterNames);
         // TODO: [👩🏾‍🤝‍👩🏻] Use here `mapAvailableToExpectedParameters`
-        if (union(difference(usedParameterNames, dependentParameterNames), difference(dependentParameterNames, usedParameterNames)).size !== 0) {
+        if (difference(union(difference(usedParameterNames, dependentParameterNames), difference(dependentParameterNames, usedParameterNames)), new Set(RESERVED_PARAMETER_NAMES)).size !== 0) {
             throw new UnexpectedError(spaceTrim.spaceTrim((block) => `
                     Dependent parameters are not consistent with used parameters:
 
@@ -4273,13 +4419,16 @@
 
                 `));
         }
+        const reservedParameters = await getReservedParametersForTask({
+            tools,
+            preparedPipeline,
+            task: currentTask,
+            pipelineIdentification,
+            parameters: parametersToPass,
+            isVerbose,
+        });
         const definedParameters = Object.freeze({
-            ...(await getReservedParametersForTask({
-                tools,
-                preparedPipeline,
-                task: currentTask,
-                pipelineIdentification,
-            })),
+            ...reservedParameters,
             ...parametersToPass,
         });
         const definedParameterNames = new Set(Object.keys(definedParameters));
@@ -4324,6 +4473,7 @@
             preparedPipeline,
             tools,
             $executionReport,
+            onProgress,
             pipelineIdentification,
             maxExecutionAttempts,
             maxParallelCount,
@@ -4351,7 +4501,8 @@
      */
 
     /**
-     * @@@
+     * Filters and returns only the output parameters from the provided pipeline execution options.
+     * Adds warnings for any expected output parameters that are missing.
      *
      * @private internal utility of `createPipelineExecutor`
      */
@@ -4376,9 +4527,12 @@
     }
 
     /**
-     * @@@
+     * Executes an entire pipeline, resolving tasks in dependency order, handling errors, and reporting progress.
+     *
+     * Note: This is not a `PipelineExecutor` (which is bound to a single pipeline), but a utility function used by `createPipelineExecutor` to create a `PipelineExecutor`.
      *
-     * Note: This is not a `PipelineExecutor` (which is binded with one exact pipeline), but a utility function of `createPipelineExecutor` which creates `PipelineExecutor`
+     * @param options - Options for execution, including input parameters, pipeline, and callbacks.
+     * @returns The result of the pipeline execution, including output parameters, errors, and usage statistics.
      *
      * @private internal utility of `createPipelineExecutor`
      */
@@ -4701,10 +4855,27 @@
                 cacheDirname,
                 intermediateFilesStrategy,
                 isAutoInstalled,
+            }).catch((error) => {
+                assertsError(error);
+                return exportJson({
+                    name: 'pipelineExecutorResult',
+                    message: `Unuccessful PipelineExecutorResult, last catch`,
+                    order: [],
+                    value: {
+                        isSuccessful: false,
+                        errors: [serializeError(error)],
+                        warnings: [],
+                        usage: UNCERTAIN_USAGE,
+                        executionReport: null,
+                        outputParameters: {},
+                        preparedPipeline,
+                    },
+                });
             });
         };
         const pipelineExecutor = (inputParameters) => createTask({
             taskType: 'EXECUTION',
+            title: pipeline.title,
             taskProcessCallback(updateOngoingResult) {
                 return pipelineExecutorWithCallback(inputParameters, async (newOngoingResult) => {
                     updateOngoingResult(newOngoingResult);
@@ -4756,12 +4927,14 @@
         const spending = new rxjs.Subject();
         const proxyTools = {
             get title() {
-                // TODO: [🧠] Maybe put here some suffix
-                return llmTools.title;
+                return `${llmTools.title} (+usage)`;
+                // <- TODO: [🧈] Maybe standartize the suffix when wrapping `LlmExecutionTools` up
+                // <- TODO: [🧈][🧠] Does it make sence to suffix "(+usage)"?
             },
             get description() {
-                // TODO: [🧠] Maybe put here some suffix
-                return llmTools.description;
+                return `${llmTools.description} (+usage)`;
+                // <- TODO: [🧈] Maybe standartize the suffix when wrapping `LlmExecutionTools` up
+                // <- TODO: [🧈][🧠] Does it make sence to suffix "(+usage)"?
             },
             checkConfiguration() {
                 return /* not await */ llmTools.checkConfiguration();
@@ -4884,7 +5057,8 @@
      */
 
     /**
-     * @@@
+     * Safely retrieves the global scope object (window in browser, global in Node.js)
+     * regardless of the JavaScript environment in which the code is running
      *
      * Note: `$` is used to indicate that this function is not a pure function - it access global scope
      *
@@ -4895,10 +5069,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`
@@ -4950,10 +5124,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`
@@ -4963,11 +5137,11 @@
     }
 
     /**
-     * Register is @@@
+     * Global registry for storing and managing registered entities of a given type.
      *
      * Note: `$` is used to indicate that this function is not a pure function - it accesses and adds variables in global scope.
      *
-     * @private internal utility, exported are only signleton instances of this class
+     * @private internal utility, exported are only singleton instances of this class
      */
     class $Register {
         constructor(registerName) {
@@ -5011,10 +5185,10 @@
     }
 
     /**
-     * @@@
+     * Global registry for storing metadata about all available scrapers and converters.
      *
-     * Note: `$` is used to indicate that this interacts with the global scope
-     * @singleton Only one instance of each register is created per build, but thare can be more @@@
+     * Note: `$` is used to indicate that this interacts with the global scope.
+     * @singleton Only one instance of each register is created per build, but there can be more in different contexts (e.g., tests).
      * @public exported from `@promptbook/core`
      */
     const $scrapersMetadataRegister = new $Register('scrapers_metadata');
@@ -5023,10 +5197,11 @@
      */
 
     /**
-     * @@@
+     * Registry for all available scrapers in the system.
+     * Central point for registering and accessing different types of content scrapers.
      *
      * Note: `$` is used to indicate that this interacts with the global scope
-     * @singleton Only one instance of each register is created per build, but thare can be more @@@
+     * @singleton Only one instance of each register is created per build, but there can be more than one in different build modules
      * @public exported from `@promptbook/core`
      */
     const $scrapersRegister = new $Register('scraper_constructors');
@@ -5122,10 +5297,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`
@@ -5194,7 +5369,8 @@
      */
 
     /**
-     * @@@
+     * Converts a name to a properly formatted subfolder path for cache storage.
+     * Handles normalization and path formatting to create consistent cache directory structures.
      *
      * @private for `FileCacheStorage`
      */
@@ -5274,11 +5450,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) {
@@ -5329,7 +5505,9 @@
      */
 
     /**
-     * @@@
+     * Factory function that creates a handler for processing knowledge sources.
+     * Provides standardized processing of different types of knowledge sources
+     * across various scraper implementations.
      *
      * @public exported from `@promptbook/core`
      */
@@ -5468,7 +5646,7 @@
     }
 
     /**
-     * Prepares the knowle
+     * Prepares the knowledge pieces
      *
      * @see https://github.com/webgptorg/promptbook/discussions/41
      * @public exported from `@promptbook/core`
@@ -5564,15 +5742,18 @@
      * TODO: [🧊] In future one preparation can take data from previous preparation and save tokens and time
      *       Put `knowledgePieces` into `PrepareKnowledgeOptions`
      * TODO: [🪂] More than max things can run in parallel by acident [1,[2a,2b,_],[3a,3b,_]]
-     * TODO: [🧠][❎] Do here propper M:N mapping
+     * TODO: [🧠][❎] Do here proper M:N mapping
      *       [x] One source can make multiple pieces
      *       [ ] One piece can have multiple sources
      */
 
     /**
-     * @@@
+     * Prepares tasks by adding knowledge to the prompt and ensuring all necessary parameters are included.
      *
-     * @public exported from `@promptbook/core`
+     * @param tasks Sequence of tasks that are chained together to form a pipeline
+     * @returns A promise that resolves to the prepared tasks.
+     *
+     * @private internal utility of `preparePipeline`
      */
     async function prepareTasks(pipeline, tools, options) {
         const { maxParallelCount = DEFAULT_MAX_PARALLEL_COUNT } = options;
@@ -5610,7 +5791,7 @@
         return { tasksPrepared };
     }
     /**
-     * TODO: [😂] Adding knowledge should be convert to async high-level abstractions, simmilar thing with expectations to sync high-level abstractions
+     * TODO: [😂] Adding knowledge should be convert to async high-level abstractions, similar thing with expectations to sync high-level abstractions
      * TODO: [🧠] Add context to each task (if missing)
      * TODO: [🧠] What is better name `prepareTask` or `prepareTaskAndParameters`
      * TODO: [♨][main] !!3 Prepare index the examples and maybe tasks
@@ -5746,7 +5927,7 @@
             order: ORDER_OF_PIPELINE_JSON,
             value: {
                 ...pipeline,
-                // <- TODO: Probbably deeply clone the pipeline because `$exportJson` freezes the subobjects
+                // <- TODO: Probably deeply clone the pipeline because `$exportJson` freezes the subobjects
                 title,
                 knowledgeSources: knowledgeSourcesPrepared,
                 knowledgePieces: knowledgePiecesPrepared,
@@ -6022,7 +6203,7 @@
                 throw new ParseError(`Task section and example section must end with return statement -> {parameterName}`);
             };
             if ($taskJson.content === undefined) {
-                throw new UnexpectedError(`Content is missing in the taskJson - probbably commands are applied in wrong order`);
+                throw new UnexpectedError(`Content is missing in the taskJson - probably commands are applied in wrong order`);
             }
             if (command.taskType === 'EXAMPLE') {
                 expectResultingParameterName();
@@ -6090,7 +6271,7 @@
     /**
      * Parses the boilerplate command
      *
-     * Note: @@@ This command is used as boilerplate for new commands - it should NOT be used in any `.book` file
+     * Note: @@ This command is used as boilerplate for new commands - it should NOT be used in any `.book` file
      *
      * @see `documentationUrl` for more details
      * @private within the commands folder
@@ -6478,11 +6659,11 @@
     };
 
     /**
-     * @@@
+     * Normalizes a given text to camelCase format.
      *
-     * @param text @@@
-     * @param _isFirstLetterCapital @@@
-     * @returns @@@
+     * @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`
@@ -6532,9 +6713,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
      *
@@ -6546,18 +6727,19 @@
         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;
     }
 
     /**
-     * Function `validateParameterName` will @@@
+     * Function `validateParameterName` will normalize and validate a parameter name for use in pipelines.
+     * It removes diacritics, emojis, and quotes, normalizes to camelCase, and checks for reserved names and invalid characters.
      *
-     * @param parameterName @@@
-     * @returns @@@
-     * @throws {ParseError} @@@
+     * @param parameterName The parameter name to validate and normalize.
+     * @returns The validated and normalized parameter name.
+     * @throws {ParseError} If the parameter name is empty, reserved, or contains invalid characters.
      * @private within the repository
      */
     function validateParameterName(parameterName) {
@@ -6627,8 +6809,6 @@
     /**
      * Parses the foreach command
      *
-     * Note: @@@ This command is used as foreach for new commands - it should NOT be used in any `.book` file
-     *
      * @see `documentationUrl` for more details
      * @public exported from `@promptbook/editable`
      */
@@ -6685,14 +6865,14 @@
                     `));
                 // <- TODO: [🏢] List all supported format names
             }
-            const subvalueDefinition = formatDefinition.subvalueDefinitions.find((subvalueDefinition) => [subvalueDefinition.subvalueName, ...(subvalueDefinition.aliases || [])].includes(subformatName));
-            if (subvalueDefinition === undefined) {
+            const subvalueParser = formatDefinition.subvalueParsers.find((subvalueParser) => [subvalueParser.subvalueName, ...(subvalueParser.aliases || [])].includes(subformatName));
+            if (subvalueParser === undefined) {
                 throw new ParseError(spaceTrim__default["default"]((block) => `
                         Unsupported subformat name "${subformatName}" for format "${formatName}"
 
                         Available subformat names for format "${formatDefinition.formatName}":
-                        ${block(formatDefinition.subvalueDefinitions
-                .map((subvalueDefinition) => subvalueDefinition.subvalueName)
+                        ${block(formatDefinition.subvalueParsers
+                .map((subvalueParser) => subvalueParser.subvalueName)
                 .map((subvalueName) => `- ${subvalueName}`)
                 .join('\n'))}
                     `));
@@ -6869,14 +7049,14 @@
     };
 
     /**
-     * @@@
+     * Chatbot form factor definition for conversational interfaces that interact with users in a chat-like manner.
      *
      * @public exported from `@promptbook/core`
      */
     const ChatbotFormfactorDefinition = {
         name: 'CHATBOT',
         aliasNames: ['CHAT'],
-        description: `@@@`,
+        description: `A chatbot form factor for conversational user interfaces.`,
         documentationUrl: `https://github.com/webgptorg/promptbook/discussions/174`,
         pipelineInterface: {
             inputParameters: [
@@ -6903,7 +7083,45 @@
     };
 
     /**
-     * Generator is form of app that @@@
+     * Completion is formfactor that emulates completion models
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const CompletionFormfactorDefinition = {
+        name: 'COMPLETION',
+        description: `Completion is formfactor that emulates completion models`,
+        documentationUrl: `https://github.com/webgptorg/promptbook/discussions/@@`,
+        //                                                                     <- TODO: https://github.com/webgptorg/promptbook/discussions/new?category=concepts
+        //                                                                              "🔠 Completion Formfactor"
+        pipelineInterface: {
+            inputParameters: [
+                {
+                    name: 'inputText',
+                    description: `Input text to be completed`,
+                    isInput: true,
+                    isOutput: false,
+                },
+                {
+                    name: 'instructions',
+                    description: `Additional instructions for the model, for example the required length, empty by default`,
+                    isInput: true,
+                    isOutput: false,
+                },
+            ],
+            outputParameters: [
+                {
+                    name: 'followingText',
+                    description: `Text that follows the input text`,
+                    isInput: false,
+                    isOutput: true,
+                },
+            ],
+        },
+    };
+
+    /**
+     * Generator form factor represents an application that generates content or data based on user input or predefined rules.
+     * This form factor is used for apps that produce outputs, such as text, images, or other media, based on provided input.
      *
      * @public exported from `@promptbook/core`
      */
@@ -6932,7 +7150,7 @@
     };
 
     /**
-     * @@@
+     * Pipeline interface which is equivalent to `any`
      *
      * @see https://github.com/webgptorg/promptbook/discussions/171
      *
@@ -6947,13 +7165,13 @@
      */
 
     /**
-     * @@@
+     * A generic pipeline
      *
      * @public exported from `@promptbook/core`
      */
     const GenericFormfactorDefinition = {
         name: 'GENERIC',
-        description: `@@@`,
+        description: `A generic pipeline`,
         documentationUrl: `https://github.com/webgptorg/promptbook/discussions/173`,
         pipelineInterface: GENERIC_PIPELINE_INTERFACE,
     };
@@ -6988,17 +7206,20 @@
     };
 
     /**
-     * Matcher is form of app that @@@
+     * Matcher is form of app that evaluates (spreadsheet) content against defined criteria or patterns,
+     * determining if it matches or meets specific requirements. Used for classification,
+     * validation, filtering, and quality assessment of inputs.
      *
      * @public exported from `@promptbook/core`
      */
     const MatcherFormfactorDefinition = {
         name: 'EXPERIMENTAL_MATCHER',
-        description: `@@@`,
+        description: `An evaluation system that determines whether content meets specific criteria or patterns.
+    Used for content validation, quality assessment, and intelligent filtering tasks. Currently in experimental phase.`,
         documentationUrl: `https://github.com/webgptorg/promptbook/discussions/177`,
         pipelineInterface: {
             inputParameters: [
-                /* @@@ */
+                /* Input parameters for content to be matched and criteria to match against */
                 {
                     name: 'nonce',
                     description: 'Just to prevent EXPERIMENTAL_MATCHER to be set as implicit formfactor',
@@ -7007,20 +7228,21 @@
                 },
             ],
             outputParameters: [
-            /* @@@ */
+            /* Output parameters containing match results, confidence scores, and relevant metadata */
             ],
         },
     };
 
     /**
-     * Sheets is form of app that @@@
+     * Sheets is form of app that processes tabular data in CSV format, allowing transformation
+     * and analysis of structured data through AI-powered operations
      *
      * @public exported from `@promptbook/core`
      */
     const SheetsFormfactorDefinition = {
         name: 'SHEETS',
         aliasNames: ['SHEETS', 'SHEET'],
-        description: `@@@`,
+        description: `A formfactor for processing spreadsheet-like data in CSV format, enabling AI transformations on tabular data`,
         documentationUrl: `https://github.com/webgptorg/promptbook/discussions/176`,
         pipelineInterface: {
             inputParameters: [
@@ -7043,13 +7265,16 @@
     };
 
     /**
-     * Translator is form of app that @@@
+     * Translator is form of app that transforms input text from one form to another,
+     * such as language translation, style conversion, tone modification, or other text transformations.
      *
      * @public exported from `@promptbook/core`
      */
     const TranslatorFormfactorDefinition = {
         name: 'TRANSLATOR',
-        description: `@@@`,
+        description: `A text transformation system that converts input content into different forms,
+    including language translations, paraphrasing, style conversions, and tone adjustments.
+    This form factor takes one input and produces one transformed output.`,
         documentationUrl: `https://github.com/webgptorg/promptbook/discussions/175`,
         pipelineInterface: {
             inputParameters: [
@@ -7086,6 +7311,8 @@
         MatcherFormfactorDefinition,
         GeneratorFormfactorDefinition,
         ImageGeneratorFormfactorDefinition,
+        CompletionFormfactorDefinition,
+        // <- [🛬] When making new formfactor, copy the _boilerplate and link it here
     ];
     /**
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -7094,7 +7321,7 @@
     /**
      * Parses the formfactor command
      *
-     * Note: @@@ This command is used as formfactor for new commands - it should NOT be used in any `.book` file
+     * Note: This command is used as a formfactor for new commands and defines the app type format - it should NOT be used in any `.book` file
      *
      * @see `documentationUrl` for more details
      * @public exported from `@promptbook/editable`
@@ -7116,7 +7343,7 @@
         /**
          * Description of the FORMFACTOR command
          */
-        description: `@@`,
+        description: `Specifies the application type and interface requirements that this promptbook should conform to`,
         /**
          * Link to documentation
          */
@@ -7259,8 +7486,7 @@
     };
 
     /**
-     * @@@
-     *
+     * @see {@link ModelVariant}
      * @public exported from `@promptbook/core`
      */
     const MODEL_VARIANTS = ['COMPLETION', 'CHAT', 'EMBEDDING' /* <- TODO [🏳] */ /* <- [🤖] */];
@@ -7692,10 +7918,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) {
@@ -8156,7 +8382,7 @@
         //        Arg1   Arg2   Arg3 | FOO
         {
             const commandNameRaw = items.slice(-1).join('_');
-            const args = items.slice(0, -1); // <- Note: This is probbably not correct
+            const args = items.slice(0, -1); // <- Note: This is probably not correct
             const rawArgs = raw
                 .substring(0, raw.length - commandNameRaw.length)
                 .trim();
@@ -8175,7 +8401,10 @@
               `));
     }
     /**
-     * @@@
+     * Generates a markdown-formatted message listing all supported commands
+     * with their descriptions and documentation links
+     *
+     * @returns A formatted markdown string containing all available commands and their details
      */
     function getSupportedCommandsMessage() {
         return COMMANDS.flatMap(({ name, aliasNames, description, documentationUrl }) => 
@@ -8186,7 +8415,10 @@
         ]).join('\n');
     }
     /**
-     * @@@
+     * Attempts to parse a command variant using the provided input parameters
+     *
+     * @param input Object containing command parsing information including raw command text and normalized values
+     * @returns A parsed Command object if successful, or null if the command cannot be parsed
      */
     function parseCommandVariant(input) {
         const { commandNameRaw, usagePlace, normalized, args, raw, rawArgs } = input;
@@ -8233,7 +8465,7 @@
     }
 
     /**
-     * @@@
+     * Extracts the interface (input and output parameters) from a pipeline.
      *
      * @deprecated https://github.com/webgptorg/promptbook/pull/186
      * @see https://github.com/webgptorg/promptbook/discussions/171
@@ -8266,7 +8498,7 @@
     }
 
     /**
-     * @@@
+     * Checks if two pipeline interfaces are structurally identical.
      *
      * @deprecated https://github.com/webgptorg/promptbook/pull/186
      * @see https://github.com/webgptorg/promptbook/discussions/171
@@ -8298,10 +8530,11 @@
     }
 
     /**
-     * @@@
+     * Checks if a given pipeline satisfies the requirements of a specified pipeline interface.
      *
      * @deprecated https://github.com/webgptorg/promptbook/pull/186
      * @see https://github.com/webgptorg/promptbook/discussions/171
+     * @returns `true` if the pipeline implements the interface, `false` otherwise.
      *
      * @public exported from `@promptbook/core`
      */
@@ -8487,7 +8720,8 @@
     }
 
     /**
-     * @@@
+     * Utility to determine if a pipeline string is in flat format.
+     * A flat pipeline is a simple text without proper structure (headers, blocks, etc).
      *
      * @public exported from `@promptbook/editable`
      */
@@ -8508,7 +8742,10 @@
     }
 
     /**
-     * @@@
+     * Converts a pipeline structure to its string representation.
+     *
+     * Transforms a flat, simple pipeline into a properly formatted pipeline string
+     * with sections for title, prompt, and return statement.
      *
      * @public exported from `@promptbook/editable`
      */
@@ -8565,7 +8802,7 @@
      * Note: It can not work with html syntax and comments
      *
      * @param markdown any valid markdown
-     * @returns @@@
+     * @returns An array of strings, each representing an individual list item found in the markdown
      * @public exported from `@promptbook/markdown-utils`
      */
     function extractAllListItemsFromMarkdown(markdown) {
@@ -8590,8 +8827,8 @@
      *
      * - When there are multiple or no code blocks the function throws a `ParseError`
      *
-     * Note: There are multiple simmilar function:
-     * - `extractBlock` just extracts the content of the code block which is also used as build-in function for postprocessing
+     * Note: There are multiple similar functions:
+     * - `extractBlock` just extracts the content of the code block which is also used as built-in function for postprocessing
      * - `extractJsonBlock` extracts exactly one valid JSON code block
      * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
      * - `extractAllBlocksFromMarkdown` extracts all code blocks with language of the code block
@@ -8746,7 +8983,7 @@
      * Compile pipeline from string (markdown) format to JSON format synchronously
      *
      * Note: There are 3 similar functions:
-     * - `compilePipeline` **(preferred)** - which propperly compiles the promptbook and use embedding for external knowledge
+     * - `compilePipeline` **(preferred)** - which properly compiles the promptbook and uses embedding for external knowledge
      * - `parsePipeline` - use only if you need to compile promptbook synchronously and it contains NO external knowledge
      * - `preparePipeline` - just one step in the compilation process
      *
@@ -9183,7 +9420,7 @@
      * TODO: Use spaceTrim more effectively
      * TODO: [🧠] Parameter flags - isInput, isOutput, isInternal
      * TODO: [🥞] Not optimal parsing because `splitMarkdownIntoSections` is executed twice with same string, once through `flattenMarkdown` and second directly here
-     * TODO: [♈] Probbably move expectations from tasks to parameters
+     * TODO: [♈] Probably move expectations from tasks to parameters
      * TODO: [🛠] Actions, instruments (and maybe knowledge) => Functions and tools
      * TODO: [🍙] Make some standard order of json properties
      */
@@ -9400,7 +9637,8 @@
      */
 
     /**
-     * @@@
+     * Attempts to locate the specified application on a Linux system using the 'which' command.
+     * Returns the path to the executable if found, or null otherwise.
      *
      * @private within the repository
      */
@@ -9420,7 +9658,8 @@
      */
 
     /**
-     * @@@
+     * Provides filesystem access (for example for Node.js-based scrapers)
+     * Creates a standardized filesystem interface that scrapers can use for file operations.
      *
      * @public exported from `@promptbook/node`
      */
@@ -9466,7 +9705,8 @@
     // eslint-disable-next-line @typescript-eslint/no-var-requires
     const userhome = require('userhome');
     /**
-     * @@@
+     * Attempts to locate the specified application on a macOS system by checking standard application paths and using mdfind.
+     * Returns the path to the executable if found, or null otherwise.
      *
      * @private within the repository
      */
@@ -9498,7 +9738,8 @@
      */
 
     /**
-     * @@@
+     * Attempts to locate the specified application on a Windows system by searching common installation directories.
+     * Returns the path to the executable if found, or null otherwise.
      *
      * @private within the repository
      */
@@ -9569,7 +9810,8 @@
      */
 
     /**
-     * @@@
+     * Locates the LibreOffice executable on the current system by searching platform-specific paths.
+     * Returns the path to the executable if found, or null otherwise.
      *
      * @private within the repository
      */
@@ -9587,7 +9829,8 @@
      */
 
     /**
-     * @@@
+     * Locates the Pandoc executable on the current system by searching platform-specific paths.
+     * Returns the path to the executable if found, or null otherwise.
      *
      * @private within the repository
      */
@@ -9605,7 +9848,7 @@
      */
 
     /**
-     * @@@
+     * Provides paths to required executables (i.e. as Pandoc and LibreOffice) for Node.js environments.
      *
      * @public exported from `@promptbook/node`
      */
@@ -9625,10 +9868,10 @@
      */
 
     /**
-     * @@@
+     * Register for LLM tools metadata.
      *
      * Note: `$` is used to indicate that this interacts with the global scope
-     * @singleton Only one instance of each register is created per build, but thare can be more @@@
+     * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
      * @public exported from `@promptbook/core`
      */
     const $llmToolsMetadataRegister = new $Register('llm_tools_metadata');
@@ -9656,10 +9899,10 @@
      */
 
     /**
-     * @@@
+     * Register for LLM tools.
      *
      * Note: `$` is used to indicate that this interacts with the global scope
-     * @singleton Only one instance of each register is created per build, but thare can be more @@@
+     * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
      * @public exported from `@promptbook/core`
      */
     const $llmToolsRegister = new $Register('llm_execution_tools_constructors');
@@ -9852,9 +10095,8 @@
      */
 
     /**
-     * @@@
+     * Provides LLM tools configuration by reading environment variables.
      *
-     * @@@ .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:
@@ -9862,7 +10104,8 @@
      * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
      * - ...
      *
-     * @returns @@@
+     * @see Environment variables documentation or .env file for required variables.
+     * @returns A promise that resolves to the LLM tools configuration, or null if configuration is incomplete or missing.
      * @public exported from `@promptbook/node`
      */
     async function $provideLlmToolsConfigurationFromEnv() {
@@ -9884,11 +10127,16 @@
      */
 
     /**
-     * @@@
+     * Creates LLM execution tools from provided configuration objects
+     *
+     * Instantiates and configures LLM tool instances for each configuration entry,
+     * combining them into a unified interface via MultipleLlmExecutionTools.
      *
      * Note: This function is not cached, every call creates new instance of `MultipleLlmExecutionTools`
      *
-     * @returns @@@
+     * @param configuration Array of LLM tool configurations to instantiate
+     * @param options Additional options for configuring the LLM tools
+     * @returns A unified interface combining all successfully instantiated LLM tools
      * @public exported from `@promptbook/core`
      */
     function createLlmToolsFromConfiguration(configuration, options = {}) {
@@ -9927,7 +10175,11 @@
     /**
      * TODO: [🎌] Together with `createLlmToolsFromConfiguration` + 'EXECUTION_TOOLS_CLASSES' gets to `@promptbook/core` ALL model providers, make this more efficient
      * TODO: [🧠][🎌] Dynamically install required providers
-     * TODO: @@@ write discussion about this - wizzard
+     * TODO: We should implement an interactive configuration wizard that would:
+     *       1. Detect which LLM providers are available in the environment
+     *       2. Guide users through required configuration settings for each provider
+     *       3. Allow testing connections before completing setup
+     *       4. Generate appropriate configuration code for application integration
      * TODO: [🧠][🍛] Which name is better `createLlmToolsFromConfig` or `createLlmToolsFromConfiguration`?
      * TODO: [🧠] Is there some meaningfull way how to test this util
      * TODO: This should be maybe not under `_common` but under `utils`
@@ -9935,11 +10187,14 @@
      */
 
     /**
-     * @@@
+     * Automatically configures LLM tools from environment variables in Node.js
+     *
+     * This utility function detects available LLM providers based on environment variables
+     * and creates properly configured LLM execution tools for each detected provider.
      *
      * Note: This function is not cached, every call creates new instance of `MultipleLlmExecutionTools`
      *
-     * @@@ .env
+     * Supports environment variables from .env files when dotenv is configured
      * 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:
@@ -9947,7 +10202,8 @@
      * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
      * - ...
      *
-     * @returns @@@
+     * @param options Configuration options for the LLM tools
+     * @returns A unified interface containing all detected and configured LLM tools
      * @public exported from `@promptbook/node`
      */
     async function $provideLlmToolsFromEnv(options = {}) {
@@ -9973,7 +10229,16 @@
         return createLlmToolsFromConfiguration(configuration, options);
     }
     /**
-     * TODO: @@@ write `$provideLlmToolsFromEnv` vs `$provideLlmToolsConfigurationFromEnv` vs `createLlmToolsFromConfiguration`
+     * TODO: The architecture for LLM tools configuration consists of three key functions:
+     * 1. `$provideLlmToolsFromEnv` - High-level function that detects available providers from env vars and returns ready-to-use LLM tools
+     * 2. `$provideLlmToolsConfigurationFromEnv` - Middle layer that extracts configuration objects from environment variables
+     * 3. `createLlmToolsFromConfiguration` - Low-level function that instantiates LLM tools from explicit configuration
+     *
+     * This layered approach allows flexibility in how tools are configured:
+     * - Use $provideLlmToolsFromEnv for automatic detection and setup in Node.js environments
+     * - Use $provideLlmToolsConfigurationFromEnv to extract config objects for modification before instantiation
+     * - Use createLlmToolsFromConfiguration for explicit control over tool configurations
+     *
      * TODO: [🧠][🍛] Which name is better `$provideLlmToolsFromEnv` or `$provideLlmToolsFromEnvironment`?
      * 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
@@ -9983,11 +10248,9 @@
      */
 
     /**
-     * @@@
-     *
-     * 1) @@@
-     * 2) @@@
-     *
+     * Provides a collection of scrapers optimized for Node.js environment.
+     * 1) `provideScrapersForNode` use as default
+     * 2) `provideScrapersForBrowser` use in limited browser environment *
      * @public exported from `@promptbook/node`
      */
     async function $provideScrapersForNode(tools, options) {
@@ -10094,11 +10357,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) {
@@ -10112,11 +10375,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) {
@@ -10183,7 +10446,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`
@@ -10202,7 +10465,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`
@@ -10217,9 +10480,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
      *
@@ -10290,7 +10553,7 @@
      *
      * - When there are multiple or no code blocks the function throws a `ParseError`
      *
-     * Note: There are multiple simmilar function:
+     * Note: There are multiple similar function:
      * - `extractBlock` just extracts the content of the code block which is also used as build-in function for postprocessing
      * - `extractJsonBlock` extracts exactly one valid JSON code block
      * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
@@ -10327,7 +10590,7 @@
         })();
     }
     /**
-     * TODO: Probbably remove in favour of `keepImported`
+     * TODO: Probably remove in favour of `keepImported`
      * TODO: [1] This maybe does memory leak
      */
 
@@ -10531,7 +10794,7 @@
      */
 
     /**
-     * Placeholder for better implementation of JavascriptExecutionTools - some propper sandboxing
+     * Placeholder for better implementation of JavascriptExecutionTools - some proper sandboxing
      *
      * @alias JavascriptExecutionTools
      * @public exported from `@promptbook/javascript`
@@ -10916,14 +11179,17 @@
         return pipelineJsonStringified;
     }
     /**
-     * TODO: [🐝] Not Working propperly @see https://promptbook.studio/examples/mixed-knowledge.book
+     * TODO: [🐝] Not Working properly @see https://promptbook.studio/examples/mixed-knowledge.book
      * TODO: [🧠][0] Maybe rename to `stringifyPipelineJson`, `stringifyIndexedJson`,...
      * TODO: [🧠] Maybe more elegant solution than replacing via regex
      * TODO: [🍙] Make some standard order of json properties
      */
 
     /**
-     * @@@
+     * A storage implementation that caches data in files organized in a directory structure.
+     * Provides methods for retrieving, storing, and managing cached data on the filesystem.
+     *
+     * This class implements the PromptbookStorage interface for filesystem-based caching.
      *
      * @public exported from `@promptbook/node`
      */
@@ -10936,7 +11202,8 @@
             }
         }
         /**
-         * @@@
+         * Converts a storage key to a filesystem path where the data should be stored.
+         * Creates a consistent, deterministic file path based on the key string.
          */
         getFilenameForKey(key) {
             // TODO: [👬] DRY
@@ -10948,7 +11215,8 @@
             ...nameToSubfolderPath(hash /* <- TODO: [🎎] Maybe add some SHA256 prefix */), `${name.substring(0, MAX_FILENAME_LENGTH)}.json`);
         }
         /**
-         * @@@ Returns the current value associated with the given key, or null if the given key does not exist in the list associated with the object.
+         * Returns the current value associated with the given key, or null if the given key does not exist.
+         * Retrieves the cached data from the file system storage.
          */
         async getItem(key) {
             const filename = this.getFilenameForKey(key);
@@ -10961,7 +11229,8 @@
             return value;
         }
         /**
-         * @@@ Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+         * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+         * Persists data to the file system, creating necessary directory structure if it doesn't exist.
          */
         async setItem(key, value) {
             const filename = this.getFilenameForKey(key);
@@ -10973,7 +11242,8 @@
             await promises.writeFile(filename, fileContent, 'utf-8');
         }
         /**
-         * @@@ Removes the key/value pair with the given key from the list associated with the object, if a key/value pair with the given key exists.
+         * Removes the key/value pair with the given key from the storage, if a key/value pair with the given key exists.
+         * Deletes the corresponding file from the filesystem.
          */
         async removeItem(key) {
             const filename = this.getFilenameForKey(key);