@promptbook/components 0.100.0-24

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

@@ -0,0 +1,46 @@
+import type { number_integer } from '../types/typeAliases';
+import type { number_positive } from '../types/typeAliases';
+/**
+ * Represents all the tools needed to interact with the user.
+ *
+ * @see https://github.com/webgptorg/promptbook#user-interface-tools
+ */
+export type UserInterfaceTools = {
+    /**
+     * Asks the user to answer a free-text (multi-line) question
+     *
+     * @param options the question to ask
+     * @returns the answer from the user
+     */
+    promptDialog(options: UserInterfaceToolsPromptDialogOptions): Promise<string>;
+};
+export type UserInterfaceToolsPromptDialogOptions = {
+    /**
+     * Prompt title
+     *
+     * Note: This is not a prompt to language model but a prompt to the user
+     * @example "Your name"
+     */
+    readonly promptTitle: string;
+    /**
+     * Prompt message
+     *
+     * Note: This is not a prompt to language model but a prompt to the user
+     * @example "Please enter your name, including your last name, title, etc."
+     */
+    readonly promptMessage: string;
+    /**
+     * Default value for the input/textarea
+     */
+    readonly defaultValue: string | null;
+    /**
+     * Placeholder for the input/textarea
+     */
+    readonly placeholder?: string;
+    /**
+     * Priority of the prompt
+     *
+     * Note: This would be reflected for example into the UI z-index of the prompt modal
+     */
+    readonly priority: number_integer & number_positive;
+};

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

@@ -0,0 +1,14 @@
+import type { PipelineExecutorResult } from './PipelineExecutorResult';
+/**
+ * Asserts that the execution of a Promptbook is successful
+ *
+ * Note: If there are only warnings, the execution is still successful but the warnings are logged in the console
+ *
+ * @param executionResult - The partial result of the Promptbook execution
+ * @throws {PipelineExecutionError} If the execution is not successful or if multiple errors occurred
+ * @private internal helper function of `asPromise` method of `ExecutionTask`
+ */
+export declare function assertsTaskSuccessful(executionResult: Pick<PipelineExecutorResult, 'isSuccessful' | 'errors' | 'warnings'>): void;
+/**
+ * TODO: [🧠] Can this return type be better typed than void
+ */

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

@@ -0,0 +1,56 @@
+import { ExpectError } from '../../errors/ExpectError';
+import type { Prompt } from '../../types/Prompt';
+import type { ChatPromptResult } from '../PromptResult';
+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>;
+    /**
+     * Array of all failed attempts, storing both the result string and the error for each failure
+     */
+    $failedResults: Array<{
+        attemptIndex: number;
+        result: string | null;
+        error: ExpectError;
+    }>;
+};

package/esm/typings/src/execution/createPipelineExecutor/00-CreatePipelineExecutorOptions.d.ts

@@ -0,0 +1,46 @@
+import type { CsvSettings } from '../../formats/csv/CsvSettings';
+import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
+import type { PrepareAndScrapeOptions } from '../../prepare/PrepareAndScrapeOptions';
+import type { ExecutionTools } from '../ExecutionTools';
+/**
+ * Options for `createPipelineExecutor`
+ */
+export type CreatePipelineExecutorOptions = PrepareAndScrapeOptions & {
+    /**
+     * The pipeline to be executed
+     */
+    readonly pipeline: PipelineJson;
+    /**
+     * The execution tools to be used during the execution of the pipeline
+     */
+    readonly tools: ExecutionTools;
+    /**
+     * When executor does not satisfy expectations it will be retried this amount of times
+     *
+     * @default MAX_EXECUTION_ATTEMPTS
+     */
+    readonly maxExecutionAttempts?: number;
+    /**
+     * Settings for CSV format
+     *
+     * @default DEFAULT_CSV_SETTINGS
+     */
+    readonly csvSettings?: CsvSettings;
+    /**
+     * If you pass fully prepared pipeline, this does not matter
+     *
+     * Otherwise:
+     * If false or not set, warning is shown when pipeline is not prepared
+     * If true, warning is suppressed
+     *
+     * @default false
+     */
+    readonly isNotPreparedWarningSuppressed?: boolean;
+};
+/**
+ * TODO: [🧎][🧠] Move `csvSettings` to some better place
+ *       1) either to some dependency in `ExecutionTools`
+ *       2) or make here container for multiple formats
+ *       3) or make the setting more universal and which just sets things like `delimiter` and `quote` without specifying the format
+ * TODO: [🤹‍♂️] More granular setting for limits of execution + better waiting for queue
+ */

