@promptbook/markdown-utils 0.92.0-24 → 0.92.0-25

package/esm/typings/src/_packages/core.index.d.ts

@@ -122,7 +122,6 @@ import { EXPECTATION_UNITS } from '../pipeline/PipelineJson/Expectations';
 import { validatePipelineString } from '../pipeline/validatePipelineString';
 import { isPipelinePrepared } from '../prepare/isPipelinePrepared';
 import { preparePipeline } from '../prepare/preparePipeline';
-import { prepareTasks } from '../prepare/prepareTasks';
 import { unpreparePipeline } from '../prepare/unpreparePipeline';
 import { identificationToPromptbookToken } from '../remote-server/socket-types/_subtypes/identificationToPromptbookToken';
 import { promptbookTokenToIdentification } from '../remote-server/socket-types/_subtypes/promptbookTokenToIdentification';
@@ -270,7 +269,6 @@ export { EXPECTATION_UNITS };
 export { validatePipelineString };
 export { isPipelinePrepared };
 export { preparePipeline };
-export { prepareTasks };
 export { unpreparePipeline };
 export { identificationToPromptbookToken };
 export { promptbookTokenToIdentification };

package/esm/typings/src/commands/_common/types/CommandParser.d.ts

@@ -8,7 +8,8 @@ import type { string_SCREAMING_CASE } from '../../../utils/normalization/normali
 import type { ___and___ } from '../../../utils/organization/___and___';
 import type { CommandUsagePlace } from './CommandUsagePlaces';
 /**
- * @@@
+ * Base type for all command objects.
+ * Requires a `type` property which is a SCREAMING_CASE string.
  *
  * @private just abstract helper for command parsers
  */
