@promptbook/color 0.100.0-48

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

@@ -0,0 +1,9 @@
+/**
+ * Error thrown when a fetch request fails
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare class PromptbookFetchError extends Error {
+    readonly name = "PromptbookFetchError";
+    constructor(message: string);
+}

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

@@ -0,0 +1,9 @@
+/**
+ * This error type indicates that the error should not happen and its last check before crashing with some other error
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare class UnexpectedError extends Error {
+    readonly name = "UnexpectedError";
+    constructor(message: string);
+}

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

@@ -0,0 +1,10 @@
+import type { really_any } from '../utils/organization/really_any';
+/**
+ * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare class WrappedError extends Error {
+    readonly name = "WrappedError";
+    constructor(whatWasThrown: really_any);
+}

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

@@ -0,0 +1,11 @@
+import type { really_unknown } from '../utils/organization/really_unknown';
+/**
+ * Helper used in catch blocks to assert that the error is an instance of `Error`
+ *
+ * @param whatWasThrown Any object that was thrown
+ * @returns Nothing if the error is an instance of `Error`
+ * @throws `WrappedError` or `UnexpectedError` if the error is not standard
+ *
+ * @private within the repository
+ */
+export declare function assertsError(whatWasThrown: really_unknown): asserts whatWasThrown is Error;

package/esm/typings/src/errors/utils/ErrorJson.d.ts

@@ -0,0 +1,25 @@
+import type { task_id } from '../../types/typeAliases';
+import type { ALL_ERRORS } from '../0-index';
+/**
+ * Represents a serialized error or custom Promptbook error
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type ErrorJson = {
+    /**
+     * The unique identifier of the error
+     */
+    readonly id?: task_id;
+    /**
+     * The type of the error
+     */
+    readonly name: keyof typeof ALL_ERRORS;
+    /**
+     * The message of the error
+     */
+    readonly message: string;
+    /**
+     * The stack trace of the error
+     */
+    readonly stack?: string;
+};

package/esm/typings/src/errors/utils/deserializeError.d.ts

@@ -0,0 +1,7 @@
+import type { ErrorJson } from './ErrorJson';
+/**
+ * Deserializes the error object
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function deserializeError(error: ErrorJson): Error;

package/esm/typings/src/errors/utils/deserializeError.test.d.ts

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

package/esm/typings/src/errors/utils/getErrorReportUrl.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Make error report URL for the given error
+ *
+ * @private private within the repository
+ */
+export declare function getErrorReportUrl(error: Error): URL;

package/esm/typings/src/errors/utils/serializeError.d.ts

@@ -0,0 +1,7 @@
+import type { ErrorJson } from './ErrorJson';
+/**
+ * Serializes an error into a [🚉] JSON-serializable object
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function serializeError(error: Error): ErrorJson;

package/esm/typings/src/errors/utils/serializeError.test.d.ts

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

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

@@ -0,0 +1,12 @@
+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`
+ */
+export declare function $provideExecutablesForNode(options?: PrepareAndScrapeOptions): Promise<Executables>;
+/**
+ * TODO: [🧠] Allow to override the executables without need to call `locatePandoc` / `locateLibreoffice` in case of provided
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

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

@@ -0,0 +1,12 @@
+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
+ */
+export declare function locateLibreoffice(): Promise<string_executable_path | null>;
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node` OR `@promptbook/legacy-documents`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

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

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

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

@@ -0,0 +1,12 @@
+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
+ */
+export declare function locatePandoc(): Promise<string_executable_path | null>;
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node` OR `@promptbook/documents`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

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

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

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

@@ -0,0 +1,33 @@
+import type { RequireAtLeastOne } from 'type-fest';
+import type { string_executable_path } from '../types/typeAliases';
+/**
+ * Options for locating any application
+ */
+export type LocateAppOptions = {
+    /**
+     * Name of the application
+     */
+    appName: string;
+    /**
+     * Name of the executable on Linux
+     */
+    linuxWhich?: string;
+    /**
+     * Path suffix on Windows
+     */
+    windowsSuffix?: string;
+    /**
+     * Name of the application on macOS
+     */
+    macOsName?: string;
+};
+/**
+ * Locates an application on the system
+ *
+ * @private within the repository
+ */
+export declare function locateApp(options: RequireAtLeastOne<LocateAppOptions, 'linuxWhich' | 'windowsSuffix' | 'macOsName'>): Promise<string_executable_path | null>;
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

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

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

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

@@ -0,0 +1,13 @@
+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
+ */
+export declare function locateAppOnLinux({ linuxWhich, }: Pick<Required<LocateAppOptions>, 'linuxWhich'>): Promise<string_executable_path | null>;
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

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

