@promptbook/google 0.92.0-9 → 0.92.0

package/esm/typings/src/commands/FOREACH/ForeachJson.d.ts

@@ -1,27 +1,27 @@
 import type { string_parameter_name } from '../../types/typeAliases';
 import type { TODO_string } from '../../utils/organization/TODO_string';
 /**
- * @@@
+ * Information for the FOREACH command, describing how to iterate over a parameter's subvalues in a pipeline task.
  */
 export type ForeachJson = {
     /**
-     * @@@
+     * The name of the format to use for parsing the parameter (e.g., 'CSV').
      */
     readonly formatName: TODO_string;
     /**
-     * @@@
+     * The name of the subformat to use (e.g., CSV Rows).
      */
     readonly subformatName: TODO_string;
     /**
-     * @@@
+     * The name of the parameter to iterate over.
      */
     readonly parameterName: string_parameter_name;
     /**
-     * @@@
+     * The names of the subparameters (e.g., name of the CSV rows)
      */
     readonly inputSubparameterNames: Array<string_parameter_name>;
     /**
-     * @@@
+     * The name of the subparameters (e.g., name of the CSV rows)
      */
     readonly outputSubparameterName: string_parameter_name;
 };

package/esm/typings/src/commands/FOREACH/foreachCommandParser.d.ts

@@ -3,8 +3,6 @@ import type { ForeachCommand } from './ForeachCommand';
 /**
  * Parses the foreach command
  *
- * Note: @@@ This command is used as foreach for new commands - it should NOT be used in any `.book` file
- *
  * @see `documentationUrl` for more details
  * @public exported from `@promptbook/editable`
  */

package/esm/typings/src/commands/FORMFACTOR/formfactorCommandParser.d.ts

@@ -3,7 +3,7 @@ import type { FormfactorCommand } from './FormfactorCommand';
 /**
  * Parses the formfactor command
  *
- * Note: @@@ This command is used as formfactor for new commands - it should NOT be used in any `.book` file
+ * Note: This command is used as a formfactor for new commands and defines the app type format - it should NOT be used in any `.book` file
  *
  * @see `documentationUrl` for more details
  * @public exported from `@promptbook/editable`

package/esm/typings/src/commands/_BOILERPLATE/boilerplateCommandParser.d.ts

@@ -3,7 +3,7 @@ import type { BoilerplateCommand } from './BoilerplateCommand';
 /**
  * Parses the boilerplate command
  *
- * Note: @@@ This command is used as boilerplate for new commands - it should NOT be used in any `.book` file
+ * Note: @@ This command is used as boilerplate for new commands - it should NOT be used in any `.book` file
  *
  * @see `documentationUrl` for more details
  * @private within the commands folder

package/esm/typings/src/commands/_common/types/CommandParser.d.ts

@@ -8,7 +8,8 @@ import type { string_SCREAMING_CASE } from '../../../utils/normalization/normali
 import type { ___and___ } from '../../../utils/organization/___and___';
 import type { CommandUsagePlace } from './CommandUsagePlaces';
 /**
- * @@@
+ * Base type for all command objects.
+ * Requires a `type` property which is a SCREAMING_CASE string.
  *
  * @private just abstract helper for command parsers
  */
