@promptbook/google 0.92.0-3 → 0.92.0-30

package/esm/typings/src/utils/organization/empty_object.d.ts

@@ -2,8 +2,8 @@
  * Organizational helper to better mark the place where to really use empty object `{}`
  *
  * Note: There are 2 similar types>
- * - `empty_object` @@@
- * - `just_empty_object` @@@
+ * - `empty_object` Type used for empty data objects allowing for potential future extensions
+ * - `just_empty_object` Type used when an object must remain permanently empty
  *
  * @private within the repository
  */

package/esm/typings/src/utils/organization/just_empty_object.d.ts

@@ -1,9 +1,9 @@
 /**
- * Organizational helper to better @@@@
+ * Organizational helper to better distinguish different empty object use cases.
  *
- * Note: There are 2 similar types>
- * - `empty_object` @@@
- * - `just_empty_object` @@@
+ * Note: There are 2 similar types:
+ * - `empty_object` Type used for empty data objects with potential extensions
+ * - `just_empty_object` Type used specifically for objects that must remain empty
  *
  * Note: In most cases, you should use `empty_object`
  *

package/esm/typings/src/utils/parameters/mapAvailableToExpectedParameters.d.ts

@@ -1,26 +1,26 @@
 import type { string_parameter_name } from '../../types/typeAliases';
 import type { string_parameter_value } from '../../types/typeAliases';
 /**
- * @@@
+ * Options for mapping available parameters to expected parameters in a pipeline task.
  */
 type MakeapAvailableToExpectedParametersOptions = {
     /**
-     * @@@
+     * The set of expected parameter names (keys) for the task, all values are null.
      */
     readonly expectedParameters: Readonly<Record<string_parameter_name, null>>;
     /**
-     * @@@
+     * The set of available parameters (name-value pairs) to map to the expected parameters.
      */
     readonly availableParameters: Readonly<Record<string_parameter_name, string_parameter_value>>;
 };
 /**
- * Maps available parameters to expected parameters
+ * Maps available parameters to expected parameters for a pipeline task.
  *
  * The strategy is:
- * 1) @@@
- * 2) @@@
+ * 1) First, match parameters by name where both available and expected.
+ * 2) Then, if there are unmatched expected and available parameters, map them by order.
  *
- * @throws {PipelineExecutionError} @@@
+ * @throws {PipelineExecutionError} If the number of unmatched expected and available parameters does not match, or mapping is ambiguous.
  * @private within the repository used in `createPipelineExecutor`
  */
 export declare function mapAvailableToExpectedParameters(options: MakeapAvailableToExpectedParametersOptions): Readonly<Record<string_parameter_name, string_parameter_value>>;

package/esm/typings/src/utils/serialization/clonePipeline.d.ts

@@ -1,10 +1,11 @@
 import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
 /**
- * @@@
+ * Creates a deep clone of a PipelineJson object, copying all properties explicitly.
  *
- * Note: It is usefull @@@
+ * Note: It is useful for ensuring that modifications to the returned pipeline do not affect the original.
  *
- * @param pipeline
+ * @param pipeline The pipeline to clone.
+ * @returns A new PipelineJson object with the same properties as the input.
  * @public exported from `@promptbook/utils`
  */
 export declare function clonePipeline(pipeline: PipelineJson): PipelineJson;

package/esm/typings/src/utils/serialization/deepClone.d.ts

@@ -1,7 +1,11 @@
 import type { WritableDeep } from 'type-fest';
 /**
- * @@@
+ * Creates a deep clone of the given object
  *
+ * Note: This method only works for objects that are fully serializable to JSON and do not contain functions, Dates, or special types.
+ *
+ * @param objectValue The object to clone.
+ * @returns A deep, writable clone of the input object.
  * @public exported from `@promptbook/utils`
  */
 export declare function deepClone<TObject>(objectValue: TObject): WritableDeep<TObject>;

