@promptbook/legacy-documents 0.71.0-12

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

@@ -0,0 +1,15 @@
+/**
+ * @@@
+ *
+ * Note: Keep it public to allow people to make their own execution tools
+ */
+export type CommonToolsOptions = {
+    /**
+     * If true, the internal executions will be logged
+     */
+    readonly isVerbose?: boolean;
+};
+/**
+ * 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 = Array<number>;
+/**
+ * TODO: Figure out how to use NPM package xyzt
+ *       Not using IVectorData due to HUGE dimensionality
+ */

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

@@ -0,0 +1,48 @@
+import type { Scraper } from '../scrapers/_common/Scraper';
+import type { Arrayable } from '../types/Arrayable';
+import type { LlmExecutionTools } from './LlmExecutionTools';
+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>;
+    /**
+     * 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;
+};
+/**
+ * TODO: [🍂] Maybe make llm = $provideLlmToolsFromEnv() without problem with bundle contaminated by only `@promptbook/node` and `@promptbook/cli` stuff
+ * TODO: [🍂] Same with scrapers
+ */

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<Array<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?
+ */

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

@@ -0,0 +1,10 @@
+import type { Registered } from '../utils/$Register';
+import type { TODO_any } from '../utils/organization/TODO_any';
+import type { LlmExecutionTools } from './LlmExecutionTools';
+/**
+ * @@@
+ */
+export type LlmExecutionToolsConstructor = Registered & ((options: TODO_any) => LlmExecutionTools);
+/**
+ * TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
+ */

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

@@ -0,0 +1,19 @@
+import type { Promisable } from 'type-fest';
+import type { TaskProgress } from '../types/TaskProgress';
+import type { Parameters } from '../types/typeAliases';
+import type { PipelineExecutorResult } from './PipelineExecutorResult';
+/**
+ * Executor is a simple async function that takes INPUT  PARAMETERs and returns result parameters _(along with all intermediate parameters and INPUT  PARAMETERs = it extends input object)_.
+ * Executor is made by combining execution tools and pipeline collection.
+ *
+ * It can be created with `createPipelineExecutor` function.
+ *
+ * @see https://github.com/webgptorg/promptbook#executor
+ */
+export type PipelineExecutor = {
+    (inputParameters: Parameters, onProgress?: (taskProgress: TaskProgress) => Promisable<void>): Promise<PipelineExecutorResult>;
+};
+/**
+ * TODO: [🐚] Change onProgress to object that represents the running execution, can be subscribed via RxJS to and also awaited
+ * TODO: [🧠] Should this file be in /execution or /types folder?
+ */

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

@@ -0,0 +1,50 @@
+import { ReadonlyDeep } from 'type-fest';
+import type { ErrorJson } from '../errors/utils/ErrorJson';
+import type { ExecutionReportJson } from '../types/execution-report/ExecutionReportJson';
+import type { PipelineJson } from '../types/PipelineJson/PipelineJson';
+import type { Parameters } from '../types/typeAliases';
+import type { PromptResultUsage } from './PromptResultUsage';
+/**
+ * @@@
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type PipelineExecutorResult = {
+    /**
+     * Result parameters of the execution
+     *
+     * Note: If the execution was not successful, there are only some of the result parameters
+     */
+    readonly outputParameters: Readonly<Parameters>;
+    /**
+     * Whether the execution was successful, details are aviable in `executionReport`
+     */
+    readonly isSuccessful: boolean;
+    /**
+     * Added usage of whole execution, detailed usage is aviable in `executionReport`
+     */
+    readonly usage: ReadonlyDeep<PromptResultUsage>;
+    /**
+     * Errors that occured during the execution, details are aviable in `executionReport`
+     */
+    readonly errors: ReadonlyDeep<Array<ErrorJson>>;
+    /**
+     * Warnings that occured during the execution, details are aviable in `executionReport`
+     */
+    readonly warnings: ReadonlyDeep<Array<ErrorJson>>;
+    /**
+     * The report of the execution with all details
+     */
+    readonly executionReport: ReadonlyDeep<ExecutionReportJson>;
+    /**
+     * The prepared pipeline that was used for the execution
+     *
+     * Note: If you called `createPipelineExecutor` with fully prepared pipeline, this is the same object as this pipeline
+     *       If you passed not fully prepared pipeline, this is same pipeline but fully prepared
+     */
+    readonly preparedPipeline: ReadonlyDeep<PipelineJson>;
+};
+/**
+ * TODO: [🧠] Should this file be in /execution or /types folder?
+ * TODO: [🧠] Maybe constrain `ErrorJson` -> `ErrorJson & { name: 'PipelineExecutionError' | 'Error' }`
+ */

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

