@promptbook/utils 0.103.0-8 → 0.103.0

package/esm/typings/src/{book-2.0/commitments → commitments}/_base/createEmptyAgentModelRequirements.d.ts

@@ -1,4 +1,4 @@
-import type { AgentModelRequirements } from '../../agent-source/AgentModelRequirements';
+import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
 /**
  * Creates an empty/basic agent model requirements object
  * This serves as the starting point for the reduce-like pattern

package/esm/typings/src/commitments/index.d.ts

@@ -0,0 +1,93 @@
+import type { BookCommitment } from './_base/BookCommitment';
+import type { CommitmentDefinition } from './_base/CommitmentDefinition';
+import { ActionCommitmentDefinition } from './ACTION/ACTION';
+import { ClosedCommitmentDefinition } from './CLOSED/CLOSED';
+import { ComponentCommitmentDefinition } from './COMPONENT/COMPONENT';
+import { DeleteCommitmentDefinition } from './DELETE/DELETE';
+import { FormatCommitmentDefinition } from './FORMAT/FORMAT';
+import { FromCommitmentDefinition } from './FROM/FROM';
+import { GoalCommitmentDefinition } from './GOAL/GOAL';
+import { KnowledgeCommitmentDefinition } from './KNOWLEDGE/KNOWLEDGE';
+import { LanguageCommitmentDefinition } from './LANGUAGE/LANGUAGE';
+import { MemoryCommitmentDefinition } from './MEMORY/MEMORY';
+import { AgentMessageCommitmentDefinition } from './MESSAGE/AgentMessageCommitmentDefinition';
+import { InitialMessageCommitmentDefinition } from './MESSAGE/InitialMessageCommitmentDefinition';
+import { MessageCommitmentDefinition } from './MESSAGE/MESSAGE';
+import { UserMessageCommitmentDefinition } from './MESSAGE/UserMessageCommitmentDefinition';
+import { MetaCommitmentDefinition } from './META/META';
+import { MetaColorCommitmentDefinition } from './META_COLOR/META_COLOR';
+import { MetaFontCommitmentDefinition } from './META_FONT/META_FONT';
+import { MetaImageCommitmentDefinition } from './META_IMAGE/META_IMAGE';
+import { MetaLinkCommitmentDefinition } from './META_LINK/META_LINK';
+import { ModelCommitmentDefinition } from './MODEL/MODEL';
+import { NoteCommitmentDefinition } from './NOTE/NOTE';
+import { OpenCommitmentDefinition } from './OPEN/OPEN';
+import { PersonaCommitmentDefinition } from './PERSONA/PERSONA';
+import { RuleCommitmentDefinition } from './RULE/RULE';
+import { SampleCommitmentDefinition } from './SAMPLE/SAMPLE';
+import { ScenarioCommitmentDefinition } from './SCENARIO/SCENARIO';
+import { StyleCommitmentDefinition } from './STYLE/STYLE';
+import { UseCommitmentDefinition } from './USE/USE';
+import { UseBrowserCommitmentDefinition } from './USE_BROWSER/USE_BROWSER';
+import { UseMcpCommitmentDefinition } from './USE_MCP/USE_MCP';
+import { UseSearchEngineCommitmentDefinition } from './USE_SEARCH_ENGINE/USE_SEARCH_ENGINE';
+import { NotYetImplementedCommitmentDefinition } from './_base/NotYetImplementedCommitmentDefinition';
+/**
+ * Registry of all available commitment definitions
+ * This array contains instances of all commitment definitions
+ * This is the single source of truth for all commitments in the system
+ *
+ * @private Use functions to access commitments instead of this array directly
+ */
+export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, MemoryCommitmentDefinition, MemoryCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, FromCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, ComponentCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, UseBrowserCommitmentDefinition, UseSearchEngineCommitmentDefinition, UseMcpCommitmentDefinition, UseCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];
+/**
+ * Gets a commitment definition by its type
+ * @param type The commitment type to look up
+ * @returns The commitment definition or null if not found
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function getCommitmentDefinition(type: BookCommitment): CommitmentDefinition | null;
+/**
+ * Gets all available commitment definitions
+ * @returns Array of all commitment definitions
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function getAllCommitmentDefinitions(): ReadonlyArray<CommitmentDefinition>;
+/**
+ * Gets all available commitment types
+ * @returns Array of all commitment types
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function getAllCommitmentTypes(): ReadonlyArray<BookCommitment>;
+/**
+ * Checks if a commitment type is supported
+ * @param type The commitment type to check
+ * @returns True if the commitment type is supported
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function isCommitmentSupported(type: BookCommitment): boolean;
+/**
+ * Grouped commitment definition
+ *
+ * @public exported from `@promptbook/core`
+ */
+export type GroupedCommitmentDefinition = {
+    primary: CommitmentDefinition;
+    aliases: string[];
+};
+/**
+ * Gets all commitment definitions grouped by their aliases
+ *
+ * @returns Array of grouped commitment definitions
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function getGroupedCommitmentDefinitions(): ReadonlyArray<GroupedCommitmentDefinition>;
+/**
+ * TODO: [🧠] Maybe create through standardized $register
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

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

@@ -1,7 +1,7 @@
-import { Color } from './_packages/color.index';
 import type { CsvSettings } from './formats/csv/CsvSettings';
 import type { IntermediateFilesStrategy } from './types/IntermediateFilesStrategy';
 import type { string_app_id, string_email, string_name, string_promptbook_server_url } from './types/typeAliases';
+import { Color } from './utils/color/Color';
 /**
  * Warning message for the generated sections and files files
  *
@@ -45,7 +45,21 @@ export declare const CLAIM = "Turn your company's scattered knowledge into AI re
  */
 export declare const PROMPTBOOK_COLOR: import("./utils/take/interfaces/ITakeChain").WithTake<Color>;
 /**
- * Dark color of the Promptbook
+ * Colors for syntax highlighting in the `<BookEditor/>`
+ *
+ * TODO: [🗽] Unite branding and make single place for it
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const PROMPTBOOK_SYNTAX_COLORS: {
+    readonly TITLE: import("./utils/take/interfaces/ITakeChain").WithTake<Color>;
+    readonly LINE: import("./utils/take/interfaces/ITakeChain").WithTake<Color>;
+    readonly SEPARATOR: import("./utils/take/interfaces/ITakeChain").WithTake<Color>;
+    readonly COMMITMENT: import("./utils/take/interfaces/ITakeChain").WithTake<Color>;
+    readonly PARAMETER: import("./utils/take/interfaces/ITakeChain").WithTake<Color>;
+};
+/**
+ * Chat color of the Promptbook (in chat)
  *
  * TODO: [🗽] Unite branding and make single place for it
  *
@@ -220,6 +234,13 @@ export declare const DEFAULT_MAX_KNOWLEDGE_SOURCES_SCRAPING_TOTAL = 200;
  * @public exported from `@promptbook/core`
  */
 export declare const DEFAULT_BOOKS_DIRNAME = "./books";
