@promptbook/markdown-utils 0.61.0-10

package/esm/typings/src/types/PipelineJson/PersonaJson.d.ts

@@ -0,0 +1,40 @@
+import type { ModelRequirements } from '../ModelRequirements';
+import type { number_id } from '../typeAliases';
+import type { string_name } from '../typeAliases';
+import type { string_persona_description } from '../typeAliases';
+/**
+ * Defines a persona in the pipeline
+ *
+ * @see https://github.com/webgptorg/promptbook/discussions/22
+ */
+export type PersonaJson = {
+    /**
+     * Name of the template
+     * - It must be unique across the pipeline
+     * - It should start uppercase and can contain letters and numbers
+     */
+    readonly name: string_name;
+    /**
+     * Description of persona
+     */
+    readonly description: string_persona_description;
+};
+/**
+ * Defines a persona in the pipeline after it has been prepared
+ *
+ * @see https://github.com/webgptorg/promptbook/discussions/22
+ */
+export type PersonaPreparedJson = PersonaJson & {
+    /**
+     * Model requirements for the persona
+     *
+     * Note: The model must be CHAT variant to be usable through persona
+     */
+    readonly modelRequirements: ModelRequirements & {
+        readonly modelVariant: 'CHAT';
+    };
+    /**
+     * List of preparation ids that were used to prepare this persona
+     */
+    readonly preparationIds: Array<number_id>;
+};

package/esm/typings/src/types/PipelineJson/PipelineJson.d.ts

@@ -0,0 +1,86 @@
+import type { string_file_path } from '../typeAliases';
+import type { string_markdown_text } from '../typeAliases';
+import type { string_pipeline_url } from '../typeAliases';
+import type { string_semantic_version } from '../typeAliases';
+import type { KnowledgePiecePreparedJson } from './KnowledgePieceJson';
+import type { KnowledgeSourceJson } from './KnowledgeSourceJson';
+import type { KnowledgeSourcePreparedJson } from './KnowledgeSourceJson';
+import type { PersonaJson } from './PersonaJson';
+import type { PersonaPreparedJson } from './PersonaJson';
+import type { PreparationJson } from './PreparationJson';
+import type { PromptTemplateJson } from './PromptTemplateJson';
+import type { PromptTemplateParameterJson } from './PromptTemplateParameterJson';
+/**
+ * Promptbook is the **core concept of this package**.
+ * It represents a series of prompt templates chained together to form a pipeline / one big prompt template with input and result parameters.
+ *
+ * @see !!! https://github.com/webgptorg/promptbook#promptbook
+ */
+export type PipelineJson = {
+    /**
+     * Unique identifier of the pipeline
+     *
+     * Note: It must be unique across all pipeline collections
+     * Note: It must use HTTPs URL
+     * Tip: You can do versioning in the URL
+     *      For example: https://promptbook.studio/webgpt/write-website-content-cs.ptbk.md@1.0.0
+     * Warning: Do not hash part of the URL, hash part is used for identification of the prompt template in the pipeline
+     */
+    readonly pipelineUrl?: string_pipeline_url;
+    /**
+     * Internal helper for tracking the source `.ptbk.md` file of the pipeline
+     */
+    readonly sourceFile?: string_file_path;
+    /**
+     * Title of the promptbook
+     * -It can use simple markdown formatting like **bold**, *italic*, [link](https://example.com), ... BUT not code blocks and structure
+     */
+    readonly title: string_markdown_text;
+    /**
+     * Version of the .ptbk.json file
+     */
+    readonly promptbookVersion: string_semantic_version;
+    /**
+     * Description of the promptbook
+     * It can use multiple paragraphs of simple markdown formatting like **bold**, *italic*, [link](https://example.com), ... BUT not code blocks and structure
+     */
+    readonly description?: string_markdown_text;
+    /**
+     * Set of variables that are used across the pipeline
+     */
+    readonly parameters: Array<PromptTemplateParameterJson>;
+    /**
+     * Sequence of prompt templates that are chained together to form a pipeline
+     */
+    readonly promptTemplates: Array<PromptTemplateJson>;
+    /**
+     * Set of information that are used as external knowledge in the pipeline
+     *
+     * @see https://github.com/webgptorg/promptbook/discussions/41
+     */
+    readonly knowledgeSources: Array<KnowledgeSourceJson | KnowledgeSourcePreparedJson>;
+    /**
+     * Set of information that are used as external knowledge in the pipeline
+     *
+     * @see https://github.com/webgptorg/promptbook/discussions/41
+     */
+    readonly knowledgePieces: Array<KnowledgePiecePreparedJson>;
+    /**
+     * List of prepared virtual personas that are used in the pipeline
+     *
+     * @see https://github.com/webgptorg/promptbook/discussions/22
+     */
+    readonly personas: Array<PersonaJson | PersonaPreparedJson>;
+    /**
+     * List of prepared virtual personas that are used in the pipeline
+     *
+     * @see https://github.com/webgptorg/promptbook/discussions/78
+     */
+    readonly preparations: Array<PreparationJson>;
+};
+/**
+ * TODO: !!!!! Implement new commands
+ * Note: There was a proposal for multiple types of promptbook objects 78816ff33e2705ee1a187aa2eb8affd976d4ea1a
+ *       But then immediately reverted back to the single type
+ *       With knowledge as part of the promptbook and collection just as a collection of promptbooks
+ */

package/esm/typings/src/types/PipelineJson/PreparationJson.d.ts

@@ -0,0 +1,25 @@
+import type { PromptResultUsage } from '../../execution/PromptResult';
+import type { string_promptbook_version } from '../../version';
+import type { number_id } from '../typeAliases';
+import type { string_date_iso8601 } from '../typeAliases';
+export type PreparationJson = {
+    /**
+     * Incremental ID of the preparation
+     */
+    readonly id: number_id;
+    /**
+     * Date and time of the preparation
+     */
+    readonly date: string_date_iso8601;
+    /**
+     * Version of the promptbook used for the preparation
+     */
+    readonly promptbookVersion: string_promptbook_version;
+    /**
+     * Usage of the prompt execution
+     */
+    readonly modelUsage: PromptResultUsage;
+};
+/**
+ * TODO: Maybe put here used `modelName`
+ */

package/esm/typings/src/types/PipelineJson/PromptDialogJson.d.ts

@@ -0,0 +1,9 @@
+import type { PromptTemplateJsonCommon } from './PromptTemplateJsonCommon';
+/**
+ * Template for prompt to user
+ *
+ * @see https://github.com/webgptorg/promptbook/discussions/76
+ */
+export interface PromptDialogJson extends PromptTemplateJsonCommon {
+    readonly blockType: 'PROMPT_DIALOG';
+}

package/esm/typings/src/types/PipelineJson/PromptTemplateJson.d.ts

@@ -0,0 +1,9 @@
+import type { ___ } from '../../utils/organization/___';
+import type { LlmTemplateJson } from './LlmTemplateJson';
+import type { PromptDialogJson } from './PromptDialogJson';
+import type { ScriptJson } from './ScriptJson';
+import type { SimpleTemplateJson } from './SimpleTemplateJson';
+/**
+ * Describes one prompt template in the promptbook
+ */
+export type PromptTemplateJson = LlmTemplateJson | SimpleTemplateJson | ScriptJson | PromptDialogJson | ___ | ___ | ___ | ___;

package/esm/typings/src/types/PipelineJson/PromptTemplateJsonCommon.d.ts

