@promptbook/remote-client 0.92.0-8 → 0.92.0

package/umd/index.umd.js

@@ -23,7 +23,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-8';
+    const PROMPTBOOK_ENGINE_VERSION = '0.92.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
@@ -73,7 +73,7 @@
     }
 
     /**
-     * This error indicates that the pipeline collection cannot be propperly loaded
+     * This error indicates that the pipeline collection cannot be properly loaded
      *
      * @public exported from `@promptbook/core`
      */
@@ -150,7 +150,7 @@
             super(spaceTrim.spaceTrim((block) => `
                     ${block(message)}
 
-                    Note: You have probbably forgot to provide some tools for pipeline execution or preparation
+                    Note: You have probably forgot to provide some tools for pipeline execution or preparation
 
                 `));
             this.name = 'MissingToolsError';
@@ -236,7 +236,7 @@
             super(message);
             this.name = 'PipelineExecutionError';
             // TODO: [🐙] DRY - Maybe $randomId
-            this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid simmilar char conflicts   */)}`;
+            this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid similar char conflicts   */)}`;
             Object.setPrototypeOf(this, PipelineExecutionError.prototype);
         }
     }
@@ -287,7 +287,7 @@
      * Returns the same value that is passed as argument.
      * No side effects.
      *
-     * Note: It can be usefull for:
+     * Note: It can be useful for:
      *
      * 1) Leveling indentation
      * 2) Putting always-true or always-false conditions without getting eslint errors
@@ -364,7 +364,7 @@
     const CONNECTION_RETRIES_LIMIT = 5;
     // <- TODO: [🧜‍♂️]
     /**
-     * @@@
+     * Default settings for parsing and generating CSV files in Promptbook.
      *
      * @public exported from `@promptbook/core`
      */
@@ -434,7 +434,7 @@
                     ${block(message)}
 
                     Note: This error should not happen.
-                    It's probbably a bug in the pipeline collection
+                    It's probably a bug in the pipeline collection
 
                     Please report issue:
                     ${block(getErrorReportUrl(new Error(message)).href)}
@@ -559,7 +559,7 @@
      * Tests if given string is valid URL.
      *
      * Note: Dataurl are considered perfectly valid.
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `isValidUrl` which tests any URL
      * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
      *
@@ -996,10 +996,10 @@
     */
 
     /**
-     * @@@
+     * Removes diacritic marks (accents) from characters in a string.
      *
-     * @param input @@@
-     * @returns @@@
+     * @param input The string containing diacritics to be normalized.
+     * @returns The string with diacritics removed or normalized.
      * @public exported from `@promptbook/utils`
      */
     function removeDiacritics(input) {
@@ -1013,10 +1013,10 @@
      */
 
     /**
-     * @@@
+     * Converts a given text to kebab-case format.
      *
-     * @param text @@@
-     * @returns @@@
+     * @param text The text to be converted.
+     * @returns The kebab-case formatted string.
      * @example 'hello-world'
      * @example 'i-love-promptbook'
      * @public exported from `@promptbook/utils`
@@ -1302,7 +1302,7 @@
                 throw new ParseError(`Task section and example section must end with return statement -> {parameterName}`);
             };
             if ($taskJson.content === undefined) {
-                throw new UnexpectedError(`Content is missing in the taskJson - probbably commands are applied in wrong order`);
+                throw new UnexpectedError(`Content is missing in the taskJson - probably commands are applied in wrong order`);
             }
             if (command.taskType === 'EXAMPLE') {
                 expectResultingParameterName();
@@ -1370,7 +1370,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
@@ -1463,7 +1463,7 @@
     /**
      * Tests if given string is valid semantic version
      *
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `isValidSemanticVersion` which tests any semantic version
      * - `isValidPromptbookVersion` *(this one)* which tests just Promptbook versions
      *
@@ -1485,7 +1485,7 @@
      *
      * @see https://www.npmjs.com/package/promptbook?activeTab=versions
      * Note: When you are using for example promptbook 2.0.0 and there already is promptbook 3.0.0 it don`t know about it.
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `isValidSemanticVersion` which tests any semantic version
      * - `isValidPromptbookVersion` *(this one)* which tests just Promptbook versions
      *
@@ -1828,7 +1828,7 @@
     };
 
     /**
-     * @@@
+     * Contains configuration options for parsing and generating CSV files, such as delimiters and quoting rules.
      *
      * @public exported from `@promptbook/core`
      */
@@ -1837,11 +1837,29 @@
         // encoding: 'utf-8',
     });
 
