@promptbook/markdown-utils 0.61.0-7

package/esm/typings/src/conversion/validation/_importPipeline.d.ts

@@ -0,0 +1,13 @@
+import type { PipelineJson } from '../../types/PipelineJson/PipelineJson';
+import type { PipelineString } from '../../types/PipelineString';
+/**
+ * Import the text file
+ *
+ * Note: Using here custom import to work in jest tests
+ * Note: Using sync version is 💩 in the production code, but it's ok here in tests
+ *
+ * @param path - The path to the file relative to samples/templates directory
+ * @private
+ */
+export declare function importPipeline(path: `${string}.ptbk.md`): PipelineString;
+export declare function importPipeline(path: `${string}.ptbk.json`): PipelineJson;

package/esm/typings/src/conversion/validation/pipelineStringToJson-syntaxErrors.test.d.ts

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

package/esm/typings/src/conversion/validation/validatePipeline-logicErrors.test.d.ts

@@ -0,0 +1,4 @@
+export {};
+/**
+ * TODO: Include automatically all samples from logic errors folder (same with syntax errors)
+ */

package/esm/typings/src/conversion/validation/validatePipeline.d.ts

@@ -0,0 +1,27 @@
+import type { PipelineJson } from '../../types/PipelineJson/PipelineJson';
+/**
+ * Validates PipelineJson if it is logically valid
+ *
+ * It checks:
+ * -   if it has correct parameters dependency
+ *
+ * It does NOT check:
+ * -   if it is valid json
+ * -   if it is meaningful
+ *
+ * @param pipeline valid or invalid PipelineJson
+ * @returns the same pipeline if it is logically valid
+ * @throws {PipelineLogicError} on logical error in the pipeline
+ */
+export declare function validatePipeline(pipeline: PipelineJson): PipelineJson;
+/**
+ * TODO: [🧠] Work with promptbookVersion
+ * TODO: Use here some json-schema, Zod or something similar and change it to:
+ *     > /**
+ *     >  * Validates PipelineJson if it is logically valid.
+ *     >  *
+ *     >  * It checks:
+ *     >  * -   it has a valid structure
+ *     >  * -   ...
+ *     >  ex port function validatePipeline(promptbook: unknown): asserts promptbook is PipelineJson {
+ */

package/esm/typings/src/conversion/validation/validatePipeline.test.d.ts

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

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