package/esm/typings/src/execution/createPipelineExecutor/00-createPipelineExecutor.d.ts

@@ -0,0 +1,10 @@
+import type { PipelineExecutor } from '../PipelineExecutor';
+import type { CreatePipelineExecutorOptions } from './00-CreatePipelineExecutorOptions';
+/**
+ * Creates executor function from pipeline and execution tools.
+ *
+ * @returns The executor function
+ * @throws {PipelineLogicError} on logical error in the pipeline
+ * @public exported from `@promptbook/core`
+ */
+export declare function createPipelineExecutor(options: CreatePipelineExecutorOptions): PipelineExecutor;

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

@@ -0,0 +1,48 @@
+import type { PartialDeep, Promisable, ReadonlyDeep } from 'type-fest';
+import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
+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.
+     */
+    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 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`
+ */
+export declare function executePipeline(options: ExecutePipelineOptions): Promise<PipelineExecutorResult>;
+export {};

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

@@ -0,0 +1,51 @@
+import type { PartialDeep, Promisable, ReadonlyDeep, WritableDeep } from 'type-fest';
+import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
+import type { TaskJson } from '../../pipeline/PipelineJson/TaskJson';
+import type { Parameters } from '../../types/typeAliases';
+import type { ExecutionReportJson } from '../execution-report/ExecutionReportJson';
+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.
+     */
+    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`
+ */
+export declare function executeTask(options: executeSingleTaskOptions): Promise<Readonly<Parameters>>;
+export {};
+/**
+ * TODO: [🤹‍♂️]
+ */

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