@@ -0,0 +1,13 @@
+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
+ */
+export declare function locateAppOnMacOs({ macOsName, }: Pick<Required<LocateAppOptions>, 'macOsName'>): Promise<string_executable_path | null>;
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

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

@@ -0,0 +1,13 @@
+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
+ */
+export declare function locateAppOnWindows({ appName, windowsSuffix, }: Pick<Required<LocateAppOptions>, 'appName' | 'windowsSuffix'>): Promise<string_executable_path | null>;
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

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

@@ -0,0 +1,25 @@
+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
+ */
+export type AbstractTaskResult = {
+    /**
+     * Whether the execution was successful, details are available in `executionReport`
+     */
+    readonly isSuccessful: boolean;
+    /**
+     * Errors that occurred during the execution, details are available in `executionReport`
+     */
+    readonly errors: ReadonlyDeep<ReadonlyArray<ErrorJson>>;
+    /**
+     * Warnings that occurred during the execution, details are available in `executionReport`
+     */
+    readonly warnings: ReadonlyDeep<ReadonlyArray<ErrorJson>>;
+};
+/**
+ * TODO: [🧠] Should this file be in /execution or /types folder?
+ * TODO: [🧠] Maybe constrain `ErrorJson` -> `ErrorJson & { name: 'PipelineExecutionError' | 'Error' }`
+ */

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

@@ -0,0 +1,50 @@
+import type { ModelVariant } from '../types/ModelVariant';
+import type { number_usd } from '../types/typeAliases';
+import type { string_model_description } from '../types/typeAliases';
+import type { string_model_name } from '../types/typeAliases';
+import type { string_title } from '../types/typeAliases';
+/**
+ * Represents a model that can be used for prompt execution
+ */
+export type AvailableModel = {
+    /**
+     * The model title, when not provided, the `modelName` should be used
+     *
+     * @example "GPT o1"
+     */
+    readonly modelTitle?: string_title;
+    /**
+     * The model name aviailable
+     *
+     * @example "o1"
+     */
+    readonly modelName: string_model_name;
+    /**
+     * Variant of the model
+     *
+     * @example "CHAT"
+     */
+    readonly modelVariant: ModelVariant;
+    /**
+     * Unstructured description of the model
+     *
+     * This will be used to pick the best available model for each task
+     *
+     * @example "Model with 1 billion parameters and advanced reasoning capabilities"
+     */
+    readonly modelDescription?: string_model_description;
+    /**
+     * Pricing information for the model
+     */
+    readonly pricing?: {
+        readonly prompt: number_usd;
+        readonly output: number_usd;
+    };
+    /**
+     * If the model is deprecated, it should not be used for new tasks
+     */
+    readonly isDeprecated?: boolean;
+};
+/**
+ * TODO: [🧠] Maybe rename to something else - like `ModelInformation` or `ModelMetadata`
+ */

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

@@ -0,0 +1,28 @@
+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
+ */
+export type CommonToolsOptions = {
+    /**
+     * A unique identifier representing your end-user
+     *
+     * Note: For example it can help to detect abuse
+     * For example for OpenAi @see https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids
+     */
+    readonly userId?: string_user_id;
+    /**
+     * If true, the internal executions will be logged
+     */
+    readonly isVerbose?: boolean;
+    /**
+     * Maximum number of requests per minute
+     */
+    readonly maxRequestsPerMinute?: number;
+};
+/**
+ * TODO: [🧠][🤺] Maybe allow overriding of `userId` for each prompt
+ * TODO: [🈁] Maybe add here `isDeterministic`
+ * TODO: [🧠][💙] Distinct between options passed into ExecutionTools and to ExecutionTools.execute
+ */

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

@@ -0,0 +1,8 @@
+/**
+ * Represents a vector in an latent space of the embedding model
+ */
+export type EmbeddingVector = ReadonlyArray<number>;
+/**
+ * TODO: Figure out how to use NPM package xyzt
+ *       Not using IVectorData due to HUGE dimensionality
+ */

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

@@ -0,0 +1,18 @@
+import type { string_executable_path } from '../types/typeAliases';
+/**
+ * Paths to the external programs executables
+ */
+export type Executables = {
+    /**
+     * Path to the `pandoc` executable
+     *
+     * @example 'C:/Users/me/AppData/Local/Pandoc/pandoc.exe'
+     */
+    pandocPath?: string_executable_path;
+    /**
+     * Path to the LibreOffice executable
+     *
+     * @example 'C:/Program Files/LibreOffice/program/swriter.exe'
+     */
+    libreOfficePath?: string_executable_path;
+};

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

