@promptbook/node 0.89.0-8 → 0.89.0

package/umd/index.umd.js

@@ -46,7 +46,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.89.0-8';
+    const PROMPTBOOK_ENGINE_VERSION = '0.89.0';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -92,6 +92,7 @@
      * @public exported from `@promptbook/core`
      */
     const ADMIN_GITHUB_NAME = 'hejny';
+    //            <- TODO: [🐊] Pick the best claim
     /**
      * When the title is not provided, the default title is used
      *
@@ -136,6 +137,7 @@
         infinity: '(infinity; ∞)',
         negativeInfinity: '(negative infinity; -∞)',
         unserializable: '(unserializable value)',
+        circular: '(circular JSON)',
     };
     /**
      * Small number limit
@@ -175,7 +177,7 @@
      */
     const DEFAULT_MAX_EXECUTION_ATTEMPTS = 10; // <- TODO: [🤹‍♂️]
     // <- TODO: [🕝] Make also `BOOKS_DIRNAME_ALTERNATIVES`
-    // TODO: !!!!!! Just .promptbook dir, hardocode others
+    // TODO: Just `.promptbook` in config, hardcode subfolders like `download-cache` or `execution-cache`
     /**
      * Where to store the temporary downloads
      *
@@ -355,6 +357,54 @@
      * TODO: [🧠] Is there a way how to meaningfully test this utility
      */
 
+    /**
+     * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
+     *
+     * @public exported from `@promptbook/core`
+     */
+    class WrappedError extends Error {
+        constructor(whatWasThrown) {
+            const tag = `[🤮]`;
+            console.error(tag, whatWasThrown);
+            super(spaceTrim.spaceTrim(`
+                Non-Error object was thrown
+
+                Note: Look for ${tag} in the console for more details
+                Please report issue on ${ADMIN_EMAIL}
+            `));
+            this.name = 'WrappedError';
+            Object.setPrototypeOf(this, WrappedError.prototype);
+        }
+    }
+
+    /**
+     * Helper used in catch blocks to assert that the error is an instance of `Error`
+     *
+     * @param whatWasThrown Any object that was thrown
+     * @returns Nothing if the error is an instance of `Error`
+     * @throws `WrappedError` or `UnexpectedError` if the error is not standard
+     *
+     * @private within the repository
+     */
+    function assertsError(whatWasThrown) {
+        // Case 1: Handle error which was rethrown as `WrappedError`
+        if (whatWasThrown instanceof WrappedError) {
+            const wrappedError = whatWasThrown;
+            throw wrappedError;
+        }
+        // Case 2: Handle unexpected errors
+        if (whatWasThrown instanceof UnexpectedError) {
+            const unexpectedError = whatWasThrown;
+            throw unexpectedError;
+        }
+        // Case 3: Handle standard errors - keep them up to consumer
+        if (whatWasThrown instanceof Error) {
+            return;
+        }
+        // Case 4: Handle non-standard errors - wrap them into `WrappedError` and throw
+        throw new WrappedError(whatWasThrown);
+    }
+
     /**
      * Checks if the value is [🚉] serializable as JSON
      * If not, throws an UnexpectedError with a rich error message and tracking
@@ -446,9 +496,7 @@
                     JSON.stringify(value); // <- TODO: [0]
                 }
                 catch (error) {
-                    if (!(error instanceof Error)) {
-                        throw error;
-                    }
+                    assertsError(error);
                     throw new UnexpectedError(spaceTrim__default["default"]((block) => `
                             \`${name}\` is not serializable
 
@@ -1135,6 +1183,9 @@
     /**
      * Function isValidJsonString will tell you if the string is valid JSON or not
      *
+     * @param value The string to check
+     * @returns True if the string is a valid JSON string, false otherwise
+     *
      * @public exported from `@promptbook/utils`
      */
     function isValidJsonString(value /* <- [👨‍⚖️] */) {
@@ -1143,9 +1194,7 @@
             return true;
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             if (error.message.includes('Unexpected token')) {
                 return false;
             }
@@ -1677,7 +1726,7 @@
         }
     }
     /**
-     * TODO: !!!!!! Add id to all errors
+     * TODO: [🧠][🌂] Add id to all errors
      */
 
     /**
@@ -1814,6 +1863,19 @@
         }
     }
 
+    /**
+     * Error thrown when a fetch request fails
+     *
+     * @public exported from `@promptbook/core`
+     */
+    class PromptbookFetchError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = 'PromptbookFetchError';
+            Object.setPrototypeOf(this, PromptbookFetchError.prototype);
+        }
+    }
+
     /**
      * Index of all custom errors
      *
@@ -1834,7 +1896,10 @@
         PipelineExecutionError,
         PipelineLogicError,
         PipelineUrlError,
+        AuthenticationError,
+        PromptbookFetchError,
         UnexpectedError,
+        WrappedError,
         // TODO: [🪑]> VersionMismatchError,
     };
     /**
@@ -1851,7 +1916,6 @@
         TypeError,
         URIError,
         AggregateError,
-        AuthenticationError,
         /*
       Note: Not widely supported
       > InternalError,
@@ -1974,8 +2038,8 @@
                     updatedAt = new Date();
                     errors.push(...executionResult.errors);
                     warnings.push(...executionResult.warnings);
-                    // <- TODO: !!! Only unique errors and warnings should be added (or filtered)
-                    // TODO: [🧠] !!! errors, warning, isSuccessful  are redundant both in `ExecutionTask` and `ExecutionTask.currentValue`
+                    // <- TODO: [🌂] Only unique errors and warnings should be added (or filtered)
+                    // TODO: [🧠] !! errors, warning, isSuccessful  are redundant both in `ExecutionTask` and `ExecutionTask.currentValue`
                     //            Also maybe move `ExecutionTask.currentValue.usage` -> `ExecutionTask.usage`
                     //            And delete `ExecutionTask.currentValue.preparedPipeline`
                     assertsTaskSuccessful(executionResult);
@@ -1985,6 +2049,7 @@
                     partialResultSubject.next(executionResult);
                 }
                 catch (error) {
+                    assertsError(error);
                     status = 'ERROR';
                     errors.push(error);
                     partialResultSubject.error(error);
@@ -2130,13 +2195,19 @@
                 return value.toISOString();
             }
             else {
-                return JSON.stringify(value);
+                try {
+                    return JSON.stringify(value);
+                }
+                catch (error) {
+                    if (error instanceof TypeError && error.message.includes('circular structure')) {
+                        return VALUE_STRINGS.circular;
+                    }
+                    throw error;
+                }
             }
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             console.error(error);
             return VALUE_STRINGS.unserializable;
         }
@@ -2308,9 +2379,7 @@
                 }
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             throw new ParseError(spaceTrim.spaceTrim((block) => `
                     Can not extract variables from the script
                     ${block(error.stack || error.message)}
@@ -2429,6 +2498,28 @@
         // encoding: 'utf-8',
     });
 
+    /**
+     * Function to check if a string is valid CSV
+     *
+     * @param value The string to check
+     * @returns True if the string is a valid CSV string, false otherwise
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    function isValidCsvString(value) {
+        try {
+            // A simple check for CSV format: at least one comma and no invalid characters
+            if (value.includes(',') && /^[\w\s,"']+$/.test(value)) {
+                return true;
+            }
+            return false;
+        }
+        catch (error) {
+            assertsError(error);
+            return false;
+        }
+    }
+
     /**
      * Definition for CSV spreadsheet
      *
@@ -2439,7 +2530,7 @@
         formatName: 'CSV',
         aliases: ['SPREADSHEET', 'TABLE'],
         isValid(value, settings, schema) {
-            return true;
+            return isValidCsvString(value);
         },
         canBeValid(partialValue, settings, schema) {
             return true;
@@ -2593,6 +2684,30 @@
      * TODO: [🏢] Allow to expect something inside each item of list and other formats
      */
 