@@ -0,0 +1,83 @@
+import type { BlockType } from '../../commands/BLOCK/BlockTypes';
+import type { ExpectFormatCommand } from '../../commands/EXPECT/ExpectFormatCommand';
+import type { string_javascript } from '../typeAliases';
+import type { string_javascript_name } from '../typeAliases';
+import type { string_markdown } from '../typeAliases';
+import type { string_markdown_text } from '../typeAliases';
+import type { string_name } from '../typeAliases';
+import type { string_prompt } from '../typeAliases';
+import type { string_template } from '../typeAliases';
+import type { Expectations } from './Expectations';
+/**
+ * Common properties of all prompt templates
+ */
+export interface PromptTemplateJsonCommon {
+    /**
+     * Name of the template
+     * - It must be unique across the pipeline
+     * - It should start uppercase and can contain letters and numbers
+     * - The pipelineUrl together with hash and name are used to identify the prompt template in the pipeline
+     */
+    readonly name: string_name;
+    /**
+     * Title of the prompt template
+     * It can use simple markdown formatting like **bold**, *italic*, [link](https://example.com), ... BUT not code blocks and structure
+     */
+    readonly title: string;
+    /**
+     * Description of the prompt template
+     * It can use multiple paragraphs of simple markdown formatting like **bold**, *italic*, [link](https://example.com), ... BUT not code blocks and structure
+     */
+    readonly description?: string_markdown_text;
+    /**
+     * List of parameter names that are used in the prompt template and must be defined before the prompt template is executed
+     *
+     * Note: Joker is one of the dependent parameters
+     */
+    readonly dependentParameterNames: Array<string_name>;
+    /**
+     * If theese parameters meet the expectations requirements, they are used instead of executing this prompt template
+     *
+     * @see https://github.com/webgptorg/promptbook/discussions/66
+     */
+    readonly jokers?: Array<string>;
+    /**
+     * Type of the execution
+     * This determines if the prompt template is send to LLM, user or some scripting evaluation
+     */
+    readonly blockType: BlockType;
+    /**
+     * Content of the template with {placeholders} for parameters
+     */
+    readonly content: (string_prompt | string_javascript | string_markdown) & string_template;
+    /**
+     * List of postprocessing steps that are executed after the prompt template
+     *
+     * @see https://github.com/webgptorg/promptbook/discussions/31
+     */
+    readonly postprocessing?: Array<string_javascript_name>;
+    /**
+     * Expect this amount of each unit in the answer
+     *
+     * For example 5 words, 3 sentences, 2 paragraphs, ...
+     *
+     * Note: Expectations are performed after all postprocessing steps
+     * @see https://github.com/webgptorg/promptbook/discussions/30
+     */
+    readonly expectations?: Expectations;
+    /**
+     * Expect this format of the answer
+     *
+     * Note: Expectations are performed after all postprocessing steps
+     * @see https://github.com/webgptorg/promptbook/discussions/30
+     * @deprecated [💝]
+     */
+    readonly expectFormat?: ExpectFormatCommand['format'];
+    /**
+     * Name of the parameter that is the result of the prompt template
+     */
+    readonly resultingParameterName: string_name;
+}
+/**
+ * TODO: use one helper type> (string_prompt | string_javascript | string_markdown) & string_template
+ */

package/esm/typings/src/types/PipelineJson/PromptTemplateParameterJson.d.ts

@@ -0,0 +1,26 @@
+import type { string_markdown_text } from '../typeAliases';
+import type { string_name } from '../typeAliases';
+/**
+ * Describes one parameter of the promptbook
+ */
+export type PromptTemplateParameterJson = {
+    /**
+     * Name of the parameter
+     * - It must be unique across the pipeline
+     * - It should start lowercase and contain letters and numbers
+     */
+    readonly name: string_name;
+    /**
+     * The parameter is input of the pipeline
+     */
+    readonly isInput: boolean;
+    /**
+     * The parameter is output of the pipeline
+     */
+    readonly isOutput: boolean;
+    /**
+     * Description of the parameter
+     * - It can use simple markdown formatting like **bold**, *italic*, [link](https://example.com), ... BUT not code blocks and structure
+     */
+    readonly description?: string_markdown_text;
+};

package/esm/typings/src/types/PipelineJson/ScriptJson.d.ts

@@ -0,0 +1,16 @@
+import type { ScriptLanguage } from '../ScriptLanguage';
+import type { PromptTemplateJsonCommon } from './PromptTemplateJsonCommon';
+/**
+ * Template for script execution
+ *
+ * @see https://github.com/webgptorg/promptbook/discussions/77
+ */
+export interface ScriptJson extends PromptTemplateJsonCommon {
+    readonly blockType: 'SCRIPT';
+    /**
+     * Language of the script
+     * - This is required only for blockType SCRIPT
+     *
+     */
+    readonly contentLanguage?: ScriptLanguage;
+}

package/esm/typings/src/types/PipelineJson/SimpleTemplateJson.d.ts

@@ -0,0 +1,9 @@
+import type { PromptTemplateJsonCommon } from './PromptTemplateJsonCommon';
+/**
+ * Template for simple concatenation of strings
+ *
+ * @see https://github.com/webgptorg/promptbook/discussions/17
+ */
+export interface SimpleTemplateJson extends PromptTemplateJsonCommon {
+    readonly blockType: 'SIMPLE_TEMPLATE';
+}

