@promptbook/cli 0.92.0-3 → 0.92.0-31

package/esm/index.es.js

@@ -21,12 +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 OpenAI from 'openai';
 import { Readability } from '@mozilla/readability';
 import { JSDOM } from 'jsdom';
@@ -46,7 +47,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.92.0-3';
+const PROMPTBOOK_ENGINE_VERSION = '0.92.0-31';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -162,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
  *
@@ -246,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
@@ -317,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`
  */
@@ -328,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`
  */
@@ -346,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
  */
@@ -686,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
  *
@@ -697,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`
@@ -752,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`
@@ -765,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) {
@@ -813,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');
@@ -825,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');
@@ -1004,6 +1030,42 @@ function $sideEffect(...sideEffectSubjects) {
     keepUnused(...sideEffectSubjects);
 }
 
+/**
+ * Converts a JavaScript Object Notation (JSON) string into an object.
+ *
+ * Note: This is wrapper around `JSON.parse()` with better error and type handling
+ *
+ * @public exported from `@promptbook/utils`
+ */
+function jsonParse(value) {
+    if (value === undefined) {
+        throw new Error(`Can not parse JSON from undefined value.`);
+    }
+    else if (typeof value !== 'string') {
+        console.error('Can not parse JSON from non-string value.', { text: value });
+        throw new Error(spaceTrim(`
+                    Can not parse JSON from non-string value.
+
+                    The value type: ${typeof value}
+                    See more in console.
+                `));
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        if (!(error instanceof Error)) {
+            throw error;
+        }
+        throw new Error(spaceTrim((block) => `
+                    ${block(error.message)}
+
+                    The JSON text:
+                    ${block(value)}
+                `));
+    }
+}
+
 /**
  * Convert identification to Promptbook token
  *
@@ -1052,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`
  */
@@ -1427,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) {
@@ -1483,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
  *
@@ -1510,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
  */
@@ -1951,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) {
@@ -1968,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`
@@ -2019,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) {
@@ -2043,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`
  */
@@ -2052,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`
  */
@@ -2065,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
@@ -2077,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);
@@ -2085,12 +2184,13 @@ class FileCacheStorage {
             return null;
         }
         const fileContent = await readFile(filename, 'utf-8');
-        const value = JSON.parse(fileContent);
+        const value = jsonParse(fileContent);
         // TODO: [🌗]
         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);
@@ -2102,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);
@@ -2581,6 +2682,23 @@ class RemoteLlmExecutionTools {
  * TODO: [🧠] Maybe remove `@promptbook/remote-client` and just use `@promptbook/core`
  */
 
+/**
+ * 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;
+}
+
 /**
  * Stores data in memory (HEAP)
  *
@@ -2670,13 +2788,36 @@ 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) {
+            console.log('!!! Cache hit for key:', { key, keyHashBase });
             return cacheItem.promptResult;
         }
+        console.log('!!! 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':
@@ -2697,7 +2838,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;
@@ -2723,9 +2873,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
  */
 
 /**
@@ -2915,9 +3065,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:
@@ -2925,7 +3074,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() {
@@ -3139,11 +3289,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 = {}) {
@@ -3182,7 +3337,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`
@@ -3190,11 +3349,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:
@@ -3202,7 +3364,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 = {}) {
@@ -3228,7 +3391,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
@@ -3396,15 +3568,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`;
@@ -3420,7 +3596,7 @@ async function $provideLlmToolsForCli(options) {
                         password,
                     }),
                 });
-                const { isSuccess, message, error, identification } = (await response.json());
+                const { isSuccess, message, error, identification } = jsonParse(await response.text());
                 if (message) {
                     if (isSuccess) {
                         console.log(colors.green(message));
@@ -3641,7 +3817,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
  */
@@ -3684,7 +3861,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
  */
@@ -3716,7 +3894,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
  */
@@ -3787,7 +3966,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
  */
@@ -3805,7 +3985,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
  */
@@ -3823,7 +4004,7 @@ function locatePandoc() {
  */
 
 /**
- * @@@
+ * Provides paths to required executables (i.e. as Pandoc and LibreOffice) for Node.js environments.
  *
  * @public exported from `@promptbook/node`
  */
@@ -3843,10 +4024,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');
@@ -3855,11 +4037,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) {
@@ -3884,10 +4064,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');
@@ -4451,7 +4631,7 @@ async function loadArchive(filePath, fs) {
     if (!indexFile) {
         throw new UnexpectedError(`Archive does not contain 'index.book.json' file`);
     }
-    const collectionJson = JSON.parse(await indexFile.async('text'));
+    const collectionJson = jsonParse(await indexFile.async('text'));
     for (const pipeline of collectionJson) {
         validatePipeline(pipeline);
     }
@@ -4461,13 +4641,13 @@ async function loadArchive(filePath, fs) {
  * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
  */
 
-var PipelineCollection = [{title:"Prepare Knowledge from Markdown",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-from-markdown.book",formfactorName:"GENERIC",parameters:[{name:"knowledgeContent",description:"Markdown document content",isInput:true,isOutput:false},{name:"knowledgePieces",description:"The knowledge JSON object",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced data researcher, extract the important knowledge from the document.\n\n# Rules\n\n-   Make pieces of information concise, clear, and easy to understand\n-   One piece of information should be approximately 1 paragraph\n-   Divide the paragraphs by markdown horizontal lines ---\n-   Omit irrelevant information\n-   Group redundant information\n-   Write just extracted information, nothing else\n\n# The document\n\nTake information from this document:\n\n> {knowledgeContent}",resultingParameterName:"knowledgePieces",dependentParameterNames:["knowledgeContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Knowledge from Markdown\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-from-markdown.book`\n-   INPUT PARAMETER `{knowledgeContent}` Markdown document content\n-   OUTPUT PARAMETER `{knowledgePieces}` The knowledge JSON object\n\n## Knowledge\n\n<!-- TODO: [🍆] -FORMAT JSON -->\n\n```markdown\nYou are experienced data researcher, extract the important knowledge from the document.\n\n# Rules\n\n-   Make pieces of information concise, clear, and easy to understand\n-   One piece of information should be approximately 1 paragraph\n-   Divide the paragraphs by markdown horizontal lines ---\n-   Omit irrelevant information\n-   Group redundant information\n-   Write just extracted information, nothing else\n\n# The document\n\nTake information from this document:\n\n> {knowledgeContent}\n```\n\n`-> {knowledgePieces}`\n"}],sourceFile:"./books/prepare-knowledge-from-markdown.book"},{title:"Prepare Keywords",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-keywords.book",formfactorName:"GENERIC",parameters:[{name:"knowledgePieceContent",description:"The content",isInput:true,isOutput:false},{name:"keywords",description:"Keywords separated by comma",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced data researcher, detect the important keywords in the document.\n\n# Rules\n\n-   Write just keywords separated by comma\n\n# The document\n\nTake information from this document:\n\n> {knowledgePieceContent}",resultingParameterName:"keywords",dependentParameterNames:["knowledgePieceContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Keywords\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-keywords.book`\n-   INPUT PARAMETER `{knowledgePieceContent}` The content\n-   OUTPUT PARAMETER `{keywords}` Keywords separated by comma\n\n## Knowledge\n\n<!-- TODO: [🍆] -FORMAT JSON -->\n\n```markdown\nYou are experienced data researcher, detect the important keywords in the document.\n\n# Rules\n\n-   Write just keywords separated by comma\n\n# The document\n\nTake information from this document:\n\n> {knowledgePieceContent}\n```\n\n`-> {keywords}`\n"}],sourceFile:"./books/prepare-knowledge-keywords.book"},{title:"Prepare Knowledge-piece Title",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-title.book",formfactorName:"GENERIC",parameters:[{name:"knowledgePieceContent",description:"The content",isInput:true,isOutput:false},{name:"title",description:"The title of the document",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced content creator, write best title for the document.\n\n# Rules\n\n-   Write just title, nothing else\n-   Write maximum 5 words for the title\n\n# The document\n\n> {knowledgePieceContent}",resultingParameterName:"title",expectations:{words:{min:1,max:8}},dependentParameterNames:["knowledgePieceContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Knowledge-piece Title\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-title.book`\n-   INPUT PARAMETER `{knowledgePieceContent}` The content\n-   OUTPUT PARAMETER `{title}` The title of the document\n\n## Knowledge\n\n-   EXPECT MIN 1 WORD\n-   EXPECT MAX 8 WORDS\n\n```markdown\nYou are experienced content creator, write best title for the document.\n\n# Rules\n\n-   Write just title, nothing else\n-   Write maximum 5 words for the title\n\n# The document\n\n> {knowledgePieceContent}\n```\n\n`-> {title}`\n"}],sourceFile:"./books/prepare-knowledge-title.book"},{title:"Prepare Persona",pipelineUrl:"https://promptbook.studio/promptbook/prepare-persona.book",formfactorName:"GENERIC",parameters:[{name:"availableModelNames",description:"List of available model names separated by comma (,)",isInput:true,isOutput:false},{name:"personaDescription",description:"Description of the persona",isInput:true,isOutput:false},{name:"modelRequirements",description:"Specific requirements for the model",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"make-model-requirements",title:"Make modelRequirements",content:"You are experienced AI engineer, you need to create virtual assistant.\nWrite\n\n## Example\n\n```json\n{\n\"modelName\": \"gpt-4o\",\n\"systemMessage\": \"You are experienced AI engineer and helpfull assistant.\",\n\"temperature\": 0.7\n}\n```\n\n## Instructions\n\n-   Your output format is JSON object\n-   Write just the JSON object, no other text should be present\n-   It contains the following keys:\n    -   `modelName`: The name of the model to use\n    -   `systemMessage`: The system message to provide context to the model\n    -   `temperature`: The sampling temperature to use\n\n### Key `modelName`\n\nPick from the following models:\n\n-   {availableModelNames}\n\n### Key `systemMessage`\n\nThe system message is used to communicate instructions or provide context to the model at the beginning of a conversation. It is displayed in a different format compared to user messages, helping the model understand its role in the conversation. The system message typically guides the model's behavior, sets the tone, or specifies desired output from the model. By utilizing the system message effectively, users can steer the model towards generating more accurate and relevant responses.\n\nFor example:\n\n> You are an experienced AI engineer and helpful assistant.\n\n> You are a friendly and knowledgeable chatbot.\n\n### Key `temperature`\n\nThe sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.\n\nYou can pick a value between 0 and 2. For example:\n\n-   `0.1`: Low temperature, extremely conservative and deterministic\n-   `0.5`: Medium temperature, balanced between conservative and creative\n-   `1.0`: High temperature, creative and bit random\n-   `1.5`: Very high temperature, extremely creative and often chaotic and unpredictable\n-   `2.0`: Maximum temperature, completely random and unpredictable, for some extreme creative use cases\n\n# The assistant\n\nTake this description of the persona:\n\n> {personaDescription}",resultingParameterName:"modelRequirements",format:"JSON",dependentParameterNames:["availableModelNames","personaDescription"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Persona\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-persona.book`\n-   INPUT PARAMETER `{availableModelNames}` List of available model names separated by comma (,)\n-   INPUT PARAMETER `{personaDescription}` Description of the persona\n-   OUTPUT PARAMETER `{modelRequirements}` Specific requirements for the model\n\n## Make modelRequirements\n\n-   FORMAT JSON\n\n```markdown\nYou are experienced AI engineer, you need to create virtual assistant.\nWrite\n\n## Example\n\n\\`\\`\\`json\n{\n\"modelName\": \"gpt-4o\",\n\"systemMessage\": \"You are experienced AI engineer and helpfull assistant.\",\n\"temperature\": 0.7\n}\n\\`\\`\\`\n\n## Instructions\n\n-   Your output format is JSON object\n-   Write just the JSON object, no other text should be present\n-   It contains the following keys:\n    -   `modelName`: The name of the model to use\n    -   `systemMessage`: The system message to provide context to the model\n    -   `temperature`: The sampling temperature to use\n\n### Key `modelName`\n\nPick from the following models:\n\n-   {availableModelNames}\n\n### Key `systemMessage`\n\nThe system message is used to communicate instructions or provide context to the model at the beginning of a conversation. It is displayed in a different format compared to user messages, helping the model understand its role in the conversation. The system message typically guides the model's behavior, sets the tone, or specifies desired output from the model. By utilizing the system message effectively, users can steer the model towards generating more accurate and relevant responses.\n\nFor example:\n\n> You are an experienced AI engineer and helpful assistant.\n\n> You are a friendly and knowledgeable chatbot.\n\n### Key `temperature`\n\nThe sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.\n\nYou can pick a value between 0 and 2. For example:\n\n-   `0.1`: Low temperature, extremely conservative and deterministic\n-   `0.5`: Medium temperature, balanced between conservative and creative\n-   `1.0`: High temperature, creative and bit random\n-   `1.5`: Very high temperature, extremely creative and often chaotic and unpredictable\n-   `2.0`: Maximum temperature, completely random and unpredictable, for some extreme creative use cases\n\n# The assistant\n\nTake this description of the persona:\n\n> {personaDescription}\n```\n\n`-> {modelRequirements}`\n"}],sourceFile:"./books/prepare-persona.book"},{title:"Prepare Title",pipelineUrl:"https://promptbook.studio/promptbook/prepare-title.book",formfactorName:"GENERIC",parameters:[{name:"book",description:"The book to prepare the title for",isInput:true,isOutput:false},{name:"title",description:"Best title for the book",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"make-title",title:"Make title",content:"Make best title for given text which describes the workflow:\n\n## Rules\n\n-   Write just title, nothing else\n-   Title should be concise and clear - Write maximum ideally 2 words, maximum 5 words\n-   Title starts with emoticon\n-   Title should not mention the input and output of the workflow but the main purpose of the workflow\n    _For example, not \"✍ Convert Knowledge-piece to title\" but \"✍ Title\"_\n\n## The workflow\n\n> {book}",resultingParameterName:"title",expectations:{words:{min:1,max:8},lines:{min:1,max:1}},dependentParameterNames:["book"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Title\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-title.book`\n-   INPUT PARAMETER `{book}` The book to prepare the title for\n-   OUTPUT PARAMETER `{title}` Best title for the book\n\n## Make title\n\n-   EXPECT MIN 1 Word\n-   EXPECT MAX 8 Words\n-   EXPECT EXACTLY 1 Line\n\n```markdown\nMake best title for given text which describes the workflow:\n\n## Rules\n\n-   Write just title, nothing else\n-   Title should be concise and clear - Write maximum ideally 2 words, maximum 5 words\n-   Title starts with emoticon\n-   Title should not mention the input and output of the workflow but the main purpose of the workflow\n    _For example, not \"✍ Convert Knowledge-piece to title\" but \"✍ Title\"_\n\n## The workflow\n\n> {book}\n```\n\n`-> {title}`\n"}],sourceFile:"./books/prepare-title.book"}];
+var PipelineCollection = [{title:"Prepare Knowledge from Markdown",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-from-markdown.book",formfactorName:"GENERIC",parameters:[{name:"knowledgeContent",description:"Markdown document content",isInput:true,isOutput:false},{name:"knowledgePieces",description:"The knowledge JSON object",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced data researcher, extract the important knowledge from the document.\n\n# Rules\n\n-   Make pieces of information concise, clear, and easy to understand\n-   One piece of information should be approximately 1 paragraph\n-   Divide the paragraphs by markdown horizontal lines ---\n-   Omit irrelevant information\n-   Group redundant information\n-   Write just extracted information, nothing else\n\n# The document\n\nTake information from this document:\n\n> {knowledgeContent}",resultingParameterName:"knowledgePieces",dependentParameterNames:["knowledgeContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Knowledge from Markdown\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-from-markdown.book`\n-   INPUT PARAMETER `{knowledgeContent}` Markdown document content\n-   OUTPUT PARAMETER `{knowledgePieces}` The knowledge JSON object\n\n## Knowledge\n\n<!-- TODO: [🍆] -FORMAT JSON -->\n\n```markdown\nYou are experienced data researcher, extract the important knowledge from the document.\n\n# Rules\n\n-   Make pieces of information concise, clear, and easy to understand\n-   One piece of information should be approximately 1 paragraph\n-   Divide the paragraphs by markdown horizontal lines ---\n-   Omit irrelevant information\n-   Group redundant information\n-   Write just extracted information, nothing else\n\n# The document\n\nTake information from this document:\n\n> {knowledgeContent}\n```\n\n`-> {knowledgePieces}`\n"}],sourceFile:"./books/prepare-knowledge-from-markdown.book"},{title:"Prepare Keywords",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-keywords.book",formfactorName:"GENERIC",parameters:[{name:"knowledgePieceContent",description:"The content",isInput:true,isOutput:false},{name:"keywords",description:"Keywords separated by comma",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced data researcher, detect the important keywords in the document.\n\n# Rules\n\n-   Write just keywords separated by comma\n\n# The document\n\nTake information from this document:\n\n> {knowledgePieceContent}",resultingParameterName:"keywords",dependentParameterNames:["knowledgePieceContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Keywords\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-keywords.book`\n-   INPUT PARAMETER `{knowledgePieceContent}` The content\n-   OUTPUT PARAMETER `{keywords}` Keywords separated by comma\n\n## Knowledge\n\n<!-- TODO: [🍆] -FORMAT JSON -->\n\n```markdown\nYou are experienced data researcher, detect the important keywords in the document.\n\n# Rules\n\n-   Write just keywords separated by comma\n\n# The document\n\nTake information from this document:\n\n> {knowledgePieceContent}\n```\n\n`-> {keywords}`\n"}],sourceFile:"./books/prepare-knowledge-keywords.book"},{title:"Prepare Knowledge-piece Title",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-title.book",formfactorName:"GENERIC",parameters:[{name:"knowledgePieceContent",description:"The content",isInput:true,isOutput:false},{name:"title",description:"The title of the document",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced content creator, write best title for the document.\n\n# Rules\n\n-   Write just title, nothing else\n-   Write maximum 5 words for the title\n\n# The document\n\n> {knowledgePieceContent}",resultingParameterName:"title",expectations:{words:{min:1,max:8}},dependentParameterNames:["knowledgePieceContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Knowledge-piece Title\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-title.book`\n-   INPUT PARAMETER `{knowledgePieceContent}` The content\n-   OUTPUT PARAMETER `{title}` The title of the document\n\n## Knowledge\n\n-   EXPECT MIN 1 WORD\n-   EXPECT MAX 8 WORDS\n\n```markdown\nYou are experienced content creator, write best title for the document.\n\n# Rules\n\n-   Write just title, nothing else\n-   Write maximum 5 words for the title\n\n# The document\n\n> {knowledgePieceContent}\n```\n\n`-> {title}`\n"}],sourceFile:"./books/prepare-knowledge-title.book"},{title:"Prepare Persona",pipelineUrl:"https://promptbook.studio/promptbook/prepare-persona.book",formfactorName:"GENERIC",parameters:[{name:"availableModels",description:"List of available model names together with their descriptions as JSON",isInput:true,isOutput:false},{name:"personaDescription",description:"Description of the persona",isInput:true,isOutput:false},{name:"modelsRequirements",description:"Specific requirements for the model",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"make-model-requirements",title:"Make modelRequirements",content:"You are an experienced AI engineer, you need to find the best models for virtual assistants:\n\n## Example\n\n```json\n[\n  {\n  \"modelName\": \"gpt-4o\",\n  \"systemMessage\": \"You are experienced AI engineer and helpfull assistant.\",\n  \"temperature\": 0.7\n  },\n  {\n    \"modelName\": \"claude-3-5-sonnet\",\n    \"systemMessage\": \"You are a friendly and knowledgeable chatbot.\",\n    \"temperature\": 0.5\n  }\n]\n```\n\n## Instructions\n\n-   Your output format is JSON array\n-   Sort best-fitting models first\n-   Omit any models that are not suitable\n-   Write just the JSON, no other text should be present\n-   Array contain items with following keys:\n    -   `modelName`: The name of the model to use\n    -   `systemMessage`: The system message to provide context to the model\n    -   `temperature`: The sampling temperature to use\n\n### Key `modelName`\n\nHere are the available models:\n\n```json\n{availableModels}\n```\n\n### Key `systemMessage`\n\nThe system message is used to communicate instructions or provide context to the model at the beginning of a conversation. It is displayed in a different format compared to user messages, helping the model understand its role in the conversation. The system message typically guides the model's behavior, sets the tone, or specifies desired output from the model. By utilizing the system message effectively, users can steer the model towards generating more accurate and relevant responses.\n\nFor example:\n\n> You are an experienced AI engineer and helpful assistant.\n\n> You are a friendly and knowledgeable chatbot.\n\n### Key `temperature`\n\nThe sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.\n\nYou can pick a value between 0 and 2. For example:\n\n-   `0.1`: Low temperature, extremely conservative and deterministic\n-   `0.5`: Medium temperature, balanced between conservative and creative\n-   `1.0`: High temperature, creative and bit random\n-   `1.5`: Very high temperature, extremely creative and often chaotic and unpredictable\n-   `2.0`: Maximum temperature, completely random and unpredictable, for some extreme creative use cases\n\n# The assistant\n\nTake this description of the persona:\n\n> {personaDescription}",resultingParameterName:"modelsRequirements",format:"JSON",dependentParameterNames:["availableModels","personaDescription"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Persona\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-persona.book`\n-   INPUT PARAMETER `{availableModels}` List of available model names together with their descriptions as JSON\n-   INPUT PARAMETER `{personaDescription}` Description of the persona\n-   OUTPUT PARAMETER `{modelsRequirements}` Specific requirements for the model\n\n## Make modelRequirements\n\n-   FORMAT JSON\n\n```markdown\nYou are an experienced AI engineer, you need to find the best models for virtual assistants:\n\n## Example\n\n\\`\\`\\`json\n[\n  {\n  \"modelName\": \"gpt-4o\",\n  \"systemMessage\": \"You are experienced AI engineer and helpfull assistant.\",\n  \"temperature\": 0.7\n  },\n  {\n    \"modelName\": \"claude-3-5-sonnet\",\n    \"systemMessage\": \"You are a friendly and knowledgeable chatbot.\",\n    \"temperature\": 0.5\n  }\n]\n\\`\\`\\`\n\n## Instructions\n\n-   Your output format is JSON array\n-   Sort best-fitting models first\n-   Omit any models that are not suitable\n-   Write just the JSON, no other text should be present\n-   Array contain items with following keys:\n    -   `modelName`: The name of the model to use\n    -   `systemMessage`: The system message to provide context to the model\n    -   `temperature`: The sampling temperature to use\n\n### Key `modelName`\n\nHere are the available models:\n\n\\`\\`\\`json\n{availableModels}\n\\`\\`\\`\n\n### Key `systemMessage`\n\nThe system message is used to communicate instructions or provide context to the model at the beginning of a conversation. It is displayed in a different format compared to user messages, helping the model understand its role in the conversation. The system message typically guides the model's behavior, sets the tone, or specifies desired output from the model. By utilizing the system message effectively, users can steer the model towards generating more accurate and relevant responses.\n\nFor example:\n\n> You are an experienced AI engineer and helpful assistant.\n\n> You are a friendly and knowledgeable chatbot.\n\n### Key `temperature`\n\nThe sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.\n\nYou can pick a value between 0 and 2. For example:\n\n-   `0.1`: Low temperature, extremely conservative and deterministic\n-   `0.5`: Medium temperature, balanced between conservative and creative\n-   `1.0`: High temperature, creative and bit random\n-   `1.5`: Very high temperature, extremely creative and often chaotic and unpredictable\n-   `2.0`: Maximum temperature, completely random and unpredictable, for some extreme creative use cases\n\n# The assistant\n\nTake this description of the persona:\n\n> {personaDescription}\n```\n\n`-> {modelsRequirements}`\n"}],sourceFile:"./books/prepare-persona.book"},{title:"Prepare Title",pipelineUrl:"https://promptbook.studio/promptbook/prepare-title.book",formfactorName:"GENERIC",parameters:[{name:"book",description:"The book to prepare the title for",isInput:true,isOutput:false},{name:"title",description:"Best title for the book",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"make-title",title:"Make title",content:"Make best title for given text which describes the workflow:\n\n## Rules\n\n-   Write just title, nothing else\n-   Title should be concise and clear - Write maximum ideally 2 words, maximum 5 words\n-   Title starts with emoticon\n-   Title should not mention the input and output of the workflow but the main purpose of the workflow\n    _For example, not \"✍ Convert Knowledge-piece to title\" but \"✍ Title\"_\n\n## The workflow\n\n> {book}",resultingParameterName:"title",expectations:{words:{min:1,max:8},lines:{min:1,max:1}},dependentParameterNames:["book"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Title\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-title.book`\n-   INPUT PARAMETER `{book}` The book to prepare the title for\n-   OUTPUT PARAMETER `{title}` Best title for the book\n\n## Make title\n\n-   EXPECT MIN 1 Word\n-   EXPECT MAX 8 Words\n-   EXPECT EXACTLY 1 Line\n\n```markdown\nMake best title for given text which describes the workflow:\n\n## Rules\n\n-   Write just title, nothing else\n-   Title should be concise and clear - Write maximum ideally 2 words, maximum 5 words\n-   Title starts with emoticon\n-   Title should not mention the input and output of the workflow but the main purpose of the workflow\n    _For example, not \"✍ Convert Knowledge-piece to title\" but \"✍ Title\"_\n\n## The workflow\n\n> {book}\n```\n\n`-> {title}`\n"}],sourceFile:"./books/prepare-title.book"}];
 
 /**
  * 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`
  */
@@ -4697,23 +4877,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
  *
@@ -4722,7 +4885,7 @@ function extractParameterNames(template) {
  */
 function unpreparePipeline(pipeline) {
     let { personas, knowledgeSources, tasks } = pipeline;
-    personas = personas.map((persona) => ({ ...persona, modelRequirements: undefined, preparationIds: undefined }));
+    personas = personas.map((persona) => ({ ...persona, modelsRequirements: undefined, preparationIds: undefined }));
     knowledgeSources = knowledgeSources.map((knowledgeSource) => ({ ...knowledgeSource, preparationIds: undefined }));
     tasks = tasks.map((task) => {
         let { dependentParameterNames } = task;
@@ -4763,7 +4926,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
@@ -4875,15 +5038,21 @@ 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) {
+        // TODO: !!! Comment this out
+        console.log('Pipeline is not prepared because title is undefined or empty', pipeline);
         return false;
     }
-    if (!pipeline.personas.every((persona) => persona.modelRequirements !== undefined)) {
+    if (!pipeline.personas.every((persona) => persona.modelsRequirements !== undefined)) {
+        // TODO: !!! Comment this out
+        console.log('Pipeline is not prepared because personas are not prepared', pipeline.personas);
         return false;
     }
     if (!pipeline.knowledgeSources.every((knowledgeSource) => knowledgeSource.preparationIds !== undefined)) {
+        // TODO: !!! Comment this out
+        console.log('Pipeline is not prepared because knowledge sources are not prepared', pipeline.knowledgeSources);
         return false;
     }
     /*
@@ -4904,6 +5073,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
 
@@ -4922,7 +5120,7 @@ function jsonStringsToJsons(object) {
     const newObject = { ...object };
     for (const [key, value] of Object.entries(object)) {
         if (typeof value === 'string' && isValidJsonString(value)) {
-            newObject[key] = JSON.parse(value);
+            newObject[key] = jsonParse(value);
         }
         else {
             newObject[key] = jsonStringsToJsons(value);
@@ -5073,35 +5271,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
  *
@@ -5344,7 +5513,7 @@ function union(...sets) {
 }
 
 /**
- * @@@
+ * Contains configuration options for parsing and generating CSV files, such as delimiters and quoting rules.
  *
  * @public exported from `@promptbook/core`
  */
@@ -5353,11 +5522,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`
  */
@@ -5381,7 +5568,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) {
@@ -5393,12 +5580,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
@@ -5413,23 +5600,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
@@ -5445,9 +5646,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 });
@@ -5456,10 +5657,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
  */
 
@@ -5468,7 +5669,7 @@ const CsvFormatDefinition = {
  *
  * @private still in development [🏢]
  */
-const JsonFormatDefinition = {
+const JsonFormatParser = {
     formatName: 'JSON',
     mimeType: 'application/json',
     isValid(value, settings, schema) {
@@ -5480,28 +5681,28 @@ const JsonFormatDefinition = {
     heal(value, settings, schema) {
         throw new Error('Not implemented');
     },
-    subvalueDefinitions: [],
+    subvalueParsers: [],
 };
 /**
  * TODO: [🧠] Maybe propper 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';
@@ -5510,19 +5711,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');
             },
         },
@@ -5532,10 +5734,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
  */
 
@@ -5543,7 +5745,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`
  */
@@ -5568,7 +5770,7 @@ function isValidXmlString(value) {
  *
  * @private still in development [🏢]
  */
-const XmlFormatDefinition = {
+const XmlFormatParser = {
     formatName: 'XML',
     mimeType: 'application/xml',
     isValid(value, settings, schema) {
@@ -5580,17 +5782,17 @@ const XmlFormatDefinition = {
     heal(value, settings, schema) {
         throw new Error('Not implemented');
     },
-    subvalueDefinitions: [],
+    subvalueParsers: [],
 };
 /**
  * TODO: [🧠] Maybe propper 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
  */
 
@@ -5599,24 +5801,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) {
@@ -5639,7 +5836,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;
     }
@@ -5670,7 +5867,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;
 }
@@ -5774,7 +5971,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`
  */
 
 /**
@@ -5836,10 +6033,12 @@ function templateParameters(template, parameters) {
             throw new PipelineExecutionError('Parameter is already opened or not closed');
         }
         if (parameters[parameterName] === undefined) {
+            console.log('!!! templateParameters 1', { parameterName, template, parameters });
             throw new PipelineExecutionError(`Parameter \`{${parameterName}}\` is not defined`);
         }
         let parameterValue = parameters[parameterName];
         if (parameterValue === undefined) {
+            console.log('!!! templateParameters 2', { parameterName, template, parameters });
             throw new PipelineExecutionError(`Parameter \`{${parameterName}}\` is not defined`);
         }
         parameterValue = valueToString(parameterValue);
@@ -5995,7 +6194,7 @@ const CountUtils = {
     PAGES: countPages,
 };
 /**
- * TODO: [🧠][🤠] This should be probbably as part of `TextFormatDefinition`
+ * TODO: [🧠][🤠] This should be probbably as part of `TextFormatParser`
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
@@ -6023,13 +6222,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) {
@@ -6251,7 +6454,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 || '');
                         }
@@ -6353,12 +6556,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);
     }
@@ -6389,16 +6596,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'))}
 
@@ -6412,53 +6619,83 @@ async function executeFormatSubvalues(options) {
         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;
+    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 probbably 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) {
@@ -6466,7 +6703,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`
  */
@@ -6475,67 +6712,167 @@ async function getExamplesForTask(task) {
 }
 
 /**
- * @@@
+ * Computes the cosine similarity between two embedding vectors
  *
- * @private internal utility of `createPipelineExecutor`
+ * 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`
  */
-async function getKnowledgeForTask(options) {
-    const { preparedPipeline, task } = options;
-    return preparedPipeline.knowledgePieces.map(({ content }) => `- ${content}`).join('\n');
-    //                                                      <- TODO: [🧠] Some smart aggregation of knowledge pieces, single-line vs multi-line vs mixed
+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
  *
  * @private internal utility of `createPipelineExecutor`
  */
-async function getReservedParametersForTask(options) {
-    const { preparedPipeline, task, pipelineIdentification } = options;
-    const context = await getContextForTask(); // <- [🏍]
-    const knowledge = await getKnowledgeForTask({ preparedPipeline, task });
-    const examples = await getExamplesForTask();
-    const currentDate = new Date().toISOString(); // <- TODO: [🧠][💩] Better
-    const modelName = RESERVED_PARAMETER_MISSING_VALUE;
-    const reservedParameters = {
-        content: RESERVED_PARAMETER_RESTRICTED,
-        context,
-        knowledge,
-        examples,
-        currentDate,
-        modelName,
-    };
-    // Note: Doublecheck that ALL reserved parameters are defined:
-    for (const parameterName of RESERVED_PARAMETER_NAMES) {
-        if (reservedParameters[parameterName] === undefined) {
-            throw new UnexpectedError(spaceTrim$1((block) => `
-                        Reserved parameter {${parameterName}} is not defined
-
-                        ${block(pipelineIdentification)}
-                    `));
-        }
-    }
-    return reservedParameters;
+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 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?
-        },
-    });
+async function getKnowledgeForTask(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 ''; // <- Note: Np knowledge present, return empty string
+    }
+    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,
+            };
+        });
+        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 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);
+    }
+}
+/**
+ * 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, parameters, pipelineIdentification } = options;
+    const context = await getContextForTask(); // <- [🏍]
+    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;
+    const reservedParameters = {
+        content: RESERVED_PARAMETER_RESTRICTED,
+        context,
+        knowledge,
+        examples,
+        currentDate,
+        modelName,
+    };
+    // Note: Doublecheck that ALL reserved parameters are defined:
+    for (const parameterName of RESERVED_PARAMETER_NAMES) {
+        if (reservedParameters[parameterName] === undefined) {
+            throw new UnexpectedError(spaceTrim$1((block) => `
+                        Reserved parameter {${parameterName}} is not defined
+
+                        ${block(pipelineIdentification)}
+                    `));
+        }
+    }
+    return reservedParameters;
+}
+
+/**
+ * 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);
     // 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:
 
@@ -6555,9 +6892,11 @@ async function executeTask(options) {
     }
     const definedParameters = Object.freeze({
         ...(await getReservedParametersForTask({
+            tools,
             preparedPipeline,
             task: currentTask,
             pipelineIdentification,
+            parameters: parametersToPass,
         })),
         ...parametersToPass,
     });
@@ -6603,6 +6942,7 @@ async function executeTask(options) {
         preparedPipeline,
         tools,
         $executionReport,
+        onProgress,
         pipelineIdentification,
         maxExecutionAttempts,
         maxParallelCount,
@@ -6630,7 +6970,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`
  */
@@ -6655,9 +6996,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`
  */
@@ -6980,6 +7324,22 @@ 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({
@@ -7040,27 +7400,48 @@ async function preparePersona(personaDescription, tools, options) {
         pipeline: await collection.getPipelineByUrl('https://promptbook.studio/promptbook/prepare-persona.book'),
         tools,
     });
-    // TODO: [🚐] Make arrayable LLMs -> single LLM DRY
     const _llms = arrayableToArray(tools.llm);
     const llmTools = _llms.length === 1 ? _llms[0] : joinLlmExecutionTools(..._llms);
-    const availableModels = await llmTools.listModels();
-    const availableModelNames = availableModels
+    const availableModels = (await llmTools.listModels())
         .filter(({ modelVariant }) => modelVariant === 'CHAT')
-        .map(({ modelName }) => modelName)
-        .join(',');
-    const result = await preparePersonaExecutor({ availableModelNames, personaDescription }).asPromise();
+        .map(({ modelName, modelDescription }) => ({
+        modelName,
+        modelDescription,
+        // <- Note: `modelTitle` and `modelVariant` is not relevant for this task
+    }));
+    const result = await preparePersonaExecutor({
+        availableModels /* <- Note: Passing as JSON */,
+        personaDescription,
+    }).asPromise();
     const { outputParameters } = result;
-    const { modelRequirements: modelRequirementsRaw } = outputParameters;
-    const modelRequirements = JSON.parse(modelRequirementsRaw);
+    const { modelsRequirements: modelsRequirementsJson } = outputParameters;
+    let modelsRequirementsUnchecked = jsonParse(modelsRequirementsJson);
     if (isVerbose) {
-        console.info(`PERSONA ${personaDescription}`, modelRequirements);
+        console.info(`PERSONA ${personaDescription}`, modelsRequirementsUnchecked);
     }
-    const { modelName, systemMessage, temperature } = modelRequirements;
-    return {
+    if (!Array.isArray(modelsRequirementsUnchecked)) {
+        // <- TODO: Book should have syntax and system to enforce shape of JSON
+        modelsRequirementsUnchecked = [modelsRequirementsUnchecked];
+        /*
+        throw new UnexpectedError(
+            spaceTrim(
+                (block) => `
+                    Invalid \`modelsRequirements\`:
+
+                    \`\`\`json
+                    ${block(JSON.stringify(modelsRequirementsUnchecked, null, 4))}
+                    \`\`\`
+                `,
+            ),
+        );
+        */
+    }
+    const modelsRequirements = modelsRequirementsUnchecked.map((modelRequirements) => ({
         modelVariant: 'CHAT',
-        modelName,
-        systemMessage,
-        temperature,
+        ...modelRequirements,
+    }));
+    return {
+        modelsRequirements,
     };
 }
 /**
@@ -7122,7 +7503,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`
  */
