@promptbook/cli 0.92.0-26 → 0.92.0-27

package/esm/index.es.js

@@ -47,7 +47,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.92.0-26';
+const PROMPTBOOK_ENGINE_VERSION = '0.92.0-27';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -2663,6 +2663,23 @@ class RemoteLlmExecutionTools {
  * TODO: [🧠] Maybe remove `@promptbook/remote-client` and just use `@promptbook/core`
  */
 
+/**
+ * Parses the task and returns the list of all parameter names
+ *
+ * @param template the string template with parameters in {curly} braces
+ * @returns the list of parameter names
+ * @public exported from `@promptbook/utils`
+ */
+function extractParameterNames(template) {
+    const matches = template.matchAll(/{\w+}/g);
+    const parameterNames = new Set();
+    for (const match of matches) {
+        const parameterName = match[0].slice(1, -1);
+        parameterNames.add(parameterName);
+    }
+    return parameterNames;
+}
+
 /**
  * Stores data in memory (HEAP)
  *
@@ -2752,20 +2769,34 @@ function cacheLlmTools(llmTools, options = {}) {
     const callCommonModel = async (prompt) => {
         const { parameters, content, modelRequirements } = prompt;
         // <- Note: These are relevant things from the prompt that the cache key should depend on.
+        // TODO: Maybe some standalone function for normalization of content for cache
+        let normalizedContent = content;
+        normalizedContent = normalizedContent.replace(/\s+/g, ' ');
+        normalizedContent = normalizedContent.split('\r\n').join('\n');
+        normalizedContent = spaceTrim(normalizedContent);
+        // Note: Do not need to save everything in the cache, just the relevant parameters
+        const relevantParameterNames = extractParameterNames(content);
+        const relevantParameters = Object.fromEntries(Object.entries(parameters).filter(([key]) => relevantParameterNames.has(key)));
+        const keyHashBase = { relevantParameters, normalizedContent, modelRequirements };
         const key = titleToName(prompt.title.substring(0, MAX_FILENAME_LENGTH - 10) +
             '-' +
-            sha256(hexEncoder.parse(JSON.stringify({ parameters, content, modelRequirements }))).toString( /* hex */));
+            sha256(hexEncoder.parse(JSON.stringify(keyHashBase)))
+                .toString( /* hex */)
+                .substring(0, 10 - 1));
         const cacheItem = !isCacheReloaded ? await storage.getItem(key) : null;
         if (cacheItem) {
-            console.log('!!! Cache hit for key:', key);
+            console.log('!!! Cache hit for key:', { key, keyHashBase });
             return cacheItem.promptResult;
         }
         console.log('!!! Cache miss for key:', key, {
             prompt,
             'prompt.title': prompt.title,
             MAX_FILENAME_LENGTH,
+            keyHashBase,
             parameters,
+            relevantParameters,
             content,
+            normalizedContent,
             modelRequirements,
         });
         let promptResult;
