@promptbook/utils 0.101.0-2 → 0.101.0-3

package/README.md

@@ -48,9 +48,34 @@ npm i ptbk
 npm install @promptbook/utils
 ```
 
-Utility functions used in the library, but also useful for individual use in pre and post-processing of LLM inputs and outputs.
+Comprehensive utility functions for text processing, validation, normalization, and LLM input/output handling in the Promptbook ecosystem.
 
-Here is an overview of the functions that can be exported from the `@promptbook/utils` package and used in your own projects:
+## 🎯 Purpose and Motivation
+
+The utils package provides a rich collection of utility functions that are essential for working with LLM inputs and outputs. It handles common tasks like text normalization, parameter templating, validation, and postprocessing, eliminating the need to implement these utilities from scratch in every promptbook application.
+
+## 🔧 High-Level Functionality
+
+This package offers utilities across multiple domains:
+
+-   **Text Processing**: Counting, splitting, and analyzing text content
+-   **Template System**: Secure parameter substitution and prompt formatting
+-   **Normalization**: Converting text to various naming conventions and formats
+-   **Validation**: Comprehensive validation for URLs, emails, file paths, and more
+-   **Serialization**: JSON handling, deep cloning, and object manipulation
+-   **Environment Detection**: Runtime environment identification utilities
+-   **Format Parsing**: Support for CSV, JSON, XML validation and parsing
+
+## ✨ Key Features
+
+-   🔒 **Secure Templating** - Prompt injection protection with template functions
+-   📊 **Text Analysis** - Count words, sentences, paragraphs, pages, and characters
+-   🔄 **Case Conversion** - Support for kebab-case, camelCase, PascalCase, SCREAMING_CASE
+-   ✅ **Comprehensive Validation** - Email, URL, file path, UUID, and format validators
+-   🧹 **Text Cleaning** - Remove emojis, quotes, diacritics, and normalize whitespace
+-   📦 **Serialization Tools** - Deep cloning, JSON export, and serialization checking
+-   🌐 **Environment Aware** - Detect browser, Node.js, Jest, and Web Worker environments
+-   🎯 **LLM Optimized** - Functions specifically designed for LLM input/output processing
 
 ## Simple templating
 
@@ -184,133 +209,149 @@ import { unwrapResult } from '@promptbook/utils';
 unwrapResult('Best greeting for the user is "Hi Pavol!"'); // 'Hi Pavol!'
 ```
 
-## Misc
-
-## 📦 Complete List of Exported Entities
+## 📦 Exported Entities
 
 ### Version Information
-- `BOOK_LANGUAGE_VERSION` - Current book language version
-- `PROMPTBOOK_ENGINE_VERSION` - Current engine version
+
+-   `BOOK_LANGUAGE_VERSION` - Current book language version
+-   `PROMPTBOOK_ENGINE_VERSION` - Current engine version
 
 ### Configuration Constants
-- `VALUE_STRINGS` - Standard value strings
-- `SMALL_NUMBER` - Small number constant
+
+-   `VALUE_STRINGS` - Standard value strings
+-   `SMALL_NUMBER` - Small number constant
 
 ### Visualization
-- `renderPromptbookMermaid` - Render promptbook as Mermaid diagram
+
+-   `renderPromptbookMermaid` - Render promptbook as Mermaid diagram
 
 ### Error Handling
-- `deserializeError` - Deserialize error objects
-- `serializeError` - Serialize error objects
+
+-   `deserializeError` - Deserialize error objects
+-   `serializeError` - Serialize error objects
 
 ### Async Utilities
-- `forEachAsync` - Async forEach implementation
+
+-   `forEachAsync` - Async forEach implementation
 
 ### Format Validation
-- `isValidCsvString` - Validate CSV string format
-- `isValidJsonString` - Validate JSON string format
-- `jsonParse` - Safe JSON parsing
-- `isValidXmlString` - Validate XML string format
+
+-   `isValidCsvString` - Validate CSV string format
+-   `isValidJsonString` - Validate JSON string format
+-   `jsonParse` - Safe JSON parsing
+-   `isValidXmlString` - Validate XML string format
 
 ### Template Functions
-- `prompt` - Template tag for secure prompt formatting
-- `promptTemplate` - Alias for prompt template tag
+
+-   `prompt` - Template tag for secure prompt formatting
+-   `promptTemplate` - Alias for prompt template tag
 
 ### Environment Detection
-- `$getCurrentDate` - Get current date (side effect)
-- `$isRunningInBrowser` - Check if running in browser
-- `$isRunningInJest` - Check if running in Jest
-- `$isRunningInNode` - Check if running in Node.js
-- `$isRunningInWebWorker` - Check if running in Web Worker
+
+-   `$getCurrentDate` - Get current date (side effect)
+-   `$isRunningInBrowser` - Check if running in browser
+-   `$isRunningInJest` - Check if running in Jest
+-   `$isRunningInNode` - Check if running in Node.js
+-   `$isRunningInWebWorker` - Check if running in Web Worker
 
 ### Text Counting and Analysis
