@promptbook/legacy-documents 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/legacy-documents`
 
 - Promptbooks are [divided into several](#-packages) packages, all are published from [single monorepo](https://github.com/webgptorg/promptbook).
@@ -58,6 +62,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.
@@ -183,6 +189,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.
@@ -232,6 +240,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.
@@ -331,6 +341,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

@@ -28,7 +28,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
@@ -177,7 +177,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`
 /**
@@ -2562,7 +2562,7 @@ function jsonParse(value) {
         throw new Error(spaceTrim$1((block) => `
                     ${block(error.message)}
 
-                    The JSON text:
+                    The expected JSON text:
                     ${block(value)}
                 `));
     }
@@ -4639,6 +4639,77 @@ function mapAvailableToExpectedParameters(options) {
     return mappedParameters;
 }
 
+/**
+ * Replaces parameters in template with values from parameters object
+ *
+ * Note: This function is not places strings into string,
+ *       It's more complex and can handle this operation specifically for LLM models
+ *
+ * @param template the template with parameters in {curly} braces
+ * @param parameters the object with parameters
+ * @returns the template with replaced parameters
+ * @throws {PipelineExecutionError} if parameter is not defined, not closed, or not opened
+ * @public exported from `@promptbook/utils`
+ */
+function templateParameters(template, parameters) {
+    for (const [parameterName, parameterValue] of Object.entries(parameters)) {
+        if (parameterValue === RESERVED_PARAMETER_MISSING_VALUE) {
+            throw new UnexpectedError(`Parameter \`{${parameterName}}\` has missing value`);
+        }
+        else if (parameterValue === RESERVED_PARAMETER_RESTRICTED) {
+            // TODO: [🍵]
+            throw new UnexpectedError(`Parameter \`{${parameterName}}\` is restricted to use`);
+        }
+    }
+    let replacedTemplates = template;
+    let match;
+    let loopLimit = LOOP_LIMIT;
+    while ((match = /^(?<precol>.*){(?<parameterName>\w+)}(.*)/m /* <- Not global */
+        .exec(replacedTemplates))) {
+        if (loopLimit-- < 0) {
+            throw new LimitReachedError('Loop limit reached during parameters replacement in `templateParameters`');
+        }
+        const precol = match.groups.precol;
+        const parameterName = match.groups.parameterName;
+        if (parameterName === '') {
+            // Note: Skip empty placeholders. It's used to avoid confusion with JSON-like strings
+            continue;
+        }
+        if (parameterName.indexOf('{') !== -1 || parameterName.indexOf('}') !== -1) {
+            throw new PipelineExecutionError('Parameter is already opened or not closed');
+        }
+        if (parameters[parameterName] === undefined) {
+            throw new PipelineExecutionError(`Parameter \`{${parameterName}}\` is not defined`);
+        }
+        let parameterValue = parameters[parameterName];
+        if (parameterValue === undefined) {
+            throw new PipelineExecutionError(`Parameter \`{${parameterName}}\` is not defined`);
+        }
+        parameterValue = valueToString(parameterValue);
+        // Escape curly braces in parameter values to prevent prompt-injection
+        parameterValue = parameterValue.replace(/[{}]/g, '\\$&');
+        if (parameterValue.includes('\n') && /^\s*\W{0,3}\s*$/.test(precol)) {
+            parameterValue = parameterValue
+                .split('\n')
+                .map((line, index) => (index === 0 ? line : `${precol}${line}`))
+                .join('\n');
+        }
+        replacedTemplates =
+            replacedTemplates.substring(0, match.index + precol.length) +
+                parameterValue +
+                replacedTemplates.substring(match.index + precol.length + parameterName.length + 2);
+    }
+    // [💫] Check if there are parameters that are not closed properly
+    if (/{\w+$/.test(replacedTemplates)) {
+        throw new PipelineExecutionError('Parameter is not closed');
+    }
+    // [💫] Check if there are parameters that are not opened properly
+    if (/^\w+}/.test(replacedTemplates)) {
+        throw new PipelineExecutionError('Parameter is not opened');
+    }
+    return replacedTemplates;
+}
+
 /**
  * Extracts all code blocks from markdown.
  *
@@ -4741,77 +4812,6 @@ function extractJsonBlock(markdown) {
  * TODO: [🏢] Make this logic part of `JsonFormatParser` or `isValidJsonString`
  */
 
