@promptbook/remote-client 0.103.0-1 → 0.103.0-100

package/esm/index.es.js

@@ -1,4 +1,4 @@
-import spaceTrim$1, { spaceTrim } from 'spacetrim';
+import spaceTrim$2, { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import { randomBytes } from 'crypto';
 import { io } from 'socket.io-client';
 import { SHA256 } from 'crypto-js';
@@ -13,14 +13,14 @@ import { basename } from 'path';
  * @generated
  * @see https://github.com/webgptorg/book
  */
-const BOOK_LANGUAGE_VERSION = '1.0.0';
+const BOOK_LANGUAGE_VERSION = '2.0.0';
 /**
  * The version of the Promptbook engine
  *
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.103.0-1';
+const PROMPTBOOK_ENGINE_VERSION = '0.103.0-100';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -82,6 +82,22 @@ class CollectionError extends Error {
     }
 }
 
+/**
+ * This error indicates error from the database
+ *
+ * @public exported from `@promptbook/core`
+ */
+class DatabaseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DatabaseError';
+        Object.setPrototypeOf(this, DatabaseError.prototype);
+    }
+}
+/**
+ * TODO: [🐱‍🚀] Explain that NotFoundError ([🐱‍🚀] and other specific errors) has priority over DatabaseError in some contexts
+ */
+
 /**
  * This error type indicates that you try to use a feature that is not available in the current environment
  *
@@ -144,7 +160,7 @@ class LimitReachedError extends Error {
  */
 class MissingToolsError extends Error {
     constructor(message) {
-        super(spaceTrim((block) => `
+        super(spaceTrim$1((block) => `
                     ${block(message)}
 
                     Note: You have probably forgot to provide some tools for pipeline execution or preparation
@@ -155,6 +171,19 @@ class MissingToolsError extends Error {
     }
 }
 
+/**
+ * This error indicates that promptbook operation is not allowed
+ *
+ * @public exported from `@promptbook/core`
+ */
+class NotAllowed extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NotAllowed';
+        Object.setPrototypeOf(this, NotAllowed.prototype);
+    }
+}
+
 /**
  * This error indicates that promptbook not found in the collection
  *
@@ -175,7 +204,7 @@ class NotFoundError extends Error {
  */
 class NotYetImplementedError extends Error {
     constructor(message) {
-        super(spaceTrim((block) => `
+        super(spaceTrim$1((block) => `
                     ${block(message)}
 
                     Note: This feature is not implemented yet but it will be soon.
@@ -210,6 +239,7 @@ class ParseError extends Error {
 /**
  * Generates random token
  *
+ * Note: `$` is used to indicate that this function is not a pure function - it is not deterministic
  * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
  *
  * @private internal helper function
@@ -219,6 +249,7 @@ function $randomToken(randomness) {
     return randomBytes(randomness).toString('hex');
 }
 /**
+ * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
  * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
  */
 
@@ -280,6 +311,17 @@ class PromptbookFetchError extends Error {
     }
 }
 
+/**
+ * Trims string from all 4 sides
+ *
+ * Note: This is a re-exported function from the `spacetrim` package which is
+ *       Developed by same author @hejny as this package
+ *
+ * @public exported from `@promptbook/utils`
+ * @see https://github.com/hejny/spacetrim#usage
+ */
+const spaceTrim = spaceTrim$1;
+
 /**
  * @private util of `@promptbook/color`
  * @de
@@ -328,6 +370,7 @@ function take(initialValue) {
  * @public exported from `@promptbook/color`
  */
 const CSS_COLORS = {
+    promptbook: '#79EAFD',
     transparent: 'rgba(0,0,0,0)',
     aliceblue: '#f0f8ff',
     antiquewhite: '#faebd7',
@@ -509,9 +552,6 @@ function checkChannelValue(channelName, value) {
         throw new Error(`${channelName} channel is greater than 255, it is ${value}`);
     }
 }
-/**
- * TODO: [🧠][🚓] Is/which combination it better to use asserts/check, validate or is utility function?
- */
 
 /**
  * Color object represents an RGB color with alpha channel
@@ -546,6 +586,28 @@ class Color {
             throw new Error(`Can not create color from given object`);
         }
     }
+    /**
+     * Creates a new Color instance from miscellaneous formats
+     * It just does not throw error when it fails, it returns PROMPTBOOK_COLOR instead
+     *
+     * @param color
+     * @returns Color object
+     */
+    static fromSafe(color) {
+        try {
+            return Color.from(color);
+        }
+        catch (error) {
+            // <- Note: Can not use `assertsError(error)` here because it causes circular dependency
+            console.warn(spaceTrim((block) => `
+                        Color.fromSafe error:
+                        ${block(error.message)}
+
+                        Returning default PROMPTBOOK_COLOR.
+                    `));
+            return Color.fromString('promptbook');
+        }
+    }
     /**
      * Creates a new Color instance from miscellaneous string formats
      *
@@ -613,6 +675,9 @@ class Color {
         if (hex.length === 3) {
             return Color.fromHex3(hex);
         }
+        if (hex.length === 4) {
+            return Color.fromHex4(hex);
+        }
         if (hex.length === 6) {
             return Color.fromHex6(hex);
         }
@@ -633,6 +698,19 @@ class Color {
         const b = parseInt(hex.substr(2, 1), 16) * 16;
         return take(new Color(r, g, b));
     }
+    /**
+     * Creates a new Color instance from color in hex format with 4 digits (with alpha channel)
+     *
+     * @param color in hex for example `09df`
+     * @returns Color object
+     */
+    static fromHex4(hex) {
+        const r = parseInt(hex.substr(0, 1), 16) * 16;
+        const g = parseInt(hex.substr(1, 1), 16) * 16;
+        const b = parseInt(hex.substr(2, 1), 16) * 16;
+        const a = parseInt(hex.substr(3, 1), 16) * 16;
+        return take(new Color(r, g, b, a));
+    }
     /**
      * Creates a new Color instance from color in hex format with 6 color digits (without alpha channel)
      *
@@ -823,7 +901,8 @@ class Color {
      * @returns true if the value is a valid hex color string (e.g., `#009edd`, `#fff`, etc.)
      */
     static isHexColorString(value) {
-        return typeof value === 'string' && /^#(?:[0-9a-fA-F]{3}){1,2}$/.test(value);
+        return (typeof value === 'string' &&
+            /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(value));
     }
     /**
      * Creates new Color object
@@ -938,6 +1017,23 @@ class Color {
  * TODO: Maybe connect with textures
  */
 
+/**
+ * Makes color transformer which returns a grayscale version of the color
+ *
+ * @param amount from 0 to 1
+ *
+ * @public exported from `@promptbook/color`
+ */
+function grayscale(amount) {
+    return ({ red, green, blue, alpha }) => {
+        const average = (red + green + blue) / 3;
+        red = Math.round(average * amount + red * (1 - amount));
+        green = Math.round(average * amount + green * (1 - amount));
+        blue = Math.round(average * amount + blue * (1 - amount));
+        return Color.fromValues(red, green, blue, alpha);
+    };
+}
+
 /**
  * Converts HSL values to RGB values
  *
@@ -1053,102 +1149,6 @@ function lighten(amount) {
  * TODO: Maybe implement by mix+hsl
  */
 
-/**
- * Calculates distance between two colors
- *
- * @param color1 first color
- * @param color2 second color
- *
- * Note: This function is inefficient. Use colorDistanceSquared instead if possible.
- *
- * @public exported from `@promptbook/color`
- */
-/**
- * Calculates distance between two colors without square root
- *
- * @param color1 first color
- * @param color2 second color
- *
- * @public exported from `@promptbook/color`
- */
-function colorDistanceSquared(color1, color2) {
-    const rmean = (color1.red + color2.red) / 2;
-    const r = color1.red - color2.red;
-    const g = color1.green - color2.green;
-    const b = color1.blue - color2.blue;
-    const weightR = 2 + rmean / 256;
-    const weightG = 4.0;
-    const weightB = 2 + (255 - rmean) / 256;
-    const distance = weightR * r * r + weightG * g * g + weightB * b * b;
-    return distance;
-}
-
-/**
- * Makes color transformer which finds the nearest color from the given list
- *
- * @param colors array of colors to choose from
- *
- * @public exported from `@promptbook/color`
- */
-function nearest(...colors) {
-    return (color) => {
-        const distances = colors.map((c) => colorDistanceSquared(c, color));
-        const minDistance = Math.min(...distances);
-        const minIndex = distances.indexOf(minDistance);
-        const nearestColor = colors[minIndex];
-        return nearestColor;
-    };
-}
-
-/**
- * Color transformer which returns the negative color
- *
- * @public exported from `@promptbook/color`
- */
-function negative(color) {
-    const r = 255 - color.red;
-    const g = 255 - color.green;
-    const b = 255 - color.blue;
-    return Color.fromValues(r, g, b, color.alpha);
-}
-
-/**
- * Makes color transformer which finds the furthest color from the given list
- *
- * @param colors array of colors to choose from
- *
- * @public exported from `@promptbook/color`
- */
-function furthest(...colors) {
-    return (color) => {
-        const furthestColor = negative(nearest(...colors.map(negative))(color));
-        return furthestColor;
-    };
-}
-/**
- * Makes color transformer which finds the best text color (black or white) for the given background color
- *
- * @public exported from `@promptbook/color`
- */
-furthest(Color.get('white'), Color.from('black'));
-
-/**
- * Makes color transformer which returns a grayscale version of the color
- *
- * @param amount from 0 to 1
- *
- * @public exported from `@promptbook/color`
- */
-function grayscale(amount) {
-    return ({ red, green, blue, alpha }) => {
-        const average = (red + green + blue) / 3;
-        red = Math.round(average * amount + red * (1 - amount));
-        green = Math.round(average * amount + green * (1 - amount));
-        blue = Math.round(average * amount + blue * (1 - amount));
-        return Color.fromValues(red, green, blue, alpha);
-    };
-}
-
 /**
  * Makes color transformer which saturate the given color
  *
@@ -1217,16 +1217,32 @@ const ADMIN_GITHUB_NAME = 'hejny';
  *
  * @public exported from `@promptbook/core`
  */
-const PROMPTBOOK_COLOR = Color.fromHex('#79EAFD');
-// <- TODO: [🧠] Using `Color` here increases the package size approx 3kb, maybe remove it
+const PROMPTBOOK_COLOR = Color.fromString('promptbook');
+// <- TODO: [🧠][🈵] Using `Color` here increases the package size approx 3kb, maybe remove it
+/**
+ * Colors for syntax highlighting in the `<BookEditor/>`
+ *
+ * TODO: [🗽] Unite branding and make single place for it
+ *
+ * @public exported from `@promptbook/core`
+ */
+({
+    TITLE: Color.fromHex('#244EA8'),
+    LINE: Color.fromHex('#eeeeee'),
+    SEPARATOR: Color.fromHex('#cccccc'),
+    COMMITMENT: Color.fromHex('#DA0F78'),
+    PARAMETER: Color.fromHex('#8e44ad'),
+});
+// <- TODO: [🧠][🈵] Using `Color` here increases the package size approx 3kb, maybe remove it
 /**
- * Dark color of the Promptbook
+ * Chat color of the Promptbook (in chat)
  *
  * TODO: [🗽] Unite branding and make single place for it
  *
  * @public exported from `@promptbook/core`
  */
 PROMPTBOOK_COLOR.then(lighten(0.1)).then(saturate(0.9)).then(grayscale(0.9));
+// <- TODO: [🧠][🈵] Using `Color` and `lighten`, `saturate`,... here increases the package size approx 3kb, maybe remove it
 /**
  * Color of the user (in chat)
  *
@@ -1235,6 +1251,7 @@ PROMPTBOOK_COLOR.then(lighten(0.1)).then(saturate(0.9)).then(grayscale(0.9));
  * @public exported from `@promptbook/core`
  */
 Color.fromHex('#1D4ED8');
+// <- TODO: [🧠][🈵] Using `Color` here increases the package size approx 3kb, maybe remove it
 /**
  * When the title is not provided, the default title is used
  *
@@ -1305,7 +1322,7 @@ parseInt(process.env.API_REQUEST_TIMEOUT || '90000');
 function getErrorReportUrl(error) {
     const report = {
         title: `🐜 Error report from ${NAME}`,
-        body: spaceTrim$1((block) => `
+        body: spaceTrim$2((block) => `
 
 
             \`${error.name || 'Error'}\` has occurred in the [${NAME}], please look into it @${ADMIN_GITHUB_NAME}.
@@ -1348,7 +1365,7 @@ function getErrorReportUrl(error) {
  */
 class UnexpectedError extends Error {
     constructor(message) {
-        super(spaceTrim((block) => `
+        super(spaceTrim$1((block) => `
                     ${block(message)}
 
                     Note: This error should not happen.
@@ -1374,7 +1391,7 @@ class WrappedError extends Error {
     constructor(whatWasThrown) {
         const tag = `[🤮]`;
         console.error(tag, whatWasThrown);
-        super(spaceTrim(`
+        super(spaceTrim$1(`
                 Non-Error object was thrown
 
                 Note: Look for ${tag} in the console for more details
@@ -1409,6 +1426,8 @@ const PROMPTBOOK_ERRORS = {
     PromptbookFetchError,
     UnexpectedError,
     WrappedError,
+    NotAllowed,
+    DatabaseError,
     // TODO: [🪑]> VersionMismatchError,
 };
 /**
@@ -1461,7 +1480,7 @@ function deserializeError(error) {
         message = `${name}: ${message}`;
     }
     if (stack !== undefined && stack !== '') {
-        message = spaceTrim$1((block) => `
+        message = spaceTrim$2((block) => `
                 ${block(message)}
 
                 Original stack trace:
@@ -1518,7 +1537,7 @@ async function createRemoteClient(options) {
     const remoteServerUrlParsed = new URL(remoteServerUrl);
     if (remoteServerUrlParsed.pathname !== '/' && remoteServerUrlParsed.pathname !== '') {
         remoteServerUrlParsed.pathname = '/';
-        throw new Error(spaceTrim$1((block) => `
+        throw new Error(spaceTrim$2((block) => `
                         Remote server requires root url \`/\`
 
                         You have provided \`remoteServerUrl\`:
@@ -1943,6 +1962,8 @@ function removeDiacritics(input) {
 /**
  * Converts a given text to kebab-case format.
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @param text The text to be converted.
  * @returns The kebab-case formatted string.
  * @example 'hello-world'
@@ -2052,7 +2073,7 @@ const knowledgeCommandParser = {
      */
     parse(input) {
         const { args } = input;
-        const knowledgeSourceContent = spaceTrim$1(args[0] || '');
+        const knowledgeSourceContent = spaceTrim$2(args[0] || '');
         if (knowledgeSourceContent === '') {
             throw new ParseError(`Source is not defined`);
         }
@@ -2196,7 +2217,7 @@ const sectionCommandParser = {
         normalized = normalized.split('DIALOGUE').join('DIALOG');
         const taskTypes = SectionTypes.filter((sectionType) => normalized.includes(sectionType.split('_TASK').join('')));
         if (taskTypes.length !== 1) {
-            throw new ParseError(spaceTrim$1((block) => `
+            throw new ParseError(spaceTrim$2((block) => `
                         Unknown section type "${normalized}"
 
                         Supported section types are:
@@ -2216,7 +2237,7 @@ const sectionCommandParser = {
      */
     $applyToTaskJson(command, $taskJson, $pipelineJson) {
         if ($taskJson.isSectionTypeSet === true) {
-            throw new ParseError(spaceTrim$1(`
+            throw new ParseError(spaceTrim$2(`
                     Section type is already defined in the section.
                     It can be defined only once.
                 `));
@@ -2635,7 +2656,7 @@ const expectCommandParser = {
     /**
      * Description of the FORMAT command
      */
-    description: spaceTrim$1(`
+    description: spaceTrim$2(`
         Expect command describes the desired output of the task *(after post-processing)*
         It can set limits for the maximum/minimum length of the output, measured in characters, words, sentences, paragraphs or some other shape of the output.
     `),
@@ -2709,7 +2730,7 @@ const expectCommandParser = {
         }
         catch (error) {
             assertsError(error);
-            throw new ParseError(spaceTrim$1((block) => `
+            throw new ParseError(spaceTrim$2((block) => `
                             Invalid FORMAT command
                             ${block(error.message)}:
                         `));
@@ -2831,7 +2852,7 @@ const CsvFormatParser = {
                 const { value, outputParameterName, settings, mapCallback, onProgress } = options;
                 const csv = csvParse(value, settings);
                 if (csv.errors.length !== 0) {
-                    throw new CsvFormatError(spaceTrim$1((block) => `
+                    throw new CsvFormatError(spaceTrim$2((block) => `
                                 CSV parsing error
 
                                 Error(s) from CSV parsing:
@@ -2876,7 +2897,7 @@ const CsvFormatParser = {
                 const { value, settings, mapCallback, onProgress } = options;
                 const csv = csvParse(value, settings);
                 if (csv.errors.length !== 0) {
-                    throw new CsvFormatError(spaceTrim$1((block) => `
+                    throw new CsvFormatError(spaceTrim$2((block) => `
                                 CSV parsing error
 
                                 Error(s) from CSV parsing:
@@ -3221,7 +3242,7 @@ function checkSerializableAsJson(options) {
     }
     else if (typeof value === 'object') {
         if (value instanceof Date) {
-            throw new UnexpectedError(spaceTrim$1((block) => `
+            throw new UnexpectedError(spaceTrim$2((block) => `
                         \`${name}\` is Date
 
                         Use \`string_date_iso8601\` instead
@@ -3240,7 +3261,7 @@ function checkSerializableAsJson(options) {
             throw new UnexpectedError(`${name} is RegExp`);
         }
         else if (value instanceof Error) {
-            throw new UnexpectedError(spaceTrim$1((block) => `
+            throw new UnexpectedError(spaceTrim$2((block) => `
                         \`${name}\` is unserialized Error
 
                         Use function \`serializeError\`
@@ -3263,7 +3284,7 @@ function checkSerializableAsJson(options) {
             }
             catch (error) {
                 assertsError(error);
-                throw new UnexpectedError(spaceTrim$1((block) => `
+                throw new UnexpectedError(spaceTrim$2((block) => `
                             \`${name}\` is not serializable
 
                             ${block(error.stack || error.message)}
@@ -3295,7 +3316,7 @@ function checkSerializableAsJson(options) {
         }
     }
     else {
-        throw new UnexpectedError(spaceTrim$1((block) => `
+        throw new UnexpectedError(spaceTrim$2((block) => `
                     \`${name}\` is unknown type
 
                     Additional message for \`${name}\`:
@@ -3325,7 +3346,7 @@ function deepClone(objectValue) {
     TODO: [🧠] Is there a better implementation?
     > const propertyNames = Object.getOwnPropertyNames(objectValue);
     > for (const propertyName of propertyNames) {
-    >     const value = (objectValue as really_any)[propertyName];
+    >     const value = (objectValue as chococake)[propertyName];
     >     if (value && typeof value === 'object') {
     >         deepClone(value);
     >     }
@@ -3418,6 +3439,8 @@ const RESERVED_PARAMETER_NAMES = exportJson({
 /**
  * Normalizes a given text to camelCase format.
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @param text The text to be normalized.
  * @param _isFirstLetterCapital Whether the first letter should be capitalized.
  * @returns The camelCase formatted string.
@@ -3513,6 +3536,8 @@ function removeQuotes(text) {
  * 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.
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @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.
@@ -3572,7 +3597,7 @@ function validateParameterName(parameterName) {
         if (!(error instanceof ParseError)) {
             throw error;
         }
-        throw new ParseError(spaceTrim$1((block) => `
+        throw new ParseError(spaceTrim$2((block) => `
                     ${block(error.message)}
 
                     Tried to validate parameter name:
@@ -3631,7 +3656,7 @@ const foreachCommandParser = {
         const assignSign = args[3];
         const formatDefinition = FORMAT_DEFINITIONS.find((formatDefinition) => [formatDefinition.formatName, ...(formatDefinition.aliases || [])].includes(formatName));
         if (formatDefinition === undefined) {
-            throw new ParseError(spaceTrim$1((block) => `
+            throw new ParseError(spaceTrim$2((block) => `
                         Unsupported format "${formatName}"
 
                         Available formats:
@@ -3643,7 +3668,7 @@ const foreachCommandParser = {
         }
         const subvalueParser = formatDefinition.subvalueParsers.find((subvalueParser) => [subvalueParser.subvalueName, ...(subvalueParser.aliases || [])].includes(subformatName));
         if (subvalueParser === undefined) {
-            throw new ParseError(spaceTrim$1((block) => `
+            throw new ParseError(spaceTrim$2((block) => `
                         Unsupported subformat name "${subformatName}" for format "${formatName}"
 
                         Available subformat names for format "${formatDefinition.formatName}":
@@ -3691,7 +3716,7 @@ const foreachCommandParser = {
                 outputSubparameterName = 'newLine';
             }
             else {
-                throw new ParseError(spaceTrim$1(`
+                throw new ParseError(spaceTrim$2(`
                         FOREACH ${formatName} ${subformatName} must specify output subparameter
 
                         Correct example:
@@ -3767,7 +3792,7 @@ const formatCommandParser = {
     /**
      * Description of the FORMAT command
      */
-    description: spaceTrim$1(`
+    description: spaceTrim$2(`
         Format command describes the desired output of the task (after post-processing)
         It can set limits for the maximum/minimum length of the output, measured in characters, words, sentences, paragraphs or some other shape of the output.
     `),
@@ -4139,7 +4164,7 @@ const formfactorCommandParser = {
         const formfactorNameCandidate = args[0].toUpperCase();
         const formfactor = FORMFACTOR_DEFINITIONS.find((definition) => [definition.name, ...{ aliasNames: [], ...definition }.aliasNames].includes(formfactorNameCandidate));
         if (formfactor === undefined) {
-            throw new ParseError(spaceTrim$1((block) => `
+            throw new ParseError(spaceTrim$2((block) => `
                         Unknown formfactor name "${formfactorNameCandidate}"
 
                         Available formfactors:
@@ -4158,7 +4183,7 @@ const formfactorCommandParser = {
      */
     $applyToPipelineJson(command, $pipelineJson) {
         if ($pipelineJson.formfactorName !== undefined && $pipelineJson.formfactorName !== command.formfactorName) {
-            throw new ParseError(spaceTrim$1(`
+            throw new ParseError(spaceTrim$2(`
                     Redefinition of \`FORMFACTOR\` in the pipeline head
 
                     You have used:
@@ -4301,7 +4326,7 @@ const modelCommandParser = {
      */
     parse(input) {
         const { args, normalized } = input;
-        const availableVariantsMessage = spaceTrim$1((block) => `
+        const availableVariantsMessage = spaceTrim$2((block) => `
               Available variants are:
               ${block(MODEL_VARIANTS.map((variantName) => `- ${variantName}${variantName !== 'EMBEDDING' ? '' : ' (Not available in pipeline)'}`).join('\n'))}
           `);
@@ -4323,14 +4348,14 @@ const modelCommandParser = {
                 // <- Note: [🤖]
             }
             else if (normalized.startsWith('MODEL_VARIANT_EMBED')) {
-                spaceTrim$1((block) => `
+                spaceTrim$2((block) => `
                         Embedding model can not be used in pipeline
 
                         ${block(availableVariantsMessage)}
                     `);
             }
             else {
-                throw new ParseError(spaceTrim$1((block) => `
+                throw new ParseError(spaceTrim$2((block) => `
                             Unknown model variant in command:
 
                             ${block(availableVariantsMessage)}
@@ -4345,7 +4370,7 @@ const modelCommandParser = {
             };
         }
         else {
-            throw new ParseError(spaceTrim$1((block) => `
+            throw new ParseError(spaceTrim$2((block) => `
                     Unknown model key in command.
 
                     Supported model keys are:
@@ -4372,7 +4397,7 @@ const modelCommandParser = {
                 // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
             }
             else {
-                throw new ParseError(spaceTrim$1(`
+                throw new ParseError(spaceTrim$2(`
                         Redefinition of \`MODEL ${command.key}\` in the pipeline head
 
                         You have used:
@@ -4404,7 +4429,7 @@ const modelCommandParser = {
                 // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
             }
             else {
-                throw new ParseError(spaceTrim$1(`
+                throw new ParseError(spaceTrim$2(`
                               Redefinition of MODEL \`${command.key}\` in the task "${$taskJson.title || $taskJson.name}"
 
                               You have used:
@@ -4414,7 +4439,7 @@ const modelCommandParser = {
             }
         }
         if (command.value === ($pipelineJson.defaultModelRequirements || {})[command.key]) {
-            console.log(spaceTrim$1(`
+            console.log(spaceTrim$2(`
                     Setting MODEL \`${command.key}\` in the task "${$taskJson.title || $taskJson.name}" to the same value as in the pipeline head
 
                     In pipeline head:
@@ -4497,7 +4522,7 @@ const parameterCommandParser = {
         // <- TODO: When [🥶] fixed, change to:
         //        >   const parameterDescriptionRaw = rawArgs.split(parameterNameRaw).join('').trim();
         if (parameterDescriptionRaw && parameterDescriptionRaw.match(/\{(?<embeddedParameterName>[a-z0-9_]+)\}/im)) {
-            throw new ParseError(spaceTrim$1((block) => `
+            throw new ParseError(spaceTrim$2((block) => `
                         Parameter \`{${parameterNameRaw}}\` can not contain another parameter in description
 
                         The description:
@@ -4679,7 +4704,7 @@ function $applyToTaskJson(command, $taskJson, $pipelineJson) {
         persona.description = personaDescription;
         return;
     }
-    console.warn(spaceTrim$1(`
+    console.warn(spaceTrim$2(`
 
             Persona "${personaName}" is defined multiple times with different description:
 
@@ -4690,7 +4715,7 @@ function $applyToTaskJson(command, $taskJson, $pipelineJson) {
             ${personaDescription}
 
         `));
-    persona.description += spaceTrim$1('\n\n' + personaDescription);
+    persona.description += spaceTrim$2('\n\n' + personaDescription);
 }
 
 /**
@@ -5087,7 +5112,7 @@ const COMMANDS = [
 function getParserForCommand(command) {
     const commandParser = COMMANDS.find((commandParser) => commandParser.name === command.type);
     if (commandParser === undefined) {
-        throw new UnexpectedError(spaceTrim((block) => `
+        throw new UnexpectedError(spaceTrim$1((block) => `
                     Command ${command.type} parser is not found
 
                     ${block(JSON.stringify(command, null, 4)
@@ -5163,7 +5188,7 @@ function parseCommand(raw, usagePlace) {
         .map(removeMarkdownFormatting)
         .map((item) => item.trim());
     if (items.length === 0 || items[0] === '') {
-        throw new ParseError(spaceTrim((block) => `
+        throw new ParseError(spaceTrim$1((block) => `
                         Malformed command:
                         - ${raw}
 
@@ -5199,7 +5224,7 @@ function parseCommand(raw, usagePlace) {
             return command;
         }
     }
-    throw new ParseError(spaceTrim((block) => `
+    throw new ParseError(spaceTrim$1((block) => `
                   Malformed or unknown command:
                   - ${raw}
 
@@ -5250,7 +5275,7 @@ function parseCommandVariant(input) {
                 if (!(error instanceof ParseError)) {
                     throw error;
                 }
-                throw new ParseError(spaceTrim((block) => `
+                throw new ParseError(spaceTrim$1((block) => `
                               Invalid ${commandName} command:
 
                               Your command:
@@ -5527,6 +5552,8 @@ function isValidEmail(email) {
  * Function `validatePipelineString` will validate the if the string is a valid pipeline string
  * It does not check if the string is fully logically correct, but if it is a string that can be a pipeline string or the string looks completely different.
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @param {string} pipelineString the candidate for a pipeline string
  * @returns {PipelineString} the same string as input, but validated as valid
  * @throws {ParseError} if the string is not a valid pipeline string
@@ -5560,6 +5587,48 @@ function validatePipelineString(pipelineString) {
 const SUPPORTED_SCRIPT_LANGUAGES = ['javascript', 'typescript', 'python'];
 //          <- TODO: [🏥] DRY
 
+/**
+ *  Number of padding lines to add at the end of the book content
+ *
+ * @public exported from `@promptbook/core`
+ */
+const PADDING_LINES = 11;
+/**
+ * A function that adds padding to the book content
+ *
+ * Note: [🔂] This function is idempotent.
+ *
+ * @public exported from `@promptbook/core`
+ */
+function padBook(content) {
+    if (!content) {
+        return '\n'.repeat(PADDING_LINES);
+    }
+    const lines = content.split('\n');
+    let trailingEmptyLines = 0;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (line === undefined) {
+            // Note: This should not happen in reality, but it's here to satisfy TypeScript's noUncheckedIndexedAccess option
+            continue;
+        }
+        if (line.trim() === '') {
+            trailingEmptyLines++;
+        }
+        else {
+            break;
+        }
+    }
+    if (trailingEmptyLines >= PADDING_LINES) {
+        return content;
+    }
+    const linesToAdd = PADDING_LINES - trailingEmptyLines;
+    return (content + '\n'.repeat(linesToAdd));
+}
+/**
+ * TODO: [🧠] Maybe export
+ */
+
 /**
  * Removes Markdown (or HTML) comments
  *
@@ -5568,7 +5637,7 @@ const SUPPORTED_SCRIPT_LANGUAGES = ['javascript', 'typescript', 'python'];
  * @public exported from `@promptbook/markdown-utils`
  */
 function removeMarkdownComments(content) {
-    return spaceTrim(content.replace(/<!--(.*?)-->/gs, ''));
+    return spaceTrim$1(content.replace(/<!--(.*?)-->/gs, ''));
 }
 
 /**
@@ -5579,7 +5648,7 @@ function removeMarkdownComments(content) {
  */
 function isFlatPipeline(pipelineString) {
     pipelineString = removeMarkdownComments(pipelineString);
-    pipelineString = spaceTrim$1(pipelineString);
+    pipelineString = spaceTrim$2(pipelineString);
     const isMarkdownBeginningWithHeadline = pipelineString.startsWith('# ');
     //const isLastLineReturnStatement = pipelineString.split('\n').pop()!.split('`').join('').startsWith('->');
     const isBacktickBlockUsed = pipelineString.includes('```');
@@ -5605,6 +5674,7 @@ function deflatePipeline(pipelineString) {
     if (!isFlatPipeline(pipelineString)) {
         return pipelineString;
     }
+    pipelineString = spaceTrim$2(pipelineString);
     const pipelineStringLines = pipelineString.split('\n');
     const potentialReturnStatement = pipelineStringLines.pop();
     let returnStatement;
@@ -5617,19 +5687,19 @@ function deflatePipeline(pipelineString) {
         returnStatement = `-> {${DEFAULT_BOOK_OUTPUT_PARAMETER_NAME}}`;
         pipelineStringLines.push(potentialReturnStatement);
     }
-    const prompt = spaceTrim$1(pipelineStringLines.join('\n'));
+    const prompt = spaceTrim$2(pipelineStringLines.join('\n'));
     let quotedPrompt;
     if (prompt.split('\n').length <= 1) {
         quotedPrompt = `> ${prompt}`;
     }
     else {
-        quotedPrompt = spaceTrim$1((block) => `
+        quotedPrompt = spaceTrim$2((block) => `
                 \`\`\`
                 ${block(prompt.split('`').join('\\`'))}
                 \`\`\`
             `);
     }
-    pipelineString = validatePipelineString(spaceTrim$1((block) => `
+    pipelineString = validatePipelineString(spaceTrim$2((block) => `
                 # ${DEFAULT_BOOK_TITLE}
 
                 ## Prompt
@@ -5639,7 +5709,7 @@ function deflatePipeline(pipelineString) {
                 ${returnStatement}
             `));
     // <- TODO: Maybe use book` notation
-    return pipelineString;
+    return padBook(pipelineString);
 }
 /**
  * TODO: Unit test
@@ -5770,7 +5840,7 @@ function extractAllBlocksFromMarkdown(markdown) {
 function extractOneBlockFromMarkdown(markdown) {
     const codeBlocks = extractAllBlocksFromMarkdown(markdown);
     if (codeBlocks.length !== 1) {
-        throw new ParseError(spaceTrim$1((block) => `
+        throw new ParseError(spaceTrim$2((block) => `
                     There should be exactly 1 code block in task section, found ${codeBlocks.length} code blocks
 
                     ${block(codeBlocks.map((block, i) => `Block ${i + 1}:\n${block.content}`).join('\n\n\n'))}
@@ -5795,7 +5865,7 @@ function parseMarkdownSection(value) {
     }
     const title = lines[0].replace(/^#+\s*/, '');
     const level = (_b = (_a = lines[0].match(/^#+/)) === null || _a === void 0 ? void 0 : _a[0].length) !== null && _b !== void 0 ? _b : 0;
-    const content = spaceTrim$1(lines.slice(1).join('\n'));
+    const content = spaceTrim$2(lines.slice(1).join('\n'));
     if (level < 1 || level > 6) {
         throw new ParseError('Markdown section must have heading level between 1 and 6');
     }
@@ -5823,7 +5893,7 @@ function splitMarkdownIntoSections(markdown) {
         if (buffer.length === 0) {
             return;
         }
-        let section = spaceTrim$1(buffer.join('\n'));
+        let section = spaceTrim$2(buffer.join('\n'));
         if (section === '') {
             return;
         }
@@ -5898,7 +5968,7 @@ function flattenMarkdown(markdown) {
         flattenedMarkdown += `## ${title}` + `\n\n`;
         flattenedMarkdown += content + `\n\n`; // <- [🧠] Maybe 3 new lines?
     }
-    return spaceTrim$1(flattenedMarkdown);
+    return spaceTrim$2(flattenedMarkdown);
 }
 /**
  * TODO: [🏛] This can be part of markdown builder
@@ -5911,6 +5981,8 @@ function flattenMarkdown(markdown) {
 /**
  * Converts a title string into a normalized name.
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @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'
@@ -5984,7 +6056,7 @@ function extractVariablesFromJavascript(script) {
     }
     catch (error) {
         assertsError(error);
-        throw new ParseError(spaceTrim((block) => `
+        throw new ParseError(spaceTrim$1((block) => `
                     Can not extract variables from the script
                     ${block(error.stack || error.message)}
 
@@ -6126,7 +6198,7 @@ function parsePipeline(pipelineString) {
     if (pipelineString.startsWith('#!')) {
         const [shebangLine, ...restLines] = pipelineString.split('\n');
         if (!(shebangLine || '').includes('ptbk')) {
-            throw new ParseError(spaceTrim((block) => `
+            throw new ParseError(spaceTrim$1((block) => `
                         It seems that you try to parse a book file which has non-standard shebang line for book files:
                         Shebang line must contain 'ptbk'
 
@@ -6142,7 +6214,7 @@ function parsePipeline(pipelineString) {
         pipelineString = validatePipelineString(restLines.join('\n'));
     }
     pipelineString = removeMarkdownComments(pipelineString);
-    pipelineString = spaceTrim(pipelineString);
+    pipelineString = spaceTrim$1(pipelineString);
     // <- TODO: [😧] `spaceTrim` should preserve discriminated type *(or at lease `PipelineString`)*
     pipelineString = deflatePipeline(pipelineString);
     // ==============
@@ -6154,7 +6226,7 @@ function parsePipeline(pipelineString) {
     // ==============
     // Note: 1️⃣◽4️⃣ Check markdown structure
     if (pipelineHead === undefined) {
-        throw new UnexpectedError(spaceTrim((block) => `
+        throw new UnexpectedError(spaceTrim$1((block) => `
                     Pipeline head is not defined
 
                     ${block(getPipelineIdentification())}
@@ -6163,7 +6235,7 @@ function parsePipeline(pipelineString) {
                 `));
     }
     if (pipelineHead.level !== 1) {
-        throw new UnexpectedError(spaceTrim((block) => `
+        throw new UnexpectedError(spaceTrim$1((block) => `
                     Pipeline head is not h1
 
                     ${block(getPipelineIdentification())}
@@ -6172,7 +6244,7 @@ function parsePipeline(pipelineString) {
                 `));
     }
     if (!pipelineSections.every((section) => section.level === 2)) {
-        throw new UnexpectedError(spaceTrim((block) => `
+        throw new UnexpectedError(spaceTrim$1((block) => `
                     Not every pipeline section is h2
 
                     ${block(getPipelineIdentification())}
@@ -6185,7 +6257,7 @@ function parsePipeline(pipelineString) {
     const defineParam = (parameterCommand) => {
         const { parameterName, parameterDescription, isInput, isOutput } = parameterCommand;
         if (RESERVED_PARAMETER_NAMES.includes(parameterName)) {
-            throw new ParseError(spaceTrim((block) => `
+            throw new ParseError(spaceTrim$1((block) => `
                         Parameter name {${parameterName}} is reserved and cannot be used as resulting parameter name
 
                         ${block(getPipelineIdentification())}
@@ -6196,7 +6268,7 @@ function parsePipeline(pipelineString) {
             existingParameter.description &&
             existingParameter.description !== parameterDescription &&
             parameterDescription) {
-            throw new ParseError(spaceTrim((block) => `
+            throw new ParseError(spaceTrim$1((block) => `
                         Parameter \`{${parameterName}}\` is defined multiple times with different description:
 
                         ${block(getPipelineIdentification())}
@@ -6234,7 +6306,7 @@ function parsePipeline(pipelineString) {
     description = description.split(/^>.*$/gm).join('');
     //Note: Remove lists and return statement - TODO: [🎾] Make util  (exported from `@promptbool/utils`)
     description = description.split(/^(?:(?:-)|(?:\d\))|(?:`?->))\s+.*$/gm).join('');
-    description = spaceTrim(description);
+    description = spaceTrim$1(description);
     if (description === '') {
         description = undefined;
     }
@@ -6245,7 +6317,7 @@ function parsePipeline(pipelineString) {
         const command = parseCommand(listItem, 'PIPELINE_HEAD');
         const commandParser = getParserForCommand(command);
         if (commandParser.isUsedInPipelineHead !== true /* <- Note: [🦦][4] */) {
-            throw new ParseError(spaceTrim((block) => `
+            throw new ParseError(spaceTrim$1((block) => `
                         Command \`${command.type}\` is not allowed in the head of the pipeline ONLY at the pipeline task
 
                         ${block(getPipelineIdentification())}
@@ -6259,7 +6331,7 @@ function parsePipeline(pipelineString) {
             if (!(error instanceof ParseError)) {
                 throw error;
             }
-            throw new ParseError(spaceTrim((block) => `
+            throw new ParseError(spaceTrim$1((block) => `
                         Command ${command.type} failed to apply to the pipeline
 
                         The error:
@@ -6312,7 +6384,7 @@ function parsePipeline(pipelineString) {
         description = description.split(/^>.*$/gm).join('');
         //Note: Remove lists and return statement - TODO: [🎾]
         description = description.split(/^(?:(?:-)|(?:\d\))|(?:`?->))\s+.*$/gm).join('');
-        description = spaceTrim(description);
+        description = spaceTrim$1(description);
         if (description === '') {
             description = undefined;
         }
@@ -6346,7 +6418,7 @@ function parsePipeline(pipelineString) {
         for (const { listItem, command } of commands) {
             const commandParser = getParserForCommand(command);
             if (commandParser.isUsedInPipelineTask !== true /* <- Note: [🦦][4] */) {
-                throw new ParseError(spaceTrim((block) => `
+                throw new ParseError(spaceTrim$1((block) => `
                             Command \`${command.type}\` is not allowed in the task of the promptbook ONLY at the pipeline head
 
                             ${block(getPipelineIdentification())}
@@ -6361,7 +6433,7 @@ function parsePipeline(pipelineString) {
                 if (!(error instanceof ParseError)) {
                     throw error;
                 }
-                throw new ParseError(spaceTrim((block) => `
+                throw new ParseError(spaceTrim$1((block) => `
                             Command \`${command.type}\` failed to apply to the task
 
                             The error:
@@ -6392,14 +6464,14 @@ function parsePipeline(pipelineString) {
         // TODO: [🍧] Should be done in SECTION command
         if ($taskJson.taskType === 'SCRIPT_TASK') {
             if (!language) {
-                throw new ParseError(spaceTrim((block) => `
+                throw new ParseError(spaceTrim$1((block) => `
                             You must specify the language of the script in the \`SCRIPT\` task
 
                             ${block(getPipelineIdentification())}
                         `));
             }
             if (!SUPPORTED_SCRIPT_LANGUAGES.includes(language)) {
-                throw new ParseError(spaceTrim((block) => `
+                throw new ParseError(spaceTrim$1((block) => `
                             Script language ${language} is not supported.
 
                             Supported languages are: