@promptbook/javascript 0.111.0-3 → 0.111.0-7

package/umd/src/execution/Executables.d.ts

@@ -0,0 +1,21 @@
+import type { string_executable_path } from '../types/typeAliases';
+/**
+ * Paths to the external programs executables
+ */
+export type Executables = {
+    /**
+     * Path to the `pandoc` executable
+     *
+     * @example 'C:/Users/me/AppData/Local/Pandoc/pandoc.exe'
+     */
+    pandocPath?: string_executable_path;
+    /**
+     * Path to the LibreOffice executable
+     *
+     * @example 'C:/Program Files/LibreOffice/program/swriter.exe'
+     */
+    libreOfficePath?: string_executable_path;
+};
+/**
+ * <- TODO: Add !!! `browserPath` to `Executables`
+ */

package/umd/src/execution/ExecutionTask.d.ts

@@ -0,0 +1,154 @@
+import type { Observable } from 'rxjs';
+import { PartialDeep } from 'type-fest';
+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';
+/**
+ * Options for creating a new task
+ */
+type CreateTaskOptions<TTaskResult extends AbstractTaskResult> = {
+    /**
+     * The type of task to create
+     */
+    readonly taskType: AbstractTask<TTaskResult>['taskType'];
+    /**
+     * Human-readable title of the task - used for displaying in the UI
+     */
+    readonly title: AbstractTask<TTaskResult>['title'];
+    /**
+     * Callback that processes the task and updates the ongoing result
+     * @param updateOngoingResult Function to update the partial result of the task processing
+     * @param updateTldr Function to update tldr progress information
+     * @returns The final task result
+     */
+    taskProcessCallback(updateOngoingResult: (newOngoingResult: PartialDeep<TTaskResult> & {
+        /**
+         * Optional update of the task title
+         */
+        readonly title?: AbstractTask<TTaskResult>['title'];
+    }) => void, updateTldr: (tldrInfo: {
+        readonly percent: number_percent;
+        readonly message: string;
+    }) => void, logLlmCall: (llmCall: LlmCall) => void): Promise<TTaskResult>;
+};
+/**
+ * Helper to create a new task
+ *
+ * @private internal helper function
+ */
+export declare function createTask<TTaskResult extends AbstractTaskResult>(options: CreateTaskOptions<TTaskResult>): AbstractTask<TTaskResult>;
+/**
+ * Represents a task that executes a pipeline
+ */
+export type ExecutionTask = AbstractTask<PipelineExecutorResult> & {
+    readonly taskType: 'EXECUTION';
+    readonly taskId: `exec-${task_id}`;
+};
+/**
+ * Represents a task that prepares a pipeline
+ * @deprecated TODO: [🐚] Currently unused - use
+ */
+export type PreparationTask = AbstractTask<PipelineExecutorResult> & {
+    readonly taskType: 'PREPARATION';
+    readonly taskId: `prep-${task_id}`;
+};
+/**
+ * Status of a task
+ */
+export type task_status = 'RUNNING' | 'FINISHED' | 'ERROR';
+/**
+ * Base interface for all task types
+ */
+export type AbstractTask<TTaskResult extends AbstractTaskResult> = {
+    /**
+     * Type of the task
+     */
+    readonly taskType: string_SCREAMING_CASE;
+    /**
+     * Version of the promptbook used to run the task
+     */
+    readonly promptbookVersion: string_promptbook_version;
+    /**
+     * Unique identifier for the task
+     */
+    readonly taskId: task_id;
+    /**
+     * Human-readable title of the task - used for displaying in the UI
+     *
+     * For example name of the book which is being executed
+     */
+    readonly title: string;
+    /**
+     * Status of the task
+     */
+    readonly status: task_status;
+    /**
+     * Short summary of the task status for quick overview in the UI
+     */
+    readonly tldr: {
+        /**
+         * Progress in percentage from 0 to 1 (100%) that can be used to display a progress bar
+         */
+        readonly percent: number_percent;
+        /**
+         * Short summary message of the task status that can be displayed in the UI
+         */
+        readonly message: string;
+    };
+    /**
+     * Date when the task was created
+     */
+    readonly createdAt: Date;
+    /**
+     * Date when the task was last updated
+     */
+    readonly updatedAt: Date;
+    /**
+     * Gets a promise that resolves with the task result
+     */
+    asPromise(options?: {
+        /**
+         * Do the task throws on error
+         *
+         * - If `true` when error occurs the returned promise will rejects
+         * - If `false` the promise will resolve with object with all listed errors and warnings and partial result
+         *
+         * @default true
+         */
+        readonly isCrashedOnError?: boolean;
+    }): Promise<TTaskResult>;
+    /**
+     * Gets an observable stream of partial task results
+     */
+    asObservable(): Observable<PartialDeep<TTaskResult>>;
+    /**
+     * Gets just the current value which is mutated during the task processing
+     */
+    readonly currentValue: PartialDeep<TTaskResult>;
+    /**
+     * List of errors that occurred during the task processing
+     */
+    readonly errors: Array<Error>;
+    /**
+     * 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 {};
+/**
+ * TODO: Maybe allow to terminate the task and add getter `isFinished` or `status`
+ * TODO: [🐚] Split into more files and make `PrepareTask` & `RemoteTask` + split the function
+ */

package/umd/src/execution/ExecutionTools.d.ts

@@ -0,0 +1,74 @@
+import type { Scraper } from '../scrapers/_common/Scraper';
+import type { Arrayable } from '../types/Arrayable';
+import type { Executables } from './Executables';
+import type { FilesystemTools } from './FilesystemTools';
+import type { LlmExecutionTools } from './LlmExecutionTools';
+import type { PromptbookFetch } from './PromptbookFetch';
+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 in large language models
+     *
+     * Tip: Use `$provideLlmToolsFromEnv` to use all available LLM providers you configured
+     *
+     * @default [] - If not provided, no LLM execution will be possible - it does not make sense in most cases
+     */
+    readonly llm?: Arrayable<LlmExecutionTools>;
+    /**
+     * Tools for filesystem operations
+     *
+     * Tip: Use `$provideFilesystemForNode` to use filesystem in Node.js
+     *
+     * @default undefined - If not provided, no filesystem operations will be possible
+     */
+    readonly fs?: FilesystemTools;
+    /**
+     * Fetch function for fetching resources
+     *
+     * @default `fetch` - If not provided, the built-in `fetch' function is used with a lightweight error handling wrapper.
+     */
+    readonly fetch?: PromptbookFetch;
+    /**
+     * Scrapers for extracting knowledge from external sources
+     *
+     * Tip: Use `$provideExecutablesForNode`
+     *
+     * @default [] - If not provided, no external knowledge extraction will be possible
+     */
+    readonly executables?: Executables;
+    /**
+     * Scrapers for extracting knowledge from external sources
+     *
+     * Tip: Use `$provideScrapersForNode` OR `$provideScrapersForBrowser` to use all available scrapers
+     *
+     * @default [] - If not provided, no external knowledge extraction will be possible
+     */
+    readonly scrapers?: Arrayable<Scraper>;
+    /**
+     * 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
+     * Tip: Use here `new JavascriptExecutionTools`
+     *
+     * @default [] - If not provided, no script execution will be possible
+     */
+    readonly 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
+     */
+    readonly userInterface?: UserInterfaceTools;
+};
+/**
+ * <- TODO: Add !!! `promptbookAgent` to `ExecutionTools`
+ * <- TODO: Add !!! `mcps` to `ExecutionTools`
+ * <- TODO: Add !!! `prepareCache` to `ExecutionTools`
+ */