@@ -0,0 +1,145 @@
+import type { Observable } from 'rxjs';
+import { PartialDeep } from 'type-fest';
+import type { number_percent } from '../types/typeAliases';
+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';
+/**
+ * Options for creating a new task
+ */
+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 updateOngoingResult Function to update the partial result of the task processing
+     * @param updateTldr Function to update tldr progress information
+     * @returns The final task result
+     */
+    taskProcessCallback(updateOngoingResult: (newOngoingResult: PartialDeep<TTaskResult> & {
+        /**
+         * Optional update of the task title
+         */
+        readonly title?: AbstractTask<TTaskResult>['title'];
+    }) => void, updateTldr: (tldrInfo: {
+        readonly percent: number_percent;
+        readonly message: string;
+    }) => void): Promise<TTaskResult>;
+};
+/**
+ * Helper to create a new task
+ *
+ * @private internal helper function
+ */
+export declare function createTask<TTaskResult extends AbstractTaskResult>(options: CreateTaskOptions<TTaskResult>): AbstractTask<TTaskResult>;
+/**
+ * Represents a task that executes a pipeline
+ */
+export type ExecutionTask = AbstractTask<PipelineExecutorResult> & {
+    readonly taskType: 'EXECUTION';
+    readonly taskId: `exec-${task_id}`;
+};
+/**
+ * Represents a task that prepares a pipeline
+ * @deprecated TODO: [🐚] Currently unused - use
+ */
+export type PreparationTask = AbstractTask<PipelineExecutorResult> & {
+    readonly taskType: 'PREPARATION';
+    readonly taskId: `prep-${task_id}`;
+};
+/**
+ * Status of a task
+ */
+export type task_status = 'RUNNING' | 'FINISHED' | 'ERROR';
+/**
+ * Base interface for all task types
+ */
+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
+     *
+     * For example name of the book which is being executed
+     */
+    readonly title: string;
+    /**
+     * Status of the task
+     */
+    readonly status: task_status;
+    /**
+     * Short summary of the task status for quick overview in the UI
+     */
+    readonly tldr: {
+        /**
+         * Progress in percentage from 0 to 1 (100%) that can be used to display a progress bar
+         */
+        readonly percent: number_percent;
+        /**
+         * Short summary message of the task status that can be displayed in the UI
+         */
+        readonly message: string;
+    };
+    /**
+     * Date when the task was created
+     */
+    readonly createdAt: Date;
+    /**
+     * Date when the task was last updated
+     */
+    readonly updatedAt: Date;
+    /**
+     * Gets a promise that resolves with the task result
+     */
+    asPromise(options?: {
+        /**
+         * Do the task throws on error
+         *
+         * - If `true` when error occurs the returned promise will rejects
+         * - If `false` the promise will resolve with object with all listed errors and warnings and partial result
+         *
+         * @default true
+         */
+        readonly isCrashedOnError?: boolean;
+    }): Promise<TTaskResult>;
+    /**
+     * Gets an observable stream of partial task results
+     */
+    asObservable(): Observable<PartialDeep<TTaskResult>>;
+    /**
+     * Gets just the current value which is mutated during the task processing
+     */
+    readonly currentValue: PartialDeep<TTaskResult>;
+    /**
+     * List of errors that occurred during the task processing
+     */
+    readonly errors: Array<Error>;
+    /**
+     * List of warnings that occurred during the task processing
+     */
+    readonly warnings: Array<Error>;
+};
+export type Task = ExecutionTask | PreparationTask;
+export {};
+/**
+ * TODO: Maybe allow to terminate the task and add getter `isFinished` or `status`
+ * TODO: [🐚] Split into more files and make `PrepareTask` & `RemoteTask` + split the function
+ */

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

