@promptbook/core 0.92.0-26 → 0.92.0-27

package/esm/index.es.js

@@ -27,7 +27,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
@@ -6497,7 +6497,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
@@ -7433,17 +7433,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',
@@ -7452,7 +7455,7 @@ const MatcherFormfactorDefinition = {
             },
         ],
         outputParameters: [
-        /* @@@ */
+        /* Output parameters containing match results, confidence scores, and relevant metadata */
         ],
     },
 };
@@ -7489,13 +7492,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: [
@@ -8622,7 +8628,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 }) => 
@@ -8633,7 +8642,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;
@@ -10494,11 +10506,16 @@ function $registeredLlmToolsMessage() {
  */
 
 /**
- * @@@
+ * 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 = {}) {
@@ -10537,7 +10554,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`
@@ -10675,20 +10696,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;
@@ -10711,7 +10746,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;