@@ -2788,7 +2819,16 @@ function cacheLlmTools(llmTools, options = {}) {
         await storage.setItem(key, {
             date: $getCurrentDate(),
             promptbookVersion: PROMPTBOOK_ENGINE_VERSION,
-            prompt,
+            bookVersion: BOOK_LANGUAGE_VERSION,
+            prompt: {
+                ...prompt,
+                parameters: Object.entries(parameters).length === Object.entries(relevantParameters).length
+                    ? parameters
+                    : {
+                        ...relevantParameters,
+                        note: `<- Note: Only relevant parameters are stored in the cache`,
+                    },
+            },
             promptResult,
         });
         return promptResult;
@@ -3230,11 +3270,16 @@ function joinLlmExecutionTools(...llmExecutionTools) {
  */
 
 /**
- * @@@
+ * Creates LLM execution tools from provided configuration objects
+ *
+ * Instantiates and configures LLM tool instances for each configuration entry,
+ * combining them into a unified interface via MultipleLlmExecutionTools.
  *
  * Note: This function is not cached, every call creates new instance of `MultipleLlmExecutionTools`
  *
- * @returns @@@
+ * @param configuration Array of LLM tool configurations to instantiate
+ * @param options Additional options for configuring the LLM tools
+ * @returns A unified interface combining all successfully instantiated LLM tools
  * @public exported from `@promptbook/core`
  */
 function createLlmToolsFromConfiguration(configuration, options = {}) {
@@ -3273,7 +3318,11 @@ function createLlmToolsFromConfiguration(configuration, options = {}) {
 /**
  * TODO: [🎌] Together with `createLlmToolsFromConfiguration` + 'EXECUTION_TOOLS_CLASSES' gets to `@promptbook/core` ALL model providers, make this more efficient
  * TODO: [🧠][🎌] Dynamically install required providers
- * TODO: @@@ write discussion about this - wizzard
+ * TODO: We should implement an interactive configuration wizard that would:
+ *       1. Detect which LLM providers are available in the environment
+ *       2. Guide users through required configuration settings for each provider
+ *       3. Allow testing connections before completing setup
+ *       4. Generate appropriate configuration code for application integration
  * TODO: [🧠][🍛] Which name is better `createLlmToolsFromConfig` or `createLlmToolsFromConfiguration`?
  * TODO: [🧠] Is there some meaningfull way how to test this util
  * TODO: This should be maybe not under `_common` but under `utils`
@@ -3281,11 +3330,14 @@ function createLlmToolsFromConfiguration(configuration, options = {}) {
  */
 
 /**
- * @@@
+ * Automatically configures LLM tools from environment variables in Node.js
+ *
+ * This utility function detects available LLM providers based on environment variables
+ * and creates properly configured LLM execution tools for each detected provider.
  *
  * Note: This function is not cached, every call creates new instance of `MultipleLlmExecutionTools`
  *
- * @@@ .env
+ * Supports environment variables from .env files when dotenv is configured
  * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file
  *
  * It looks for environment variables:
@@ -3293,7 +3345,8 @@ function createLlmToolsFromConfiguration(configuration, options = {}) {
  * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
  * - ...
  *
- * @returns @@@
+ * @param options Configuration options for the LLM tools
+ * @returns A unified interface containing all detected and configured LLM tools
  * @public exported from `@promptbook/node`
  */
 async function $provideLlmToolsFromEnv(options = {}) {
@@ -3319,7 +3372,16 @@ async function $provideLlmToolsFromEnv(options = {}) {
     return createLlmToolsFromConfiguration(configuration, options);
 }
 /**
- * TODO: @@@ write `$provideLlmToolsFromEnv` vs `$provideLlmToolsConfigurationFromEnv` vs `createLlmToolsFromConfiguration`
+ * TODO: The architecture for LLM tools configuration consists of three key functions:
+ * 1. `$provideLlmToolsFromEnv` - High-level function that detects available providers from env vars and returns ready-to-use LLM tools
+ * 2. `$provideLlmToolsConfigurationFromEnv` - Middle layer that extracts configuration objects from environment variables
+ * 3. `createLlmToolsFromConfiguration` - Low-level function that instantiates LLM tools from explicit configuration
+ *
+ * This layered approach allows flexibility in how tools are configured:
+ * - Use $provideLlmToolsFromEnv for automatic detection and setup in Node.js environments
+ * - Use $provideLlmToolsConfigurationFromEnv to extract config objects for modification before instantiation
+ * - Use createLlmToolsFromConfiguration for explicit control over tool configurations
+ *
  * TODO: [🧠][🍛] Which name is better `$provideLlmToolsFromEnv` or `$provideLlmToolsFromEnvironment`?
  * TODO: [🧠] Is there some meaningfull way how to test this util
  * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
@@ -4787,23 +4849,6 @@ function taskParameterJsonToString(taskParameterJson) {
  * TODO: [🧠] Should be in generated .book.md file GENERATOR_WARNING
  */
 
-/**
- * Parses the task and returns the list of all parameter names
- *
- * @param template the string template with parameters in {curly} braces
- * @returns the list of parameter names
- * @public exported from `@promptbook/utils`
- */
-function extractParameterNames(template) {
-    const matches = template.matchAll(/{\w+}/g);
-    const parameterNames = new Set();
-    for (const match of matches) {
-        const parameterName = match[0].slice(1, -1);
-        parameterNames.add(parameterName);
-    }
-    return parameterNames;
-}
-
 /**
  * Unprepare just strips the preparation data of the pipeline
  *
@@ -8191,7 +8236,7 @@ const sectionCommandParser = {
 /**
  * Parses the boilerplate command
  *
- * Note: @@@ This command is used as boilerplate for new commands - it should NOT be used in any `.book` file
+ * Note: @@ This command is used as boilerplate for new commands - it should NOT be used in any `.book` file
  *
  * @see `documentationUrl` for more details
  * @private within the commands folder
@@ -9127,17 +9172,20 @@ const ImageGeneratorFormfactorDefinition = {
 };
 
 /**
- * Matcher is form of app that @@@
+ * Matcher is form of app that evaluates (spreadsheet) content against defined criteria or patterns,
+ * determining if it matches or meets specific requirements. Used for classification,
+ * validation, filtering, and quality assessment of inputs.
  *
  * @public exported from `@promptbook/core`
  */
 const MatcherFormfactorDefinition = {
     name: 'EXPERIMENTAL_MATCHER',
-    description: `@@@`,
+    description: `An evaluation system that determines whether content meets specific criteria or patterns.
+    Used for content validation, quality assessment, and intelligent filtering tasks. Currently in experimental phase.`,
     documentationUrl: `https://github.com/webgptorg/promptbook/discussions/177`,
     pipelineInterface: {
         inputParameters: [
-            /* @@@ */
+            /* Input parameters for content to be matched and criteria to match against */
             {
                 name: 'nonce',
                 description: 'Just to prevent EXPERIMENTAL_MATCHER to be set as implicit formfactor',
@@ -9146,7 +9194,7 @@ const MatcherFormfactorDefinition = {
             },
         ],
         outputParameters: [
-        /* @@@ */
+        /* Output parameters containing match results, confidence scores, and relevant metadata */
         ],
     },
 };
@@ -9183,13 +9231,16 @@ const SheetsFormfactorDefinition = {
 };
 
 /**
- * Translator is form of app that @@@
+ * Translator is form of app that transforms input text from one form to another,
+ * such as language translation, style conversion, tone modification, or other text transformations.
  *
  * @public exported from `@promptbook/core`
  */
 const TranslatorFormfactorDefinition = {
     name: 'TRANSLATOR',
-    description: `@@@`,
+    description: `A text transformation system that converts input content into different forms,
+    including language translations, paraphrasing, style conversions, and tone adjustments.
+    This form factor takes one input and produces one transformed output.`,
     documentationUrl: `https://github.com/webgptorg/promptbook/discussions/175`,
     pipelineInterface: {
         inputParameters: [
@@ -10316,7 +10367,10 @@ function parseCommand(raw, usagePlace) {
               `));
 }
 /**
- * @@@
+ * Generates a markdown-formatted message listing all supported commands
+ * with their descriptions and documentation links
+ *
+ * @returns A formatted markdown string containing all available commands and their details
  */
 function getSupportedCommandsMessage() {
     return COMMANDS.flatMap(({ name, aliasNames, description, documentationUrl }) => 
@@ -10327,7 +10381,10 @@ function getSupportedCommandsMessage() {
     ]).join('\n');
 }
 /**
- * @@@
+ * Attempts to parse a command variant using the provided input parameters
+ *
+ * @param input Object containing command parsing information including raw command text and normalized values
+ * @returns A parsed Command object if successful, or null if the command cannot be parsed
  */
 function parseCommandVariant(input) {
     const { commandNameRaw, usagePlace, normalized, args, raw, rawArgs } = input;
@@ -15089,14 +15146,18 @@ function computeUsageCounts(content) {
 /**
  * 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 };
 }
 
@@ -17003,10 +17064,14 @@ resultContent, rawResponse) {
     }
     const inputTokens = rawResponse.usage.prompt_tokens;
     const outputTokens = ((_b = rawResponse.usage) === null || _b === void 0 ? void 0 : _b.completion_tokens) || 0;
+    let isUncertain = false;
     let modelInfo = OPENAI_MODELS.find((model) => model.modelName === rawResponse.model);
     if (modelInfo === undefined) {
-        // Note: Model is not in the list of known models, maybe just a different version of the same model
-        modelInfo = OPENAI_MODELS.find((model) => model.modelName.startsWith(rawResponse.model || SALT_NONCE));
+        // Note: Model is not in the list of known models, fallback to the family of the models and mark price as uncertain
+        modelInfo = OPENAI_MODELS.find((model) => (rawResponse.model || SALT_NONCE).startsWith(model.modelName));
+        if (modelInfo !== undefined) {
+            isUncertain = true;
+        }
     }
     console.log('!!! computeOpenAiUsage', {
         inputTokens,
@@ -17022,7 +17087,7 @@ resultContent, rawResponse) {
         price = uncertainNumber();
     }
     else {
-        price = uncertainNumber(inputTokens * modelInfo.pricing.prompt + outputTokens * modelInfo.pricing.output);
+        price = uncertainNumber(inputTokens * modelInfo.pricing.prompt + outputTokens * modelInfo.pricing.output, isUncertain);
     }
     return {
         price,