@promptbook/markdown-utils 0.61.0-10

package/esm/typings/src/config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The maximum number of iterations for a loops
+ */
+export declare const LOOP_LIMIT = 1000;
+/**
+ * The maximum number of iterations for a loops which adds characters one by one
+ */
+export declare const CHARACTER_LOOP_LIMIT = 100000;
+/**
+ * The maximum number of (LLM) tasks running in parallel
+ */
+export declare const MAX_PARALLEL_COUNT = 5;
+/**
+ * The name of the builded pipeline collection made by CLI `ptbk make` and for lookup in `createCollectionFromDirectory`
+ */
+export declare const PIPELINE_COLLECTION_BASE_FILENAME = "index";
+/**
+ * The names of the parameters that are reserved for special purposes
+ */
+export declare const RESERVED_PARAMETER_NAMES: string[];

package/esm/typings/src/conversion/pipelineJsonToString.d.ts

@@ -0,0 +1,14 @@
+import type { PipelineJson } from '../types/PipelineJson/PipelineJson';
+import type { PipelineString } from '../types/PipelineString';
+/**
+ * Converts promptbook in JSON format to string format
+ *
+ * @param pipelineJson Promptbook in JSON format (.ptbk.json)
+ * @returns Promptbook in string format (.ptbk.md)
+ */
+export declare function pipelineJsonToString(pipelineJson: PipelineJson): PipelineString;
+/**
+ * TODO: !!!!! Implement new features and commands into `promptTemplateParameterJsonToString`
+ * TODO: [🧠] Is there a way to auto-detect missing features in pipelineJsonToString
+ * TODO: Escape all
+ */

package/esm/typings/src/conversion/pipelineStringToJson.d.ts

@@ -0,0 +1,34 @@
+import type { LlmExecutionTools } from '../execution/LlmExecutionTools';
+import type { PipelineJson } from '../types/PipelineJson/PipelineJson';
+import type { PipelineString } from '../types/PipelineString';
+/**
+ * Options for `pipelineStringToJson`
+ */
+export type PipelineStringToJsonOptions = {
+    /**
+     * Tools for processing required for preparation of knowledge *(not for actual execution)*
+     *
+     * Note: If you provide `null`, the knowledge will not be prepared
+     */
+    readonly llmTools: LlmExecutionTools | null;
+};
+/**
+ * Compile pipeline from string (markdown) format to JSON format
+ *
+ * Note: There are 3 similar functions:
+ * - `pipelineStringToJson` **(preferred)** - which propperly compiles the promptbook and use embedding for external knowledge
+ * - `pipelineStringToJsonSync` - use only if you need to compile promptbook synchronously and it contains NO external knowledge
+ * - `preparePipeline` - just one step in the compilation process
+ *
+ * @param pipelineString {Promptbook} in string markdown format (.ptbk.md)
+ * @param options - Options and tools for the compilation
+ * @returns {Promptbook} compiled in JSON format (.ptbk.json)
+ * @throws {ParsingError} if the promptbook string is not valid
+ *
+ * Note: This function does not validate logic of the pipeline only the syntax
+ * Note: This function acts as compilation process
+ */
+export declare function pipelineStringToJson(pipelineString: PipelineString, options?: PipelineStringToJsonOptions): Promise<PipelineJson>;
+/**
+ * TODO: [🏏] Leverage the batch API and build queues @see https://platform.openai.com/docs/guides/batch
+ */

package/esm/typings/src/conversion/pipelineStringToJson.test.d.ts

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

package/esm/typings/src/conversion/pipelineStringToJsonSync.d.ts

@@ -0,0 +1,25 @@
+import type { PipelineJson } from '../types/PipelineJson/PipelineJson';
+import type { PipelineString } from '../types/PipelineString';
+/**
+ * Compile pipeline from string (markdown) format to JSON format synchronously
+ *
+ * Note: There are 3 similar functions:
+ * - `pipelineStringToJson` **(preferred)** - which propperly compiles the promptbook and use embedding for external knowledge
+ * - `pipelineStringToJsonSync` - use only if you need to compile promptbook synchronously and it contains NO external knowledge
+ * - `preparePipeline` - just one step in the compilation process
+ *
+ * @param pipelineString {Promptbook} in string markdown format (.ptbk.md)
+ * @returns {Promptbook} compiled in JSON format (.ptbk.json)
+ * @throws {ParsingError} if the promptbook string is not valid
+ *
+ * Note: This function does not validate logic of the pipeline only the syntax
+ * Note: This function acts as compilation process
+ */
+export declare function pipelineStringToJsonSync(pipelineString: PipelineString): PipelineJson;
+/**
+ * TODO: !!!! Warn if used only sync version
+ * TODO: [🚞] Report here line/column of error
+ * TODO: Use spaceTrim more effectively
+ * TODO: [🧠] Parameter flags - isInput, isOutput, isInternal
+ * TODO: [🥞] Not optimal parsing because `splitMarkdownIntoSections` is executed twice with same string, once through `flattenMarkdown` and second directly here
+ */

package/esm/typings/src/conversion/pipelineStringToJsonSync.test.d.ts

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

package/esm/typings/src/conversion/prettify/PrettifyOptions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Options for `prettifyPipelineString` function
+ */
+export type PrettifyOptions = {
+    /***
+     * If true, adds Mermaid graph to the Promptbook string
+     */
+    readonly isGraphAdded?: boolean;
+    /**
+     * If true, the string is prettifyed as markdown
+     */
+    readonly isPrettifyed?: boolean;
+};

package/esm/typings/src/conversion/prettify/prettifyPipelineString.d.ts

@@ -0,0 +1,10 @@
+import type { PipelineString } from '../../types/PipelineString';
+import type { PrettifyOptions } from './PrettifyOptions';
+/**
+ * Prettyfies Promptbook string and adds Mermaid graph
+ */
+export declare function prettifyPipelineString(pipelineString: PipelineString, options: PrettifyOptions): Promise<PipelineString>;
+/**
+ * TODO: Maybe use some Mermaid package instead of string templating
+ * TODO: [🕌] When more than 2 functionalities, split into separate functions
+ */

package/esm/typings/src/conversion/prettify/renderPipelineMermaidOptions.d.ts

@@ -0,0 +1,25 @@
+import type { PipelineJson } from '../../types/PipelineJson/PipelineJson';
+import type { PromptTemplateJson } from '../../types/PipelineJson/PromptTemplateJson';
+import type { string_href } from '../../types/typeAliases';
+/**
+ * Addtional options for rendering Mermaid graph
+ */
+export type renderPipelineMermaidOptions = {
+    /**
+     * Callback for creating from prompt template graph node
+     */
+    linkPromptTemplate?(promptTemplate: PromptTemplateJson): {
+        href: string_href;
+        title: string;
+    } | null;
+};
+/**
+ * Creates a Mermaid graph based on the promptbook
+ *
+ * Note: The result is not wrapped in a Markdown code block
+ */
+export declare function renderPromptbookMermaid(pipelineJson: PipelineJson, options?: renderPipelineMermaidOptions): string;
+/**
+ * TODO: Maybe use some Mermaid package instead of string templating
+ * TODO: [🕌] When more than 2 functionalities, split into separate functions
+ */

package/esm/typings/src/conversion/utils/extractParametersFromPromptTemplate.d.ts

@@ -0,0 +1,13 @@
+import type { PromptTemplateJson } from '../../types/PipelineJson/PromptTemplateJson';
+import type { string_name } from '../../types/typeAliases';
+/**
+ * Parses the prompt template and returns the set of all used parameters
+ *
+ * @param promptTemplate the template with used parameters
+ * @returns the set of parameter names
+ * @throws {ParsingError} if the script is invalid
+ */
+export declare function extractParametersFromPromptTemplate(promptTemplate: Pick<PromptTemplateJson, 'title' | 'description' | 'blockType' | 'content'>): Set<string_name>;
+/**
+ * TODO: [🔣] If script require contentLanguage
+ */

package/esm/typings/src/conversion/utils/extractParametersFromPromptTemplate.test.d.ts

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

package/esm/typings/src/conversion/utils/extractVariables.d.ts

@@ -0,0 +1,13 @@
+import type { string_javascript } from '../../types/typeAliases';
+import type { string_javascript_name } from '../../types/typeAliases';
+/**
+ * Parses the given script and returns the list of all used variables that are not defined in the script
+ *
+ * @param script from which to extract the variables
+ * @returns the list of variable names
+ * @throws {ParsingError} if the script is invalid
+ */
+export declare function extractVariables(script: string_javascript): Set<string_javascript_name>;
+/**
+ * TODO: [🔣] Support for multiple languages - python, java,...
+ */

package/esm/typings/src/conversion/utils/extractVariables.test.d.ts

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

package/esm/typings/src/conversion/utils/renameParameter.d.ts

@@ -0,0 +1,25 @@
+import type { PipelineJson } from '../../types/PipelineJson/PipelineJson';
+import type { string_name } from '../../types/typeAliases';
+type RenameParameterOptions = {
+    /**
+     * Pipeline to search and replace for parameters
+     * This pipeline is returned as copy with replaced parameters
+     */
+    readonly pipeline: PipelineJson;
+    /**
+     * Original parameter name that should be replaced
+     */
+    readonly oldParameterName: string_name;
+    /**
+     * New parameter name that should replace the original parameter name
+     */
+    readonly newParameterName: string_name;
+};
+/**
+ * Function renameParameter will find all usable parameters for given prompt template
+ * In other words, it will find all parameters that are not used in the prompt template itseld and all its dependencies
+ *
+ * @throws {PipelineLogicError} If the new parameter name is already used in the pipeline
+ */
+export declare function renameParameter(options: RenameParameterOptions): PipelineJson;
+export {};

package/esm/typings/src/conversion/utils/renameParameter.test.d.ts

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

package/esm/typings/src/conversion/utils/titleToName.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Function normalizes title to name which can be used as identifier
+ */
+export declare function titleToName(value: string): string;

package/esm/typings/src/conversion/utils/titleToName.test.d.ts

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

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 importPipelineWithoutPreparation(path: `${string}.ptbk.md`): PipelineString;
+export declare function importPipelineWithoutPreparation(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/VersionMismatch.d.ts

@@ -0,0 +1,8 @@
+import type { string_semantic_version } from '../types/typeAliases';
+/**
+ * This error type indicates that the version of the pipeline is not matching the expected version
+ */
+export declare class VersionMismatch extends Error {
+    readonly name = "UnexpectedError";
+    constructor(message: string, expectedVersion: string_semantic_version);
+}

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`
+         */
+        readonly isSuccessful: boolean;
+        /**
+         * Added usage of whole execution, detailed usage is aviable in `executionReport`
+         */
+        readonly usage: PromptResultUsage;
+        /**
+         * Errors that occured during the execution, details are aviable in `executionReport`
+         */
+        readonly errors: Array<Error>;
+        /**
+         * The report of the execution with all details
+         */
+        readonly executionReport: ExecutionReportJson;
+        /**
+         * Result parameters of the execution
+         *
+         * Note: If the execution was not successful, there are only some of the result parameters
+         */
+        readonly outputParameters: Record<string_name, string>;
+    }>;
+};
+/**
+ * TODO: [🧠] Should this file be in /execution or /types folder?
+ */