@promptbook/javascript 0.88.0-1

package/esm/typings/src/executables/locateApp.d.ts

@@ -0,0 +1,33 @@
+import type { RequireAtLeastOne } from 'type-fest';
+import type { string_executable_path } from '../types/typeAliases';
+/**
+ * Options for locating any application
+ */
+export interface LocateAppOptions {
+    /**
+     * Name of the application
+     */
+    appName: string;
+    /**
+     * Name of the executable on Linux
+     */
+    linuxWhich?: string;
+    /**
+     * Path suffix on Windows
+     */
+    windowsSuffix?: string;
+    /**
+     * Name of the application on macOS
+     */
+    macOsName?: string;
+}
+/**
+ * Locates an application on the system
+ *
+ * @private within the repository
+ */
+export declare function locateApp(options: RequireAtLeastOne<LocateAppOptions, 'linuxWhich' | 'windowsSuffix' | 'macOsName'>): Promise<string_executable_path | null>;
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

package/esm/typings/src/executables/locateApp.test.d.ts

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

package/esm/typings/src/executables/platforms/locateAppOnLinux.d.ts

@@ -0,0 +1,12 @@
+import type { string_executable_path } from '../../types/typeAliases';
+import type { LocateAppOptions } from '../locateApp';
+/**
+ * @@@
+ *
+ * @private within the repository
+ */
+export declare function locateAppOnLinux({ linuxWhich, }: Pick<Required<LocateAppOptions>, 'linuxWhich'>): Promise<string_executable_path | null>;
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

package/esm/typings/src/executables/platforms/locateAppOnMacOs.d.ts

@@ -0,0 +1,12 @@
+import type { string_executable_path } from '../../types/typeAliases';
+import type { LocateAppOptions } from '../locateApp';
+/**
+ * @@@
+ *
+ * @private within the repository
+ */
+export declare function locateAppOnMacOs({ macOsName, }: Pick<Required<LocateAppOptions>, 'macOsName'>): Promise<string_executable_path | null>;
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

package/esm/typings/src/executables/platforms/locateAppOnWindows.d.ts

@@ -0,0 +1,12 @@
+import type { string_executable_path } from '../../types/typeAliases';
+import type { LocateAppOptions } from '../locateApp';
+/**
+ * @@@
+ *
+ * @private within the repository
+ */
+export declare function locateAppOnWindows({ appName, windowsSuffix, }: Pick<Required<LocateAppOptions>, 'appName' | 'windowsSuffix'>): Promise<string_executable_path | null>;
+/**
+ * TODO: [🧠][♿] Maybe export through `@promptbook/node`
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

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

@@ -0,0 +1,25 @@
+import { ReadonlyDeep } from 'type-fest';
+import type { ErrorJson } from '../errors/utils/ErrorJson';
+/**
+ * @@@
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type AbstractTaskResult = {
+    /**
+     * Whether the execution was successful, details are available in `executionReport`
+     */
+    readonly isSuccessful: boolean;
+    /**
+     * Errors that occured during the execution, details are available in `executionReport`
+     */
+    readonly errors: ReadonlyDeep<ReadonlyArray<ErrorJson>>;
+    /**
+     * Warnings that occured during the execution, details are available in `executionReport`
+     */
+    readonly warnings: ReadonlyDeep<ReadonlyArray<ErrorJson>>;
+};
+/**
+ * TODO: [🧠] Should this file be in /execution or /types folder?
+ * TODO: [🧠] Maybe constrain `ErrorJson` -> `ErrorJson & { name: 'PipelineExecutionError' | 'Error' }`
+ */

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

@@ -0,0 +1,38 @@
+import type { ModelVariant } from '../types/ModelVariant';
+import type { string_model_description } from '../types/typeAliases';
+import type { string_model_name } from '../types/typeAliases';
+import type { string_title } from '../types/typeAliases';
+/**
+ * Represents a model that can be used for prompt execution
+ */
+export type AvailableModel = {
+    /**
+     * The model title, when not provided, the `modelName` should be used
+     *
+     * @example "GPT o1"
+     */
+    readonly modelTitle?: string_title;
+    /**
+     * The model name aviailable
+     *
+     * @example "o1"
+     */
+    readonly modelName: string_model_name;
+    /**
+     * Variant of the model
+     *
+     * @example "CHAT"
+     */
+    readonly modelVariant: ModelVariant;
+    /**
+     * Unstructured description of the model
+     *
+     * This will be used to pick the best available model for each task
+     *
+     * @example "Model with 1 billion parameters and advanced reasoning capabilities"
+     */
+    readonly modelDescription?: string_model_description;
+};
+/**
+ * TODO: (not only [🕘]) Put pricing information here
+ */

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

@@ -0,0 +1,24 @@
+import type { string_user_id } from '../types/typeAliases';
+/**
+ * @@@
+ *
+ * Note: Keep it public to allow people to make their own execution tools
+ */
+export type CommonToolsOptions = {
+    /**
+     * A unique identifier representing your end-user
+     *
+     * Note: For example it can help to detect abuse
+     * For example for OpenAi @see https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids
+     */
+    readonly userId?: string_user_id;
+    /**
+     * If true, the internal executions will be logged
+     */
+    readonly isVerbose?: boolean;
+};
+/**
+ * TODO: [🧠][🤺] Maybe allow overriding of `userId` for each prompt
+ * TODO: [🈁] Maybe add here `isDeterministic`
+ * TODO: [🧠][💙] Distinct between options passed into ExecutionTools and to ExecutionTools.execute
+ */

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

