@promptbook/cli 0.92.0-8 → 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('commander'), require('spacetrim'), require('waitasecond'), require('prompts'), require('path'), require('fs/promises'), require('dotenv'), require('crypto-js/enc-hex'), require('crypto-js/sha256'), require('crypto'), require('socket.io-client'), require('rxjs'), require('child_process'), require('jszip'), require('prettier'), require('prettier/parser-html'), require('papaparse'), require('crypto-js'), require('mime-types'), require('glob-promise'), require('moment'), require('express'), require('http'), require('socket.io'), require('express-openapi-validator'), require('swagger-ui-express'), require('@anthropic-ai/sdk'), require('@azure/openai'), require('openai'), require('@mozilla/readability'), require('jsdom'), require('showdown')) :
-    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'commander', 'spacetrim', 'waitasecond', 'prompts', 'path', 'fs/promises', 'dotenv', 'crypto-js/enc-hex', 'crypto-js/sha256', 'crypto', 'socket.io-client', 'rxjs', 'child_process', 'jszip', 'prettier', 'prettier/parser-html', 'papaparse', 'crypto-js', 'mime-types', 'glob-promise', 'moment', 'express', 'http', 'socket.io', 'express-openapi-validator', 'swagger-ui-express', '@anthropic-ai/sdk', '@azure/openai', 'openai', '@mozilla/readability', 'jsdom', 'showdown'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-cli"] = {}, global.colors, global.commander, global.spaceTrim, global.waitasecond, global.prompts, global.path, global.promises, global.dotenv, global.hexEncoder, global.sha256, global.crypto, global.socket_ioClient, global.rxjs, global.child_process, global.JSZip, global.prettier, global.parserHtml, global.papaparse, global.cryptoJs, global.mimeTypes, global.glob, global.moment, global.express, global.http, global.socket_io, global.OpenApiValidator, global.swaggerUi, global.Anthropic, global.openai, global.OpenAI, global.readability, global.jsdom, global.showdown));
-})(this, (function (exports, colors, commander, spaceTrim, waitasecond, prompts, path, promises, dotenv, hexEncoder, sha256, crypto, socket_ioClient, rxjs, child_process, JSZip, prettier, parserHtml, papaparse, cryptoJs, mimeTypes, glob, moment, express, http, socket_io, OpenApiValidator, swaggerUi, Anthropic, openai, OpenAI, readability, jsdom, showdown) { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('commander'), require('spacetrim'), require('waitasecond'), require('prompts'), require('path'), require('fs/promises'), require('dotenv'), require('crypto-js/enc-hex'), require('crypto-js/sha256'), require('crypto'), require('socket.io-client'), require('rxjs'), require('child_process'), require('jszip'), require('prettier'), require('prettier/parser-html'), require('papaparse'), require('crypto-js'), require('mime-types'), require('glob-promise'), require('moment'), require('express'), require('express-openapi-validator'), require('http'), require('socket.io'), require('swagger-ui-express'), require('@anthropic-ai/sdk'), require('bottleneck'), require('@azure/openai'), require('openai'), require('@mozilla/readability'), require('jsdom'), require('showdown')) :
+    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'commander', 'spacetrim', 'waitasecond', 'prompts', 'path', 'fs/promises', 'dotenv', 'crypto-js/enc-hex', 'crypto-js/sha256', 'crypto', 'socket.io-client', 'rxjs', 'child_process', 'jszip', 'prettier', 'prettier/parser-html', 'papaparse', 'crypto-js', 'mime-types', 'glob-promise', 'moment', 'express', 'express-openapi-validator', 'http', 'socket.io', 'swagger-ui-express', '@anthropic-ai/sdk', 'bottleneck', '@azure/openai', 'openai', '@mozilla/readability', 'jsdom', 'showdown'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-cli"] = {}, global.colors, global.commander, global.spaceTrim, global.waitasecond, global.prompts, global.path, global.promises, global.dotenv, global.hexEncoder, global.sha256, global.crypto, global.socket_ioClient, global.rxjs, global.child_process, global.JSZip, global.prettier, global.parserHtml, global.papaparse, global.cryptoJs, global.mimeTypes, global.glob, global.moment, global.express, global.OpenApiValidator, global.http, global.socket_io, global.swaggerUi, global.Anthropic, global.Bottleneck, global.openai, global.OpenAI, global.readability, global.jsdom, global.showdown));
+})(this, (function (exports, colors, commander, spaceTrim, waitasecond, prompts, path, promises, dotenv, hexEncoder, sha256, crypto, socket_ioClient, rxjs, child_process, JSZip, prettier, parserHtml, papaparse, cryptoJs, mimeTypes, glob, moment, express, OpenApiValidator, http, socket_io, swaggerUi, Anthropic, Bottleneck, openai, OpenAI, readability, jsdom, showdown) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -36,10 +36,11 @@
     var glob__default = /*#__PURE__*/_interopDefaultLegacy(glob);
     var moment__default = /*#__PURE__*/_interopDefaultLegacy(moment);
     var express__default = /*#__PURE__*/_interopDefaultLegacy(express);
-    var http__default = /*#__PURE__*/_interopDefaultLegacy(http);
     var OpenApiValidator__namespace = /*#__PURE__*/_interopNamespace(OpenApiValidator);
+    var http__default = /*#__PURE__*/_interopDefaultLegacy(http);
     var swaggerUi__default = /*#__PURE__*/_interopDefaultLegacy(swaggerUi);
     var Anthropic__default = /*#__PURE__*/_interopDefaultLegacy(Anthropic);
+    var Bottleneck__default = /*#__PURE__*/_interopDefaultLegacy(Bottleneck);
     var OpenAI__default = /*#__PURE__*/_interopDefaultLegacy(OpenAI);
 
     // ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
@@ -56,7 +57,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-8';
+    const PROMPTBOOK_ENGINE_VERSION = '0.92.0';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -97,7 +98,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
@@ -172,6 +173,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 = '!?';
     /**
      * Warning message for the generated sections and files files
      *
@@ -256,6 +272,7 @@
      * @public exported from `@promptbook/core`
      */
     const DEFAULT_MAX_EXECUTION_ATTEMPTS = 10; // <- TODO: [🤹‍♂️]
+    // <- TODO: [🐝]
     /**
      * Where to store your books
      * This is kind of a "src" for your books
@@ -327,7 +344,7 @@
     const DEFAULT_REMOTE_SERVER_URL = REMOTE_SERVER_URLS[0].urls[0];
     // <- TODO: [🧜‍♂️]
     /**
-     * @@@
+     * Default settings for parsing and generating CSV files in Promptbook.
      *
      * @public exported from `@promptbook/core`
      */
@@ -338,13 +355,13 @@
         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`
      */
@@ -356,7 +373,15 @@
      */
     const DEFAULT_GET_PIPELINE_COLLECTION_FUNCTION_NAME = `getPipelineCollection`;
     /**
-     * @@@
+     * Default rate limits (requests per minute)
+     *
+     * Note: Adjust based on the provider tier you are have
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const DEFAULT_MAX_REQUESTS_PER_MINUTE = 60;
+    /**
+     * Indicates whether pipeline logic validation is enabled. When true, the pipeline logic is checked for consistency.
      *
      * @private within the repository
      */
@@ -513,7 +538,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)}
@@ -696,7 +721,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
      *
@@ -707,10 +733,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`
@@ -762,10 +788,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`
@@ -775,11 +801,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) {
@@ -823,10 +849,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');
@@ -835,10 +861,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');
@@ -990,7 +1016,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
@@ -1043,15 +1069,12 @@
             }
             throw new Error(spaceTrim__default["default"]((block) => `
                     ${block(error.message)}
-            
+
                     The JSON text:
                     ${block(value)}
                 `));
         }
     }
-    /**
-     * TODO: !!!! Use in Promptbook.studio
-     */
 
     /**
      * Convert identification to Promptbook token
@@ -1091,7 +1114,7 @@
      * Just marks a place of place where should be something implemented
      * No side effects.
      *
-     * Note: It can be usefull suppressing eslint errors of unused variables
+     * Note: It can be useful suppressing eslint errors of unused variables
      *
      * @param value any values
      * @returns void
@@ -1101,7 +1124,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`
      */
@@ -1476,8 +1500,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) {
@@ -1532,6 +1560,26 @@
      * TODO: [🧠] Is there a way how to meaningfully test this utility
      */
 
+    // <- TODO: Maybe do better levels of trust
+    /**
+     * How is the model provider important?
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const MODEL_ORDERS = {
+        /**
+         * Top-tier models, e.g. OpenAI, Anthropic,...
+         */
+        TOP_TIER: 333,
+        /**
+         * Mid-tier models, e.g. Llama, Mistral, etc.
+         */
+        NORMAL: 100,
+        /**
+         * Low-tier models, e.g. Phi, Tiny, etc.
+         */
+        LOW_TIER: 0,
+    };
     /**
      * Order of keys in the pipeline JSON
      *
@@ -1559,13 +1607,19 @@
      */
     const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
     /**
-     * @@@
+     * Nonce which is used as string which is not occurring in normal text
+     *
+     * @private within the repository
+     */
+    const SALT_NONCE = 'ptbkghhewbvruets21t54et5';
+    /**
+     * Placeholder value indicating a parameter is missing its value.
      *
      * @private within the repository
      */
     const RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
     /**
-     * @@@
+     * Placeholder value indicating a parameter is restricted and cannot be used directly.
      *
      * @private within the repository
      */
@@ -1655,7 +1709,7 @@
         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
@@ -1730,7 +1784,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
      *
@@ -2000,10 +2054,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) {
@@ -2017,10 +2071,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`
@@ -2068,11 +2122,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) {
@@ -2092,7 +2146,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`
      */
@@ -2101,7 +2156,10 @@
     }
 
     /**
-     * @@@
+     * 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`
      */
