@promptbook/editable 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
@@ -33,7 +33,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
@@ -91,7 +91,7 @@
     const LOOP_LIMIT = 1000;
     // <- TODO: [🧜‍♂️]
     /**
-     * @@@
+     * Default settings for parsing and generating CSV files in Promptbook.
      *
      * @public exported from `@promptbook/core`
      */
@@ -161,7 +161,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)}
@@ -193,7 +193,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
@@ -309,7 +309,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
      *
@@ -331,7 +331,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
      *
@@ -724,7 +724,7 @@
     }
 
     /**
-     * @@@
+     * Contains configuration options for parsing and generating CSV files, such as delimiters and quoting rules.
      *
      * @public exported from `@promptbook/core`
      */
@@ -733,11 +733,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`
      */
@@ -761,7 +779,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) {
@@ -773,12 +791,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
@@ -793,23 +811,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
@@ -825,9 +857,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 });
@@ -836,10 +868,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
      */
 
@@ -847,7 +879,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`
      */
@@ -870,7 +902,7 @@
      *
      * @private still in development [🏢]
      */
-    const JsonFormatDefinition = {
+    const JsonFormatParser = {
         formatName: 'JSON',
         mimeType: 'application/json',
         isValid(value, settings, schema) {
@@ -882,28 +914,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';
@@ -912,19 +944,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');
                 },
             },
@@ -934,10 +967,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
      */
 
@@ -945,7 +978,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`
      */
@@ -970,7 +1003,7 @@
      *
      * @private still in development [🏢]
      */
-    const XmlFormatDefinition = {
+    const XmlFormatParser = {
         formatName: 'XML',
         mimeType: 'application/xml',
         isValid(value, settings, schema) {
@@ -982,17 +1015,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
      */
 
@@ -1001,21 +1034,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`
@@ -1247,8 +1275,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) {
@@ -1334,11 +1366,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`
@@ -1630,10 +1662,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) {
@@ -1665,9 +1697,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
      *
@@ -1679,18 +1711,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) {
@@ -1760,8 +1793,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`
      */
@@ -1818,14 +1849,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'))}
                     `));
@@ -2002,14 +2033,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: [
@@ -2036,7 +2067,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`
      */
@@ -2065,7 +2134,7 @@
     };
 
     /**
-     * @@@
+     * Pipeline interface which is equivalent to `any`
      *
      * @see https://github.com/webgptorg/promptbook/discussions/171
      *
@@ -2080,13 +2149,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,
     };
@@ -2121,17 +2190,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',
@@ -2140,20 +2212,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: [
@@ -2176,13 +2249,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: [
@@ -2219,6 +2295,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
@@ -2227,7 +2305,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`
@@ -2249,7 +2327,7 @@
         /**
          * Description of the FORMFACTOR command
          */
-        description: `@@`,
+        description: `Specifies the application type and interface requirements that this promptbook should conform to`,
         /**
          * Link to documentation
          */
@@ -2444,7 +2522,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
      *
@@ -2470,10 +2548,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`
@@ -2636,8 +2714,7 @@
      */
 
     /**
-     * @@@
-     *
+     * @see {@link ModelVariant}
      * @public exported from `@promptbook/core`
      */
     const MODEL_VARIANTS = ['COMPLETION', 'CHAT', 'EMBEDDING' /* <- TODO [🏳] */ /* <- [🤖] */];
@@ -3069,10 +3146,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) {
@@ -3321,7 +3398,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();
@@ -3389,7 +3466,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
      *
@@ -3791,7 +3868,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();
@@ -3810,7 +3887,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 }) => 
@@ -3821,7 +3901,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;
@@ -3923,7 +4006,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`
      */
@@ -3944,7 +4028,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`
      */
@@ -3993,7 +4080,7 @@
      */
 
     /**
-     * @@@
+     * Adds a new command to a pipeline string in the correct format.
      *
      * @public exported from `@promptbook/editable`
      */
@@ -4206,7 +4293,7 @@
         return pipelineJsonStringified;
     }
     /**
-     * TODO: [🐝] Not Working propperly @see https://promptbook.studio/examples/mixed-knowledge.book
+     * TODO: [🐝] Not Working properly @see https://promptbook.studio/examples/mixed-knowledge.book
      * TODO: [🧠][0] Maybe rename to `stringifyPipelineJson`, `stringifyIndexedJson`,...
      * TODO: [🧠] Maybe more elegant solution than replacing via regex
      * TODO: [🍙] Make some standard order of json properties