@promptbook/node 0.104.0-9 → 0.105.0-0

package/esm/typings/src/utils/random/$randomAgentPersona.d.ts

@@ -1,9 +1,14 @@
+import type { string_persona_description } from '../../types/typeAliases';
 /**
- * @@@@
+ * Generates a random agent persona description.
  *
+ * This function selects a random personality profile from a predefined pool
+ * of common AI agent characteristics (e.g., friendly, professional, creative).
+ *
+ * @returns A string describing the agent's persona
  * @private internal helper function
  */
-export declare function $randomAgentPersona(): string;
+export declare function $randomAgentPersona(): string_persona_description;
 /**
  * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
  */

package/esm/typings/src/utils/random/$randomItem.d.ts

@@ -6,4 +6,4 @@
 export declare function $randomItem<TItem>(...items: Array<TItem>): TItem;
 /**
  * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
- */ 
+ */

package/esm/typings/src/utils/random/$randomSeed.d.ts

@@ -10,4 +10,4 @@ import type { number_seed } from '../../types/typeAliases';
 export declare function $randomSeed(): number_seed;
 /**
  * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
- */ 
+ */

package/esm/typings/src/utils/validators/url/isValidAgentUrl.d.ts

@@ -0,0 +1,16 @@
+import type { string_agent_url } from '../../../types/typeAliases';
+import type { really_unknown } from '../../organization/really_unknown';
+/**
+ * Tests if given string is valid agent URL
+ *
+ * Note: There are few similar functions:
+ * - `isValidUrl` which tests any URL
+ * - `isValidAgentUrl` *(this one)* which tests just agent URL
+ * - `isValidPipelineUrl` which tests just pipeline URL
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function isValidAgentUrl(url: really_unknown): url is string_agent_url;
+/**
+ * TODO: [🐠] Maybe more info why the URL is invalid
+ */

package/esm/typings/src/utils/validators/url/isValidAgentUrl.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/validators/url/isValidPipelineUrl.d.ts

@@ -3,8 +3,9 @@ import type { really_unknown } from '../../organization/really_unknown';
 /**
  * Tests if given string is valid pipeline URL URL.
  *
- * Note: There are two similar functions:
+ * Note: There are few similar functions:
  * - `isValidUrl` which tests any URL
+ * - `isValidAgentUrl` which tests just agent URL
  * - `isValidPipelineUrl` *(this one)* which tests just pipeline URL
  *
  * @public exported from `@promptbook/utils`

package/esm/typings/src/utils/validators/url/isValidUrl.d.ts

@@ -5,9 +5,10 @@ import type { really_unknown } from '../../organization/really_unknown';
  *
  * Note: [🔂] This function is idempotent.
  * Note: Dataurl are considered perfectly valid.
- * Note: There are two similar functions:
- * - `isValidUrl` which tests any URL
- * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
+ * Note: There are few similar functions:
+ * - `isValidUrl` *(this one)* which tests any URL
+ * - `isValidAgentUrl` which tests just agent URL
+ * - `isValidPipelineUrl` which tests just pipeline URL
  *
  * @public exported from `@promptbook/utils`
  */

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.104.0-8`).
+ * It follows semantic versioning (e.g., `0.104.0`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/node",
-    "version": "0.104.0-9",
+    "version": "0.105.0-0",
     "description": "Promptbook: Turn your company's scattered knowledge into AI ready books",
     "private": false,
     "sideEffects": false,
@@ -93,7 +93,7 @@
     "module": "./esm/index.es.js",
     "typings": "./esm/typings/src/_packages/node.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.104.0-9"
+        "@promptbook/core": "0.105.0-0"
     },
     "dependencies": {
         "colors": "1.4.0",

package/umd/index.umd.js

@@ -45,7 +45,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.104.0-9';
+    const PROMPTBOOK_ENGINE_VERSION = '0.105.0-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
@@ -1724,9 +1724,10 @@
      *
      * Note: [🔂] This function is idempotent.
      * Note: Dataurl are considered perfectly valid.
-     * Note: There are two similar functions:
-     * - `isValidUrl` which tests any URL
-     * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
+     * Note: There are few similar functions:
+     * - `isValidUrl` *(this one)* which tests any URL
+     * - `isValidAgentUrl` which tests just agent URL
+     * - `isValidPipelineUrl` which tests just pipeline URL
      *
      * @public exported from `@promptbook/utils`
      */
@@ -1752,8 +1753,9 @@
     /**
      * Tests if given string is valid pipeline URL URL.
      *
-     * Note: There are two similar functions:
+     * Note: There are few similar functions:
      * - `isValidUrl` which tests any URL
+     * - `isValidAgentUrl` which tests just agent URL
      * - `isValidPipelineUrl` *(this one)* which tests just pipeline URL
      *
      * @public exported from `@promptbook/utils`
@@ -2986,7 +2988,7 @@
      *
      * @public exported from `@promptbook/utils`
      */
-    function deserializeError(error) {
+    function deserializeError(error, isStackAddedToMessage = true) {
         const { name, stack, id } = error; // Added id
         let { message } = error;
         let ErrorClass = ALL_ERRORS[error.name];
@@ -2994,7 +2996,7 @@
             ErrorClass = Error;
             message = `${name}: ${message}`;
         }
-        if (stack !== undefined && stack !== '') {
+        if (isStackAddedToMessage && stack !== undefined && stack !== '') {
             message = spaceTrim__default["default"]((block) => `
                 ${block(message)}
 