@@ -0,0 +1,101 @@
+import type { string_date_iso8601 } from '../types/typeAliases';
+import type { string_model_name } from '../types/typeAliases';
+import type { string_prompt } from '../types/typeAliases';
+import type { TODO_object } from '../utils/organization/TODO_object';
+import type { EmbeddingVector } from './EmbeddingVector';
+import type { PromptResultUsage } from './PromptResultUsage';
+/**
+ * Prompt result is the simplest concept of execution.
+ * It is the result of executing one prompt _(NOT a template)_.
+ *
+ * @see https://github.com/webgptorg/promptbook#prompt-result
+ */
+export type PromptResult = CompletionPromptResult | ChatPromptResult | EmbeddingPromptResult;
+/**
+ * Completion prompt result
+ *
+ * Note:It contains only the newly generated text NOT the whole completion
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type CompletionPromptResult = CommonPromptResult;
+/**
+ *Chat prompt result
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type ChatPromptResult = CommonPromptResult & {};
+/**
+ * Embedding prompt  result
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type EmbeddingPromptResult = Omit<CommonPromptResult, 'content'> & {
+    /**
+     * The response from the model
+     */
+    content: EmbeddingVector;
+};
+/**
+ * Common properties for all prompt results
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private just abstract the common properties of the prompt results
+ */
+export type CommonPromptResult = {
+    /**
+     * Exact text response from the model
+     */
+    readonly content: string;
+    /**
+     * Name of the model used to generate the response
+     */
+    readonly modelName: string_model_name;
+    /**
+     * Timing
+     */
+    readonly timing: {
+        /**
+         * Start of the execution
+         */
+        readonly start: string_date_iso8601;
+        /**
+         * First token generated
+         */
+        readonly firstToken?: string_date_iso8601;
+        /**
+         * End of the execution
+         */
+        readonly complete: string_date_iso8601;
+    };
+    /**
+     * Usage of the prompt execution
+     */
+    readonly usage: PromptResultUsage;
+    /**
+     * Exact text of the prompt (with all replacements)
+     *
+     * Note: This contains redundant information
+     */
+    readonly rawPromptContent: string_prompt;
+    /**
+     * Raw request to the model
+     *
+     * Note: This contains redundant information
+     */
+    readonly rawRequest: TODO_object | null;
+    /**
+     * Raw response from the model
+     *
+     * Note: This contains redundant information
+     */
+    readonly rawResponse: TODO_object;
+};
+/**
+ * TODO: [🧠] Maybe timing more accurate then seconds?
+ * TODO: [🧠] Should here be link to the prompt?
+ * TODO: [🧠] Maybe type `rawResponse` properly - not onject but OpenAI.result.whatever
+ * TODO: [🧠] Maybe remove redundant raw.choices.text
+ * TODO: Log raw even if prompt failed - log the raw error
+ * TODO: [🏳] Add `TranslationPromptResult`
+ */

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