package/esm/typings/src/utils/validators/javascriptName/isValidJavascriptName.d.ts

@@ -1,10 +1,10 @@
 import type { string_javascript_name } from '../../../types/typeAliases';
 import type { really_unknown } from '../../organization/really_unknown';
 /**
- * @@@
+ * Checks if the given value is a valid JavaScript identifier name.
  *
- * @param javascriptName @@@
- * @returns @@@
+ * @param javascriptName The value to check for JavaScript identifier validity.
+ * @returns `true` if the value is a valid JavaScript name, false otherwise.
  * @public exported from `@promptbook/utils`
  */
 export declare function isValidJavascriptName(javascriptName: really_unknown): javascriptName is string_javascript_name;

package/esm/typings/src/utils/validators/parameterName/validateParameterName.d.ts

@@ -1,10 +1,11 @@
 import type { string_parameter_name } from '../../../types/typeAliases';
 /**
- * Function `validateParameterName` will @@@
+ * 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.
  *
- * @param parameterName @@@
- * @returns @@@
- * @throws {ParseError} @@@
+ * @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.
  * @private within the repository
  */
 export declare function validateParameterName(parameterName: string): string_parameter_name;

package/esm/typings/src/version.d.ts

@@ -14,7 +14,8 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
  */
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
- * @@@
+ * Represents the version string of the Promptbook engine.
+ * It follows semantic versioning (e.g., `0.92.0-29`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/google",
-    "version": "0.92.0-3",
+    "version": "0.92.0-30",
     "description": "It's time for a paradigm shift. The future of software in plain English, French or Latin",
     "private": false,
     "sideEffects": false,
@@ -51,7 +51,7 @@
     "module": "./esm/index.es.js",
     "typings": "./esm/typings/src/_packages/google.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.92.0-3"
+        "@promptbook/core": "0.92.0-30"
     },
     "dependencies": {
         "@ai-sdk/google": "1.0.5",

package/umd/index.umd.js

@@ -23,7 +23,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-3';
+    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-30';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -424,10 +424,10 @@
     */
 
     /**
-     * @@@
+     * Removes diacritic marks (accents) from characters in a string.
      *
-     * @param input @@@
-     * @returns @@@
+     * @param input The string containing diacritics to be normalized.
+     * @returns The string with diacritics removed or normalized.
      * @public exported from `@promptbook/utils`
      */
     function removeDiacritics(input) {
@@ -573,14 +573,18 @@
     /**
      * Make UncertainNumber
      *
-     * @param value
+     * @param value value of the uncertain number, if `NaN` or `undefined`, it will be set to 0 and `isUncertain=true`
+     * @param isUncertain if `true`, the value is uncertain, otherwise depends on the value
      *
      * @private utility for initializating UncertainNumber
      */
-    function uncertainNumber(value) {
+    function uncertainNumber(value, isUncertain) {
         if (value === null || value === undefined || Number.isNaN(value)) {
             return UNCERTAIN_ZERO_VALUE;
         }
+        if (isUncertain === true) {
+            return { value, isUncertain };
+        }
         return { value };
     }
 
@@ -646,7 +650,7 @@
     const SMALL_NUMBER = 0.001;
     // <- TODO: [🧜‍♂️]
     /**
-     * @@@
+     * Default settings for parsing and generating CSV files in Promptbook.
      *
      * @public exported from `@promptbook/core`
      */
@@ -931,8 +935,12 @@
      */
 
     /**
-     * @@@
+     * Creates a deep clone of the given object
+     *
+     * Note: This method only works for objects that are fully serializable to JSON and do not contain functions, Dates, or special types.
      *
+     * @param objectValue The object to clone.
+     * @returns A deep, writable clone of the input object.
      * @public exported from `@promptbook/utils`
      */
     function deepClone(objectValue) {
@@ -994,13 +1002,13 @@
      */
     const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
     /**
-     * @@@
+     * Placeholder value indicating a parameter is missing its value.
      *
      * @private within the repository
      */
     const RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
     /**
-     * @@@
+     * Placeholder value indicating a parameter is restricted and cannot be used directly.
      *
      * @private within the repository
      */
@@ -1163,10 +1171,12 @@
                 throw new PipelineExecutionError('Parameter is already opened or not closed');
             }
             if (parameters[parameterName] === undefined) {
+                console.log('!!! templateParameters 1', { parameterName, template, parameters });
                 throw new PipelineExecutionError(`Parameter \`{${parameterName}}\` is not defined`);
             }
             let parameterValue = parameters[parameterName];
             if (parameterValue === undefined) {
+                console.log('!!! templateParameters 2', { parameterName, template, parameters });
                 throw new PipelineExecutionError(`Parameter \`{${parameterName}}\` is not defined`);
             }
             parameterValue = valueToString(parameterValue);
@@ -1358,6 +1368,183 @@
         };
     }
 
+    /**
+     * Function computeUsage will create price per one token based on the string value found on openai page
+     *
+     * @private within the repository, used only as internal helper for `OPENAI_MODELS`
+     */
+    function computeUsage(value) {
+        const [price, tokens] = value.split(' / ');
+        return parseFloat(price.replace('$', '')) / parseFloat(tokens.replace('M tokens', '')) / 1000000;
+    }
+
+    /**
+     * List of available Google models with descriptions
+     *
+     * Note: Done at 2025-05-06
+     *
+     * @see https://ai.google.dev/models/gemini
+     * @public exported from `@promptbook/google`
+     */
+    const GOOGLE_MODELS = exportJson({
+        name: 'GOOGLE_MODELS',
+        value: [
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 2.5 Pro',
+                modelName: 'gemini-2.5-pro-preview-03-25',
+                modelDescription: 'Latest advanced multimodal model with exceptional reasoning, tool use, and instruction following. 1M token context window with improved vision capabilities for complex visual tasks.',
+                pricing: {
+                    prompt: computeUsage(`$8.00 / 1M tokens`),
+                    output: computeUsage(`$24.00 / 1M tokens`),
+                },
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 2.0 Flash',
+                modelName: 'gemini-2.0-flash',
+                modelDescription: 'Fast, efficient model optimized for rapid response times. Good balance between performance and cost, with strong capabilities across text, code, and reasoning tasks. 128K context window.',
+                pricing: {
+                    prompt: computeUsage(`$0.35 / 1M tokens`),
+                    output: computeUsage(`$1.05 / 1M tokens`),
+                },
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 2.0 Flash Lite',
+                modelName: 'gemini-2.0-flash-lite',
+                modelDescription: 'Streamlined version of Gemini 2.0 Flash, designed for extremely low-latency applications and edge deployments. Optimized for efficiency while maintaining core capabilities.',
+                pricing: {
+                    prompt: computeUsage(`$0.20 / 1M tokens`),
+                    output: computeUsage(`$0.60 / 1M tokens`),
+                },
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 2.0 Flash Thinking',
+                modelName: 'gemini-2.0-flash-thinking-exp-01-21',
+                modelDescription: 'Experimental model focused on enhanced reasoning with explicit chain-of-thought processes. Designed for tasks requiring structured thinking and problem-solving approaches.',
+                pricing: {
+                    prompt: computeUsage(`$0.35 / 1M tokens`),
+                    output: computeUsage(`$1.05 / 1M tokens`),
+                },
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Flash',
+                modelName: 'gemini-1.5-flash',
+                modelDescription: 'Efficient model balancing speed and quality for general-purpose applications. 1M token context window with good multimodal capabilities and quick response times.',
+                pricing: {
+                    prompt: computeUsage(`$0.25 / 1M tokens`),
+                    output: computeUsage(`$0.75 / 1M tokens`),
+                },
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Flash Latest',
+                modelName: 'gemini-1.5-flash-latest',
+                modelDescription: 'Points to the latest version of Gemini 1.5 Flash, ensuring access to the most recent improvements and bug fixes while maintaining stable interfaces.',
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Flash 001',
+                modelName: 'gemini-1.5-flash-001',
+                modelDescription: 'First stable release of Gemini 1.5 Flash model with reliable performance characteristics for production applications. 1M token context window.',
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Flash 002',
+                modelName: 'gemini-1.5-flash-002',
+                modelDescription: 'Improved version of Gemini 1.5 Flash with enhanced instruction following and more consistent outputs. Refined for better application integration.',
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Flash Exp',
+                modelName: 'gemini-1.5-flash-exp-0827',
+                modelDescription: 'Experimental version of Gemini 1.5 Flash with new capabilities being tested. May offer improved performance but with potential behavior differences from stable releases.',
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Flash 8B',
+                modelName: 'gemini-1.5-flash-8b',
+                modelDescription: 'Compact 8B parameter model optimized for efficiency and deployment in resource-constrained environments. Good performance despite smaller size.',
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Flash 8B Latest',
+                modelName: 'gemini-1.5-flash-8b-latest',
+                modelDescription: 'Points to the most recent version of the compact 8B parameter model, providing latest improvements while maintaining a small footprint.',
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Flash 8B Exp',
+                modelName: 'gemini-1.5-flash-8b-exp-0924',
+                modelDescription: 'Experimental version of the 8B parameter model with new capabilities and optimizations being evaluated for future stable releases.',
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Flash 8B Exp',
+                modelName: 'gemini-1.5-flash-8b-exp-0827',
+                modelDescription: 'August experimental release of the efficient 8B parameter model with specific improvements to reasoning capabilities and response quality.',
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Pro Latest',
+                modelName: 'gemini-1.5-pro-latest',
+                modelDescription: 'Points to the most recent version of the flagship Gemini 1.5 Pro model, ensuring access to the latest capabilities and improvements.',
+                pricing: {
+                    prompt: computeUsage(`$7.00 / 1M tokens`),
+                    output: computeUsage(`$21.00 / 1M tokens`),
+                },
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Pro',
+                modelName: 'gemini-1.5-pro',
+                modelDescription: 'Flagship multimodal model with strong performance across text, code, vision, and audio tasks. 1M token context window with excellent reasoning capabilities.',
+                pricing: {
+                    prompt: computeUsage(`$6.00 / 1M tokens`),
+                    output: computeUsage(`$18.00 / 1M tokens`),
+                },
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Pro 001',
+                modelName: 'gemini-1.5-pro-001',
+                modelDescription: 'First stable release of Gemini 1.5 Pro with consistent performance characteristics and reliable behavior for production applications.',
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Pro 002',
+                modelName: 'gemini-1.5-pro-002',
+                modelDescription: 'Refined version of Gemini 1.5 Pro with improved instruction following, better multimodal understanding, and more consistent outputs.',
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.5 Pro Exp',
+                modelName: 'gemini-1.5-pro-exp-0827',
+                modelDescription: 'Experimental version of Gemini 1.5 Pro with new capabilities and optimizations being tested before wider release. May offer improved performance.',
+            },
+            {
+                modelVariant: 'CHAT',
+                modelTitle: 'Gemini 1.0 Pro',
+                modelName: 'gemini-1.0-pro',
+                modelDescription: 'Original Gemini series foundation model with solid multimodal capabilities. 32K context window with good performance on text, code, and basic vision tasks.',
+                pricing: {
+                    prompt: computeUsage(`$0.35 / 1M tokens`),
+                    output: computeUsage(`$1.05 / 1M tokens`),
+                },
+            },
+            // <- [🕕]
+        ],
+    });
+    /**
+     * 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
+     */
+
     /**
      * Execution Tools for calling Google Gemini API.
      *
@@ -1379,29 +1566,7 @@
             title: 'Google',
             description: 'Implementation of Google models',
             vercelProvider: googleGeminiVercelProvider,
-            availableModels: [
-                // TODO: [🕘] Maybe list models in same way as in other providers - in separate file with metadata
-                'gemini-2.5-pro-preview-03-25',
-                'gemini-2.0-flash',
-                'gemini-2.0-flash-lite',
-                'gemini-2.0-flash-thinking-exp-01-21',
-                'gemini-1.5-flash',
-                'gemini-1.5-flash-latest',
-                'gemini-1.5-flash-001',
-                'gemini-1.5-flash-002',
-                'gemini-1.5-flash-exp-0827',
-                'gemini-1.5-flash-8b',
-                'gemini-1.5-flash-8b-latest',
-                'gemini-1.5-flash-8b-exp-0924',
-                'gemini-1.5-flash-8b-exp-0827',
-                'gemini-1.5-pro-latest',
-                'gemini-1.5-pro',
-                'gemini-1.5-pro-001',
-                'gemini-1.5-pro-002',
-                'gemini-1.5-pro-exp-0827',
-                'gemini-1.0-pro',
-                // <- [🕕]
-            ].map((modelName) => ({ modelName, modelVariant: 'CHAT' })),
+            availableModels: GOOGLE_MODELS,
             ...options,
         });
     }, {
@@ -1436,7 +1601,8 @@
     }
 
     /**
-     * @@@
+     * Safely retrieves the global scope object (window in browser, global in Node.js)
+     * regardless of the JavaScript environment in which the code is running
      *
      * Note: `$` is used to indicate that this function is not a pure function - it access global scope
      *
@@ -1447,10 +1613,10 @@
     }
 
     /**
-     * @@@
+     * Normalizes a text string to SCREAMING_CASE (all uppercase with underscores).
      *
-     * @param text @@@
-     * @returns @@@
+     * @param text The text string to be converted to SCREAMING_CASE format.
+     * @returns The normalized text in SCREAMING_CASE format.
      * @example 'HELLO_WORLD'
      * @example 'I_LOVE_PROMPTBOOK'
      * @public exported from `@promptbook/utils`
@@ -1502,10 +1668,10 @@
      */
 
     /**
-     * @@@
+     * Normalizes a text string to snake_case format.
      *
-     * @param text @@@
-     * @returns @@@
+     * @param text The text string to be converted to snake_case format.
+     * @returns The normalized text in snake_case format.
      * @example 'hello_world'
      * @example 'i_love_promptbook'
      * @public exported from `@promptbook/utils`
@@ -1515,11 +1681,11 @@
     }
 
     /**
-     * Register is @@@
+     * Global registry for storing and managing registered entities of a given type.
      *
      * Note: `$` is used to indicate that this function is not a pure function - it accesses and adds variables in global scope.
      *
-     * @private internal utility, exported are only signleton instances of this class
+     * @private internal utility, exported are only singleton instances of this class
      */
     class $Register {
         constructor(registerName) {
@@ -1563,10 +1729,10 @@
     }
 
     /**
-     * @@@
+     * Register for LLM tools.
      *
      * Note: `$` is used to indicate that this interacts with the global scope
-     * @singleton Only one instance of each register is created per build, but thare can be more @@@
+     * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
      * @public exported from `@promptbook/core`
      */
     const $llmToolsRegister = new $Register('llm_execution_tools_constructors');
@@ -1590,6 +1756,7 @@
      */
 
     exports.BOOK_LANGUAGE_VERSION = BOOK_LANGUAGE_VERSION;
+    exports.GOOGLE_MODELS = GOOGLE_MODELS;
     exports.PROMPTBOOK_ENGINE_VERSION = PROMPTBOOK_ENGINE_VERSION;
     exports._GoogleRegistration = _GoogleRegistration;
     exports.createGoogleExecutionTools = createGoogleExecutionTools;