package/umd/src/execution/FilesystemTools.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="node" />
+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' | 'watch'>;
+/**
+ * TODO: Implement destroyable pattern to free resources
+ */

package/umd/src/execution/LlmExecutionTools.d.ts

@@ -0,0 +1,93 @@
+import type { Promisable } from 'type-fest';
+import type { ChatParticipant } from '../book-components/Chat/types/ChatParticipant';
+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, 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` - (Deprecated) which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities
+ * - `OpenAiAgentKitExecutionTools` - which is a specific implementation of `LlmExecutionTools` backed by OpenAI AgentKit
+ * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
+ *
+ * @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;
+    /**
+     * Profile representing the model as a virtual persona for chat interfaces
+     * This includes visual identity like avatar, colors, and display information
+     *
+     * @example { name: 'OPENAI', fullname: 'OpenAI GPT', color: '#10a37f', avatarSrc: '/openai-logo.png' }
+     */
+    readonly profile?: ChatParticipant;
+    /**
+     * Check comfiguration
+     *
+     * @returns nothing if configuration is correct
+     * @throws {Error} if configuration is incorrect
+     */
+    checkConfiguration(): Promisable<void>;
+    /**
+     * List all available models that can be used
+     */
+    listModels(): Promisable<ReadonlyArray<AvailableModel>>;
+    /**
+     * Calls a chat model
+     */
+    callChatModel?(prompt: Prompt): Promise<ChatPromptResult>;
+    /**
+     * Calls a chat model with streaming
+     */
+    callChatModelStream?(prompt: Prompt, onProgress: (chunk: ChatPromptResult & {
+        isFinished?: boolean;
+    }) => 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 -  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
+ * 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
+ * TODO: [🧠][🪐] Should be common things like types, utils in folder containing A,B,C,.. or else outside this listing folder?
+ */

package/umd/src/execution/LlmExecutionToolsConstructor.d.ts

@@ -0,0 +1,11 @@
+import type { Registered } from '../utils/misc/$Register';
+import type { TODO_any } from '../utils/organization/TODO_any';
+import type { LlmExecutionTools } from './LlmExecutionTools';
+/**
+ * Type representing a constructor for LLM execution tools, which are used to interact with language models.
+ * Combines registration metadata with a factory function for creating LLM tool instances.
+ */
+export type LlmExecutionToolsConstructor = Registered & ((options: TODO_any) => LlmExecutionTools);
+/**
+ * TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
+ */

package/umd/src/execution/PipelineExecutor.d.ts

@@ -0,0 +1,16 @@
+import type { InputParameters } from '../types/typeAliases';
+import type { ExecutionTask } from './ExecutionTask';
+/**
+ * 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: InputParameters): ExecutionTask;
+};
+/**
+ * TODO: [🧠] Should this file be in /execution or /types folder?
+ */

package/umd/src/execution/PipelineExecutorResult.d.ts

@@ -0,0 +1,39 @@
+import { ReadonlyDeep } from 'type-fest';
+import type { PipelineJson } from '../pipeline/PipelineJson/PipelineJson';
+import type { Parameters } from '../types/typeAliases';
+import type { AbstractTaskResult } from './AbstractTaskResult';
+import type { ExecutionReportJson } from './execution-report/ExecutionReportJson';
+import type { Usage } from './Usage';
+/**
+ * The result of executing a pipeline
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type PipelineExecutorResult = AbstractTaskResult & {
+    /**
+     * Result parameters of the execution
+     *
+     * Note: If the execution was not successful, there are only some of the result parameters
+     */
+    readonly outputParameters: Readonly<Parameters>;
+    /**
+     * Added usage of whole execution, detailed usage is available in `executionReport`
+     */
+    readonly usage: ReadonlyDeep<Usage>;
+    /**
+     * The report of the execution with all details
+     *
+     * Note: If the execution fails unexpectedly, this will be `null`
+     */
+    readonly executionReport: ReadonlyDeep<ExecutionReportJson> | null;
+    /**
+     * The prepared pipeline that was used for the execution
+     *
+     * Note: If you called `createPipelineExecutor` with fully prepared pipeline, this is the same object as this pipeline
+     *       If you passed not fully prepared pipeline, this is same pipeline but fully prepared
+     */
+    readonly preparedPipeline: ReadonlyDeep<PipelineJson>;
+};
+/**
+ * TODO: [🧠] Should this file be in /execution or /types folder?
+ */

package/umd/src/execution/PromptResult.d.ts

@@ -0,0 +1,111 @@
+import type { ToolCall } from '../types/ToolCall';
+import type { string_date_iso8601, string_model_name, string_prompt } from '../types/typeAliases';
+import type { TODO_object } from '../utils/organization/TODO_object';
+import type { EmbeddingVector } from './EmbeddingVector';
+import type { Usage } from './Usage';
+/**
+ * Prompt result is the simplest concept of execution.
+ * It is the result of executing one prompt _(NOT a template)_.
+ *
+ * @see https://github.com/webgptorg/promptbook#prompt-result
+ */
+export type PromptResult = CompletionPromptResult | ChatPromptResult | ImagePromptResult | EmbeddingPromptResult;
+/**
+ * Completion prompt result
+ *
+ * Note:It contains only the newly generated text NOT the whole completion
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type CompletionPromptResult = CommonPromptResult;
+/**
+ *Chat prompt result
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type ChatPromptResult = CommonPromptResult & {
+    /**
+     * Optional tool calls made during the execution
+     */
+    readonly toolCalls?: ReadonlyArray<ToolCall>;
+};
+/**
+ * Image prompt result
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type ImagePromptResult = CommonPromptResult;
+/**
+ * Embedding prompt  result
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type EmbeddingPromptResult = Omit<CommonPromptResult, 'content'> & {
+    /**
+     * The response from the model
+     */
+    content: EmbeddingVector;
+};
+/**
+ * Common properties for all prompt results
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private just abstract the common properties of the prompt results
+ */
+export type CommonPromptResult = {
+    /**
+     * Text response from the model
+     */
+    readonly content: string;
+    /**
+     * Name of the model used to generate the response
+     */
+    readonly modelName: string_model_name;
+    /**
+     * Timing
+     */
+    readonly timing: {
+        /**
+         * Start of the execution
+         */
+        readonly start: string_date_iso8601;
+        /**
+         * First token generated
+         */
+        readonly firstToken?: string_date_iso8601;
+        /**
+         * End of the execution
+         */
+        readonly complete: string_date_iso8601;
+    };
+    /**
+     * Usage of the prompt execution
+     */
+    readonly usage: Usage;
+    /**
+     * Exact text of the prompt (with all replacements)
+     *
+     * Note: This contains redundant information
+     */
+    readonly rawPromptContent: string_prompt;
+    /**
+     * Raw request to the model
+     *
+     * Note: This contains redundant information
+     */
+    readonly rawRequest: TODO_object | null;
+    /**
+     * Raw response from the model
+     *
+     * Note: This contains redundant information
+     */
+    readonly rawResponse: TODO_object;
+};
+/**
+ * TODO: [🧠] Maybe timing more accurate then seconds?
+ * TODO: [🧠] Should here be link to the prompt?
+ * TODO: [🧠] Maybe type `rawResponse` properly - not onject but OpenAI.result.whatever
+ * TODO: [🧠] Maybe remove redundant raw.choices.text
+ * TODO: Log raw even if prompt failed - log the raw error
+ * TODO: [🏳] Add `TranslationPromptResult`
+ */

package/umd/src/execution/PromptbookFetch.d.ts

@@ -0,0 +1,12 @@
+import type { string_url } from '../types/typeAliases';
+/**
+ * Fetch function used in Promptbook engine
+ *
+ * In most cases it is just native `fetch` function with a lightweight error handling wrapper
+ * But it can be replaced with any other fetch function, polyfill, custom implementation, security layer, etc.
+ *
+ * It is used in these places:
+ * - Fetching knowledge sources
+ * - Callbacks from remote server
+ */
+export type PromptbookFetch = (url: string_url, init?: RequestInit) => Promise<Response>;

package/umd/src/execution/PromptbookFetch.test-type.d.ts

@@ -0,0 +1,5 @@
+export {};
+/**
+ * Note: [⚪] This should never be in any released package
+ * TODO: Is this a good pattern to do type testing?
+ */

package/umd/src/execution/ScriptExecutionTools.d.ts

@@ -0,0 +1,39 @@
+import type { ScriptLanguage } from '../types/ScriptLanguage';
+import type { Parameters } from '../types/typeAliases';
+import type { string_script } from '../types/typeAliases';
+/**
+ * Represents all the tools needed to execute `SCRIPT` tasks
+ *
+ * @see https://github.com/webgptorg/promptbook#script-execution-tools
+ */
+export type ScriptExecutionTools = {
+    execute(options: ScriptExecutionToolsExecuteOptions): Promise<string>;
+};
+/**
+ * Input for the script execution
+ */
+export type ScriptExecutionToolsExecuteOptions = {
+    /**
+     * Language of the script
+     */
+    readonly scriptLanguage: ScriptLanguage;
+    /**
+     * Parameters for the script
+     * These parameters are passed to the script as variables
+     * For example: { "name": "John" } => const name = "John";
+     */
+    readonly parameters: Parameters;
+    /**
+     * The content of the script to execute
+     * - It can be a single statement
+     * - It can be multiple statements separated by semicolon and return
+     * - It can be a function (but you need to call it)
+     * - It can be IIFE (immediately invoked function expression)
+     * - It can use the parameters as variables and functions from global scope
+     */
+    readonly script: string_script;
+};
+/**
+ * TODO: [🧠][💙] Distinct between options passed into ExecutionTools and to ExecutionTools.execute
+ * TODO: [🧠][🪐] Should be common things like types, utils in folder containing A,B,C,.. or else outside this listing folder?
+ */

package/umd/src/execution/UncertainNumber.d.ts

@@ -0,0 +1,19 @@
+import type { number_positive } from '../types/typeAliases';
+import type { number_usd } from '../types/typeAliases';
+/**
+ * Number which can be uncertain
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ * Note: If the value is completelly unknown, the value 0 and isUncertain is true
+ * Note: Not using NaN or null because it looses the value which is better to be uncertain then not to be at all
+ */
+export type UncertainNumber = {
+    /**
+     * The numeric value
+     */
+    readonly value: number_usd & (number_positive | 0);
+    /**
+     * Is the value uncertain
+     */
+    readonly isUncertain?: true;
+};

package/umd/src/execution/Usage.d.ts

@@ -0,0 +1,33 @@
+import type { KebabCase } from 'type-fest';
+import type { ExpectationUnit } from '../pipeline/PipelineJson/Expectations';
+import type { UncertainNumber } from './UncertainNumber';
+/**
+ * Usage statistics for one or more prompt results
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type Usage = {
+    /**
+     * Cost of the execution in USD
+     *
+     * Note: If the cost is unknown, the value 0 and isUncertain is true
+     */
+    readonly price: UncertainNumber;
+    /**
+     * Number of whatever used in the input aka. `prompt_tokens`
+     */
+    readonly input: UsageCounts;
+    /**
+     * Number of tokens used in the output aka. `completion_tokens`
+     */
+    readonly output: UsageCounts;
+};
+/**
+ * Record of all possible measurable units
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type UsageCounts = Record<`${KebabCase<'TOKENS' | ExpectationUnit>}Count`, UncertainNumber>;
+/**
+ * TODO: [🍙] Make some standard order of json properties
+ */