@promptbook/javascript 0.111.0-4 → 0.111.0-7

package/umd/src/storage/blackhole/BlackholeStorage.d.ts

@@ -0,0 +1,33 @@
+import type { PromptbookStorage } from '../_common/PromptbookStorage';
+/**
+ * Behaves like a storage but forgets everything you put in it
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare class BlackholeStorage<TItem> implements PromptbookStorage<TItem> {
+    /**
+     * Returns the number of key/value pairs currently present in the list associated with the object.
+     */
+    get length(): number;
+    /**
+     * Empties the list associated with the object of all key/value pairs, if there are any.
+     */
+    clear(): void;
+    /**
+     * Returns the current value associated with the given key, or null if the given key does not exist in the list associated with the object.
+     * @param key
+     */
+    getItem(key: string): null;
+    /**
+     * Returns the name of the nth key in the list, or null if n is greater than or equal to the number of key/value pairs in the object.
+     */
+    key(index: number): null;
+    /**
+     * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+     */
+    setItem(key: string, value: TItem): void;
+    /**
+     * Removes the key/value pair with the given key from the list associated with the object, if a key/value pair with the given key exists.
+     */
+    removeItem(key: string): void;
+}

package/umd/src/storage/env-storage/$EnvStorage.d.ts

@@ -0,0 +1,41 @@
+import type { $side_effect } from '../../utils/organization/$side_effect';
+import type { PromptbookStorage } from '../_common/PromptbookStorage';
+/**
+ * Stores data in .env variables
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file and also writes to `process.env`
+ *
+ * @private within the repository - for CLI utils
+ */
+export declare class $EnvStorage<TItem> implements PromptbookStorage<TItem> {
+    private envFilename;
+    private $provideOrCreateEnvFile;
+    private transformKey;
+    /**
+     * Returns the number of key/value pairs currently present in the list associated with the object.
+     */
+    get length(): number;
+    /**
+     * Empties the list associated with the object of all key/value pairs, if there are any.
+     */
+    clear(): void;
+    /**
+     * Returns the current value associated with the given key, or null if the given key does not exist in the list associated with the object.
+     */
+    getItem(key: string): Promise<TItem | null>;
+    /**
+     * Returns the name of the nth key in the list, or null if n is greater than or equal to the number of key/value pairs in the object.
+     */
+    key(index: number): string | null;
+    /**
+     * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+     */
+    setItem(key: string, value: TItem): Promise<$side_effect>;
+    /**
+     * Removes the key/value pair with the given key from the list associated with the object, if a key/value pair with the given key exists.
+     */
+    removeItem(key: string): void;
+}
+/**
+ * TODO: Write file more securely - ensure that there can be no accidental overwriting of existing variables and other content
+ */

package/umd/src/storage/file-cache-storage/FileCacheStorage.d.ts

@@ -0,0 +1,40 @@
+import type { ExecutionTools } from '../../execution/ExecutionTools';
+import type { PromptbookStorage } from '../_common/PromptbookStorage';
+import type { FileCacheStorageOptions } from './FileCacheStorageOptions';
+/**
+ * A storage implementation that caches data in files organized in a directory structure.
+ * Provides methods for retrieving, storing, and managing cached data on the filesystem.
+ *
+ * This class implements the PromptbookStorage interface for filesystem-based caching.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare class FileCacheStorage<TItem> implements PromptbookStorage<TItem> {
+    protected readonly tools: Required<Pick<ExecutionTools, 'fs'>>;
+    private readonly options;
+    constructor(tools: Required<Pick<ExecutionTools, 'fs'>>, options: FileCacheStorageOptions);
+    /**
+     * Converts a storage key to a filesystem path where the data should be stored.
+     * Creates a consistent, deterministic file path based on the key string.
+     */
+    private getFilenameForKey;
+    /**
+     * Returns the current value associated with the given key, or null if the given key does not exist.
+     * Retrieves the cached data from the file system storage.
+     */
+    getItem(key: string): Promise<TItem | null>;
+    /**
+     * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+     * Persists data to the file system, creating necessary directory structure if it doesn't exist.
+     */
+    setItem(key: string, value: TItem): Promise<void>;
+    /**
+     * Removes the key/value pair with the given key from the storage, if a key/value pair with the given key exists.
+     * Deletes the corresponding file from the filesystem.
+     */
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * TODO: [🌗] Maybe some checkers, not all valid JSONs are desired and valid values
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