@@ -16,47 +17,48 @@ export type CommandBase = {
     type: string_name & string_SCREAMING_CASE;
 };
 /**
- * @@@
+ * Represents a parser for a specific command used within a Promptbook pipeline.
+ * It can parse commands used in the pipeline head, tasks, or both.
  *
  * @public exported from `@promptbook/editable`
  */
 export type CommandParser<TCommand extends CommandBase> = PipelineHeadCommandParser<TCommand> | PipelineTaskCommandParser<TCommand> | PipelineBothCommandParser<TCommand>;
 /**
- * @@@
+ * Common properties shared by all command parsers.
  *
  * @private just abstract the common properties of the command parsers
  */
 export type CommonCommandParser<TCommand extends CommandBase> = {
     /**
-     * @@@
+     * The unique SCREAMING_CASE name of the command (e.g., 'MODEL', 'PARAMETER').
      */
     readonly name: string_name & string_SCREAMING_CASE;
     /**
-     * @@@
+     * Indicates if the command can be used in the pipeline's head section.
      */
     readonly isUsedInPipelineHead: boolean;
     /**
-     * @@@
+     * Indicates if the command can be used within a pipeline task.
      */
     readonly isUsedInPipelineTask: boolean;
     /**
-     * @@@
+     * Optional alternative names (aliases) for the command, also in SCREAMING_CASE.
      */
     readonly aliasNames?: ReadonlyArray<string_name & string_SCREAMING_CASE>;
     /**
-     * @@@
+     * Optional list of deprecated names for the command, used for backward compatibility.
      */
     readonly deprecatedNames?: ReadonlyArray<string_name & string_SCREAMING_CASE>;
     /**
-     * @@@
+     * A brief description of the command's purpose, supporting simple Markdown.
      */
     readonly description: string_markdown_text;
     /**
-     * @@@
+     * A URL pointing to the command's documentation.
      */
     readonly documentationUrl: string_promptbook_documentation_url;
     /**
-     * @@@
+     * Examples demonstrating the usage of the command in Markdown format.
      */
     readonly examples: ReadonlyArray<string_markdown_text>;
     /**
@@ -72,23 +74,23 @@ export type CommonCommandParser<TCommand extends CommandBase> = {
     stringify(command: TCommand): string_markdown_text;
 };
 /**
- * @@@
+ * Represents a command parser that can be used in both the pipeline head and tasks.
  *
  * @public exported from `@promptbook/editable`
  */
 export type PipelineBothCommandParser<TCommand extends CommandBase> = ___and___ & Omit<PipelineHeadCommandParser<TCommand>, 'isUsedInPipelineTask'> & Omit<PipelineTaskCommandParser<TCommand>, 'isUsedInPipelineHead'>;
 /**
- * @@@
+ * Represents a command parser specifically for the pipeline head section.
  *
  * @public exported from `@promptbook/editable`
  */
 export type PipelineHeadCommandParser<TCommand extends CommandBase> = CommonCommandParser<TCommand> & {
     /**
-     * @@@
+     * Always true for pipeline head commands.
      */
     readonly isUsedInPipelineHead: true;
     /**
-     * @@@
+     * Always false for pipeline head commands.
      */
     readonly isUsedInPipelineTask: false;
     /**
@@ -106,17 +108,17 @@ export type PipelineHeadCommandParser<TCommand extends CommandBase> = CommonComm
     takeFromPipelineJson(pipelineJson: PipelineJson): ReadonlyArray<TCommand>;
 };
 /**
- * @@@
+ * Represents a command parser specifically for pipeline tasks.
  *
  * @public exported from `@promptbook/editable`
  */
 export type PipelineTaskCommandParser<TCommand extends CommandBase> = CommonCommandParser<TCommand> & {
     /**
-     * @@@
+     * Always false for pipeline task commands.
      */
     readonly isUsedInPipelineHead: false;
     /**
-     * @@@
+     * Always true for pipeline task commands.
      */
     readonly isUsedInPipelineTask: true;
     /**
@@ -133,58 +135,64 @@ export type PipelineTaskCommandParser<TCommand extends CommandBase> = CommonComm
     takeFromTaskJson($taskJson: $TaskJson): ReadonlyArray<TCommand>;
 };
 /**
- * @@@
+ * Represents a mutable TaskJson object, used internally by command parsers during application.
  *
- * Note: `$` is used to indicate that purpose of this type is to mutate the given object
+ * Note: `$` prefix indicates the object is intended for mutation.
  *
  * @private internal helper for command parsers
  */
 export type $TaskJson = {
+    /**
+     * Flag indicating if the section type (e.g., `SIMPLE_TEMPLATE`) has been set for this task.
+     */
     isSectionTypeSet: boolean;
+    /**
+     * Flag indicating if this object represents a task (as opposed to other sections like parameters).
+     */
     isTask: boolean;
 } & Partial<WritableDeep<TaskJson>>;
 /**
- * @@@
+ * Represents a mutable PipelineJson object, used internally by command parsers during application.
  *
- *  Note: `$` is used to indicate that purpose of this type is to mutate the given object
+ * Note: `$` prefix indicates the object is intended for mutation.
  *
  * @private internal helper for command parsers
  */
 export type $PipelineJson = WritableDeep<SetOptional<PipelineJson, 'formfactorName'>>;
 /**
- * @@@
+ * Input object provided to the `parse` method of a CommandParser.
  */
 export type CommandParserInput = {
     /**
-     * @@@
+     * Specifies where the command is being used (pipeline head or task).
      *
      * @example 'PIPELINE_HEAD'
      * @example 'PIPELINE_TASK'
      */
     readonly usagePlace: CommandUsagePlace;
     /**
-     * @@@
+     * The raw, unprocessed line containing the command and its arguments.
      *
      * @example 'promptbook version 0.62.0'
      * @example 'FOREACH Text Line `{customers}` -> `{customer}`'
      */
     readonly raw: string_markdown_text;
     /**
-     * @@@
+     * The arguments part of the raw command line, after the command name.
      *
      * @example '0.62.0'
      * @example 'List Line `{customers}` -> `{customer}`'
      */
     readonly rawArgs: string_markdown_text;
     /**
-     * @@@
+     * The normalized, SCREAMING_CASE representation of the command and its core arguments.
      *
      * @example 'PROMPTBOOK_ENGINE_VERSION_0_62_0'
      * @example 'FOREACH_LIST_LINE_CUSTOMERS_CUSTOMER'
      */
     readonly normalized: string_name & string_SCREAMING_CASE;
     /**
-     * @@@
+     * An array of arguments extracted from the line where the command is used.
      *
      * @example [ '0.62.0' ]
      * @example [ 'List', 'Line', '{customers}', '', '{customer}' ]

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

@@ -13,13 +13,13 @@ export declare const ORDER_OF_PIPELINE_JSON: ExportJsonOptions<PipelineJson>['or
  */
 export declare const REPLACING_NONCE = "ptbkauk42kV2dzao34faw7FudQUHYPtW";
 /**
- * @@@
+ * Placeholder value indicating a parameter is missing its value.
  *
  * @private within the repository
  */
 export declare const RESERVED_PARAMETER_MISSING_VALUE: string;
 /**
- * @@@
+ * Placeholder value indicating a parameter is restricted and cannot be used directly.
  *
  * @private within the repository
  */

package/esm/typings/src/errors/0-BoilerplateError.d.ts

@@ -1,5 +1,5 @@
 /**
- * This error indicates @@@
+ * This error indicates @@
  *
  * @public exported from `@promptbook/core`
  */
@@ -8,5 +8,5 @@ export declare class BoilerplateError extends Error {
     constructor(message: string);
 }
 /**
- * TODO: @@@ Do not forget to add the error into `0-index.ts` ERRORS
+ * TODO: @@ Do not forget to add the error into `0-index.ts` ERRORS
  */

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

@@ -1,6 +1,6 @@
 import type { string_user_id } from '../types/typeAliases';
 /**
- * @@@
+ * Common options shared across various execution tools.
  *
  * Note: Keep it public to allow people to make their own execution tools
  */
@@ -17,8 +17,8 @@ export type CommonToolsOptions = {
      */
     readonly isVerbose?: boolean;
     /**
-    * Maximum number of requests per minute
-    */
+     * Maximum number of requests per minute
+     */
     readonly maxRequestsPerMinute?: number;
 };
 /**

package/esm/typings/src/llm-providers/_common/register/$llmToolsMetadataRegister.d.ts

@@ -1,13 +1,13 @@
 import { $Register } from '../../../utils/$Register';
 import type { LlmToolsMetadata } from './LlmToolsMetadata';
 /**
- * @@@
+ * Register for LLM tools metadata.
  *
  * Note: `$` is used to indicate that this interacts with the global scope
- * @singleton Only one instance of each register is created per build, but thare can be more @@@
+ * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
  * @public exported from `@promptbook/core`
  */
 export declare const $llmToolsMetadataRegister: $Register<LlmToolsMetadata>;
 /**
  * TODO: [®] DRY Register logic
- */ 
+ */

package/esm/typings/src/llm-providers/_common/register/$llmToolsRegister.d.ts

@@ -1,13 +1,13 @@
 import type { LlmExecutionToolsConstructor } from '../../../execution/LlmExecutionToolsConstructor';
 import { $Register } from '../../../utils/$Register';
 /**
- * @@@
+ * Register for LLM tools.
  *
  * Note: `$` is used to indicate that this interacts with the global scope
- * @singleton Only one instance of each register is created per build, but thare can be more @@@
+ * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
  * @public exported from `@promptbook/core`
  */
 export declare const $llmToolsRegister: $Register<LlmExecutionToolsConstructor>;
 /**
  * TODO: [®] DRY Register logic
- */ 
+ */

package/esm/typings/src/llm-providers/_common/register/$provideLlmToolsConfigurationFromEnv.d.ts

@@ -1,8 +1,7 @@
 import type { LlmToolsConfiguration } from './LlmToolsConfiguration';
 /**
- * @@@
+ * Provides LLM tools configuration by reading environment variables.
  *
- * @@@ .env
  * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file
  *
  * It looks for environment variables:
@@ -10,10 +9,11 @@ import type { LlmToolsConfiguration } from './LlmToolsConfiguration';
  * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
  * - ...
  *
- * @returns @@@
+ * @see Environment variables documentation or .env file for required variables.
+ * @returns A promise that resolves to the LLM tools configuration, or null if configuration is incomplete or missing.
  * @public exported from `@promptbook/node`
  */
 export declare function $provideLlmToolsConfigurationFromEnv(): Promise<LlmToolsConfiguration>;
 /**
  * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
- */
+ */ 

package/esm/typings/src/llm-providers/_common/utils/cache/CacheItem.d.ts

@@ -3,23 +3,23 @@ import type { Prompt } from '../../../../types/Prompt';
 import type { string_date_iso8601 } from '../../../../types/typeAliases';
 import type { string_promptbook_version } from '../../../../version';
 /**
- * @@@
+ * Represents a single item stored in the LLM cache.
  */
 export type CacheItem = {
     /**
-     * @@@
+     * The date and time when the cache item was created, in ISO 8601 format.
      */
     date: string_date_iso8601;
     /**
-     * @@@
+     * The version of the Promptbook library used when this cache item was created.
      */
     promptbookVersion?: string_promptbook_version;
     /**
-     * @@@
+     * The prompt that was sent to the LLM.
      */
     prompt: Prompt;
     /**
-     * @@@
+     * The response received from the LLM.
      */
     promptResult: PromptResult;
 };

package/esm/typings/src/llm-providers/_common/utils/cache/CacheLlmToolsOptions.d.ts

@@ -1,17 +1,19 @@
 import type { PromptbookStorage } from '../../../../storage/_common/PromptbookStorage';
 import type { CacheItem } from './CacheItem';
 /**
- * @@@
+ * Options for configuring caching behavior for LlmExecutionTools.
  */
 export type CacheLlmToolsOptions = {
     /**
-     * @@@
+     * The cache provider instance to use for storing and retrieving cached data.
      *
      * @default MemoryStorage
      */
     storage: PromptbookStorage<CacheItem>;
     /**
-     * @@@
+     * When set to `true`, the cache will be reloaded regardless of whether the data is already present in the cache.
+     * This can be useful for debugging or when you want to ensure that the latest data is always fetched.
+     * Data will ne still saved to the cache.
      *
      * @default false
      */

package/esm/typings/src/llm-providers/_common/utils/count-total-usage/limitTotalUsage.d.ts

@@ -4,24 +4,24 @@ import type { PromptbookStorage } from '../../../../storage/_common/PromptbookSt
 import type { TODO_any } from '../../../../utils/organization/TODO_any';
 import type { LlmExecutionToolsWithTotalUsage } from './LlmExecutionToolsWithTotalUsage';
 /**
- * Options for `limitTotalUsage`
+ * Options for the `limitTotalUsage` function.
  */
 type LimitTotalUsageOptions = {
     /**
-     * @@@
+     * The usage limits to apply.
      *
      * @default ZERO_USAGE
      */
     maxTotalUsage: Usage;
     /**
-     * @@@
+     * The storage mechanism to use for tracking usage across multiple executions or instances.
      *
-     * @default MemoryStorage
+     * @default MemoryStorage which will not persist when the process ends
      */
     storage: PromptbookStorage<TODO_any>;
 };
 /**
- * @@@
+ * Wraps LlmExecutionTools to limit the total usage based on provided limits.
  *
  * @public exported from `@promptbook/core`
  */

package/esm/typings/src/other/templates/getBookTemplates.d.ts

@@ -3,14 +3,14 @@ import type { string_formfactor_name } from '../../formfactors/_common/string_fo
 import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
 import type { NonEmptyReadonlyArray } from '../../types/NonEmptyArray';
 /**
- * @@@
+ * Internal cache for the `getBookTemplates` function, storing retrieved pipelines.
  *
  * @singleton
  * @private internal cache of `getBookTemplate`
  */
 export declare let pipelines: Array<SetRequired<PipelineJson, 'pipelineUrl'>> | null;
 /**
- * Get template for new book
+ * Retrieves a collection of Promptbook templates.
  *
  * @param formfactorName - optional filter for FORMFACTOR - get only pipelines for this formfactor
  * @returns list of pipelines

package/esm/typings/src/pipeline/PipelineInterface/PipelineInterface.d.ts

@@ -1,20 +1,20 @@
 import type { InputParameterJson } from '../PipelineJson/ParameterJson';
 import type { OutputParameterJson } from '../PipelineJson/ParameterJson';
 /**
- * @@@
+ * Defines the interface of a Promptbook pipeline, specifying its input and output parameters.
  *
  * Note: [🚉] This is fully serializable as JSON
  * @see https://github.com/webgptorg/promptbook/discussions/171
  */
 export type PipelineInterface = {
     /**
-     * @@@
+     * Input parameters required by the pipeline.
      *
      * Note: Sorted alphabetically
      */
     readonly inputParameters: ReadonlyArray<InputParameterJson>;
     /**
-     * @@@
+     * Output parameters produced by the pipeline.
      *
      * Note: Sorted alphabetically
      */

package/esm/typings/src/pipeline/PipelineInterface/constants.d.ts

@@ -1,5 +1,5 @@
 /**
- * @@@
+ * Pipeline interface which is equivalent to `any`
  *
  * @see https://github.com/webgptorg/promptbook/discussions/171
  *

package/esm/typings/src/pipeline/PipelineInterface/getPipelineInterface.d.ts

@@ -1,7 +1,7 @@
 import type { PipelineJson } from '../PipelineJson/PipelineJson';
 import type { PipelineInterface } from './PipelineInterface';
 /**
- * @@@
+ * Extracts the interface (input and output parameters) from a pipeline.
  *
  * @deprecated https://github.com/webgptorg/promptbook/pull/186
  * @see https://github.com/webgptorg/promptbook/discussions/171

package/esm/typings/src/pipeline/PipelineInterface/isPipelineImplementingInterface.d.ts

@@ -1,25 +1,26 @@
 import type { PipelineJson } from '../PipelineJson/PipelineJson';
 import type { PipelineInterface } from './PipelineInterface';
 /**
- * @@@
+ * Options for the `isPipelineImplementingInterface` function.
  *
  * @see https://github.com/webgptorg/promptbook/discussions/171
  */
 export type IsPipelineImplementingInterfaceOptions = {
     /**
-     * @@@
+     * @param pipeline The pipeline to check.
      */
     pipeline: PipelineJson;
     /**
-     * @@@
+     * @param pipelineInterface The interface to check against.
      */
     pipelineInterface: PipelineInterface;
 };
 /**
- * @@@
+ * Checks if a given pipeline satisfies the requirements of a specified pipeline interface.
  *
  * @deprecated https://github.com/webgptorg/promptbook/pull/186
  * @see https://github.com/webgptorg/promptbook/discussions/171
+ * @returns `true` if the pipeline implements the interface, `false` otherwise.
  *
  * @public exported from `@promptbook/core`
  */

package/esm/typings/src/pipeline/PipelineInterface/isPipelineInterfacesEqual.d.ts

@@ -1,6 +1,6 @@
 import type { PipelineInterface } from './PipelineInterface';
 /**
- * @@@
+ * Checks if two pipeline interfaces are structurally identical.
  *
  * @deprecated https://github.com/webgptorg/promptbook/pull/186
  * @see https://github.com/webgptorg/promptbook/discussions/171

package/esm/typings/src/pipeline/PipelineJson/CommonTaskJson.d.ts

@@ -38,13 +38,15 @@ export type CommonTaskJson = {
      */
     readonly dependentParameterNames: Array<string_parameter_name>;
     /**
-     * If theese parameters meet the expectations requirements, they are used instead of executing this task
+     * List of parameter names that act as jokers.
+     * If a joker parameter meets the expectations, its value is used instead of executing the task.
      *
      * @see https://github.com/webgptorg/promptbook/discussions/66
      */
     readonly jokerParameterNames?: Array<string_parameter_name>;
     /**
-     * @@@
+     * Configuration for the FOREACH command, if used.
+     * Allows iterating over a list parameter.
      */
     readonly foreach?: ForeachJson;
     /**
@@ -53,15 +55,16 @@ export type CommonTaskJson = {
      */
     readonly taskType: SectionType;
     /**
-     * Content of the task with {placeholders} for parameters
+     * Raw content of the task with {placeholders} for parameters before any preparation.
      *
-     * @@@ content vs preparedContent
+     * @see preparedContent
      */
     readonly content: (string_prompt | string_javascript | string_markdown) & string_template;
     /**
-     * @@@ Content of the task with {placeholders} for parameters
+     * Content of the task after preparation, with {placeholders} for parameters.
+     * This is the content used during execution.
      *
-     * @@@ content vs preparedContent
+     * @see content
      *
      * @default "{content}"
      */

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

@@ -15,12 +15,12 @@ import type { PersonaPreparedJson } from './PersonaJson';
 import type { PreparationJson } from './PreparationJson';
 import type { TaskJson } from './TaskJson';
 /**
- * Promptbook is the **core concept of this package**.
+ * Represents a Promptbook pipeline defined in JSON format.
  * It represents a series of tasks chained together to form a pipeline / one big task with input and result parameters.
  *
  * Note: [🚉] This is fully serializable as JSON
  *
- * @see @@@ https://github.com/webgptorg/promptbook#promptbook
+ * @see The main Promptbook documentation for more details: https://github.com/webgptorg/promptbook#promptbook
  */
 export type PipelineJson = {
     /**

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

@@ -2,7 +2,9 @@
  * Promptbook is the **core concept of this package**.
  * It represents a series of tasks chained together to form a pipeline / one big task with input and result parameters.
  *
- * @see @@@ https://github.com/webgptorg/promptbook#promptbook
+ * Represents a Promptbook pipeline defined as a string.
+ *
+ * @see The main Promptbook documentation for more details: https://github.com/webgptorg/promptbook#promptbook
  */
 export type PipelineString = string & {
     readonly _type: 'Promptbook';

package/esm/typings/src/pipeline/book-notation.d.ts

@@ -7,8 +7,8 @@ import type { PipelineString } from './PipelineString';
  * 2) `promptTemplate` alias for `prompt`
  * 3) `book` for notating and validating entire books exported from `@promptbook/utils`
  *
- * @param strings @@@
- * @param values @@@
+ * @param strings The static string parts of the template literal
+ * @param values The dynamic values embedded within the template literal used as data
  * @returns the pipeline string
  * @public exported from `@promptbook/core`
  */

package/esm/typings/src/prepare/prepareTasks.d.ts

@@ -4,20 +4,23 @@ import type { TaskJson } from '../pipeline/PipelineJson/TaskJson';
 import type { PrepareAndScrapeOptions } from './PrepareAndScrapeOptions';
 type PrepareTaskInput = Pick<PipelineJson, 'tasks' | 'parameters'> & {
     /**
-     * @@@
+     * The number of knowledge pieces available for the pipeline.
      */
     readonly knowledgePiecesCount: number;
 };
 type PreparedTasks = {
     /**
-     * @@@ Sequence of tasks that are chained together to form a pipeline
+     * The sequence of tasks after preparation.
      */
     readonly tasksPrepared: ReadonlyArray<TaskJson>;
 };
 /**
- * @@@
+ * Prepares tasks by adding knowledge to the prompt and ensuring all necessary parameters are included.
  *
- * @public exported from `@promptbook/core`
+ * @param tasks Sequence of tasks that are chained together to form a pipeline
+ * @returns A promise that resolves to the prepared tasks.
+ *
+ * @private internal utility of `preparePipeline`
  */
 export declare function prepareTasks(pipeline: PrepareTaskInput, tools: Pick<ExecutionTools, 'llm' | 'fs' | 'scrapers'>, options: PrepareAndScrapeOptions): Promise<PreparedTasks>;
 export {};

package/esm/typings/src/remote-server/types/RemoteServerOptions.d.ts

@@ -13,7 +13,7 @@ import type { string_user_id } from '../../types/typeAliases';
 import type { ApplicationModeIdentification } from '../socket-types/_subtypes/Identification';
 import type { Identification } from '../socket-types/_subtypes/Identification';
 /**
- * @@@
+ * Options for configuring the Promptbook remote server.
  *
  * There are two modes of remote server:
  *
@@ -28,6 +28,7 @@ import type { Identification } from '../socket-types/_subtypes/Identification';
 export type RemoteServerOptions<TCustomOptions> = CommonToolsOptions & {
     /**
      * Port on which the server will listen
+     * @property {number} port The port number the server will listen on.
      */
     readonly port: number;
     /**