@@ -2114,7 +2172,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
@@ -2126,7 +2185,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);
@@ -2139,7 +2199,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);
@@ -2151,7 +2212,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);
@@ -2210,7 +2272,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`
      */
@@ -2274,7 +2336,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';
@@ -2337,7 +2399,7 @@
             super(message);
             this.name = 'PipelineExecutionError';
             // TODO: [🐙] DRY - Maybe $randomId
-            this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid simmilar char conflicts   */)}`;
+            this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid similar char conflicts   */)}`;
             Object.setPrototypeOf(this, PipelineExecutionError.prototype);
         }
     }
@@ -2534,10 +2596,10 @@
         }
         get title() {
             // TODO: [🧠] Maybe fetch title+description from the remote server (as well as if model methods are defined)
-            return 'Remote server';
+            return 'Promptbook remote server';
         }
         get description() {
-            return 'Use all models by your remote server';
+            return `Models from Promptbook remote server ${this.options.remoteServerUrl}`;
         }
         /**
          * Check the configuration of all execution tools
@@ -2552,7 +2614,7 @@
          * List all available models that can be used
          */
         async listModels() {
-            // TODO: [👒] Listing models (and checking configuration) probbably should go through REST API not Socket.io
+            // TODO: [👒] Listing models (and checking configuration) probably should go through REST API not Socket.io
             const socket = await createRemoteClient(this.options);
             socket.emit('listModels-request', {
                 identification: this.options.identification,
@@ -2689,6 +2751,23 @@
         return new Date().toISOString();
     }
 
+    /**
+     * Parses the task and returns the list of all parameter names
+     *
+     * @param template the string template with parameters in {curly} braces
+     * @returns the list of parameter names
+     * @public exported from `@promptbook/utils`
+     */
+    function extractParameterNames(template) {
+        const matches = template.matchAll(/{\w+}/g);
+        const parameterNames = new Set();
+        for (const match of matches) {
+            const parameterName = match[0].slice(1, -1);
+            parameterNames.add(parameterName);
+        }
+        return parameterNames;
+    }
+
     /**
      * Intercepts LLM tools and counts total usage of the tools
      *
@@ -2699,17 +2778,19 @@
      * @public exported from `@promptbook/core`
      */
     function cacheLlmTools(llmTools, options = {}) {
-        const { storage = new MemoryStorage(), isCacheReloaded = false } = options;
+        const { storage = new MemoryStorage(), isCacheReloaded = false, isVerbose = DEFAULT_IS_VERBOSE } = options;
         const proxyTools = {
             ...llmTools,
             // <- Note: [🥫]
             get title() {
-                // TODO: [🧠] Maybe put here some suffix
-                return llmTools.title;
+                return `${llmTools.title} (cached)`;
+                // <- TODO: [🧈] Maybe standartize the suffix when wrapping `LlmExecutionTools` up
+                // <- TODO: [🧈][🧠] Does it make sence to suffix "(cached)"?
             },
             get description() {
-                // TODO: [🧠] Maybe put here some suffix
-                return llmTools.description;
+                return `${llmTools.description} (cached)`;
+                // <- TODO: [🧈] Maybe standartize the suffix when wrapping `LlmExecutionTools` up
+                // <- TODO: [🧈][🧠] Does it make sence to suffix "(cached)"?
             },
             listModels() {
                 // TODO: [🧠] Should be model listing also cached?
@@ -2719,13 +2800,37 @@
         const callCommonModel = async (prompt) => {
             const { parameters, content, modelRequirements } = prompt;
             // <- Note: These are relevant things from the prompt that the cache key should depend on.
+            // TODO: Maybe some standalone function for normalization of content for cache
+            let normalizedContent = content;
+            normalizedContent = normalizedContent.replace(/\s+/g, ' ');
+            normalizedContent = normalizedContent.split('\r\n').join('\n');
+            normalizedContent = spaceTrim__default["default"](normalizedContent);
+            // Note: Do not need to save everything in the cache, just the relevant parameters
+            const relevantParameterNames = extractParameterNames(content);
+            const relevantParameters = Object.fromEntries(Object.entries(parameters).filter(([key]) => relevantParameterNames.has(key)));
+            const keyHashBase = { relevantParameters, normalizedContent, modelRequirements };
             const key = titleToName(prompt.title.substring(0, MAX_FILENAME_LENGTH - 10) +
                 '-' +
-                sha256__default["default"](hexEncoder__default["default"].parse(JSON.stringify({ parameters, content, modelRequirements }))).toString( /* hex */));
+                sha256__default["default"](hexEncoder__default["default"].parse(JSON.stringify(keyHashBase)))
+                    .toString( /* hex */)
+                    .substring(0, 10 - 1));
             const cacheItem = !isCacheReloaded ? await storage.getItem(key) : null;
             if (cacheItem) {
                 return cacheItem.promptResult;
             }
+            if (isVerbose) {
+                console.info('Cache miss for key:', key, {
+                    prompt,
+                    'prompt.title': prompt.title,
+                    MAX_FILENAME_LENGTH,
+                    keyHashBase,
+                    parameters,
+                    relevantParameters,
+                    content,
+                    normalizedContent,
+                    modelRequirements,
+                });
+            }
             let promptResult;
             variant: switch (prompt.modelRequirements.modelVariant) {
                 case 'CHAT':
@@ -2746,7 +2851,16 @@
             await storage.setItem(key, {
                 date: $getCurrentDate(),
                 promptbookVersion: PROMPTBOOK_ENGINE_VERSION,
-                prompt,
+                bookVersion: BOOK_LANGUAGE_VERSION,
+                prompt: {
+                    ...prompt,
+                    parameters: Object.entries(parameters).length === Object.entries(relevantParameters).length
+                        ? parameters
+                        : {
+                            ...relevantParameters,
+                            note: `<- Note: Only relevant parameters are stored in the cache`,
+                        },
+                },
                 promptResult,
             });
             return promptResult;
@@ -2772,9 +2886,9 @@
     /**
      * TODO: [🧠][💸] Maybe make some common abstraction `interceptLlmTools` and use here (or use javascript Proxy?)
      * TODO: [🧠] Is there some meaningfull way how to test this util
-     * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
-     *            @@@ write discussion about this and storages
-     *            @@@ write how to combine multiple interceptors
+     * TODO: [👷‍♂️] Comprehensive manual about construction of llmTools
+     *            Detailed explanation about caching strategies and appropriate storage selection for different use cases
+     *            Examples of how to combine multiple interceptors for advanced caching, logging, and usage tracking
      */
 
     /**
@@ -2904,12 +3018,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();
@@ -2964,9 +3080,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:
@@ -2974,7 +3089,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() {
@@ -3012,29 +3128,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
@@ -3188,11 +3315,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 = {}) {
@@ -3231,7 +3363,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`
@@ -3239,11 +3375,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:
@@ -3251,7 +3390,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 = {}) {
@@ -3277,7 +3417,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
@@ -3445,15 +3594,19 @@
                             type: 'text',
                             name: 'username',
                             message: 'Enter your email:',
-                            validate: (value) => (isValidEmail(value) ? true : 'Valid email is required'),
+                            validate(value) {
+                                return isValidEmail(value) ? true : 'Valid email is required';
+                            },
                         },
                         {
                             type: 'password',
                             name: 'password',
                             message: 'Enter your password:',
-                            validate: (value) => value.length /* <- TODO: [🧠] Better password validation */ > 0
-                                ? true
-                                : 'Password is required',
+                            validate(value) {
+                                return value.length /* <- TODO: [🧠] Better password validation */ > 0
+                                    ? true
+                                    : 'Password is required';
+                            },
                         },
                     ]);
                     const loginUrl = `${remoteServerUrl}/login`;
@@ -3690,7 +3843,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
      */
@@ -3733,7 +3887,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
      */
@@ -3765,7 +3920,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
      */
@@ -3836,7 +3992,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
      */
@@ -3854,7 +4011,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
      */
@@ -3872,7 +4030,7 @@
      */
 
     /**
-     * @@@
+     * Provides paths to required executables (i.e. as Pandoc and LibreOffice) for Node.js environments.
      *
      * @public exported from `@promptbook/node`
      */
@@ -3892,10 +4050,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');
@@ -3904,11 +4063,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) {
@@ -3933,10 +4090,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');
@@ -4119,7 +4276,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
      *
@@ -4141,7 +4298,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
      *
@@ -4161,7 +4318,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
      *
@@ -4258,7 +4415,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) => `
@@ -4269,7 +4426,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) => `
@@ -4516,7 +4673,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`
      */
@@ -4628,7 +4785,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)}`);
@@ -4746,23 +4903,6 @@
      * TODO: [🧠] Should be in generated .book.md file GENERATOR_WARNING
      */
 
-    /**
-     * Parses the task and returns the list of all parameter names
-     *
-     * @param template the string template with parameters in {curly} braces
-     * @returns the list of parameter names
-     * @public exported from `@promptbook/utils`
-     */
-    function extractParameterNames(template) {
-        const matches = template.matchAll(/{\w+}/g);
-        const parameterNames = new Set();
-        for (const match of matches) {
-            const parameterName = match[0].slice(1, -1);
-            parameterNames.add(parameterName);
-        }
-        return parameterNames;
-    }
-
     /**
      * Unprepare just strips the preparation data of the pipeline
      *
@@ -4812,7 +4952,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
@@ -4924,15 +5064,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;
         }
         /*
@@ -4953,6 +5096,35 @@
      *     - [♨] Are tasks prepared
      */
 
+    /**
+     * 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
 
@@ -5031,8 +5203,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;
@@ -5042,6 +5215,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);
@@ -5087,17 +5264,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() {
@@ -5105,15 +5289,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] --||--
             },
         };
     }
@@ -5122,35 +5306,6 @@
      * TODO: [🐚] Split into more files and make `PrepareTask` & `RemoteTask` + split the function
      */
 
-    /**
-     * 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
-        };
-    }
-
     /**
      * Format either small or big number
      *
@@ -5393,7 +5548,7 @@
     }
 
     /**
-     * @@@
+     * Contains configuration options for parsing and generating CSV files, such as delimiters and quoting rules.
      *
      * @public exported from `@promptbook/core`
      */
@@ -5402,11 +5557,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`
      */
@@ -5430,7 +5603,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) {
@@ -5442,12 +5615,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
@@ -5462,23 +5635,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
@@ -5494,9 +5681,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 });
@@ -5505,10 +5692,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
      */
 
@@ -5517,7 +5704,7 @@
      *
      * @private still in development [🏢]
      */
-    const JsonFormatDefinition = {
+    const JsonFormatParser = {
         formatName: 'JSON',
         mimeType: 'application/json',
         isValid(value, settings, schema) {
@@ -5529,28 +5716,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';
@@ -5559,19 +5746,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');
                 },
             },
@@ -5581,10 +5769,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
      */
 
@@ -5592,7 +5780,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`
      */
@@ -5617,7 +5805,7 @@
      *
      * @private still in development [🏢]
      */
-    const XmlFormatDefinition = {
+    const XmlFormatParser = {
         formatName: 'XML',
         mimeType: 'application/xml',
         isValid(value, settings, schema) {
@@ -5629,17 +5817,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
      */
 
@@ -5648,24 +5836,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) {
@@ -5688,7 +5871,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;
         }
@@ -5719,7 +5902,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;
     }
@@ -5727,8 +5910,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
@@ -5778,7 +5961,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) {
@@ -5798,7 +5981,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
@@ -5823,7 +6006,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`
      */
 
     /**
@@ -6044,14 +6227,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
      *
@@ -6072,13 +6255,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) {
@@ -6300,7 +6487,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 || '');
                             }
@@ -6402,12 +6589,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);
         }
@@ -6438,16 +6629,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'))}
 
@@ -6459,55 +6650,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) {
@@ -6515,7 +6736,7 @@
     }
 
     /**
-     * @@@
+     * Retrieves example values or templates for a given task, used to guide or validate pipeline execution.
      *
      * @private internal utility of `createPipelineExecutor`
      */
@@ -6524,91 +6745,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);
+    }
+
+    /**
      *
-     * Here is the place where RAG (retrieval-augmented generation) happens
+     * @param knowledgePieces
+     * @returns
+     *
+     * @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;
@@ -6620,6 +6878,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) {
@@ -6634,23 +6895,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:
 
@@ -6668,13 +6927,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));
@@ -6719,6 +6981,7 @@
             preparedPipeline,
             tools,
             $executionReport,
+            onProgress,
             pipelineIdentification,
             maxExecutionAttempts,
             maxParallelCount,
@@ -6746,7 +7009,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`
      */
@@ -6771,9 +7035,12 @@
     }
 
     /**
-     * @@@
+     * Executes an entire pipeline, resolving tasks in dependency order, handling errors, and reporting progress.
      *
-     * Note: This is not a `PipelineExecutor` (which is binded with one exact pipeline), but a utility function of `createPipelineExecutor` which creates `PipelineExecutor`
+     * Note: This is not a `PipelineExecutor` (which is bound to a single pipeline), but a utility function used by `createPipelineExecutor` to create a `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`
      */
@@ -7096,10 +7363,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);
@@ -7259,7 +7543,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`
      */
@@ -7398,7 +7684,7 @@
     }
 
     /**
-     * Prepares the knowle
+     * Prepares the knowledge pieces
      *
      * @see https://github.com/webgptorg/promptbook/discussions/41
      * @public exported from `@promptbook/core`
@@ -7494,15 +7780,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;
@@ -7540,7 +7829,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
@@ -7676,7 +7965,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,
@@ -7952,7 +8241,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();
@@ -8020,7 +8309,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
@@ -8408,11 +8697,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`
@@ -8462,9 +8751,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
      *
@@ -8476,18 +8765,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) {
@@ -8557,8 +8847,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`
      */
@@ -8615,14 +8903,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'))}
                     `));
@@ -8799,14 +9087,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: [
@@ -8833,7 +9121,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`
      */
@@ -8862,7 +9188,7 @@
     };
 
     /**
-     * @@@
+     * Pipeline interface which is equivalent to `any`
      *
      * @see https://github.com/webgptorg/promptbook/discussions/171
      *
@@ -8877,13 +9203,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,
     };
@@ -8918,17 +9244,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',
@@ -8937,20 +9266,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: [
@@ -8973,13 +9303,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: [
@@ -9016,6 +9349,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
@@ -9024,7 +9359,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`
@@ -9046,7 +9381,7 @@
         /**
          * Description of the FORMFACTOR command
          */
-        description: `@@`,
+        description: `Specifies the application type and interface requirements that this promptbook should conform to`,
         /**
          * Link to documentation
          */
@@ -9189,8 +9524,7 @@
     };
 
     /**
-     * @@@
-     *
+     * @see {@link ModelVariant}
      * @public exported from `@promptbook/core`
      */
     const MODEL_VARIANTS = ['COMPLETION', 'CHAT', 'EMBEDDING' /* <- TODO [🏳] */ /* <- [🤖] */];
@@ -9622,10 +9956,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) {
@@ -10086,7 +10420,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();
@@ -10105,7 +10439,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 }) => 
@@ -10116,7 +10453,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;
@@ -10163,7 +10503,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
@@ -10196,7 +10536,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
@@ -10228,10 +10568,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`
      */
@@ -10417,7 +10758,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`
      */
@@ -10438,7 +10780,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`
      */
@@ -10495,7 +10840,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) {
@@ -10520,8 +10865,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
@@ -10676,7 +11021,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
      *
@@ -11113,7 +11458,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
      */
@@ -11158,21 +11503,63 @@
      */
     function renderPromptbookMermaid(pipelineJson, options) {
         const { linkTask = () => null } = options || {};
+        const MERMAID_PREFIX = 'pipeline_';
+        const MERMAID_KNOWLEDGE_NAME = MERMAID_PREFIX + 'knowledge';
+        const MERMAID_RESERVED_NAME = MERMAID_PREFIX + 'reserved';
+        const MERMAID_INPUT_NAME = MERMAID_PREFIX + 'input';
+        const MERMAID_OUTPUT_NAME = MERMAID_PREFIX + 'output';
         const parameterNameToTaskName = (parameterName) => {
+            if (parameterName === 'knowledge') {
+                return MERMAID_KNOWLEDGE_NAME;
+            }
+            else if (RESERVED_PARAMETER_NAMES.includes(parameterName)) {
+                return MERMAID_RESERVED_NAME;
+            }
             const parameter = pipelineJson.parameters.find((parameter) => parameter.name === parameterName);
             if (!parameter) {
                 throw new UnexpectedError(`Could not find {${parameterName}}`);
-                // <- TODO: !!6 This causes problems when {knowledge} and other reserved parameters are used
+                // <- TODO: This causes problems when {knowledge} and other reserved parameters are used
             }
             if (parameter.isInput) {
-                return 'input';
+                return MERMAID_INPUT_NAME;
             }
             const task = pipelineJson.tasks.find((task) => task.resultingParameterName === parameterName);
             if (!task) {
                 throw new Error(`Could not find task for {${parameterName}}`);
             }
-            return task.name || normalizeTo_camelCase('task-' + titleToName(task.title));
+            return MERMAID_PREFIX + (task.name || normalizeTo_camelCase('task-' + titleToName(task.title)));
         };
+        const inputAndIntermediateParametersMermaid = pipelineJson.tasks
+            .flatMap(({ title, dependentParameterNames, resultingParameterName }) => [
+            `${parameterNameToTaskName(resultingParameterName)}("${title}")`,
+            ...dependentParameterNames.map((dependentParameterName) => `${parameterNameToTaskName(dependentParameterName)}--"{${dependentParameterName}}"-->${parameterNameToTaskName(resultingParameterName)}`),
+        ])
+            .join('\n');
+        const outputParametersMermaid = pipelineJson.parameters
+            .filter(({ isOutput }) => isOutput)
+            .map(({ name }) => `${parameterNameToTaskName(name)}--"{${name}}"-->${MERMAID_OUTPUT_NAME}`)
+            .join('\n');
+        const linksMermaid = pipelineJson.tasks
+            .map((task) => {
+            const link = linkTask(task);
+            if (link === null) {
+                return '';
+            }
+            const { href, title } = link;
+            const taskName = parameterNameToTaskName(task.resultingParameterName);
+            return `click ${taskName} href "${href}" "${title}";`;
+        })
+            .filter((line) => line !== '')
+            .join('\n');
+        const interactionPointsMermaid = Object.entries({
+            [MERMAID_INPUT_NAME]: 'Input',
+            [MERMAID_OUTPUT_NAME]: 'Output',
+            [MERMAID_RESERVED_NAME]: 'Other',
+            [MERMAID_KNOWLEDGE_NAME]: 'Knowledge',
+        })
+            .filter(([MERMAID_NAME]) => (inputAndIntermediateParametersMermaid + outputParametersMermaid).includes(MERMAID_NAME))
+            .map(([MERMAID_NAME, title]) => `${MERMAID_NAME}((${title})):::${MERMAID_NAME}`)
+            .join('\n');
         const promptbookMermaid = spaceTrim.spaceTrim((block) => `
 
             %% 🔮 Tip: Open this on GitHub or in the VSCode website to see the Mermaid graph visually
@@ -11180,37 +11567,27 @@
             flowchart LR
               subgraph "${pipelineJson.title}"
 
+                  %% Basic configuration
                   direction TB
 
-                  input((Input)):::input
-                  ${block(pipelineJson.tasks
-        .flatMap(({ title, dependentParameterNames, resultingParameterName }) => [
-        `${parameterNameToTaskName(resultingParameterName)}("${title}")`,
-        ...dependentParameterNames.map((dependentParameterName) => `${parameterNameToTaskName(dependentParameterName)}--"{${dependentParameterName}}"-->${parameterNameToTaskName(resultingParameterName)}`),
-    ])
-        .join('\n'))}
+                  %% Interaction points from pipeline to outside
+                  ${block(interactionPointsMermaid)}
 
-                  ${block(pipelineJson.parameters
-        .filter(({ isOutput }) => isOutput)
-        .map(({ name }) => `${parameterNameToTaskName(name)}--"{${name}}"-->output`)
-        .join('\n'))}
-                  output((Output)):::output
+                  %% Input and intermediate parameters
+                  ${block(inputAndIntermediateParametersMermaid)}
 
-                  ${block(pipelineJson.tasks
-        .map((task) => {
-        const link = linkTask(task);
-        if (link === null) {
-            return '';
-        }
-        const { href, title } = link;
-        const taskName = parameterNameToTaskName(task.resultingParameterName);
-        return `click ${taskName} href "${href}" "${title}";`;
-    })
-        .filter((line) => line !== '')
-        .join('\n'))}
 
-                  classDef input color: grey;
-                  classDef output color: grey;
+                  %% Output parameters
+                  ${block(outputParametersMermaid)}
+
+                  %% Links
+                  ${block(linksMermaid)}
+
+                  %% Styles
+                  classDef ${MERMAID_INPUT_NAME} color: grey;
+                  classDef ${MERMAID_OUTPUT_NAME} color: grey;
+                  classDef ${MERMAID_RESERVED_NAME} color: grey;
+                  classDef ${MERMAID_KNOWLEDGE_NAME} color: grey;
 
               end;
 
@@ -11250,11 +11627,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) {
@@ -11268,11 +11645,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) {
@@ -11316,7 +11693,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`
@@ -11335,7 +11712,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`
@@ -11350,9 +11727,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
      *
@@ -11423,7 +11800,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
@@ -11460,7 +11837,7 @@
         })();
     }
     /**
-     * TODO: Probbably remove in favour of `keepImported`
+     * TODO: Probably remove in favour of `keepImported`
      * TODO: [1] This maybe does memory leak
      */
 
@@ -11664,7 +12041,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`
@@ -12038,7 +12415,7 @@
     /**
      * Function usageToWorktime will take usage and estimate saved worktime in hours of reading / writing
      *
-     * Note: This is an estimate based of theese sources:
+     * Note: This is an estimate based of these sources:
      * - https://jecas.cz/doba-cteni
      * - https://www.originalnitonery.cz/blog/psani-vsemi-deseti-se-muzete-naucit-i-sami-doma
      *
@@ -13123,7 +13500,9 @@
                     type: 'text',
                     name: 'pipelineSource',
                     message: '',
-                    validate: (value) => (value.length > 0 ? true : 'Pipeline source is required'),
+                    validate(value) {
+                        return value.length > 0 ? true : 'Pipeline source is required';
+                    },
                 });
                 if (!response.pipelineSource) {
                     console.error(colors__default["default"].red('Pipeline source is required'));
@@ -13248,10 +13627,10 @@
                 console.info(colors__default["default"].gray('--- Detailed Result ---'));
                 console.info({ isSuccessful, errors, warnings, outputParameters, executionReport });
             }
-            if (saveReport && saveReport.endsWith('.json')) {
+            if (executionReport !== null && saveReport && saveReport.endsWith('.json')) {
                 await promises.writeFile(saveReport, JSON.stringify(executionReport, null, 4) + '\n', 'utf-8');
             }
-            else if (saveReport && saveReport.endsWith('.md')) {
+            else if (executionReport !== null && saveReport && saveReport.endsWith('.md')) {
                 const executionReportString = executionReportJsonToString(executionReport);
                 await promises.writeFile(saveReport, executionReportString, 'utf-8');
             }
@@ -13294,15 +13673,15 @@
      * TODO: [🖇] What about symlinks? Maybe flag --follow-symlinks
      */
 
-    // TODO: !!!! List running services from REMOTE_SERVER_URLS
-    // TODO: !!!! Import directly from YML
+    // TODO: [🥺] List running services from REMOTE_SERVER_URLS
+    // TODO: [🥺] Import directly from YML
     /**
-     * @private !!!! Decide how to expose this
+     * @private [🥺] Decide how to expose this
      */
     const openapiJson = {
         openapi: '3.0.0',
         info: {
-            title: 'Promptbook Remote Server API (!!!! From YML)',
+            title: 'Promptbook Remote Server API ([🥺] From YML)',
             version: '1.0.0',
             description: 'API documentation for the Promptbook Remote Server',
         },
@@ -13925,7 +14304,7 @@
             // TODO: [main] !!4 Validate here userId (pass validator as dependency)
             let llm;
             if (isAnonymous === true) {
-                // Note: Anonymouse mode
+                // Note: Anonymous mode
                 // TODO: Maybe check that configuration is not empty
                 const { llmToolsConfiguration } = identification;
                 llm = createLlmToolsFromConfiguration(llmToolsConfiguration, { isVerbose });
@@ -13935,7 +14314,7 @@
                 llm = await createLlmExecutionTools(identification);
             }
             else {
-                throw new PipelineExecutionError(`You must provide either llmToolsConfiguration or non-anonymous mode must be propperly configured`);
+                throw new PipelineExecutionError(`You must provide either llmToolsConfiguration or non-anonymous mode must be properly configured`);
             }
             const customExecutionTools = createExecutionTools ? await createExecutionTools(identification) : {};
             const fs = customExecutionTools.fs || $provideFilesystemForNode();
@@ -13960,7 +14339,7 @@
             response.setHeader('X-Powered-By', 'Promptbook engine');
             next();
         });
-        // TODO: !!!! Expose openapiJson to consumer and also allow to add new routes
+        // TODO: [🥺] Expose openapiJson to consumer and also allow to add new routes
         app.use(OpenApiValidator__namespace.middleware({
             apiSpec: openapiJson,
             ignorePaths(path) {
@@ -14000,7 +14379,7 @@
 
                     **Server port:** ${port}
                     **Startup date:** ${startupDate.toISOString()}
-                    **Anonymouse mode:** ${isAnonymousModeAllowed ? 'enabled' : 'disabled'}
+                    **Anonymous mode:** ${isAnonymousModeAllowed ? 'enabled' : 'disabled'}
                     **Application mode:** ${isApplicationModeAllowed ? 'enabled' : 'disabled'}
                     ${block(!isApplicationModeAllowed || collection === null
             ? ''
@@ -14030,7 +14409,7 @@
                     To connect to this server use:
 
                     1) The client https://www.npmjs.com/package/@promptbook/remote-client
-                    2) OpenAI compatible client *(Not wotking yet)*
+                    2) OpenAI compatible client *(Not working yet)*
                     3) REST API
 
                     For more information look at:
@@ -14114,12 +14493,13 @@
         });
         function exportExecutionTask(executionTask, isFull) {
             // <- TODO: [🧠] This should be maybe method of `ExecutionTask` itself
-            const { taskType, taskId, status, errors, warnings, createdAt, updatedAt, currentValue } = executionTask;
+            const { taskType, promptbookVersion, taskId, title, status, errors, warnings, createdAt, updatedAt, currentValue, } = executionTask;
             if (isFull) {
                 return {
-                    nonce: '✨',
                     taskId,
+                    title,
                     taskType,
+                    promptbookVersion,
                     status,
                     errors: errors.map(serializeError),
                     warnings: warnings.map(serializeError),
@@ -14130,9 +14510,10 @@
             }
             else {
                 return {
-                    nonce: '✨',
                     taskId,
+                    title,
                     taskType,
+                    promptbookVersion,
                     status,
                     createdAt,
                     updatedAt,
@@ -14282,7 +14663,7 @@
                 }
             });
             // -----------
-            // TODO: [👒] Listing models (and checking configuration) probbably should go through REST API not Socket.io
+            // TODO: [👒] Listing models (and checking configuration) probably should go through REST API not Socket.io
             socket.on('listModels-request', async (request) => {
                 const { identification } = request;
                 if (isVerbose) {
@@ -14304,7 +14685,7 @@
                 }
             });
             // -----------
-            // TODO: [👒] Listing models (and checking configuration) probbably should go through REST API not Socket.io
+            // TODO: [👒] Listing models (and checking configuration) probably should go through REST API not Socket.io
             socket.on('preparePipeline-request', async (request) => {
                 const { identification, pipeline } = request;
                 if (isVerbose) {
@@ -14364,7 +14745,7 @@
         };
     }
     /**
-     * TODO: [🌡] Add CORS and security - probbably via `helmet`
+     * TODO: [🌡] Add CORS and security - probably via `helmet`
      * TODO: Split this file into multiple functions - handler for each request
      * TODO: Maybe use `$exportJson`
      * TODO: [🧠][🛍] Maybe not `isAnonymous: boolean` BUT `mode: 'ANONYMOUS'|'COLLECTION'`
@@ -14600,7 +14981,7 @@
         program.alias('ptbk');
         program.version(PROMPTBOOK_ENGINE_VERSION);
         program.description(CLAIM);
-        // Note: Theese options are valid for all commands
+        // Note: These options are valid for all commands
         $initializeAboutCommand(program);
         $initializeRunCommand(program);
         $initializeLoginCommand(program);
@@ -14640,37 +15021,6 @@
      * Note: [🟡] Code in this file should never be published outside of `@promptbook/cli`
      */
 
-    /**
-     * How is the model provider trusted?
-     *
-     * @public exported from `@promptbook/core`
-     */
-    // <- TODO: Maybe do better levels of trust
-    /**
-     * How is the model provider important?
-     *
-     * @public exported from `@promptbook/core`
-     */
-    const MODEL_ORDER = {
-        /**
-         * Top-tier models, e.g. OpenAI, Anthropic,...
-         */
-        TOP_TIER: 333,
-        /**
-         * Mid-tier models, e.g. Llama, Mistral, etc.
-         */
-        NORMAL: 100,
-        /**
-         * Low-tier models, e.g. Phi, Tiny, etc.
-         */
-        LOW_TIER: 0,
-    };
-    /**
-     * TODO: Add configuration schema and maybe some documentation link
-     * TODO: Maybe constrain LlmToolsConfiguration[number] by generic to ensure that `createConfigurationFromEnv` and `getBoilerplateConfiguration` always create same `packageName` and `className`
-     * TODO: [®] DRY Register logic
-     */
-
     /**
      * Registration of LLM provider metadata
      *
@@ -14686,7 +15036,7 @@
         className: 'AnthropicClaudeExecutionTools',
         envVariables: ['ANTHROPIC_CLAUDE_API_KEY'],
         trustLevel: 'CLOSED',
-        order: MODEL_ORDER.TOP_TIER,
+        order: MODEL_ORDERS.TOP_TIER,
         getBoilerplateConfiguration() {
             return {
                 title: 'Anthropic Claude',
@@ -14696,6 +15046,7 @@
                     apiKey: 'sk-ant-api03-',
                     isProxied: true,
                     remoteServerUrl: DEFAULT_REMOTE_SERVER_URL,
+                    maxRequestsPerMinute: DEFAULT_MAX_REQUESTS_PER_MINUTE,
                 },
             };
         },
@@ -14731,7 +15082,7 @@
     /**
      * List of available Anthropic Claude models with pricing
      *
-     * Note: Done at 2024-08-16
+     * Note: Done at 2025-05-06
      *
      * @see https://docs.anthropic.com/en/docs/models-overview
      * @public exported from `@promptbook/anthropic-claude`
@@ -14745,8 +15096,8 @@
                 modelName: 'claude-3-5-sonnet-20240620',
                 modelDescription: 'Latest Claude model with great reasoning, coding, and language understanding capabilities. 200K context window. Optimized balance of intelligence and speed.',
                 pricing: {
-                    prompt: computeUsage(`$3.00 / 1M tokens`),
-                    output: computeUsage(`$15.00 / 1M tokens`),
+                    prompt: computeUsage(`$2.50 / 1M tokens`),
+                    output: computeUsage(`$12.50 / 1M tokens`),
                 },
             },
             {
@@ -14755,8 +15106,8 @@
                 modelName: 'claude-3-opus-20240229',
                 modelDescription: 'Most capable Claude model excelling at complex reasoning, coding, and detailed instruction following. 200K context window. Best for sophisticated tasks requiring nuanced understanding.',
                 pricing: {
-                    prompt: computeUsage(`$15.00 / 1M tokens`),
-                    output: computeUsage(`$75.00 / 1M tokens`),
+                    prompt: computeUsage(`$12.00 / 1M tokens`),
+                    output: computeUsage(`$60.00 / 1M tokens`),
                 },
             },
             {
@@ -14815,8 +15166,8 @@
                 modelName: 'claude-3-7-sonnet-20250219',
                 modelDescription: 'Latest generation Claude model with advanced reasoning and language understanding. Enhanced capabilities over 3.5 with improved domain knowledge. 200K context window.',
                 pricing: {
-                    prompt: computeUsage(`$3.00 / 1M tokens`),
-                    output: computeUsage(`$15.00 / 1M tokens`),
+                    prompt: computeUsage(`$2.50 / 1M tokens`),
+                    output: computeUsage(`$12.50 / 1M tokens`),
                 },
             },
             {
@@ -14863,14 +15214,18 @@
     /**
      * Make UncertainNumber
      *
-     * @param value
+     * @param value value of the uncertain number, if `NaN` or `undefined`, it will be set to 0 and `isUncertain=true`
+     * @param isUncertain if `true`, the value is uncertain, otherwise depends on the value
      *
      * @private utility for initializating UncertainNumber
      */
-    function uncertainNumber(value) {
+    function uncertainNumber(value, isUncertain) {
         if (value === null || value === undefined || Number.isNaN(value)) {
             return UNCERTAIN_ZERO_VALUE;
         }
+        if (isUncertain === true) {
+            return { value, isUncertain };
+        }
         return { value };
     }
 
@@ -14936,6 +15291,8 @@
              * Anthropic Claude API client.
              */
             this.client = null;
+            const rate = this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE;
+            this.limiter = new Bottleneck__default["default"]({ minTime: 60000 / rate });
         }
         get title() {
             return 'Anthropic Claude';
@@ -14987,8 +15344,6 @@
                 //                                            <- TODO: [🌾] Make some global max cap for maxTokens
                 temperature: modelRequirements.temperature,
                 system: modelRequirements.systemMessage,
-                // <- TODO: [🈁] Use `seed` here AND/OR use is `isDeterministic` for entire execution tools
-                // <- Note: [🧆]
                 messages: [
                     {
                         role: 'user',
@@ -14997,14 +15352,14 @@
                         //    @see https://docs.anthropic.com/en/docs/test-and-evaluate/strengthen-guardrails/increase-consistency#specify-the-desired-output-format
                     },
                 ],
-                // TODO: Is here some equivalent of user identification?> user: this.options.user,
             };
             const start = $getCurrentDate();
-            let complete;
             if (this.options.isVerbose) {
                 console.info(colors__default["default"].bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
             }
-            const rawResponse = await client.messages.create(rawRequest).catch((error) => {
+            const rawResponse = await this.limiter
+                .schedule(() => client.messages.create(rawRequest))
+                .catch((error) => {
                 if (this.options.isVerbose) {
                     console.info(colors__default["default"].bgRed('error'), error);
                 }
@@ -15024,12 +15379,11 @@
                 throw new PipelineExecutionError(`Returned content is not "text" type but "${contentBlock.type}"`);
             }
             const resultContent = contentBlock.text;
-            // eslint-disable-next-line prefer-const
-            complete = $getCurrentDate();
+            const complete = $getCurrentDate();
             const usage = computeAnthropicClaudeUsage(rawPromptContent || '', resultContent || '', rawResponse);
             return exportJson({
                 name: 'promptResult',
-                message: `Result of \`AzureOpenAiExecutionTools.callChatModel\``,
+                message: `Result of \`AnthropicClaudeExecutionTools.callChatModel\``,
                 order: [],
                 value: {
                     content: resultContent,
@@ -15046,83 +15400,59 @@
                 },
             });
         }
