\n ⚠ Warning: This is a pre-release version of the library. It is not yet ready for production use. Please look at latest stable release.\n\n\n## 📦 Package `@promptbook/utils`\n\n- Promptbooks are [divided into several](#-packages) packages, all are published from [single monorepo](https://github.com/webgptorg/promptbook).\n- This package `@promptbook/utils` is one part of the promptbook ecosystem.\n\nTo install this package, run:\n\n```bash\n# Install entire promptbook ecosystem\nnpm i ptbk\n\n# Install just this package to save space\nnpm install @promptbook/utils\n```\n\nComprehensive utility functions for text processing, validation, normalization, and LLM input/output handling in the Promptbook ecosystem.\n\n## 🎯 Purpose and Motivation\n\nThe 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.\n\n## 🔧 High-Level Functionality\n\nThis package offers utilities across multiple domains:\n\n- **Text Processing**: Counting, splitting, and analyzing text content\n- **Template System**: Secure parameter substitution and prompt formatting\n- **Normalization**: Converting text to various naming conventions and formats\n- **Validation**: Comprehensive validation for URLs, emails, file paths, and more\n- **Serialization**: JSON handling, deep cloning, and object manipulation\n- **Environment Detection**: Runtime environment identification utilities\n- **Format Parsing**: Support for CSV, JSON, XML validation and parsing\n\n## ✨ Key Features\n\n- 🔒 **Secure Templating** - Prompt injection protection with template functions\n- 📊 **Text Analysis** - Count words, sentences, paragraphs, pages, and characters\n- 🔄 **Case Conversion** - Support for kebab-case, camelCase, PascalCase, SCREAMING_CASE\n- ✅ **Comprehensive Validation** - Email, URL, file path, UUID, and format validators\n- 🧹 **Text Cleaning** - Remove emojis, quotes, diacritics, and normalize whitespace\n- 📦 **Serialization Tools** - Deep cloning, JSON export, and serialization checking\n- 🌐 **Environment Aware** - Detect browser, Node.js, Jest, and Web Worker environments\n- 🎯 **LLM Optimized** - Functions specifically designed for LLM input/output processing\n\n## Simple templating\n\nThe `prompt` template tag function helps format prompt strings for LLM interactions. It handles string interpolation and maintains consistent formatting for multiline strings and lists and also handles a security to avoid **prompt injection**.\n\n```typescript\nimport { prompt } from '@promptbook/utils';\n\nconst promptString = prompt`\n Correct the following sentence:\n\n > ${unsecureUserInput}\n`;\n```\n\nThe `prompt` name could be overloaded by multiple things in your code. If you want to use the `promptTemplate` which is alias for `prompt`:\n\n```typescript\nimport { promptTemplate } from '@promptbook/utils';\n\nconst promptString = promptTemplate`\n Correct the following sentence:\n\n > ${unsecureUserInput}\n`;\n```\n\n## Advanced templating\n\nThere is a function `templateParameters` which is used to replace the parameters in given template optimized to LLM prompt templates.\n\n```typescript\nimport { templateParameters } from '@promptbook/utils';\n\ntemplateParameters('Hello, {name}!', { name: 'world' }); // 'Hello, world!'\n```\n\nAnd also multiline templates with blockquotes\n\n```typescript\nimport { templateParameters, spaceTrim } from '@promptbook/utils';\n\ntemplateParameters(\n spaceTrim(`\n Hello, {name}!\n\n > {answer}\n `),\n {\n name: 'world',\n answer: spaceTrim(`\n I'm fine,\n thank you!\n\n And you?\n `),\n },\n);\n\n// Hello, world!\n//\n// > I'm fine,\n// > thank you!\n// >\n// > And you?\n```\n\n## Counting\n\nThese functions are useful to count stats about the input/output in human-like terms not tokens and bytes, you can use\n`countCharacters`, `countLines`, `countPages`, `countParagraphs`, `countSentences`, `countWords`\n\n```typescript\nimport { countWords } from '@promptbook/utils';\n\nconsole.log(countWords('Hello, world!')); // 2\n```\n\n## Splitting\n\nSplitting functions are similar to counting but they return the split parts of the input/output, you can use\n`splitIntoCharacters`, `splitIntoLines`, `splitIntoPages`, `splitIntoParagraphs`, `splitIntoSentences`, `splitIntoWords`\n\n```typescript\nimport { splitIntoWords } from '@promptbook/utils';\n\nconsole.log(splitIntoWords('Hello, world!')); // ['Hello', 'world']\n```\n\n## Normalization\n\nNormalization functions are used to put the string into a normalized form, you can use\n`kebab-case`\n`PascalCase`\n`SCREAMING_CASE`\n`snake_case`\n`kebab-case`\n\n```typescript\nimport { normalizeTo } from '@promptbook/utils';\n\nconsole.log(normalizeTo['kebab-case']('Hello, world!')); // 'hello-world'\n```\n\n- There are more normalization functions like `capitalize`, `decapitalize`, `removeDiacritics`,...\n- These can be also used as postprocessing functions in the `POSTPROCESS` command in promptbook\n\n## Postprocessing\n\nSometimes you need to postprocess the output of the LLM model, every postprocessing function that is available through `POSTPROCESS` command in promptbook is exported from `@promptbook/utils`. You can use:\n\n- `spaceTrim`\n- `extractAllBlocksFromMarkdown`, _<- Note: Exported from [`@promptbook/markdown-utils`](https://www.npmjs.com/package/@promptbook/markdown-utils)_\n- `extractAllListItemsFromMarkdown` _<- Note: Exported from [`@promptbook/markdown-utils`](https://www.npmjs.com/package/@promptbook/markdown-utils)_\n- `extractBlock`\n- `extractOneBlockFromMarkdown `_<- Note: Exported from [`@promptbook/markdown-utils`](https://www.npmjs.com/package/@promptbook/markdown-utils)_\n- `prettifyPipelineString`\n- `removeMarkdownComments`\n- `removeEmojis`\n- `removeMarkdownFormatting` _<- Note: Exported from [`@promptbook/markdown-utils`](https://www.npmjs.com/package/@promptbook/markdown-utils)_\n- `removeQuotes`\n- `trimCodeBlock`\n- `trimEndOfCodeBlock`\n- `unwrapResult`\n\nVery often you will use `unwrapResult`, which is used to extract the result you need from output with some additional information:\n\n```typescript\nimport { unwrapResult } from '@promptbook/utils';\n\nunwrapResult('Best greeting for the user is \"Hi Pavol!\"'); // 'Hi Pavol!'\n```\n\n## 📦 Exported Entities\n\n### Version Information\n\n- `BOOK_LANGUAGE_VERSION` - Current book language version\n- `PROMPTBOOK_ENGINE_VERSION` - Current engine version\n\n### Configuration Constants\n\n- `VALUE_STRINGS` - Standard value strings\n- `SMALL_NUMBER` - Small number constant\n\n### Visualization\n\n- `renderPromptbookMermaid` - Render promptbook as Mermaid diagram\n\n### Error Handling\n\n- `deserializeError` - Deserialize error objects\n- `serializeError` - Serialize error objects\n\n### Async Utilities\n\n- `forEachAsync` - Async forEach implementation\n\n### Format Validation\n\n- `isValidCsvString` - Validate CSV string format\n- `isValidJsonString` - Validate JSON string format\n- `jsonParse` - Safe JSON parsing\n- `isValidXmlString` - Validate XML string format\n\n### Template Functions\n\n- `prompt` - Template tag for secure prompt formatting\n- `promptTemplate` - Alias for prompt template tag\n\n### Environment Detection\n\n- `$getCurrentDate` - Get current date (side effect)\n- `$isRunningInBrowser` - Check if running in browser\n- `$isRunningInJest` - Check if running in Jest\n- `$isRunningInNode` - Check if running in Node.js\n- `$isRunningInWebWorker` - Check if running in Web Worker\n\n### Text Counting and Analysis\n\n- `CHARACTERS_PER_STANDARD_LINE` - Characters per standard line constant\n- `LINES_PER_STANDARD_PAGE` - Lines per standard page constant\n- `countCharacters` - Count characters in text\n- `countLines` - Count lines in text\n- `countPages` - Count pages in text\n- `countParagraphs` - Count paragraphs in text\n- `splitIntoSentences` - Split text into sentences\n- `countSentences` - Count sentences in text\n- `countWords` - Count words in text\n- `CountUtils` - Utility object with all counting functions\n\n### Text Normalization\n\n- `capitalize` - Capitalize first letter\n- `decapitalize` - Decapitalize first letter\n- `DIACRITIC_VARIANTS_LETTERS` - Diacritic variants mapping\n- `string_keyword` - Keyword string type (type)\n- `Keywords` - Keywords type (type)\n- `isValidKeyword` - Validate keyword format\n- `nameToUriPart` - Convert name to URI part\n- `nameToUriParts` - Convert name to URI parts\n- `string_kebab_case` - Kebab case string type (type)\n- `normalizeToKebabCase` - Convert to kebab-case\n- `string_camelCase` - Camel case string type (type)\n- `normalizeTo_camelCase` - Convert to camelCase\n- `string_PascalCase` - Pascal case string type (type)\n- `normalizeTo_PascalCase` - Convert to PascalCase\n- `string_SCREAMING_CASE` - Screaming case string type (type)\n- `normalizeTo_SCREAMING_CASE` - Convert to SCREAMING_CASE\n- `normalizeTo_snake_case` - Convert to snake_case\n- `normalizeWhitespaces` - Normalize whitespace characters\n- `orderJson` - Order JSON object properties\n- `parseKeywords` - Parse keywords from input\n- `parseKeywordsFromString` - Parse keywords from string\n- `removeDiacritics` - Remove diacritic marks\n- `searchKeywords` - Search within keywords\n- `suffixUrl` - Add suffix to URL\n- `titleToName` - Convert title to name format\n\n### Text Organization\n\n- `spaceTrim` - Trim spaces while preserving structure\n\n### Parameter Processing\n\n- `extractParameterNames` - Extract parameter names from template\n- `numberToString` - Convert number to string\n- `templateParameters` - Replace template parameters\n- `valueToString` - Convert value to string\n\n### Parsing Utilities\n\n- `parseNumber` - Parse number from string\n\n### Text Processing\n\n- `removeEmojis` - Remove emoji characters\n- `removeQuotes` - Remove quote characters\n\n### Serialization\n\n- `$deepFreeze` - Deep freeze object (side effect)\n- `checkSerializableAsJson` - Check if serializable as JSON\n- `clonePipeline` - Clone pipeline object\n- `deepClone` - Deep clone object\n- `exportJson` - Export object as JSON\n- `isSerializableAsJson` - Check if object is JSON serializable\n- `jsonStringsToJsons` - Convert JSON strings to objects\n\n### Set Operations\n\n- `difference` - Set difference operation\n- `intersection` - Set intersection operation\n- `union` - Set union operation\n\n### Code Processing\n\n- `trimCodeBlock` - Trim code block formatting\n- `trimEndOfCodeBlock` - Trim end of code block\n- `unwrapResult` - Extract result from wrapped output\n\n### Validation\n\n- `isValidEmail` - Validate email address format\n- `isRootPath` - Check if path is root path\n- `isValidFilePath` - Validate file path format\n- `isValidJavascriptName` - Validate JavaScript identifier\n- `isValidPromptbookVersion` - Validate promptbook version\n- `isValidSemanticVersion` - Validate semantic version\n- `isHostnameOnPrivateNetwork` - Check if hostname is on private network\n- `isUrlOnPrivateNetwork` - Check if URL is on private network\n- `isValidPipelineUrl` - Validate pipeline URL format\n- `isValidUrl` - Validate URL format\n- `isValidUuid` - Validate UUID format\n\n> 💡 This package provides utility functions for promptbook applications. For the core functionality, see [@promptbook/core](#-packages) or install all packages with `npm i ptbk`\n\n\n---\n\nRest of the documentation is common for **entire promptbook ecosystem**:\n\n\n\n\n## 📖 The Book Whitepaper\n\nPromptbook lets you create **persistent AI agents** that work on real goals for your company. The [**Agents Server**](https://gallery.ptbk.io/) is the heart of the project - a place where your AI agents live, remember context, collaborate in teams, and get things done.\n\nNowadays, the biggest challenge for most business applications isn't the raw capabilities of AI models. Large language models such as Claude Mythos, GPT-5.6 or Kimi K2.7 are incredibly capable.\n\nThe main challenge lies in **managing the context**, providing rules and knowledge, and narrowing the personality.\n\nIn Promptbook, you define your agents **using simple Books** - a human-readable language that is explicit, easy to understand and write, reliable, and highly portable. You then deploy them to the **Agents Server**, where they run persistently and work toward their goals.\n\n
| \n\n**Lawyer** \n \nGOAL You are a company lawyer. \nYour job is to provide legal advice and support to the company and its employees. \nRespond to incoming legal inquiries via email and keep the company website updated with the latest legal policies. \n \n**RULE** You are knowledgeable, professional, and detail-oriented. \n**KNOWLEDGE** https://company.com/company-policies.pdf \n**KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx \n \n \nTEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law. \n\n |
| \n\n**Paul Smith & Associés** \n \n**PERSONA** You are a company lawyer. \nYour job is to provide legal advice and support to the company and its employees. \n\n |
| \n\n**Company Lawyer** \n \nGOAL \nYour job is to provide legal advice and support to the company and its employees. \nGOAL Respond to incoming legal inquiries via email within 24 hours. \nGOAL Keep the company website updated with the latest legal policies and compliance information. \n\n |
| \n\n**Paul Smith & Associés** \n \n**PERSONA** You are a company lawyer. \nYour job is to provide legal advice and support to the company and its employees. \nGOAL Respond to incoming legal inquiries via email within 24 hours. \nGOAL Keep the company website updated with the latest legal policies and compliance information. \n**KNOWLEDGE** https://company.com/company-policies.pdf \n**KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx \n\n |
| \n\n**Paul Smith & Associés** \n \n**PERSONA** You are a company lawyer. \nYour job is to provide legal advice and support to the company and its employees. \nGOAL Respond to incoming legal inquiries via email within 24 hours. \nGOAL Keep the company website updated with the latest legal policies and compliance information. \n**RULE** Always ensure compliance with local laws and regulations. \n**RULE** Never provide legal advice outside your area of expertise. \n**RULE** Never provide legal advice about criminal law. \n**KNOWLEDGE** https://company.com/company-policies.pdf \n**KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx \n\n |
| \n\n**Paul Smith & Associés** \n \n**PERSONA** You are a company lawyer. \nYour job is to provide legal advice and support to the company and its employees. \nGOAL Respond to incoming legal inquiries via email within 24 hours. \nGOAL Keep the company website updated with the latest legal policies and compliance information. \n**RULE** Always ensure compliance with local laws and regulations. \n**RULE** Never provide legal advice outside your area of expertise. \n**RULE** Never provide legal advice about criminal law. \n**KNOWLEDGE** https://company.com/company-policies.pdf \n**KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx \n\n |
| \n\n**Paul Smith & Associés** \n \n**PERSONA** You are a company lawyer. \nYour job is to provide legal advice and support to the company and its employees. \nGOAL Respond to incoming legal inquiries via email within 24 hours. \nGOAL Keep the company website updated with the latest legal policies and compliance information. \n**RULE** Always ensure compliance with local laws and regulations. \n**RULE** Never provide legal advice outside your area of expertise. \n**RULE** Never provide legal advice about criminal law. \n**KNOWLEDGE** https://company.com/company-policies.pdf \n**KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx \nTEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law. \n\n |
| Project | \nAbout | \n
|---|---|
| ⭐ Agents Server | \n\n The primary way to use Promptbook. A production-ready platform where your AI agents live - create, manage, deploy, and interact with persistent agents that work on goals. Available as a hosted service or self-hosted via Docker.\n | \n
| Book language | \n\n Human-friendly, high-level language that abstracts away low-level details of AI. It allows to focus on personality, behavior, knowledge, and rules of AI agents rather than on models, parameters, and prompt engineering.\n \n There is also a plugin for VSCode to support .book file extension\n | \n
| Promptbook Engine | \n\n The open-source core that powers the Agents Server. Can also be used as a standalone TypeScript/JavaScript library to embed agent capabilities into your own applications.\n Released as multiple NPM packages.\n | \n
| Platform | \nDescription | \n
|---|---|
| 💬 Discord | \nJoin our active developer community for discussions and support | \n
| 🗣️ GitHub Discussions | \nTechnical discussions, feature requests, and community Q&A | \n
| Professional updates and industry insights | \n|
| General announcements and community engagement | \n|
| 🔗 ptbk.io | \nOfficial landing page with project information | \n
| 📸 Instagram @promptbook.studio | \nVisual updates, UI showcases, and design inspiration | \n
| Data & Knowledge Management | \nPipeline Control | \n
|---|---|
\n
| \n \n
| \n
| Language & Output Control | \nAdvanced Generation | \n
\n
| \n \n
| \n