@promptbook/browser 0.92.0-9 → 0.93.0

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

@@ -68,6 +68,28 @@ export declare const DEFAULT_BOOK_OUTPUT_PARAMETER_NAME = "result";
  * @public exported from `@promptbook/core`
  */
 export declare const DEFAULT_MAX_FILE_SIZE: number;
+/**
+ * Threshold value that determines when a dataset is considered "big"
+ * and may require special handling or optimizations
+ *
+ * For example, when error occurs in one item of the big dataset, it will not fail the whole pipeline
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const BIG_DATASET_TRESHOLD = 50;
+/**
+ * Placeholder text used to represent a placeholder value of failed operation
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const FAILED_VALUE_PLACEHOLDER = "!?";
+/**
+ * Placeholder text used to represent operations or values that are still in progress
+ * or awaiting completion in UI displays and logging
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const PENDING_VALUE_PLACEHOLDER = "\u2026";
 /**
  * Warning message for the generated sections and files files
  *
@@ -156,15 +178,15 @@ export declare const DEFAULT_MAX_PARALLEL_COUNT = 5;
  */
 export declare const DEFAULT_MAX_EXECUTION_ATTEMPTS = 10;
 /**
- * @@@
- * TODO: [🐝][main] !!3 Use
+ * The maximum depth to which knowledge sources will be scraped when building a knowledge base.
+ * This prevents infinite recursion and limits resource usage.
  *
  * @public exported from `@promptbook/core`
  */
 export declare const DEFAULT_MAX_KNOWLEDGE_SOURCES_SCRAPING_DEPTH = 3;
 /**
- * @@@
- * TODO: [🐝][main] !!3 Use
+ * The maximum total number of knowledge sources that will be scraped in a single operation.
+ * This acts as a global limit to avoid excessive resource consumption.
  *
  * @public exported from `@promptbook/core`
  */
@@ -234,27 +256,27 @@ export declare const MOMENT_ARG_THRESHOLDS: {
  */
 export declare const DEFAULT_REMOTE_SERVER_URL: string_promptbook_server_url;
 /**
- * @@@
+ * Default settings for parsing and generating CSV files in Promptbook.
  *
  * @public exported from `@promptbook/core`
  */
 export declare const DEFAULT_CSV_SETTINGS: CsvSettings;
 /**
- * @@@
+ * Controls whether verbose logging is enabled by default throughout the application.
  *
  * @public exported from `@promptbook/core`
  */
 export declare let DEFAULT_IS_VERBOSE: boolean;
 /**
- * @@@
+ * Enables or disables verbose logging globally at runtime.
  *
- * Note: This is experimental feature
+ * Note: This is an experimental feature.
  *
  * @public exported from `@promptbook/core`
  */
 export declare function SET_IS_VERBOSE(isVerbose: boolean): void;
 /**
- * @@@
+ * Controls whether auto-installation of dependencies is enabled by default.
  *
  * @public exported from `@promptbook/core`
  */
@@ -266,13 +288,21 @@ export declare const DEFAULT_IS_AUTO_INSTALLED = false;
  */
 export declare const DEFAULT_GET_PIPELINE_COLLECTION_FUNCTION_NAME = "getPipelineCollection";
 /**
- * @@@
+ * Default rate limits (requests per minute)
+ *
+ * Note: Adjust based on the provider tier you are have
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const DEFAULT_MAX_REQUESTS_PER_MINUTE = 60;
+/**
+ * Indicates whether pipeline logic validation is enabled. When true, the pipeline logic is checked for consistency.
  *
  * @private within the repository
  */
 export declare const IS_PIPELINE_LOGIC_VALIDATED: boolean;
 /**
- * @@@
+ * Indicates whether cost-prevention is enabled. When true, real API keys are prevented from being used in tests.
  *
  * @private within the repository
  */

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

@@ -1,5 +1,40 @@
 import type { PipelineJson } from './pipeline/PipelineJson/PipelineJson';
 import type { ExportJsonOptions } from './utils/serialization/exportJson';
+/**
+ * How is the model provider trusted?
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const MODEL_TRUST_LEVELS: {
+    readonly FULL: "Model is running on the local machine, training data and model weights are known, data are ethically sourced";
+    readonly OPEN: "Model is open source, training data and model weights are known";
+    readonly PARTIALLY_OPEN: "Model is open source, but training data and model weights are not (fully) known";
+    readonly CLOSED_LOCAL: "Model can be run locally, but it is not open source";
+    readonly CLOSED_FREE: "Model is behind API gateway but free to use";
+    readonly CLOSED_BUSINESS: "Model is behind API gateway and paid but has good SLA, TOS, privacy policy and in general is a good to use in business applications";
+    readonly CLOSED: "Model is behind API gateway and paid";
+    readonly UNTRUSTED: "Model has questions about the training data and ethics, but it is not known if it is a problem or not";
+    readonly VURNABLE: "Model has some known serious vulnerabilities, leaks, ethical problems, etc.";
+};
+/**
+ * How is the model provider important?
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const MODEL_ORDERS: {
+    /**
+     * Top-tier models, e.g. OpenAI, Anthropic,...
+     */
+    readonly TOP_TIER: 333;
+    /**
+     * Mid-tier models, e.g. Llama, Mistral, etc.
+     */
+    readonly NORMAL: 100;
+    /**
+     * Low-tier models, e.g. Phi, Tiny, etc.
+     */
+    readonly LOW_TIER: 0;
+};
 /**
  * Order of keys in the pipeline JSON
  *
@@ -13,13 +48,19 @@ export declare const ORDER_OF_PIPELINE_JSON: ExportJsonOptions<PipelineJson>['or
  */
 export declare const REPLACING_NONCE = "ptbkauk42kV2dzao34faw7FudQUHYPtW";
 /**
- * @@@
+ * Nonce which is used as string which is not occurring in normal text
+ *
+ * @private within the repository
+ */
+export declare const SALT_NONCE = "ptbkghhewbvruets21t54et5";
+/**
+ * Placeholder value indicating a parameter is missing its value.
  *
  * @private within the repository
  */
 export declare const RESERVED_PARAMETER_MISSING_VALUE: string;
 /**
- * @@@
+ * Placeholder value indicating a parameter is restricted and cannot be used directly.
  *
  * @private within the repository
  */