+/**
+ * Where to store your agents (also book files)
+ * This is kind of a "src" for your books
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const DEFAULT_AGENTS_DIRNAME = "./agents";
 /**
  * Where to store the temporary downloads
  *
@@ -257,7 +278,7 @@ export declare const CLI_APP_ID: string_app_id;
  */
 export declare const PLAYGROUND_APP_ID: string_app_id;
 /**
- * The name of the builded pipeline collection made by CLI `ptbk make` and for lookup in `createCollectionFromDirectory`
+ * The name of the builded pipeline collection made by CLI `ptbk make` and for lookup in `createPipelineCollectionFromDirectory`
  *
  * @public exported from `@promptbook/core`
  */

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

@@ -9,6 +9,8 @@ import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
  * -   if it is valid json
  * -   if it is meaningful
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @param pipeline valid or invalid PipelineJson
  * @returns the same pipeline if it is logically valid
  * @throws {PipelineLogicError} on logical error in the pipeline

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

@@ -2,11 +2,13 @@ import { CsvFormatError } from '../formats/csv/CsvFormatError';
 import { AbstractFormatError } from './AbstractFormatError';
 import { AuthenticationError } from './AuthenticationError';
 import { CollectionError } from './CollectionError';
+import { DatabaseError } from './DatabaseError';
 import { EnvironmentMismatchError } from './EnvironmentMismatchError';
 import { ExpectError } from './ExpectError';
 import { KnowledgeScrapeError } from './KnowledgeScrapeError';
 import { LimitReachedError } from './LimitReachedError';
 import { MissingToolsError } from './MissingToolsError';