@@ -4145,17 +4147,21 @@
      */
 
     /**
-     * Joins multiple LLM Execution Tools into one
+     * Joins multiple LLM Execution Tools into one.
      *
-     * @returns {LlmExecutionTools} Single wrapper for multiple LlmExecutionTools
+     * This function takes a list of `LlmExecutionTools` and returns a single unified
+     * `MultipleLlmExecutionTools` object. It provides failover and aggregation logic:
      *
-     * 0) If there is no LlmExecutionTools, it warns and returns valid but empty LlmExecutionTools
-     * 1) If there is only one LlmExecutionTools, it returns it wrapped in a proxy object
-     * 2) If there are multiple LlmExecutionTools, first will be used first, second will be used if the first hasn`t defined model variant or fails, etc.
-     * 3) When all LlmExecutionTools fail, it throws an error with a list of all errors merged into one
+     * 1.  **Failover**: When a model call is made, it tries providers in the order they were provided.
+     *     If the first provider doesn't support the requested model or fails, it tries the next one.
+     * 2.  **Aggregation**: `listModels` returns a combined list of all models available from all providers.
+     * 3.  **Empty case**: If no tools are provided, it logs a warning (as Promptbook requires LLMs to function).
      *
+     * @param title - A descriptive title for this collection of joined tools
+     * @param llmExecutionTools - An array of execution tools to be joined
+     * @returns A single unified execution tool wrapper
      *
-     * Tip: You don't have to use this function directly, just pass an array of LlmExecutionTools to the `ExecutionTools`
+     * Tip: You don't have to use this function directly, just pass an array of LlmExecutionTools to the `ExecutionTools`.
      *
      * @public exported from `@promptbook/core`
      */