package/umd/src/storage/file-cache-storage/FileCacheStorageOptions.d.ts

@@ -0,0 +1,12 @@
+import type { string_dirname } from '../../types/typeAliases';
+/**
+ * Configuration options for the FileCacheStorage implementation.
+ * Defines how and where file cache data should be stored and managed.
+ */
+export type FileCacheStorageOptions = {
+    /**
+     * The absolute path to the root directory where cache files will be stored.
+     * This directory must exist and be writable by the application.
+     */
+    rootFolderPath: string_dirname;
+};

package/umd/src/storage/file-cache-storage/utils/nameToSubfolderPath.d.ts

@@ -0,0 +1,8 @@
+import type { string_name } from '../../../types/typeAliases';
+/**
+ * Converts a name to a properly formatted subfolder path for cache storage.
+ * Handles normalization and path formatting to create consistent cache directory structures.
+ *
+ * @private for `FileCacheStorage`
+ */
+export declare function nameToSubfolderPath(name: string_name): ReadonlyArray<string>;

package/umd/src/storage/file-cache-storage/utils/nameToSubfolderPath.test.d.ts

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

package/umd/src/storage/local-storage/getIndexedDbStorage.d.ts

@@ -0,0 +1,11 @@
+import type { PromptbookStorage } from '../_common/PromptbookStorage';
+import type { IndexedDbStorageOptions } from './utils/IndexedDbStorageOptions';
+/**
+ * Gets wrapper around IndexedDB which can be used as PromptbookStorage
+ *
+ * @public exported from `@promptbook/browser`
+ */
+export declare function getIndexedDbStorage<TItem>(options: IndexedDbStorageOptions): PromptbookStorage<TItem>;
+/**
+ * Note: [🔵] Code in this file should never be published outside of `@promptbook/browser`
+ */

package/umd/src/storage/local-storage/getLocalStorage.d.ts

@@ -0,0 +1,10 @@
+import type { PromptbookStorage } from '../_common/PromptbookStorage';
+/**
+ * Gets wrapper around `localStorage` object which can be used as `PromptbookStorage`
+ *
+ * @public exported from `@promptbook/browser`
+ */
+export declare function getLocalStorage<TItem>(): PromptbookStorage<TItem>;
+/**
+ * Note: [🔵] Code in this file should never be published outside of `@promptbook/browser`
+ */

package/umd/src/storage/local-storage/getSessionStorage.d.ts

@@ -0,0 +1,10 @@
+import type { PromptbookStorage } from '../_common/PromptbookStorage';
+/**
+ * Gets wrapper around `sessionStorage` object which can be used as `PromptbookStorage`
+ *
+ * @public exported from `@promptbook/browser`
+ */
+export declare function getSessionStorage<TItem>(): PromptbookStorage<TItem>;
+/**
+ * Note: [🔵] Code in this file should never be published outside of `@promptbook/browser`
+ */

package/umd/src/storage/local-storage/utils/IndexedDbStorageOptions.d.ts

@@ -0,0 +1,14 @@
+import type { string_name } from '../../../types/typeAliases';
+/**
+ * Options for IndexedDB storage
+ */
+export type IndexedDbStorageOptions = {
+    /**
+     * Name of the database
+     */
+    databaseName: string_name;
+    /**
+     * Name of the object store (table) in the database
+     */
+    storeName: string_name;
+};

package/umd/src/storage/local-storage/utils/makePromptbookStorageFromIndexedDb.d.ts

@@ -0,0 +1,8 @@
+import type { PromptbookStorage } from '../../_common/PromptbookStorage';
+import type { IndexedDbStorageOptions } from './IndexedDbStorageOptions';
+/**
+ * Creates a PromptbookStorage backed by IndexedDB.
+ * Uses a single object store named 'promptbook'.
+ * @private for `getIndexedDbStorage`
+ */
+export declare function makePromptbookStorageFromIndexedDb<TValue>(options: IndexedDbStorageOptions): PromptbookStorage<TValue>;

package/umd/src/storage/local-storage/utils/makePromptbookStorageFromWebStorage.d.ts