@@ -7229,7 +7612,7 @@ async function makeKnowledgeSourceHandler(knowledgeSource, tools, options) {
                 > },
             */
             async asJson() {
-                return JSON.parse(await tools.fs.readFile(filename, 'utf-8'));
+                return jsonParse(await tools.fs.readFile(filename, 'utf-8'));
             },
             async asText() {
                 return await tools.fs.readFile(filename, 'utf-8');
@@ -7363,9 +7746,12 @@ TODO: [🧊] This is how it can look in future
  */
 
 /**
- * @@@
+ * 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;
@@ -7487,14 +7873,14 @@ async function preparePipeline(pipeline, tools, options) {
     // TODO: [🖌][🧠] Implement some `mapAsync` function
     const preparedPersonas = new Array(personas.length);
     await forEachAsync(personas, { maxParallelCount /* <- TODO: [🪂] When there are subtasks, this maximul limit can be broken */ }, async (persona, index) => {
-        const modelRequirements = await preparePersona(persona.description, { ...tools, llm: llmToolsWithUsage }, {
+        const { modelsRequirements } = await preparePersona(persona.description, { ...tools, llm: llmToolsWithUsage }, {
             rootDirname,
             maxParallelCount /* <- TODO:  [🪂] */,
             isVerbose,
         });
         const preparedPersona = {
             ...persona,
-            modelRequirements,
+            modelsRequirements,
             preparationIds: [/* TODO: [🧊] -> */ currentPreparation.id],
             // <- TODO: [🍙] Make some standard order of json properties
         };
@@ -7883,7 +8269,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
@@ -8271,11 +8657,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`
@@ -8346,11 +8732,12 @@ function removeQuotes(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) {
@@ -8420,8 +8807,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`
  */
@@ -8478,14 +8863,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'))}
                     `));
@@ -8662,14 +9047,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: [
@@ -8696,7 +9081,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`
  */
@@ -8725,7 +9148,7 @@ const GeneratorFormfactorDefinition = {
 };
 
 /**
- * @@@
+ * Pipeline interface which is equivalent to `any`
  *
  * @see https://github.com/webgptorg/promptbook/discussions/171
  *
@@ -8740,13 +9163,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,
 };
@@ -8781,17 +9204,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',
@@ -8800,20 +9226,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: [
@@ -8836,13 +9263,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: [
@@ -8879,6 +9309,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
@@ -8887,7 +9319,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`
@@ -8909,7 +9341,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
      */
@@ -9052,8 +9484,7 @@ const jokerCommandParser = {
 };
 
 /**
- * @@@
- *
+ * @see {@link ModelVariant}
  * @public exported from `@promptbook/core`
  */
 const MODEL_VARIANTS = ['COMPLETION', 'CHAT', 'EMBEDDING' /* <- TODO [🏳] */ /* <- [🤖] */];
@@ -9485,10 +9916,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) {
@@ -9968,7 +10399,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 }) => 
@@ -9979,7 +10413,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;
@@ -10026,7 +10463,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
@@ -10059,7 +10496,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
@@ -10091,10 +10528,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`
  */
@@ -10280,7 +10718,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`
  */
@@ -10301,7 +10740,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`
  */
@@ -10358,7 +10800,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) {
@@ -11021,45 +11463,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) {
@@ -11070,10 +11510,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
 
-                  classDef input color: grey;
-                  classDef output color: grey;
+                  %% Interaction points from pipeline to outside
+                  ${block(interactionPointsMermaid)}
+
+                  %% Input and intermediate parameters
+                  ${block(inputAndIntermediateParametersMermaid)}
+
+
+                  %% Output parameters
+                  ${block(outputParametersMermaid)}
+
+                  %% Links
+                  ${block(linksMermaid)}
+
+                  %% Styles
+                  classDef ${MERMAID_INPUT_NAME} color: grey;
+                  classDef ${MERMAID_OUTPUT_NAME} color: grey;
+                  classDef ${MERMAID_RESERVED_NAME} color: grey;
+                  classDef ${MERMAID_KNOWLEDGE_NAME} color: grey;
 
               end;
 
@@ -11113,11 +11587,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) {
@@ -11131,11 +11605,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) {
@@ -12934,7 +13408,7 @@ function $initializeRunCommand(program) {
         }
         let inputParameters = {};
         if (json) {
-            inputParameters = JSON.parse(json);
+            inputParameters = jsonParse(json);
             //                <- TODO: Maybe check shape of passed JSON and if its valid parameters Record
         }
         // TODO: DRY [◽]
@@ -12986,7 +13460,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'));
@@ -13111,10 +13587,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');
         }
@@ -13157,15 +13633,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 TS)',
+        title: 'Promptbook Remote Server API ([🥺] From YML)',
         version: '1.0.0',
         description: 'API documentation for the Promptbook Remote Server',
     },
@@ -13177,6 +13653,13 @@ const openapiJson = {
                 responses: {
                     '200': {
                         description: 'Server details in markdown format.',
+                        content: {
+                            'text/markdown': {
+                                schema: {
+                                    type: 'string',
+                                },
+                            },
+                        },
                     },
                 },
             },
@@ -13207,13 +13690,22 @@ const openapiJson = {
                     },
                 },
                 responses: {
-                    '200': {
+                    '201': {
                         description: 'Successful login',
                         content: {
                             'application/json': {
                                 schema: {
                                     type: 'object',
                                     properties: {
+                                        isSuccess: {
+                                            type: 'boolean',
+                                        },
+                                        message: {
+                                            type: 'string',
+                                        },
+                                        error: {
+                                            type: 'object',
+                                        },
                                         identification: {
                                             type: 'object',
                                         },
@@ -13222,6 +13714,43 @@ const openapiJson = {
                             },
                         },
                     },
+                    '400': {
+                        description: 'Bad request or login failed',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        error: {
+                                            type: 'object',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    '401': {
+                        description: 'Authentication error',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        isSuccess: {
+                                            type: 'boolean',
+                                            enum: [false],
+                                        },
+                                        message: {
+                                            type: 'string',
+                                        },
+                                        error: {
+                                            type: 'object',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
                 },
             },
         },
@@ -13243,6 +13772,16 @@ const openapiJson = {
                             },
                         },
                     },
+                    '500': {
+                        description: 'No collection available',
+                        content: {
+                            'text/plain': {
+                                schema: {
+                                    type: 'string',
+                                },
+                            },
+                        },
+                    },
                 },
             },
         },
@@ -13274,6 +13813,28 @@ const openapiJson = {
                     },
                     '404': {
                         description: 'Book not found.',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        error: {
+                                            type: 'object',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    '500': {
+                        description: 'No collection available',
+                        content: {
+                            'text/plain': {
+                                schema: {
+                                    type: 'string',
+                                },
+                            },
+                        },
                     },
                 },
             },
@@ -13291,6 +13852,28 @@ const openapiJson = {
                                     type: 'array',
                                     items: {
                                         type: 'object',
+                                        properties: {
+                                            nonce: {
+                                                type: 'string',
+                                            },
+                                            taskId: {
+                                                type: 'string',
+                                            },
+                                            taskType: {
+                                                type: 'string',
+                                            },
+                                            status: {
+                                                type: 'string',
+                                            },
+                                            createdAt: {
+                                                type: 'string',
+                                                format: 'date-time',
+                                            },
+                                            updatedAt: {
+                                                type: 'string',
+                                                format: 'date-time',
+                                            },
+                                        },
                                     },
                                 },
                             },
@@ -13299,51 +13882,350 @@ const openapiJson = {
                 },
             },
         },
-        '/executions/new': {
-            post: {
-                summary: 'Start a new execution',
-                description: 'Starts a new execution task for a given pipeline.',
-                requestBody: {
-                    required: true,
-                    content: {
-                        'application/json': {
-                            schema: {
-                                type: 'object',
-                                properties: {
-                                    pipelineUrl: {
-                                        type: 'string',
-                                    },
-                                    inputParameters: {
-                                        type: 'object',
-                                    },
-                                    identification: {
-                                        type: 'object',
-                                    },
-                                },
-                            },
-                        },
-                    },
-                },
+        '/executions/last': {
+            get: {
+                summary: 'Get the last execution',
+                description: 'Returns details of the last execution task.',
                 responses: {
                     '200': {
-                        description: 'The newly created execution task.',
+                        description: 'The last execution task with full details.',
                         content: {
                             'application/json': {
                                 schema: {
                                     type: 'object',
-                                },
-                            },
-                        },
-                    },
-                    '400': {
-                        description: 'Invalid input.',
+                                    properties: {
+                                        nonce: {
+                                            type: 'string',
+                                        },
+                                        taskId: {
+                                            type: 'string',
+                                        },
+                                        taskType: {
+                                            type: 'string',
+                                        },
+                                        status: {
+                                            type: 'string',
+                                        },
+                                        errors: {
+                                            type: 'array',
+                                            items: {
+                                                type: 'object',
+                                            },
+                                        },
+                                        warnings: {
+                                            type: 'array',
+                                            items: {
+                                                type: 'object',
+                                            },
+                                        },
+                                        createdAt: {
+                                            type: 'string',
+                                            format: 'date-time',
+                                        },
+                                        updatedAt: {
+                                            type: 'string',
+                                            format: 'date-time',
+                                        },
+                                        currentValue: {
+                                            type: 'object',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    '404': {
+                        description: 'No execution tasks found.',
+                        content: {
+                            'text/plain': {
+                                schema: {
+                                    type: 'string',
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        '/executions/{taskId}': {
+            get: {
+                summary: 'Get specific execution',
+                description: 'Returns details of a specific execution task.',
+                parameters: [
+                    {
+                        in: 'path',
+                        name: 'taskId',
+                        required: true,
+                        schema: {
+                            type: 'string',
+                        },
+                        description: 'The ID of the execution task to retrieve.',
+                    },
+                ],
+                responses: {
+                    '200': {
+                        description: 'The execution task with full details.',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        nonce: {
+                                            type: 'string',
+                                        },
+                                        taskId: {
+                                            type: 'string',
+                                        },
+                                        taskType: {
+                                            type: 'string',
+                                        },
+                                        status: {
+                                            type: 'string',
+                                        },
+                                        errors: {
+                                            type: 'array',
+                                            items: {
+                                                type: 'object',
+                                            },
+                                        },
+                                        warnings: {
+                                            type: 'array',
+                                            items: {
+                                                type: 'object',
+                                            },
+                                        },
+                                        createdAt: {
+                                            type: 'string',
+                                            format: 'date-time',
+                                        },
+                                        updatedAt: {
+                                            type: 'string',
+                                            format: 'date-time',
+                                        },
+                                        currentValue: {
+                                            type: 'object',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    '404': {
+                        description: 'Execution task not found.',
+                        content: {
+                            'text/plain': {
+                                schema: {
+                                    type: 'string',
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        '/executions/new': {
+            post: {
+                summary: 'Start a new execution',
+                description: 'Starts a new execution task for a given pipeline.',
+                requestBody: {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                properties: {
+                                    pipelineUrl: {
+                                        type: 'string',
+                                        description: 'URL of the pipeline to execute',
+                                    },
+                                    book: {
+                                        type: 'string',
+                                        description: 'Alternative field for pipelineUrl',
+                                    },
+                                    inputParameters: {
+                                        type: 'object',
+                                        description: 'Parameters for pipeline execution',
+                                    },
+                                    identification: {
+                                        type: 'object',
+                                        description: 'User identification data',
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                responses: {
+                    '200': {
+                        description: 'The newly created execution task.',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                },
+                            },
+                        },
+                    },
+                    '400': {
+                        description: 'Invalid input.',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        error: {
+                                            type: 'object',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    '404': {
+                        description: 'Pipeline not found.',
+                        content: {
+                            'text/plain': {
+                                schema: {
+                                    type: 'string',
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        '/api-docs': {
+            get: {
+                summary: 'API documentation UI',
+                description: 'Swagger UI for API documentation',
+                responses: {
+                    '200': {
+                        description: 'HTML Swagger UI',
+                    },
+                },
+            },
+        },
+        '/swagger': {
+            get: {
+                summary: 'API documentation UI (alternative path)',
+                description: 'Swagger UI for API documentation',
+                responses: {
+                    '200': {
+                        description: 'HTML Swagger UI',
+                    },
+                },
+            },
+        },
+        '/openapi': {
+            get: {
+                summary: 'OpenAPI specification',
+                description: 'Returns the OpenAPI JSON specification',
+                responses: {
+                    '200': {
+                        description: 'OpenAPI specification',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                },
+                            },
+                        },
                     },
                 },
             },
         },
     },
-    components: {},
-    tags: [],
+    components: {
+        schemas: {
+            Error: {
+                type: 'object',
+                properties: {
+                    error: {
+                        type: 'object',
+                    },
+                },
+            },
+            ExecutionTaskSummary: {
+                type: 'object',
+                properties: {
+                    nonce: {
+                        type: 'string',
+                    },
+                    taskId: {
+                        type: 'string',
+                    },
+                    taskType: {
+                        type: 'string',
+                    },
+                    status: {
+                        type: 'string',
+                    },
+                    createdAt: {
+                        type: 'string',
+                        format: 'date-time',
+                    },
+                    updatedAt: {
+                        type: 'string',
+                        format: 'date-time',
+                    },
+                },
+            },
+            ExecutionTaskFull: {
+                type: 'object',
+                properties: {
+                    nonce: {
+                        type: 'string',
+                    },
+                    taskId: {
+                        type: 'string',
+                    },
+                    taskType: {
+                        type: 'string',
+                    },
+                    status: {
+                        type: 'string',
+                    },
+                    errors: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                        },
+                    },
+                    warnings: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                        },
+                    },
+                    createdAt: {
+                        type: 'string',
+                        format: 'date-time',
+                    },
+                    updatedAt: {
+                        type: 'string',
+                        format: 'date-time',
+                    },
+                    currentValue: {
+                        type: 'object',
+                    },
+                },
+            },
+        },
+    },
+    tags: [
+        {
+            name: 'Books',
+            description: 'Operations related to books and pipelines',
+        },
+        {
+            name: 'Executions',
+            description: 'Operations related to execution tasks',
+        },
+        {
+            name: 'Authentication',
+            description: 'Authentication operations',
+        },
+    ],
 };
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -13417,7 +14299,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) {
@@ -13714,6 +14596,7 @@ function startRemoteServer(options) {
                         promptResult = await llm.callCompletionModel(prompt);
                         break;
                     case 'EMBEDDING':
+                        console.log('!!! llm (EMBEDDING)', llm);
                         if (llm.callEmbeddingModel === undefined) {
                             // Note: [0] This check should not be a thing
                             throw new PipelineExecutionError(`Embedding model is not available`);
@@ -13988,7 +14871,7 @@ function $initializeTestCommand(program) {
                     }
                 }
                 if (filename.endsWith('.bookc')) {
-                    pipeline = JSON.parse(await readFile(filename, 'utf-8'));
+                    pipeline = jsonParse(await readFile(filename, 'utf-8'));
                 }
                 else {
                     if (isVerbose) {
@@ -14111,9 +14994,11 @@ const _AnthropicClaudeMetadataRegistration = $llmToolsMetadataRegister.register(
     packageName: '@promptbook/anthropic-claude',
     className: 'AnthropicClaudeExecutionTools',
     envVariables: ['ANTHROPIC_CLAUDE_API_KEY'],
+    trustLevel: 'CLOSED',
+    order: MODEL_ORDERS.TOP_TIER,
     getBoilerplateConfiguration() {
         return {
-            title: 'Anthropic Claude (boilerplate)',
+            title: 'Anthropic Claude',
             packageName: '@promptbook/anthropic-claude',
             className: 'AnthropicClaudeExecutionTools',
             options: {
@@ -14155,7 +15040,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`
@@ -14169,8 +15054,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`),
             },
         },
         {
@@ -14179,8 +15064,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`),
             },
         },
         {
@@ -14225,7 +15110,7 @@ const ANTHROPIC_CLAUDE_MODELS = exportJson({
         },
         {
             modelVariant: 'CHAT',
-            modelTitle: '	Claude Instant 1.2',
+            modelTitle: 'Claude Instant 1.2',
             modelName: 'claude-instant-1.2',
             modelDescription: 'Older, faster Claude model optimized for high throughput applications. Lower cost but less capable than newer models. 100K context window.',
             pricing: {
@@ -14239,8 +15124,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`),
             },
         },
         {
@@ -14287,14 +15172,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 };
 }
 
@@ -14649,9 +15538,11 @@ const _AzureOpenAiMetadataRegistration = $llmToolsMetadataRegister.register({
     packageName: '@promptbook/azure-openai',
     className: 'AzureOpenAiExecutionTools',
     envVariables: ['AZUREOPENAI_RESOURCE_NAME', 'AZUREOPENAI_DEPLOYMENT_NAME', 'AZUREOPENAI_API_KEY'],
+    trustLevel: 'CLOSED_BUSINESS',
+    order: MODEL_ORDERS.NORMAL,
     getBoilerplateConfiguration() {
         return {
-            title: 'Azure Open AI (boilerplate)',
+            title: 'Azure Open AI',
             packageName: '@promptbook/azure-openai',
             className: 'AzureOpenAiExecutionTools',
             options: {
@@ -14706,7 +15597,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/
@@ -14735,7 +15626,7 @@ const OPENAI_MODELS = exportJson({
             modelDescription: 'Legacy completion model with strong performance on text generation tasks. Optimized for complex instructions and longer outputs.',
             pricing: {
                 prompt: computeUsage(`$2.00 / 1M tokens`),
-                output: computeUsage(`$2.00 / 1M tokens`), // <- not sure
+                output: computeUsage(`$2.00 / 1M tokens`),
             },
         },
         /**/
@@ -14877,8 +15768,8 @@ const OPENAI_MODELS = exportJson({
             modelName: 'gpt-3.5-turbo',
             modelDescription: 'Latest version of GPT-3.5 Turbo with improved performance and instruction following capabilities. Default 4K context window with options for 16K.',
             pricing: {
-                prompt: computeUsage(`$3.00 / 1M tokens`),
-                output: computeUsage(`$6.00 / 1M tokens`), // <- Not sure, refer to gpt-3.5-turbo in Fine-tuning models
+                prompt: computeUsage(`$0.50 / 1M tokens`),
+                output: computeUsage(`$1.50 / 1M tokens`),
             },
         },
         /**/
@@ -14902,7 +15793,7 @@ const OPENAI_MODELS = exportJson({
             modelDescription: 'Efficient legacy completion model with a good balance of performance and speed. Suitable for straightforward text generation tasks.',
             pricing: {
                 prompt: computeUsage(`$0.40 / 1M tokens`),
-                output: computeUsage(`$0.40 / 1M tokens`), // <- Not sure
+                output: computeUsage(`$0.40 / 1M tokens`),
             },
         },
         /**/
@@ -14956,7 +15847,7 @@ const OPENAI_MODELS = exportJson({
             modelDescription: 'Preview version of GPT-4 Turbo that points to the latest model version. Features improved instruction following, 128K token context window and lower latency.',
             pricing: {
                 prompt: computeUsage(`$10.00 / 1M tokens`),
-                output: computeUsage(`$30.00 / 1M tokens`), // <- Not sure, just for gpt-4-turbo
+                output: computeUsage(`$30.00 / 1M tokens`),
             },
         },
         /**/
@@ -14967,7 +15858,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
             },
@@ -15060,8 +15951,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`),
             },
         },
         /**/
@@ -15107,10 +15998,10 @@ const OPENAI_MODELS = exportJson({
             modelVariant: 'CHAT',
             modelTitle: 'o1',
             modelName: 'o1',
+            modelDescription: "OpenAI's advanced reasoning model focused on logic and problem-solving. Designed for complex analytical tasks with rigorous step-by-step reasoning. 128K context window.",
             pricing: {
-                prompt: computeUsage(`$3.00 / 1M tokens`),
-                output: computeUsage(`$12.00 / 1M tokens`),
-                // <- TODO: !! Unsure, check the pricing
+                prompt: computeUsage(`$15.00 / 1M tokens`),
+                output: computeUsage(`$60.00 / 1M tokens`),
             },
         },
         /**/
@@ -15119,7 +16010,7 @@ const OPENAI_MODELS = exportJson({
             modelVariant: 'CHAT',
             modelTitle: 'o3-mini',
             modelName: 'o3-mini',
-            modelDescription: 'Compact and efficient reasoning model specializing in problem-solving with a focus on research and analysis tasks.',
+            modelDescription: 'Cost-effective reasoning model optimized for academic and scientific problem-solving. Efficient performance on STEM tasks with deep mathematical and scientific knowledge. 128K context window.',
             pricing: {
                 prompt: computeUsage(`$3.00 / 1M tokens`),
                 output: computeUsage(`$12.00 / 1M tokens`),
@@ -15186,6 +16077,10 @@ class AzureOpenAiExecutionTools {
          * OpenAI Azure API client.
          */
         this.client = null;
+        // TODO: Allow configuring rate limits via options
+        this.limiter = new Bottleneck({
+            minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE),
+        });
     }
     get title() {
         return 'Azure OpenAI';
@@ -15263,7 +16158,9 @@ class AzureOpenAiExecutionTools {
                 console.info(colors.bgWhite('messages'), JSON.stringify(messages, null, 4));
             }
             const rawRequest = [modelName, messages, modelSettings];
-            const rawResponse = await this.withTimeout(client.getChatCompletions(...rawRequest)).catch((error) => {
+            const rawResponse = await this.limiter
+                .schedule(() => this.withTimeout(client.getChatCompletions(...rawRequest)))
+                .catch((error) => {
                 if (this.options.isVerbose) {
                     console.info(colors.bgRed('error'), error);
                 }
@@ -15359,7 +16256,9 @@ class AzureOpenAiExecutionTools {
                 [rawPromptContent],
                 modelSettings,
             ];
-            const rawResponse = await this.withTimeout(client.getCompletions(...rawRequest)).catch((error) => {
+            const rawResponse = await this.limiter
+                .schedule(() => this.withTimeout(client.getCompletions(...rawRequest)))
+                .catch((error) => {
                 if (this.options.isVerbose) {
                     console.info(colors.bgRed('error'), error);
                 }
@@ -15499,9 +16398,11 @@ const _DeepseekMetadataRegistration = $llmToolsMetadataRegister.register({
     packageName: '@promptbook/deepseek',
     className: 'DeepseekExecutionTools',
     envVariables: ['DEEPSEEK_GENERATIVE_AI_API_KEY'],
+    trustLevel: 'UNTRUSTED',
+    order: MODEL_ORDERS.NORMAL,
     getBoilerplateConfiguration() {
         return {
-            title: 'Deepseek (boilerplate)',
+            title: 'Deepseek',
             packageName: '@promptbook/deepseek',
             className: 'DeepseekExecutionTools',
             options: {
@@ -15698,6 +16599,67 @@ function createExecutionToolsFromVercelProvider(options) {
     };
 }
 
+/**
+ * List of available Deepseek models with descriptions
+ *
+ * Note: Done at 2025-05-06
+ *
+ * @see https://www.deepseek.com/models
+ * @public exported from `@promptbook/deepseek`
+ */
+const DEEPSEEK_MODELS = exportJson({
+    name: 'DEEPSEEK_MODELS',
+    value: [
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Deepseek Chat',
+            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(`$0.80 / 1M tokens`),
+                output: computeUsage(`$1.60 / 1M tokens`),
+            },
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Deepseek Reasoner',
+            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(`$3.50 / 1M tokens`),
+                output: computeUsage(`$7.00 / 1M tokens`),
+            },
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'DeepSeek V3',
+            modelName: 'deepseek-v3-0324',
+            modelDescription: 'Advanced general-purpose model with improved reasoning, coding abilities, and multimodal understanding. Built on the latest DeepSeek architecture with enhanced knowledge representation.',
+            pricing: {
+                prompt: computeUsage(`$1.50 / 1M tokens`),
+                output: computeUsage(`$3.00 / 1M tokens`),
+            },
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'DeepSeek R1',
+            modelName: 'deepseek-r1',
+            modelDescription: 'Research-focused model optimized for scientific problem-solving and analytical tasks. Excellent performance on tasks requiring domain-specific expertise and critical thinking.',
+            pricing: {
+                prompt: computeUsage(`$5.00 / 1M tokens`),
+                output: computeUsage(`$10.00 / 1M tokens`),
+            },
+        },
+        // <- [🕕]
+    ],
+});
+/**
+ * TODO: [🧠] Add information about context window sizes, capabilities, and relative performance characteristics
+ * TODO: [🎰] Some mechanism to auto-update available models
+ * TODO: [🧠] Verify pricing information is current with Deepseek's official documentation
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */
+
 /**
  * Execution Tools for calling Deepseek API.
  *
@@ -15719,18 +16681,7 @@ const createDeepseekExecutionTools = Object.assign((options) => {
         title: 'Deepseek',
         description: 'Implementation of Deepseek models',
         vercelProvider: deepseekVercelProvider,
-        availableModels: [
-            {
-                modelName: 'deepseek-chat',
-                modelVariant: 'CHAT',
-            },
-            {
-                modelName: 'deepseek-reasoner',
-                modelVariant: 'CHAT',
-            },
-            // <- [🕕]
-            // <- TODO: How picking of the default model looks like in `createExecutionToolsFromVercelProvider`
-        ],
+        availableModels: DEEPSEEK_MODELS,
         ...options,
     });
 }, {
@@ -15770,9 +16721,11 @@ const _GoogleMetadataRegistration = $llmToolsMetadataRegister.register({
     packageName: '@promptbook/google',
     className: 'GoogleExecutionTools',
     envVariables: ['GOOGLE_GENERATIVE_AI_API_KEY'],
+    trustLevel: 'CLOSED',
+    order: MODEL_ORDERS.NORMAL,
     getBoilerplateConfiguration() {
         return {
-            title: 'Google Gemini (boilerplate)',
+            title: 'Google Gemini',
             packageName: '@promptbook/google',
             className: 'GoogleExecutionTools',
             options: {
@@ -15805,6 +16758,173 @@ const _GoogleMetadataRegistration = $llmToolsMetadataRegister.register({
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
+/**
+ * List of available Google models with descriptions
+ *
+ * Note: Done at 2025-05-06
+ *
+ * @see https://ai.google.dev/models/gemini
+ * @public exported from `@promptbook/google`
+ */
+const GOOGLE_MODELS = exportJson({
+    name: 'GOOGLE_MODELS',
+    value: [
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 2.5 Pro',
+            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(`$8.00 / 1M tokens`),
+                output: computeUsage(`$24.00 / 1M tokens`),
+            },
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 2.0 Flash',
+            modelName: 'gemini-2.0-flash',
+            modelDescription: 'Fast, efficient model optimized for rapid response times. Good balance between performance and cost, with strong capabilities across text, code, and reasoning tasks. 128K context window.',
+            pricing: {
+                prompt: computeUsage(`$0.35 / 1M tokens`),
+                output: computeUsage(`$1.05 / 1M tokens`),
+            },
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 2.0 Flash Lite',
+            modelName: 'gemini-2.0-flash-lite',
+            modelDescription: 'Streamlined version of Gemini 2.0 Flash, designed for extremely low-latency applications and edge deployments. Optimized for efficiency while maintaining core capabilities.',
+            pricing: {
+                prompt: computeUsage(`$0.20 / 1M tokens`),
+                output: computeUsage(`$0.60 / 1M tokens`),
+            },
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 2.0 Flash Thinking',
+            modelName: 'gemini-2.0-flash-thinking-exp-01-21',
+            modelDescription: 'Experimental model focused on enhanced reasoning with explicit chain-of-thought processes. Designed for tasks requiring structured thinking and problem-solving approaches.',
+            pricing: {
+                prompt: computeUsage(`$0.35 / 1M tokens`),
+                output: computeUsage(`$1.05 / 1M tokens`),
+            },
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Flash',
+            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.25 / 1M tokens`),
+                output: computeUsage(`$0.75 / 1M tokens`),
+            },
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Flash Latest',
+            modelName: 'gemini-1.5-flash-latest',
+            modelDescription: 'Points to the latest version of Gemini 1.5 Flash, ensuring access to the most recent improvements and bug fixes while maintaining stable interfaces.',
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Flash 001',
+            modelName: 'gemini-1.5-flash-001',
+            modelDescription: 'First stable release of Gemini 1.5 Flash model with reliable performance characteristics for production applications. 1M token context window.',
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Flash 002',
+            modelName: 'gemini-1.5-flash-002',
+            modelDescription: 'Improved version of Gemini 1.5 Flash with enhanced instruction following and more consistent outputs. Refined for better application integration.',
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Flash Exp',
+            modelName: 'gemini-1.5-flash-exp-0827',
+            modelDescription: 'Experimental version of Gemini 1.5 Flash with new capabilities being tested. May offer improved performance but with potential behavior differences from stable releases.',
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Flash 8B',
+            modelName: 'gemini-1.5-flash-8b',
+            modelDescription: 'Compact 8B parameter model optimized for efficiency and deployment in resource-constrained environments. Good performance despite smaller size.',
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Flash 8B Latest',
+            modelName: 'gemini-1.5-flash-8b-latest',
+            modelDescription: 'Points to the most recent version of the compact 8B parameter model, providing latest improvements while maintaining a small footprint.',
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Flash 8B Exp',
+            modelName: 'gemini-1.5-flash-8b-exp-0924',
+            modelDescription: 'Experimental version of the 8B parameter model with new capabilities and optimizations being evaluated for future stable releases.',
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Flash 8B Exp',
+            modelName: 'gemini-1.5-flash-8b-exp-0827',
+            modelDescription: 'August experimental release of the efficient 8B parameter model with specific improvements to reasoning capabilities and response quality.',
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Pro Latest',
+            modelName: 'gemini-1.5-pro-latest',
+            modelDescription: 'Points to the most recent version of the flagship Gemini 1.5 Pro model, ensuring access to the latest capabilities and improvements.',
+            pricing: {
+                prompt: computeUsage(`$7.00 / 1M tokens`),
+                output: computeUsage(`$21.00 / 1M tokens`),
+            },
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Pro',
+            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(`$6.00 / 1M tokens`),
+                output: computeUsage(`$18.00 / 1M tokens`),
+            },
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Pro 001',
+            modelName: 'gemini-1.5-pro-001',
+            modelDescription: 'First stable release of Gemini 1.5 Pro with consistent performance characteristics and reliable behavior for production applications.',
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Pro 002',
+            modelName: 'gemini-1.5-pro-002',
+            modelDescription: 'Refined version of Gemini 1.5 Pro with improved instruction following, better multimodal understanding, and more consistent outputs.',
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.5 Pro Exp',
+            modelName: 'gemini-1.5-pro-exp-0827',
+            modelDescription: 'Experimental version of Gemini 1.5 Pro with new capabilities and optimizations being tested before wider release. May offer improved performance.',
+        },
+        {
+            modelVariant: 'CHAT',
+            modelTitle: 'Gemini 1.0 Pro',
+            modelName: 'gemini-1.0-pro',
+            modelDescription: 'Original Gemini series foundation model with solid multimodal capabilities. 32K context window with good performance on text, code, and basic vision tasks.',
+            pricing: {
+                prompt: computeUsage(`$0.35 / 1M tokens`),
+                output: computeUsage(`$1.05 / 1M tokens`),
+            },
+        },
+        // <- [🕕]
+    ],
+});
+/**
+ * TODO: [🧠] Add information about context window sizes, capabilities, and relative performance characteristics
+ * TODO: [🎰] Some mechanism to auto-update available models
+ * TODO: [🧠] Verify pricing information is current with Google's official documentation
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */
+
 /**
  * Execution Tools for calling Google Gemini API.
  *
@@ -15826,29 +16946,7 @@ const createGoogleExecutionTools = Object.assign((options) => {
         title: 'Google',
         description: 'Implementation of Google models',
         vercelProvider: googleGeminiVercelProvider,
-        availableModels: [
-            // TODO: [🕘] Maybe list models in same way as in other providers - in separate file with metadata
-            'gemini-2.5-pro-preview-03-25',
-            'gemini-2.0-flash',
-            'gemini-2.0-flash-lite',
-            'gemini-2.0-flash-thinking-exp-01-21',
-            'gemini-1.5-flash',
-            'gemini-1.5-flash-latest',
-            'gemini-1.5-flash-001',
-            'gemini-1.5-flash-002',
-            'gemini-1.5-flash-exp-0827',
-            'gemini-1.5-flash-8b',
-            'gemini-1.5-flash-8b-latest',
-            'gemini-1.5-flash-8b-exp-0924',
-            'gemini-1.5-flash-8b-exp-0827',
-            'gemini-1.5-pro-latest',
-            'gemini-1.5-pro',
-            'gemini-1.5-pro-001',
-            'gemini-1.5-pro-002',
-            'gemini-1.5-pro-exp-0827',
-            'gemini-1.0-pro',
-            // <- [🕕]
-        ].map((modelName) => ({ modelName, modelVariant: 'CHAT' })),
+        availableModels: GOOGLE_MODELS,
         ...options,
     });
 }, {
@@ -15888,13 +16986,16 @@ const _OpenAiMetadataRegistration = $llmToolsMetadataRegister.register({
     packageName: '@promptbook/openai',
     className: 'OpenAiExecutionTools',
     envVariables: ['OPENAI_API_KEY'],
+    trustLevel: 'CLOSED',
+    order: MODEL_ORDERS.TOP_TIER,
     getBoilerplateConfiguration() {
         return {
-            title: 'Open AI (boilerplate)',
+            title: 'Open AI',
             packageName: '@promptbook/openai',
             className: 'OpenAiExecutionTools',
             options: {
                 apiKey: 'sk-',
+                maxRequestsPerMinute: DEFAULT_MAX_REQUESTS_PER_MINUTE,
             },
         };
     },
@@ -15914,9 +17015,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`
@@ -15928,9 +17029,11 @@ const _OpenAiAssistantMetadataRegistration = $llmToolsMetadataRegister.register(
     className: 'OpenAiAssistantExecutionTools',
     envVariables: null,
     //            <- TODO: ['OPENAI_API_KEY', 'OPENAI_ASSISTANT_ID']
+    trustLevel: 'CLOSED',
+    order: MODEL_ORDERS.NORMAL,
     getBoilerplateConfiguration() {
         return {
-            title: 'Open AI Assistant (boilerplate)',
+            title: 'Open AI Assistant',
             packageName: '@promptbook/openai',
             className: 'OpenAiAssistantExecutionTools',
             options: {
@@ -15975,20 +17078,39 @@ function computeOpenAiUsage(promptContent, // <- Note: Intentionally using [] to
 resultContent, rawResponse) {
     var _a, _b;
     if (rawResponse.usage === undefined) {
+        console.log('!!! computeOpenAiUsage', 'The usage is not defined in the response from OpenAI');
         throw new PipelineExecutionError('The usage is not defined in the response from OpenAI');
     }
     if (((_a = rawResponse.usage) === null || _a === void 0 ? void 0 : _a.prompt_tokens) === undefined) {
+        console.log('!!! computeOpenAiUsage', 'In OpenAI response `usage.prompt_tokens` not defined');
         throw new PipelineExecutionError('In OpenAI response `usage.prompt_tokens` not defined');
     }
     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;
+        }
+    }
+    console.log('!!! computeOpenAiUsage', {
+        inputTokens,
+        outputTokens,
+        rawResponse,
+        'rawResponse.model': rawResponse.model,
+        OPENAI_MODELS,
+        resultContent,
+        modelInfo,
+    });
     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,
@@ -16023,6 +17145,10 @@ class OpenAiExecutionTools {
          * OpenAI API client.
          */
         this.client = null;
+        // TODO: Allow configuring rate limits via options
+        this.limiter = new Bottleneck({
+            minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE),
+        });
     }
     get title() {
         return 'OpenAI';
@@ -16126,7 +17252,9 @@ class OpenAiExecutionTools {
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
-        const rawResponse = await client.chat.completions.create(rawRequest).catch((error) => {
+        const rawResponse = await this.limiter
+            .schedule(() => client.chat.completions.create(rawRequest))
+            .catch((error) => {
             assertsError(error);
             if (this.options.isVerbose) {
                 console.info(colors.bgRed('error'), error);
@@ -16203,7 +17331,9 @@ class OpenAiExecutionTools {
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
-        const rawResponse = await client.completions.create(rawRequest).catch((error) => {
+        const rawResponse = await this.limiter
+            .schedule(() => client.completions.create(rawRequest))
+            .catch((error) => {
             assertsError(error);
             if (this.options.isVerbose) {
                 console.info(colors.bgRed('error'), error);
@@ -16267,7 +17397,9 @@ class OpenAiExecutionTools {
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
-        const rawResponse = await client.embeddings.create(rawRequest).catch((error) => {
+        const rawResponse = await this.limiter
+            .schedule(() => client.embeddings.create(rawRequest))
+            .catch((error) => {
             assertsError(error);
             if (this.options.isVerbose) {
                 console.info(colors.bgRed('error'), error);
@@ -16365,6 +17497,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';
@@ -16566,9 +17699,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`
@@ -16581,9 +17714,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
  */
@@ -16810,14 +17942,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: [🤛] */
 /**
@@ -16835,7 +17967,7 @@ const _BoilerplateScraperMetadataRegistration = $scrapersMetadataRegister.regist
  */
 
 /**
- * Scraper of @@@ files
+ * Scraper of @@ files
  *
  * @see `documentationUrl` for more details
  * @public exported from `@promptbook/boilerplate`
@@ -16853,30 +17985,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, {
@@ -16886,7 +18018,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}"`;
@@ -16912,7 +18044,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,
@@ -16943,7 +18075,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
  */
 
 /**
@@ -17277,7 +18409,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`
  */
@@ -17304,7 +18437,7 @@ const _LegacyDocumentScraperRegistration = $scrapersRegister.register(createLega
  */
 
 /**
- * @@@
+ * Creates a scraper for document content.
  *
  * @public exported from `@promptbook/documents`
  */
@@ -17331,7 +18464,7 @@ const _DocumentScraperRegistration = $scrapersRegister.register(createDocumentSc
  */
 
 /**
- * @@@
+ * Creates a scraper for markdown content.
  *
  * @public exported from `@promptbook/markdown-utils`
  */
@@ -17437,8 +18570,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 });
@@ -17460,11 +18593,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,
@@ -17608,7 +18741,8 @@ class PdfScraper {
  */
 
 /**
- * @@@
+ * Factory function to create an instance of PdfScraper.
+ * It bundles the scraper class with its metadata.
  *
  * @public exported from `@promptbook/pdf`
  */
@@ -17784,7 +18918,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`
  */