-- `CHARACTERS_PER_STANDARD_LINE` - Characters per standard line constant
-- `LINES_PER_STANDARD_PAGE` - Lines per standard page constant
-- `countCharacters` - Count characters in text
-- `countLines` - Count lines in text
-- `countPages` - Count pages in text
-- `countParagraphs` - Count paragraphs in text
-- `splitIntoSentences` - Split text into sentences
-- `countSentences` - Count sentences in text
-- `countWords` - Count words in text
-- `CountUtils` - Utility object with all counting functions
+
+-   `CHARACTERS_PER_STANDARD_LINE` - Characters per standard line constant
+-   `LINES_PER_STANDARD_PAGE` - Lines per standard page constant
+-   `countCharacters` - Count characters in text
+-   `countLines` - Count lines in text
+-   `countPages` - Count pages in text
+-   `countParagraphs` - Count paragraphs in text
+-   `splitIntoSentences` - Split text into sentences
+-   `countSentences` - Count sentences in text
+-   `countWords` - Count words in text
+-   `CountUtils` - Utility object with all counting functions
 
 ### Text Normalization
-- `capitalize` - Capitalize first letter
-- `decapitalize` - Decapitalize first letter
-- `DIACRITIC_VARIANTS_LETTERS` - Diacritic variants mapping
-- `string_keyword` - Keyword string type
-- `Keywords` - Keywords type
-- `isValidKeyword` - Validate keyword format
-- `nameToUriPart` - Convert name to URI part
-- `nameToUriParts` - Convert name to URI parts
-- `string_kebab_case` - Kebab case string type
-- `normalizeToKebabCase` - Convert to kebab-case
-- `string_camelCase` - Camel case string type
-- `normalizeTo_camelCase` - Convert to camelCase
-- `string_PascalCase` - Pascal case string type
-- `normalizeTo_PascalCase` - Convert to PascalCase
-- `string_SCREAMING_CASE` - Screaming case string type
-- `normalizeTo_SCREAMING_CASE` - Convert to SCREAMING_CASE
-- `normalizeTo_snake_case` - Convert to snake_case
-- `normalizeWhitespaces` - Normalize whitespace characters
-- `orderJson` - Order JSON object properties
-- `parseKeywords` - Parse keywords from input
-- `parseKeywordsFromString` - Parse keywords from string
-- `removeDiacritics` - Remove diacritic marks
-- `searchKeywords` - Search within keywords
-- `suffixUrl` - Add suffix to URL
-- `titleToName` - Convert title to name format
+
+-   `capitalize` - Capitalize first letter
+-   `decapitalize` - Decapitalize first letter
+-   `DIACRITIC_VARIANTS_LETTERS` - Diacritic variants mapping
+-   `string_keyword` - Keyword string type (type)
+-   `Keywords` - Keywords type (type)
+-   `isValidKeyword` - Validate keyword format
+-   `nameToUriPart` - Convert name to URI part
+-   `nameToUriParts` - Convert name to URI parts
+-   `string_kebab_case` - Kebab case string type (type)
+-   `normalizeToKebabCase` - Convert to kebab-case
+-   `string_camelCase` - Camel case string type (type)
+-   `normalizeTo_camelCase` - Convert to camelCase
+-   `string_PascalCase` - Pascal case string type (type)
+-   `normalizeTo_PascalCase` - Convert to PascalCase
+-   `string_SCREAMING_CASE` - Screaming case string type (type)
+-   `normalizeTo_SCREAMING_CASE` - Convert to SCREAMING_CASE
+-   `normalizeTo_snake_case` - Convert to snake_case
+-   `normalizeWhitespaces` - Normalize whitespace characters
+-   `orderJson` - Order JSON object properties
+-   `parseKeywords` - Parse keywords from input
+-   `parseKeywordsFromString` - Parse keywords from string
+-   `removeDiacritics` - Remove diacritic marks
+-   `searchKeywords` - Search within keywords
+-   `suffixUrl` - Add suffix to URL
+-   `titleToName` - Convert title to name format
 
 ### Text Organization
-- `spaceTrim` - Trim spaces while preserving structure
+
+-   `spaceTrim` - Trim spaces while preserving structure
 
 ### Parameter Processing
-- `extractParameterNames` - Extract parameter names from template
-- `numberToString` - Convert number to string
-- `templateParameters` - Replace template parameters
-- `valueToString` - Convert value to string
+
+-   `extractParameterNames` - Extract parameter names from template
+-   `numberToString` - Convert number to string
+-   `templateParameters` - Replace template parameters
+-   `valueToString` - Convert value to string
 
 ### Parsing Utilities
-- `parseNumber` - Parse number from string
+
+-   `parseNumber` - Parse number from string
 
 ### Text Processing
-- `removeEmojis` - Remove emoji characters
-- `removeQuotes` - Remove quote characters
+
+-   `removeEmojis` - Remove emoji characters
+-   `removeQuotes` - Remove quote characters
 
 ### Serialization