@@ -0,0 +1,12 @@
+import type { PromptbookStorage } from '../../_common/PromptbookStorage';
+/**
+ * Creates a Promptbook storage interface from a web storage object.
+ * Facilitates using Web Storage (localStorage/sessionStorage) as a storage backend.
+ *
+ * @private for `getLocalStorage` and `getSessionStorage`
+ */
+export declare function makePromptbookStorageFromWebStorage<TValue>(webStorage: Storage): PromptbookStorage<TValue>;
+/**
+ * TODO: [🧠] Should this be named `makePromptbookStorageFromWebStorage` vs `createPromptbookStorageFromWebStorage`
+ * TODO: [🌗] Maybe some checkers, not all valid JSONs are desired and valid values
+ */

package/umd/src/storage/memory/MemoryStorage.d.ts

@@ -0,0 +1,33 @@
+import type { PromptbookStorage } from '../_common/PromptbookStorage';
+/**
+ * Stores data in memory (HEAP)
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare class MemoryStorage<TItem> implements PromptbookStorage<TItem> {
+    private storage;
+    /**
+     * Returns the number of key/value pairs currently present in the list associated with the object.
+     */
+    get length(): number;
+    /**
+     * Empties the list associated with the object of all key/value pairs, if there are any.
+     */
+    clear(): void;
+    /**
+     * Returns the current value associated with the given key, or null if the given key does not exist in the list associated with the object.
+     */
+    getItem(key: string): TItem | null;
+    /**
+     * Returns the name of the nth key in the list, or null if n is greater than or equal to the number of key/value pairs in the object.
+     */
+    key(index: number): string | null;
+    /**
+     * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+     */
+    setItem(key: string, value: TItem): void;
+    /**
+     * Removes the key/value pair with the given key from the list associated with the object, if a key/value pair with the given key exists.
+     */
+    removeItem(key: string): void;
+}

package/umd/src/storage/utils/PrefixStorage.d.ts

@@ -0,0 +1,25 @@
+import type { Promisable } from 'type-fest';
+import type { PromptbookStorage } from '../_common/PromptbookStorage';
+/**
+ * This class behaves like LocalStorage but separates keys by prefix
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare class PrefixStorage<TItem> implements PromptbookStorage<TItem> {
+    private baseStorage;
+    private keyPrefix;
+    private separator;
+    constructor(baseStorage: PromptbookStorage<TItem>, keyPrefix: string, separator?: string);
+    /**
+     * Returns the current value associated with the given key, or null if the given key does not exist in the list associated with the object.
+     */
+    getItem(key: string): Promisable<TItem | null>;
+    /**
+     * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+     */
+    setItem(key: string, value: TItem): Promisable<void>;
+    /**
+     * Removes the key/value pair with the given key from the list associated with the object, if a key/value pair with the given key exists.
+     */
+    removeItem(key: string): void;
+}

package/umd/src/transpilers/_common/BookTranspiler.d.ts

@@ -0,0 +1,33 @@
+import { Promisable } from 'type-fest';
+import type { string_book } from '../../book-2.0/agent-source/string_book';
+import type { ExecutionTools } from '../../execution/ExecutionTools';
+import type { string_name, string_script, string_title } from '../../types/typeAliases';
+import type { Registered } from '../../utils/misc/$Register';
+import type { BookTranspilerOptions } from './BookTranspilerOptions';
+/**
+ * Transpiler takes a book and transpiles it into another format (e.g., Langchain).
+ */
+export type BookTranspiler = Registered & {
+    /**
+     * The name of the transpiler.
+     * It is used to identify the transpiler in the register.
+     *
+     * @example 'python-langchain'
+     */
+    readonly name: string_name;
+    /**
+     * The title of the transpiler.
+     * It is used to display the transpiler in the UI.
+     *
+     * @example 'Python Langchain'
+     */
+    readonly title: string_title;
+    /**
+     * Transpiles a book.
+     *
+     * @param book book to transpile
+     * @param options additional options for the transpiler
+     * @returns transpiled book
+     */
+    transpileBook(book: string_book, tools: ExecutionTools, options?: BookTranspilerOptions): Promisable<string_script>;
+};

package/umd/src/transpilers/_common/BookTranspilerOptions.d.ts

