@promptbook/node 0.92.0-23 → 0.92.0-25

package/esm/index.es.js

@@ -30,7 +30,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @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
@@ -102,11 +102,20 @@ const DEFAULT_BOOK_OUTPUT_PARAMETER_NAME = 'result';
  */
 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
@@ -657,13 +666,13 @@ const ORDER_OF_PIPELINE_JSON = [
  */
 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
  */
@@ -1536,7 +1545,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
@@ -1666,8 +1675,8 @@ class MissingToolsError extends Error {
  * @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);
@@ -2626,6 +2635,15 @@ const CsvFormatParser = {
                     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(unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS }));
                     }
                 }
@@ -2842,7 +2860,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;
     }
@@ -2873,7 +2891,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;
 }
@@ -3624,10 +3642,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) {
@@ -4115,15 +4133,14 @@ async function executeFormatSubvalues(options) {
                 const highLevelError = new PipelineExecutionError(spaceTrim((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;
             }
@@ -4147,14 +4164,13 @@ async function executeFormatSubvalues(options) {
             catch (error) {
                 if (length > BIG_DATASET_TRESHOLD) {
                     console.error(spaceTrim((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;
             }
@@ -4993,7 +5009,8 @@ async function preparePersona(personaDescription, tools, options) {
  */
 
 /**
- * @@@
+ * 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
  *
@@ -5004,10 +5021,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`
@@ -5059,10 +5076,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`
@@ -5132,10 +5149,11 @@ const $scrapersMetadataRegister = new $Register('scrapers_metadata');
  */
 
 /**
- * @@@
+ * 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');
@@ -5231,10 +5249,10 @@ function $registeredScrapersMessage(availableScrapers) {
  */
 
 /**
- * @@@
+ * 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`
@@ -5303,7 +5321,8 @@ function knowledgeSourceContentToName(knowledgeSourceContent) {
  */
 
 /**
- * @@@
+ * 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`
  */
@@ -5383,11 +5402,11 @@ function removeEmojis(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) {
@@ -5438,7 +5457,9 @@ const promptbookFetch = async (urlOrRequest, init) => {
  */
 
 /**
- * @@@
+ * 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`
  */
@@ -5679,9 +5700,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;
@@ -6587,11 +6611,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`
@@ -7079,7 +7103,7 @@ const GeneratorFormfactorDefinition = {
 };
 
 /**
- * @@@
+ * Pipeline interface which is equivalent to `any`
  *
  * @see https://github.com/webgptorg/promptbook/discussions/171
  *
@@ -7160,14 +7184,15 @@ const MatcherFormfactorDefinition = {
 };
 
 /**
- * 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: [
@@ -7243,7 +7268,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`
@@ -7265,7 +7290,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
      */
@@ -7408,8 +7433,7 @@ const jokerCommandParser = {
 };
 
 /**
- * @@@
- *
+ * @see {@link ModelVariant}
  * @public exported from `@promptbook/core`
  */
 const MODEL_VARIANTS = ['COMPLETION', 'CHAT', 'EMBEDDING' /* <- TODO [🏳] */ /* <- [🤖] */];
@@ -8382,7 +8406,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
@@ -8415,7 +8439,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
@@ -8447,10 +8471,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`
  */
@@ -8636,7 +8661,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`
  */
@@ -8657,7 +8683,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`
  */
@@ -8714,7 +8743,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) {
@@ -9569,7 +9598,8 @@ async function locateAppOnLinux({ linuxWhich, }) {
  */
 
 /**
- * @@@
+ * 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`
  */
@@ -9774,10 +9804,10 @@ async function $provideExecutablesForNode(options) {
  */
 
 /**
- * @@@
+ * 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');
@@ -9805,10 +9835,10 @@ function isRootPath(value) {
  */
 
 /**
- * @@@
+ * 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');
@@ -10001,9 +10031,8 @@ async function $provideEnvFilename() {
  */
 
 /**
- * @@@
+ * 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:
@@ -10011,7 +10040,8 @@ async function $provideEnvFilename() {
  * - `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() {
@@ -10132,11 +10162,9 @@ async function $provideLlmToolsFromEnv(options = {}) {
  */
 
 /**
- * @@@
- *
- * 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) {
@@ -10243,11 +10271,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) {
@@ -10261,11 +10289,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) {
@@ -11072,7 +11100,10 @@ function stringifyPipelineJson(pipeline) {
  */
 
 /**
- * @@@
+ * 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`
  */
@@ -11085,7 +11116,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
@@ -11097,7 +11129,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);
@@ -11110,7 +11143,8 @@ class FileCacheStorage {
         return value;
     }
     /**
-     * @@@ Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+     * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+     * Persists data to the file system, creating necessary directory structure if it doesn't exist.
      */
     async setItem(key, value) {
         const filename = this.getFilenameForKey(key);
@@ -11122,7 +11156,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);