@promptbook/azure-openai 0.92.0-9 → 0.93.0

package/README.md

@@ -1,6 +1,8 @@
 <!-- ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten -->
 
-# ✨ Promptbook
+# ✨ Promptbook: AI apps in plain Language
+
+Write AI applications using plain human language across multiple models and platforms.
 
 
 
@@ -8,24 +10,20 @@
 [![NPM Version of ![Promptbook logo - cube with letters P and B](./design/logo-h1.png) Promptbook](https://badge.fury.io/js/promptbook.svg)](https://www.npmjs.com/package/promptbook)
 [![Quality of package ![Promptbook logo - cube with letters P and B](./design/logo-h1.png) Promptbook](https://packagequality.com/shield/promptbook.svg)](https://packagequality.com/#?package=promptbook)
 [![Known Vulnerabilities](https://snyk.io/test/github/webgptorg/promptbook/badge.svg)](https://snyk.io/test/github/webgptorg/promptbook)
+[![Build Status](https://github.com/webgptorg/promptbook/actions/workflows/ci.yml/badge.svg)](https://github.com/webgptorg/promptbook/actions)
+[![Coverage Status](https://coveralls.io/repos/github/webgptorg/promptbook/badge.svg?branch=main)](https://coveralls.io/github/webgptorg/promptbook?branch=main)
 [![Issues](https://img.shields.io/github/issues/webgptorg/promptbook.svg?style=flat)](https://github.com/webgptorg/promptbook/issues)
 
 
 
-
-
 ## 🌟 New Features
 
--   📂 We have plugin for [VSCode](https://github.com/webgptorg/book-extension) to support `.book` file extension
--   🐳 Available [Docker image](https://hub.docker.com/r/hejny/promptbook/)
--   💫 Support of [`o3-mini` model by OpenAI](https://openai.com/index/openai-o3-mini/)
--   🐋 **Support of [DeepSeek models](https://www.npmjs.com/package/@promptbook/deepseek)**
-
+-   💡 VS Code support for `.book` files with syntax highlighting and IntelliSense
+-   🐳 Official Docker image (`hejny/promptbook`) for seamless containerized usage
+-   🔥 Native support for OpenAI `o3-mini`, GPT-4 and other leading LLMs
+-   🔍 DeepSeek integration for advanced knowledge search
 
 
-<blockquote style="color: #ff8811">
-    <b>⚠ Warning:</b> This is a pre-release version of the library. It is not yet ready for production use. Please look at <a href="https://www.npmjs.com/package/@promptbook/core?activeTab=versions">latest stable release</a>.
-</blockquote>
 
 ## 📦 Package `@promptbook/azure-openai`
 
@@ -328,65 +326,92 @@ Hello world examples:
 -   [Hello world in Node.js](https://github.com/webgptorg/hello-world-node-js)
 -   [Hello world in Next.js](https://github.com/webgptorg/hello-world-next-js)
 
+### 🌐 Community & Social Media
 
+Join our growing community of developers and users:
 
-We also have a community of developers and users of **Promptbook**:
-
--   [Discord community](https://discord.gg/x3QWNaa89N)
--   [Landing page `ptbk.io`](https://ptbk.io)
--   [Github discussions](https://github.com/webgptorg/promptbook/discussions)
--   [LinkedIn `Promptbook`](https://linkedin.com/company/promptbook)
--   [Facebook `Promptbook`](https://www.facebook.com/61560776453536) 
-
-And **Promptbook.studio** branded socials:
-
-
-
--   [Instagram `@promptbook.studio`](https://www.instagram.com/promptbook.studio/)
-
-And **Promptujeme** sub-brand:
-
-_/Subbrand for Czech clients/_
-
-
+<table>
+  <thead>
+    <tr>
+      <th>Platform</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><a href="https://discord.gg/x3QWNaa89N">💬 Discord</a></td>
+      <td>Join our active developer community for discussions and support</td>
+    </tr>
+    <tr>
+      <td><a href="https://github.com/webgptorg/promptbook/discussions">🗣️ GitHub Discussions</a></td>
+      <td>Technical discussions, feature requests, and community Q&A</td>
+    </tr>
+    <tr>
+      <td><a href="https://linkedin.com/company/promptbook">👔 LinkedIn</a></td>
+      <td>Professional updates and industry insights</td>
+    </tr>
+    <tr>
+      <td><a href="https://www.facebook.com/61560776453536">📱 Facebook</a></td>
+      <td>General announcements and community engagement</td>
+    </tr>
+    <tr>
+      <td><a href="https://ptbk.io">🔗 ptbk.io</a></td>
+      <td>Official landing page with project information</td>
+    </tr>
+  </tbody>
+</table>
 
+### 🖼️ Product & Brand Channels
 
--   [Promptujeme.cz](https://www.promptujeme.cz/)
--   [Facebook `Promptujeme`](https://www.facebook.com/promptujeme/)
+#### Promptbook.studio
 
-And **Promptbook.city** branded socials:
+<table>
+  <tbody>
+    <tr>
+      <td><a href="https://www.instagram.com/promptbook.studio/">📸 Instagram @promptbook.studio</a></td>
+      <td>Visual updates, UI showcases, and design inspiration</td>
+    </tr>
+    
+  </tbody>
+</table>
 
-_/Sub-brand for images and graphics generated via Promptbook prompting/_
 
--   [Instagram `@promptbook.city`](https://www.instagram.com/promptbook.city/)
--   [Facebook `Promptbook City`](https://www.facebook.com/61565718625569)
 
 
 
 
+## 📘 Book Language Blueprint
 
+_A concise, Markdown-based DSL for crafting AI workflows and automations._
 
-## 💙 The Book language
+---
 
+### 📑 Table of Contents
 
+-   [Introduction](#introduction)
+-   [Example](#example)
+-   [1. What: Workflows, Tasks & Parameters](#1-what-workflows-tasks--parameters)
+-   [2. Who: Personas](#2-who-personas)
+-   [3. How: Knowledge, Instruments & Actions](#3-how-knowledge-instruments-and-actions)
+-   [General Principles](#general-principles)
 
-Following is the documentation and blueprint of the [Book language](https://github.com/webgptorg/book).
+### Introduction
 
-Book is a language that can be used to write AI applications, agents, workflows, automations, knowledgebases, translators, sheet processors, email automations and more. It allows you to harness the power of AI models in human-like terms, without the need to know the specifics and technicalities of the models.
+Book is a Markdown-based language that simplifies the creation of AI applications, workflows, and automations. With human-readable commands, you can define inputs, outputs, personas, knowledge sources, and actions—without needing model-specific details.
 
 ### Example
 
-```markdown
-# 🌟 My first Book
+```book
+# 🌟 My First Book
 
 -   BOOK VERSION 1.0.0
 -   URL https://promptbook.studio/hello.book
 -   INPUT PARAMETER {topic}
 -   OUTPUT PARAMETER {article}
 
-# Write an article
+# Write an Article
 
--   PERSONA Jane, marketing specialist with prior experience in writing articles about technology and artificial intelligence
+-   PERSONA Jane, marketing specialist with prior experience in tech and AI writing
 -   KNOWLEDGE https://wikipedia.org/
 -   KNOWLEDGE ./journalist-ethics.pdf
 -   EXPECT MIN 1 Sentence
@@ -394,20 +419,20 @@ Book is a language that can be used to write AI applications, agents, workflows,
 
 > Write an article about {topic}
 
--> {article}
+→ {article}
 ```
 
 Each part of the book defines one of 3 circles:
 
-### **What:** Workflows, Tasks and Parameters
+### **1. What:** Workflows, Tasks and Parameters
 
-What work needs to be done. Each book defines a [workflow *(scenario or pipeline)*](https://github.com/webgptorg/promptbook/discussions/88), which is one or more tasks. Each workflow has a fixed input and output. For example, you have a book that generates an article from a topic. Once it generates an article about AI, once about marketing, once about cooking. The workflow (= your AI program) is the same, only the input and output change.
+What work needs to be done. Each book defines a [workflow _(scenario or pipeline)_](https://github.com/webgptorg/promptbook/discussions/88), which is one or more tasks. Each workflow has a fixed input and output. For example, you have a book that generates an article from a topic. Once it generates an article about AI, once about marketing, once about cooking. The workflow (= your AI program) is the same, only the input and output change.
 
 **Related commands:**
 
 -   [PARAMETER](https://github.com/webgptorg/promptbook/blob/main/documents/commands/PARAMETER.md)
 
-### **Who:** Personas
+### **2. Who:** Personas
 
 Who does the work. Each task is performed by a persona. A persona is a description of your virtual employee. It is a higher abstraction than the model, tokens, temperature, top-k, top-p and other model parameters.
 
@@ -421,7 +446,7 @@ Personas can have access to different knowledge, tools and actions. They can als
 
 
 
-### **How:** Knowledge, Instruments and Actions
+### **3. How:** Knowledge, Instruments and Actions
 
 The resources used by the personas are used to do the work.
 
@@ -431,7 +456,7 @@ The resources used by the personas are used to do the work.
 -   [INSTRUMENT](https://github.com/webgptorg/promptbook/blob/main/documents/commands/INSTRUMENT.md) for real-time data like time, location, weather, stock prices, searching the internet, calculations, etc.
 -   [ACTION](https://github.com/webgptorg/promptbook/blob/main/documents/commands/ACTION.md) for actions like sending emails, creating files, ending a workflow, etc.
 
-### General principles of book language
+### General Principles
 
 Book language is based on markdown. It is subset of markdown. It is designed to be easy to read and write. It is designed to be understandable by both humans and machines and without specific knowledge of the language.
 
@@ -445,6 +470,10 @@ But unlike programming languages, it is designed to be understandable by non-pro
 
 
 
+## 📚 Documentation
+
+See detailed guides and API reference in the [docs](https://github.com/webgptorg/promptbook/discussions/categories/concepts) or [online](https://discord.gg/x3QWNaa89N).
+
 ## 🔒 Security
 
 For information on reporting security vulnerabilities, see our [Security Policy](./SECURITY.md).
@@ -488,7 +517,7 @@ Or you can install them separately:
 -   **[@promptbook/legacy-documents](https://www.npmjs.com/package/@promptbook/legacy-documents)** - Read knowledge from legacy documents like `.doc`, `.rtf`,…
 -   **[@promptbook/website-crawler](https://www.npmjs.com/package/@promptbook/website-crawler)** - Crawl knowledge from the web
 -   **[@promptbook/editable](https://www.npmjs.com/package/@promptbook/editable)** - Editable book as native javascript object with imperative object API
--   **[@promptbook/templates](https://www.npmjs.com/package/@promptbook/templates)** - Usefull templates and examples of books which can be used as a starting point
+-   **[@promptbook/templates](https://www.npmjs.com/package/@promptbook/templates)** - Useful templates and examples of books which can be used as a starting point
 -   **[@promptbook/types](https://www.npmjs.com/package/@promptbook/types)** - Just typescript types used in the library
 -   ⭐ **[@promptbook/cli](https://www.npmjs.com/package/@promptbook/cli)** - Command line interface utilities for promptbooks
 -   🐋 **[Docker image](https://hub.docker.com/r/hejny/promptbook/)** - Promptbook server
@@ -525,25 +554,56 @@ _Note: This section is not complete dictionary, more list of general AI / LLM te
 -   [🤼 Personas](https://github.com/webgptorg/promptbook/discussions/22)
 -   [⭕ Parameters](https://github.com/webgptorg/promptbook/discussions/83)
 -   [🚀 Pipeline execution](https://github.com/webgptorg/promptbook/discussions/84)
--   [🧪 Expectations](https://github.com/webgptorg/promptbook/discussions/30)
--   [✂️ Postprocessing](https://github.com/webgptorg/promptbook/discussions/31)
--   [🔣 Words not tokens](https://github.com/webgptorg/promptbook/discussions/29)
--   [☯ Separation of concerns](https://github.com/webgptorg/promptbook/discussions/32)
+-   [🧪 Expectations](https://github.com/webgptorg/promptbook/discussions/30) - Define what outputs should look like and how they're validated
+-   [✂️ Postprocessing](https://github.com/webgptorg/promptbook/discussions/31) - How outputs are refined after generation
+-   [🔣 Words not tokens](https://github.com/webgptorg/promptbook/discussions/29) - The human-friendly way to think about text generation
+-   [☯ Separation of concerns](https://github.com/webgptorg/promptbook/discussions/32) - How Book language organizes different aspects of AI workflows
 
-#### Advanced concepts
+### Advanced concepts
+
+<table>
+  <tr>
+    <th>Data & Knowledge Management</th>
+    <th>Pipeline Control</th>
+  </tr>
+  <tr>
+    <td>
+      <ul>
+        <li><a href="https://github.com/webgptorg/promptbook/discussions/41">📚 Knowledge (RAG)</a> - Retrieve and use external information</li>
+        <li><a href="https://github.com/webgptorg/promptbook/discussions/54">📽 Media handling</a> - Working with images, audio, video, spreadsheets</li>
+        <li><a href="https://github.com/webgptorg/promptbook/discussions/40">🔴 Anomaly detection</a> - Identifying unusual patterns or outputs</li>
+      </ul>
+    </td>
+    <td>
+      <ul>
+        <li><a href="https://github.com/webgptorg/promptbook/discussions/89">🌏 Remote server</a> - Executing workflows on remote infrastructure</li>
+        <li><a href="https://github.com/webgptorg/promptbook/discussions/66">🃏 Jokers (conditions)</a> - Adding conditional logic to workflows</li>
+        <li><a href="https://github.com/webgptorg/promptbook/discussions/35">🔳 Metaprompting</a> - Creating prompts that generate other prompts</li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <th>Language & Output Control</th>
+    <th>Advanced Generation</th>
+  </tr>
+  <tr>
+    <td>
+      <ul>
+        <li><a href="https://github.com/webgptorg/promptbook/discussions/53">🌏 Linguistically typed languages</a> - Type systems for natural language</li>
+        <li><a href="https://github.com/webgptorg/promptbook/discussions/42">🌍 Auto-Translations</a> - Automatic multilingual support</li>
+        <li><a href="https://github.com/webgptorg/promptbook/discussions/39">👮 Agent adversary expectations</a> - Safety and control mechanisms</li>
+      </ul>
+    </td>
+    <td>
+      <ul>
+        <li><a href="https://github.com/webgptorg/promptbook/discussions/37">🔙 Expectation-aware generation</a> - Outputs that meet defined criteria</li>
+        <li><a href="https://github.com/webgptorg/promptbook/discussions/33">⏳ Just-in-time fine-tuning</a> - Dynamic model adaptation</li>
+      </ul>
+    </td>
+  </tr>
+</table>
 
--   [📚 Knowledge (Retrieval-augmented generation)](https://github.com/webgptorg/promptbook/discussions/41)
--   [🌏 Remote server](https://github.com/webgptorg/promptbook/discussions/89)
--   [🃏 Jokers (conditions)](https://github.com/webgptorg/promptbook/discussions/66)
--   [🔳 Metaprompting](https://github.com/webgptorg/promptbook/discussions/35)
--   [🌏 Linguistically typed languages](https://github.com/webgptorg/promptbook/discussions/53)
--   [🌍 Auto-Translations](https://github.com/webgptorg/promptbook/discussions/42)
--   [📽 Images, audio, video, spreadsheets](https://github.com/webgptorg/promptbook/discussions/54)
--   [🔙 Expectation-aware generation](https://github.com/webgptorg/promptbook/discussions/37)
--   [⏳ Just-in-time fine-tuning](https://github.com/webgptorg/promptbook/discussions/33)
--   [🔴 Anomaly detection](https://github.com/webgptorg/promptbook/discussions/40)
--   [👮 Agent adversary expectations](https://github.com/webgptorg/promptbook/discussions/39)
--   [view more](https://github.com/webgptorg/promptbook/discussions/categories/concepts)
+<p align="center"><a href="https://github.com/webgptorg/promptbook/discussions/categories/concepts">🔍 View more concepts</a></p>
 
 
 
@@ -598,36 +658,28 @@ If you have a question [start a discussion](https://github.com/webgptorg/promptb
 -   [❔ Is Promptbook using RAG _(Retrieval-Augmented Generation)_?](https://github.com/webgptorg/promptbook/discussions/123)
 -   [❔ Is Promptbook using function calling?](https://github.com/webgptorg/promptbook/discussions/124)
 
-## ⌚ Changelog
+## 📅 Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md)
 
 ## 📜 License
 
-Promptbook project is under [BUSL 1.1 is an SPDX license](https://spdx.org/licenses/BUSL-1.1.html)
+This project is licensed under [BUSL 1.1](./LICENSE.md).
 
-## 🎯 Todos
+## 🤝 Contributing
 
-See [TODO.md](./TODO.md)
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
 
-## 🤝 Partners
-
-<div style="display: flex; align-items: center; gap: 20px;">
-
-  <a href="https://promptbook.studio/">
-    <img src="./design/promptbook-studio-logo.png" alt="Partner 3" height="70">
-  </a>
-
-  <a href="https://technologickainkubace.org/en/about-technology-incubation/about-the-project/">
-    <img src="./other/partners/CI-Technology-Incubation.png" alt="Technology Incubation" height="70">
-  </a>
-
-</div>
+You can also ⭐ star the project, [follow us on GitHub](https://github.com/hejny) or [various other social networks](https://www.pavolhejny.com/contact/).We are open to [pull requests, feedback, and suggestions](./CONTRIBUTING.md).
 
-## 🖋️ Contributing
+## 🆘 Support & Community
 
-You can also ⭐ star the project, [follow us on GitHub](https://github.com/hejny) or [various other social networks](https://www.pavolhejny.com/contact/).We are open to [pull requests, feedback, and suggestions](./CONTRIBUTING.md).
+Need help with Book language? We're here for you!
 
-## 📞 Support
+-   💬 [Join our Discord community](https://discord.gg/x3QWNaa89N) for real-time support
+-   📝 [Browse our GitHub discussions](https://github.com/webgptorg/promptbook/discussions) for FAQs and community knowledge
+-   🐛 [Report issues](https://github.com/webgptorg/book/issues) for bugs or feature requests
+-   📚 Visit [ptbk.io](https://ptbk.io) for more resources and documentation
+-   📧 Contact us directly through the channels listed in our [signpost](./SIGNPOST.md)
 
-If you need help or have questions, please check our [Support Resources](./SUPPORT.md).
+We welcome contributions and feedback to make Book language better for everyone!

package/esm/index.es.js

@@ -18,7 +18,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.92.0-9';
+const PROMPTBOOK_ENGINE_VERSION = '0.93.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
@@ -80,7 +80,7 @@ const SMALL_NUMBER = 0.001;
 const CONNECTION_TIMEOUT_MS = 7 * 1000;
 // <- TODO: [🧜‍♂️]
 /**
- * @@@
+ * Default settings for parsing and generating CSV files in Promptbook.
  *
  * @public exported from `@promptbook/core`
  */
@@ -90,6 +90,14 @@ Object.freeze({
     newline: '\n',
     skipEmptyLines: true,
 });
+/**
+ * Default rate limits (requests per minute)
+ *
+ * Note: Adjust based on the provider tier you are have
+ *
+ * @public exported from `@promptbook/core`
+ */
+const DEFAULT_MAX_REQUESTS_PER_MINUTE = 60;
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name
  * TODO: [🧠][🧜‍♂️] Maybe join remoteServerUrl and path into single value
@@ -121,7 +129,7 @@ class PipelineExecutionError extends Error {
         super(message);
         this.name = 'PipelineExecutionError';
         // TODO: [🐙] DRY - Maybe $randomId
-        this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid simmilar char conflicts   */)}`;
+        this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid similar char conflicts   */)}`;
         Object.setPrototypeOf(this, PipelineExecutionError.prototype);
     }
 }
@@ -184,7 +192,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)}
@@ -540,10 +548,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) {
@@ -689,14 +697,18 @@ $deepFreeze({
 /**
  * Make UncertainNumber
  *
- * @param value
+ * @param value value of the uncertain number, if `NaN` or `undefined`, it will be set to 0 and `isUncertain=true`
+ * @param isUncertain if `true`, the value is uncertain, otherwise depends on the value
  *
  * @private utility for initializating UncertainNumber
  */
-function uncertainNumber(value) {
+function uncertainNumber(value, isUncertain) {
     if (value === null || value === undefined || Number.isNaN(value)) {
         return UNCERTAIN_ZERO_VALUE;
     }
+    if (isUncertain === true) {
+        return { value, isUncertain };
+    }
     return { value };
 }
 
@@ -914,8 +926,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) {
@@ -977,13 +993,13 @@ function exportJson(options) {
  */
 const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
 /**
- * @@@
+ * Placeholder value indicating a parameter is missing its value.
  *
  * @private within the repository
  */
 const RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
 /**
- * @@@
+ * Placeholder value indicating a parameter is restricted and cannot be used directly.
  *
  * @private within the repository
  */
@@ -1190,7 +1206,7 @@ function computeUsage(value) {
 /**
  * List of available OpenAI models with pricing
  *
- * Note: Done at 2024-05-20
+ * Note: Done at 2025-05-06
  *
  * @see https://platform.openai.com/docs/models/
  * @see https://openai.com/api/pricing/
@@ -1451,7 +1467,7 @@ const OPENAI_MODELS = exportJson({
             modelName: 'text-embedding-3-large',
             modelDescription: "OpenAI's most capable text embedding model designed for high-quality embeddings for complex similarity tasks and information retrieval.",
             pricing: {
-                prompt: computeUsage(`$0.13  / 1M tokens`),
+                prompt: computeUsage(`$0.13 / 1M tokens`),
                 // TODO: [🏏] Leverage the batch API @see https://platform.openai.com/docs/guides/batch
                 output: 0, // <- Note: [🆖] In Embedding models you dont pay for output
             },
@@ -1544,8 +1560,8 @@ const OPENAI_MODELS = exportJson({
             modelName: 'gpt-4o-mini',
             modelDescription: 'Smaller, more cost-effective version of GPT-4o with good performance across text, vision, and audio tasks at reduced complexity.',
             pricing: {
-                prompt: computeUsage(`$3.00 / 1M tokens`),
-                output: computeUsage(`$9.00 / 1M tokens`),
+                prompt: computeUsage(`$0.15 / 1M tokens`),
+                output: computeUsage(`$0.60 / 1M tokens`),
             },
         },
         /**/
@@ -1567,7 +1583,7 @@ const OPENAI_MODELS = exportJson({
             modelTitle: 'o1-preview-2024-09-12',
             modelName: 'o1-preview-2024-09-12',
             modelDescription: 'September 2024 version of O1 preview with specialized reasoning capabilities for complex tasks requiring precise analytical thinking.',
-            //             <- TODO: [💩] Some better system to organize theese date suffixes and versions
+            //             <- TODO: [💩] Some better system to organize these date suffixes and versions
             pricing: {
                 prompt: computeUsage(`$15.00 / 1M tokens`),
                 output: computeUsage(`$60.00 / 1M tokens`),
@@ -1653,9 +1669,6 @@ const OPENAI_MODELS = exportJson({
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
-// Default rate limits (requests per minute) - adjust as needed based on Azure OpenAI tier
-const DEFAULT_RPM = 60;
-// <- TODO: !!! Put in some better place
 /**
  * Execution Tools for calling Azure OpenAI API.
  *
@@ -1675,7 +1688,7 @@ class AzureOpenAiExecutionTools {
         this.client = null;
         // TODO: Allow configuring rate limits via options
         this.limiter = new Bottleneck({
-            minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_RPM),
+            minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE),
         });
     }
     get title() {
@@ -1929,7 +1942,7 @@ class AzureOpenAiExecutionTools {
         });
     }
     /**
-     * Changes Azure error (which is not propper Error but object) to propper Error
+     * Changes Azure error (which is not proper Error but object) to proper Error
      */
     transformAzureError(azureError) {
         if (azureError instanceof UnexpectedError) {
@@ -1989,7 +2002,8 @@ class NotYetImplementedError extends Error {
 }
 
 /**
- * @@@
+ * Safely retrieves the global scope object (window in browser, global in Node.js)
+ * regardless of the JavaScript environment in which the code is running
  *
  * Note: `$` is used to indicate that this function is not a pure function - it access global scope
  *
@@ -2000,10 +2014,10 @@ function $getGlobalScope() {
 }
 
 /**
- * @@@
+ * 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`
@@ -2055,10 +2069,10 @@ function normalizeTo_SCREAMING_CASE(text) {
  */
 
 /**
- * @@@
+ * Normalizes a text string to snake_case format.
  *
- * @param text @@@
- * @returns @@@
+ * @param text The text string to be converted to snake_case format.
+ * @returns The normalized text in snake_case format.
  * @example 'hello_world'
  * @example 'i_love_promptbook'
  * @public exported from `@promptbook/utils`
@@ -2068,11 +2082,11 @@ function normalizeTo_snake_case(text) {
 }
 
 /**
- * Register is @@@
+ * Global registry for storing and managing registered entities of a given type.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it accesses and adds variables in global scope.
  *
- * @private internal utility, exported are only signleton instances of this class
+ * @private internal utility, exported are only singleton instances of this class
  */
 class $Register {
     constructor(registerName) {
@@ -2116,10 +2130,10 @@ class $Register {
 }
 
 /**
- * @@@
+ * Register for LLM tools.
  *
  * Note: `$` is used to indicate that this interacts with the global scope
- * @singleton Only one instance of each register is created per build, but thare can be more @@@
+ * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
  * @public exported from `@promptbook/core`
  */
 const $llmToolsRegister = new $Register('llm_execution_tools_constructors');