@promptbook/node 0.92.0-23 → 0.92.0-25

package/umd/index.umd.js

@@ -46,7 +46,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-23';
+    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-25';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -118,11 +118,20 @@
      */
     const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
     /**
-     * @@@
+     * Threshold value that determines when a dataset is considered "big"
+     * and may require special handling or optimizations
+     *
+     * For example, when error occurs in one item of the big dataset, it will not fail the whole pipeline
      *
      * @public exported from `@promptbook/core`
      */
     const BIG_DATASET_TRESHOLD = 50;
+    /**
+     * Placeholder text used to represent a placeholder value of failed operation
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const FAILED_VALUE_PLACEHOLDER = '!?';
     // <- TODO: [🧠] Better system for generator warnings - not always "code" and "by `@promptbook/cli`"
     /**
      * The maximum number of iterations for a loops
@@ -673,13 +682,13 @@
      */
     const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
     /**
-     * @@@
+     * Placeholder value indicating a parameter is missing its value.
      *
      * @private within the repository
      */
     const RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
     /**
-     * @@@
+     * Placeholder value indicating a parameter is restricted and cannot be used directly.
      *
      * @private within the repository
      */
@@ -1552,7 +1561,7 @@
         /**
          * Constructs a pipeline collection from pipelines
          *
-         * @param pipelines @@@
+         * @param pipelines Array of pipeline JSON objects to include in the collection
          *
          * Note: During the construction logic of all pipelines are validated
          * Note: It is not recommended to use this constructor directly, use `createCollectionFromJson` *(or other variant)* instead
@@ -1682,8 +1691,8 @@
      * @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);
@@ -2642,6 +2651,15 @@
                         mappedData.push(mappedRow);
                         if (onProgress) {
                             // Note: Report the CSV with all rows mapped so far
+                            /*
+                            !!!!
+                             // Report progress with updated value
+                                const progressData = mappedData.map((row, i) =>
+                                  i > index ? { ...row, [outputParameterName]: PENDING_VALUE_PLACEHOLDER } : row,
+                              );
+
+
+                            */
                             await onProgress(papaparse.unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS }));
                         }
                     }
@@ -2858,7 +2876,7 @@
             else if (!availableParametersNames.has(parameterName) && expectedParameterNames.has(parameterName)) ;
         }
         if (expectedParameterNames.size === 0) {
-            // Note: [👨‍👨‍👧] Now we can freeze `mappedParameters` to prevent @@@
+            // Note: [👨‍👨‍👧] Now we can freeze `mappedParameters` to prevent accidental modifications after mapping
             Object.freeze(mappedParameters);
             return mappedParameters;
         }
@@ -2889,7 +2907,7 @@
         for (let i = 0; i < expectedParameterNames.size; i++) {
             mappedParameters[expectedParameterNamesArray[i]] = availableParameters[availableParametersNamesArray[i]];
         }
-        // Note: [👨‍👨‍👧] Now we can freeze `mappedParameters` to prevent @@@
+        // Note: [👨‍👨‍👧] Now we can freeze `mappedParameters` to prevent accidental modifications after mapping
         Object.freeze(mappedParameters);
         return mappedParameters;
     }
@@ -3640,10 +3658,10 @@
     */
 
     /**
-     * @@@
+     * Removes diacritic marks (accents) from characters in a string.
      *
-     * @param input @@@
-     * @returns @@@
+     * @param input The string containing diacritics to be normalized.
+     * @returns The string with diacritics removed or normalized.
      * @public exported from `@promptbook/utils`
      */
     function removeDiacritics(input) {
@@ -4131,15 +4149,14 @@
                     const highLevelError = new PipelineExecutionError(spaceTrim__default["default"]((block) => `
                             ${error.message}
 
-                            This is error in FOREACH command when mapping data
+                            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}
                         `));
                     if (length > BIG_DATASET_TRESHOLD) {
                         console.error(highLevelError);
-                        return '~';
+                        return FAILED_VALUE_PLACEHOLDER;
                     }
                     throw highLevelError;
                 }