@@ -4195,7 +4201,7 @@
     }
     /**
      * TODO: [🙆] `getSingleLlmExecutionTools` vs `joinLlmExecutionTools` - explain difference or pick one
-     * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
+     * TODO: [👷‍♂️] Write a comprehensive manual about how to construct and use LLM execution tools in Promptbook
      */
 
     /**
@@ -4212,7 +4218,7 @@
     }
     /**
      * TODO: [🙆] `getSingleLlmExecutionTools` vs `joinLlmExecutionTools` - explain difference or pick one
-     * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
+     * TODO: [👷‍♂️] Write a comprehensive manual about how to construct and use LLM execution tools in Promptbook
      */
 
     /**
@@ -4766,8 +4772,8 @@
      */
     function removeDiacritics(input) {
         /*eslint no-control-regex: "off"*/
-        return input.replace(/[^\u0000-\u007E]/g, (a) => {
-            return DIACRITIC_VARIANTS_LETTERS[a] || a;
+        return input.replace(/[^\u0000-\u007E]/g, (character) => {
+            return DIACRITIC_VARIANTS_LETTERS[character] || character;
         });
     }
     /**
@@ -5458,7 +5464,7 @@
             const taskEmbeddingResult = await llmTools.callEmbeddingModel(taskEmbeddingPrompt);
             const knowledgePiecesWithRelevance = preparedPipeline.knowledgePieces.map((knowledgePiece) => {
                 const { index } = knowledgePiece;
-                const knowledgePieceIndex = index.find((i) => i.modelName === firstKnowledgeIndex.modelName);
+                const knowledgePieceIndex = index.find((knowledgePieceIndex) => knowledgePieceIndex.modelName === firstKnowledgeIndex.modelName);
                 // <- TODO: Do not use just first knowledge piece and first index to determine embedding model
                 if (knowledgePieceIndex === undefined) {
                     return {
@@ -5906,7 +5912,7 @@
                         resovedParameterNames = [...resovedParameterNames, currentTask.resultingParameterName];
                     })
                         .then(() => {
-                        resolving = resolving.filter((w) => w !== work);
+                        resolving = resolving.filter((workItem) => workItem !== work);
                     });
                     // <- Note: Errors are catched here [3]
                     //    TODO: BUT if in multiple tasks are errors, only the first one is catched so maybe we should catch errors here and save them to errors array here
@@ -6072,7 +6078,7 @@
                         // Calculate and update tldr based on pipeline progress
                         const cv = newOngoingResult;
                         // Calculate progress based on parameters resolved vs total parameters
-                        const totalParameters = pipeline.parameters.filter((p) => !p.isInput).length;
+                        const totalParameters = pipeline.parameters.filter((parameter) => !parameter.isInput).length;
                         let resolvedParameters = 0;
                         let currentTaskTitle = '';
                         // Get the resolved parameters from output parameters
@@ -6152,7 +6158,7 @@
             tasks.push(task);
             runningTasks.push(task);
             /* not await */ Promise.resolve(task).then(() => {
-                runningTasks = runningTasks.filter((t) => t !== task);
+                runningTasks = runningTasks.filter((runningTask) => runningTask !== task);
             });
             if (maxParallelCount < runningTasks.length) {
                 await Promise.race(runningTasks);
@@ -6162,10 +6168,14 @@
     }
 
     /**
-     * Intercepts LLM tools and counts total usage of the tools
+     * Intercepts LLM tools and counts total usage of the tools.
+     *
+     * This function wraps the provided `LlmExecutionTools` with a proxy that tracks the cumulative
+     * usage (tokens, cost, etc.) across all model calls. It provides a way to monitor spending
+     * in real-time through an observable.
      *
-     * @param llmTools LLM tools to be intercepted with usage counting
-     * @returns LLM tools with same functionality with added total cost counting
+     * @param llmTools - The LLM tools to be intercepted and tracked
+     * @returns An augmented version of the tools that includes usage tracking capabilities
      * @public exported from `@promptbook/core`
      */
     function countUsage(llmTools) {
@@ -6240,7 +6250,7 @@
      * TODO: [🧠] Is there some meaningfull way how to test this util
      * TODO: [🧠][🌯] Maybe a way how to hide ability to `get totalUsage`
      *     > const [llmToolsWithUsage,getUsage] = countTotalUsage(llmTools);
-     * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
+     * TODO: [👷‍♂️] Write a comprehensive manual explaining the construction and usage of LLM tools in the Promptbook ecosystem
      */
 
     /**
@@ -6777,7 +6787,6 @@
      * @public exported from `@promptbook/core`
      */
     async function makeKnowledgeSourceHandler(knowledgeSource, tools, options) {
-        // console.log('!! makeKnowledgeSourceHandler', knowledgeSource);
         var _a;
         const { fetch = promptbookFetch } = tools;
         const { knowledgeSourceContent } = knowledgeSource;
@@ -7798,6 +7807,9 @@
      * @public exported from `@promptbook/utils`
      */
     function parseNumber(value) {
+        if (value === null || value === undefined) {
+            return 0;
+        }
         const originalValue = value;
         if (typeof value === 'number') {
             value = value.toString(); // <- TODO: Maybe more efficient way to do this
@@ -8832,7 +8844,12 @@
      * @see {@link ModelVariant}
      * @public exported from `@promptbook/core`
      */
-    const MODEL_VARIANTS = ['COMPLETION', 'CHAT', 'IMAGE_GENERATION', 'EMBEDDING' /* <- TODO [🏳] */ /* <- [🤖] */];
+    const MODEL_VARIANTS = [
+        'COMPLETION',
+        'CHAT',
+        'IMAGE_GENERATION',
+        'EMBEDDING' /* <- TODO [🏳] */ /* <- [🤖] */,
+    ];
 
     /**
      * Parses the model command