+import { NotAllowed } from './NotAllowed';
 import { NotFoundError } from './NotFoundError';
 import { NotYetImplementedError } from './NotYetImplementedError';
 import { ParseError } from './ParseError';
@@ -40,6 +42,8 @@ export declare const PROMPTBOOK_ERRORS: {
     readonly PromptbookFetchError: typeof PromptbookFetchError;
     readonly UnexpectedError: typeof UnexpectedError;
     readonly WrappedError: typeof WrappedError;
+    readonly NotAllowed: typeof NotAllowed;
+    readonly DatabaseError: typeof DatabaseError;
 };
 /**
  * Index of all javascript errors
@@ -88,6 +92,8 @@ export declare const ALL_ERRORS: {
     readonly PromptbookFetchError: typeof PromptbookFetchError;
     readonly UnexpectedError: typeof UnexpectedError;
     readonly WrappedError: typeof WrappedError;
+    readonly NotAllowed: typeof NotAllowed;
+    readonly DatabaseError: typeof DatabaseError;
 };
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -0,0 +1,12 @@
+/**
+ * This error indicates error from the database
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare class DatabaseError extends Error {
+    readonly name = "DatabaseError";
+    constructor(message: string);
+}
+/**
+ * TODO: [🐱‍🚀] Explain that NotFoundError ([🐱‍🚀] and other specific errors) has priority over DatabaseError in some contexts
+ */

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

@@ -0,0 +1,9 @@
+/**
+ * This error indicates that promptbook operation is not allowed
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare class NotAllowed extends Error {
+    readonly name = "NotAllowed";
+    constructor(message: string);
+}

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

@@ -1,4 +1,4 @@
-import type { really_any } from '../utils/organization/really_any';
+import type { chococake } from '../utils/organization/really_any';
 /**
  * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
  *
@@ -6,5 +6,5 @@ import type { really_any } from '../utils/organization/really_any';
  */
 export declare class WrappedError extends Error {
     readonly name = "WrappedError";
-    constructor(whatWasThrown: really_any);
+    constructor(whatWasThrown: chococake);
 }

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

@@ -46,5 +46,6 @@ export type AvailableModel = {
     readonly isDeprecated?: boolean;
 };
 /**
+ * TODO: [🕛] Extend this from sth like `AgentBasicInformation` / `ModelBasicInformation`
  * TODO: [🧠] Maybe rename to something else - like `ModelInformation` or `ModelMetadata`
  */

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

@@ -16,3 +16,6 @@ export type Executables = {
      */
     libreOfficePath?: string_executable_path;
 };
+/**
+ * <- TODO: Add !!! `browserPath` to `Executables`
+ */

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

@@ -1,8 +1,9 @@
 import type { Observable } from 'rxjs';
 import { PartialDeep } from 'type-fest';
-import type { number_percent } from '../types/typeAliases';
-import type { task_id } from '../types/typeAliases';
+import type { LlmCall } from '../types/LlmCall';
+import type { number_percent, task_id } from '../types/typeAliases';
 import type { string_SCREAMING_CASE } from '../utils/normalization/normalizeTo_SCREAMING_CASE';
+import type { chococake } from '../utils/organization/really_any';
 import type { string_promptbook_version } from '../version';
 import type { AbstractTaskResult } from './AbstractTaskResult';
 import type { PipelineExecutorResult } from './PipelineExecutorResult';
@@ -32,7 +33,7 @@ type CreateTaskOptions<TTaskResult extends AbstractTaskResult> = {
     }) => void, updateTldr: (tldrInfo: {
         readonly percent: number_percent;
         readonly message: string;
-    }) => void): Promise<TTaskResult>;
+    }) => void, logLlmCall: (llmCall: LlmCall) => void): Promise<TTaskResult>;
 };
 /**
  * Helper to create a new task
@@ -136,6 +137,14 @@ export type AbstractTask<TTaskResult extends AbstractTaskResult> = {
      * List of warnings that occurred during the task processing
      */
     readonly warnings: Array<Error>;
