@promptbook/editable 0.92.0-8 → 0.92.0

package/esm/index.es.js

@@ -17,7 +17,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @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
@@ -27,7 +27,7 @@ const PROMPTBOOK_ENGINE_VERSION = '0.92.0-8';
  * 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
@@ -85,7 +85,7 @@ const DEFAULT_BOOK_OUTPUT_PARAMETER_NAME = 'result';
 const LOOP_LIMIT = 1000;
 // <- TODO: [🧜‍♂️]
 /**
- * @@@
+ * Default settings for parsing and generating CSV files in Promptbook.
  *
  * @public exported from `@promptbook/core`
  */
@@ -155,7 +155,7 @@ class UnexpectedError extends Error {
                     ${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)}
@@ -187,7 +187,7 @@ class ParseError extends Error {
 /**
  * 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
@@ -303,7 +303,7 @@ class NotYetImplementedError extends Error {
 /**
  * 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
  *
@@ -325,7 +325,7 @@ function isValidSemanticVersion(version) {
  *
  * @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
  *
@@ -718,7 +718,7 @@ class CsvFormatError extends AbstractFormatError {
 }
 
 /**
- * @@@
+ * Contains configuration options for parsing and generating CSV files, such as delimiters and quoting rules.
  *
  * @public exported from `@promptbook/core`
  */
@@ -727,11 +727,29 @@ const MANDATORY_CSV_SETTINGS = Object.freeze({
     // 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 = 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`
  */
@@ -755,7 +773,7 @@ function isValidCsvString(value) {
  * @public exported from `@promptbook/core`
  *                          <- TODO: [🏢] Export from package `@promptbook/csv`
  */
-const CsvFormatDefinition = {
+const CsvFormatParser = {
     formatName: 'CSV',
     aliases: ['SPREADSHEET', 'TABLE'],
     isValid(value, settings, schema) {
@@ -767,12 +785,12 @@ const CsvFormatDefinition = {
     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 = 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((block) => `
                                 CSV parsing error
@@ -787,23 +805,37 @@ const CsvFormatDefinition = {
                                 ${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(unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS }));
+                    }
+                }
                 return unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS });
             },
         },
         {
             subvalueName: 'CELL',
-            async mapValues(value, outputParameterName, settings, mapCallback) {
-                // TODO: [👨🏾‍🤝‍👨🏼] DRY csv parsing
-                const csv = 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((block) => `
                                 CSV parsing error
@@ -819,9 +851,9 @@ const CsvFormatDefinition = {
                             `));
                 }
                 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 unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS });
@@ -830,10 +862,10 @@ const CsvFormatDefinition = {
     ],
 };
 /**
- * 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
  */
 
@@ -841,7 +873,7 @@ const CsvFormatDefinition = {
  * 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`
  */
@@ -864,7 +896,7 @@ function isValidJsonString(value /* <- [👨‍⚖️] */) {
  *
  * @private still in development [🏢]
  */
-const JsonFormatDefinition = {
+const JsonFormatParser = {
     formatName: 'JSON',
     mimeType: 'application/json',
     isValid(value, settings, schema) {
@@ -876,28 +908,28 @@ const JsonFormatDefinition = {
     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';
@@ -906,19 +938,20 @@ const TextFormatDefinition = {
         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');
             },
         },
@@ -928,10 +961,10 @@ const TextFormatDefinition = {
 /**
  * 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
  */
 
@@ -939,7 +972,7 @@ const TextFormatDefinition = {
  * 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`
  */
@@ -964,7 +997,7 @@ function isValidXmlString(value) {
  *
  * @private still in development [🏢]
  */
-const XmlFormatDefinition = {
+const XmlFormatParser = {
     formatName: 'XML',
     mimeType: 'application/xml',
     isValid(value, settings, schema) {
@@ -976,17 +1009,17 @@ const XmlFormatDefinition = {
     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
  */
 
@@ -995,21 +1028,16 @@ const XmlFormatDefinition = {
  *
  * @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`
@@ -1241,8 +1269,12 @@ function checkSerializableAsJson(options) {
  */
 
 /**
- * @@@
+ * 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) {
@@ -1328,11 +1360,11 @@ const RESERVED_PARAMETER_NAMES = exportJson({
  */
 
 /**
- * @@@
+ * 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`
@@ -1624,10 +1656,10 @@ for (let i = 0; i < defaultDiacriticsRemovalMap.length; i++) {
 */
 
 /**
- * @@@
+ * 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) {
@@ -1659,9 +1691,9 @@ function removeEmojis(text) {
 /**
  * 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
  *
@@ -1673,18 +1705,19 @@ function removeQuotes(text) {
     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) {
@@ -1754,8 +1787,6 @@ function validateParameterName(parameterName) {
 /**
  * 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`
  */
@@ -1812,14 +1843,14 @@ const foreachCommandParser = {
                     `));
             // <- 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((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'))}
                     `));
@@ -1996,14 +2027,14 @@ const formatCommandParser = {
 };
 
 /**
- * @@@
+ * 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: [
@@ -2030,7 +2061,45 @@ const ChatbotFormfactorDefinition = {
 };
 
 /**
- * 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`
  */
@@ -2059,7 +2128,7 @@ const GeneratorFormfactorDefinition = {
 };
 
 /**
- * @@@
+ * Pipeline interface which is equivalent to `any`
  *
  * @see https://github.com/webgptorg/promptbook/discussions/171
  *
@@ -2074,13 +2143,13 @@ const GENERIC_PIPELINE_INTERFACE = {
  */
 
 /**
- * @@@
+ * 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,
 };
@@ -2115,17 +2184,20 @@ const ImageGeneratorFormfactorDefinition = {
 };
 
 /**
- * Matcher is form of app that @@@
+ * Matcher is form of app that evaluates (spreadsheet) content against defined criteria or patterns,
+ * determining if it matches or meets specific requirements. Used for classification,
+ * validation, filtering, and quality assessment of inputs.
  *
  * @public exported from `@promptbook/core`
  */
 const MatcherFormfactorDefinition = {
     name: 'EXPERIMENTAL_MATCHER',
-    description: `@@@`,
+    description: `An evaluation system that determines whether content meets specific criteria or patterns.
+    Used for content validation, quality assessment, and intelligent filtering tasks. Currently in experimental phase.`,
     documentationUrl: `https://github.com/webgptorg/promptbook/discussions/177`,
     pipelineInterface: {
         inputParameters: [
-            /* @@@ */
+            /* Input parameters for content to be matched and criteria to match against */
             {
                 name: 'nonce',
                 description: 'Just to prevent EXPERIMENTAL_MATCHER to be set as implicit formfactor',
@@ -2134,20 +2206,21 @@ const MatcherFormfactorDefinition = {
             },
         ],
         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: [
@@ -2170,13 +2243,16 @@ const SheetsFormfactorDefinition = {
 };
 
 /**
- * Translator is form of app that @@@
+ * Translator is form of app that transforms input text from one form to another,
+ * such as language translation, style conversion, tone modification, or other text transformations.
  *
  * @public exported from `@promptbook/core`
  */
 const TranslatorFormfactorDefinition = {
     name: 'TRANSLATOR',
-    description: `@@@`,
+    description: `A text transformation system that converts input content into different forms,
+    including language translations, paraphrasing, style conversions, and tone adjustments.
+    This form factor takes one input and produces one transformed output.`,
     documentationUrl: `https://github.com/webgptorg/promptbook/discussions/175`,
     pipelineInterface: {
         inputParameters: [
@@ -2213,6 +2289,8 @@ const FORMFACTOR_DEFINITIONS = [
     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
@@ -2221,7 +2299,7 @@ const FORMFACTOR_DEFINITIONS = [
 /**
  * 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`
@@ -2243,7 +2321,7 @@ const formfactorCommandParser = {
     /**
      * Description of the FORMFACTOR command
      */
-    description: `@@`,
+    description: `Specifies the application type and interface requirements that this promptbook should conform to`,
     /**
      * Link to documentation
      */
@@ -2438,7 +2516,7 @@ function isValidFilePath(filename) {
  * 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
  *
@@ -2464,10 +2542,10 @@ function isValidUrl(url) {
 }
 
 /**
- * @@@
+ * 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`
@@ -2630,8 +2708,7 @@ const knowledgeCommandParser = {
  */
 
 /**
- * @@@
- *
+ * @see {@link ModelVariant}
  * @public exported from `@promptbook/core`
  */
 const MODEL_VARIANTS = ['COMPLETION', 'CHAT', 'EMBEDDING' /* <- TODO [🏳] */ /* <- [🤖] */];
@@ -3063,10 +3140,10 @@ function $applyToTaskJson(command, $taskJson, $pipelineJson) {
 }
 
 /**
- * @@@
+ * 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) {
@@ -3315,7 +3392,7 @@ const sectionCommandParser = {
             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();
@@ -3383,7 +3460,7 @@ const sectionCommandParser = {
 /**
  * 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
  *
@@ -3785,7 +3862,7 @@ function parseCommand(raw, usagePlace) {
     //        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();
@@ -3804,7 +3881,10 @@ function parseCommand(raw, usagePlace) {
               `));
 }
 /**
- * @@@
+ * Generates a markdown-formatted message listing all supported commands
+ * with their descriptions and documentation links
+ *
+ * @returns A formatted markdown string containing all available commands and their details
  */
 function getSupportedCommandsMessage() {
     return COMMANDS.flatMap(({ name, aliasNames, description, documentationUrl }) => 
@@ -3815,7 +3895,10 @@ function getSupportedCommandsMessage() {
     ]).join('\n');
 }
 /**
- * @@@
+ * Attempts to parse a command variant using the provided input parameters
+ *
+ * @param input Object containing command parsing information including raw command text and normalized values
+ * @returns A parsed Command object if successful, or null if the command cannot be parsed
  */
 function parseCommandVariant(input) {
     const { commandNameRaw, usagePlace, normalized, args, raw, rawArgs } = input;
@@ -3917,7 +4000,8 @@ function removeMarkdownComments(content) {
 }
 
 /**
- * @@@
+ * 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`
  */
@@ -3938,7 +4022,10 @@ function isFlatPipeline(pipelineString) {
 }
 
 /**
- * @@@
+ * 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`
  */
@@ -3987,7 +4074,7 @@ function deflatePipeline(pipelineString) {
  */
 
 /**
- * @@@
+ * Adds a new command to a pipeline string in the correct format.
  *
  * @public exported from `@promptbook/editable`
  */
@@ -4200,7 +4287,7 @@ function stringifyPipelineJson(pipeline) {
     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