+    /**
+     * Function to check if a string is valid XML
+     *
+     * @param value
+     * @returns True if the string is a valid XML string, false otherwise
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    function isValidXmlString(value) {
+        try {
+            const parser = new DOMParser();
+            const parsedDocument = parser.parseFromString(value, 'application/xml');
+            const parserError = parsedDocument.getElementsByTagName('parsererror');
+            if (parserError.length > 0) {
+                return false;
+            }
+            return true;
+        }
+        catch (error) {
+            assertsError(error);
+            return false;
+        }
+    }
+
     /**
      * Definition for XML format
      *
@@ -2602,7 +2717,7 @@
         formatName: 'XML',
         mimeType: 'application/xml',
         isValid(value, settings, schema) {
-            return true;
+            return isValidXmlString(value);
         },
         canBeValid(partialValue, settings, schema) {
             return true;
@@ -2799,14 +2914,15 @@
                     }
                 }
                 catch (error) {
-                    if (!(error instanceof Error) || error instanceof UnexpectedError) {
+                    assertsError(error);
+                    if (error instanceof UnexpectedError) {
                         throw error;
                     }
                     errors.push({ llmExecutionTools, error });
                 }
             }
             if (errors.length === 1) {
-                throw errors[0];
+                throw errors[0].error;
             }
             else if (errors.length > 1) {
                 throw new PipelineExecutionError(
@@ -3663,9 +3779,7 @@
                                     break scripts;
                                 }
                                 catch (error) {
-                                    if (!(error instanceof Error)) {
-                                        throw error;
-                                    }
+                                    assertsError(error);
                                     if (error instanceof UnexpectedError) {
                                         throw error;
                                     }
@@ -3735,9 +3849,7 @@
                                 break scripts;
                             }
                             catch (error) {
-                                if (!(error instanceof Error)) {
-                                    throw error;
-                                }
+                                assertsError(error);
                                 if (error instanceof UnexpectedError) {
                                     throw error;
                                 }
@@ -4358,9 +4470,7 @@
             await Promise.all(resolving);
         }
         catch (error /* <- Note: [3] */) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             // Note: No need to rethrow UnexpectedError
             // if (error instanceof UnexpectedError) {
             // Note: Count usage, [🧠] Maybe put to separate function executionReportJsonToUsage + DRY [🤹‍♂️]
@@ -5063,17 +5173,22 @@
     /**
      * The built-in `fetch' function with a lightweight error handling wrapper as default fetch function used in Promptbook scrapers
      *
-     * @private as default `fetch` function used in Promptbook scrapers
+     * @public exported from `@promptbook/core`
      */