@@ -0,0 +1,7 @@
+/**
+ * This error indicates that the pipeline collection cannot be propperly loaded
+ */
+export declare class CollectionError extends Error {
+    readonly name = "CollectionError";
+    constructor(message: string);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * This error indicates that promptbook not found in the collection
+ */
+export declare class NotFoundError extends Error {
+    readonly name = "NotFoundError";
+    constructor(message: string);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * This error type indicates that some part of the code is not implemented yet
+ */
+export declare class NotYetImplementedError extends Error {
+    readonly name = "NotYetImplementedError";
+    constructor(message: string);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
+ */
+export declare class ParsingError extends Error {
+    readonly name = "ParsingError";
+    constructor(message: string);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * This error indicates errors during the execution of the pipeline
+ */
+export declare class PipelineExecutionError extends Error {
+    readonly name = "PipelineExecutionError";
+    constructor(message: string);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * This error indicates that the promptbook object has valid syntax but contains logical errors (like circular dependencies)
+ */
+export declare class PipelineLogicError extends Error {
+    readonly name = "PipelineLogicError";
+    constructor(message: string);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * This error indicates errors in referencing promptbooks between each other
+ */
+export declare class ReferenceError extends Error {
+    readonly name = "ReferenceError";
+    constructor(message: string);
+}

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

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

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

@@ -0,0 +1,10 @@
+/**
+ * This error occurs when some expectation is not met in the execution of the pipeline
+ *
+ * @private Always catched and rethrown as `PipelineExecutionError`
+ * Note: This is a kindof subtype of PipelineExecutionError
+ */
+export declare class ExpectError extends Error {
+    readonly name = "ExpectError";
+    constructor(message: string);
+}

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

@@ -0,0 +1,9 @@
+export type CommonExecutionToolsOptions = {
+    /**
+     * If true, the internal executions will be logged
+     */
+    readonly isVerbose?: boolean;
+};
+/**
+ * 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,33 @@
+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 to large language models like GPT-4
+     *
+     * Tip: Combine multiple LLM execution tools - use array of LlmExecutionTools instead of single LlmExecutionTools
+     * @see https://github.com/webgptorg/promptbook/?tab=readme-ov-file#llm-execution-tools
+     */
+    llm?: Arrayable<LlmExecutionTools>;
+    /**
+     * 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
+     * @see https://github.com/webgptorg/promptbook/?tab=readme-ov-file#script-execution-tools
+     */
+    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
+     * @see https://github.com/webgptorg/promptbook/?tab=readme-ov-file#user-interface-tools
+     */
+    userInterface?: UserInterfaceTools;
+};

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

@@ -0,0 +1,70 @@
+import type { Promisable } from 'type-fest';
+import type { ModelVariant } from '../types/ModelRequirements';
+import type { Prompt } from '../types/Prompt';
+import type { string_markdown } from '../types/typeAliases';
+import type { string_markdown_text } from '../types/typeAliases';
+import type { string_model_name } from '../types/typeAliases';
+import type { string_title } from '../types/typeAliases';
+import type { PromptChatResult } from './PromptResult';
+import type { PromptCompletionResult } from './PromptResult';
+import type { PromptEmbeddingResult } 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;
+    /**
+     * Calls a chat model
+     */
+    callChatModel?(prompt: Prompt): Promise<PromptChatResult>;
+    /**
+     * Calls a completion model
+     */
+    callCompletionModel?(prompt: Prompt): Promise<PromptCompletionResult>;
+    /**
+     * Calls an embedding model
+     */
+    callEmbeddingModel?(prompt: Prompt): Promise<PromptEmbeddingResult>;
+    /**
+     * List all available models that can be used
+     */
+    listModels(): Promisable<Array<AvailableModel>>;
+};
+/**
+ * Represents a model that can be used for prompt execution
+ */
+export type AvailableModel = {
+    /**
+     * The model title
+     */
+    readonly modelTitle: string_title;
+    /**
+     * The model name aviailable
+     */
+    readonly modelName: string_model_name;
+    /**
+     * Variant of the model
+     */
+    readonly modelVariant: ModelVariant;
+};
+/**
+ * TODO: !!!! Translation model
+ * 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
+ */

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

@@ -0,0 +1,42 @@
+import type { Promisable } from 'type-fest';
+import type { TaskProgress } from '../types/TaskProgress';
+import type { ExecutionReportJson } from '../types/execution-report/ExecutionReportJson';
+import type { string_name } from '../types/typeAliases';
+import type { PromptResultUsage } from './PromptResult';
+/**
+ * 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: Record<string_name, string>, onProgress?: (taskProgress: TaskProgress) => Promisable<void>): Promise<{
+        /**
+         * Whether the execution was successful, details are aviable in `executionReport`
+         */
+        isSuccessful: boolean;
+        /**
+         * Added usage of whole execution, detailed usage is aviable in `executionReport`
+         */
+        usage: PromptResultUsage;
+        /**
+         * Errors that occured during the execution, details are aviable in `executionReport`
+         */
+        errors: Array<Error>;
+        /**
+         * The report of the execution with all details
+         */
+        executionReport: ExecutionReportJson;
+        /**
+         * Result parameters of the execution
+         *
+         * Note: If the execution was not successful, there are only some of the result parameters
+         */
+        outputParameters: Record<string_name, string>;
+    }>;
+};
+/**
+ * TODO: [🧠] Should this file be in /execution or /types folder?
+ */

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

@@ -0,0 +1,114 @@
+import type { KebabCase } from 'type-fest';
+import type { ExpectationUnit } from '../types/PipelineJson/Expectations';
+import type { number_positive } from '../types/typeAliases';
+import type { number_usd } from '../types/typeAliases';
+import type { string_date_iso8601 } from '../types/typeAliases';
+import type { string_model_name } from '../types/typeAliases';
+import type { EmbeddingVector } from './EmbeddingVector';
+/**
+ * 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 = PromptCompletionResult | PromptChatResult | PromptEmbeddingResult;
+/**
+ * Prompt completion result
+ * It contains only the following text NOT the whole completion
+ */
+export type PromptCompletionResult = PromptCommonResult;
+/**
+ * Prompt chat result
+ */
+export type PromptChatResult = PromptCommonResult & {};
+/**
+ * Prompt embedding result
+ * It contains only the following text NOT the whole completion
+ */
+export type PromptEmbeddingResult = Omit<PromptCommonResult, 'content'> & {
+    /**
+     * The response from the model
+     */
+    content: EmbeddingVector;
+};
+export type PromptCommonResult = {
+    /**
+     * 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
+         */
+        start: string_date_iso8601;
+        /**
+         * First token generated
+         */
+        firstToken?: string_date_iso8601;
+        /**
+         * End of the execution
+         */
+        complete: string_date_iso8601;
+    };
+    /**
+     * Usage of the prompt execution
+     */
+    readonly usage: PromptResultUsage;
+    /**
+     * Raw response from the model
+     */
+    readonly rawResponse: object;
+};
+/**
+ * Usage statistics for one or many prompt results
+ */
+export type PromptResultUsage = {
+    /**
+     * Cost of the execution in USD
+     *
+     * Note: If the cost is unknown, the value 0 and isUncertain is true
+     */
+    price: UncertainNumber;
+    /**
+     * Number of whatever used in the input aka. `prompt_tokens`
+     */
+    input: PromptResultUsageCounts;
+    /**
+     * Number of tokens used in the output aka. `completion_tokens`
+     */
+    output: PromptResultUsageCounts;
+};
+/**
+ * Record of all possible measurable units
+ */
+export type PromptResultUsageCounts = Record<`${KebabCase<'TOKENS' | ExpectationUnit>}Count`, UncertainNumber>;
+/**
+ * Number which can be uncertain
+ *
+ * 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
+     */
+    value: number_usd & (number_positive | 0);
+    /**
+     * Is the value uncertain
+     */
+    isUncertain?: true;
+};
+/**
+ * TODO: [🧠] Maybe timing more accurate then seconds?
+ * TODO: [🧠] Should here be link to the prompt?
+ * TODO: [🧠] Maybe type raw 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
+ */

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