@@ -16,47 +17,48 @@ export type CommandBase = {
     type: string_name & string_SCREAMING_CASE;
 };
 /**
- * @@@
+ * Represents a parser for a specific command used within a Promptbook pipeline.
+ * It can parse commands used in the pipeline head, tasks, or both.
  *
  * @public exported from `@promptbook/editable`
  */
 export type CommandParser<TCommand extends CommandBase> = PipelineHeadCommandParser<TCommand> | PipelineTaskCommandParser<TCommand> | PipelineBothCommandParser<TCommand>;
 /**
- * @@@
+ * Common properties shared by all command parsers.
  *
  * @private just abstract the common properties of the command parsers
  */
 export type CommonCommandParser<TCommand extends CommandBase> = {
     /**
-     * @@@
+     * The unique SCREAMING_CASE name of the command (e.g., 'MODEL', 'PARAMETER').
      */
     readonly name: string_name & string_SCREAMING_CASE;
     /**
-     * @@@
+     * Indicates if the command can be used in the pipeline's head section.
      */
     readonly isUsedInPipelineHead: boolean;
     /**
-     * @@@
+     * Indicates if the command can be used within a pipeline task.
      */
     readonly isUsedInPipelineTask: boolean;
     /**
-     * @@@
+     * Optional alternative names (aliases) for the command, also in SCREAMING_CASE.
      */
     readonly aliasNames?: ReadonlyArray<string_name & string_SCREAMING_CASE>;
     /**
-     * @@@
+     * Optional list of deprecated names for the command, used for backward compatibility.
      */
     readonly deprecatedNames?: ReadonlyArray<string_name & string_SCREAMING_CASE>;
     /**
-     * @@@
+     * A brief description of the command's purpose, supporting simple Markdown.
      */
     readonly description: string_markdown_text;
     /**
-     * @@@
+     * A URL pointing to the command's documentation.
      */
     readonly documentationUrl: string_promptbook_documentation_url;
     /**
-     * @@@
+     * Examples demonstrating the usage of the command in Markdown format.
      */
     readonly examples: ReadonlyArray<string_markdown_text>;
     /**
@@ -72,23 +74,23 @@ export type CommonCommandParser<TCommand extends CommandBase> = {
     stringify(command: TCommand): string_markdown_text;
 };
 /**
- * @@@
+ * Represents a command parser that can be used in both the pipeline head and tasks.
  *
  * @public exported from `@promptbook/editable`
  */
 export type PipelineBothCommandParser<TCommand extends CommandBase> = ___and___ & Omit<PipelineHeadCommandParser<TCommand>, 'isUsedInPipelineTask'> & Omit<PipelineTaskCommandParser<TCommand>, 'isUsedInPipelineHead'>;
 /**
- * @@@
+ * Represents a command parser specifically for the pipeline head section.
  *
  * @public exported from `@promptbook/editable`
  */
 export type PipelineHeadCommandParser<TCommand extends CommandBase> = CommonCommandParser<TCommand> & {
     /**
-     * @@@
+     * Always true for pipeline head commands.
      */
     readonly isUsedInPipelineHead: true;
     /**
-     * @@@
+     * Always false for pipeline head commands.
      */
     readonly isUsedInPipelineTask: false;
     /**
@@ -106,17 +108,17 @@ export type PipelineHeadCommandParser<TCommand extends CommandBase> = CommonComm
     takeFromPipelineJson(pipelineJson: PipelineJson): ReadonlyArray<TCommand>;
 };
 /**
- * @@@
+ * Represents a command parser specifically for pipeline tasks.
  *
  * @public exported from `@promptbook/editable`
  */
 export type PipelineTaskCommandParser<TCommand extends CommandBase> = CommonCommandParser<TCommand> & {
     /**
-     * @@@
+     * Always false for pipeline task commands.
      */
     readonly isUsedInPipelineHead: false;
     /**
-     * @@@
+     * Always true for pipeline task commands.
      */
     readonly isUsedInPipelineTask: true;
     /**
@@ -133,58 +135,64 @@ export type PipelineTaskCommandParser<TCommand extends CommandBase> = CommonComm
     takeFromTaskJson($taskJson: $TaskJson): ReadonlyArray<TCommand>;
 };
 /**
- * @@@
+ * Represents a mutable TaskJson object, used internally by command parsers during application.
  *
- * Note: `$` is used to indicate that purpose of this type is to mutate the given object
+ * Note: `$` prefix indicates the object is intended for mutation.
  *
  * @private internal helper for command parsers
  */
 export type $TaskJson = {
+    /**
+     * Flag indicating if the section type (e.g., `SIMPLE_TEMPLATE`) has been set for this task.
+     */
     isSectionTypeSet: boolean;
+    /**
+     * Flag indicating if this object represents a task (as opposed to other sections like parameters).
+     */
     isTask: boolean;
 } & Partial<WritableDeep<TaskJson>>;
 /**
- * @@@
+ * Represents a mutable PipelineJson object, used internally by command parsers during application.
  *
- *  Note: `$` is used to indicate that purpose of this type is to mutate the given object
+ * Note: `$` prefix indicates the object is intended for mutation.
  *
  * @private internal helper for command parsers
  */
 export type $PipelineJson = WritableDeep<SetOptional<PipelineJson, 'formfactorName'>>;
 /**
- * @@@
+ * Input object provided to the `parse` method of a CommandParser.
  */
 export type CommandParserInput = {
     /**
-     * @@@
+     * Specifies where the command is being used (pipeline head or task).
      *
      * @example 'PIPELINE_HEAD'
      * @example 'PIPELINE_TASK'
      */
     readonly usagePlace: CommandUsagePlace;
     /**
-     * @@@
+     * The raw, unprocessed line containing the command and its arguments.
      *
      * @example 'promptbook version 0.62.0'
      * @example 'FOREACH Text Line `{customers}` -> `{customer}`'
      */
     readonly raw: string_markdown_text;
     /**
-     * @@@
+     * The arguments part of the raw command line, after the command name.
      *
      * @example '0.62.0'
      * @example 'List Line `{customers}` -> `{customer}`'
      */
     readonly rawArgs: string_markdown_text;
     /**
-     * @@@
+     * The normalized, SCREAMING_CASE representation of the command and its core arguments.
      *
      * @example 'PROMPTBOOK_ENGINE_VERSION_0_62_0'
      * @example 'FOREACH_LIST_LINE_CUSTOMERS_CUSTOMER'
      */
     readonly normalized: string_name & string_SCREAMING_CASE;
     /**
-     * @@@
+     * An array of arguments extracted from the line where the command is used.
      *
      * @example [ '0.62.0' ]
      * @example [ 'List', 'Line', '{customers}', '', '{customer}' ]

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
      *