@@ -0,0 +1,33 @@
+import type { KebabCase } from 'type-fest';
+import type { ExpectationUnit } from '../types/PipelineJson/Expectations';
+import type { UncertainNumber } from './UncertainNumber';
+/**
+ * Usage statistics for one or many prompt results
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type PromptResultUsage = {
+    /**
+     * Cost of the execution in USD
+     *
+     * Note: If the cost is unknown, the value 0 and isUncertain is true
+     */
+    readonly price: UncertainNumber;
+    /**
+     * Number of whatever used in the input aka. `prompt_tokens`
+     */
+    readonly input: PromptResultUsageCounts;
+    /**
+     * Number of tokens used in the output aka. `completion_tokens`
+     */
+    readonly output: PromptResultUsageCounts;
+};
+/**
+ * Record of all possible measurable units
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type PromptResultUsageCounts = Record<`${KebabCase<'TOKENS' | ExpectationUnit>}Count`, UncertainNumber>;
+/**
+ * TODO: [🍙] Make some standard order of json properties
+ */

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

@@ -0,0 +1,39 @@
+import type { ScriptLanguage } from '../types/ScriptLanguage';
+import type { Parameters } from '../types/typeAliases';
+import type { string_script } from '../types/typeAliases';
+/**
+ * Represents all the tools needed to execute SCRIPT TEMPLATE
+ *
+ * @see https://github.com/webgptorg/promptbook#script-execution-tools
+ */
+export type ScriptExecutionTools = {
+    execute(options: ScriptExecutionToolsExecuteOptions): Promise<string>;
+};
+/**
+ * Input for the script execution
+ */
+export type ScriptExecutionToolsExecuteOptions = {
+    /**
+     * Language of the script
+     */
+    readonly scriptLanguage: ScriptLanguage;
+    /**
+     * Parameters for the script
+     * Theese parameters are passed to the script as variables
+     * For example: { "name": "John" } => const name = "John";
+     */
+    readonly parameters: Parameters;
+    /**
+     * The content of the script to execute
+     * - It can be a single statement
+     * - It can be multiple statements separated by semicolon and return
+     * - It can be a function (but you need to call it)
+     * - It can be IIFE (immediately invoked function expression)
+     * - It can use the parameters as variables and functions from global scope
+     */
+    readonly script: string_script;
+};
+/**
+ * TODO: [🧠][💙] Distinct between options passed into ExecutionTools and to ExecutionTools.execute
+ * TODO: [🧠][🪐] Should be common things like types, utils in folder containing A,B,C,.. or else outside this listing folder?
+ */

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

@@ -0,0 +1,19 @@
+import type { number_positive } from '../types/typeAliases';
+import type { number_usd } from '../types/typeAliases';
+/**
+ * Number which can be uncertain
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ * Note: If the value is completelly unknown, the value 0 and isUncertain is true
+ * Note: Not using NaN or null because it looses the value which is better to be uncertain then not to be at all
+ */
+export type UncertainNumber = {
+    /**
+     * The numeric value
+     */
+    readonly value: number_usd & (number_positive | 0);
+    /**
+     * Is the value uncertain
+     */
+    readonly isUncertain?: true;
+};

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/assertsExecutionSuccessful.d.ts

@@ -0,0 +1,12 @@
+import type { PipelineExecutor } from './PipelineExecutor';
+/**
+ * Asserts that the execution of a Promptbook is successful
+ *
+ * @param executionResult - The partial result of the Promptbook execution
+ * @throws {PipelineExecutionError} If the execution is not successful or if multiple errors occurred
+ * @public exported from `@promptbook/core`
+ */
+export declare function assertsExecutionSuccessful(executionResult: Pick<Awaited<ReturnType<PipelineExecutor>>, 'isSuccessful' | 'errors'>): void;
+/**
+ * TODO: [🧠] Can this return type be better typed than void
+ */

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

@@ -0,0 +1,45 @@
+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';
+/**
+ * @@@
+ *
+ * @private internal utility of `createPipelineExecutor`
+ */
+export type $OngoingTemplateResult = {
+    /**
+     * @@@
+     */
+    $prompt?: Prompt;
+    /**
+     * @@@
+     */
+    $chatResult?: ChatPromptResult;
+    /**
+     * @@@
+     */
+    $completionResult?: CompletionPromptResult;
+    /**
+     * @@@
+     */
+    $embeddingResult?: EmbeddingPromptResult;
+    /**
+     * @@@
+     */
+    $result: PromptResult | null;
+    /**
+     * @@@
+     */
+    $resultString: string | null;
+    /**
+     * @@@
+     */
+    $expectError: ExpectError | null;
+    /**
+     * @@@
+     */
+    $scriptPipelineExecutionErrors: Array<Error>;
+};

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