package/esm/typings/src/conversion/parsePipeline.d.ts

@@ -4,7 +4,7 @@ import type { PipelineString } from '../pipeline/PipelineString';
  * Compile pipeline from string (markdown) format to JSON format synchronously
  *
  * Note: There are 3 similar functions:
- * - `compilePipeline` **(preferred)** - which propperly compiles the promptbook and use embedding for external knowledge
+ * - `compilePipeline` **(preferred)** - which properly compiles the promptbook and uses embedding for external knowledge
  * - `parsePipeline` - use only if you need to compile promptbook synchronously and it contains NO external knowledge
  * - `preparePipeline` - just one step in the compilation process
  *
@@ -24,7 +24,7 @@ export declare function parsePipeline(pipelineString: PipelineString): PipelineJ
  * TODO: Use spaceTrim more effectively
  * TODO: [🧠] Parameter flags - isInput, isOutput, isInternal
  * TODO: [🥞] Not optimal parsing because `splitMarkdownIntoSections` is executed twice with same string, once through `flattenMarkdown` and second directly here
- * TODO: [♈] Probbably move expectations from tasks to parameters
+ * TODO: [♈] Probably move expectations from tasks to parameters
  * TODO: [🛠] Actions, instruments (and maybe knowledge) => Functions and tools
  * TODO: [🍙] Make some standard order of json properties
  */

package/esm/typings/src/errors/0-BoilerplateError.d.ts

@@ -1,5 +1,5 @@
 /**
- * This error indicates @@@
+ * This error indicates @@
  *
  * @public exported from `@promptbook/core`
  */
@@ -8,5 +8,5 @@ export declare class BoilerplateError extends Error {
     constructor(message: string);
 }
 /**
- * TODO: @@@ Do not forget to add the error into `0-index.ts` ERRORS
+ * TODO: @@ Do not forget to add the error into `0-index.ts` ERRORS
  */