+    /**
+     * List of LLM calls that occurred during the task processing
+     */
+    readonly llmCalls: Array<LlmCall>;
+    /**
+     * Optional nonce to correlate logs with version of the Promptbook engine
+     */
+    readonly ptbkNonce?: chococake;
 };
 export type Task = ExecutionTask | PreparationTask;
 export {};

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

@@ -67,3 +67,8 @@ export type ExecutionTools = {
      */
     readonly userInterface?: UserInterfaceTools;
 };
+/**
+ * <- TODO: Add !!! `promptbookAgent` to `ExecutionTools`
+ * <- TODO: Add !!! `mcps` to `ExecutionTools`
+ * <- TODO: Add !!! `prepareCache` to `ExecutionTools`
+ */

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

@@ -3,7 +3,7 @@ import type fs from 'fs/promises';
 /**
  * Container for all the tools needed to manipulate with filesystem
  */
-export type FilesystemTools = Pick<typeof fs, 'access' | 'constants' | 'readFile' | 'writeFile' | 'stat' | 'readdir' | 'mkdir'>;
+export type FilesystemTools = Pick<typeof fs, 'access' | 'constants' | 'readFile' | 'writeFile' | 'stat' | 'readdir' | 'mkdir' | 'watch'>;
 /**
  * TODO: Implement destroyable pattern to free resources
  */

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

@@ -3,12 +3,19 @@ import type { ChatParticipant } from '../book-components/Chat/types/ChatParticip
 import type { Prompt } from '../types/Prompt';
 import type { string_markdown, string_markdown_text, string_title } from '../types/typeAliases';
 import type { AvailableModel } from './AvailableModel';
-import type { ChatPromptResult, CompletionPromptResult, EmbeddingPromptResult } from './PromptResult';
+import type { ChatPromptResult, CompletionPromptResult, EmbeddingPromptResult, ImagePromptResult } 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,...
  *
+ * Note: [🦖] There are several different things in Promptbook:
+ * - `Agent` - which represents an AI Agent with its source, memories, actions, etc. Agent is a higher-level abstraction which is internally using:
+ * - `LlmExecutionTools` - which wraps one or more LLM models and provides an interface to execute them
+ * - `AgentLlmExecutionTools` - which is a specific implementation of `LlmExecutionTools` that wraps another LlmExecutionTools and applies agent-specific system prompts and requirements
+ * - `OpenAiAssistantExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities, recommended for usage in `Agent` or `AgentLlmExecutionTools`
+ * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
+ *
  * @see https://github.com/webgptorg/promptbook#llm-execution-tools
  */
 export type LlmExecutionTools = {
@@ -46,17 +53,34 @@ export type LlmExecutionTools = {
      * Calls a chat model
      */
     callChatModel?(prompt: Prompt): Promise<ChatPromptResult>;
+    /**
+     * Calls a chat model with streaming
+     */
+    callChatModelStream?(prompt: Prompt, onProgress: (chunk: ChatPromptResult) => void): Promise<ChatPromptResult>;
+    /**
+     * Calls a voice chat model
+     */
+    callVoiceChatModel?(audio: Blob, prompt: Prompt): Promise<{
+        text: string;
+        audio: Blob;
+        userMessage?: string;
+        agentMessage?: string;
+    }>;
     /**
      * Calls a completion model
      */
     callCompletionModel?(prompt: Prompt): Promise<CompletionPromptResult>;
+    /**
+     * Calls a image generation model
+     */
+    callImageGenerationModel?(prompt: Prompt): Promise<ImagePromptResult>;
     /**
      * Calls an embedding model
      */
     callEmbeddingModel?(prompt: Prompt): Promise<EmbeddingPromptResult>;
 };
 /**
- * TODO: [🕛] Extend this from sth class
+ * TODO: [🕛] Extend this from sth class -  like `AgentBasicInformation` / `ModelBasicInformation``
  * TODO: [🍚] Implement destroyable pattern to free resources
  * TODO: [🏳] Add `callTranslationModel`
  * TODO: [🧠] Emulation of one type of model with another one - emuate chat with completion; emulate translation with chat

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

@@ -8,7 +8,7 @@ import type { Usage } from './Usage';
  *
  * @see https://github.com/webgptorg/promptbook#prompt-result
  */