@@ -0,0 +1,18 @@
+import type { CommonToolsOptions } from '../../execution/CommonToolsOptions';
+/**
+ * Options for the BookTranspiler.
+ */
+export type BookTranspilerOptions = Omit<CommonToolsOptions, 'maxRequestsPerMinute'> & {
+    /**
+     * If true, the transpiler will log verbose information to the console.
+     *
+     * @default false
+     */
+    readonly isVerbose?: boolean;
+    /**
+     * If true, the transpiler will include comments in the output.
+     *
+     * @default true
+     */
+    readonly shouldIncludeComments?: boolean;
+};

package/umd/src/transpilers/_common/register/$bookTranspilersRegister.d.ts

@@ -0,0 +1,15 @@
+import { $Register } from '../../../utils/misc/$Register';
+import type { BookTranspiler } from '../BookTranspiler';
+/**
+ * Register for book transpilers.
+ *
+ * Note: `$` is used to indicate that this interacts with the global scope
+ * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
+ * @see https://github.com/webgptorg/promptbook/issues/249
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const $bookTranspilersRegister: $Register<BookTranspiler>;
+/**
+ * TODO: [®] DRY Register logic
+ */

package/umd/src/transpilers/formatted-book-in-markdown/FormattedBookInMarkdownTranspiler.d.ts

@@ -0,0 +1,16 @@
+import type { string_book } from '../../book-2.0/agent-source/string_book';
+import type { ExecutionTools } from '../../execution/ExecutionTools';
+import type { string_markdown } from '../../types/typeAliases';
+import type { BookTranspilerOptions } from '../_common/BookTranspilerOptions';
+/**
+ * Converts a book into a 1:1 formatted markdown
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const FormattedBookInMarkdownTranspiler: {
+    readonly name: "formatted-book-in-markdown";
+    readonly title: "Formatted Book in Markdown";
+    readonly packageName: "@promptbook/core";
+    readonly className: "FormattedBookInMarkdownTranspiler";
+    readonly transpileBook: (book: string_book, tools: ExecutionTools, options?: BookTranspilerOptions) => string_markdown;
+};

package/umd/src/transpilers/formatted-book-in-markdown/register.d.ts

@@ -0,0 +1,15 @@
+import type { Registration } from '../../utils/misc/$Register';
+/**
+ * Registration of transpiler
+ *
+ * Warning: This is not useful for the end user, it is just a side effect of the mechanism that handles all available LLM tools
+ *
+ * @public exported from `@promptbook/wizard`
+ * @public exported from `@promptbook/cli`
+ *
+ * TODO: !!! Which package should export this?
+ */
+export declare const _FormattedBookInMarkdownTranspilerRegistration: Registration;
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/umd/src/transpilers/openai-sdk/OpenAiSdkTranspiler.d.ts

@@ -0,0 +1,16 @@
+import type { string_book } from '../../book-2.0/agent-source/string_book';
+import type { ExecutionTools } from '../../execution/ExecutionTools';
+import type { string_script } from '../../types/typeAliases';
+import type { BookTranspilerOptions } from '../_common/BookTranspilerOptions';
+/**
+ * Transpiler to Javascript code using OpenAI SDK.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const OpenAiSdkTranspiler: {
+    readonly name: "openai-sdk";
+    readonly title: "OpenAI SDK";
+    readonly packageName: "@promptbook/core";
+    readonly className: "OpenAiSdkTranspiler";
+    readonly transpileBook: (book: string_book, tools: ExecutionTools, options?: BookTranspilerOptions) => Promise<string_script>;
+};

package/umd/src/transpilers/openai-sdk/OpenAiSdkTranspiler.test.d.ts

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

package/umd/src/transpilers/openai-sdk/playground/playground.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env ts-node
+export {};
+/**
+ * Note: [⚫] Code in this file should never be published in any package
+ */

package/umd/src/transpilers/openai-sdk/register.d.ts