@@ -4163,14 +4180,13 @@
                 catch (error) {
                     if (length > BIG_DATASET_TRESHOLD) {
                         console.error(spaceTrim__default["default"]((block) => `
-                              Error in FOREACH command:
+                              ${error.message}
 
-                              ${block(pipelineIdentification)}
+                              This is error in FOREACH command when processing ${formatDefinition.formatName} ${subvalueParser.subvalueName} data (${index + 1}/${length})
 
                               ${block(pipelineIdentification)}
-                              Subparameter index: ${index}
                           `));
-                        return '~';
+                        return FAILED_VALUE_PLACEHOLDER;
                     }
                     throw error;
                 }
@@ -5009,7 +5025,8 @@
      */
 
     /**
-     * @@@
+     * Safely retrieves the global scope object (window in browser, global in Node.js)
+     * regardless of the JavaScript environment in which the code is running
      *
      * Note: `$` is used to indicate that this function is not a pure function - it access global scope
      *
@@ -5020,10 +5037,10 @@
     }
 
     /**
-     * @@@
+     * Normalizes a text string to SCREAMING_CASE (all uppercase with underscores).
      *
-     * @param text @@@
-     * @returns @@@
+     * @param text The text string to be converted to SCREAMING_CASE format.
+     * @returns The normalized text in SCREAMING_CASE format.
      * @example 'HELLO_WORLD'
      * @example 'I_LOVE_PROMPTBOOK'
      * @public exported from `@promptbook/utils`
@@ -5075,10 +5092,10 @@
      */
 
     /**
-     * @@@
+     * Normalizes a text string to snake_case format.
      *
-     * @param text @@@
-     * @returns @@@
+     * @param text The text string to be converted to snake_case format.
+     * @returns The normalized text in snake_case format.
      * @example 'hello_world'
      * @example 'i_love_promptbook'
      * @public exported from `@promptbook/utils`
@@ -5148,10 +5165,11 @@
      */
 
     /**
-     * @@@
+     * Registry for all available scrapers in the system.
+     * Central point for registering and accessing different types of content scrapers.
      *
      * Note: `$` is used to indicate that this interacts with the global scope
-     * @singleton Only one instance of each register is created per build, but thare can be more @@@
+     * @singleton Only one instance of each register is created per build, but there can be more than one in different build modules
      * @public exported from `@promptbook/core`
      */
     const $scrapersRegister = new $Register('scraper_constructors');
@@ -5247,10 +5265,10 @@
      */
 
     /**
-     * @@@
+     * Converts a given text to kebab-case format.
      *
-     * @param text @@@
-     * @returns @@@
+     * @param text The text to be converted.
+     * @returns The kebab-case formatted string.
      * @example 'hello-world'
      * @example 'i-love-promptbook'
      * @public exported from `@promptbook/utils`
@@ -5319,7 +5337,8 @@
      */
 
     /**
-     * @@@
+     * Converts a name to a properly formatted subfolder path for cache storage.
+     * Handles normalization and path formatting to create consistent cache directory structures.
      *
      * @private for `FileCacheStorage`
      */