-/**
- * Replaces parameters in template with values from parameters object
- *
- * Note: This function is not places strings into string,
- *       It's more complex and can handle this operation specifically for LLM models
- *
- * @param template the template with parameters in {curly} braces
- * @param parameters the object with parameters
- * @returns the template with replaced parameters
- * @throws {PipelineExecutionError} if parameter is not defined, not closed, or not opened
- * @public exported from `@promptbook/utils`
- */
-function templateParameters(template, parameters) {
-    for (const [parameterName, parameterValue] of Object.entries(parameters)) {
-        if (parameterValue === RESERVED_PARAMETER_MISSING_VALUE) {
-            throw new UnexpectedError(`Parameter \`{${parameterName}}\` has missing value`);
-        }
-        else if (parameterValue === RESERVED_PARAMETER_RESTRICTED) {
-            // TODO: [🍵]
-            throw new UnexpectedError(`Parameter \`{${parameterName}}\` is restricted to use`);
-        }
-    }
-    let replacedTemplates = template;
-    let match;
-    let loopLimit = LOOP_LIMIT;
-    while ((match = /^(?<precol>.*){(?<parameterName>\w+)}(.*)/m /* <- Not global */
-        .exec(replacedTemplates))) {
-        if (loopLimit-- < 0) {
-            throw new LimitReachedError('Loop limit reached during parameters replacement in `templateParameters`');
-        }
-        const precol = match.groups.precol;
-        const parameterName = match.groups.parameterName;
-        if (parameterName === '') {
-            // Note: Skip empty placeholders. It's used to avoid confusion with JSON-like strings
-            continue;
-        }
-        if (parameterName.indexOf('{') !== -1 || parameterName.indexOf('}') !== -1) {
-            throw new PipelineExecutionError('Parameter is already opened or not closed');
-        }
-        if (parameters[parameterName] === undefined) {
-            throw new PipelineExecutionError(`Parameter \`{${parameterName}}\` is not defined`);
-        }
-        let parameterValue = parameters[parameterName];
-        if (parameterValue === undefined) {
-            throw new PipelineExecutionError(`Parameter \`{${parameterName}}\` is not defined`);
-        }
-        parameterValue = valueToString(parameterValue);
-        // Escape curly braces in parameter values to prevent prompt-injection
-        parameterValue = parameterValue.replace(/[{}]/g, '\\$&');
-        if (parameterValue.includes('\n') && /^\s*\W{0,3}\s*$/.test(precol)) {
-            parameterValue = parameterValue
-                .split('\n')
-                .map((line, index) => (index === 0 ? line : `${precol}${line}`))
-                .join('\n');
-        }
-        replacedTemplates =
-            replacedTemplates.substring(0, match.index + precol.length) +
-                parameterValue +
-                replacedTemplates.substring(match.index + precol.length + parameterName.length + 2);
-    }
-    // [💫] Check if there are parameters that are not closed properly
-    if (/{\w+$/.test(replacedTemplates)) {
-        throw new PipelineExecutionError('Parameter is not closed');
-    }
-    // [💫] Check if there are parameters that are not opened properly
-    if (/^\w+}/.test(replacedTemplates)) {
-        throw new PipelineExecutionError('Parameter is not opened');
-    }
-    return replacedTemplates;
-}
-
 /**
  * Counts number of characters in the text
  *
@@ -4972,6 +4972,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((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.
@@ -4989,17 +5051,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((block) => `
-                        Joker not found in attempt ${attempt}
+                        Joker not found in attempt ${attemptIndex}
 
                         ${block(pipelineIdentification)}
                     `));
@@ -5197,35 +5260,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((block) => `
-                                        Expected valid JSON string
-
-                                        ${block(
-                            /*<- Note: No need for `pipelineIdentification`, it will be catched and added later */ '')}
-                                    `));
-                        }
-                    }
-                }
-                else {
-                    throw new UnexpectedError(spaceTrim((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;
         }
@@ -5234,6 +5280,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 &&
@@ -5255,35 +5310,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((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(failure.result)
+                        .split('\n')
+                        .map((line) => `> ${line}`)
+                        .join('\n'))}
+                        `;
+            }))
+                .join('\n\n---\n\n');
             throw new PipelineExecutionError(spaceTrim((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($ongoingTaskResult.$resultString)
-                        .split('\n')
-                        .map((line) => `> ${line}`)
-                        .join('\n'))}
-                        ---
+                        All Failed Attempts:
+                        ${block(failuresSummary)}
                     `;
             }));
         }