@promptbook/google 0.112.0-11 → 0.112.0-111

package/umd/index.umd.js

@@ -1,12 +1,11 @@
 (function (global, factory) {
     typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('crypto'), require('spacetrim'), require('colors')) :
     typeof define === 'function' && define.amd ? define(['exports', 'crypto', 'spacetrim', 'colors'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-google"] = {}, global.crypto, global.spaceTrim$1, global.colors));
-})(this, (function (exports, crypto, spaceTrim$1, colors) { 'use strict';
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-google"] = {}, global.crypto, global.spacetrim, global.colors));
+})(this, (function (exports, crypto, spacetrim, colors) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
-    var spaceTrim__default = /*#__PURE__*/_interopDefaultLegacy(spaceTrim$1);
     var colors__default = /*#__PURE__*/_interopDefaultLegacy(colors);
 
     // ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
@@ -23,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-11';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-111';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -35,16 +34,15 @@
      * 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
      * @returns secure random token
+     *
+     * @private internal helper function
      */
     function $randomToken(randomness) {
         return crypto.randomBytes(randomness).toString('hex');
     }
-    /**
-     * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
-     * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
-     */
+    // TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+    // TODO: Maybe use nanoid instead https://github.com/ai/nanoid
 
     /**
      * This error indicates errors during the execution of the pipeline
@@ -61,9 +59,7 @@
             Object.setPrototypeOf(this, PipelineExecutionError.prototype);
         }
     }
-    /**
-     * TODO: [🧠][🌂] Add id to all errors
-     */
+    // TODO: [🧠][🌂] Add id to all errors
 
     /**
      * Counts number of characters in the text
@@ -79,10 +75,8 @@
         text = text.replace(/\p{Extended_Pictographic}(\u{200D}\p{Extended_Pictographic})*/gu, '-');
         return text.length;
     }
-    /**
-     * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
-     * TODO: [🧠][✌️] Make some Promptbook-native token system
-     */
+    // TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+    // TODO: [🧠][✌️] Make some Promptbook-native token system
 
     /**
      * Number of characters per standard line with 11pt Arial font size.
@@ -96,10 +90,8 @@
      * @public exported from `@promptbook/utils`
      */
     const LINES_PER_STANDARD_PAGE = 44;
-    /**
-     * TODO: [🧠] Should be this `constants.ts` or `config.ts`?
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // TODO: [🧠] Should be this `constants.ts` or `config.ts`?
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Counts number of lines in the text
@@ -117,10 +109,8 @@
         const lines = text.split(/\r?\n/);
         return lines.reduce((count, line) => count + Math.max(Math.ceil(line.length / CHARACTERS_PER_STANDARD_LINE), 1), 0);
     }
-    /**
-     * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
-     * TODO: [🧠][✌️] Make some Promptbook-native token system
-     */
+    // TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+    // TODO: [🧠][✌️] Make some Promptbook-native token system
 
     /**
      * Counts number of pages in the text
@@ -132,10 +122,8 @@
     function countPages(text) {
         return Math.ceil(countLines(text) / LINES_PER_STANDARD_PAGE);
     }
-    /**
-     * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
-     * TODO: [🧠][✌️] Make some Promptbook-native token system
-     */
+    // TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+    // TODO: [🧠][✌️] Make some Promptbook-native token system
 
     /**
      * Counts number of paragraphs in the text
@@ -145,10 +133,8 @@
     function countParagraphs(text) {
         return text.split(/\n\s*\n/).filter((paragraph) => paragraph.trim() !== '').length;
     }
-    /**
-     * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
-     * TODO: [🧠][✌️] Make some Promptbook-native token system
-     */
+    // TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+    // TODO: [🧠][✌️] Make some Promptbook-native token system
 
     /**
      * Split text into sentences
@@ -166,11 +152,12 @@
     function countSentences(text) {
         return splitIntoSentences(text).length;
     }
+    // TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+    // TODO: [🧠][✌️] Make some Promptbook-native token system
+
     /**
-     * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
-     * TODO: [🧠][✌️] Make some Promptbook-native token system
+     * Collection of default diacritics removal map.
      */
-
     const defaultDiacriticsRemovalMap = [
         {
             base: 'A',
@@ -422,6 +409,7 @@
      *
      * @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) {
@@ -430,9 +418,7 @@
             return DIACRITIC_VARIANTS_LETTERS[character] || character;
         });
     }
-    /**
-     * TODO: [Ж] Variant for cyrillic (and in general non-latin) letters
-     */
+    // TODO: [Ж] Variant for cyrillic (and in general non-latin) letters
 
     /**
      * Counts number of words in the text
@@ -446,11 +432,9 @@
         text = text.replace(/([a-z])([A-Z])/g, '$1 $2');
         return text.split(/[^a-zа-я0-9]+/i).filter((word) => word.length > 0).length;
     }
-    /**
-     * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
-     * TODO: [🧠][✌️] Make some Promptbook-native token system
-     * TODO: [✌️] `countWords` should be just `splitWords(...).length`, and all other counters should use this pattern as well
-     */
+    // TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+    // TODO: [🧠][✌️] Make some Promptbook-native token system
+    // TODO: [✌️] `countWords` should be just `splitWords(...).length`, and all other counters should use this pattern as well
 
     /**
      * Helper of usage compute
@@ -478,6 +462,7 @@
      * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
      *
      * @returns The same object as the input, but deeply frozen
+     *
      * @public exported from `@promptbook/utils`
      */
     function $deepFreeze(objectValue) {
@@ -494,9 +479,7 @@
         Object.freeze(objectValue);
         return objectValue;
     }
-    /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
-     */
+    // TODO: [🧠] Is there a way how to meaningfully test this utility
 
     /**
      * Represents the uncertain value
@@ -564,9 +547,7 @@
             pagesCount: UNCERTAIN_ZERO_VALUE,
         },
     });
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Make UncertainNumber
@@ -602,9 +583,7 @@
             return false;
         }
     }
-    /**
-     * TODO: [🎺]
-     */
+    // TODO: [🎺]
 
     /**
      * Simple wrapper `new Date().toISOString()`
@@ -612,6 +591,7 @@
      * Note: `$` is used to indicate that this function is not a pure function - it is not deterministic because it depends on the current time
      *
      * @returns string_date branded type
+     *
      * @public exported from `@promptbook/utils`
      */
     function $getCurrentDate() {
@@ -622,16 +602,20 @@
      * 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
+     * Developed by same author @hejny as this package
      *
-     * @public exported from `@promptbook/utils`
      * @see https://github.com/hejny/spacetrim#usage
+     *
+     * @public exported from `@promptbook/utils`
      */
-    const spaceTrim = spaceTrim$1.spaceTrim;
+    const spaceTrim = spacetrim.spaceTrim;
 
     /**
-     * @private util of `@promptbook/color`
+     * Class implementing take chain.
+     *
      * @de
+     *
+     * @private util of `@promptbook/color`
      */
     class TakeChain {
         constructor(value) {
@@ -648,9 +632,9 @@
      *
      * @param {*} initialValue - The initial value.
      * @returns {Proxy<WithTake<TValue>>} - A proxy object with a `take` method.
+     * @deprecated [🤡] Use some better functional library instead of `TakeChain`
      *
      * @private util of `@promptbook/color`
-     * @deprecated [🤡] Use some better functional library instead of `TakeChain`
      */
     function take(initialValue) {
         if (initialValue instanceof TakeChain) {
@@ -828,9 +812,7 @@
         yellow: '#ffff00',
         yellowgreen: '#9acd32',
     };
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Validates that a channel value is a valid number within the range of 0 to 255.
@@ -860,7 +842,118 @@
         }
     }
 
+    /**
+     * Shared immutable channel storage and serialization helpers for `Color`.
+     *
+     * @private base class of Color
+     */
+    class ColorValue {
+        constructor(red, green, blue, alpha = 255) {
+            this.red = red;
+            this.green = green;
+            this.blue = blue;
+            this.alpha = alpha;
+            checkChannelValue('Red', red);
+            checkChannelValue('Green', green);
+            checkChannelValue('Blue', blue);
+            checkChannelValue('Alpha', alpha);
+        }
+        /**
+         * Shortcut for `red` property
+         * Number from 0 to 255
+         * @alias red
+         */
+        get r() {
+            return this.red;
+        }
+        /**
+         * Shortcut for `green` property
+         * Number from 0 to 255
+         * @alias green
+         */
+        get g() {
+            return this.green;
+        }
+        /**
+         * Shortcut for `blue` property
+         * Number from 0 to 255
+         * @alias blue
+         */
+        get b() {
+            return this.blue;
+        }
+        /**
+         * Shortcut for `alpha` property
+         * Number from 0 (transparent) to 255 (opaque)
+         * @alias alpha
+         */
+        get a() {
+            return this.alpha;
+        }
+        /**
+         * Shortcut for `alpha` property
+         * Number from 0 (transparent) to 255 (opaque)
+         * @alias alpha
+         */
+        get opacity() {
+            return this.alpha;
+        }
+        /**
+         * Shortcut for 1-`alpha` property
+         */
+        get transparency() {
+            return 255 - this.alpha;
+        }
+        clone() {
+            return take(this.createColor(this.red, this.green, this.blue, this.alpha));
+        }
+        toString() {
+            return this.toHex();
+        }
+        toHex() {
+            if (this.alpha === 255) {
+                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}`;
+            }
+            else {
+                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
+            }
+        }
+        toRgb() {
+            if (this.alpha === 255) {
+                return `rgb(${this.red}, ${this.green}, ${this.blue})`;
+            }
+            else {
+                return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
+            }
+        }
+        toHsl() {
+            throw new Error(`Getting HSL is not implemented`);
+        }
+    }
+
+    /**
+     * Checks if the given value is a valid hex color string
+     *
+     * @param value - value to check
+     * @returns true if the value is a valid hex color string (e.g., `#009edd`, `#fff`, etc.)
+     *
+     * @private function of Color
+     */
+    function isHexColorString(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));
+    }
+
+    /**
+     * Constant for short hex lengths.
+     */
     const SHORT_HEX_LENGTHS = new Set([3, 4]);
+    /**
+     * Constant for long hex lengths.
+     */
     const LONG_HEX_LENGTHS = new Set([6, 8]);
     /**
      * Parses a hex string into RGBA channel values.
@@ -893,6 +986,9 @@
         }
         return throwInvalidHex();
     }
+    /**
+     * Parses short hex channel.
+     */
     function parseShortHexChannel(char, onError) {
         if (!char) {
             return onError();
@@ -903,6 +999,9 @@
         }
         return parsed * 16;
     }
+    /**
+     * Parses long hex channel.
+     */
     function parseLongHexChannel(hex, start, onError) {
         const segment = hex.substr(start, 2);
         if (segment.length < 2) {
@@ -915,6 +1014,9 @@
         return parsed;
     }
 
+    /**
+     * Pattern matching hsl.
+     */
     const HSL_REGEX = /^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/;
     /**
      * Parses an HSL string into RGBA channel values.
@@ -940,6 +1042,9 @@
             alpha: 255,
         };
     }
+    /**
+     * Handles convert hsl to Rgb.
+     */
     function convertHslToRgb(h, s, l) {
         const c = (1 - Math.abs(2 * l - 1)) * s;
         const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
@@ -978,7 +1083,13 @@
         };
     }
 
+    /**
+     * Pattern matching RGB.
+     */
     const RGB_REGEX = /^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    /**
+     * Pattern matching rgba.
+     */
     const RGBA_REGEX = /^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
     /**
      * Parses an RGB string into RGBA channel values.
@@ -1020,6 +1131,9 @@
             alpha: parseAlphaValue(match[4]),
         };
     }
+    /**
+     * Parses channel value.
+     */
     function parseChannelValue(value) {
         if (value.endsWith('%')) {
             const percent = parseFloat(value);
@@ -1027,6 +1141,9 @@
         }
         return Math.round(parseFloat(value));
     }
+    /**
+     * Parses alpha value.
+     */
     function parseAlphaValue(value) {
         if (value.endsWith('%')) {
             const percent = parseFloat(value);
@@ -1039,9 +1156,55 @@
         return Math.round(parsed);
     }
 
+    /**
+     * Pattern matching hsl regex.
+     *
+     * @private function of Color
+     */
     const HSL_REGEX_PATTERN = /^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/;
+    /**
+     * Pattern matching RGB regex.
+     *
+     * @private function of Color
+     */
     const RGB_REGEX_PATTERN = /^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    /**
+     * Pattern matching rgba regex.
+     *
+     * @private function of Color
+     */
     const RGBA_REGEX_PATTERN = /^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    /**
+     * Parses a supported color string into RGBA channels.
+     *
+     * @param color as a string for example `#009edd`, `rgb(0,158,221)`, `rgb(0%,62%,86.7%)`, `hsl(197.1,100%,43.3%)`, `red`, `darkgrey`,...
+     * @returns RGBA channel values.
+     *
+     * @private function of Color
+     */
+    function parseColorString(color) {
+        const trimmed = color.trim();
+        const cssColor = CSS_COLORS[trimmed];
+        if (cssColor) {
+            return parseColorString(cssColor);
+        }
+        else if (isHexColorString(trimmed)) {
+            return parseHexColor(trimmed);
+        }
+        if (HSL_REGEX_PATTERN.test(trimmed)) {
+            return parseHslColor(trimmed);
+        }
+        else if (RGB_REGEX_PATTERN.test(trimmed)) {
+            return parseRgbColor(trimmed);
+        }
+        else if (RGBA_REGEX_PATTERN.test(trimmed)) {
+            return parseRgbaColor(trimmed);
+        }
+        else {
+            throw new Error(`Can not create a new Color instance from string "${trimmed}".`);
+        }
+    }
+
     /**
      * Color object represents an RGB color with alpha channel
      *
@@ -1049,7 +1212,7 @@
      *
      * @public exported from `@promptbook/color`
      */
-    class Color {
+    class Color extends ColorValue {
         /**
          * Creates a new Color instance from miscellaneous formats
          * - It can receive Color instance and just return the same instance
@@ -1122,25 +1285,7 @@
          * @returns Color object
          */
         static fromString(color) {
-            const trimmed = color.trim();
-            if (CSS_COLORS[trimmed]) {
-                return Color.fromString(CSS_COLORS[trimmed]);
-            }
-            else if (Color.isHexColorString(trimmed)) {
-                return Color.fromHex(trimmed);
-            }
-            if (HSL_REGEX_PATTERN.test(trimmed)) {
-                return Color.fromHsl(trimmed);
-            }
-            else if (RGB_REGEX_PATTERN.test(trimmed)) {
-                return Color.fromRgbString(trimmed);
-            }
-            else if (RGBA_REGEX_PATTERN.test(trimmed)) {
-                return Color.fromRgbaString(trimmed);
-            }
-            else {
-                throw new Error(`Can not create a new Color instance from string "${trimmed}".`);
-            }
+            return Color.fromColorChannels(parseColorString(color));
         }
         /**
          * Gets common color
@@ -1170,8 +1315,7 @@
          * @returns Color object
          */
         static fromHex(hex) {
-            const { red, green, blue, alpha } = parseHexColor(hex);
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels(parseHexColor(hex));
         }
         /**
          * Creates a new Color instance from color in hsl format
@@ -1180,8 +1324,7 @@
          * @returns Color object
          */
         static fromHsl(hsl) {
-            const { red, green, blue, alpha } = parseHslColor(hsl);
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels(parseHslColor(hsl));
         }
         /**
          * Creates a new Color instance from color in rgb format
@@ -1190,8 +1333,7 @@
          * @returns Color object
          */
         static fromRgbString(rgb) {
-            const { red, green, blue, alpha } = parseRgbColor(rgb);
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels(parseRgbColor(rgb));
         }
         /**
          * Creates a new Color instance from color in rbga format
@@ -1200,8 +1342,7 @@
          * @returns Color object
          */
         static fromRgbaString(rgba) {
-            const { red, green, blue, alpha } = parseRgbaColor(rgba);
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels(parseRgbaColor(rgba));
         }
         /**
          * Creates a new Color for color channels values
@@ -1213,7 +1354,7 @@
          * @returns Color object
          */
         static fromValues(red, green, blue, alpha = 255) {
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels({ red, green, blue, alpha });
         }
         /**
          * Checks if the given value is a valid Color object.
@@ -1246,8 +1387,7 @@
          * @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}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(value));
+            return isHexColorString(value);
         }
         /**
          * Creates new Color object
@@ -1260,89 +1400,13 @@
          * @param alpha number from 0 (transparent) to 255 (opaque)
          */
         constructor(red, green, blue, alpha = 255) {
-            this.red = red;
-            this.green = green;
-            this.blue = blue;
-            this.alpha = alpha;
-            checkChannelValue('Red', red);
-            checkChannelValue('Green', green);
-            checkChannelValue('Blue', blue);
-            checkChannelValue('Alpha', alpha);
-        }
-        /**
-         * Shortcut for `red` property
-         * Number from 0 to 255
-         * @alias red
-         */
-        get r() {
-            return this.red;
-        }
-        /**
-         * Shortcut for `green` property
-         * Number from 0 to 255
-         * @alias green
-         */
-        get g() {
-            return this.green;
-        }
-        /**
-         * Shortcut for `blue` property
-         * Number from 0 to 255
-         * @alias blue
-         */
-        get b() {
-            return this.blue;
-        }
-        /**
-         * Shortcut for `alpha` property
-         * Number from 0 (transparent) to 255 (opaque)
-         * @alias alpha
-         */
-        get a() {
-            return this.alpha;
-        }
-        /**
-         * Shortcut for `alpha` property
-         * Number from 0 (transparent) to 255 (opaque)
-         * @alias alpha
-         */
-        get opacity() {
-            return this.alpha;
-        }
-        /**
-         * Shortcut for 1-`alpha` property
-         */
-        get transparency() {
-            return 255 - this.alpha;
-        }
-        clone() {
-            return take(new Color(this.red, this.green, this.blue, this.alpha));
-        }
-        toString() {
-            return this.toHex();
-        }
-        toHex() {
-            if (this.alpha === 255) {
-                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}`;
-            }
-            else {
-                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
-            }
+            super(red, green, blue, alpha);
         }
-        toRgb() {
-            if (this.alpha === 255) {
-                return `rgb(${this.red}, ${this.green}, ${this.blue})`;
-            }
-            else {
-                return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
-            }
+        createColor(red, green, blue, alpha) {
+            return new Color(red, green, blue, alpha);
         }
-        toHsl() {
-            throw new Error(`Getting HSL is not implemented`);
+        static fromColorChannels({ red, green, blue, alpha }) {
+            return take(new Color(red, green, blue, alpha));
         }
     }
 
@@ -1406,9 +1470,7 @@
         }
         return [Math.round(red * 255), Math.round(green * 255), Math.round(blue * 255)];
     }
-    /**
-     * TODO: Properly name all used internal variables
-     */
+    // TODO: Properly name all used internal variables
 
     /**
      * Converts RGB values to HSL values
@@ -1454,9 +1516,7 @@
         }
         return [hue, saturation, lightness];
     }
-    /**
-     * TODO: Properly name all used internal variables
-     */
+    // TODO: Properly name all used internal variables
 
     /**
      * Makes color transformer which lighten the given color
@@ -1474,9 +1534,7 @@
             return Color.fromValues(r, g, b, alpha);
         };
     }
-    /**
-     * TODO: Maybe implement by mix+hsl
-     */
+    // TODO: Maybe implement by mix+hsl
 
     /**
      * Makes color transformer which saturate the given color
@@ -1494,9 +1552,36 @@
             return Color.fromValues(r, g, b, alpha);
         };
     }
+    // TODO: Maybe implement by mix+hsl
+
     /**
-     * TODO: Maybe implement by mix+hsl
+     * Stable root directory used for Promptbook-owned temporary files and caches.
+     *
+     * @private internal utility for Promptbook temporary folders
      */
+    const PROMPTBOOK_TEMPORARY_DIRECTORY = '.promptbook';
+    /**
+     * Builds one normalized project-relative path inside Promptbook's dedicated temporary root.
+     *
+     * The returned path intentionally uses `/` separators so the same helper can be reused from
+     * Node.js and edge-safe code without depending on the Node `path` module.
+     *
+     * @private internal utility for Promptbook temporary folders
+     */
+    function getPromptbookTemporaryPath(...pathSegments) {
+        const normalizedPathSegments = pathSegments.flatMap(splitPathSegments).filter(Boolean);
+        return [PROMPTBOOK_TEMPORARY_DIRECTORY, ...normalizedPathSegments].join('/');
+    }
+    /**
+     * Normalizes one raw path segment into slash-delimited pieces without empty items.
+     */
+    function splitPathSegments(pathSegment) {
+        return pathSegment
+            .split(/[\\/]+/u)
+            .map((segment) => segment.trim())
+            .filter(Boolean);
+    }
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Name for the Promptbook
@@ -1592,6 +1677,31 @@
      * @public exported from `@promptbook/utils`
      */
     const SMALL_NUMBER = 0.001;
+    // <- TODO: [🕝] Make also `AGENTS_DIRNAME_ALTERNATIVES`
+    /**
+     * Where to store the temporary downloads
+     *
+     * Note: When the folder does not exist, it is created recursively
+     *
+     * @public exported from `@promptbook/core`
+     */
+`./${getPromptbookTemporaryPath('download-cache')}`;
+    /**
+     * Where to store the cache of executions for promptbook CLI
+     *
+     * Note: When the folder does not exist, it is created recursively
+     *
+     * @public exported from `@promptbook/core`
+     */
+`./${getPromptbookTemporaryPath('execution-cache')}`;
+    /**
+     * Where to store the scrape cache
+     *
+     * Note: When the folder does not exist, it is created recursively
+     *
+     * @public exported from `@promptbook/core`
+     */
+`./${getPromptbookTemporaryPath('scrape-cache')}`;
     // <- TODO: [🧜‍♂️]
     /**
      * Default settings for parsing and generating CSV files in Promptbook.
@@ -1620,6 +1730,7 @@
      * Orders JSON object by keys
      *
      * @returns The same type of object as the input re-ordered
+     *
      * @public exported from `@promptbook/utils`
      */
     function orderJson(options) {
@@ -1639,7 +1750,7 @@
     function getErrorReportUrl(error) {
         const report = {
             title: `🐜 Error report from ${NAME}`,
-            body: spaceTrim__default["default"]((block) => `
+            body: spacetrim.spaceTrim((block) => `
 
 
             \`${error.name || 'Error'}\` has occurred in the [${NAME}], please look into it @${ADMIN_GITHUB_NAME}.
@@ -1682,7 +1793,7 @@
      */
     class UnexpectedError extends Error {
         constructor(message) {
-            super(spaceTrim$1.spaceTrim((block) => `
+            super(spacetrim.spaceTrim((block) => `
                     ${block(message)}
 
                     Note: This error should not happen.
@@ -1708,7 +1819,7 @@
         constructor(whatWasThrown) {
             const tag = `[🤮]`;
             console.error(tag, whatWasThrown);
-            super(spaceTrim$1.spaceTrim(`
+            super(spacetrim.spaceTrim(`
                 Non-Error object was thrown
 
                 Note: Look for ${tag} in the console for more details
@@ -1765,125 +1876,187 @@
      * - And much more...
      *
      * @throws UnexpectedError if the value is not serializable as JSON
+     *
      * @public exported from `@promptbook/utils`
      */
     function checkSerializableAsJson(options) {
-        const { value, name, message } = options;
+        checkSerializableValue(options);
+    }
+    // TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
+    // TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
+    // Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
+    /**
+     * Checks one value and dispatches to the appropriate specialized validator.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableValue(options) {
+        const { value } = options;
+        if (isSerializablePrimitive(value)) {
+            return;
+        }
         if (value === undefined) {
-            throw new UnexpectedError(`${name} is undefined`);
+            throw new UnexpectedError(`${options.name} is undefined`);
         }
-        else if (value === null) {
-            return;
+        if (typeof value === 'symbol') {
+            throw new UnexpectedError(`${options.name} is symbol`);
         }
-        else if (typeof value === 'boolean') {
-            return;
+        if (typeof value === 'function') {
+            throw new UnexpectedError(`${options.name} is function`);
         }
-        else if (typeof value === 'number' && !isNaN(value)) {
+        if (Array.isArray(value)) {
+            checkSerializableArray(options, value);
             return;
         }
-        else if (typeof value === 'string') {
+        if (value !== null && typeof value === 'object') {
+            checkSerializableObject(options, value);
             return;
         }
-        else if (typeof value === 'symbol') {
-            throw new UnexpectedError(`${name} is symbol`);
-        }
-        else if (typeof value === 'function') {
-            throw new UnexpectedError(`${name} is function`);
-        }
-        else if (typeof value === 'object' && Array.isArray(value)) {
-            for (let i = 0; i < value.length; i++) {
-                checkSerializableAsJson({ name: `${name}[${i}]`, value: value[i], message });
-            }
+        throwUnknownTypeError(options);
+    }
+    /**
+     * Checks the primitive values that are directly JSON serializable.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function isSerializablePrimitive(value) {
+        return (value === null ||
+            typeof value === 'boolean' ||
+            (typeof value === 'number' && !isNaN(value)) ||
+            typeof value === 'string');
+    }
+    /**
+     * Recursively checks JSON array items.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableArray(context, arrayValue) {
+        for (let index = 0; index < arrayValue.length; index++) {
+            checkSerializableAsJson({
+                ...context,
+                name: `${context.name}[${index}]`,
+                value: arrayValue[index],
+            });
         }
-        else if (typeof value === 'object') {
-            if (value instanceof Date) {
-                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                        \`${name}\` is Date
+    }
+    /**
+     * Checks object-like values and dispatches special unsupported built-ins.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableObject(context, objectValue) {
+        checkUnsupportedObjectType(context, objectValue);
+        checkSerializableObjectEntries(context, objectValue);
+        assertJsonStringificationSucceeds(context, objectValue);
+    }
+    /**
+     * Rejects built-in objects that must be converted before JSON serialization.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkUnsupportedObjectType(context, objectValue) {
+        if (objectValue instanceof Date) {
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                    \`${context.name}\` is Date
 
-                        Use \`string_date_iso8601\` instead
+                    Use \`string_date_iso8601\` instead
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
-                    `));
-            }
-            else if (value instanceof Map) {
-                throw new UnexpectedError(`${name} is Map`);
-            }
-            else if (value instanceof Set) {
-                throw new UnexpectedError(`${name} is Set`);
-            }
-            else if (value instanceof RegExp) {
-                throw new UnexpectedError(`${name} is RegExp`);
-            }
-            else if (value instanceof Error) {
-                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                        \`${name}\` is unserialized Error
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
+                `));
+        }
+        if (objectValue instanceof Map) {
+            throw new UnexpectedError(`${context.name} is Map`);
+        }
+        if (objectValue instanceof Set) {
+            throw new UnexpectedError(`${context.name} is Set`);
+        }
+        if (objectValue instanceof RegExp) {
+            throw new UnexpectedError(`${context.name} is RegExp`);
+        }
+        if (objectValue instanceof Error) {
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                    \`${context.name}\` is unserialized Error
 
-                        Use function \`serializeError\`
+                    Use function \`serializeError\`
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
 
-                    `));
+                `));
+        }
+    }
+    /**
+     * Recursively checks object properties while preserving omitted `undefined` keys.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableObjectEntries(context, objectValue) {
+        for (const [subName, subValue] of Object.entries(objectValue)) {
+            if (subValue === undefined) {
+                // Note: undefined in object is serializable - it is just omitted
+                continue;
             }
-            else {
-                for (const [subName, subValue] of Object.entries(value)) {
-                    if (subValue === undefined) {
-                        // Note: undefined in object is serializable - it is just omitted
-                        continue;
-                    }
-                    checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
-                }
-                try {
-                    JSON.stringify(value); // <- TODO: [0]
-                }
-                catch (error) {
-                    assertsError(error);
-                    throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                            \`${name}\` is not serializable
+            checkSerializableAsJson({
+                ...context,
+                name: `${context.name}.${subName}`,
+                value: subValue,
+            });
+        }
+    }
+    /**
+     * Uses `JSON.stringify` as the final guard for cases like circular references.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function assertJsonStringificationSucceeds(context, objectValue) {
+        try {
+            JSON.stringify(objectValue); // <- TODO: [0]
+        }
+        catch (error) {
+            assertsError(error);
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                    \`${context.name}\` is not serializable
 
-                            ${block(error.stack || error.message)}
+                    ${block(error.stack || error.message)}
 
-                            Additional message for \`${name}\`:
-                            ${block(message || '(nothing)')}
-                        `));
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
+                `));
+        }
+        /*
+        TODO: [0] Is there some more elegant way to check circular references?
+        const seen = new Set();
+        const stack = [{ value }];
+        while (stack.length > 0) {
+            const { value } = stack.pop()!;
+            if (typeof value === 'object' && value !== null) {
+                if (seen.has(value)) {
+                    throw new UnexpectedError(`${name} has circular reference`);
                 }
-                /*
-                TODO: [0] Is there some more elegant way to check circular references?
-                const seen = new Set();
-                const stack = [{ value }];
-                while (stack.length > 0) {
-                    const { value } = stack.pop()!;
-                    if (typeof value === 'object' && value !== null) {
-                        if (seen.has(value)) {
-                            throw new UnexpectedError(`${name} has circular reference`);
-                        }
-                        seen.add(value);
-                        if (Array.isArray(value)) {
-                            stack.push(...value.map((value) => ({ value })));
-                        } else {
-                            stack.push(...Object.values(value).map((value) => ({ value })));
-                        }
-                    }
+                seen.add(value);
+                if (Array.isArray(value)) {
+                    stack.push(...value.map((value) => ({ value })));
+                } else {
+                    stack.push(...Object.values(value).map((value) => ({ value })));
                 }
-                */
-                return;
             }
         }
-        else {
-            throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                    \`${name}\` is unknown type
-
-                    Additional message for \`${name}\`:
-                    ${block(message || '(nothing)')}
-                `));
-        }
+        */
     }
     /**
-     * TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
-     * TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
-     * Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
+     * Throws the fallback error for unsupported value types like `bigint` and `NaN`.
+     *
+     * @private function of `checkSerializableAsJson`
      */