@@ -0,0 +1,23 @@
+import type { PipelineJson } from '../../types/PipelineJson/PipelineJson';
+import type { ExecutionTools } from '../ExecutionTools';
+import type { CreatePipelineExecutorSettings } from './00-CreatePipelineExecutorSettings';
+/**
+ * Options for `createPipelineExecutor`
+ */
+export type CreatePipelineExecutorOptions = {
+    /**
+     * The pipeline to be executed
+     */
+    readonly pipeline: PipelineJson;
+    /**
+     * The execution tools to be used during the execution of the pipeline
+     */
+    readonly tools: ExecutionTools;
+    /**
+     * Optional settings for the pipeline executor
+     */
+    readonly settings?: Partial<CreatePipelineExecutorSettings>;
+};
+/**
+ * TODO: !!!!!! Unite `CreatePipelineExecutorOptions` and `CreatePipelineExecutorSettings` OR describe the difference
+ */ 

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

@@ -0,0 +1,29 @@
+import type { CsvSettings } from '../../formats/csv/CsvSettings';
+import type { PrepareAndScrapeOptions } from '../../prepare/PrepareAndScrapeOptions';
+export type CreatePipelineExecutorSettings = Omit<PrepareAndScrapeOptions, 'llmTools'> & {
+    /**
+     * 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 isNotPreparedWarningSupressed: boolean;
+};
+/**
+ * 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,13 @@
+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;
+/**
+ * TODO: [🐚] Change onProgress to object that represents the running execution, can be subscribed via RxJS to and also awaited
+ */

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

@@ -0,0 +1,58 @@
+import type { Promisable, ReadonlyDeep } from 'type-fest';
+import type { PipelineJson } from '../../types/PipelineJson/PipelineJson';
+import type { TaskProgress } from '../../types/TaskProgress';
+import type { Parameters } from '../../types/typeAliases';
+import type { ExecutionTools } from '../ExecutionTools';
+import type { PipelineExecutorResult } from '../PipelineExecutorResult';
+import type { CreatePipelineExecutorSettings } from './00-CreatePipelineExecutorSettings';
+/**
+ * @@@
+ *
+ * @private internal type of `executePipeline`
+ */
+type ExecutePipelineOptions = {
+    /**
+     * @@@
+     */
+    readonly inputParameters: Readonly<Parameters>;
+    /**
+     * @@@
+     */
+    readonly tools: ExecutionTools;
+    /**
+     * @@@
+     */
+    onProgress?(taskProgress: TaskProgress): Promisable<void>;
+    /**
+     * @@@
+     */
+    readonly pipeline: PipelineJson;
+    /**
+     * @@@
+     */
+    readonly preparedPipeline: ReadonlyDeep<PipelineJson>;
+    /**
+     * @@@
+     */
+    readonly setPreparedPipeline: (preparedPipeline: ReadonlyDeep<PipelineJson>) => void;
+    /**
+     * @@@
+     */
+    readonly pipelineIdentification: string;
+    /**
+     * Settings for the pipeline executor
+     */
+    readonly settings: CreatePipelineExecutorSettings;
+};
+/**
+ * @@@
+ *
+ * Note: This is not a `PipelineExecutor` (which is binded with one exact pipeline), but a utility function of `createPipelineExecutor` which creates `PipelineExecutor`
+ *
+ * @private internal utility of `createPipelineExecutor`
+ */
+export declare function executePipeline(options: ExecutePipelineOptions): Promise<PipelineExecutorResult>;
+export {};
+/**
+ * TODO: [🐚] Change onProgress to object that represents the running execution, can be subscribed via RxJS to and also awaited
+ */