@@ -0,0 +1,15 @@
+import type { Registration } from '../../utils/misc/$Register';
+/**
+ * Registration of transpiler
+ *
+ * Warning: This is not useful for the end user, it is just a side effect of the mechanism that handles all available LLM tools
+ *
+ * @public exported from `@promptbook/wizard`
+ * @public exported from `@promptbook/cli`
+ *
+ * TODO: [🧠] Which package should export this?
+ */
+export declare const _OpenAiSdkTranspilerRegistration: Registration;
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/umd/src/types/Arrayable.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Item or array of items
+ *
+ * 1) Any item except array and undefined represents array with that one item (also null)
+ * 2) Undefined represents empty array
+ * 3) Array represents itself
+ *
+ * @deprecated Use `Arrayable` from `type-fest` instead
+ * @private internal type
+ */
+export type Arrayable<TItem> = TItem | ReadonlyArray<TItem> | undefined;

package/umd/src/types/IntermediateFilesStrategy.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Defines strategies for handling intermediate files during pipeline execution.
+ * Controls how temporary or intermediate files are managed throughout processing.
+ */
+export type IntermediateFilesStrategy = 'HIDE_AND_CLEAN' | 'HIDE_AND_KEEP';
+/**
+ * TODO: [🎅] Maube add options for all kinds of cache, unite with `isCacheReloaded` and make `cacheStrategy` (which is not specific only for intermediate files)
+ */

package/umd/src/types/LlmCall.d.ts

@@ -0,0 +1,20 @@
+import type { ExecutionPromptReportJson } from '../execution/execution-report/ExecutionPromptReportJson';
+import type { string_model_name } from './typeAliases';
+/**
+ * Represents a single LLM call with its report.
+ *
+ * @see https://github.com/webgptorg/promptbook/issues/24
+ */
+export type LlmCall = {
+    /**
+     * The name of the model used for the call.
+     */
+    readonly modelName: string_model_name;
+    /**
+     * The report of the LLM execution.
+     */
+    readonly report: ExecutionPromptReportJson;
+};
+/**
+ * TODO: !!! Maybe different shape of LlmCall
+ */

package/umd/src/types/LlmToolDefinition.d.ts

@@ -0,0 +1,28 @@
+import type { string_markdown_text, string_name } from './typeAliases';
+/**
+ * Definition of a tool that can be used by the model
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type LlmToolDefinition = {
+    /**
+     * Name of the tool
+     */
+    readonly name: string_name;
+    /**
+     * Description of the tool
+     */
+    readonly description: string_markdown_text;
+    /**
+     * Parameters of the tool in JSON Schema format
+     */
+    readonly parameters: {
+        readonly type: 'object';
+        readonly properties: Record<string, {
+            type: string;
+            description?: string;
+        }>;
+        readonly required?: string[];
+        readonly additionalProperties?: boolean;
+    };
+};

package/umd/src/types/Message.d.ts

@@ -0,0 +1,49 @@
+import { Arrayable } from 'type-fest';
+import { really_any } from '../_packages/types.index';
+import { id, string_date_iso8601, string_markdown } from './typeAliases';
+/**
+ * A generic message structure for various communication channels
+ */
+export type Message<TParticipant> = {
+    /**
+     * Unique identifier of the message
+     */
+    readonly id?: id;
+    /**
+     * Date when the message was created
+     */
+    readonly createdAt?: Date | string_date_iso8601;
+    /**
+     * The communication channel of the message
+     */
+    readonly channel?: 'PROMPTBOOK_CHAT' | 'EMAIL' | 'SMS' | 'WHATSAPP' | 'TELEGRAM' | 'SIGNAL' | string | 'UNKNOWN';
+    /**
+     * Is the message send from the Promptbook or to the Promptbook
+     */
+    readonly direction?: 'INBOUND' | 'OUTBOUND' | 'INTERNAL' | 'INITIAL';
+    /**
+     * Who sent the message
+     */
+    readonly sender: TParticipant;
+    /**
+     * Who are the recipients of the message
+     */
+    readonly recipients?: Readonly<Arrayable<TParticipant>>;
+    /**
+     * The content of the message as markdown
+     *
+     * Note: We are converting all message content to markdown for consistency
+     */
+    readonly content: string_markdown;
+    /**
+     * The thread identifier the message belongs to
+     *
+     * - `null` means the message is not part of any thread
+     * - `undefined` means that we don't know if the message is part of a thread or not
+     */
+    readonly threadId?: id | null;
+    /**
+     * Arbitrary metadata associated with the message
+     */
+    readonly metadata?: Readonly<Record<string, really_any>>;
+};