@promptbook/node 0.92.0-25 → 0.92.0-27

package/esm/index.es.js

@@ -30,7 +30,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.92.0-25';
+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
@@ -6223,7 +6223,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
@@ -7159,17 +7159,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',
@@ -7178,7 +7181,7 @@ const MatcherFormfactorDefinition = {
             },
         ],
         outputParameters: [
-        /* @@@ */
+        /* Output parameters containing match results, confidence scores, and relevant metadata */
         ],
     },
 };
@@ -7215,13 +7218,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: [
@@ -8348,7 +8354,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 }) => 
@@ -8359,7 +8368,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;
@@ -10063,11 +10075,16 @@ async function $provideLlmToolsConfigurationFromEnv() {
  */
 
 /**
- * @@@
+ * 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 = {}) {
@@ -10106,7 +10123,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`
@@ -10114,11 +10135,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:
@@ -10126,7 +10150,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 = {}) {
@@ -10152,7 +10177,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