@@ -0,0 +1,38 @@
+import type { ScriptLanguage } from '../types/ScriptLanguage';
+import type { string_name } from '../types/typeAliases';
+import type { string_script } from '../types/typeAliases';
+/**
+ * Represents all the tools needed to EXECUTE SCRIPTs
+ *
+ * @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
+     */
+    scriptLanguage: ScriptLanguage;
+    /**
+     * Parameters for the script
+     * Theese parameters are passed to the script as variables
+     * For example: { "name": "John" } => const name = "John";
+     */
+    parameters: Record<string_name, string>;
+    /**
+     * 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
+     */
+    script: string_script;
+};
+/**
+ * TODO: [🧠][💙] Distinct between options passed into ExecutionTools and to ExecutionTools.execute
+ */

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"
+     */
+    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."
+     */
+    promptMessage: string;
+    /**
+     * Default value for the input/textarea
+     */
+    defaultValue: string | null;
+    /**
+     * Placeholder for the input/textarea
+     */
+    placeholder?: string;
+    /**
+     * Priority of the prompt
+     *
+     * Note: This would be reflected for example into the UI z-index of the prompt modal
+     */
+    priority: number_integer & number_positive;
+};

package/esm/typings/src/execution/addPromptResultUsage.test.d.ts

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

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

@@ -0,0 +1,11 @@
+import type { PipelineExecutor } from './PipelineExecutor';
+/**
+ * Asserts that the execution of a promptnook is successful
+ *
+ * @param executionResult - The partial result of the promptnook execution
+ * @throws {PipelineExecutionError} If the execution is not successful or if multiple errors occurred
+ */
+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.d.ts

@@ -0,0 +1,42 @@
+import type { PipelineJson } from '../types/PipelineJson/PipelineJson';
+import type { ExecutionTools } from './ExecutionTools';
+import type { PipelineExecutor } from './PipelineExecutor';
+type CreatePipelineExecutorSettings = {
+    /**
+     * When executor does not satisfy expectations it will be retried this amount of times
+     *
+     * @default 3
+     */
+    readonly maxExecutionAttempts: number;
+};
+/**
+ * Options for creating a pipeline executor
+ */
+interface 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>;
+}
+/**
+ * Creates executor function from pipeline and execution tools.
+ *
+ * @returns The executor function
+ * @throws {PipelineLogicError} on logical error in the pipeline
+ */
+export declare function createPipelineExecutor(options: CreatePipelineExecutorOptions): PipelineExecutor;
+export {};
+/**
+ * TODO: [🧠] When not meet expectations in PROMPT_DIALOG, make some way to tell the user
+ * TODO: [👧] Strongly type the executors to avoid need of remove nullables whtn noUncheckedIndexedAccess in tsconfig.json
+ * Note: CreatePipelineExecutorOptions are just connected to PipelineExecutor so do not extract to types folder
+ * TODO: [🧠][3] transparent = (report intermediate parameters) / opaque execution = (report only output parameters) progress reporting mode
+ */

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