package/esm/typings/src/errors/CollectionError.d.ts

@@ -1,5 +1,5 @@
 /**
- * This error indicates that the pipeline collection cannot be propperly loaded
+ * This error indicates that the pipeline collection cannot be properly loaded
  *
  * @public exported from `@promptbook/core`
  */

package/esm/typings/src/executables/$provideExecutablesForNode.d.ts

@@ -1,7 +1,7 @@
 import type { Executables } from '../execution/Executables';
 import type { PrepareAndScrapeOptions } from '../prepare/PrepareAndScrapeOptions';
 /**
- * @@@
+ * Provides paths to required executables (i.e. as Pandoc and LibreOffice) for Node.js environments.
  *
  * @public exported from `@promptbook/node`
  */

package/esm/typings/src/executables/apps/locateLibreoffice.d.ts

@@ -1,6 +1,7 @@
 import type { string_executable_path } from '../../types/typeAliases';
 /**
- * @@@
+ * Locates the LibreOffice executable on the current system by searching platform-specific paths.
+ * Returns the path to the executable if found, or null otherwise.
  *
  * @private within the repository
  */

package/esm/typings/src/executables/apps/locatePandoc.d.ts

@@ -1,6 +1,7 @@
 import type { string_executable_path } from '../../types/typeAliases';
 /**
- * @@@
+ * Locates the Pandoc executable on the current system by searching platform-specific paths.
+ * Returns the path to the executable if found, or null otherwise.
  *
  * @private within the repository
  */

package/esm/typings/src/executables/locateApp.d.ts

@@ -3,7 +3,7 @@ import type { string_executable_path } from '../types/typeAliases';
 /**
  * Options for locating any application
  */
-export interface LocateAppOptions {
+export type LocateAppOptions = {
     /**
      * Name of the application
      */
@@ -20,7 +20,7 @@ export interface LocateAppOptions {
      * Name of the application on macOS
      */
     macOsName?: string;
-}
+};
 /**
  * Locates an application on the system
  *

package/esm/typings/src/executables/platforms/locateAppOnLinux.d.ts

@@ -1,7 +1,8 @@
 import type { string_executable_path } from '../../types/typeAliases';
 import type { LocateAppOptions } from '../locateApp';
 /**
- * @@@
+ * Attempts to locate the specified application on a Linux system using the 'which' command.
+ * Returns the path to the executable if found, or null otherwise.
  *
  * @private within the repository
  */

package/esm/typings/src/executables/platforms/locateAppOnMacOs.d.ts

@@ -1,7 +1,8 @@
 import type { string_executable_path } from '../../types/typeAliases';
 import type { LocateAppOptions } from '../locateApp';
 /**
- * @@@
+ * Attempts to locate the specified application on a macOS system by checking standard application paths and using mdfind.
+ * Returns the path to the executable if found, or null otherwise.
  *
  * @private within the repository
  */

package/esm/typings/src/executables/platforms/locateAppOnWindows.d.ts

@@ -1,7 +1,8 @@
 import type { string_executable_path } from '../../types/typeAliases';
 import type { LocateAppOptions } from '../locateApp';
 /**
- * @@@
+ * Attempts to locate the specified application on a Windows system by searching common installation directories.
+ * Returns the path to the executable if found, or null otherwise.
  *
  * @private within the repository
  */

package/esm/typings/src/execution/AbstractTaskResult.d.ts

@@ -1,7 +1,7 @@
 import { ReadonlyDeep } from 'type-fest';
 import type { ErrorJson } from '../errors/utils/ErrorJson';
 /**
- * @@@
+ * Represents the result of execution of a task in a pipeline
  *
  * Note: [🚉] This is fully serializable as JSON
  */

package/esm/typings/src/execution/CommonToolsOptions.d.ts

@@ -1,6 +1,6 @@
 import type { string_user_id } from '../types/typeAliases';
 /**
- * @@@
+ * Common options shared across various execution tools.
  *
  * Note: Keep it public to allow people to make their own execution tools
  */
@@ -17,8 +17,8 @@ export type CommonToolsOptions = {
      */
     readonly isVerbose?: boolean;
     /**
-    * Maximum number of requests per minute
-    */
+     * Maximum number of requests per minute
+     */
     readonly maxRequestsPerMinute?: number;
 };
 /**

package/esm/typings/src/execution/ExecutionTask.d.ts

@@ -2,6 +2,7 @@ import type { Observable } from 'rxjs';
 import { PartialDeep } from 'type-fest';
 import type { task_id } from '../types/typeAliases';
 import type { string_SCREAMING_CASE } from '../utils/normalization/normalizeTo_SCREAMING_CASE';
+import type { string_promptbook_version } from '../version';
 import type { AbstractTaskResult } from './AbstractTaskResult';
 import type { PipelineExecutorResult } from './PipelineExecutorResult';
 /**
@@ -12,12 +13,21 @@ type CreateTaskOptions<TTaskResult extends AbstractTaskResult> = {
      * The type of task to create
      */
     readonly taskType: AbstractTask<TTaskResult>['taskType'];
+    /**
+     * Human-readable title of the task - used for displaying in the UI
+     */
+    readonly title: AbstractTask<TTaskResult>['title'];
     /**
      * Callback that processes the task and updates the ongoing result
      * @param ongoingResult The partial result of the task processing
      * @returns The final task result
      */
-    taskProcessCallback(updateOngoingResult: (newOngoingResult: PartialDeep<TTaskResult>) => void): Promise<TTaskResult>;
+    taskProcessCallback(updateOngoingResult: (newOngoingResult: PartialDeep<TTaskResult> & {
+        /**
+         * Optional update of the task title
+         */
+        readonly title?: AbstractTask<TTaskResult>['title'];
+    }) => void): Promise<TTaskResult>;
 };
 /**
  * Helper to create a new task
@@ -52,10 +62,18 @@ export type AbstractTask<TTaskResult extends AbstractTaskResult> = {
      * Type of the task
      */
     readonly taskType: string_SCREAMING_CASE;