package/esm/typings/src/types/PipelineString.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Promptbook is the **core concept of this package**.
+ * It represents a series of prompt templates chained together to form a pipeline / one big prompt template with input and result parameters.
+ *
+ * @see !!! https://github.com/webgptorg/promptbook#promptbook
+ */
+export type PipelineString = string & {
+    readonly _type: 'Promptbook';
+};
+/**
+ * TODO: !! Better validation (validatePipelineString) or remove branded type and make it just string
+ */

package/esm/typings/src/types/Prompt.d.ts

@@ -0,0 +1,65 @@
+import type { ExpectFormatCommand } from '../commands/EXPECT/ExpectFormatCommand';
+import type { PostprocessingFunction } from '../scripting/javascript/JavascriptExecutionToolsOptions';
+import type { ModelRequirements } from './ModelRequirements';
+import type { Expectations } from './PipelineJson/Expectations';
+import type { string_name } from './typeAliases';
+import type { string_pipeline_url_with_hashtemplate } from './typeAliases';
+import type { string_prompt } from './typeAliases';
+import type { string_title } from './typeAliases';
+/**
+ * Prompt in a text along with model requirements, but without any execution or templating logic.
+ *
+ * @see https://github.com/webgptorg/promptbook#prompt
+ */
+export type Prompt = {
+    /**
+     * The title of the prompt
+     *
+     * Note: This has no effect on the model, it is just for the reporting
+     */
+    readonly title: string_title;
+    /**
+     * The text of the prompt
+     *
+     * Note: This is not a template, this is exactly the text that will be sent to the model
+     * @example "What is the capital of France?"
+     */
+    readonly content: string_prompt;
+    /**
+     * Requirements for the model
+     */
+    readonly modelRequirements: ModelRequirements;
+    /**
+     * List of postprocessing steps that are executed after the prompt
+     */
+    readonly postprocessing?: Array<PostprocessingFunction>;
+    /**
+     * Expectations for the answer
+     *
+     * For example 5 words, 3 sentences, 2 paragraphs, ...
+     * If not set, nothing is expected from the answer
+     */
+    readonly expectations?: Expectations;
+    /**
+     * Expect this format of the answer
+     *
+     * Note: Expectations are performed after all postprocessing steps
+     * @deprecated [💝]
+     */
+    readonly expectFormat?: ExpectFormatCommand['format'];
+    /**
+     * Unique identifier of the pipeline with specific template name as hash
+     *
+     * @example https://promptbook.studio/webgpt/write-website-content-cs.ptbk.md#keywords
+     */
+    readonly pipelineUrl?: string_pipeline_url_with_hashtemplate;
+    /**
+     * Parameters used in the prompt
+     *
+     * Note: This is redundant (same information is in pipelineUrl+content) but useful for logging and debugging
+     */
+    readonly parameters: Record<string_name, string>;
+};
+/**
+ * TODO: [✔] Check ModelRequirements in runtime
+ */

package/esm/typings/src/types/ScriptLanguage.d.ts

@@ -0,0 +1,9 @@
+import type { TupleToUnion } from 'type-fest';
+/**
+ * Supported script languages
+ */
+export declare const SUPPORTED_SCRIPT_LANGUAGES: readonly ["javascript", "typescript", "python"];
+/**
+ * Script language
+ */
+export type ScriptLanguage = TupleToUnion<typeof SUPPORTED_SCRIPT_LANGUAGES>;

package/esm/typings/src/types/TaskProgress.d.ts

@@ -0,0 +1,43 @@
+import type { BlockType } from '../commands/BLOCK/BlockTypes';
+import type { string_markdown_text } from './typeAliases';
+import type { string_name } from './typeAliases';
+/**
+ * TaskProgress represents the progress of a Promptbook execution.
+ */
+export type TaskProgress = {
+    /**
+     * The unique name of the task.
+     *
+     * Note: This is not supposed to be displayed to the user.
+     *       It is used to identify the task in the code, for example as react key
+     */
+    readonly name: string_name;
+    /**
+     * Title of the task.
+     *
+     * Note: This is supposed to be displayed to the user.
+     * Note: This is trimmed and stripped of HTML tags and emojis
+     */
+    readonly title: string_markdown_text;
+    /**
+     * Does the task started?
+     */
+    readonly isStarted: boolean;
+    /**
+     * Is task done?
+     */
+    readonly isDone: boolean;
+    /**
+     * The type of the execution.
+     * Note: The pipeline executor reports everything, in the app level you can filter out the execution types that you don't want to show to the user.
+     */
+    readonly blockType: BlockType;
+    /**
+     * The parameter name that is being processed.
+     */
+    readonly parameterName: string_name;
+    /**
+     * The parameter value or null if the parameter is not yet processed.
+     */
+    readonly parameterValue: string | null;
+};

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