@@ -5399,11 +5418,11 @@
     }
 
     /**
-     * @@@
+     * Converts a title string into a normalized name.
      *
-     * @param value @@@
-     * @returns @@@
-     * @example @@@
+     * @param value The title string to be converted to a name.
+     * @returns A normalized name derived from the input title.
+     * @example 'Hello World!' -> 'hello-world'
      * @public exported from `@promptbook/utils`
      */
     function titleToName(value) {
@@ -5454,7 +5473,9 @@
      */
 
     /**
-     * @@@
+     * Factory function that creates a handler for processing knowledge sources.
+     * Provides standardized processing of different types of knowledge sources
+     * across various scraper implementations.
      *
      * @public exported from `@promptbook/core`
      */
@@ -5695,9 +5716,12 @@
      */
 
     /**
-     * @@@
+     * 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;
@@ -6603,11 +6627,11 @@
     };
 
     /**
-     * @@@
+     * Normalizes a given text to camelCase format.
      *
-     * @param text @@@
-     * @param _isFirstLetterCapital @@@
-     * @returns @@@
+     * @param text The text to be normalized.
+     * @param _isFirstLetterCapital Whether the first letter should be capitalized.
+     * @returns The camelCase formatted string.
      * @example 'helloWorld'
      * @example 'iLovePromptbook'
      * @public exported from `@promptbook/utils`
@@ -7095,7 +7119,7 @@
     };
 
     /**
-     * @@@
+     * Pipeline interface which is equivalent to `any`
      *
      * @see https://github.com/webgptorg/promptbook/discussions/171
      *
@@ -7176,14 +7200,15 @@
     };
 
     /**
-     * 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: [
@@ -7259,7 +7284,7 @@
     /**
      * Parses the formfactor command
      *
-     * Note: @@@ This command is used as formfactor for new commands - it should NOT be used in any `.book` file
+     * Note: This command is used as a formfactor for new commands and defines the app type format - it should NOT be used in any `.book` file
      *
      * @see `documentationUrl` for more details
      * @public exported from `@promptbook/editable`
@@ -7281,7 +7306,7 @@
         /**
          * Description of the FORMFACTOR command
          */
-        description: `@@`,
+        description: `Specifies the application type and interface requirements that this promptbook should conform to`,
         /**
          * Link to documentation
          */
@@ -7424,8 +7449,7 @@
     };
 
     /**
-     * @@@
-     *
+     * @see {@link ModelVariant}
      * @public exported from `@promptbook/core`
      */
     const MODEL_VARIANTS = ['COMPLETION', 'CHAT', 'EMBEDDING' /* <- TODO [🏳] */ /* <- [🤖] */];
@@ -8398,7 +8422,7 @@
     }
 
     /**
-     * @@@
+     * Extracts the interface (input and output parameters) from a pipeline.
      *
      * @deprecated https://github.com/webgptorg/promptbook/pull/186
      * @see https://github.com/webgptorg/promptbook/discussions/171
@@ -8431,7 +8455,7 @@
     }
 
     /**
-     * @@@
+     * Checks if two pipeline interfaces are structurally identical.
      *
      * @deprecated https://github.com/webgptorg/promptbook/pull/186
      * @see https://github.com/webgptorg/promptbook/discussions/171
@@ -8463,10 +8487,11 @@
     }
 
     /**
-     * @@@
+     * Checks if a given pipeline satisfies the requirements of a specified pipeline interface.
      *
      * @deprecated https://github.com/webgptorg/promptbook/pull/186
      * @see https://github.com/webgptorg/promptbook/discussions/171
+     * @returns `true` if the pipeline implements the interface, `false` otherwise.
      *
      * @public exported from `@promptbook/core`
      */
@@ -8652,7 +8677,8 @@
     }
 
     /**
-     * @@@
+     * Utility to determine if a pipeline string is in flat format.
+     * A flat pipeline is a simple text without proper structure (headers, blocks, etc).
      *
      * @public exported from `@promptbook/editable`
      */
@@ -8673,7 +8699,10 @@
     }
 
     /**
-     * @@@
+     * Converts a pipeline structure to its string representation.
+     *
+     * Transforms a flat, simple pipeline into a properly formatted pipeline string
+     * with sections for title, prompt, and return statement.
      *
      * @public exported from `@promptbook/editable`
      */
@@ -8730,7 +8759,7 @@
      * Note: It can not work with html syntax and comments
      *
      * @param markdown any valid markdown