+    /**
+     * Version of the promptbook used to run the task
+     */
+    readonly promptbookVersion: string_promptbook_version;
     /**
      * Unique identifier for the task
      */
     readonly taskId: task_id;
+    /**
+     * Human-readable title of the task - used for displaying in the UI
+     */
+    readonly title: string;
     /**
      * Status of the task
      */

package/esm/typings/src/execution/LlmExecutionToolsConstructor.d.ts

@@ -2,7 +2,8 @@ import type { Registered } from '../utils/$Register';
 import type { TODO_any } from '../utils/organization/TODO_any';
 import type { LlmExecutionTools } from './LlmExecutionTools';
 /**
- * @@@
+ * Type representing a constructor for LLM execution tools, which are used to interact with language models.
+ * Combines registration metadata with a factory function for creating LLM tool instances.
  */
 export type LlmExecutionToolsConstructor = Registered & ((options: TODO_any) => LlmExecutionTools);
 /**

package/esm/typings/src/execution/PipelineExecutorResult.d.ts

@@ -5,7 +5,7 @@ import type { AbstractTaskResult } from './AbstractTaskResult';
 import type { ExecutionReportJson } from './execution-report/ExecutionReportJson';
 import type { Usage } from './Usage';
 /**
- * @@@
+ * The result of executing a pipeline
  *
  * Note: [🚉] This is fully serializable as JSON
  */
@@ -22,8 +22,10 @@ export type PipelineExecutorResult = AbstractTaskResult & {
     readonly usage: ReadonlyDeep<Usage>;
     /**
      * The report of the execution with all details
+     *
+     * Note: If the execution fails unexpectedly, this will be `null`
      */
-    readonly executionReport: ReadonlyDeep<ExecutionReportJson>;
+    readonly executionReport: ReadonlyDeep<ExecutionReportJson> | null;
     /**
      * The prepared pipeline that was used for the execution
      *

package/esm/typings/src/execution/PromptbookFetch.d.ts

@@ -5,7 +5,7 @@ import type { string_url } from '../types/typeAliases';
  * In most cases it is just native `fetch` function with a lightweight error handling wrapper
  * But it can be replaced with any other fetch function, polyfill, custom implementation, security layer, etc.
  *
- * It is used in theese places:
+ * It is used in these places:
  * - Fetching knowledge sources
  * - Callbacks from remote server
  */

package/esm/typings/src/execution/ScriptExecutionTools.d.ts

@@ -19,7 +19,7 @@ export type ScriptExecutionToolsExecuteOptions = {
     readonly scriptLanguage: ScriptLanguage;
     /**
      * Parameters for the script
-     * Theese parameters are passed to the script as variables
+     * These parameters are passed to the script as variables
      * For example: { "name": "John" } => const name = "John";
      */
     readonly parameters: Parameters;

package/esm/typings/src/execution/createPipelineExecutor/$OngoingTaskResult.d.ts

@@ -5,41 +5,44 @@ import type { CompletionPromptResult } from '../PromptResult';
 import type { EmbeddingPromptResult } from '../PromptResult';
 import type { PromptResult } from '../PromptResult';
 /**
- * @@@
+ * Represents the ongoing result of a pipeline task execution
+ *
+ * Used internally by the pipeline executor to track state during execution attempts
  *
  * @private internal utility of `createPipelineExecutor`
  */
 export type $OngoingTaskResult = {
     /**
-     * @@@
+     * The prompt object used for the current execution attempt, if applicable.
      */
     $prompt?: Prompt;
     /**
-     * @@@
+     * The result of a chat model execution, if applicable.
      */
     $chatResult?: ChatPromptResult;
     /**
-     * @@@
+     * The result of a completion model execution, if applicable.
      */
     $completionResult?: CompletionPromptResult;
     /**
-     * @@@
+     * The result of an embedding model execution, if applicable.
+     * Note: [🤖] Embedding results are less common in standard pipelines.
      */
     $embeddingResult?: EmbeddingPromptResult;
     /**
-     * @@@
+     * The final result object for the task, or null if not yet available.
      */
     $result: PromptResult | null;
     /**
-     * @@@
+     * The result string produced by the task, or null if not yet available.
      */
     $resultString: string | null;
     /**
-     * @@@
+     * The last expectation error encountered, or null if none.
      */
     $expectError: ExpectError | null;
     /**
-     * @@@
+     * List of errors encountered during script postprocessing or execution.
      */
     $scriptPipelineExecutionErrors: Array<Error>;
 };

package/esm/typings/src/execution/createPipelineExecutor/10-executePipeline.d.ts

@@ -4,40 +4,43 @@ import type { InputParameters } from '../../types/typeAliases';
 import type { PipelineExecutorResult } from '../PipelineExecutorResult';
 import type { CreatePipelineExecutorOptions } from './00-CreatePipelineExecutorOptions';
 /**
- * @@@
+ * Options for executing an entire pipeline, including input parameters, pipeline context, and progress callbacks.
  *
  * @private internal type of `executePipeline`
  */
 type ExecutePipelineOptions = Required<CreatePipelineExecutorOptions> & {
     /**
-     * @@@
+     * The input parameters provided by the user for pipeline execution.
      */
     readonly inputParameters: Readonly<InputParameters>;
     /**
-     * @@@
+     * Optional callback invoked with partial results as the pipeline execution progresses.
      */
     onProgress?(newOngoingResult: PartialDeep<PipelineExecutorResult>): Promisable<void>;
     /**
-     * @@@
+     * The pipeline definition to execute.
      */
     readonly pipeline: PipelineJson;
     /**
-     * @@@
+     * The prepared and validated pipeline, ready for execution.
      */
     readonly preparedPipeline: ReadonlyDeep<PipelineJson>;
     /**
-     * @@@
+     * Callback to update the prepared pipeline reference after preparation.
      */
-    readonly setPreparedPipeline: (preparedPipeline: ReadonlyDeep<PipelineJson>) => void;
+    setPreparedPipeline(preparedPipeline: ReadonlyDeep<PipelineJson>): void;
     /**
-     * @@@
+     * String identifier for the pipeline, used in error messages and reporting.
      */
     readonly pipelineIdentification: string;
 };
 /**
- * @@@
+ * Executes an entire pipeline, resolving tasks in dependency order, handling errors, and reporting progress.
  *
- * Note: This is not a `PipelineExecutor` (which is binded with one exact pipeline), but a utility function of `createPipelineExecutor` which creates `PipelineExecutor`
+ * Note: This is not a `PipelineExecutor` (which is bound to a single pipeline), but a utility function used by `createPipelineExecutor` to create a `PipelineExecutor`.
+ *
+ * @param options - Options for execution, including input parameters, pipeline, and callbacks.
+ * @returns The result of the pipeline execution, including output parameters, errors, and usage statistics.
  *
  * @private internal utility of `createPipelineExecutor`
  */

package/esm/typings/src/execution/createPipelineExecutor/20-executeTask.d.ts

@@ -6,38 +6,41 @@ import type { ExecutionReportJson } from '../execution-report/ExecutionReportJso
 import type { PipelineExecutorResult } from '../PipelineExecutorResult';
 import type { CreatePipelineExecutorOptions } from './00-CreatePipelineExecutorOptions';
 /**
- * @@@
+ * Options for executing a single pipeline task, including task details, pipeline context, parameters, and callbacks.
  *
  * @private internal type of `executeTask`
  */
 type executeSingleTaskOptions = Required<CreatePipelineExecutorOptions> & {
     /**
-     * @@@
+     * The task to be executed.
      */
     readonly currentTask: ReadonlyDeep<TaskJson>;
     /**
-     * @@@
+     * The pipeline in which the task resides, fully prepared and validated.
      */
     readonly preparedPipeline: ReadonlyDeep<PipelineJson>;
     /**
-     * @@@
+     * The parameters to pass to the task execution.
      */
     readonly parametersToPass: Readonly<Parameters>;
     /**
-     * @@@
+     * Callback invoked with partial results as the execution progresses.
      */
-    readonly onProgress: (newOngoingResult: PartialDeep<PipelineExecutorResult>) => Promisable<void>;
+    onProgress(newOngoingResult: PartialDeep<PipelineExecutorResult>): Promisable<void>;
     /**
-     * @@@
+     * Mutable execution report object for tracking execution details.
      */
     readonly $executionReport: WritableDeep<ExecutionReportJson>;
     /**
-     * @@@
+     * String identifier for the pipeline, used in error messages and reporting.
      */
     readonly pipelineIdentification: string;
 };
 /**
- * @@@
+ * Executes a single task within a pipeline, handling parameter validation, error checking, and progress reporting.
+ *
+ * @param options - Options for execution, including the task, pipeline, parameters, and callbacks.
+ * @returns The output parameters produced by the task.
  *
  * @private internal utility of `createPipelineExecutor`
  */

package/esm/typings/src/execution/createPipelineExecutor/30-executeFormatSubvalues.d.ts

@@ -1,13 +1,25 @@
+import type { PartialDeep, Promisable } from 'type-fest';
 import type { TODO_any } from '../../utils/organization/TODO_any';
+import type { PipelineExecutorResult } from '../PipelineExecutorResult';
 import type { ExecuteAttemptsOptions } from './40-executeAttempts';
 /**
- * @@@
+ * Options for executing a pipeline task that involves formatting subvalues (e.g., iterating over CSV rows).
+ * Extends ExecuteAttemptsOptions with a progress callback.
  *
  * @private internal type of `executeFormatSubvalues`
  */
-type ExecuteFormatCellsOptions = ExecuteAttemptsOptions;
+type ExecuteFormatCellsOptions = ExecuteAttemptsOptions & {
+    /**
+     * Callback invoked with partial results as the execution progresses.
+     */
+    onProgress(newOngoingResult: PartialDeep<PipelineExecutorResult>): Promisable<void>;
+};
 /**
- * @@@
+ * Executes a pipeline task that requires mapping or iterating over subvalues of a parameter (such as rows in a CSV).
+ * Handles format and subformat resolution, error handling, and progress reporting.
+ *
+ * @param options - Options for execution, including task details and progress callback.
+ * @returns The result of the subvalue mapping or execution attempts.
  *
  * @private internal utility of `createPipelineExecutor`
  */