@@ -0,0 +1,5 @@
+import type { EmbeddingVector } from './EmbeddingVector';
+/**
+ * Pretty print an embedding vector for logging
+ */
+export declare function embeddingVectorToString(embeddingVector: EmbeddingVector): string;

package/esm/typings/src/execution/translation/automatic-translate/automatic-translators/AutomaticTranslator.d.ts

@@ -0,0 +1,4 @@
+import type { Promisable } from 'type-fest';
+export type AutomaticTranslator = {
+    translate(message: string): Promisable<string>;
+};

package/esm/typings/src/execution/translation/automatic-translate/automatic-translators/DebugAutomaticTranslator.d.ts

@@ -0,0 +1,9 @@
+import type { AutomaticTranslator } from './AutomaticTranslator';
+/**
+ * This will wrap an automatic translator and log each translation into the console
+ */
+export declare class DebugAutomaticTranslator implements AutomaticTranslator {
+    private readonly automaticTranslator;
+    constructor(automaticTranslator: AutomaticTranslator);
+    translate(message: string): Promise<string>;
+}

package/esm/typings/src/execution/translation/automatic-translate/automatic-translators/FakeAutomaticTranslator.d.ts

@@ -0,0 +1,5 @@
+import type { AutomaticTranslator } from './AutomaticTranslator';
+export declare class FakeAutomaticTranslator implements AutomaticTranslator {
+    constructor();
+    translate(message: string): string;
+}

package/esm/typings/src/execution/translation/automatic-translate/automatic-translators/LindatAutomaticTranslator.d.ts

@@ -0,0 +1,11 @@
+import type { AutomaticTranslator } from './AutomaticTranslator';
+import type { TranslatorOptions } from './TranslatorOptions';
+interface LindatAutomaticTranslatorOptions extends TranslatorOptions {
+    apiUrl?: URL;
+}
+export declare class LindatAutomaticTranslator implements AutomaticTranslator {
+    private readonly options;
+    constructor(options: LindatAutomaticTranslatorOptions);
+    translate(message: string): Promise<string>;
+}
+export {};

package/esm/typings/src/execution/translation/automatic-translate/automatic-translators/TranslatorOptions.d.ts

@@ -0,0 +1,4 @@
+export type TranslatorOptions = {
+    from?: string;
+    to: string;
+};

package/esm/typings/src/execution/translation/automatic-translate/automatic-translators/utils/extractMultiplicatedOccurrence.d.ts

@@ -0,0 +1,7 @@
+/**
+ *
+ * @param message
+ * @returns
+ * @throws {PipelineExecutionError}
+ */
+export declare function extractMultiplicatedOccurrence(message: string): string;

package/esm/typings/src/execution/translation/automatic-translate/automatic-translators/utils/extractMultiplicatedOccurrence.test.d.ts

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

package/esm/typings/src/execution/translation/automatic-translate/translateMessages.d.ts

@@ -0,0 +1,5 @@
+import type { AutomaticTranslator } from './automatic-translators/AutomaticTranslator';
+import type { TranslatorOptions } from './automatic-translators/TranslatorOptions';
+export declare function translateMessages({ automaticTranslator, from, to, }: {
+    automaticTranslator: AutomaticTranslator;
+} & TranslatorOptions): Promise<void>;

package/esm/typings/src/execution/utils/addUsage.d.ts

@@ -0,0 +1,7 @@
+import type { PromptResultUsage } from '../PromptResult';
+/**
+ * Function `addUsage` will add multiple usages into one
+ *
+ * Note: If you provide 0 values, it returns void usage
+ */
+export declare function addUsage(...usageItems: Array<PromptResultUsage>): PromptResultUsage;

package/esm/typings/src/execution/utils/addUsage.test.d.ts

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