+    /**
+     * Converts a CSV string into an object
+     *
+     * Note: This is wrapper around `papaparse.parse()` with better autohealing
+     *
+     * @private - for now until `@promptbook/csv` is released
+     */
+    function csvParse(value /* <- TODO: string_csv */, settings, schema /* <- TODO: Make CSV Schemas */) {
+        settings = { ...settings, ...MANDATORY_CSV_SETTINGS };
+        // Note: Autoheal invalid '\n' characters
+        if (settings.newline && !settings.newline.includes('\r') && value.includes('\r')) {
+            console.warn('CSV string contains carriage return characters, but in the CSV settings the `newline` setting does not include them. Autohealing the CSV string.');
+            value = value.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+        }
+        const csv = papaparse.parse(value, settings);
+        return csv;
+    }
+
     /**
      * 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
+     * @returns `true` if the string is a valid CSV string, false otherwise
      *
      * @public exported from `@promptbook/utils`
      */
@@ -1865,7 +1883,7 @@
      * @public exported from `@promptbook/core`
      *                          <- TODO: [🏢] Export from package `@promptbook/csv`
      */
-    const CsvFormatDefinition = {
+    const CsvFormatParser = {
         formatName: 'CSV',
         aliases: ['SPREADSHEET', 'TABLE'],
         isValid(value, settings, schema) {
@@ -1877,12 +1895,12 @@
         heal(value, settings, schema) {
             throw new Error('Not implemented');
         },
-        subvalueDefinitions: [
+        subvalueParsers: [
             {
                 subvalueName: 'ROW',
-                async mapValues(value, outputParameterName, settings, mapCallback) {
-                    // TODO: [👨🏾‍🤝‍👨🏼] DRY csv parsing
-                    const csv = papaparse.parse(value, { ...settings, ...MANDATORY_CSV_SETTINGS });
+                async mapValues(options) {
+                    const { value, outputParameterName, settings, mapCallback, onProgress } = options;
+                    const csv = csvParse(value, settings);
                     if (csv.errors.length !== 0) {
                         throw new CsvFormatError(spaceTrim__default["default"]((block) => `
                                 CSV parsing error
@@ -1897,23 +1915,37 @@
                                 ${block(value)}
                             `));
                     }
-                    const mappedData = await Promise.all(csv.data.map(async (row, index) => {
+                    const mappedData = [];
+                    const length = csv.data.length;
+                    for (let index = 0; index < length; index++) {
+                        const row = csv.data[index];
                         if (row[outputParameterName]) {
                             throw new CsvFormatError(`Can not overwrite existing column "${outputParameterName}" in CSV row`);
                         }
-                        return {
+                        const mappedRow = {
                             ...row,
-                            [outputParameterName]: await mapCallback(row, index),
+                            [outputParameterName]: await mapCallback(row, index, length),
                         };
-                    }));
+                        mappedData.push(mappedRow);
+                        if (onProgress) {
+                            // Note: Report the CSV with all rows mapped so far
+                            /*
+                            // TODO: [🛕] Report progress with all the rows including the pending ones
+                              const progressData = mappedData.map((row, i) =>
+                                i > index ? { ...row, [outputParameterName]: PENDING_VALUE_PLACEHOLDER } : row,
+                            );
+                            */
+                            await onProgress(papaparse.unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS }));
+                        }
+                    }
                     return papaparse.unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS });
                 },
             },
             {
                 subvalueName: 'CELL',
-                async mapValues(value, outputParameterName, settings, mapCallback) {
-                    // TODO: [👨🏾‍🤝‍👨🏼] DRY csv parsing
-                    const csv = papaparse.parse(value, { ...settings, ...MANDATORY_CSV_SETTINGS });
+                async mapValues(options) {
+                    const { value, settings, mapCallback, onProgress } = options;
+                    const csv = csvParse(value, settings);
                     if (csv.errors.length !== 0) {
                         throw new CsvFormatError(spaceTrim__default["default"]((block) => `
                                 CSV parsing error
@@ -1929,9 +1961,9 @@
                             `));
                     }
                     const mappedData = await Promise.all(csv.data.map(async (row, rowIndex) => {
-                        return /* not await */ Promise.all(Object.entries(row).map(async ([key, value], columnIndex) => {
+                        return /* not await */ Promise.all(Object.entries(row).map(async ([key, value], columnIndex, array) => {
                             const index = rowIndex * Object.keys(row).length + columnIndex;
-                            return /* not await */ mapCallback({ [key]: value }, index);
+                            return /* not await */ mapCallback({ [key]: value }, index, array.length);
                         }));
                     }));
                     return papaparse.unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS });
@@ -1940,10 +1972,10 @@
         ],
     };
     /**
-     * TODO: [🍓] In `CsvFormatDefinition` implement simple `isValid`
-     * TODO: [🍓] In `CsvFormatDefinition` implement partial `canBeValid`
-     * TODO: [🍓] In `CsvFormatDefinition` implement `heal
-     * TODO: [🍓] In `CsvFormatDefinition` implement `subvalueDefinitions`
+     * TODO: [🍓] In `CsvFormatParser` implement simple `isValid`
+     * TODO: [🍓] In `CsvFormatParser` implement partial `canBeValid`
+     * TODO: [🍓] In `CsvFormatParser` implement `heal
+     * TODO: [🍓] In `CsvFormatParser` implement `subvalueParsers`
      * TODO: [🏢] Allow to expect something inside CSV objects and other formats
      */
 
@@ -1951,7 +1983,7 @@
      * 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
+     * @returns `true` if the string is a valid JSON string, false otherwise
      *
      * @public exported from `@promptbook/utils`
      */
@@ -1974,7 +2006,7 @@
      *
      * @private still in development [🏢]
      */
-    const JsonFormatDefinition = {
+    const JsonFormatParser = {
         formatName: 'JSON',
         mimeType: 'application/json',
         isValid(value, settings, schema) {
@@ -1986,28 +2018,28 @@
         heal(value, settings, schema) {
             throw new Error('Not implemented');
         },
-        subvalueDefinitions: [],
+        subvalueParsers: [],
     };
     /**
-     * TODO: [🧠] Maybe propper instance of object
+     * TODO: [🧠] Maybe proper instance of object
      * TODO: [0] Make string_serialized_json
      * TODO: [1] Make type for JSON Settings and Schema
      * TODO: [🧠] What to use for validating JSONs - JSON Schema, ZoD, typescript types/interfaces,...?
-     * TODO: [🍓] In `JsonFormatDefinition` implement simple `isValid`
-     * TODO: [🍓] In `JsonFormatDefinition` implement partial `canBeValid`
-     * TODO: [🍓] In `JsonFormatDefinition` implement `heal
-     * TODO: [🍓] In `JsonFormatDefinition` implement `subvalueDefinitions`
+     * TODO: [🍓] In `JsonFormatParser` implement simple `isValid`
+     * TODO: [🍓] In `JsonFormatParser` implement partial `canBeValid`
+     * TODO: [🍓] In `JsonFormatParser` implement `heal
+     * TODO: [🍓] In `JsonFormatParser` implement `subvalueParsers`
      * TODO: [🏢] Allow to expect something inside JSON objects and other formats
      */
 
     /**
      * Definition for any text - this will be always valid
      *
-     * Note: This is not useful for validation, but for splitting and mapping with `subvalueDefinitions`
+     * Note: This is not useful for validation, but for splitting and mapping with `subvalueParsers`
      *
      * @public exported from `@promptbook/core`
      */
-    const TextFormatDefinition = {
+    const TextFormatParser = {
         formatName: 'TEXT',
         isValid(value) {
             return typeof value === 'string';
@@ -2016,19 +2048,20 @@
             return typeof partialValue === 'string';
         },
         heal() {
-            throw new UnexpectedError('It does not make sense to call `TextFormatDefinition.heal`');
+            throw new UnexpectedError('It does not make sense to call `TextFormatParser.heal`');
         },
-        subvalueDefinitions: [
+        subvalueParsers: [
             {
                 subvalueName: 'LINE',
-                async mapValues(value, outputParameterName, settings, mapCallback) {
+                async mapValues(options) {
+                    const { value, mapCallback, onProgress } = options;
                     const lines = value.split('\n');
-                    const mappedLines = await Promise.all(lines.map((lineContent, lineNumber) => 
+                    const mappedLines = await Promise.all(lines.map((lineContent, lineNumber, array) => 
                     // TODO: [🧠] Maybe option to skip empty line
                     /* not await */ mapCallback({
                         lineContent,
                         // TODO: [🧠] Maybe also put here `lineNumber`
-                    }, lineNumber)));
+                    }, lineNumber, array.length)));
                     return mappedLines.join('\n');
                 },
             },
@@ -2038,10 +2071,10 @@
     /**
      * TODO: [1] Make type for XML Text and Schema
      * TODO: [🧠][🤠] Here should be all words, characters, lines, paragraphs, pages available as subvalues
-     * TODO: [🍓] In `TextFormatDefinition` implement simple `isValid`
-     * TODO: [🍓] In `TextFormatDefinition` implement partial `canBeValid`
-     * TODO: [🍓] In `TextFormatDefinition` implement `heal
-     * TODO: [🍓] In `TextFormatDefinition` implement `subvalueDefinitions`
+     * TODO: [🍓] In `TextFormatParser` implement simple `isValid`
+     * TODO: [🍓] In `TextFormatParser` implement partial `canBeValid`
+     * TODO: [🍓] In `TextFormatParser` implement `heal
+     * TODO: [🍓] In `TextFormatParser` implement `subvalueParsers`
      * TODO: [🏢] Allow to expect something inside each item of list and other formats
      */
 
@@ -2049,7 +2082,7 @@
      * Function to check if a string is valid XML
      *
      * @param value
-     * @returns True if the string is a valid XML string, false otherwise
+     * @returns `true` if the string is a valid XML string, false otherwise
      *
      * @public exported from `@promptbook/utils`
      */
@@ -2074,7 +2107,7 @@
      *
      * @private still in development [🏢]
      */
-    const XmlFormatDefinition = {
+    const XmlFormatParser = {
         formatName: 'XML',
         mimeType: 'application/xml',
         isValid(value, settings, schema) {
@@ -2086,17 +2119,17 @@
         heal(value, settings, schema) {
             throw new Error('Not implemented');
         },
-        subvalueDefinitions: [],
+        subvalueParsers: [],
     };
     /**
-     * TODO: [🧠] Maybe propper instance of object
+     * TODO: [🧠] Maybe proper instance of object
      * TODO: [0] Make string_serialized_xml
      * TODO: [1] Make type for XML Settings and Schema
      * TODO: [🧠] What to use for validating XMLs - XSD,...
-     * TODO: [🍓] In `XmlFormatDefinition` implement simple `isValid`
-     * TODO: [🍓] In `XmlFormatDefinition` implement partial `canBeValid`
-     * TODO: [🍓] In `XmlFormatDefinition` implement `heal
-     * TODO: [🍓] In `XmlFormatDefinition` implement `subvalueDefinitions`
+     * TODO: [🍓] In `XmlFormatParser` implement simple `isValid`
+     * TODO: [🍓] In `XmlFormatParser` implement partial `canBeValid`
+     * TODO: [🍓] In `XmlFormatParser` implement `heal
+     * TODO: [🍓] In `XmlFormatParser` implement `subvalueParsers`
      * TODO: [🏢] Allow to expect something inside XML and other formats
      */
 
@@ -2105,21 +2138,16 @@
      *
      * @private internal index of `...` <- TODO [🏢]
      */
-    const FORMAT_DEFINITIONS = [
-        JsonFormatDefinition,
-        XmlFormatDefinition,
-        TextFormatDefinition,
-        CsvFormatDefinition,
-    ];
+    const FORMAT_DEFINITIONS = [JsonFormatParser, XmlFormatParser, TextFormatParser, CsvFormatParser];
     /**
      * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
     /**
-     * @@@
+     * Normalizes a text string to SCREAMING_CASE (all uppercase with underscores).
      *
-     * @param text @@@
-     * @returns @@@
+     * @param text The text string to be converted to SCREAMING_CASE format.
+     * @returns The normalized text in SCREAMING_CASE format.
      * @example 'HELLO_WORLD'
      * @example 'I_LOVE_PROMPTBOOK'
      * @public exported from `@promptbook/utils`
@@ -2351,8 +2379,12 @@
      */
 
     /**
-     * @@@
+     * Creates a deep clone of the given object
      *
+     * Note: This method only works for objects that are fully serializable to JSON and do not contain functions, Dates, or special types.
+     *
+     * @param objectValue The object to clone.
+     * @returns A deep, writable clone of the input object.
      * @public exported from `@promptbook/utils`
      */
     function deepClone(objectValue) {
@@ -2452,11 +2484,11 @@
      */
 
     /**
-     * @@@
+     * Normalizes a given text to camelCase format.
      *
-     * @param text @@@
-     * @param _isFirstLetterCapital @@@
-     * @returns @@@
+     * @param text The text to be normalized.
+     * @param _isFirstLetterCapital Whether the first letter should be capitalized.
+     * @returns The camelCase formatted string.
      * @example 'helloWorld'
      * @example 'iLovePromptbook'
      * @public exported from `@promptbook/utils`
@@ -2522,9 +2554,9 @@
     /**
      * Removes quotes from a string
      *
-     * Tip: This is very usefull for post-processing of the result of the LLM model
+     * Tip: This is very useful for post-processing of the result of the LLM model
      * Note: This function removes only the same quotes from the beginning and the end of the string
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `removeQuotes` which removes only bounding quotes
      * - `unwrapResult` which removes whole introduce sentence
      *
@@ -2536,18 +2568,19 @@
         if (text.startsWith('"') && text.endsWith('"')) {
             return text.slice(1, -1);
         }
-        if (text.startsWith('\'') && text.endsWith('\'')) {
+        if (text.startsWith("'") && text.endsWith("'")) {
             return text.slice(1, -1);
         }
         return text;
     }
 
     /**
-     * Function `validateParameterName` will @@@
+     * Function `validateParameterName` will normalize and validate a parameter name for use in pipelines.
+     * It removes diacritics, emojis, and quotes, normalizes to camelCase, and checks for reserved names and invalid characters.
      *
-     * @param parameterName @@@
-     * @returns @@@
-     * @throws {ParseError} @@@
+     * @param parameterName The parameter name to validate and normalize.
+     * @returns The validated and normalized parameter name.
+     * @throws {ParseError} If the parameter name is empty, reserved, or contains invalid characters.
      * @private within the repository
      */
     function validateParameterName(parameterName) {
@@ -2617,8 +2650,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`
      */
@@ -2675,14 +2706,14 @@
                     `));
                 // <- TODO: [🏢] List all supported format names
             }
-            const subvalueDefinition = formatDefinition.subvalueDefinitions.find((subvalueDefinition) => [subvalueDefinition.subvalueName, ...(subvalueDefinition.aliases || [])].includes(subformatName));
-            if (subvalueDefinition === undefined) {
+            const subvalueParser = formatDefinition.subvalueParsers.find((subvalueParser) => [subvalueParser.subvalueName, ...(subvalueParser.aliases || [])].includes(subformatName));
+            if (subvalueParser === undefined) {
                 throw new ParseError(spaceTrim__default["default"]((block) => `
                         Unsupported subformat name "${subformatName}" for format "${formatName}"
 
                         Available subformat names for format "${formatDefinition.formatName}":
-                        ${block(formatDefinition.subvalueDefinitions
-                .map((subvalueDefinition) => subvalueDefinition.subvalueName)
+                        ${block(formatDefinition.subvalueParsers
+                .map((subvalueParser) => subvalueParser.subvalueName)
                 .map((subvalueName) => `- ${subvalueName}`)
                 .join('\n'))}
                     `));
@@ -2859,14 +2890,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: [
@@ -2893,7 +2924,45 @@
     };
 
     /**
-     * Generator is form of app that @@@
+     * Completion is formfactor that emulates completion models
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const CompletionFormfactorDefinition = {
+        name: 'COMPLETION',
+        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"
+        pipelineInterface: {
+            inputParameters: [
+                {
+                    name: 'inputText',
+                    description: `Input text to be completed`,
+                    isInput: true,
+                    isOutput: false,
+                },
+                {
+                    name: 'instructions',
+                    description: `Additional instructions for the model, for example the required length, empty by default`,
+                    isInput: true,
+                    isOutput: false,
+                },
+            ],
+            outputParameters: [
+                {
+                    name: 'followingText',
+                    description: `Text that follows the input text`,
+                    isInput: false,
+                    isOutput: true,
+                },
+            ],
+        },
+    };
+
+    /**
+     * 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`
      */
@@ -2922,7 +2991,7 @@
     };
 
     /**
-     * @@@
+     * Pipeline interface which is equivalent to `any`
      *
      * @see https://github.com/webgptorg/promptbook/discussions/171
      *
@@ -2937,13 +3006,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,
     };
@@ -2978,17 +3047,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',
@@ -2997,20 +3069,21 @@
                 },
             ],
             outputParameters: [
-            /* @@@ */
+            /* Output parameters containing match results, confidence scores, and relevant metadata */
             ],
         },
     };
 
     /**
-     * Sheets is form of app that @@@
+     * Sheets is form of app that processes tabular data in CSV format, allowing transformation
+     * and analysis of structured data through AI-powered operations
      *
      * @public exported from `@promptbook/core`
      */
     const SheetsFormfactorDefinition = {
         name: 'SHEETS',
         aliasNames: ['SHEETS', 'SHEET'],
-        description: `@@@`,
+        description: `A formfactor for processing spreadsheet-like data in CSV format, enabling AI transformations on tabular data`,
         documentationUrl: `https://github.com/webgptorg/promptbook/discussions/176`,
         pipelineInterface: {
             inputParameters: [
@@ -3033,13 +3106,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: [
@@ -3076,6 +3152,8 @@
         MatcherFormfactorDefinition,
         GeneratorFormfactorDefinition,
         ImageGeneratorFormfactorDefinition,
+        CompletionFormfactorDefinition,
+        // <- [🛬] When making new formfactor, copy the _boilerplate and link it here
     ];
     /**
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -3084,7 +3162,7 @@
     /**
      * Parses the formfactor command
      *
-     * Note: @@@ This command is used as formfactor for new commands - it should NOT be used in any `.book` file
+     * Note: This command is used as a formfactor for new commands and defines the app type format - it should NOT be used in any `.book` file
      *
      * @see `documentationUrl` for more details
      * @public exported from `@promptbook/editable`
@@ -3106,7 +3184,7 @@
         /**
          * Description of the FORMFACTOR command
          */
-        description: `@@`,
+        description: `Specifies the application type and interface requirements that this promptbook should conform to`,
         /**
          * Link to documentation
          */
@@ -3249,8 +3327,7 @@
     };
 
     /**
-     * @@@
-     *
+     * @see {@link ModelVariant}
      * @public exported from `@promptbook/core`
      */
     const MODEL_VARIANTS = ['COMPLETION', 'CHAT', 'EMBEDDING' /* <- TODO [🏳] */ /* <- [🤖] */];
@@ -3682,10 +3759,10 @@
     }
 
     /**
-     * @@@
+     * Checks if the given value is a valid JavaScript identifier name.
      *
-     * @param javascriptName @@@
-     * @returns @@@
+     * @param javascriptName The value to check for JavaScript identifier validity.
+     * @returns `true` if the value is a valid JavaScript name, false otherwise.
      * @public exported from `@promptbook/utils`
      */
     function isValidJavascriptName(javascriptName) {
@@ -3776,7 +3853,7 @@
     /**
      * Tests if given string is valid pipeline URL URL.
      *
-     * Note: There are two simmilar functions:
+     * Note: There are two similar functions:
      * - `isValidUrl` which tests any URL
      * - `isValidPipelineUrl` *(this one)* which tests just pipeline URL
      *
@@ -4178,7 +4255,7 @@
         //        Arg1   Arg2   Arg3 | FOO
         {
             const commandNameRaw = items.slice(-1).join('_');
-            const args = items.slice(0, -1); // <- Note: This is probbably not correct
+            const args = items.slice(0, -1); // <- Note: This is probably not correct
             const rawArgs = raw
                 .substring(0, raw.length - commandNameRaw.length)
                 .trim();
@@ -4197,7 +4274,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 }) => 
@@ -4208,7 +4288,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;
@@ -4255,7 +4338,7 @@
     }
 
     /**
-     * @@@
+     * Extracts the interface (input and output parameters) from a pipeline.
      *
      * @deprecated https://github.com/webgptorg/promptbook/pull/186
      * @see https://github.com/webgptorg/promptbook/discussions/171
@@ -4288,7 +4371,7 @@
     }
 
     /**
-     * @@@
+     * Checks if two pipeline interfaces are structurally identical.
      *
      * @deprecated https://github.com/webgptorg/promptbook/pull/186
      * @see https://github.com/webgptorg/promptbook/discussions/171
@@ -4320,10 +4403,11 @@
     }
 
     /**
-     * @@@
+     * Checks if a given pipeline satisfies the requirements of a specified pipeline interface.
      *
      * @deprecated https://github.com/webgptorg/promptbook/pull/186
      * @see https://github.com/webgptorg/promptbook/discussions/171
+     * @returns `true` if the pipeline implements the interface, `false` otherwise.
      *
      * @public exported from `@promptbook/core`
      */
@@ -4553,7 +4637,8 @@
     }
 
     /**
-     * @@@
+     * Utility to determine if a pipeline string is in flat format.
+     * A flat pipeline is a simple text without proper structure (headers, blocks, etc).
      *
      * @public exported from `@promptbook/editable`
      */
@@ -4574,7 +4659,10 @@
     }
 
     /**
-     * @@@
+     * Converts a pipeline structure to its string representation.
+     *
+     * Transforms a flat, simple pipeline into a properly formatted pipeline string
+     * with sections for title, prompt, and return statement.
      *
      * @public exported from `@promptbook/editable`
      */
@@ -4631,7 +4719,7 @@
      * Note: It can not work with html syntax and comments
      *
      * @param markdown any valid markdown
-     * @returns @@@
+     * @returns An array of strings, each representing an individual list item found in the markdown
      * @public exported from `@promptbook/markdown-utils`
      */
     function extractAllListItemsFromMarkdown(markdown) {
@@ -4663,8 +4751,8 @@
     /**
      * Extracts all code blocks from markdown.
      *
-     * Note: There are multiple simmilar function:
-     * - `extractBlock` just extracts the content of the code block which is also used as build-in function for postprocessing
+     * Note: There are multiple similar functions:
+     * - `extractBlock` just extracts the content of the code block which is also used as built-in function for postprocessing
      * - `extractJsonBlock` extracts exactly one valid JSON code block
      * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
      * - `extractAllBlocksFromMarkdown` extracts all code blocks with language of the code block
@@ -4714,7 +4802,7 @@
                 if (currentCodeBlock.content !== '') {
                     currentCodeBlock.content += '\n';
                 }
-                currentCodeBlock.content += line.split('\\`\\`\\`').join('```') /* <- TODO: Maybe make propper unescape */;
+                currentCodeBlock.content += line.split('\\`\\`\\`').join('```') /* <- TODO: Maybe make proper unescape */;
             }
         }
         if (currentCodeBlock !== null) {
@@ -4731,8 +4819,8 @@
      *
      * - When there are multiple or no code blocks the function throws a `ParseError`
      *
-     * Note: There are multiple simmilar function:
-     * - `extractBlock` just extracts the content of the code block which is also used as build-in function for postprocessing
+     * Note: There are multiple similar functions:
+     * - `extractBlock` just extracts the content of the code block which is also used as built-in function for postprocessing
      * - `extractJsonBlock` extracts exactly one valid JSON code block
      * - `extractOneBlockFromMarkdown` extracts exactly one code block with language of the code block
      * - `extractAllBlocksFromMarkdown` extracts all code blocks with language of the code block
@@ -4884,11 +4972,11 @@
      */
 
     /**
-     * @@@
+     * Converts a title string into a normalized name.
      *
-     * @param value @@@
-     * @returns @@@
-     * @example @@@
+     * @param value The title string to be converted to a name.
+     * @returns A normalized name derived from the input title.
+     * @example 'Hello World!' -> 'hello-world'
      * @public exported from `@promptbook/utils`
      */
     function titleToName(value) {
@@ -5053,7 +5141,7 @@
      * Compile pipeline from string (markdown) format to JSON format synchronously
      *
      * Note: There are 3 similar functions:
-     * - `compilePipeline` **(preferred)** - which propperly compiles the promptbook and use embedding for external knowledge
+     * - `compilePipeline` **(preferred)** - which properly compiles the promptbook and uses embedding for external knowledge
      * - `parsePipeline` - use only if you need to compile promptbook synchronously and it contains NO external knowledge
      * - `preparePipeline` - just one step in the compilation process
      *
@@ -5490,7 +5578,7 @@
      * TODO: Use spaceTrim more effectively
      * TODO: [🧠] Parameter flags - isInput, isOutput, isInternal
      * TODO: [🥞] Not optimal parsing because `splitMarkdownIntoSections` is executed twice with same string, once through `flattenMarkdown` and second directly here
-     * TODO: [♈] Probbably move expectations from tasks to parameters
+     * TODO: [♈] Probably move expectations from tasks to parameters
      * TODO: [🛠] Actions, instruments (and maybe knowledge) => Functions and tools
      * TODO: [🍙] Make some standard order of json properties
      */
@@ -5535,10 +5623,10 @@
         }
         get title() {
             // TODO: [🧠] Maybe fetch title+description from the remote server (as well as if model methods are defined)
-            return 'Remote server';
+            return 'Promptbook remote server';
         }
         get description() {
-            return 'Use all models by your remote server';
+            return `Models from Promptbook remote server ${this.options.remoteServerUrl}`;
         }
         /**
          * Check the configuration of all execution tools
@@ -5553,7 +5641,7 @@
          * List all available models that can be used
          */
         async listModels() {
-            // TODO: [👒] Listing models (and checking configuration) probbably should go through REST API not Socket.io
+            // TODO: [👒] Listing models (and checking configuration) probably should go through REST API not Socket.io
             const socket = await createRemoteClient(this.options);
             socket.emit('listModels-request', {
                 identification: this.options.identification,