@@ -0,0 +1,69 @@
+import type { Scraper } from '../scrapers/_common/Scraper';
+import type { Arrayable } from '../types/Arrayable';
+import type { Executables } from './Executables';
+import type { FilesystemTools } from './FilesystemTools';
+import type { LlmExecutionTools } from './LlmExecutionTools';
+import type { PromptbookFetch } from './PromptbookFetch';
+import type { ScriptExecutionTools } from './ScriptExecutionTools';
+import type { UserInterfaceTools } from './UserInterfaceTools';
+/**
+ * All the tools needed to execute pipelines.
+ *
+ * @see https://github.com/webgptorg/promptbook#execution-tools
+ */
+export type ExecutionTools = {
+    /**
+     * Tools for executing prompts in large language models
+     *
+     * Tip: Use `$provideLlmToolsFromEnv` to use all available LLM providers you configured
+     *
+     * @default [] - If not provided, no LLM execution will be possible - it does not make sense in most cases
+     */
+    readonly llm?: Arrayable<LlmExecutionTools>;
+    /**
+     * Tools for filesystem operations
+     *
+     * Tip: Use `$provideFilesystemForNode` to use filesystem in Node.js
+     *
+     * @default undefined - If not provided, no filesystem operations will be possible
+     */
+    readonly fs?: FilesystemTools;
+    /**
+     * Fetch function for fetching resources
+     *
+     * @default `fetch` - If not provided, the built-in `fetch' function is used with a lightweight error handling wrapper.
+     */
+    readonly fetch?: PromptbookFetch;
+    /**
+     * Scrapers for extracting knowledge from external sources
+     *
+     * Tip: Use `$provideExecutablesForNode`
+     *
+     * @default [] - If not provided, no external knowledge extraction will be possible
+     */
+    readonly executables?: Executables;
+    /**
+     * Scrapers for extracting knowledge from external sources
+     *
+     * Tip: Use `$provideScrapersForNode` OR `$provideScrapersForBrowser` to use all available scrapers
+     *
+     * @default [] - If not provided, no external knowledge extraction will be possible
+     */
+    readonly scrapers?: Arrayable<Scraper>;
+    /**
+     * Tools for executing scripts
+     *
+     * Note: You can pass multiple ScriptExecutionTools, they will be tried one by one until one of them supports the script
+     *       If none of them supports the script, an error is thrown
+     * Tip: Use here `new JavascriptExecutionTools`
+     *
+     * @default [] - If not provided, no script execution will be possible
+     */
+    readonly script?: Arrayable<ScriptExecutionTools>;
+    /**
+     * Tools for interacting with the user
+     *
+     * Note: When undefined, the user interface is disabled and promptbook which requires user interaction will fail
+     */
+    readonly userInterface?: UserInterfaceTools;
+};

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

@@ -0,0 +1,9 @@
+/// <reference types="node" />
+import type fs from 'fs/promises';
+/**
+ * Container for all the tools needed to manipulate with filesystem
+ */
+export type FilesystemTools = Pick<typeof fs, 'access' | 'constants' | 'readFile' | 'writeFile' | 'stat' | 'readdir' | 'mkdir'>;
+/**
+ * TODO: Implement destroyable pattern to free resources
+ */

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

@@ -0,0 +1,61 @@
+import type { Promisable } from 'type-fest';
+import type { Prompt } from '../types/Prompt';
+import type { string_markdown } from '../types/typeAliases';
+import type { string_markdown_text } from '../types/typeAliases';
+import type { string_title } from '../types/typeAliases';
+import type { AvailableModel } from './AvailableModel';
+import type { ChatPromptResult } from './PromptResult';
+import type { CompletionPromptResult } from './PromptResult';
+import type { EmbeddingPromptResult } from './PromptResult';
+/**
+ * Container for all the tools needed to execute prompts to large language models like GPT-4
+ * On its interface it exposes common methods for prompt execution.
+ * Inside (in constructor) it calls OpenAI, Azure, GPU, proxy, cache, logging,...
+ *
+ * @see https://github.com/webgptorg/promptbook#llm-execution-tools
+ */
+export type LlmExecutionTools = {
+    /**
+     * Title of the model provider
+     *
+     * @example "OpenAI"
+     */
+    readonly title: string_title & string_markdown_text;
+    /**
+     * Description of the provider
+     *
+     * @example "Use all models from OpenAI"
+     */
+    readonly description?: string_markdown;
+    /**
+     * Check comfiguration
+     *
+     * @returns nothing if configuration is correct
+     * @throws {Error} if configuration is incorrect
+     */
+    checkConfiguration(): Promisable<void>;
+    /**
+     * List all available models that can be used
+     */
+    listModels(): Promisable<ReadonlyArray<AvailableModel>>;
+    /**
+     * Calls a chat model
+     */
+    callChatModel?(prompt: Prompt): Promise<ChatPromptResult>;
+    /**
+     * Calls a completion model
+     */
+    callCompletionModel?(prompt: Prompt): Promise<CompletionPromptResult>;
+    /**
+     * Calls an embedding model
+     */
+    callEmbeddingModel?(prompt: Prompt): Promise<EmbeddingPromptResult>;
+};
+/**
+ * TODO: [🍚] Implement destroyable pattern to free resources
+ * TODO: [🏳] Add `callTranslationModel`
+ * TODO: [🧠] Emulation of one type of model with another one - emuate chat with completion; emulate translation with chat
+ * TODO: [🍓][♐] Some heuristic to pick the best model in listed models
+ * TODO: [🧠] Should or should not there be a word "GPT" in both callCompletionModel and callChatModel
+ * TODO: [🧠][🪐] Should be common things like types, utils in folder containing A,B,C,.. or else outside this listing folder?
+ */