+    function throwUnknownTypeError(context) {
+        throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                \`${context.name}\` is unknown type
+
+                Additional message for \`${context.name}\`:
+                ${block(context.message || '(nothing)')}
+            `));
+    }
 
     /**
      * Creates a deep clone of the given object
@@ -1893,6 +2066,7 @@
      *
      * @param objectValue The object to clone.
      * @returns A deep, writable clone of the input object.
+     *
      * @public exported from `@promptbook/utils`
      */
     function deepClone(objectValue) {
@@ -1909,9 +2083,7 @@
         > return Object.assign({}, objectValue);
         */
     }
-    /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
-     */
+    // TODO: [🧠] Is there a way how to meaningfully test this utility
 
     /**
      * Utility to export a JSON object from a function
@@ -1924,6 +2096,7 @@
      * Note: This function does not mutates the given object
      *
      * @returns The same type of object as the input but read-only and re-ordered
+     *
      * @public exported from `@promptbook/utils`
      */
     function exportJson(options) {
@@ -1943,9 +2116,7 @@
         $deepFreeze(orderedValue);
         return orderedValue;
     }
-    /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
-     */
+    // TODO: [🧠] Is there a way how to meaningfully test this utility
 
     /**
      * Nonce which is used for replacing things in strings
@@ -1985,9 +2156,7 @@
             // <- TODO: Add [emoji] + instructions ACRY when adding new reserved parameter
         ],
     });
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * This error type indicates that some limit was reached
@@ -2035,8 +2204,8 @@
      * This is useful and used in the `templateParameters` function
      *
      * Note: This function is not just calling `toString` method
-     *       It's more complex and can handle this conversion specifically for LLM models
-     *       See `VALUE_STRINGS`
+     * It's more complex and can handle this conversion specifically for LLM models
+     * See `VALUE_STRINGS`
      *
      * Note: There are 2 similar functions
      * - `valueToString` converts value to string for LLM models as human-readable string
@@ -2087,12 +2256,13 @@
      * 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
+     * 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) {
@@ -2235,7 +2405,7 @@
                 const modelName = modelRequirements.modelName ||
                     ((_a = availableModels.find(({ modelVariant }) => modelVariant === 'CHAT')) === null || _a === void 0 ? void 0 : _a.modelName);
                 if (!modelName) {
-                    throw new PipelineExecutionError(spaceTrim__default["default"](`
+                    throw new PipelineExecutionError(spacetrim.spaceTrim(`
                         Can not determine which model to use.
 
                         You need to provide at least one of:
@@ -2360,9 +2530,10 @@
     /**
      * List of available Google models with descriptions
      *
-     * Note: Synced with official API docs at 2025-11-19
+     * Note: Synced with official API docs at 2026-03-22
      *
      * @see https://ai.google.dev/models/gemini
+     *
      * @public exported from `@promptbook/google`
      */
     const GOOGLE_MODELS = exportJson({
@@ -2381,8 +2552,8 @@
                 modelName: 'gemini-2.5-pro',
                 modelDescription: 'State-of-the-art thinking model with 1M token context window capable of reasoning over complex problems in code, math, and STEM. Features enhanced thinking capabilities, advanced multimodal understanding, and superior performance on analytical tasks. Ideal for complex enterprise applications requiring maximum intelligence and reasoning.',
                 pricing: {
-                    prompt: pricing(`$7.00 / 1M tokens`),
-                    output: pricing(`$21.00 / 1M tokens`),
+                    prompt: pricing(`$1.25 / 1M tokens`),
+                    output: pricing(`$10.00 / 1M tokens`),
                 },
             },
             {
@@ -2391,8 +2562,8 @@
                 modelName: 'gemini-2.5-flash',
                 modelDescription: 'Best model in terms of price-performance with 1M token context window offering well-rounded capabilities. Features adaptive thinking, cost efficiency, and enhanced reasoning for large-scale processing. Ideal for low-latency, high-volume tasks that require thinking and agentic use cases.',
                 pricing: {
-                    prompt: pricing(`$0.35 / 1M tokens`),
-                    output: pricing(`$1.05 / 1M tokens`),
+                    prompt: pricing(`$0.30 / 1M tokens`),
+                    output: pricing(`$2.50 / 1M tokens`),
                 },
             },
             {
@@ -2401,8 +2572,8 @@
                 modelName: 'gemini-2.5-flash-lite',
                 modelDescription: 'Cost-efficient Gemini 2.5 Flash model optimized for high throughput with 1M token context window. Features thinking capabilities while maintaining the most cost-efficient pricing. Perfect for real-time, low-latency use cases requiring good quality at scale.',
                 pricing: {
-                    prompt: pricing(`$0.20 / 1M tokens`),
-                    output: pricing(`$0.60 / 1M tokens`),
+                    prompt: pricing(`$0.10 / 1M tokens`),
+                    output: pricing(`$0.40 / 1M tokens`),
                 },
             },
             {
@@ -2577,12 +2748,10 @@
             },
         ],
     });