@@ -0,0 +1,27 @@
+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 & {
+    /**
+     * 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`
+ */
+export declare function executeFormatSubvalues(options: ExecuteFormatCellsOptions): Promise<TODO_any>;
+export {};

package/esm/typings/src/execution/createPipelineExecutor/40-executeAttempts.d.ts

@@ -0,0 +1,70 @@
+import type { ReadonlyDeep, WritableDeep } from 'type-fest';
+import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
+import type { TaskJson } from '../../pipeline/PipelineJson/TaskJson';
+import type { Parameters } from '../../types/typeAliases';
+import type { string_parameter_name } from '../../types/typeAliases';
+import type { TODO_string } from '../../utils/organization/TODO_string';
+import type { ExecutionReportJson } from '../execution-report/ExecutionReportJson';
+import type { CreatePipelineExecutorOptions } from './00-CreatePipelineExecutorOptions';
+/**
+ * Options for executing attempts of a pipeline task, including configuration for jokers, priority,
+ * maximum attempts, prepared content, parameters, the task itself, the prepared pipeline, execution report,
+ * and pipeline identification. Used internally by the pipeline executor.
+ *
+ * @private internal type of `executeAttempts`
+ */
+export type ExecuteAttemptsOptions = Required<Omit<CreatePipelineExecutorOptions, 'pipeline'>> & {
+    /**
+     * Names of parameters that act as jokers, which can be used to bypass normal execution if their value meets requirements.
+     */
+    readonly jokerParameterNames: Readonly<ReadonlyArray<string_parameter_name>>;
+    /**
+     * Priority of the current execution attempt, used to influence UI or execution order.
+     */
+    readonly priority: number;
+    /**
+     * Maximum number of attempts allowed for this task, including retries and joker attempts.
+     * Note: [💂] There are two distinct variables
+     * 1) `maxExecutionAttempts` - attempts for LLM model
+     * 2) `maxAttempts` - attempts for any task (LLM, SCRIPT, DIALOG, etc.)
+     */
+    readonly maxAttempts: number;
+    /**
+     * The content prepared for execution, with parameters already substituted.
+     */
+    readonly preparedContent: TODO_string;
+    /**
+     * The parameters provided for this execution attempt.
+     */
+    readonly parameters: Readonly<Parameters>;
+    /**
+     * The task being executed, as a deeply immutable TaskJson object.
+     * Note: Naming should be unified between `task` and `currentTask`.
+     */
+    readonly task: ReadonlyDeep<TaskJson>;
+    /**
+     * The pipeline structure prepared for execution, as a deeply immutable PipelineJson object.
+     */
+    readonly preparedPipeline: ReadonlyDeep<PipelineJson>;
+    /**
+     * The execution report object, which is updated during execution.
+     */
+    readonly $executionReport: WritableDeep<ExecutionReportJson>;
+    /**
+     * String identifier for the pipeline, used for logging and error reporting.
+     */
+    readonly pipelineIdentification: string;
+};
+/**
+ * Executes a pipeline task with multiple attempts, including joker and retry logic. Handles different task types
+ * (prompt, script, dialog, etc.), applies postprocessing, checks expectations, and updates the execution report.
+ * Throws errors if execution fails after all attempts.
+ *
+ * @param options - The options for execution, including task, parameters, pipeline, and configuration.
+ * @returns The result string of the executed task.
+ * @private internal utility of `createPipelineExecutor`
+ */
+export declare function executeAttempts(options: ExecuteAttemptsOptions): Promise<TODO_string>;
+/**
+ * TODO: Break into smaller functions
+ */

package/esm/typings/src/execution/createPipelineExecutor/computeCosineSimilarity.d.ts

@@ -0,0 +1,13 @@
+import type { EmbeddingVector } from '../EmbeddingVector';
+/**
+ * Computes the cosine similarity between two embedding vectors
+ *
+ * Note: This is helping function for RAG (retrieval-augmented generation)
+ *
+ * @param embeddingVector1
+ * @param embeddingVector2
+ * @returns Cosine similarity between the two vectors
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function computeCosineSimilarity(embeddingVector1: EmbeddingVector, embeddingVector2: EmbeddingVector): number;

package/esm/typings/src/execution/createPipelineExecutor/filterJustOutputParameters.d.ts

@@ -0,0 +1,35 @@
+import type { ReadonlyDeep } from 'type-fest';
+import { PipelineExecutionError } from '../../errors/PipelineExecutionError';
+import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
+import type { Parameters } from '../../types/typeAliases';
+/**
+ * Options for filtering and extracting only output parameters from a pipeline execution.
+ *
+ * @private internal type of `createPipelineExecutor`
+ */
+type FilterJustOutputParametersOptions = {
+    /**
+     * The fully prepared pipeline containing parameter definitions.
+     */
+    readonly preparedPipeline: ReadonlyDeep<PipelineJson>;
+    /**
+     * The parameters passed to the pipeline, including both input and output values.
+     */
+    readonly parametersToPass: Readonly<Parameters>;
+    /**
+     * Array to collect warnings encountered during parameter extraction.
+     */
+    readonly $warnings: PipelineExecutionError[];
+    /**
+     * String identifier for the pipeline, used in warning messages.
+     */
+    readonly pipelineIdentification: string;
+};
+/**
+ * Filters and returns only the output parameters from the provided pipeline execution options.
+ * Adds warnings for any expected output parameters that are missing.
+ *
+ * @private internal utility of `createPipelineExecutor`
+ */
+export declare function filterJustOutputParameters(options: FilterJustOutputParametersOptions): Parameters;
+export {};

package/esm/typings/src/execution/createPipelineExecutor/getContextForTask.d.ts

@@ -0,0 +1,14 @@
+import type { ReadonlyDeep } from 'type-fest';
+import type { TaskJson } from '../../pipeline/PipelineJson/TaskJson';
+import type { string_markdown } from '../../types/typeAliases';
+import type { string_parameter_value } from '../../types/typeAliases';
+/**
+ * Returns the context for a given task, typically used to provide additional information or variables
+ * required for the execution of the task within a pipeline. The context is returned as a string value
+ * that may include markdown formatting.
+ *
+ * @param task - The task for which the context is being generated. This should be a deeply immutable TaskJson object.
+ * @returns The context as a string, formatted as markdown and parameter value.
+ * @private internal utility of `createPipelineExecutor`
+ */
+export declare function getContextForTask(task: ReadonlyDeep<TaskJson>): Promise<string_parameter_value & string_markdown>;

package/esm/typings/src/execution/createPipelineExecutor/getExamplesForTask.d.ts

@@ -0,0 +1,10 @@
+import type { ReadonlyDeep } from 'type-fest';
+import type { TaskJson } from '../../pipeline/PipelineJson/TaskJson';
+import type { string_markdown } from '../../types/typeAliases';
+import type { string_parameter_value } from '../../types/typeAliases';
+/**
+ * Retrieves example values or templates for a given task, used to guide or validate pipeline execution.
+ *
+ * @private internal utility of `createPipelineExecutor`
+ */
+export declare function getExamplesForTask(task: ReadonlyDeep<TaskJson>): Promise<string_parameter_value & string_markdown>;

package/esm/typings/src/execution/createPipelineExecutor/getKnowledgeForTask.d.ts

@@ -0,0 +1,42 @@
+import type { ReadonlyDeep } from 'type-fest';
+import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
+import type { TaskJson } from '../../pipeline/PipelineJson/TaskJson';
+import type { Parameters } from '../../types/typeAliases';
+import type { string_markdown } from '../../types/typeAliases';
+import type { string_parameter_value } from '../../types/typeAliases';
+import type { ExecutionTools } from '../ExecutionTools';
+/**
+ * Options for retrieving relevant knowledge for a specific task during pipeline execution.
+ *
+ * @private internal type of `getKnowledgeForTask`
+ */
+type GetKnowledgeForTaskOptions = {
+    /**
+     * The execution tools to be used during the execution of the pipeline.
+     */
+    readonly tools: ExecutionTools;
+    /**
+     * The fully prepared pipeline containing all tasks and knowledge pieces.
+     */
+    readonly preparedPipeline: ReadonlyDeep<PipelineJson>;
+    /**
+     * The current task for which knowledge is being retrieved.
+     */
+    readonly task: ReadonlyDeep<TaskJson>;
+    /**
+     * Parameters used to complete the content of the task for embedding and knowledge retrieval.
+     */
+    readonly parameters: Readonly<Parameters>;
+};
+/**
+ * Retrieves the most relevant knowledge pieces for a given task using embedding-based similarity search.
+ * This is where retrieval-augmented generation (RAG) is performed to enhance the task with external knowledge.
+ *
+ * @private internal utility of `createPipelineExecutor`
+ */
+export declare function getKnowledgeForTask(options: GetKnowledgeForTaskOptions): Promise<string_parameter_value & string_markdown>;
+export {};
+/**
+ * TODO: [♨] Implement Better - use keyword search
+ * TODO: [♨] Examples of values
+ */

package/esm/typings/src/execution/createPipelineExecutor/getReservedParametersForTask.d.ts

@@ -0,0 +1,48 @@
+import type { ReadonlyDeep } from 'type-fest';
+import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
+import type { TaskJson } from '../../pipeline/PipelineJson/TaskJson';
+import type { Parameters } from '../../types/typeAliases';
+import type { ReservedParameters } from '../../types/typeAliases';
+import type { ExecutionTools } from '../ExecutionTools';
+/**
+ * Options for retrieving reserved parameters for a pipeline task, including context, pipeline, and identification.
+ *
+ * @private internal type of `getReservedParametersForTask`
+ */
+type GetReservedParametersForTaskOptions = {
+    /**
+     * The execution tools to be used during the execution of the pipeline
+     */
+    readonly tools: ExecutionTools;
+    /**
+     * The prepared and validated pipeline in which the task resides.
+     */
+    readonly preparedPipeline: ReadonlyDeep<PipelineJson>;
+    /**
+     * The task for which reserved parameters are being retrieved.
+     */
+    readonly task: ReadonlyDeep<TaskJson>;
+    /**
+     * Parameters to complete the content of the task for embedding and context.
+     */
+    readonly parameters: Readonly<Parameters>;
+    /**
+     * String identifier for the pipeline, used in error messages and reporting.
+     */
+    readonly pipelineIdentification: string;
+    /**
+     * If true, the preparation logs the reserved parameters for debugging purposes.
+     */
+    readonly isVerbose?: boolean;
+};
+/**
+ * Retrieves all reserved parameters for a given pipeline task, including context, knowledge, examples, and metadata.
+ * Ensures all reserved parameters are defined and throws if any are missing.
+ *
+ * @param options - Options including tools, pipeline, task, and context.
+ * @returns An object containing all reserved parameters for the task.
+ *
+ * @private internal utility of `createPipelineExecutor`
+ */
+export declare function getReservedParametersForTask(options: GetReservedParametersForTaskOptions): Promise<Readonly<ReservedParameters>>;
+export {};

package/esm/typings/src/execution/createPipelineExecutor/knowledgePiecesToString.d.ts

@@ -0,0 +1,9 @@
+import type { KnowledgePiecePreparedJson } from '../../pipeline/PipelineJson/KnowledgePieceJson';
+/**
+ *
+ * @param knowledgePieces
+ * @returns
+ *
+ * @private internal utility of `createPipelineExecutor`
+ */
+export declare function knowledgePiecesToString(knowledgePieces: ReadonlyArray<Pick<KnowledgePiecePreparedJson, 'content'>>): string;

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

@@ -0,0 +1,7 @@
+import type { EmbeddingVector } from './EmbeddingVector';
+/**
+ * Pretty print an embedding vector for logging
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function embeddingVectorToString(embeddingVector: Readonly<EmbeddingVector>): string;

package/esm/typings/src/execution/execution-report/ExecutionPromptReportJson.d.ts

@@ -0,0 +1,24 @@
+import type { ErrorJson } from '../../errors/utils/ErrorJson';
+import type { Prompt } from '../../types/Prompt';
+import type { PromptResult } from '../PromptResult';
+/**
+ * Report of single prompt execution
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type ExecutionPromptReportJson = {
+    /**
+     * The prompt which was executed
+     */
+    readonly prompt: Omit<Prompt, 'pipelineUrl'>;
+    /**
+     * Result of the prompt execution (if not failed during LLM execution)
+     */
+    readonly result?: PromptResult;
+    /**
+     * The error which occurred during LLM execution or during postprocessing or expectation checking
+     *
+     * Note: It makes sense to have both error and result defined, for example when the result not pass expectations
+     */
+    readonly error?: ErrorJson;
+};

