@promptbook/node 0.92.0-26 → 0.92.0-28

package/umd/index.umd.js

@@ -46,7 +46,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-26';
+    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-28';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -2550,7 +2550,7 @@
     }
 
     /**
-     * @@@
+     * Contains configuration options for parsing and generating CSV files, such as delimiters and quoting rules.
      *
      * @public exported from `@promptbook/core`
      */
@@ -3737,8 +3737,12 @@
      */
 
     /**
-     * @@@
+     * Executes a pipeline task with multiple attempts, including joker and retry logic. Handles different task types
+     * (prompt, script, dialog, etc.), applies postprocessing, checks expectations, and updates the execution report.
+     * Throws errors if execution fails after all attempts.
      *
+     * @param options - The options for execution, including task, parameters, pipeline, and configuration.
+     * @returns The result string of the executed task.
      * @private internal utility of `createPipelineExecutor`
      */
     async function executeAttempts(options) {
@@ -4196,8 +4200,12 @@
     }
 
     /**
-     * @@@
+     * Returns the context for a given task, typically used to provide additional information or variables
+     * required for the execution of the task within a pipeline. The context is returned as a string value
+     * that may include markdown formatting.
      *
+     * @param task - The task for which the context is being generated. This should be a deeply immutable TaskJson object.
+     * @returns The context as a string, formatted as markdown and parameter value.
      * @private internal utility of `createPipelineExecutor`
      */
     async function getContextForTask(task) {
@@ -4205,7 +4213,7 @@
     }
 
     /**
-     * @@@
+     * Retrieves example values or templates for a given task, used to guide or validate pipeline execution.
      *
      * @private internal utility of `createPipelineExecutor`
      */
@@ -4252,9 +4260,8 @@
     }
 
     /**
-     * @@@
-     *
-     * Here is the place where RAG (retrieval-augmented generation) happens
+     * Retrieves the most relevant knowledge pieces for a given task using embedding-based similarity search.
+     * This is where retrieval-augmented generation (RAG) is performed to enhance the task with external knowledge.
      *
      * @private internal utility of `createPipelineExecutor`
      */
@@ -4473,7 +4480,8 @@
      */
 
     /**
-     * @@@
+     * Filters and returns only the output parameters from the provided pipeline execution options.
+     * Adds warnings for any expected output parameters that are missing.
      *
      * @private internal utility of `createPipelineExecutor`
      */
@@ -6239,7 +6247,7 @@
     /**
      * 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
@@ -6777,8 +6785,6 @@
     /**
      * Parses the foreach command
      *
-     * Note: @@@ This command is used as foreach for new commands - it should NOT be used in any `.book` file
-     *
      * @see `documentationUrl` for more details
      * @public exported from `@promptbook/editable`
      */
@@ -7019,14 +7025,14 @@
     };
 
     /**
-     * @@@
+     * Chatbot form factor definition for conversational interfaces that interact with users in a chat-like manner.
      *
      * @public exported from `@promptbook/core`
      */
     const ChatbotFormfactorDefinition = {
         name: 'CHATBOT',
         aliasNames: ['CHAT'],
-        description: `@@@`,
+        description: `A chatbot form factor for conversational user interfaces.`,
         documentationUrl: `https://github.com/webgptorg/promptbook/discussions/174`,
         pipelineInterface: {
             inputParameters: [
@@ -7059,7 +7065,7 @@
      */
     const CompletionFormfactorDefinition = {
         name: 'COMPLETION',
-        description: `@@@`,
+        description: `Completion is formfactor that emulates completion models`,
         documentationUrl: `https://github.com/webgptorg/promptbook/discussions/@@`,
         //                                                                     <- TODO: https://github.com/webgptorg/promptbook/discussions/new?category=concepts
         //                                                                              "🔠 Completion Formfactor"
@@ -7090,7 +7096,8 @@
     };
 
     /**
-     * Generator is form of app that @@@
+     * Generator form factor represents an application that generates content or data based on user input or predefined rules.
+     * This form factor is used for apps that produce outputs, such as text, images, or other media, based on provided input.
      *
      * @public exported from `@promptbook/core`
      */
@@ -7134,13 +7141,13 @@
      */
 
     /**
-     * @@@
+     * A generic pipeline
      *
      * @public exported from `@promptbook/core`
      */
     const GenericFormfactorDefinition = {
         name: 'GENERIC',
-        description: `@@@`,
+        description: `A generic pipeline`,
         documentationUrl: `https://github.com/webgptorg/promptbook/discussions/173`,
         pipelineInterface: GENERIC_PIPELINE_INTERFACE,
     };
@@ -7175,17 +7182,20 @@
     };
 
     /**
-     * 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',
@@ -7194,7 +7204,7 @@
                 },
             ],
             outputParameters: [
-            /* @@@ */
+            /* Output parameters containing match results, confidence scores, and relevant metadata */
             ],
         },
     };
@@ -7231,13 +7241,16 @@
     };
 
     /**
-     * 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: [
@@ -8364,7 +8377,10 @@
               `));
     }
     /**
-     * @@@
+     * 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 }) => 
@@ -8375,7 +8391,10 @@
         ]).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;
@@ -9594,7 +9613,8 @@
      */
 
     /**
-     * @@@
+     * Attempts to locate the specified application on a Linux system using the 'which' command.
+     * Returns the path to the executable if found, or null otherwise.
      *
      * @private within the repository
      */
@@ -9661,7 +9681,8 @@
     // eslint-disable-next-line @typescript-eslint/no-var-requires
     const userhome = require('userhome');
     /**
-     * @@@
+     * Attempts to locate the specified application on a macOS system by checking standard application paths and using mdfind.
+     * Returns the path to the executable if found, or null otherwise.
      *
      * @private within the repository
      */
@@ -9693,7 +9714,8 @@
      */
 
     /**
-     * @@@
+     * Attempts to locate the specified application on a Windows system by searching common installation directories.
+     * Returns the path to the executable if found, or null otherwise.
      *
      * @private within the repository
      */
@@ -9764,7 +9786,8 @@
      */
 
     /**
-     * @@@
+     * Locates the LibreOffice executable on the current system by searching platform-specific paths.
+     * Returns the path to the executable if found, or null otherwise.
      *
      * @private within the repository
      */
@@ -9782,7 +9805,8 @@
      */
 
     /**
-     * @@@
+     * Locates the Pandoc executable on the current system by searching platform-specific paths.
+     * Returns the path to the executable if found, or null otherwise.
      *
      * @private within the repository
      */
@@ -9800,7 +9824,7 @@
      */
 
     /**
-     * @@@
+     * Provides paths to required executables (i.e. as Pandoc and LibreOffice) for Node.js environments.
      *
      * @public exported from `@promptbook/node`
      */
@@ -10079,11 +10103,16 @@
      */
 
     /**
-     * @@@
+     * 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 = {}) {
@@ -10122,7 +10151,11 @@
     /**
      * 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`
@@ -10130,11 +10163,14 @@
      */
 
     /**
-     * @@@
+     * 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:
@@ -10142,7 +10178,8 @@
      * - `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 = {}) {
@@ -10168,7 +10205,16 @@
         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