-    const scraperFetch = async (url, init) => {
+    const promptbookFetch = async (urlOrRequest, init) => {
         try {
-            return await fetch(url, init);
+            return await fetch(urlOrRequest, init);
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
+            assertsError(error);
+            let url;
+            if (typeof urlOrRequest === 'string') {
+                url = urlOrRequest;
             }
-            throw new KnowledgeScrapeError(spaceTrim__default["default"]((block) => `
+            else if (urlOrRequest instanceof Request) {
+                url = urlOrRequest.url;
+            }
+            throw new PromptbookFetchError(spaceTrim__default["default"]((block) => `
                     Can not fetch "${url}"
 
                     Fetch error:
@@ -5094,7 +5209,7 @@
     async function makeKnowledgeSourceHandler(knowledgeSource, tools, options) {
         // console.log('!! makeKnowledgeSourceHandler', knowledgeSource);
         var _a;
-        const { fetch = scraperFetch } = tools;
+        const { fetch = promptbookFetch } = tools;
         const { knowledgeSourceContent } = knowledgeSource;
         let { name } = knowledgeSource;
         const { rootDirname = null, 
@@ -5296,9 +5411,7 @@
                 knowledgePreparedUnflatten[index] = pieces;
             }
             catch (error) {
-                if (!(error instanceof Error)) {
-                    throw error;
-                }
+                assertsError(error);
                 console.warn(error);
                 // <- TODO: [🏮] Some standard way how to transform errors into warnings and how to handle non-critical fails during the tasks
             }
@@ -6096,6 +6209,8 @@
      */
 
     /**
+    import { WrappedError } from '../../errors/WrappedError';
+    import { assertsError } from '../../errors/assertsError';
      * Parses the expect command
      *
      * @see `documentationUrl` for more details
@@ -6187,9 +6302,7 @@
                 };
             }
             catch (error) {
-                if (!(error instanceof Error)) {
-                    throw error;
-                }
+                assertsError(error);
                 throw new ParseError(spaceTrim__default["default"]((block) => `
                             Invalid FORMAT command
                             ${block(error.message)}:
@@ -9170,9 +9283,7 @@
             return result.trim();
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             return null;
         }
     }
@@ -9250,9 +9361,7 @@
             return result.trim() + toExec;
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             return null;
         }
     }
@@ -9283,9 +9392,7 @@
             throw new Error(`Can not locate app ${appName} on Windows.`);
         }
         catch (error) {
-            if (!(error instanceof Error)) {
-                throw error;
-            }
+            assertsError(error);
             return null;
         }
     }
@@ -9574,21 +9681,15 @@
      */
 
     /**
-     * @@@
-     *
-     * @@@ .env
+     * Provides the path to the `.env` file
      *
-     * It looks for environment variables:
-     * - `process.env.OPENAI_API_KEY`
-     * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
-     * - ...
+     * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file
      *
-     * @returns @@@
-     * @public exported from `@promptbook/node`
+     * @private within the repository - for CLI utils
      */
-    async function $provideLlmToolsConfigurationFromEnv() {
+    async function $provideEnvFilename() {
         if (!$isRunningInNode()) {
-            throw new EnvironmentMismatchError('Function `$provideLlmToolsFromEnv` works only in Node.js environment');
+            throw new EnvironmentMismatchError('Function `$provideEnvFilename` works only in Node.js environment');
         }
         const envFilePatterns = [
             '.env',
@@ -9608,8 +9709,7 @@
                 const envFilename = path.join(rootDirname, pattern);
                 if (await isFileExisting(envFilename, $provideFilesystemForNode())) {
                     $setUsedEnvFilename(envFilename);
-                    dotenv__namespace.config({ path: envFilename });
-                    break up_to_root;
+                    return envFilename;
                 }
             }
             if (isRootPath(rootDirname)) {
@@ -9618,6 +9718,34 @@
             // Note: If the directory does not exist, try the parent directory
             rootDirname = path.join(rootDirname, '..');
         }
+        return null;
+    }
+    /**
+     * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+     */
+
+    /**
+     * @@@
+     *
+     * @@@ .env
+     * 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:
+     * - `process.env.OPENAI_API_KEY`
+     * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
+     * - ...
+     *
+     * @returns @@@
+     * @public exported from `@promptbook/node`
+     */
+    async function $provideLlmToolsConfigurationFromEnv() {
+        if (!$isRunningInNode()) {
+            throw new EnvironmentMismatchError('Function `$provideLlmToolsFromEnv` works only in Node.js environment');
+        }
+        const envFilepath = await $provideEnvFilename();
+        if (envFilepath !== null) {
+            dotenv__namespace.config({ path: envFilepath });
+        }
         const llmToolsConfiguration = $llmToolsMetadataRegister
             .list()
             .map((metadata) => metadata.createConfigurationFromEnv(process.env))
@@ -9625,15 +9753,8 @@
         return llmToolsConfiguration;
     }
     /**
-     * TODO: [🧠][🪁] Maybe do allow to do auto-install if package not registered and not found
-     * TODO: Add Azure OpenAI
-     * TODO: [🧠][🍛]
-     * 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
-     * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
-     * TODO: This should be maybe not under `_common` but under `utils`
-     * TODO: [🧠][⚛] Maybe pass env as argument
-     * TODO: [®] DRY Register logic */
+     */
 
     /**
      * @@@
@@ -9692,6 +9813,7 @@
      * Note: This function is not cached, every call creates new instance of `MultipleLlmExecutionTools`
      *
      * @@@ .env
+     * 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:
      * - `process.env.OPENAI_API_KEY`
@@ -10225,9 +10347,7 @@
                 }
             }
             catch (error) {
-                if (!(error instanceof Error)) {
-                    throw error;
-                }
+                assertsError(error);
                 if (error instanceof ReferenceError) {
                     const undefinedName = error.message.split(' ')[0];
                     /*
@@ -10502,9 +10622,7 @@
                     // ---
                 }
                 catch (error) {
-                    if (!(error instanceof Error)) {
-                        throw error;
-                    }
+                    assertsError(error);
                     // TODO: [7] DRY
                     const wrappedErrorMessage = spaceTrim__default["default"]((block) => `
                             ${error.name} in pipeline ${fileName.split('\\').join('/')}⁠:
@@ -10595,9 +10713,7 @@
                     }
                 }
                 catch (error) {
-                    if (!(error instanceof Error)) {
-                        throw error;
-                    }
+                    assertsError(error);
                     // TODO: [7] DRY
                     const wrappedErrorMessage = spaceTrim__default["default"]((block) => `
                             ${error.name} in pipeline ${fileName.split('\\').join('/')}⁠: