@promptbook/cli 0.92.0-9 → 0.93.0

package/esm/index.es.js

@@ -21,13 +21,13 @@ import { lookup, extension } from 'mime-types';
 import glob from 'glob-promise';
 import moment from 'moment';
 import express from 'express';
+import * as OpenApiValidator from 'express-openapi-validator';
 import http from 'http';
 import { Server } from 'socket.io';
-import * as OpenApiValidator from 'express-openapi-validator';
 import swaggerUi from 'swagger-ui-express';
 import Anthropic from '@anthropic-ai/sdk';
-import { OpenAIClient, AzureKeyCredential } from '@azure/openai';
 import Bottleneck from 'bottleneck';
+import { OpenAIClient, AzureKeyCredential } from '@azure/openai';
 import OpenAI from 'openai';
 import { Readability } from '@mozilla/readability';
 import { JSDOM } from 'jsdom';
@@ -47,7 +47,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.92.0-9';
+const PROMPTBOOK_ENGINE_VERSION = '0.93.0';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -88,7 +88,7 @@ const REMOTE_SERVER_URLS = [
  * 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
@@ -163,6 +163,21 @@ const DEFAULT_BOOK_OUTPUT_PARAMETER_NAME = 'result';
  * @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
  *
@@ -247,6 +262,7 @@ const DEFAULT_MAX_PARALLEL_COUNT = 5; // <- TODO: [🤹‍♂️]
  * @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
@@ -318,7 +334,7 @@ const MOMENT_ARG_THRESHOLDS = {
 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`
  */
@@ -329,13 +345,13 @@ const DEFAULT_CSV_SETTINGS = Object.freeze({
     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`
  */
@@ -347,7 +363,15 @@ const DEFAULT_IS_AUTO_INSTALLED = false;
  */
 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
  */
@@ -504,7 +528,7 @@ class UnexpectedError extends Error {
                     ${block(message)}
 
                     Note: This error should not happen.
-                    It's probbably a bug in the pipeline collection
+                    It's probably a bug in the pipeline collection
 
                     Please report issue:
                     ${block(getErrorReportUrl(new Error(message)).href)}
@@ -687,7 +711,8 @@ class NotYetImplementedError extends Error {
 }
 
 /**
- * @@@
+ * 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
  *
@@ -698,10 +723,10 @@ function $getGlobalScope() {
 }
 
 /**
- * @@@
+ * Normalizes a text string to SCREAMING_CASE (all uppercase with underscores).
  *
- * @param text @@@
- * @returns @@@
+ * @param text The text string to be converted to SCREAMING_CASE format.
+ * @returns The normalized text in SCREAMING_CASE format.
  * @example 'HELLO_WORLD'
  * @example 'I_LOVE_PROMPTBOOK'
  * @public exported from `@promptbook/utils`
@@ -753,10 +778,10 @@ function normalizeTo_SCREAMING_CASE(text) {
  */
 
 /**
- * @@@
+ * Normalizes a text string to snake_case format.
  *
- * @param text @@@
- * @returns @@@
+ * @param text The text string to be converted to snake_case format.
+ * @returns The normalized text in snake_case format.
  * @example 'hello_world'
  * @example 'i_love_promptbook'
  * @public exported from `@promptbook/utils`
@@ -766,11 +791,11 @@ function normalizeTo_snake_case(text) {
 }
 
 /**
- * Register is @@@
+ * Global registry for storing and managing registered entities of a given type.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it accesses and adds variables in global scope.
  *
- * @private internal utility, exported are only signleton instances of this class
+ * @private internal utility, exported are only singleton instances of this class
  */
 class $Register {
     constructor(registerName) {
@@ -814,10 +839,10 @@ class $Register {
 }
 
 /**
- * @@@
+ * 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');
@@ -826,10 +851,10 @@ const $llmToolsMetadataRegister = new $Register('llm_tools_metadata');
  */
 
 /**
- * @@@
+ * 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');
@@ -981,7 +1006,7 @@ function $registeredLlmToolsMessage() {
  * 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
@@ -1034,15 +1059,12 @@ function jsonParse(value) {
         }
         throw new Error(spaceTrim((block) => `
                     ${block(error.message)}
-            
+
                     The JSON text:
                     ${block(value)}
                 `));
     }
 }
-/**
- * TODO: !!!! Use in Promptbook.studio
- */
 
 /**
  * Convert identification to Promptbook token
@@ -1082,7 +1104,7 @@ function promptbookTokenToIdentification(promptbookToken) {
  * 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
@@ -1092,7 +1114,8 @@ function TODO_USE(...value) {
 }
 
 /**
- * @@@
+ * 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`
  */
@@ -1467,8 +1490,12 @@ function checkSerializableAsJson(options) {
  */
 
 /**
- * @@@
+ * Creates a deep clone of the given object
  *
+ * Note: This method only works for objects that are fully serializable to JSON and do not contain functions, Dates, or special types.
+ *
+ * @param objectValue The object to clone.
+ * @returns A deep, writable clone of the input object.
  * @public exported from `@promptbook/utils`
  */
 function deepClone(objectValue) {
@@ -1523,6 +1550,26 @@ function exportJson(options) {
  * 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
  *
@@ -1550,13 +1597,19 @@ const ORDER_OF_PIPELINE_JSON = [
  */
 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
  */
@@ -1646,7 +1699,7 @@ function stringifyPipelineJson(pipeline) {
     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
@@ -1721,7 +1774,7 @@ function isValidFilePath(filename) {
  * 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
  *
@@ -1991,10 +2044,10 @@ for (let i = 0; i < defaultDiacriticsRemovalMap.length; i++) {
 */
 
 /**
- * @@@
+ * Removes diacritic marks (accents) from characters in a string.
  *
- * @param input @@@
- * @returns @@@
+ * @param input The string containing diacritics to be normalized.
+ * @returns The string with diacritics removed or normalized.
  * @public exported from `@promptbook/utils`
  */
 function removeDiacritics(input) {
@@ -2008,10 +2061,10 @@ function removeDiacritics(input) {
  */
 
 /**
- * @@@
+ * 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`
@@ -2059,11 +2112,11 @@ function normalizeToKebabCase(text) {
  */
 
 /**
- * @@@
+ * 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) {
@@ -2083,7 +2136,8 @@ function titleToName(value) {
 }
 
 /**
- * @@@
+ * 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`
  */
@@ -2092,7 +2146,10 @@ function nameToSubfolderPath(name) {
 }
 
 /**
- * @@@
+ * 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`
  */
@@ -2105,7 +2162,8 @@ class FileCacheStorage {
         }
     }
     /**
-     * @@@
+     * 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
@@ -2117,7 +2175,8 @@ class FileCacheStorage {
         ...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);
@@ -2130,7 +2189,8 @@ class FileCacheStorage {
         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);
@@ -2142,7 +2202,8 @@ class FileCacheStorage {
         await 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);
@@ -2201,7 +2262,7 @@ class AuthenticationError extends Error {
 }
 
 /**
- * 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`
  */
@@ -2265,7 +2326,7 @@ class MissingToolsError extends Error {
         super(spaceTrim$1((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';
@@ -2328,7 +2389,7 @@ class PipelineExecutionError extends Error {
         super(message);
         this.name = 'PipelineExecutionError';
         // TODO: [🐙] DRY - Maybe $randomId
-        this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid simmilar char conflicts   */)}`;
+        this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid similar char conflicts   */)}`;
         Object.setPrototypeOf(this, PipelineExecutionError.prototype);
     }
 }
@@ -2525,10 +2586,10 @@ class RemoteLlmExecutionTools {
     }
     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
@@ -2543,7 +2604,7 @@ class RemoteLlmExecutionTools {
      * 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,
@@ -2680,6 +2741,23 @@ function $getCurrentDate() {
     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
  *
@@ -2690,17 +2768,19 @@ function $getCurrentDate() {
  * @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?
@@ -2710,13 +2790,37 @@ function cacheLlmTools(llmTools, options = {}) {
     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(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(hexEncoder.parse(JSON.stringify({ parameters, content, modelRequirements }))).toString( /* hex */));
+            sha256(hexEncoder.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':
@@ -2737,7 +2841,16 @@ function cacheLlmTools(llmTools, options = {}) {
         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;
@@ -2763,9 +2876,9 @@ function cacheLlmTools(llmTools, options = {}) {
 /**
  * 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
  */
 
 /**
@@ -2895,12 +3008,14 @@ function countUsage(llmTools) {
     const spending = new 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();
@@ -2955,9 +3070,8 @@ function countUsage(llmTools) {
  */
 
 /**
- * @@@
+ * 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:
@@ -2965,7 +3079,8 @@ function countUsage(llmTools) {
  * - `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() {
@@ -3003,29 +3118,40 @@ class MultipleLlmExecutionTools {
         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((block) => `
+                        ${headLine}
+                        
+                          ${ /* <- Note: Indenting the description: */block(description)}
+                    `);
+        })
+            .join('\n\n');
+        return spaceTrim((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
@@ -3179,11 +3305,16 @@ function joinLlmExecutionTools(...llmExecutionTools) {
  */
 
 /**
- * @@@
+ * 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 = {}) {
@@ -3222,7 +3353,11 @@ function createLlmToolsFromConfiguration(configuration, options = {}) {
 /**
  * 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`
@@ -3230,11 +3365,14 @@ function createLlmToolsFromConfiguration(configuration, options = {}) {
  */
 
 /**
- * @@@
+ * 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:
@@ -3242,7 +3380,8 @@ function createLlmToolsFromConfiguration(configuration, options = {}) {
  * - `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 = {}) {
@@ -3268,7 +3407,16 @@ async function $provideLlmToolsFromEnv(options = {}) {
     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
@@ -3436,15 +3584,19 @@ async function $provideLlmToolsForCli(options) {
                         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`;
@@ -3681,7 +3833,8 @@ function $execCommand(options) {
  */
 
 /**
- * @@@
+ * 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
  */
@@ -3724,7 +3877,8 @@ async function isExecutable(path, fs) {
 // 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
  */
@@ -3756,7 +3910,8 @@ async function locateAppOnMacOs({ macOsName, }) {
  */
 
 /**
- * @@@
+ * 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
  */
@@ -3827,7 +3982,8 @@ function locateApp(options) {
  */
 
 /**
- * @@@
+ * 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
  */
@@ -3845,7 +4001,8 @@ function locateLibreoffice() {
  */
 
 /**
- * @@@
+ * 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
  */
@@ -3863,7 +4020,7 @@ function locatePandoc() {
  */
 
 /**
- * @@@
+ * Provides paths to required executables (i.e. as Pandoc and LibreOffice) for Node.js environments.
  *
  * @public exported from `@promptbook/node`
  */
@@ -3883,10 +4040,11 @@ async function $provideExecutablesForNode(options) {
  */
 
 /**
- * @@@
+ * 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');
@@ -3895,11 +4053,9 @@ const $scrapersRegister = new $Register('scraper_constructors');
  */
 
 /**
- * @@@
- *
- * 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) {
@@ -3924,10 +4080,10 @@ async function $provideScrapersForNode(tools, options) {
  */
 
 /**
- * @@@
+ * 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');
@@ -4110,7 +4266,7 @@ async function collectionToJson(collection) {
 /**
  * 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
  *
@@ -4132,7 +4288,7 @@ function isValidSemanticVersion(version) {
  *
  * @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
  *
@@ -4152,7 +4308,7 @@ function isValidPromptbookVersion(version) {
 /**
  * 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
  *
@@ -4249,7 +4405,7 @@ function validatePipeline_InnerFunction(pipeline) {
                     ${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$1((block) => `
@@ -4260,7 +4416,7 @@ function validatePipeline_InnerFunction(pipeline) {
                     ${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$1((block) => `
@@ -4507,7 +4663,7 @@ var PipelineCollection = [{title:"Prepare Knowledge from Markdown",pipelineUrl:"
  * 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`
  */
@@ -4619,7 +4775,7 @@ function pipelineJsonToString(pipelineJson) {
     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)}`);
@@ -4737,23 +4893,6 @@ function taskParameterJsonToString(taskParameterJson) {
  * 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
  *
@@ -4803,7 +4942,7 @@ class SimplePipelineCollection {
     /**
      * 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
@@ -4915,15 +5054,18 @@ function createCollectionFromJson(...promptbooks) {
  * @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;
     }
     /*
@@ -4944,6 +5086,35 @@ function isPipelinePrepared(pipeline) {
  *     - [♨] 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((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
 
@@ -5022,8 +5193,9 @@ function assertsTaskSuccessful(executionResult) {
  */
 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;
@@ -5033,6 +5205,10 @@ function createTask(options) {
     const partialResultSubject = new 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);
@@ -5078,17 +5254,24 @@ function createTask(options) {
     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() {
@@ -5096,15 +5279,15 @@ function createTask(options) {
         },
         get errors() {
             return errors;
-            // <- Note: [1]
+            // <- Note: [1] --||--
         },
         get warnings() {
             return warnings;
-            // <- Note: [1]
+            // <- Note: [1] --||--
         },
         get currentValue() {
             return currentValue;
-            // <- Note: [1]
+            // <- Note: [1] --||--
         },
     };
 }
@@ -5113,35 +5296,6 @@ function createTask(options) {
  * 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((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
  *
@@ -5384,7 +5538,7 @@ function union(...sets) {
 }
 
 /**
- * @@@
+ * Contains configuration options for parsing and generating CSV files, such as delimiters and quoting rules.
  *
  * @public exported from `@promptbook/core`
  */
@@ -5393,11 +5547,29 @@ const MANDATORY_CSV_SETTINGS = Object.freeze({
     // 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 = 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`
  */
@@ -5421,7 +5593,7 @@ function isValidCsvString(value) {
  * @public exported from `@promptbook/core`
  *                          <- TODO: [🏢] Export from package `@promptbook/csv`
  */
-const CsvFormatDefinition = {
+const CsvFormatParser = {
     formatName: 'CSV',
     aliases: ['SPREADSHEET', 'TABLE'],
     isValid(value, settings, schema) {
@@ -5433,12 +5605,12 @@ const CsvFormatDefinition = {
     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 = 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((block) => `
                                 CSV parsing error
@@ -5453,23 +5625,37 @@ const CsvFormatDefinition = {
                                 ${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(unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS }));
+                    }
+                }
                 return unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS });
             },
         },
         {
             subvalueName: 'CELL',
-            async mapValues(value, outputParameterName, settings, mapCallback) {
-                // TODO: [👨🏾‍🤝‍👨🏼] DRY csv parsing
-                const csv = 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((block) => `
                                 CSV parsing error
@@ -5485,9 +5671,9 @@ const CsvFormatDefinition = {
                             `));
                 }
                 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 unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS });
@@ -5496,10 +5682,10 @@ const CsvFormatDefinition = {
     ],
 };
 /**
- * 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
  */
 
@@ -5508,7 +5694,7 @@ const CsvFormatDefinition = {
  *
  * @private still in development [🏢]
  */
-const JsonFormatDefinition = {
+const JsonFormatParser = {
     formatName: 'JSON',
     mimeType: 'application/json',
     isValid(value, settings, schema) {
@@ -5520,28 +5706,28 @@ const JsonFormatDefinition = {
     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';
@@ -5550,19 +5736,20 @@ const TextFormatDefinition = {
         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');
             },
         },
@@ -5572,10 +5759,10 @@ const TextFormatDefinition = {
 /**
  * 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
  */
 
@@ -5583,7 +5770,7 @@ const TextFormatDefinition = {
  * 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`
  */
@@ -5608,7 +5795,7 @@ function isValidXmlString(value) {
  *
  * @private still in development [🏢]
  */
-const XmlFormatDefinition = {
+const XmlFormatParser = {
     formatName: 'XML',
     mimeType: 'application/xml',
     isValid(value, settings, schema) {
@@ -5620,17 +5807,17 @@ const XmlFormatDefinition = {
     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
  */
 
@@ -5639,24 +5826,19 @@ const XmlFormatDefinition = {
  *
  * @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) {
@@ -5679,7 +5861,7 @@ function mapAvailableToExpectedParameters(options) {
         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;
     }
@@ -5710,7 +5892,7 @@ function mapAvailableToExpectedParameters(options) {
     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;
 }
@@ -5718,8 +5900,8 @@ function mapAvailableToExpectedParameters(options) {
 /**
  * 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
@@ -5769,7 +5951,7 @@ function extractAllBlocksFromMarkdown(markdown) {
             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) {
@@ -5789,7 +5971,7 @@ function extractAllBlocksFromMarkdown(markdown) {
  * - 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
@@ -5814,7 +5996,7 @@ function extractJsonBlock(markdown) {
 }
 /**
  * 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`
  */
 
 /**
@@ -6035,14 +6217,14 @@ const CountUtils = {
     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
  *
@@ -6063,13 +6245,17 @@ function checkExpectations(expectations, value) {
 }
 /**
  * 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) {
@@ -6291,7 +6477,7 @@ async function executeAttempts(options) {
             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 || '');
                         }
@@ -6393,12 +6579,16 @@ async function executeAttempts(options) {
  */
 
 /**
- * @@@
+ * 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);
     }
@@ -6429,16 +6619,16 @@ async function executeFormatSubvalues(options) {
                     ${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((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'))}
 
@@ -6450,55 +6640,85 @@ async function executeFormatSubvalues(options) {
     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((block) => `
-                        ${error.message}
+            catch (error) {
+                if (!(error instanceof PipelineExecutionError)) {
+                    throw error;
+                }
+                const highLevelError = new PipelineExecutionError(spaceTrim((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((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((block) => `
+                            ${block(pipelineIdentification)}
+                            Subparameter index: ${index}
+                        `),
+                });
+                return subresultString;
+            }
+            catch (error) {
+                if (length > BIG_DATASET_TRESHOLD) {
+                    console.error(spaceTrim((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) {
@@ -6506,7 +6726,7 @@ async function getContextForTask(task) {
 }
 
 /**
- * @@@
+ * Retrieves example values or templates for a given task, used to guide or validate pipeline execution.
  *
  * @private internal utility of `createPipelineExecutor`
  */
@@ -6515,91 +6735,128 @@ async function getExamplesForTask(task) {
 }
 
 /**
- * @@@
+ * Computes the cosine similarity between two embedding vectors
+ *
+ * Note: This is helping function for RAG (retrieval-augmented generation)
+ *
+ * @param embeddingVector1
+ * @param embeddingVector2
+ * @returns Cosine similarity between the two vectors
+ *
+ * @public exported from `@promptbook/core`
+ */
+function computeCosineSimilarity(embeddingVector1, embeddingVector2) {
+    if (embeddingVector1.length !== embeddingVector2.length) {
+        throw new TypeError('Embedding vectors must have the same length');
+    }
+    const dotProduct = embeddingVector1.reduce((sum, value, index) => sum + value * embeddingVector2[index], 0);
+    const magnitude1 = Math.sqrt(embeddingVector1.reduce((sum, value) => sum + value * value, 0));
+    const magnitude2 = Math.sqrt(embeddingVector2.reduce((sum, value) => sum + value * value, 0));
+    return 1 - dotProduct / (magnitude1 * magnitude2);
+}
+
+/**
+ *
+ * @param knowledgePieces
+ * @returns
  *
- * Here is the place where RAG (retrieval-augmented generation) happens
+ * @private internal utility of `createPipelineExecutor`
+ */
+function knowledgePiecesToString(knowledgePieces) {
+    return knowledgePieces
+        .map((knowledgePiece) => {
+        const { content } = knowledgePiece;
+        return `- ${content}`;
+    })
+        .join('\n');
+    // <- TODO: [🧠] Some smarter aggregation of knowledge pieces, single-line vs multi-line vs mixed
+}
+
+/**
+ * Retrieves the most relevant knowledge pieces for a given task using embedding-based similarity search.
+ * This is where retrieval-augmented generation (RAG) is performed to enhance the task with external knowledge.
  *
  * @private internal utility of `createPipelineExecutor`
  */
 async function getKnowledgeForTask(options) {
-    const { tools, preparedPipeline, task } = options;
+    const { tools, preparedPipeline, task, parameters } = options;
     const firstKnowlegePiece = preparedPipeline.knowledgePieces[0];
     const firstKnowlegeIndex = firstKnowlegePiece === null || firstKnowlegePiece === void 0 ? void 0 : firstKnowlegePiece.index[0];
     // <- TODO: Do not use just first knowledge piece and first index to determine embedding model, use also keyword search
     if (firstKnowlegePiece === undefined || firstKnowlegeIndex === undefined) {
-        return 'No knowledge pieces found';
+        return ''; // <- Note: Np knowledge present, return empty string
     }
-    // TODO: [🚐] Make arrayable LLMs -> single LLM DRY
-    const _llms = arrayableToArray(tools.llm);
-    const llmTools = _llms.length === 1 ? _llms[0] : joinLlmExecutionTools(..._llms);
-    const taskEmbeddingPrompt = {
-        title: 'Knowledge Search',
-        modelRequirements: {
-            modelVariant: 'EMBEDDING',
-            modelName: firstKnowlegeIndex.modelName,
-        },
-        content: task.content,
-        parameters: {
-        /* !!!!!!!! */
-        },
-    };
-    const taskEmbeddingResult = await llmTools.callEmbeddingModel(taskEmbeddingPrompt);
-    const knowledgePiecesWithRelevance = preparedPipeline.knowledgePieces.map((knowledgePiece) => {
-        const { index } = knowledgePiece;
-        const knowledgePieceIndex = index.find((i) => i.modelName === firstKnowlegeIndex.modelName);
-        // <- TODO: Do not use just first knowledge piece and first index to determine embedding model
-        if (knowledgePieceIndex === undefined) {
+    try {
+        // TODO: [🚐] Make arrayable LLMs -> single LLM DRY
+        const _llms = arrayableToArray(tools.llm);
+        const llmTools = _llms.length === 1 ? _llms[0] : joinLlmExecutionTools(..._llms);
+        const taskEmbeddingPrompt = {
+            title: 'Knowledge Search',
+            modelRequirements: {
+                modelVariant: 'EMBEDDING',
+                modelName: firstKnowlegeIndex.modelName,
+            },
+            content: task.content,
+            parameters,
+        };
+        const taskEmbeddingResult = await llmTools.callEmbeddingModel(taskEmbeddingPrompt);
+        const knowledgePiecesWithRelevance = preparedPipeline.knowledgePieces.map((knowledgePiece) => {
+            const { index } = knowledgePiece;
+            const knowledgePieceIndex = index.find((i) => i.modelName === firstKnowlegeIndex.modelName);
+            // <- TODO: Do not use just first knowledge piece and first index to determine embedding model
+            if (knowledgePieceIndex === undefined) {
+                return {
+                    content: knowledgePiece.content,
+                    relevance: 0,
+                };
+            }
+            const relevance = computeCosineSimilarity(knowledgePieceIndex.position, taskEmbeddingResult.content);
             return {
                 content: knowledgePiece.content,
-                relevance: 0,
+                relevance,
             };
-        }
-        const relevance = computeCosineSimilarity(knowledgePieceIndex.position, taskEmbeddingResult.content);
-        return {
-            content: knowledgePiece.content,
-            relevance,
-        };
-    });
-    const knowledgePiecesSorted = knowledgePiecesWithRelevance.sort((a, b) => a.relevance - b.relevance);
-    const knowledgePiecesLimited = knowledgePiecesSorted.slice(0, 5);
-    console.log('!!! Embedding', {
-        task,
-        taskEmbeddingPrompt,
-        taskEmbeddingResult,
-        firstKnowlegePiece,
-        firstKnowlegeIndex,
-        knowledgePiecesWithRelevance,
-        knowledgePiecesSorted,
-        knowledgePiecesLimited,
-    });
-    return knowledgePiecesLimited.map(({ content }) => `- ${content}`).join('\n');
-    //                                                      <- TODO: [🧠] Some smart aggregation of knowledge pieces, single-line vs multi-line vs mixed
-}
-// TODO: !!!!!! Annotate + to new file
-function computeCosineSimilarity(embeddingVector1, embeddingVector2) {
-    if (embeddingVector1.length !== embeddingVector2.length) {
-        throw new TypeError('Embedding vectors must have the same length');
+        });
+        const knowledgePiecesSorted = knowledgePiecesWithRelevance.sort((a, b) => a.relevance - b.relevance);
+        const knowledgePiecesLimited = knowledgePiecesSorted.slice(0, 5);
+        /*
+        console.log('`getKnowledgeForTask` Embedding', {
+            task,
+            taskEmbeddingPrompt,
+            taskEmbeddingResult,
+            firstKnowlegePiece,
+            firstKnowlegeIndex,
+            knowledgePiecesWithRelevance,
+            knowledgePiecesSorted,
+            knowledgePiecesLimited,
+        });
+        */
+        return knowledgePiecesToString(knowledgePiecesLimited);
+    }
+    catch (error) {
+        assertsError(error);
+        console.error('Error in `getKnowledgeForTask`', error);
+        // Note: If the LLM fails, just return all knowledge pieces
+        return knowledgePiecesToString(preparedPipeline.knowledgePieces);
     }
-    const dotProduct = embeddingVector1.reduce((sum, value, index) => sum + value * embeddingVector2[index], 0);
-    const magnitude1 = Math.sqrt(embeddingVector1.reduce((sum, value) => sum + value * value, 0));
-    const magnitude2 = Math.sqrt(embeddingVector2.reduce((sum, value) => sum + value * value, 0));
-    return 1 - dotProduct / (magnitude1 * magnitude2);
 }
 /**
- * TODO: !!!! Verify if this is working
  * TODO: [♨] Implement Better - use keyword search
  * TODO: [♨] Examples of values
  */
 
 /**
- * @@@
+ * Retrieves all reserved parameters for a given pipeline task, including context, knowledge, examples, and metadata.
+ * Ensures all reserved parameters are defined and throws if any are missing.
+ *
+ * @param options - Options including tools, pipeline, task, and context.
+ * @returns An object containing all reserved parameters for the task.
  *
  * @private internal utility of `createPipelineExecutor`
  */
 async function getReservedParametersForTask(options) {
-    const { tools, preparedPipeline, task, pipelineIdentification } = options;
+    const { tools, preparedPipeline, task, parameters, pipelineIdentification, isVerbose } = options;
     const context = await getContextForTask(); // <- [🏍]
-    const knowledge = await getKnowledgeForTask({ tools, preparedPipeline, task });
+    const knowledge = await getKnowledgeForTask({ tools, preparedPipeline, task, parameters });
     const examples = await getExamplesForTask();
     const currentDate = new Date().toISOString(); // <- TODO: [🧠][💩] Better
     const modelName = RESERVED_PARAMETER_MISSING_VALUE;
@@ -6611,6 +6868,9 @@ async function getReservedParametersForTask(options) {
         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) {
@@ -6625,23 +6885,21 @@ async function getReservedParametersForTask(options) {
 }
 
 /**
- * @@@
+ * 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$1((block) => `
                     Dependent parameters are not consistent with used parameters:
 
@@ -6659,13 +6917,16 @@ async function executeTask(options) {
 
                 `));
     }
+    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));
@@ -6710,6 +6971,7 @@ async function executeTask(options) {
         preparedPipeline,
         tools,
         $executionReport,
+        onProgress,
         pipelineIdentification,
         maxExecutionAttempts,
         maxParallelCount,
@@ -6737,7 +6999,8 @@ async function executeTask(options) {
  */
 
 /**
- * @@@
+ * 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`
  */
@@ -6762,9 +7025,12 @@ function filterJustOutputParameters(options) {
 }
 
 /**
- * @@@
+ * Executes an entire pipeline, resolving tasks in dependency order, handling errors, and reporting progress.
+ *
+ * Note: This is not a `PipelineExecutor` (which is bound to a single pipeline), but a utility function used by `createPipelineExecutor` to create a `PipelineExecutor`.
  *
- * Note: This is not a `PipelineExecutor` (which is binded with one exact pipeline), but a utility function of `createPipelineExecutor` which creates `PipelineExecutor`
+ * @param options - Options for execution, including input parameters, pipeline, and callbacks.
+ * @returns The result of the pipeline execution, including output parameters, errors, and usage statistics.
  *
  * @private internal utility of `createPipelineExecutor`
  */
@@ -7087,10 +7353,27 @@ function createPipelineExecutor(options) {
             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);
@@ -7250,7 +7533,9 @@ function mimeTypeToExtension(value) {
 }
 
 /**
- * @@@
+ * 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`
  */
@@ -7389,7 +7674,7 @@ async function makeKnowledgeSourceHandler(knowledgeSource, tools, options) {
 }
 
 /**
- * Prepares the knowle
+ * Prepares the knowledge pieces
  *
  * @see https://github.com/webgptorg/promptbook/discussions/41
  * @public exported from `@promptbook/core`
@@ -7485,15 +7770,18 @@ TODO: [🧊] This is how it can look in future
  * 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;
@@ -7531,7 +7819,7 @@ async function prepareTasks(pipeline, tools, options) {
     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
@@ -7667,7 +7955,7 @@ async function preparePipeline(pipeline, tools, options) {
         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,
@@ -7943,7 +8231,7 @@ const sectionCommandParser = {
             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();
@@ -8011,7 +8299,7 @@ const sectionCommandParser = {
 /**
  * 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
@@ -8399,11 +8687,11 @@ const expectCommandParser = {
 };
 
 /**
- * @@@
+ * 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`
@@ -8453,9 +8741,9 @@ function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
 /**
  * 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
  *
@@ -8467,18 +8755,19 @@ function removeQuotes(text) {
     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) {
@@ -8548,8 +8837,6 @@ function validateParameterName(parameterName) {
 /**
  * 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`
  */
@@ -8606,14 +8893,14 @@ const foreachCommandParser = {
                     `));
             // <- 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((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'))}
                     `));
@@ -8790,14 +9077,14 @@ const formatCommandParser = {
 };
 
 /**
- * @@@
+ * 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: [
@@ -8824,7 +9111,45 @@ const ChatbotFormfactorDefinition = {
 };
 
 /**
- * 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`
  */
@@ -8853,7 +9178,7 @@ const GeneratorFormfactorDefinition = {
 };
 
 /**
- * @@@
+ * Pipeline interface which is equivalent to `any`
  *
  * @see https://github.com/webgptorg/promptbook/discussions/171
  *
@@ -8868,13 +9193,13 @@ const GENERIC_PIPELINE_INTERFACE = {
  */
 
 /**
- * @@@
+ * 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,
 };
@@ -8909,17 +9234,20 @@ const ImageGeneratorFormfactorDefinition = {
 };
 
 /**
- * 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',
@@ -8928,20 +9256,21 @@ const MatcherFormfactorDefinition = {
             },
         ],
         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: [
@@ -8964,13 +9293,16 @@ const SheetsFormfactorDefinition = {
 };
 
 /**
- * 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: [
@@ -9007,6 +9339,8 @@ const FORMFACTOR_DEFINITIONS = [
     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
@@ -9015,7 +9349,7 @@ const FORMFACTOR_DEFINITIONS = [
 /**
  * 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`
@@ -9037,7 +9371,7 @@ const formfactorCommandParser = {
     /**
      * Description of the FORMFACTOR command
      */
-    description: `@@`,
+    description: `Specifies the application type and interface requirements that this promptbook should conform to`,
     /**
      * Link to documentation
      */
@@ -9180,8 +9514,7 @@ const jokerCommandParser = {
 };
 
 /**
- * @@@
- *
+ * @see {@link ModelVariant}
  * @public exported from `@promptbook/core`
  */
 const MODEL_VARIANTS = ['COMPLETION', 'CHAT', 'EMBEDDING' /* <- TODO [🏳] */ /* <- [🤖] */];
@@ -9613,10 +9946,10 @@ function $applyToTaskJson(command, $taskJson, $pipelineJson) {
 }
 
 /**
- * @@@
+ * 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) {
@@ -10077,7 +10410,7 @@ function parseCommand(raw, usagePlace) {
     //        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();
@@ -10096,7 +10429,10 @@ function parseCommand(raw, usagePlace) {
               `));
 }
 /**
- * @@@
+ * 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 }) => 
@@ -10107,7 +10443,10 @@ function getSupportedCommandsMessage() {
     ]).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;
@@ -10154,7 +10493,7 @@ function parseCommandVariant(input) {
 }
 
 /**
- * @@@
+ * 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
@@ -10187,7 +10526,7 @@ function getPipelineInterface(pipeline) {
 }
 
 /**
- * @@@
+ * Checks if two pipeline interfaces are structurally identical.
  *
  * @deprecated https://github.com/webgptorg/promptbook/pull/186
  * @see https://github.com/webgptorg/promptbook/discussions/171
@@ -10219,10 +10558,11 @@ function isPipelineInterfacesEqual(pipelineInterface1, pipelineInterface2) {
 }
 
 /**
- * @@@
+ * 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`
  */
@@ -10408,7 +10748,8 @@ function removeMarkdownComments(content) {
 }
 
 /**
- * @@@
+ * 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`
  */
@@ -10429,7 +10770,10 @@ function isFlatPipeline(pipelineString) {
 }
 
 /**
- * @@@
+ * 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`
  */
@@ -10486,7 +10830,7 @@ function deflatePipeline(pipelineString) {
  * 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) {
@@ -10511,8 +10855,8 @@ function extractAllListItemsFromMarkdown(markdown) {
  *
  * - 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
@@ -10667,7 +11011,7 @@ function flattenMarkdown(markdown) {
  * 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
  *
@@ -11104,7 +11448,7 @@ function parsePipeline(pipelineString) {
  * 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
  */
@@ -11149,45 +11493,43 @@ async function compilePipeline(pipelineString, tools, options) {
  */
 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 promptbookMermaid = spaceTrim$1((block) => `
-
-            %% 🔮 Tip: Open this on GitHub or in the VSCode website to see the Mermaid graph visually
-
-            flowchart LR
-              subgraph "${pipelineJson.title}"
-
-                  direction TB
-
-                  input((Input)):::input
-                  ${block(pipelineJson.tasks
+    const inputAndIntermediateParametersMermaid = pipelineJson.tasks
         .flatMap(({ title, dependentParameterNames, resultingParameterName }) => [
         `${parameterNameToTaskName(resultingParameterName)}("${title}")`,
         ...dependentParameterNames.map((dependentParameterName) => `${parameterNameToTaskName(dependentParameterName)}--"{${dependentParameterName}}"-->${parameterNameToTaskName(resultingParameterName)}`),
     ])
-        .join('\n'))}
-
-                  ${block(pipelineJson.parameters
+        .join('\n');
+    const outputParametersMermaid = pipelineJson.parameters
         .filter(({ isOutput }) => isOutput)
-        .map(({ name }) => `${parameterNameToTaskName(name)}--"{${name}}"-->output`)
-        .join('\n'))}
-                  output((Output)):::output
-
-                  ${block(pipelineJson.tasks
+        .map(({ name }) => `${parameterNameToTaskName(name)}--"{${name}}"-->${MERMAID_OUTPUT_NAME}`)
+        .join('\n');
+    const linksMermaid = pipelineJson.tasks
         .map((task) => {
         const link = linkTask(task);
         if (link === null) {
@@ -11198,10 +11540,44 @@ function renderPromptbookMermaid(pipelineJson, options) {
         return `click ${taskName} href "${href}" "${title}";`;
     })
         .filter((line) => line !== '')
-        .join('\n'))}
+        .join('\n');
+    const interactionPointsMermaid = Object.entries({
+        [MERMAID_INPUT_NAME]: 'Input',
+        [MERMAID_OUTPUT_NAME]: 'Output',
+        [MERMAID_RESERVED_NAME]: 'Other',
+        [MERMAID_KNOWLEDGE_NAME]: 'Knowledge',
+    })
+        .filter(([MERMAID_NAME]) => (inputAndIntermediateParametersMermaid + outputParametersMermaid).includes(MERMAID_NAME))
+        .map(([MERMAID_NAME, title]) => `${MERMAID_NAME}((${title})):::${MERMAID_NAME}`)
+        .join('\n');
+    const promptbookMermaid = spaceTrim$1((block) => `
+
+            %% 🔮 Tip: Open this on GitHub or in the VSCode website to see the Mermaid graph visually
+
+            flowchart LR
+              subgraph "${pipelineJson.title}"
+
+                  %% Basic configuration
+                  direction TB
+
+                  %% Interaction points from pipeline to outside
+                  ${block(interactionPointsMermaid)}
+
+                  %% Input and intermediate parameters
+                  ${block(inputAndIntermediateParametersMermaid)}
+
 
-                  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;
 
@@ -11241,11 +11617,11 @@ function parseKeywordsFromString(input) {
 }
 
 /**
- * @@@
+ * 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) {
@@ -11259,11 +11635,11 @@ function nameToUriPart(name) {
 }
 
 /**
- * @@@
+ * 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) {
@@ -11307,7 +11683,7 @@ function suffixUrl(value, suffix) {
 /**
  * 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`
@@ -11326,7 +11702,7 @@ function trimCodeBlock(value) {
 /**
  * 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`
@@ -11341,9 +11717,9 @@ function trimEndOfCodeBlock(value) {
 /**
  * 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
  *
@@ -11414,7 +11790,7 @@ function unwrapResult(text, options) {
  *
  * - 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
@@ -11451,7 +11827,7 @@ function preserve(func) {
     })();
 }
 /**
- * TODO: Probbably remove in favour of `keepImported`
+ * TODO: Probably remove in favour of `keepImported`
  * TODO: [1] This maybe does memory leak
  */
 
@@ -11655,7 +12031,7 @@ class JavascriptEvalExecutionTools {
  */
 
 /**
- * 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`
@@ -12029,7 +12405,7 @@ async function saveArchive(filePath, collectionJson, fs) {
 /**
  * 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
  *
@@ -13114,7 +13490,9 @@ function $initializeRunCommand(program) {
                 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.red('Pipeline source is required'));
@@ -13239,10 +13617,10 @@ function $initializeRunCommand(program) {
             console.info(colors.gray('--- Detailed Result ---'));
             console.info({ isSuccessful, errors, warnings, outputParameters, executionReport });
         }
-        if (saveReport && saveReport.endsWith('.json')) {
+        if (executionReport !== null && saveReport && saveReport.endsWith('.json')) {
             await 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 writeFile(saveReport, executionReportString, 'utf-8');
         }
@@ -13285,15 +13663,15 @@ function $initializeRunCommand(program) {
  * 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',
     },
@@ -13916,7 +14294,7 @@ function startRemoteServer(options) {
         // 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 });
@@ -13926,7 +14304,7 @@ function startRemoteServer(options) {
             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();
@@ -13951,7 +14329,7 @@ function startRemoteServer(options) {
         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.middleware({
         apiSpec: openapiJson,
         ignorePaths(path) {
@@ -13991,7 +14369,7 @@ function startRemoteServer(options) {
 
                     **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
             ? ''
@@ -14021,7 +14399,7 @@ function startRemoteServer(options) {
                     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:
@@ -14105,12 +14483,13 @@ function startRemoteServer(options) {
     });
     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),
@@ -14121,9 +14500,10 @@ function startRemoteServer(options) {
         }
         else {
             return {
-                nonce: '✨',
                 taskId,
+                title,
                 taskType,
+                promptbookVersion,
                 status,
                 createdAt,
                 updatedAt,
@@ -14273,7 +14653,7 @@ function startRemoteServer(options) {
             }
         });
         // -----------
-        // 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) {
@@ -14295,7 +14675,7 @@ function startRemoteServer(options) {
             }
         });
         // -----------
-        // 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) {
@@ -14355,7 +14735,7 @@ function startRemoteServer(options) {
     };
 }
 /**
- * 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'`
@@ -14591,7 +14971,7 @@ async function promptbookCli() {
     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);
@@ -14631,37 +15011,6 @@ const _CLI = {
  * 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
  *
@@ -14677,7 +15026,7 @@ const _AnthropicClaudeMetadataRegistration = $llmToolsMetadataRegister.register(
     className: 'AnthropicClaudeExecutionTools',
     envVariables: ['ANTHROPIC_CLAUDE_API_KEY'],
     trustLevel: 'CLOSED',
-    order: MODEL_ORDER.TOP_TIER,
+    order: MODEL_ORDERS.TOP_TIER,
     getBoilerplateConfiguration() {
         return {
             title: 'Anthropic Claude',
@@ -14687,6 +15036,7 @@ const _AnthropicClaudeMetadataRegistration = $llmToolsMetadataRegister.register(
                 apiKey: 'sk-ant-api03-',
                 isProxied: true,
                 remoteServerUrl: DEFAULT_REMOTE_SERVER_URL,
+                maxRequestsPerMinute: DEFAULT_MAX_REQUESTS_PER_MINUTE,
             },
         };
     },
@@ -14722,7 +15072,7 @@ function computeUsage(value) {
 /**
  * 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`
@@ -14736,8 +15086,8 @@ const ANTHROPIC_CLAUDE_MODELS = exportJson({
             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`),
             },
         },
         {
@@ -14746,8 +15096,8 @@ const ANTHROPIC_CLAUDE_MODELS = exportJson({
             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`),
             },
         },
         {
@@ -14806,8 +15156,8 @@ const ANTHROPIC_CLAUDE_MODELS = exportJson({
             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`),
             },
         },
         {
@@ -14854,14 +15204,18 @@ function computeUsageCounts(content) {
 /**
  * Make UncertainNumber
  *
- * @param value
+ * @param value value of the uncertain number, if `NaN` or `undefined`, it will be set to 0 and `isUncertain=true`
+ * @param isUncertain if `true`, the value is uncertain, otherwise depends on the value
  *
  * @private utility for initializating UncertainNumber
  */
-function uncertainNumber(value) {
+function uncertainNumber(value, isUncertain) {
     if (value === null || value === undefined || Number.isNaN(value)) {
         return UNCERTAIN_ZERO_VALUE;
     }
+    if (isUncertain === true) {
+        return { value, isUncertain };
+    }
     return { value };
 }
 
@@ -14927,6 +15281,8 @@ class AnthropicClaudeExecutionTools {
          * Anthropic Claude API client.
          */
         this.client = null;
+        const rate = this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE;
+        this.limiter = new Bottleneck({ minTime: 60000 / rate });
     }
     get title() {
         return 'Anthropic Claude';
@@ -14978,8 +15334,6 @@ class AnthropicClaudeExecutionTools {
             //                                            <- 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',
@@ -14988,14 +15342,14 @@ class AnthropicClaudeExecutionTools {
                     //    @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.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.bgRed('error'), error);
             }
@@ -15015,12 +15369,11 @@ class AnthropicClaudeExecutionTools {
             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,
@@ -15037,83 +15390,59 @@ class AnthropicClaudeExecutionTools {
             },
         });
     }
-    /*
-    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.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');
-        }
-
-        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
@@ -15122,7 +15451,7 @@ class AnthropicClaudeExecutionTools {
         const model = ANTHROPIC_CLAUDE_MODELS.find(({ modelName }) => modelName.startsWith(defaultModelName));
         if (model === undefined) {
             throw new UnexpectedError(spaceTrim((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'))}
@@ -15215,9 +15544,9 @@ const _AzureOpenAiMetadataRegistration = $llmToolsMetadataRegister.register({
     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',
@@ -15225,6 +15554,9 @@ const _AzureOpenAiMetadataRegistration = $llmToolsMetadataRegister.register({
             className: 'AzureOpenAiExecutionTools',
             options: {
                 apiKey: 'sk-',
+                resourceName: 'my-resource-name',
+                deploymentName: 'my-deployment-name',
+                maxRequestsPerMinute: DEFAULT_MAX_REQUESTS_PER_MINUTE,
             },
         };
     },
@@ -15238,15 +15570,15 @@ const _AzureOpenAiMetadataRegistration = $llmToolsMetadataRegister.register({
                 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
@@ -15275,7 +15607,7 @@ const _AzureOpenAiMetadataRegistration = $llmToolsMetadataRegister.register({
 /**
  * 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/
@@ -15536,7 +15868,7 @@ const OPENAI_MODELS = exportJson({
             modelName: 'text-embedding-3-large',
             modelDescription: "OpenAI's most capable text embedding model designed for high-quality embeddings for complex similarity tasks and information retrieval.",
             pricing: {
-                prompt: computeUsage(`$0.13  / 1M tokens`),
+                prompt: computeUsage(`$0.13 / 1M tokens`),
                 // TODO: [🏏] Leverage the batch API @see https://platform.openai.com/docs/guides/batch
                 output: 0, // <- Note: [🆖] In Embedding models you dont pay for output
             },
@@ -15629,8 +15961,8 @@ const OPENAI_MODELS = exportJson({
             modelName: 'gpt-4o-mini',
             modelDescription: 'Smaller, more cost-effective version of GPT-4o with good performance across text, vision, and audio tasks at reduced complexity.',
             pricing: {
-                prompt: computeUsage(`$3.00 / 1M tokens`),
-                output: computeUsage(`$9.00 / 1M tokens`),
+                prompt: computeUsage(`$0.15 / 1M tokens`),
+                output: computeUsage(`$0.60 / 1M tokens`),
             },
         },
         /**/
@@ -15652,7 +15984,7 @@ const OPENAI_MODELS = exportJson({
             modelTitle: 'o1-preview-2024-09-12',
             modelName: 'o1-preview-2024-09-12',
             modelDescription: 'September 2024 version of O1 preview with specialized reasoning capabilities for complex tasks requiring precise analytical thinking.',
-            //             <- TODO: [💩] Some better system to organize theese date suffixes and versions
+            //             <- TODO: [💩] Some better system to organize these date suffixes and versions
             pricing: {
                 prompt: computeUsage(`$15.00 / 1M tokens`),
                 output: computeUsage(`$60.00 / 1M tokens`),
@@ -15738,9 +16070,6 @@ const OPENAI_MODELS = exportJson({
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
-// Default rate limits (requests per minute) - adjust as needed based on Azure OpenAI tier
-const DEFAULT_RPM$1 = 60;
-// <- TODO: !!! Put in some better place
 /**
  * Execution Tools for calling Azure OpenAI API.
  *
@@ -15760,7 +16089,7 @@ class AzureOpenAiExecutionTools {
         this.client = null;
         // TODO: Allow configuring rate limits via options
         this.limiter = new Bottleneck({
-            minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_RPM$1),
+            minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE),
         });
     }
     get title() {
@@ -16014,7 +16343,7 @@ class AzureOpenAiExecutionTools {
         });
     }
     /**
-     * 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) {
@@ -16080,7 +16409,7 @@ const _DeepseekMetadataRegistration = $llmToolsMetadataRegister.register({
     className: 'DeepseekExecutionTools',
     envVariables: ['DEEPSEEK_GENERATIVE_AI_API_KEY'],
     trustLevel: 'UNTRUSTED',
-    order: MODEL_ORDER.NORMAL,
+    order: MODEL_ORDERS.NORMAL,
     getBoilerplateConfiguration() {
         return {
             title: 'Deepseek',
@@ -16160,12 +16489,14 @@ function createExecutionToolsFromVercelProvider(options) {
     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,
@@ -16283,7 +16614,7 @@ function createExecutionToolsFromVercelProvider(options) {
 /**
  * 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`
@@ -16297,8 +16628,8 @@ const DEEPSEEK_MODELS = exportJson({
             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`),
             },
         },
         {
@@ -16307,8 +16638,8 @@ const DEEPSEEK_MODELS = exportJson({
             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`),
             },
         },
         {
@@ -16403,7 +16734,7 @@ const _GoogleMetadataRegistration = $llmToolsMetadataRegister.register({
     className: 'GoogleExecutionTools',
     envVariables: ['GOOGLE_GENERATIVE_AI_API_KEY'],
     trustLevel: 'CLOSED',
-    order: MODEL_ORDER.NORMAL,
+    order: MODEL_ORDERS.NORMAL,
     getBoilerplateConfiguration() {
         return {
             title: 'Google Gemini',
@@ -16442,7 +16773,7 @@ const _GoogleMetadataRegistration = $llmToolsMetadataRegister.register({
 /**
  * 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`
@@ -16456,8 +16787,8 @@ const GOOGLE_MODELS = exportJson({
             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`),
             },
         },
         {
@@ -16496,8 +16827,8 @@ const GOOGLE_MODELS = exportJson({
             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`),
             },
         },
         {
@@ -16564,8 +16895,8 @@ const GOOGLE_MODELS = exportJson({
             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`),
             },
         },
         {
@@ -16668,7 +16999,7 @@ const _OpenAiMetadataRegistration = $llmToolsMetadataRegister.register({
     className: 'OpenAiExecutionTools',
     envVariables: ['OPENAI_API_KEY'],
     trustLevel: 'CLOSED',
-    order: MODEL_ORDER.TOP_TIER,
+    order: MODEL_ORDERS.TOP_TIER,
     getBoilerplateConfiguration() {
         return {
             title: 'Open AI',
@@ -16676,6 +17007,7 @@ const _OpenAiMetadataRegistration = $llmToolsMetadataRegister.register({
             className: 'OpenAiExecutionTools',
             options: {
                 apiKey: 'sk-',
+                maxRequestsPerMinute: DEFAULT_MAX_REQUESTS_PER_MINUTE,
             },
         };
     },
@@ -16695,9 +17027,9 @@ const _OpenAiMetadataRegistration = $llmToolsMetadataRegister.register({
     },
 });
 /**
- * @@@ 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`
@@ -16710,7 +17042,7 @@ const _OpenAiAssistantMetadataRegistration = $llmToolsMetadataRegister.register(
     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',
@@ -16719,6 +17051,7 @@ const _OpenAiAssistantMetadataRegistration = $llmToolsMetadataRegister.register(
             options: {
                 apiKey: 'sk-',
                 assistantId: 'asst_',
+                maxRequestsPerMinute: DEFAULT_MAX_REQUESTS_PER_MINUTE,
             },
         };
     },
@@ -16765,13 +17098,21 @@ resultContent, rawResponse) {
     }
     const inputTokens = rawResponse.usage.prompt_tokens;
     const outputTokens = ((_b = rawResponse.usage) === null || _b === void 0 ? void 0 : _b.completion_tokens) || 0;
-    const modelInfo = OPENAI_MODELS.find((model) => model.modelName === rawResponse.model);
+    let isUncertain = false;
+    let modelInfo = OPENAI_MODELS.find((model) => model.modelName === rawResponse.model);
+    if (modelInfo === undefined) {
+        // Note: Model is not in the list of known models, fallback to the family of the models and mark price as uncertain
+        modelInfo = OPENAI_MODELS.find((model) => (rawResponse.model || SALT_NONCE).startsWith(model.modelName));
+        if (modelInfo !== undefined) {
+            isUncertain = true;
+        }
+    }
     let price;
     if (modelInfo === undefined || modelInfo.pricing === undefined) {
         price = uncertainNumber();
     }
     else {
-        price = uncertainNumber(inputTokens * modelInfo.pricing.prompt + outputTokens * modelInfo.pricing.output);
+        price = uncertainNumber(inputTokens * modelInfo.pricing.prompt + outputTokens * modelInfo.pricing.output, isUncertain);
     }
     return {
         price,
@@ -16789,9 +17130,6 @@ resultContent, rawResponse) {
  * TODO: [🤝] DRY Maybe some common abstraction between `computeOpenAiUsage` and `computeAnthropicClaudeUsage`
  */
 
-// Default rate limits (requests per minute) - adjust as needed based on OpenAI tier
-const DEFAULT_RPM = 60;
-// <- TODO: !!! Put in some better place
 /**
  * Execution Tools for calling OpenAI API
  *
@@ -16811,7 +17149,7 @@ class OpenAiExecutionTools {
         this.client = null;
         // TODO: Allow configuring rate limits via options
         this.limiter = new Bottleneck({
-            minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_RPM),
+            minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE),
         });
     }
     get title() {
@@ -16912,7 +17250,6 @@ class OpenAiExecutionTools {
             user: (_a = this.options.userId) === null || _a === void 0 ? void 0 : _a.toString(),
         };
         const start = $getCurrentDate();
-        let complete;
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
@@ -16928,6 +17265,7 @@ class OpenAiExecutionTools {
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
         }
+        const complete = $getCurrentDate();
         if (!rawResponse.choices[0]) {
             throw new PipelineExecutionError('No choises from OpenAI');
         }
@@ -16936,8 +17274,6 @@ class OpenAiExecutionTools {
             throw new PipelineExecutionError('More than one choise from OpenAI');
         }
         const resultContent = rawResponse.choices[0].message.content;
-        // eslint-disable-next-line prefer-const
-        complete = $getCurrentDate();
         const usage = computeOpenAiUsage(content || '', resultContent || '', rawResponse);
         if (resultContent === null) {
             throw new PipelineExecutionError('No response message from OpenAI');
@@ -16991,7 +17327,6 @@ class OpenAiExecutionTools {
             user: (_a = this.options.userId) === null || _a === void 0 ? void 0 : _a.toString(),
         };
         const start = $getCurrentDate();
-        let complete;
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
@@ -17007,6 +17342,7 @@ class OpenAiExecutionTools {
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
         }
+        const complete = $getCurrentDate();
         if (!rawResponse.choices[0]) {
             throw new PipelineExecutionError('No choises from OpenAI');
         }
@@ -17015,8 +17351,6 @@ class OpenAiExecutionTools {
             throw new PipelineExecutionError('More than one choise from OpenAI');
         }
         const resultContent = rawResponse.choices[0].text;
-        // eslint-disable-next-line prefer-const
-        complete = $getCurrentDate();
         const usage = computeOpenAiUsage(content || '', resultContent || '', rawResponse);
         return exportJson({
             name: 'promptResult',
@@ -17057,7 +17391,6 @@ class OpenAiExecutionTools {
             model: modelName,
         };
         const start = $getCurrentDate();
-        let complete;
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
@@ -17073,12 +17406,11 @@ class OpenAiExecutionTools {
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
         }
+        const complete = $getCurrentDate();
         if (rawResponse.data.length !== 1) {
             throw new PipelineExecutionError(`Expected exactly 1 data item in response, got ${rawResponse.data.length}`);
         }
         const resultContent = rawResponse.data[0].embedding;
-        // eslint-disable-next-line prefer-const
-        complete = $getCurrentDate();
         const usage = computeOpenAiUsage(content || '', '', 
         // <- Note: Embedding does not have result content
         rawResponse);
@@ -17106,7 +17438,8 @@ class OpenAiExecutionTools {
      * Get the model that should be used as default
      */
     getDefaultModel(defaultModelName) {
-        const model = OPENAI_MODELS.find(({ modelName }) => modelName === defaultModelName);
+        // Note: Match exact or prefix for model families
+        const model = OPENAI_MODELS.find(({ modelName }) => modelName === defaultModelName || modelName.startsWith(defaultModelName));
         if (model === undefined) {
             throw new UnexpectedError(spaceTrim((block) => `
                             Cannot find model in OpenAI models with name "${defaultModelName}" which should be used as default.
@@ -17148,7 +17481,7 @@ class OpenAiExecutionTools {
 /**
  * Execution Tools for calling OpenAI API Assistants
  *
- * This is usefull for calling OpenAI API with a single assistant, for more wide usage use `OpenAiExecutionTools`.
+ * This is useful for calling OpenAI API with a single assistant, for more wide usage use `OpenAiExecutionTools`.
  *
  * @public exported from `@promptbook/openai`
  */
@@ -17161,6 +17494,7 @@ class OpenAiAssistantExecutionTools extends OpenAiExecutionTools {
     constructor(options) {
         super(options);
         this.assistantId = options.assistantId;
+        // TODO: [👱] Make limiter same as in `OpenAiExecutionTools`
     }
     get title() {
         return 'OpenAI Assistant';
@@ -17362,9 +17696,9 @@ const createOpenAiExecutionTools = Object.assign((options) => {
  */
 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`
@@ -17377,9 +17711,8 @@ const _OpenAiAssistantRegistration = $llmToolsRegister.register(createOpenAiAssi
  */
 
 /**
- * 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
  */
@@ -17522,7 +17855,7 @@ class MarkdownScraper {
         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(knowledgeTextPiece.substring(0, 100));
             const knowledgePieceContent = spaceTrim(knowledgeTextPiece);
@@ -17606,14 +17939,14 @@ const boilerplateScraperMetadata = $deepFreeze({
     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: [🤛] */
 /**
@@ -17631,7 +17964,7 @@ const _BoilerplateScraperMetadataRegistration = $scrapersMetadataRegister.regist
  */
 
 /**
- * Scraper of @@@ files
+ * Scraper of @@ files
  *
  * @see `documentationUrl` for more details
  * @public exported from `@promptbook/boilerplate`
@@ -17649,30 +17982,30 @@ class BoilerplateScraper {
         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, {
@@ -17682,7 +18015,7 @@ class BoilerplateScraper {
             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}"`;
@@ -17708,7 +18041,7 @@ class BoilerplateScraper {
      */
     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,
@@ -17739,7 +18072,7 @@ class BoilerplateScraper {
  * 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
  */
 
 /**
@@ -18073,7 +18406,8 @@ class LegacyDocumentScraper {
  */
 
 /**
- * @@@
+ * 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`
  */
@@ -18100,7 +18434,7 @@ const _LegacyDocumentScraperRegistration = $scrapersRegister.register(createLega
  */
 
 /**
- * @@@
+ * Creates a scraper for document content.
  *
  * @public exported from `@promptbook/documents`
  */
@@ -18127,7 +18461,7 @@ const _DocumentScraperRegistration = $scrapersRegister.register(createDocumentSc
  */
 
 /**
- * @@@
+ * Creates a scraper for markdown content.
  *
  * @public exported from `@promptbook/markdown-utils`
  */
@@ -18233,8 +18567,8 @@ class MarkitdownScraper {
             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 });
@@ -18256,11 +18590,11 @@ class MarkitdownScraper {
         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,
@@ -18404,7 +18738,8 @@ class PdfScraper {
  */
 
 /**
- * @@@
+ * Factory function to create an instance of PdfScraper.
+ * It bundles the scraper class with its metadata.
  *
  * @public exported from `@promptbook/pdf`
  */
@@ -18580,7 +18915,8 @@ class WebsiteScraper {
  */
 
 /**
- * @@@
+ * Factory function to create an instance of WebsiteScraper.
+ * It bundles the scraper class with its metadata.
  *
  * @public exported from `@promptbook/website-crawler`
  */