@@ -0,0 +1,58 @@
+import type { PromptResult } from '../../execution/PromptResult';
+import type { Prompt } from '../Prompt';
+import type { string_markdown_text } from '../typeAliases';
+import type { string_pipeline_url } from '../typeAliases';
+import type { string_semantic_version } from '../typeAliases';
+/**
+ * ExecutionReport is result of executing one promptbook
+ * It is kind of a variant of the promptbook usefull for debugging, logging and transparency for users.
+ *
+ * It can have 2 formats:
+ * -   **.md file** created from the **JSON** format
+ * -   _(this)_ **JSON** format
+ *
+ * @see https://github.com/webgptorg/promptbook#execution-report
+ */
+export type ExecutionReportJson = {
+    /**
+     * Unique identifier of the pipeline from promptbook which was executed
+     */
+    readonly pipelineUrl?: string_pipeline_url;
+    /**
+     * Title of from promptbook which was executed
+     */
+    readonly title?: string;
+    /**
+     * Version from promptbook which was executed
+     */
+    readonly promptbookUsedVersion: string_semantic_version;
+    /**
+     * Version from promptbook which was requested by promptbook
+     */
+    readonly promptbookRequestedVersion?: string_semantic_version;
+    /**
+     * Description of the promptbook which was executed
+     */
+    readonly description?: string_markdown_text;
+    /**
+     * Sequence of prompt templates in order which were executed
+     */
+    readonly promptExecutions: Array<{
+        /**
+         * The prompt wich was executed
+         */
+        readonly prompt: Omit<Prompt, 'pipelineUrl' | 'parameters'>;
+        /**
+         * Result of the prompt execution (if not failed during LLM execution)
+         */
+        readonly result?: PromptResult;
+        /**
+         * The error which occured during LLM execution or during postprocessing or expectation checking
+         *
+         * Note: It makes sense to have both error and result defined, for example when the result not pass expectations
+         */
+        readonly error?: {
+            readonly message: string;
+        };
+    }>;
+};

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

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

package/esm/typings/src/types/execution-report/ExecutionReportStringOptions.d.ts

@@ -0,0 +1,21 @@
+import type { number_percent } from '../typeAliases';
+/**
+ * Options for `executionReportJsonToString`
+ */
+export type ExecutionReportStringOptions = {
+    /**
+     * The tax rate to be applied, expressed as a percentage from 0 to 1 (=100%) or even more
+     */
+    readonly taxRate: number_percent;
+    /**
+     * The width of the charts in the report
+     */
+    readonly chartsWidth: number;
+};
+/**
+ * Default options for generating an execution report string
+ */
+export declare const ExecutionReportStringOptionsDefaults: {
+    taxRate: number;
+    chartsWidth: number;
+};

package/esm/typings/src/types/execution-report/config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The thresholds for the relative time in the `moment` NPM package.
+ *
+ * @see https://momentjscom.readthedocs.io/en/latest/moment/07-customization/13-relative-time-threshold/
+ */
+export declare const MOMENT_ARG_THRESHOLDS: {
+    readonly ss: 3;
+};

package/esm/typings/src/types/execution-report/countWorkingDuration.d.ts

@@ -0,0 +1,7 @@
+import type { FromtoItems } from '../../utils/FromtoItems';
+/**
+ * Count the duration of working time
+ *
+ * @private within the package
+ */
+export declare function countWorkingDuration(items: FromtoItems): number;

package/esm/typings/src/types/execution-report/countWorkingDuration.test.d.ts

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

package/esm/typings/src/types/execution-report/executionReportJsonToString.d.ts

@@ -0,0 +1,11 @@
+import type { ExecutionReportJson } from './ExecutionReportJson';
+import type { ExecutionReportString } from './ExecutionReportString';
+import type { ExecutionReportStringOptions } from './ExecutionReportStringOptions';
+/**
+ * Converts execution report from JSON to string format
+ */
+export declare function executionReportJsonToString(executionReportJson: ExecutionReportJson, options?: Partial<ExecutionReportStringOptions>): ExecutionReportString;
+/**
+ * TODO: Add mermaid chart for every report
+ * TODO: [🧠] Allow to filter out some parts of the report by options
+ */