-export type PromptResult = CompletionPromptResult | ChatPromptResult | EmbeddingPromptResult;
+export type PromptResult = CompletionPromptResult | ChatPromptResult | ImagePromptResult | EmbeddingPromptResult;
 /**
  * Completion prompt result
  *
@@ -22,6 +22,12 @@ export type CompletionPromptResult = CommonPromptResult;
  * Note: [🚉] This is fully serializable as JSON
  */
 export type ChatPromptResult = CommonPromptResult & {};
+/**
+ * Image prompt result
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type ImagePromptResult = CommonPromptResult;
 /**
  * Embedding prompt  result
  *

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

@@ -2,6 +2,7 @@ import type { PartialDeep, Promisable, ReadonlyDeep } from 'type-fest';
 import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
 import type { InputParameters } from '../../types/typeAliases';
 import type { PipelineExecutorResult } from '../PipelineExecutorResult';
+import type { LlmCall } from '../../types/LlmCall';
 import type { CreatePipelineExecutorOptions } from './00-CreatePipelineExecutorOptions';
 /**
  * Options for executing an entire pipeline, including input parameters, pipeline context, and progress callbacks.
@@ -17,6 +18,10 @@ type ExecutePipelineOptions = Required<CreatePipelineExecutorOptions> & {
      * Optional callback invoked with partial results as the pipeline execution progresses.
      */
     onProgress?(newOngoingResult: PartialDeep<PipelineExecutorResult>): Promisable<void>;
+    /**
+     * Optional callback invoked with each LLM call.
+     */
+    logLlmCall?(llmCall: LlmCall): Promisable<void>;
     /**
      * The pipeline definition to execute.
      */

package/esm/typings/src/execution/createPipelineExecutor/20-executeTask.d.ts

@@ -2,6 +2,7 @@ import type { PartialDeep, Promisable, ReadonlyDeep, WritableDeep } from 'type-f
 import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
 import type { TaskJson } from '../../pipeline/PipelineJson/TaskJson';
 import type { Parameters } from '../../types/typeAliases';
+import type { LlmCall } from '../../types/LlmCall';
 import type { ExecutionReportJson } from '../execution-report/ExecutionReportJson';
 import type { PipelineExecutorResult } from '../PipelineExecutorResult';
 import type { CreatePipelineExecutorOptions } from './00-CreatePipelineExecutorOptions';
@@ -27,6 +28,10 @@ type executeSingleTaskOptions = Required<CreatePipelineExecutorOptions> & {
      * Callback invoked with partial results as the execution progresses.
      */
     onProgress(newOngoingResult: PartialDeep<PipelineExecutorResult>): Promisable<void>;
+    /**
+     * Optional callback invoked with each LLM call.
+     */
+    logLlmCall?(llmCall: LlmCall): Promisable<void>;
     /**
      * Mutable execution report object for tracking execution details.
      */

package/esm/typings/src/execution/createPipelineExecutor/30-executeFormatSubvalues.d.ts

@@ -1,5 +1,6 @@
 import type { PartialDeep, Promisable } from 'type-fest';
 import type { TODO_any } from '../../utils/organization/TODO_any';
+import type { LlmCall } from '../../types/LlmCall';
 import type { PipelineExecutorResult } from '../PipelineExecutorResult';
 import type { ExecuteAttemptsOptions } from './40-executeAttempts';
 /**
@@ -13,6 +14,10 @@ type ExecuteFormatCellsOptions = ExecuteAttemptsOptions & {
      * Callback invoked with partial results as the execution progresses.
      */
     onProgress(newOngoingResult: PartialDeep<PipelineExecutorResult>): Promisable<void>;
+    /**
+     * Optional callback invoked with each LLM call.
+     */
+    logLlmCall?(llmCall: LlmCall): Promisable<void>;
 };
 /**
  * Executes a pipeline task that requires mapping or iterating over subvalues of a parameter (such as rows in a CSV).

package/esm/typings/src/execution/createPipelineExecutor/40-executeAttempts.d.ts

@@ -1,6 +1,7 @@
 import type { PartialDeep, Promisable, ReadonlyDeep, WritableDeep } from 'type-fest';
 import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
 import type { TaskJson } from '../../pipeline/PipelineJson/TaskJson';
+import type { LlmCall } from '../../types/LlmCall';
 import type { Parameters, string_parameter_name } from '../../types/typeAliases';
 import type { TODO_string } from '../../utils/organization/TODO_string';
 import type { ExecutionReportJson } from '../execution-report/ExecutionReportJson';
@@ -50,6 +51,10 @@ export type ExecuteAttemptsOptions = Required<Omit<CreatePipelineExecutorOptions
      * Callback invoked with partial results as the execution progresses.
      */
     onProgress(newOngoingResult: PartialDeep<PipelineExecutorResult>): Promisable<void>;