-- `$deepFreeze` - Deep freeze object (side effect)
-- `checkSerializableAsJson` - Check if serializable as JSON
-- `clonePipeline` - Clone pipeline object
-- `deepClone` - Deep clone object
-- `exportJson` - Export object as JSON
-- `isSerializableAsJson` - Check if object is JSON serializable
-- `jsonStringsToJsons` - Convert JSON strings to objects
+
+-   `$deepFreeze` - Deep freeze object (side effect)
+-   `checkSerializableAsJson` - Check if serializable as JSON
+-   `clonePipeline` - Clone pipeline object
+-   `deepClone` - Deep clone object
+-   `exportJson` - Export object as JSON
+-   `isSerializableAsJson` - Check if object is JSON serializable
+-   `jsonStringsToJsons` - Convert JSON strings to objects
 
 ### Set Operations
-- `difference` - Set difference operation
-- `intersection` - Set intersection operation
-- `union` - Set union operation
+
+-   `difference` - Set difference operation
+-   `intersection` - Set intersection operation
+-   `union` - Set union operation
 
 ### Code Processing
-- `trimCodeBlock` - Trim code block formatting
-- `trimEndOfCodeBlock` - Trim end of code block
-- `unwrapResult` - Extract result from wrapped output
+
+-   `trimCodeBlock` - Trim code block formatting
+-   `trimEndOfCodeBlock` - Trim end of code block
+-   `unwrapResult` - Extract result from wrapped output
 
 ### Validation
-- `isValidEmail` - Validate email address format
-- `isRootPath` - Check if path is root path
-- `isValidFilePath` - Validate file path format
-- `isValidJavascriptName` - Validate JavaScript identifier
-- `isValidPromptbookVersion` - Validate promptbook version
-- `isValidSemanticVersion` - Validate semantic version
-- `isHostnameOnPrivateNetwork` - Check if hostname is on private network
-- `isUrlOnPrivateNetwork` - Check if URL is on private network
-- `isValidPipelineUrl` - Validate pipeline URL format
-- `isValidUrl` - Validate URL format
-- `isValidUuid` - Validate UUID format
-
-See also the documentation for all the functions in the `@promptbook/utils` package, every function is documented by jsdoc, typed by typescript and tested by jest.
+
+-   `isValidEmail` - Validate email address format
+-   `isRootPath` - Check if path is root path
+-   `isValidFilePath` - Validate file path format
+-   `isValidJavascriptName` - Validate JavaScript identifier
+-   `isValidPromptbookVersion` - Validate promptbook version
+-   `isValidSemanticVersion` - Validate semantic version
+-   `isHostnameOnPrivateNetwork` - Check if hostname is on private network
+-   `isUrlOnPrivateNetwork` - Check if URL is on private network
+-   `isValidPipelineUrl` - Validate pipeline URL format
+-   `isValidUrl` - Validate URL format
+-   `isValidUuid` - Validate UUID format
+
+> 💡 This package provides utility functions for promptbook applications. For the core functionality, see [@promptbook/core](#-packages) or install all packages with `npm i ptbk`
 
 
 ---

package/esm/index.es.js

@@ -16,7 +16,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.101.0-2';
+const PROMPTBOOK_ENGINE_VERSION = '0.101.0-3';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name

package/esm/typings/src/book-components/Chat/Chat/ChatProps.d.ts

@@ -119,4 +119,24 @@ export type ChatProps = {
      * Keys should match ChatMessage.from values (e.g., 'USER', 'AGENT_{id}', etc.)
      */
     readonly participants?: ReadonlyArray<ChatParticipant>;
+    /**
+     * Optional callback for handling user feedback on messages
+     * When provided, star rating buttons (1-5 stars) will be displayed next to each message
+     *
+     * @param feedback - Object containing the feedback data
+     * @param feedback.message - The message being rated
+     * @param feedback.rating - Star rating from 1 to 5
+     * @param feedback.textRating - Optional text feedback/note from user
+     * @param feedback.chatThread - Complete chat thread as string
+     * @param feedback.expectedAnswer - Optional expected answer provided by user
+     * @param feedback.url - Current page URL where feedback was given
+     */
+    onFeedback?(feedback: {
+        message: ChatMessage;
+        rating: number;
+        textRating: string;
+        chatThread: string;
+        expectedAnswer: string | null;
+        url: string;
+    }): Promisable<void>;
 };

package/esm/typings/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.101.0-1`).
+ * It follows semantic versioning (e.g., `0.101.0-2`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/utils",
-    "version": "0.101.0-2",
+    "version": "0.101.0-3",
     "description": "Promptbook: Run AI apps in plain human language across multiple models and platforms",
     "private": false,
     "sideEffects": false,

package/umd/index.umd.js

@@ -22,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.101.0-2';
+    const PROMPTBOOK_ENGINE_VERSION = '0.101.0-3';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name