package/esm/typings/src/execution/execution-report/ExecutionReportJson.d.ts

@@ -0,0 +1,41 @@
+import type { string_markdown_text } from '../../types/typeAliases';
+import type { string_pipeline_url } from '../../types/typeAliases';
+import type { string_semantic_version } from '../../types/typeAliases';
+import type { ExecutionPromptReportJson } from './ExecutionPromptReportJson';
+/**
+ * ExecutionReport is result of executing one promptbook
+ * It is kind of a variant of the promptbook useful for debugging, logging and transparency for users.
+ *
+ * It can have 2 formats:
+ * -   **.md file** created from the **JSON** format
+ * -   _(this)_ **JSON** format
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ * @see https://github.com/webgptorg/promptbook#execution-report
+ */
+export type ExecutionReportJson = {
+    /**
+     * Unique identifier of the pipeline from promptbook which was executed
+     */
+    readonly pipelineUrl?: string_pipeline_url;
+    /**
+     * Title of from promptbook which was executed
+     */
+    readonly title?: string;
+    /**
+     * Version from promptbook which was executed
+     */
+    readonly promptbookUsedVersion: string_semantic_version;
+    /**
+     * Version from promptbook which was requested by promptbook
+     */
+    readonly promptbookRequestedVersion?: string_semantic_version;
+    /**
+     * Description of the promptbook which was executed
+     */
+    readonly description?: string_markdown_text;
+    /**
+     * Sequence of tasks in order which were executed
+     */
+    readonly promptExecutions: ReadonlyArray<ExecutionPromptReportJson>;
+};

package/esm/typings/src/execution/execution-report/ExecutionReportString.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ExecutionReport is result of executing one promptbook
+ * It is kind of a variant of the promptbook useful for debugging, logging and transparency for users.
+ *
+ * It can have 2 formats:
+ * -   _(this)_ **.md file** created from the **JSON** format
+ * -   **JSON** format
+ *
+ * @see https://github.com/webgptorg/promptbook#execution-report
+ */
+export type ExecutionReportString = string & {
+    readonly _type: 'ExecutionReportString';
+};
+/**
+ * TODO: [💩] Better validation or remove branded type and make it just string
+ */