+    /**
+     * Optional callback invoked with each LLM call.
+     */
+    logLlmCall?(llmCall: LlmCall): Promisable<void>;
     /**
      * The execution report object, which is updated during execution.
      */

package/esm/typings/src/execution/utils/usage-constants.d.ts

@@ -3,145 +3,25 @@
  *
  * @public exported from `@promptbook/core`
  */
-export declare const ZERO_VALUE: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-    readonly value: 0;
-}>;
+export declare const ZERO_VALUE: any;
 /**
  * Represents the uncertain value
  *
  * @public exported from `@promptbook/core`
  */
-export declare const UNCERTAIN_ZERO_VALUE: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-    readonly value: 0;
-    readonly isUncertain: true;
-}>;
+export declare const UNCERTAIN_ZERO_VALUE: any;
 /**
  * Represents the usage with no resources consumed
  *
  * @public exported from `@promptbook/core`
  */
-export declare const ZERO_USAGE: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-    readonly price: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-        readonly value: 0;
-    }>;
-    readonly input: {
-        readonly tokensCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-        readonly charactersCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-        readonly wordsCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-        readonly sentencesCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-        readonly linesCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-        readonly paragraphsCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-        readonly pagesCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-    };
-    readonly output: {
-        readonly tokensCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-        readonly charactersCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-        readonly wordsCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-        readonly sentencesCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-        readonly linesCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-        readonly paragraphsCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-        readonly pagesCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-        }>;
-    };
-}>;
+export declare const ZERO_USAGE: any;
 /**
  * Represents the usage with unknown resources consumed
  *
  * @public exported from `@promptbook/core`
  */
-export declare const UNCERTAIN_USAGE: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-    readonly price: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-        readonly value: 0;
-        readonly isUncertain: true;
-    }>;
-    readonly input: {
-        readonly tokensCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-        readonly charactersCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-        readonly wordsCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-        readonly sentencesCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-        readonly linesCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-        readonly paragraphsCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-        readonly pagesCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-    };
-    readonly output: {
-        readonly tokensCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-        readonly charactersCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-        readonly wordsCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-        readonly sentencesCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-        readonly linesCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-        readonly paragraphsCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-        readonly pagesCount: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
-            readonly value: 0;
-            readonly isUncertain: true;
-        }>;
-    };
-}>;
+export declare const UNCERTAIN_USAGE: any;
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */

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

@@ -46,6 +46,8 @@ export type ValidatePromptResultResult = {
  * This function provides a common abstraction for result validation that can be used
  * by both execution logic and caching logic to ensure consistency.
  *
+ * Note: [🔂] This function is idempotent.
+ *
  * @param options - The validation options including result string, expectations, and format
  * @returns Validation result with processed string and validity status
  * @private internal function of `createPipelineExecutor` and `cacheLlmTools`

package/esm/typings/src/high-level-abstractions/_common/HighLevelAbstraction.d.ts

@@ -1,4 +1,5 @@
 import type { $PipelineJson } from '../../commands/_common/types/CommandParser';
+import type { $side_effect } from '../../utils/organization/$side_effect';
 /**
  * Used in `parsePipeline`
  *
@@ -11,7 +12,7 @@ export type SyncHighLevelAbstraction = {
      *
      * Note: `$` is used to indicate that this function mutates given `pipelineJson`
      */
-    $applyToPipelineJson($pipelineJson: $PipelineJson): void;
+    $applyToPipelineJson($pipelineJson: $PipelineJson): $side_effect;
 };
 /**
  * TODO: [♓️] Add order here