-     * @returns @@@
+     * @returns An array of strings, each representing an individual list item found in the markdown
      * @public exported from `@promptbook/markdown-utils`
      */
     function extractAllListItemsFromMarkdown(markdown) {
@@ -9585,7 +9614,8 @@
      */
 
     /**
-     * @@@
+     * Provides filesystem access (for example for Node.js-based scrapers)
+     * Creates a standardized filesystem interface that scrapers can use for file operations.
      *
      * @public exported from `@promptbook/node`
      */
@@ -9790,10 +9820,10 @@
      */
 
     /**
-     * @@@
+     * Register for LLM tools metadata.
      *
      * Note: `$` is used to indicate that this interacts with the global scope
-     * @singleton Only one instance of each register is created per build, but thare can be more @@@
+     * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
      * @public exported from `@promptbook/core`
      */
     const $llmToolsMetadataRegister = new $Register('llm_tools_metadata');
@@ -9821,10 +9851,10 @@
      */
 
     /**
-     * @@@
+     * Register for LLM tools.
      *
      * Note: `$` is used to indicate that this interacts with the global scope
-     * @singleton Only one instance of each register is created per build, but thare can be more @@@
+     * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
      * @public exported from `@promptbook/core`
      */
     const $llmToolsRegister = new $Register('llm_execution_tools_constructors');
@@ -10017,9 +10047,8 @@
      */
 
     /**
-     * @@@
+     * Provides LLM tools configuration by reading environment variables.
      *
-     * @@@ .env
      * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file
      *
      * It looks for environment variables:
@@ -10027,7 +10056,8 @@
      * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
      * - ...
      *
-     * @returns @@@
+     * @see Environment variables documentation or .env file for required variables.
+     * @returns A promise that resolves to the LLM tools configuration, or null if configuration is incomplete or missing.
      * @public exported from `@promptbook/node`
      */
     async function $provideLlmToolsConfigurationFromEnv() {
@@ -10148,11 +10178,9 @@
      */
 
     /**
-     * @@@
-     *
-     * 1) @@@
-     * 2) @@@
-     *
+     * Provides a collection of scrapers optimized for Node.js environment.
+     * 1) `provideScrapersForNode` use as default
+     * 2) `provideScrapersForBrowser` use in limited browser environment *
      * @public exported from `@promptbook/node`
      */
     async function $provideScrapersForNode(tools, options) {
@@ -10259,11 +10287,11 @@
     }
 
     /**
-     * @@@
+     * Converts a name string into a URI-compatible format.
      *
-     * @param name @@@
-     * @returns @@@
-     * @example @@@
+     * @param name The string to be converted to a URI-compatible format.
+     * @returns A URI-compatible string derived from the input name.
+     * @example 'Hello World' -> 'hello-world'
      * @public exported from `@promptbook/utils`
      */
     function nameToUriPart(name) {
@@ -10277,11 +10305,11 @@
     }
 
     /**
-     * @@@
+     * Converts a given name into URI-compatible parts.
      *
-     * @param name @@@
-     * @returns @@@
-     * @example @@@
+     * @param name The name to be converted into URI parts.
+     * @returns An array of URI-compatible parts derived from the name.
+     * @example 'Example Name' -> ['example', 'name']
      * @public exported from `@promptbook/utils`
      */
     function nameToUriParts(name) {
@@ -11088,7 +11116,10 @@
      */
 
     /**
-     * @@@
+     * A storage implementation that caches data in files organized in a directory structure.
+     * Provides methods for retrieving, storing, and managing cached data on the filesystem.
+     *
+     * This class implements the PromptbookStorage interface for filesystem-based caching.
      *
      * @public exported from `@promptbook/node`
      */
@@ -11101,7 +11132,8 @@
             }
         }
         /**
-         * @@@
+         * Converts a storage key to a filesystem path where the data should be stored.
+         * Creates a consistent, deterministic file path based on the key string.
          */
         getFilenameForKey(key) {
             // TODO: [👬] DRY
@@ -11113,7 +11145,8 @@
             ...nameToSubfolderPath(hash /* <- TODO: [🎎] Maybe add some SHA256 prefix */), `${name.substring(0, MAX_FILENAME_LENGTH)}.json`);
         }
         /**
-         * @@@ Returns the current value associated with the given key, or null if the given key does not exist in the list associated with the object.
+         * Returns the current value associated with the given key, or null if the given key does not exist.
+         * Retrieves the cached data from the file system storage.
          */
         async getItem(key) {
             const filename = this.getFilenameForKey(key);
@@ -11126,7 +11159,8 @@
             return value;
         }
         /**
-         * @@@ Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+         * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+         * Persists data to the file system, creating necessary directory structure if it doesn't exist.
          */
         async setItem(key, value) {
             const filename = this.getFilenameForKey(key);
@@ -11138,7 +11172,8 @@
             await promises.writeFile(filename, fileContent, 'utf-8');
         }
         /**
-         * @@@ Removes the key/value pair with the given key from the list associated with the object, if a key/value pair with the given key exists.
+         * Removes the key/value pair with the given key from the storage, if a key/value pair with the given key exists.
+         * Deletes the corresponding file from the filesystem.
          */
         async removeItem(key) {
             const filename = this.getFilenameForKey(key);