-    /**
-     * TODO: [🧠] Add information about context window sizes, capabilities, and relative performance characteristics
-     * TODO: [🎰] Some mechanism to auto-update available models
-     * TODO: [🧠] Verify pricing information is current with Google's official documentation
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // TODO: [🧠] Add information about context window sizes, capabilities, and relative performance characteristics
+    // TODO: [🎰] Some mechanism to auto-update available models
+    // TODO: [🧠] Verify pricing information is current with Google's official documentation
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Profile for Google Gemini provider
@@ -2592,7 +2761,13 @@
         fullname: 'Google Gemini',
         color: '#4285f4',
     };
+    /**
+     * Constant for default google generative AI base URL.
+     */
     const DEFAULT_GOOGLE_GENERATIVE_AI_BASE_URL = 'https://generativelanguage.googleapis.com/v1beta';
+    /**
+     * Map of google image response modalities.
+     */
     const GOOGLE_IMAGE_RESPONSE_MODALITIES = {
         responseModalities: ['TEXT', 'IMAGE'],
     };
@@ -2754,11 +2929,9 @@
     }, {
         packageName: '@promptbook/google',
         className: 'GoogleExecutionTools',
-    });
-    /**
-     * TODO: !!!!! Rename to `createGoogleLlmExecutionTools`, `...GoogleLlmExecutionTools`
-     * TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
-     */
+    }); /* <- Note: [🤛] */
+    // TODO: !!!!! Rename to `createGoogleLlmExecutionTools`, `...GoogleLlmExecutionTools`
+    // TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
 
     /**
      * This error type indicates that some part of the code is not implemented yet
@@ -2767,7 +2940,7 @@
      */
     class NotYetImplementedError extends Error {
         constructor(message) {
-            super(spaceTrim$1.spaceTrim((block) => `
+            super(spacetrim.spaceTrim((block) => `
                     ${block(message)}
 
                     Note: This feature is not implemented yet but it will be soon.
@@ -2789,7 +2962,7 @@
      *
      * Note: `$` is used to indicate that this function is not a pure function - it access global scope
      *
-     *  @private internal function of `$Register`
+     * @private internal function of `$Register`
      */
     function $getGlobalScope() {
         return Function('return this')();
@@ -2804,6 +2977,7 @@
      * @returns The normalized text in SCREAMING_CASE format.
      * @example 'HELLO_WORLD'
      * @example 'I_LOVE_PROMPTBOOK'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeTo_SCREAMING_CASE(text) {
@@ -2861,6 +3035,7 @@
      * @returns The normalized text in snake_case format.
      * @example 'hello_world'
      * @example 'i_love_promptbook'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeTo_snake_case(text) {
@@ -2919,13 +3094,13 @@
      * 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 there can be more instances across different builds or environments.
+     *
      * @public exported from `@promptbook/core`
      */
     const $llmToolsRegister = new $Register('llm_execution_tools_constructors');
-    /**
-     * TODO: [®] DRY Register logic
-     */
+    // TODO: [®] DRY Register logic
 
     /**
      * Registration of LLM provider
@@ -2937,10 +3112,8 @@
      * @public exported from `@promptbook/cli`
      */
     const _GoogleRegistration = $llmToolsRegister.register(createGoogleExecutionTools);
-    /**
-     * TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     exports.BOOK_LANGUAGE_VERSION = BOOK_LANGUAGE_VERSION;
     exports.GOOGLE_MODELS = GOOGLE_MODELS;