@@ -0,0 +1,8 @@
+/**
+ * Represents a vector in an latent space of the embedding model
+ */
+export type EmbeddingVector = ReadonlyArray<number>;
+/**
+ * TODO: Figure out how to use NPM package xyzt
+ *       Not using IVectorData due to HUGE dimensionality
+ */

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

@@ -0,0 +1,18 @@
+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;
+};

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

@@ -0,0 +1,75 @@
+import type { Observable } from 'rxjs';
+import { PartialDeep } from 'type-fest';
+import type { task_id } from '../types/typeAliases';
+import type { string_SCREAMING_CASE } from '../utils/normalization/normalizeTo_SCREAMING_CASE';
+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'];
+    /**
+     * Callback that processes the task and updates the ongoing result
+     * @param ongoingResult The partial result of the task processing
+     * @returns The final task result
+     */
+    taskProcessCallback(updateOngoingResult: (newOngoingResult: PartialDeep<TTaskResult>) => 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}`;
+};
+/**
+ * Base interface for all task types
+ */
+export type AbstractTask<TTaskResult extends AbstractTaskResult> = {
+    /**
+     * Type of the task
+     */
+    readonly taskType: string_SCREAMING_CASE;
+    /**
+     * Unique identifier for the task
+     */
+    readonly taskId: task_id;
+    /**
+     * Gets a promise that resolves with the task result
+     */
+    asPromise(options?: {
+        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
+     */
+    currentValue: PartialDeep<TTaskResult>;
+};
+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/esm/typings/src/execution/ExecutionTools.d.ts

@@ -0,0 +1,69 @@
+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;
+};

package/esm/typings/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'>;
+/**
+ * TODO: Implement destroyable pattern to free resources
+ */

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

@@ -0,0 +1,61 @@
+import type { Promisable } from 'type-fest';
+import type { Prompt } from '../types/Prompt';
+import type { string_markdown } from '../types/typeAliases';
+import type { string_markdown_text } from '../types/typeAliases';
+import type { string_title } from '../types/typeAliases';
+import type { AvailableModel } from './AvailableModel';
+import type { ChatPromptResult } from './PromptResult';
+import type { CompletionPromptResult } from './PromptResult';
+import type { EmbeddingPromptResult } from './PromptResult';
+/**
+ * Container for all the tools needed to execute prompts to large language models like GPT-4
+ * On its interface it exposes common methods for prompt execution.
+ * Inside (in constructor) it calls OpenAI, Azure, GPU, proxy, cache, logging,...
+ *
+ * @see https://github.com/webgptorg/promptbook#llm-execution-tools
+ */
+export type LlmExecutionTools = {
+    /**
+     * Title of the model provider
+     *
+     * @example "OpenAI"
+     */
+    readonly title: string_title & string_markdown_text;
+    /**
+     * Description of the provider
+     *
+     * @example "Use all models from OpenAI"
+     */
+    readonly description?: string_markdown;
+    /**
+     * 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 completion model
+     */
+    callCompletionModel?(prompt: Prompt): Promise<CompletionPromptResult>;
+    /**
+     * Calls an embedding model
+     */
+    callEmbeddingModel?(prompt: Prompt): Promise<EmbeddingPromptResult>;
+};
+/**
+ * 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/esm/typings/src/execution/LlmExecutionToolsConstructor.d.ts

@@ -0,0 +1,10 @@
+import type { Registered } from '../utils/$Register';
+import type { TODO_any } from '../utils/organization/TODO_any';
+import type { LlmExecutionTools } from './LlmExecutionTools';
+/**
+ * @@@
+ */
+export type LlmExecutionToolsConstructor = Registered & ((options: TODO_any) => LlmExecutionTools);
+/**
+ * TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
+ */

package/esm/typings/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/esm/typings/src/execution/PipelineExecutorResult.d.ts

@@ -0,0 +1,37 @@
+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 { PromptResultUsage } from './PromptResultUsage';
+/**
+ * @@@
+ *
+ * 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<PromptResultUsage>;
+    /**
+     * The report of the execution with all details
+     */
+    readonly executionReport: ReadonlyDeep<ExecutionReportJson>;
+    /**
+     * 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/esm/typings/src/execution/PromptResult.d.ts

@@ -0,0 +1,101 @@
+import type { string_date_iso8601 } from '../types/typeAliases';
+import type { string_model_name } from '../types/typeAliases';
+import type { string_prompt } from '../types/typeAliases';
+import type { TODO_object } from '../utils/organization/TODO_object';
+import type { EmbeddingVector } from './EmbeddingVector';
+import type { PromptResultUsage } from './PromptResultUsage';
+/**
+ * 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 | 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 & {};
+/**
+ * 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 = {
+    /**
+     * Exact 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: PromptResultUsage;
+    /**
+     * 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/esm/typings/src/execution/PromptResultUsage.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 many prompt results
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type PromptResultUsage = {
+    /**
+     * 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: PromptResultUsageCounts;
+    /**
+     * Number of tokens used in the output aka. `completion_tokens`
+     */
+    readonly output: PromptResultUsageCounts;
+};
+/**
+ * Record of all possible measurable units
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type PromptResultUsageCounts = Record<`${KebabCase<'TOKENS' | ExpectationUnit>}Count`, UncertainNumber>;
+/**
+ * TODO: [🍙] Make some standard order of json properties
+ */

package/esm/typings/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 theese places:
+ * - Fetching knowledge sources
+ * - Callbacks from remote server ([👩🏾‍🤝‍🧑🏾] Not yet implemented)
+ */
+export type PromptbookFetch = (url: string_url, init?: RequestInit) => Promise<Response>;

package/esm/typings/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?
+ */