-        /*
-        TODO: [👏]
-        public async callCompletionModel(
-            prompt: Pick<Prompt, 'content' | 'parameters' | 'modelRequirements'>,
-        ): Promise<CompletionPromptResult> {
-
+        /**
+         * Calls Anthropic Claude API to use a completion model.
+         */
+        async callCompletionModel(prompt) {
             if (this.options.isVerbose) {
                 console.info('🖋 Anthropic Claude callCompletionModel call');
             }
-
             const { content, parameters, modelRequirements } = prompt;
-
-            // TODO: [☂] Use here more modelRequirements
             if (modelRequirements.modelVariant !== 'COMPLETION') {
                 throw new PipelineExecutionError('Use callCompletionModel only for COMPLETION variant');
             }
-
+            const client = await this.getClient();
             const modelName = modelRequirements.modelName || this.getDefaultChatModel().modelName;
-            const modelSettings = {
+            const rawPromptContent = templateParameters(content, { ...parameters, modelName });
+            const rawRequest = {
                 model: modelName,
-                max_tokens: modelRequirements.maxTokens || 2000, // <- Note: 2000 is for lagacy reasons
-                //                                                  <- TODO: [🌾] Make some global max cap for maxTokens
-                // <- TODO: Use here `systemMessage`, `temperature` and `seed`
-            };
-
-            const rawRequest: xxxx.Completions.CompletionCreateParamsNonStreaming = {
-                ...modelSettings,
+                max_tokens_to_sample: modelRequirements.maxTokens || 2000,
+                temperature: modelRequirements.temperature,
                 prompt: rawPromptContent,
-                user: this.options.user,
             };
-            const start: string_date_iso8601 = $getCurrentDate();
-            let complete: string_date_iso8601;
-
-            if (this.options.isVerbose) {
-                console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
-            }
-            const rawResponse = await this.client.completions.create(rawRequest).catch((error) => {
-                    if (this.options.isVerbose) {
-                        console.info(colors.bgRed('error'), error);
-                    }
-                    throw error;
-                });
-
-
+            const start = $getCurrentDate();
+            const rawResponse = await this.limiter
+                .schedule(() => client.completions.create(rawRequest))
+                .catch((error) => {
+                if (this.options.isVerbose) {
+                    console.info(colors__default["default"].bgRed('error'), error);
+                }
+                throw error;
+            });
             if (this.options.isVerbose) {
-                console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
-            }
-
-            if (!rawResponse.choices[0]) {
-                throw new PipelineExecutionError('No choises from Anthropic Claude');
+                console.info(colors__default["default"].bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
             }
-
-            if (rawResponse.choices.length > 1) {
-                // TODO: This should be maybe only warning
-                throw new PipelineExecutionError('More than one choise from Anthropic Claude');
+            if (!rawResponse.completion) {
+                throw new PipelineExecutionError('No completion from Anthropic Claude');
             }
-
-            const resultContent = rawResponse.choices[0].text;
-            // eslint-disable-next-line prefer-const
-            complete = $getCurrentDate();
-            const usage = { price: 'UNKNOWN', inputTokens: 0, outputTokens: 0 /* <- TODO: [🐞] Compute usage * / } satisfies Usage;
-
-
-
-            return $exportJson({ name: 'promptResult',message: Result of \`AzureOpenAiExecutionTools callChatModel\`, order: [],value:{
-                content: resultContent,
-                modelName: rawResponse.model || model,
-                timing: {
-                    start,
-                    complete,
+            const resultContent = rawResponse.completion;
+            const complete = $getCurrentDate();
+            const usage = computeAnthropicClaudeUsage(rawPromptContent, resultContent, rawResponse);
+            return exportJson({
+                name: 'promptResult',
+                message: `Result of \`AnthropicClaudeExecutionTools.callCompletionModel\``,
+                order: [],
+                value: {
+                    content: resultContent,
+                    modelName: rawResponse.model || modelName,
+                    timing: { start, complete },
+                    usage,
+                    rawPromptContent,
+                    rawRequest,
+                    rawResponse,
                 },
-                usage,
-                rawResponse,
-                // <- [🗯]
             });
         }
-        */
         // <- Note: [🤖] callXxxModel
         /**
          * Get the model that should be used as default
@@ -15131,7 +15461,7 @@
             const model = ANTHROPIC_CLAUDE_MODELS.find(({ modelName }) => modelName.startsWith(defaultModelName));
             if (model === undefined) {
                 throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                          Cannot find model in OpenAI models with name "${defaultModelName}" which should be used as default.
+                          Cannot find model in Anthropic Claude models with name "${defaultModelName}" which should be used as default.
 
                           Available models:
                           ${block(ANTHROPIC_CLAUDE_MODELS.map(({ modelName }) => `- "${modelName}"`).join('\n'))}
@@ -15224,9 +15554,9 @@
         title: 'Azure Open AI',
         packageName: '@promptbook/azure-openai',
         className: 'AzureOpenAiExecutionTools',
-        envVariables: ['AZUREOPENAI_RESOURCE_NAME', 'AZUREOPENAI_DEPLOYMENT_NAME', 'AZUREOPENAI_API_KEY'],
+        envVariables: ['AZUREOPENAI_API_KEY', 'AZUREOPENAI_RESOURCE_NAME', 'AZUREOPENAI_DEPLOYMENT_NAME'],
         trustLevel: 'CLOSED_BUSINESS',
-        order: MODEL_ORDER.NORMAL,
+        order: MODEL_ORDERS.NORMAL,
         getBoilerplateConfiguration() {
             return {
                 title: 'Azure Open AI',
@@ -15234,6 +15564,9 @@
                 className: 'AzureOpenAiExecutionTools',
                 options: {
                     apiKey: 'sk-',
+                    resourceName: 'my-resource-name',
+                    deploymentName: 'my-deployment-name',
+                    maxRequestsPerMinute: DEFAULT_MAX_REQUESTS_PER_MINUTE,
                 },
             };
         },
@@ -15247,15 +15580,15 @@
                     packageName: '@promptbook/azure-openai',
                     className: 'AzureOpenAiExecutionTools',
                     options: {
+                        apiKey: env.AZUREOPENAI_API_KEY,
                         resourceName: env.AZUREOPENAI_RESOURCE_NAME,
                         deploymentName: env.AZUREOPENAI_DEPLOYMENT_NAME,
-                        apiKey: env.AZUREOPENAI_API_KEY,
                     },
                 };
             }
-            else if (typeof env.AZUREOPENAI_RESOURCE_NAME === 'string' ||
-                typeof env.AZUREOPENAI_DEPLOYMENT_NAME === 'string' ||
-                typeof env.AZUREOPENAI_API_KEY === 'string') {
+            else if (typeof env.AZUREOPENAI_API_KEY === 'string' ||
+                typeof env.AZUREOPENAI_RESOURCE_NAME === 'string' ||
+                typeof env.AZUREOPENAI_DEPLOYMENT_NAME === 'string') {
                 return null;
                 /*
                 Note: [🗨] Partial configuration is handled more gracefully elsewhere
@@ -15284,7 +15617,7 @@
     /**
      * List of available OpenAI models with pricing
      *
-     * Note: Done at 2024-05-20
+     * Note: Done at 2025-05-06
      *
      * @see https://platform.openai.com/docs/models/
      * @see https://openai.com/api/pricing/
@@ -15545,7 +15878,7 @@
                 modelName: 'text-embedding-3-large',
                 modelDescription: "OpenAI's most capable text embedding model designed for high-quality embeddings for complex similarity tasks and information retrieval.",
                 pricing: {
-                    prompt: computeUsage(`$0.13  / 1M tokens`),
+                    prompt: computeUsage(`$0.13 / 1M tokens`),
                     // TODO: [🏏] Leverage the batch API @see https://platform.openai.com/docs/guides/batch
                     output: 0, // <- Note: [🆖] In Embedding models you dont pay for output
                 },
@@ -15638,8 +15971,8 @@
                 modelName: 'gpt-4o-mini',
                 modelDescription: 'Smaller, more cost-effective version of GPT-4o with good performance across text, vision, and audio tasks at reduced complexity.',
                 pricing: {
-                    prompt: computeUsage(`$3.00 / 1M tokens`),
-                    output: computeUsage(`$9.00 / 1M tokens`),
+                    prompt: computeUsage(`$0.15 / 1M tokens`),
+                    output: computeUsage(`$0.60 / 1M tokens`),
                 },
             },
             /**/
@@ -15661,7 +15994,7 @@
                 modelTitle: 'o1-preview-2024-09-12',
                 modelName: 'o1-preview-2024-09-12',
                 modelDescription: 'September 2024 version of O1 preview with specialized reasoning capabilities for complex tasks requiring precise analytical thinking.',
-                //             <- TODO: [💩] Some better system to organize theese date suffixes and versions
+                //             <- TODO: [💩] Some better system to organize these date suffixes and versions
                 pricing: {
                     prompt: computeUsage(`$15.00 / 1M tokens`),
                     output: computeUsage(`$60.00 / 1M tokens`),
@@ -15764,6 +16097,10 @@
              * OpenAI Azure API client.
              */
             this.client = null;
+            // TODO: Allow configuring rate limits via options
+            this.limiter = new Bottleneck__default["default"]({
+                minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE),
+            });
         }
         get title() {
             return 'Azure OpenAI';
@@ -15841,7 +16178,9 @@
                     console.info(colors__default["default"].bgWhite('messages'), JSON.stringify(messages, null, 4));
                 }
                 const rawRequest = [modelName, messages, modelSettings];
-                const rawResponse = await this.withTimeout(client.getChatCompletions(...rawRequest)).catch((error) => {
+                const rawResponse = await this.limiter
+                    .schedule(() => this.withTimeout(client.getChatCompletions(...rawRequest)))
+                    .catch((error) => {
                     if (this.options.isVerbose) {
                         console.info(colors__default["default"].bgRed('error'), error);
                     }
@@ -15937,7 +16276,9 @@
                     [rawPromptContent],
                     modelSettings,
                 ];
-                const rawResponse = await this.withTimeout(client.getCompletions(...rawRequest)).catch((error) => {
+                const rawResponse = await this.limiter
+                    .schedule(() => this.withTimeout(client.getCompletions(...rawRequest)))
+                    .catch((error) => {
                     if (this.options.isVerbose) {
                         console.info(colors__default["default"].bgRed('error'), error);
                     }
@@ -16012,7 +16353,7 @@
             });
         }
         /**
-         * Changes Azure error (which is not propper Error but object) to propper Error
+         * Changes Azure error (which is not proper Error but object) to proper Error
          */
         transformAzureError(azureError) {
             if (azureError instanceof UnexpectedError) {
@@ -16078,7 +16419,7 @@
         className: 'DeepseekExecutionTools',
         envVariables: ['DEEPSEEK_GENERATIVE_AI_API_KEY'],
         trustLevel: 'UNTRUSTED',
-        order: MODEL_ORDER.NORMAL,
+        order: MODEL_ORDERS.NORMAL,
         getBoilerplateConfiguration() {
             return {
                 title: 'Deepseek',
@@ -16158,12 +16499,14 @@
         const { vercelProvider, availableModels, userId, additionalChatSettings = {} } = options;
         if (!/Vercel/i.test(title)) {
             title = `${title} (through Vercel)`;
+            // <- TODO: [🧈] Maybe standartize the suffix
         } /* not else */
         if (description === undefined) {
             description = `Implementation of ${title} through Vercel`;
         } /* not else */
         if (!/Vercel/i.test(description)) {
             description = `${description} (through Vercel)`;
+            // <- TODO: [🧈] Maybe standartize the suffix
         } /* not else */
         return {
             title,
@@ -16281,7 +16624,7 @@
     /**
      * List of available Deepseek models with descriptions
      *
-     * Note: Done at 2025-04-22
+     * Note: Done at 2025-05-06
      *
      * @see https://www.deepseek.com/models
      * @public exported from `@promptbook/deepseek`
@@ -16295,8 +16638,8 @@
                 modelName: 'deepseek-chat',
                 modelDescription: 'General-purpose language model with strong performance across conversation, reasoning, and content generation. 128K context window with excellent instruction following capabilities.',
                 pricing: {
-                    prompt: computeUsage(`$1.00 / 1M tokens`),
-                    output: computeUsage(`$2.00 / 1M tokens`),
+                    prompt: computeUsage(`$0.80 / 1M tokens`),
+                    output: computeUsage(`$1.60 / 1M tokens`),
                 },
             },
             {
@@ -16305,8 +16648,8 @@
                 modelName: 'deepseek-reasoner',
                 modelDescription: 'Specialized model focused on complex reasoning tasks like mathematical problem-solving and logical analysis. Enhanced step-by-step reasoning with explicit chain-of-thought processes. 128K context window.',
                 pricing: {
-                    prompt: computeUsage(`$4.00 / 1M tokens`),
-                    output: computeUsage(`$8.00 / 1M tokens`),
+                    prompt: computeUsage(`$3.50 / 1M tokens`),
+                    output: computeUsage(`$7.00 / 1M tokens`),
                 },
             },
             {
@@ -16401,7 +16744,7 @@
         className: 'GoogleExecutionTools',
         envVariables: ['GOOGLE_GENERATIVE_AI_API_KEY'],
         trustLevel: 'CLOSED',
-        order: MODEL_ORDER.NORMAL,
+        order: MODEL_ORDERS.NORMAL,
         getBoilerplateConfiguration() {
             return {
                 title: 'Google Gemini',
@@ -16440,7 +16783,7 @@
     /**
      * List of available Google models with descriptions
      *
-     * Note: Done at 2025-04-22
+     * Note: Done at 2025-05-06
      *
      * @see https://ai.google.dev/models/gemini
      * @public exported from `@promptbook/google`
@@ -16454,8 +16797,8 @@
                 modelName: 'gemini-2.5-pro-preview-03-25',
                 modelDescription: 'Latest advanced multimodal model with exceptional reasoning, tool use, and instruction following. 1M token context window with improved vision capabilities for complex visual tasks.',
                 pricing: {
-                    prompt: computeUsage(`$7.00 / 1M tokens`),
-                    output: computeUsage(`$21.00 / 1M tokens`),
+                    prompt: computeUsage(`$8.00 / 1M tokens`),
+                    output: computeUsage(`$24.00 / 1M tokens`),
                 },
             },
             {
@@ -16494,8 +16837,8 @@
                 modelName: 'gemini-1.5-flash',
                 modelDescription: 'Efficient model balancing speed and quality for general-purpose applications. 1M token context window with good multimodal capabilities and quick response times.',
                 pricing: {
-                    prompt: computeUsage(`$0.35 / 1M tokens`),
-                    output: computeUsage(`$1.05 / 1M tokens`),
+                    prompt: computeUsage(`$0.25 / 1M tokens`),
+                    output: computeUsage(`$0.75 / 1M tokens`),
                 },
             },
             {
@@ -16562,8 +16905,8 @@
                 modelName: 'gemini-1.5-pro',
                 modelDescription: 'Flagship multimodal model with strong performance across text, code, vision, and audio tasks. 1M token context window with excellent reasoning capabilities.',
                 pricing: {
-                    prompt: computeUsage(`$7.00 / 1M tokens`),
-                    output: computeUsage(`$21.00 / 1M tokens`),
+                    prompt: computeUsage(`$6.00 / 1M tokens`),
+                    output: computeUsage(`$18.00 / 1M tokens`),
                 },
             },
             {
@@ -16666,7 +17009,7 @@
         className: 'OpenAiExecutionTools',
         envVariables: ['OPENAI_API_KEY'],
         trustLevel: 'CLOSED',
-        order: MODEL_ORDER.TOP_TIER,
+        order: MODEL_ORDERS.TOP_TIER,
         getBoilerplateConfiguration() {
             return {
                 title: 'Open AI',
@@ -16674,6 +17017,7 @@
                 className: 'OpenAiExecutionTools',
                 options: {
                     apiKey: 'sk-',
+                    maxRequestsPerMinute: DEFAULT_MAX_REQUESTS_PER_MINUTE,
                 },
             };
         },
@@ -16693,9 +17037,9 @@
         },
     });
     /**
-     * @@@ registration1 of default configuration for Open AI
+     * Registration of the OpenAI Assistant metadata
      *
-     * Note: [🏐] Configurations registrations are done in @@@ BUT constructor @@@
+     * Note: [🏐] Configurations registrations are done in the metadata registration section, but the constructor registration is handled separately.
      *
      * @public exported from `@promptbook/core`
      * @public exported from `@promptbook/wizzard`
@@ -16708,7 +17052,7 @@
         envVariables: null,
         //            <- TODO: ['OPENAI_API_KEY', 'OPENAI_ASSISTANT_ID']
         trustLevel: 'CLOSED',
-        order: MODEL_ORDER.NORMAL,
+        order: MODEL_ORDERS.NORMAL,
         getBoilerplateConfiguration() {
             return {
                 title: 'Open AI Assistant',
@@ -16717,6 +17061,7 @@
                 options: {
                     apiKey: 'sk-',
                     assistantId: 'asst_',
+                    maxRequestsPerMinute: DEFAULT_MAX_REQUESTS_PER_MINUTE,
                 },
             };
         },
@@ -16763,13 +17108,21 @@
         }
         const inputTokens = rawResponse.usage.prompt_tokens;
         const outputTokens = ((_b = rawResponse.usage) === null || _b === void 0 ? void 0 : _b.completion_tokens) || 0;
-        const modelInfo = OPENAI_MODELS.find((model) => model.modelName === rawResponse.model);
+        let isUncertain = false;
+        let modelInfo = OPENAI_MODELS.find((model) => model.modelName === rawResponse.model);
+        if (modelInfo === undefined) {
+            // Note: Model is not in the list of known models, fallback to the family of the models and mark price as uncertain
+            modelInfo = OPENAI_MODELS.find((model) => (rawResponse.model || SALT_NONCE).startsWith(model.modelName));
+            if (modelInfo !== undefined) {
+                isUncertain = true;
+            }
+        }
         let price;
         if (modelInfo === undefined || modelInfo.pricing === undefined) {
             price = uncertainNumber();
         }
         else {
-            price = uncertainNumber(inputTokens * modelInfo.pricing.prompt + outputTokens * modelInfo.pricing.output);
+            price = uncertainNumber(inputTokens * modelInfo.pricing.prompt + outputTokens * modelInfo.pricing.output, isUncertain);
         }
         return {
             price,
@@ -16804,6 +17157,10 @@
              * OpenAI API client.
              */
             this.client = null;
+            // TODO: Allow configuring rate limits via options
+            this.limiter = new Bottleneck__default["default"]({
+                minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE),
+            });
         }
         get title() {
             return 'OpenAI';
@@ -16903,11 +17260,12 @@
                 user: (_a = this.options.userId) === null || _a === void 0 ? void 0 : _a.toString(),
             };
             const start = $getCurrentDate();
-            let complete;
             if (this.options.isVerbose) {
                 console.info(colors__default["default"].bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
             }
-            const rawResponse = await client.chat.completions.create(rawRequest).catch((error) => {
+            const rawResponse = await this.limiter
+                .schedule(() => client.chat.completions.create(rawRequest))
+                .catch((error) => {
                 assertsError(error);
                 if (this.options.isVerbose) {
                     console.info(colors__default["default"].bgRed('error'), error);
@@ -16917,6 +17275,7 @@
             if (this.options.isVerbose) {
                 console.info(colors__default["default"].bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
             }
+            const complete = $getCurrentDate();
             if (!rawResponse.choices[0]) {
                 throw new PipelineExecutionError('No choises from OpenAI');
             }
@@ -16925,8 +17284,6 @@
                 throw new PipelineExecutionError('More than one choise from OpenAI');
             }
             const resultContent = rawResponse.choices[0].message.content;
-            // eslint-disable-next-line prefer-const
-            complete = $getCurrentDate();
             const usage = computeOpenAiUsage(content || '', resultContent || '', rawResponse);
             if (resultContent === null) {
                 throw new PipelineExecutionError('No response message from OpenAI');
@@ -16980,11 +17337,12 @@
                 user: (_a = this.options.userId) === null || _a === void 0 ? void 0 : _a.toString(),
             };
             const start = $getCurrentDate();
-            let complete;
             if (this.options.isVerbose) {
                 console.info(colors__default["default"].bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
             }
-            const rawResponse = await client.completions.create(rawRequest).catch((error) => {
+            const rawResponse = await this.limiter
+                .schedule(() => client.completions.create(rawRequest))
+                .catch((error) => {
                 assertsError(error);
                 if (this.options.isVerbose) {
                     console.info(colors__default["default"].bgRed('error'), error);
@@ -16994,6 +17352,7 @@
             if (this.options.isVerbose) {
                 console.info(colors__default["default"].bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
             }
+            const complete = $getCurrentDate();
             if (!rawResponse.choices[0]) {
                 throw new PipelineExecutionError('No choises from OpenAI');
             }
@@ -17002,8 +17361,6 @@
                 throw new PipelineExecutionError('More than one choise from OpenAI');
             }
             const resultContent = rawResponse.choices[0].text;
-            // eslint-disable-next-line prefer-const
-            complete = $getCurrentDate();
             const usage = computeOpenAiUsage(content || '', resultContent || '', rawResponse);
             return exportJson({
                 name: 'promptResult',
@@ -17044,11 +17401,12 @@
                 model: modelName,
             };
             const start = $getCurrentDate();
-            let complete;
             if (this.options.isVerbose) {
                 console.info(colors__default["default"].bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
             }
-            const rawResponse = await client.embeddings.create(rawRequest).catch((error) => {
+            const rawResponse = await this.limiter
+                .schedule(() => client.embeddings.create(rawRequest))
+                .catch((error) => {
                 assertsError(error);
                 if (this.options.isVerbose) {
                     console.info(colors__default["default"].bgRed('error'), error);
@@ -17058,12 +17416,11 @@
             if (this.options.isVerbose) {
                 console.info(colors__default["default"].bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
             }
+            const complete = $getCurrentDate();
             if (rawResponse.data.length !== 1) {
                 throw new PipelineExecutionError(`Expected exactly 1 data item in response, got ${rawResponse.data.length}`);
             }
             const resultContent = rawResponse.data[0].embedding;
-            // eslint-disable-next-line prefer-const
-            complete = $getCurrentDate();
             const usage = computeOpenAiUsage(content || '', '', 
             // <- Note: Embedding does not have result content
             rawResponse);
@@ -17091,7 +17448,8 @@
          * Get the model that should be used as default
          */
         getDefaultModel(defaultModelName) {
-            const model = OPENAI_MODELS.find(({ modelName }) => modelName === defaultModelName);
+            // Note: Match exact or prefix for model families
+            const model = OPENAI_MODELS.find(({ modelName }) => modelName === defaultModelName || modelName.startsWith(defaultModelName));
             if (model === undefined) {
                 throw new UnexpectedError(spaceTrim__default["default"]((block) => `
                             Cannot find model in OpenAI models with name "${defaultModelName}" which should be used as default.
@@ -17133,7 +17491,7 @@
     /**
      * Execution Tools for calling OpenAI API Assistants
      *
-     * This is usefull for calling OpenAI API with a single assistant, for more wide usage use `OpenAiExecutionTools`.
+     * This is useful for calling OpenAI API with a single assistant, for more wide usage use `OpenAiExecutionTools`.
      *
      * @public exported from `@promptbook/openai`
      */
@@ -17146,6 +17504,7 @@
         constructor(options) {
             super(options);
             this.assistantId = options.assistantId;
+            // TODO: [👱] Make limiter same as in `OpenAiExecutionTools`
         }
         get title() {
             return 'OpenAI Assistant';
@@ -17347,9 +17706,9 @@
      */
     const _OpenAiRegistration = $llmToolsRegister.register(createOpenAiExecutionTools);
     /**
-     * @@@ registration2
+     * Registration of the OpenAI Assistant provider
      *
-     * Note: [🏐] Configurations registrations are done in @@@ BUT constructor @@@
+     * Note: [🏐] Configurations registrations are done in register-constructor.ts BUT constructor register-constructor.ts
      *
      * @public exported from `@promptbook/openai`
      * @public exported from `@promptbook/wizzard`
@@ -17362,9 +17721,8 @@
      */
 
     /**
-     * Create a filename for intermediate cache for scrapers
-     *
-     * Note: It also checks if directory exists and creates it if not
+     * Retrieves an intermediate source for a scraper based on the knowledge source.
+     * Manages the caching and retrieval of intermediate scraper results for optimized performance.
      *
      * @private as internal utility for scrapers
      */
@@ -17507,7 +17865,7 @@
             const knowledge = await Promise.all(
             // TODO: [🪂] Do not send all at once but in chunks
             knowledgeTextPieces.map(async (knowledgeTextPiece, i) => {
-                // Note: Theese are just default values, they will be overwritten by the actual values:
+                // Note: These are just default values, they will be overwritten by the actual values:
                 let name = `piece-${i}`;
                 let title = spaceTrim__default["default"](knowledgeTextPiece.substring(0, 100));
                 const knowledgePieceContent = spaceTrim__default["default"](knowledgeTextPiece);
@@ -17591,14 +17949,14 @@
         packageName: '@promptbook/boilerplate',
         className: 'BoilerplateScraper',
         mimeTypes: [
-            '@@@/@@@',
-            // <- TODO: @@@ Add compatible mime types with Boilerplate scraper
+            '@@/@@',
+            // <- TODO: @@ Add compatible mime types with Boilerplate scraper
         ],
-        documentationUrl: 'https://github.com/webgptorg/promptbook/discussions/@@@',
+        documentationUrl: 'https://github.com/webgptorg/promptbook/discussions/@@',
         isAvilableInBrowser: false,
         // <- Note: [🌏] Only `MarkdownScraper` makes sense to be available in the browser, for scraping non-markdown sources in the browser use a remote server
         requiredExecutables: [
-        /* @@@ 'Pandoc' */
+        /* @@ 'Pandoc' */
         ],
     }); /* <- Note: [🤛] */
     /**
@@ -17616,7 +17974,7 @@
      */
 
     /**
-     * Scraper of @@@ files
+     * Scraper of @@ files
      *
      * @see `documentationUrl` for more details
      * @public exported from `@promptbook/boilerplate`
@@ -17634,30 +17992,30 @@
             this.markdownScraper = new MarkdownScraper(tools, options);
         }
         /**
-         * Convert the `.@@@`  to `.md` file and returns intermediate source
+         * Convert the `.@@`  to `.md` file and returns intermediate source
          *
          * Note: `$` is used to indicate that this function is not a pure function - it leaves files on the disk and you are responsible for cleaning them by calling `destroy` method of returned object
          */
         async $convert(source) {
             var _a;
             const { rootDirname = process.cwd(), cacheDirname = DEFAULT_SCRAPE_CACHE_DIRNAME, intermediateFilesStrategy = DEFAULT_INTERMEDIATE_FILES_STRATEGY, isVerbose = DEFAULT_IS_VERBOSE, } = this.options;
-            // TODO: @@@ Preserve or delete
+            // TODO: @@ Preserve or delete
             if (!$isRunningInNode()) {
                 throw new KnowledgeScrapeError('BoilerplateScraper is only supported in Node environment');
             }
-            // TODO: @@@ Preserve or delete
+            // TODO: @@ Preserve or delete
             if (this.tools.fs === undefined) {
                 throw new EnvironmentMismatchError('Can not scrape boilerplates without filesystem tools');
                 //          <- TODO: [🧠] What is the best error type here`
             }
-            // TODO: @@@ Preserve, delete or modify
+            // TODO: @@ Preserve, delete or modify
             if (((_a = this.tools.executables) === null || _a === void 0 ? void 0 : _a.pandocPath) === undefined) {
                 throw new MissingToolsError('Pandoc is required for scraping .docx files');
             }
-            // TODO: @@@ Preserve, delete or modify
+            // TODO: @@ Preserve, delete or modify
             if (source.filename === null) {
                 // TODO: [🧠] Maybe save file as temporary
-                throw new KnowledgeScrapeError('When parsing .@@@ file, it must be real file in the file system');
+                throw new KnowledgeScrapeError('When parsing .@@ file, it must be real file in the file system');
             }
             const extension = getFileExtension(source.filename);
             const cacheFilehandler = await getScraperIntermediateSource(source, {
@@ -17667,7 +18025,7 @@
                 extension: 'md',
                 isVerbose,
             });
-            // TODO: @@@ Preserve, delete or modify
+            // TODO: @@ Preserve, delete or modify
             // Note: Running Pandoc ONLY if the file in the cache does not exist
             if (!(await isFileExisting(cacheFilehandler.filename, this.tools.fs))) {
                 const command = `"${this.tools.executables.pandocPath}" -f ${extension} -t markdown "${source.filename}" -o "${cacheFilehandler.filename}"`;
@@ -17693,7 +18051,7 @@
          */
         async scrape(source) {
             const cacheFilehandler = await this.$convert(source);
-            // TODO: @@@ Preserve, delete or modify
+            // TODO: @@ Preserve, delete or modify
             const markdownSource = {
                 source: source.source,
                 filename: cacheFilehandler.filename,
@@ -17724,7 +18082,7 @@
      * TODO: [👣] Converted documents can act as cached items - there is no need to run conversion each time
      * TODO: [🪂] Do it in parallel
      * Note: No need to aggregate usage here, it is done by intercepting the llmTools
-     * @@@ Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+     * @@ Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
      */
 
     /**
@@ -18058,7 +18416,8 @@
      */
 
     /**
-     * @@@
+     * Creates a scraper for legacy document formats (.doc, .rtf, etc).
+     * Uses LibreOffice for conversion to extract content from older document formats.
      *
      * @public exported from `@promptbook/legacy-documents`
      */
@@ -18085,7 +18444,7 @@
      */
 
     /**
-     * @@@
+     * Creates a scraper for document content.
      *
      * @public exported from `@promptbook/documents`
      */
@@ -18112,7 +18471,7 @@
      */
 
     /**
-     * @@@
+     * Creates a scraper for markdown content.
      *
      * @public exported from `@promptbook/markdown-utils`
      */
@@ -18218,8 +18577,8 @@
                 extension: 'md',
                 isVerbose,
             });
-            // TODO: @@@ Preserve, delete or modify
-            // Note: Running Pandoc ONLY if the file in the cache does not exist
+            // TODO: Determine if Markitdown conversion should run only if the cache file doesn't exist, or always.
+            // Note: Running Markitdown conversion ONLY if the file in the cache does not exist
             if (!(await isFileExisting(cacheFilehandler.filename, this.tools.fs))) {
                 const src = source.filename || source.url || null;
                 // console.log('!!', { src, source, cacheFilehandler });
@@ -18241,11 +18600,11 @@
             return cacheFilehandler;
         }
         /**
-         * Scrapes the docx file and returns the knowledge pieces or `null` if it can't scrape it
+         * Scrapes the source document (PDF, DOCX, etc.) and returns the knowledge pieces or `null` if it can't scrape it.
          */
         async scrape(source) {
             const cacheFilehandler = await this.$convert(source);
-            // TODO: @@@ Preserve, delete or modify
+            // TODO: Ensure this correctly creates the source object for the internal MarkdownScraper using the converted file.
             const markdownSource = {
                 source: source.source,
                 filename: cacheFilehandler.filename,
@@ -18389,7 +18748,8 @@
      */
 
     /**
-     * @@@
+     * Factory function to create an instance of PdfScraper.
+     * It bundles the scraper class with its metadata.
      *
      * @public exported from `@promptbook/pdf`
      */
@@ -18565,7 +18925,8 @@
      */
 
     /**
-     * @@@
+     * Factory function to create an instance of WebsiteScraper.
+     * It bundles the scraper class with its metadata.
      *
      * @public exported from `@promptbook/website-crawler`
      */