@promptbook/node 0.95.0 → 0.98.0-10

package/README.md

@@ -25,6 +25,10 @@ Write AI applications using plain human language across multiple models and plat
 
 
 
+<blockquote style="color: #ff8811">
+    <b>⚠ Warning:</b> This is a pre-release version of the library. It is not yet ready for production use. Please look at <a href="https://www.npmjs.com/package/@promptbook/core?activeTab=versions">latest stable release</a>.
+</blockquote>
+
 ## 📦 Package `@promptbook/node`
 
 - Promptbooks are [divided into several](#-packages) packages, all are published from [single monorepo](https://github.com/webgptorg/promptbook).
@@ -60,6 +64,8 @@ Rest of the documentation is common for **entire promptbook ecosystem**:
 
 During the computer revolution, we have seen [multiple generations of computer languages](https://github.com/webgptorg/promptbook/discussions/180), from the physical rewiring of the vacuum tubes through low-level machine code to the high-level languages like Python or JavaScript. And now, we're on the edge of the **next revolution**!
 
+
+
 It's a revolution of writing software in **plain human language** that is understandable and executable by both humans and machines – and it's going to change everything!
 
 The incredible growth in power of microprocessors and the Moore's Law have been the driving force behind the ever-more powerful languages, and it's been an amazing journey! Similarly, the large language models (like GPT or Claude) are the next big thing in language technology, and they're set to transform the way we interact with computers.
@@ -185,6 +191,8 @@ Join our growing community of developers and users:
 
 _A concise, Markdown-based DSL for crafting AI workflows and automations._
 
+
+
 ### Introduction
 
 Book is a Markdown-based language that simplifies the creation of AI applications, workflows, and automations. With human-readable commands, you can define inputs, outputs, personas, knowledge sources, and actions—without needing model-specific details.
@@ -234,6 +242,8 @@ Personas can have access to different knowledge, tools and actions. They can als
 
 -   [PERSONA](https://github.com/webgptorg/promptbook/blob/main/documents/commands/PERSONA.md)
 
+
+
 ### **3. How:** Knowledge, Instruments and Actions
 
 The resources used by the personas are used to do the work.
@@ -333,6 +343,8 @@ The following glossary is used to clarify certain concepts:
 
 _Note: This section is not a complete dictionary, more list of general AI / LLM terms that has connection with Promptbook_
 
+
+
 ### 💯 Core concepts
 
 -   [📚 Collection of pipelines](https://github.com/webgptorg/promptbook/discussions/65)

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.95.0';
+const PROMPTBOOK_ENGINE_VERSION = '0.98.0-10';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -174,7 +174,7 @@ const DEFAULT_MAX_PARALLEL_COUNT = 5; // <- TODO: [🤹‍♂️]
  *
  * @public exported from `@promptbook/core`
  */
-const DEFAULT_MAX_EXECUTION_ATTEMPTS = 10; // <- TODO: [🤹‍♂️]
+const DEFAULT_MAX_EXECUTION_ATTEMPTS = 7; // <- TODO: [🤹‍♂️]
 // <- TODO: [🕝] Make also `BOOKS_DIRNAME_ALTERNATIVES`
 // TODO: Just `.promptbook` in config, hardcode subfolders like `download-cache` or `execution-cache`
 /**
@@ -344,7 +344,7 @@ function jsonParse(value) {
         throw new Error(spaceTrim((block) => `
                     ${block(error.message)}
 
-                    The JSON text:
+                    The expected JSON text:
                     ${block(value)}
                 `));
     }
@@ -3105,108 +3105,6 @@ function joinLlmExecutionTools(...llmExecutionTools) {
  * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
  */
 
-/**
- * Extracts all code blocks from markdown.
- *
- * Note: There are multiple similar functions:
- * - `extractBlock` just extracts the content of the code block which is also used as built-in function for postprocessing
- * - `extractJsonBlock` extracts exactly one valid JSON code block
- * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
- * - `extractAllBlocksFromMarkdown` extracts all code blocks with language of the code block
- *
- * @param markdown any valid markdown
- * @returns code blocks with language and content
- * @throws {ParseError} if block is not closed properly
- * @public exported from `@promptbook/markdown-utils`
- */
-function extractAllBlocksFromMarkdown(markdown) {
-    const codeBlocks = [];
-    const lines = markdown.split('\n');
-    // Note: [0] Ensure that the last block notated by gt > will be closed
-    lines.push('');
-    let currentCodeBlock = null;
-    for (const line of lines) {
-        if (line.startsWith('> ') || line === '>') {
-            if (currentCodeBlock === null) {
-                currentCodeBlock = { blockNotation: '>', language: null, content: '' };
-            } /* not else */
-            if (currentCodeBlock.blockNotation === '>') {
-                if (currentCodeBlock.content !== '') {
-                    currentCodeBlock.content += '\n';
-                }
-                currentCodeBlock.content += line.slice(2);
-            }
-        }
-        else if (currentCodeBlock !== null && currentCodeBlock.blockNotation === '>' /* <- Note: [0] */) {
-            codeBlocks.push(currentCodeBlock);
-            currentCodeBlock = null;
-        }
-        /* not else */
-        if (line.startsWith('```')) {
-            const language = line.slice(3).trim() || null;
-            if (currentCodeBlock === null) {
-                currentCodeBlock = { blockNotation: '```', language, content: '' };
-            }
-            else {
-                if (language !== null) {
-                    throw new ParseError(`${capitalize(currentCodeBlock.language || 'the')} code block was not closed and already opening new ${language} code block`);
-                }
-                codeBlocks.push(currentCodeBlock);
-                currentCodeBlock = null;
-            }
-        }
-        else if (currentCodeBlock !== null && currentCodeBlock.blockNotation === '```') {
-            if (currentCodeBlock.content !== '') {
-                currentCodeBlock.content += '\n';
-            }
-            currentCodeBlock.content += line.split('\\`\\`\\`').join('```') /* <- TODO: Maybe make proper unescape */;
-        }
-    }
-    if (currentCodeBlock !== null) {
-        throw new ParseError(`${capitalize(currentCodeBlock.language || 'the')} code block was not closed at the end of the markdown`);
-    }
-    return codeBlocks;
-}
-/**
- * TODO: Maybe name for `blockNotation` instead of  '```' and '>'
- */
-
-/**
- * Extracts  extracts exactly one valid JSON code block
- *
- * - When given string is a valid JSON as it is, it just returns it
- * - When there is no JSON code block the function throws a `ParseError`
- * - When there are multiple JSON code blocks the function throws a `ParseError`
- *
- * Note: It is not important if marked as ```json BUT if it is VALID JSON
- * Note: There are multiple similar function:
- * - `extractBlock` just extracts the content of the code block which is also used as build-in function for postprocessing
- * - `extractJsonBlock` extracts exactly one valid JSON code block
- * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
- * - `extractAllBlocksFromMarkdown` extracts all code blocks with language of the code block
- *
- * @public exported from `@promptbook/markdown-utils`
- * @throws {ParseError} if there is no valid JSON block in the markdown
- */
-function extractJsonBlock(markdown) {
-    if (isValidJsonString(markdown)) {
-        return markdown;
-    }
-    const codeBlocks = extractAllBlocksFromMarkdown(markdown);
-    const jsonBlocks = codeBlocks.filter(({ content }) => isValidJsonString(content));
-    if (jsonBlocks.length === 0) {
-        throw new Error('There is no valid JSON block in the markdown');
-    }
-    if (jsonBlocks.length > 1) {
-        throw new Error('There are multiple JSON code blocks in the markdown');
-    }
-    return jsonBlocks[0].content;
-}
-/**
- * TODO: Add some auto-healing logic + extract YAML, JSON5, TOML, etc.
- * TODO: [🏢] Make this logic part of `JsonFormatParser` or `isValidJsonString`
- */
-
 /**
  * Takes an item or an array of items and returns an array of items
  *
@@ -3314,6 +3212,108 @@ function templateParameters(template, parameters) {
     return replacedTemplates;
 }
 
+/**
+ * Extracts all code blocks from markdown.
+ *
+ * Note: There are multiple similar functions:
+ * - `extractBlock` just extracts the content of the code block which is also used as built-in function for postprocessing
+ * - `extractJsonBlock` extracts exactly one valid JSON code block
+ * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
+ * - `extractAllBlocksFromMarkdown` extracts all code blocks with language of the code block
+ *
+ * @param markdown any valid markdown
+ * @returns code blocks with language and content
+ * @throws {ParseError} if block is not closed properly
+ * @public exported from `@promptbook/markdown-utils`
+ */
+function extractAllBlocksFromMarkdown(markdown) {
+    const codeBlocks = [];
+    const lines = markdown.split('\n');
+    // Note: [0] Ensure that the last block notated by gt > will be closed
+    lines.push('');
+    let currentCodeBlock = null;
+    for (const line of lines) {
+        if (line.startsWith('> ') || line === '>') {
+            if (currentCodeBlock === null) {
+                currentCodeBlock = { blockNotation: '>', language: null, content: '' };
+            } /* not else */
+            if (currentCodeBlock.blockNotation === '>') {
+                if (currentCodeBlock.content !== '') {
+                    currentCodeBlock.content += '\n';
+                }
+                currentCodeBlock.content += line.slice(2);
+            }
+        }
+        else if (currentCodeBlock !== null && currentCodeBlock.blockNotation === '>' /* <- Note: [0] */) {
+            codeBlocks.push(currentCodeBlock);
+            currentCodeBlock = null;
+        }
+        /* not else */
+        if (line.startsWith('```')) {
+            const language = line.slice(3).trim() || null;
+            if (currentCodeBlock === null) {
+                currentCodeBlock = { blockNotation: '```', language, content: '' };
+            }
+            else {
+                if (language !== null) {
+                    throw new ParseError(`${capitalize(currentCodeBlock.language || 'the')} code block was not closed and already opening new ${language} code block`);
+                }
+                codeBlocks.push(currentCodeBlock);
+                currentCodeBlock = null;
+            }
+        }
+        else if (currentCodeBlock !== null && currentCodeBlock.blockNotation === '```') {
+            if (currentCodeBlock.content !== '') {
+                currentCodeBlock.content += '\n';
+            }
+            currentCodeBlock.content += line.split('\\`\\`\\`').join('```') /* <- TODO: Maybe make proper unescape */;
+        }
+    }
+    if (currentCodeBlock !== null) {
+        throw new ParseError(`${capitalize(currentCodeBlock.language || 'the')} code block was not closed at the end of the markdown`);
+    }
+    return codeBlocks;
+}
+/**
+ * TODO: Maybe name for `blockNotation` instead of  '```' and '>'
+ */
+
+/**
+ * Extracts  extracts exactly one valid JSON code block
+ *
+ * - When given string is a valid JSON as it is, it just returns it
+ * - When there is no JSON code block the function throws a `ParseError`
+ * - When there are multiple JSON code blocks the function throws a `ParseError`
+ *
+ * Note: It is not important if marked as ```json BUT if it is VALID JSON
+ * Note: There are multiple similar function:
+ * - `extractBlock` just extracts the content of the code block which is also used as build-in function for postprocessing
+ * - `extractJsonBlock` extracts exactly one valid JSON code block
+ * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
+ * - `extractAllBlocksFromMarkdown` extracts all code blocks with language of the code block
+ *
+ * @public exported from `@promptbook/markdown-utils`
+ * @throws {ParseError} if there is no valid JSON block in the markdown
+ */
+function extractJsonBlock(markdown) {
+    if (isValidJsonString(markdown)) {
+        return markdown;
+    }
+    const codeBlocks = extractAllBlocksFromMarkdown(markdown);
+    const jsonBlocks = codeBlocks.filter(({ content }) => isValidJsonString(content));
+    if (jsonBlocks.length === 0) {
+        throw new Error('There is no valid JSON block in the markdown');
+    }
+    if (jsonBlocks.length > 1) {
+        throw new Error('There are multiple JSON code blocks in the markdown');
+    }
+    return jsonBlocks[0].content;
+}
+/**
+ * TODO: Add some auto-healing logic + extract YAML, JSON5, TOML, etc.
+ * TODO: [🏢] Make this logic part of `JsonFormatParser` or `isValidJsonString`
+ */
+
 /**
  * Counts number of characters in the text
  *
@@ -3735,6 +3735,68 @@ function checkExpectations(expectations, value) {
  * Note: [💝] and [🤠] are interconnected together
  */
 
+/**
+ * Validates a prompt result against expectations and format requirements.
+ * This function provides a common abstraction for result validation that can be used
+ * by both execution logic and caching logic to ensure consistency.
+ *
+ * @param options - The validation options including result string, expectations, and format
+ * @returns Validation result with processed string and validity status
+ * @private internal function of `createPipelineExecutor` and `cacheLlmTools`
+ */
+function validatePromptResult(options) {
+    const { resultString, expectations, format } = options;
+    let processedResultString = resultString;
+    let validationError;
+    try {
+        // TODO: [💝] Unite object for expecting amount and format
+        if (format) {
+            if (format === 'JSON') {
+                if (!isValidJsonString(processedResultString)) {
+                    // TODO: [🏢] Do more universally via `FormatParser`
+                    try {
+                        processedResultString = extractJsonBlock(processedResultString);
+                    }
+                    catch (error) {
+                        keepUnused(error);
+                        throw new ExpectError(spaceTrim$1((block) => `
+                                    Expected valid JSON string
+
+                                    The expected JSON text:
+                                    ${block(processedResultString)}
+                                `));
+                    }
+                }
+            }
+            else {
+                throw new UnexpectedError(`Unknown format "${format}"`);
+            }
+        }
+        // TODO: [💝] Unite object for expecting amount and format
+        if (expectations) {
+            checkExpectations(expectations, processedResultString);
+        }
+        return {
+            isValid: true,
+            processedResultString,
+        };
+    }
+    catch (error) {
+        if (error instanceof ExpectError) {
+            validationError = error;
+        }
+        else {
+            // Re-throw non-ExpectError errors (like UnexpectedError)
+            throw error;
+        }
+        return {
+            isValid: false,
+            processedResultString,
+            error: validationError,
+        };
+    }
+}
+
 /**
  * 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.
@@ -3752,17 +3814,18 @@ async function executeAttempts(options) {
         $resultString: null,
         $expectError: null,
         $scriptPipelineExecutionErrors: [],
+        $failedResults: [], // Track all failed attempts
     };
     // TODO: [🚐] Make arrayable LLMs -> single LLM DRY
     const _llms = arrayableToArray(tools.llm);
     const llmTools = _llms.length === 1 ? _llms[0] : joinLlmExecutionTools(..._llms);
-    attempts: for (let attempt = -jokerParameterNames.length; attempt < maxAttempts; attempt++) {
-        const isJokerAttempt = attempt < 0;
-        const jokerParameterName = jokerParameterNames[jokerParameterNames.length + attempt];
+    attempts: for (let attemptIndex = -jokerParameterNames.length; attemptIndex < maxAttempts; attemptIndex++) {
+        const isJokerAttempt = attemptIndex < 0;
+        const jokerParameterName = jokerParameterNames[jokerParameterNames.length + attemptIndex];
         // TODO: [🧠][🍭] JOKERS, EXPECTATIONS, POSTPROCESSING and FOREACH
         if (isJokerAttempt && !jokerParameterName) {
             throw new UnexpectedError(spaceTrim$1((block) => `
-                        Joker not found in attempt ${attempt}
+                        Joker not found in attempt ${attemptIndex}
 
                         ${block(pipelineIdentification)}
                     `));
@@ -3960,35 +4023,18 @@ async function executeAttempts(options) {
                 }
             }
             // TODO: [💝] Unite object for expecting amount and format
-            if (task.format) {
-                if (task.format === 'JSON') {
-                    if (!isValidJsonString($ongoingTaskResult.$resultString || '')) {
-                        // TODO: [🏢] Do more universally via `FormatParser`
-                        try {
-                            $ongoingTaskResult.$resultString = extractJsonBlock($ongoingTaskResult.$resultString || '');
-                        }
-                        catch (error) {
-                            keepUnused(error);
-                            throw new ExpectError(spaceTrim$1((block) => `
-                                        Expected valid JSON string
-
-                                        ${block(
-                            /*<- Note: No need for `pipelineIdentification`, it will be catched and added later */ '')}
-                                    `));
-                        }
-                    }
-                }
-                else {
-                    throw new UnexpectedError(spaceTrim$1((block) => `
-                                Unknown format "${task.format}"
-
-                                ${block(pipelineIdentification)}
-                            `));
+            // Use the common validation function for both format and expectations
+            if (task.format || task.expectations) {
+                const validationResult = validatePromptResult({
+                    resultString: $ongoingTaskResult.$resultString || '',
+                    expectations: task.expectations,
+                    format: task.format,
+                });
+                if (!validationResult.isValid) {
+                    throw validationResult.error;
                 }
-            }
-            // TODO: [💝] Unite object for expecting amount and format
-            if (task.expectations) {
-                checkExpectations(task.expectations, $ongoingTaskResult.$resultString || '');
+                // Update the result string in case format processing modified it (e.g., JSON extraction)
+                $ongoingTaskResult.$resultString = validationResult.processedResultString;
             }
             break attempts;
         }
@@ -3997,6 +4043,15 @@ async function executeAttempts(options) {
                 throw error;
             }
             $ongoingTaskResult.$expectError = error;
+            // Store each failed attempt
+            if (!Array.isArray($ongoingTaskResult.$failedResults)) {
+                $ongoingTaskResult.$failedResults = [];
+            }
+            $ongoingTaskResult.$failedResults.push({
+                attemptIndex,
+                result: $ongoingTaskResult.$resultString,
+                error: error,
+            });
         }
         finally {
             if (!isJokerAttempt &&
@@ -4018,35 +4073,41 @@ async function executeAttempts(options) {
                 });
             }
         }
-        if ($ongoingTaskResult.$expectError !== null && attempt === maxAttempts - 1) {
+        if ($ongoingTaskResult.$expectError !== null && attemptIndex === maxAttempts - 1) {
+            // Note: Create a summary of all failures
+            const failuresSummary = $ongoingTaskResult.$failedResults
+                .map((failure) => spaceTrim$1((block) => {
+                var _a, _b;
+                return `
+                            Attempt ${failure.attemptIndex + 1}:
+                            Error ${((_a = failure.error) === null || _a === void 0 ? void 0 : _a.name) || ''}:
+                            ${block((_b = failure.error) === null || _b === void 0 ? void 0 : _b.message.split('\n').map((line) => `> ${line}`).join('\n'))}
+
+                            Result:
+                            ${block(failure.result === null
+                    ? 'null'
+                    : spaceTrim$1(failure.result)
+                        .split('\n')
+                        .map((line) => `> ${line}`)
+                        .join('\n'))}
+                        `;
+            }))
+                .join('\n\n---\n\n');
             throw new PipelineExecutionError(spaceTrim$1((block) => {
-                var _a, _b, _c;
+                var _a;
                 return `
                         LLM execution failed ${maxExecutionAttempts}x
 
                         ${block(pipelineIdentification)}
 
-                        ---
                         The Prompt:
                         ${block((((_a = $ongoingTaskResult.$prompt) === null || _a === void 0 ? void 0 : _a.content) || '')
                     .split('\n')
                     .map((line) => `> ${line}`)
                     .join('\n'))}
 
-                        Last error ${((_b = $ongoingTaskResult.$expectError) === null || _b === void 0 ? void 0 : _b.name) || ''}:
-                        ${block((((_c = $ongoingTaskResult.$expectError) === null || _c === void 0 ? void 0 : _c.message) || '')
-                    .split('\n')
-                    .map((line) => `> ${line}`)
-                    .join('\n'))}
-
-                        Last result:
-                        ${block($ongoingTaskResult.$resultString === null
-                    ? 'null'
-                    : spaceTrim$1($ongoingTaskResult.$resultString)
-                        .split('\n')
-                        .map((line) => `> ${line}`)
-                        .join('\n'))}
-                        ---
+                        All Failed Attempts:
+                        ${block(failuresSummary)}
                     `;
             }));
         }
@@ -10117,6 +10178,46 @@ async function $provideLlmToolsConfigurationFromEnv() {
  * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
  */
 
+/**
+ * Detects if the code is running in a browser environment in main thread (Not in a web worker)
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it looks at the global object to determine the environment
+ *
+ * @public exported from `@promptbook/utils`
+ */
+const $isRunningInBrowser = new Function(`
+    try {
+        return this === window;
+    } catch (e) {
+        return false;
+    }
+`);
+/**
+ * TODO: [🎺]
+ */
+
+/**
+ * Detects if the code is running in a web worker
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it looks at the global object to determine the environment
+ *
+ * @public exported from `@promptbook/utils`
+ */
+const $isRunningInWebWorker = new Function(`
+    try {
+        if (typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope) {
+            return true;
+        } else {
+            return false;
+        }
+    } catch (e) {
+        return false;
+    }
+`);
+/**
+ * TODO: [🎺]
+ */
+
 /**
  * Creates LLM execution tools from provided configuration objects
  *
@@ -10137,8 +10238,10 @@ function createLlmToolsFromConfiguration(configuration, options = {}) {
             .list()
             .find(({ packageName, className }) => llmConfiguration.packageName === packageName && llmConfiguration.className === className);
         if (registeredItem === undefined) {
+            console.log('!!! $llmToolsRegister.list()', $llmToolsRegister.list());
             throw new Error(spaceTrim((block) => `
                         There is no constructor for LLM provider \`${llmConfiguration.className}\` from \`${llmConfiguration.packageName}\`
+                        Running in ${!$isRunningInBrowser() ? '' : 'browser environment'}${!$isRunningInNode() ? '' : 'node environment'}${!$isRunningInWebWorker() ? '' : 'worker environment'}
 
                         You have probably forgotten install and import the provider package.
                         To fix this issue, you can:
@@ -10265,24 +10368,6 @@ async function $provideScrapersForNode(tools, options) {
  * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
  */
 
-/**
- * Detects if the code is running in a browser environment in main thread (Not in a web worker)
- *
- * Note: `$` is used to indicate that this function is not a pure function - it looks at the global object to determine the environment
- *
- * @public exported from `@promptbook/utils`
- */
-new Function(`
-    try {
-        return this === window;
-    } catch (e) {
-        return false;
-    }
-`);
-/**
- * TODO: [🎺]
- */
-
 /**
  * Detects if the code is running in jest environment
  *
@@ -10301,28 +10386,6 @@ new Function(`
  * TODO: [🎺]
  */
 
-/**
- * Detects if the code is running in a web worker
- *
- * Note: `$` is used to indicate that this function is not a pure function - it looks at the global object to determine the environment
- *
- * @public exported from `@promptbook/utils`
- */
-new Function(`
-    try {
-        if (typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope) {
-            return true;
-        } else {
-            return false;
-        }
-    } catch (e) {
-        return false;
-    }
-`);
-/**
- * TODO: [🎺]
- */
-
 /**
  * Makes first letter of a string uppercase
  *