@promptbook/wizard 0.95.0

package/esm/typings/src/scrapers/pdf/PdfScraper.d.ts

@@ -0,0 +1,41 @@
+import type { KnowledgePiecePreparedJson } from '../../pipeline/PipelineJson/KnowledgePieceJson';
+import type { Scraper } from '../_common/Scraper';
+import type { ScraperSourceHandler } from '../_common/Scraper';
+import type { ExecutionTools } from '../../execution/ExecutionTools';
+import type { PrepareAndScrapeOptions } from '../../prepare/PrepareAndScrapeOptions';
+import type { Converter } from '../_common/Converter';
+import type { ScraperAndConverterMetadata } from '../_common/register/ScraperAndConverterMetadata';
+import type { ScraperIntermediateSource } from '../_common/ScraperIntermediateSource';
+/**
+ * Scraper for .pdf files
+ *
+ * @see `documentationUrl` for more details
+ * @public exported from `@promptbook/pdf`
+ */
+export declare class PdfScraper implements Converter, Scraper {
+    private readonly tools;
+    private readonly options;
+    /**
+     * Metadata of the scraper which includes title, mime types, etc.
+     */
+    get metadata(): ScraperAndConverterMetadata;
+    /**
+     * Markdown scraper is used internally
+     */
+    private readonly markdownScraper;
+    constructor(tools: Pick<ExecutionTools, 'llm'>, options: PrepareAndScrapeOptions);
+    /**
+     * Converts the `.pdf` file to `.md` file and returns intermediate source
+     */
+    $convert(source: ScraperSourceHandler): Promise<ScraperIntermediateSource>;
+    /**
+     * Scrapes the `.pdf` file and returns the knowledge pieces or `null` if it can't scrape it
+     */
+    scrape(source: ScraperSourceHandler): Promise<ReadonlyArray<Omit<KnowledgePiecePreparedJson, 'sources' | 'preparationIds'>> | null>;
+}
+/**
+ * TODO: [👣] Converted pdf documents can act as cached items - there is no need to run conversion each time
+ * TODO: [🪂] Do it in parallel 11:11
+ * Note: No need to aggregate usage here, it is done by intercepting the llmTools
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

package/esm/typings/src/scrapers/pdf/createPdfScraper.d.ts

@@ -0,0 +1,21 @@
+import type { ExecutionTools } from '../../execution/ExecutionTools';
+import type { PrepareAndScrapeOptions } from '../../prepare/PrepareAndScrapeOptions';
+import { PdfScraper } from './PdfScraper';
+/**
+ * Factory function to create an instance of PdfScraper.
+ * It bundles the scraper class with its metadata.
+ *
+ * @public exported from `@promptbook/pdf`
+ */
+export declare const createPdfScraper: ((tools: Pick<ExecutionTools, 'llm'>, options: PrepareAndScrapeOptions) => PdfScraper) & import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
+    title: string;
+    packageName: string;
+    className: string;
+    mimeTypes: string[];
+    documentationUrl: "https://github.com/webgptorg/promptbook/discussions/@@";
+    isAvailableInBrowser: false;
+    requiredExecutables: never[];
+}>;
+/**
+ * TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
+ */

package/esm/typings/src/scrapers/pdf/playground/pdf-scraper-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/esm/typings/src/scrapers/pdf/register-constructor.d.ts

@@ -0,0 +1,15 @@
+import type { Registration } from '../../utils/$Register';
+/**
+ * Registration of known scraper
+ *
+ * Warning: This is not useful for the end user, it is just a side effect of the mechanism that handles all available known scrapers
+ *
+ * @public exported from `@promptbook/pdf`
+ * @public exported from `@promptbook/wizard`
+ * @public exported from `@promptbook/cli`
+ */
+export declare const _PdfScraperRegistration: Registration;
+/**
+ * TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/scrapers/pdf/register-metadata.d.ts

@@ -0,0 +1,28 @@
+import type { Registration } from '../../utils/$Register';
+/**
+ * Metadata of the scraper
+ *
+ * @private within the scraper directory
+ */
+export declare const pdfScraperMetadata: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
+    title: string;
+    packageName: string;
+    className: string;
+    mimeTypes: string[];
+    documentationUrl: "https://github.com/webgptorg/promptbook/discussions/@@";
+    isAvailableInBrowser: false;
+    requiredExecutables: never[];
+}>;
+/**
+ * Registration of known scraper metadata
+ *
+ * Warning: This is not useful for the end user, it is just a side effect of the mechanism that handles all available known scrapers
+ *
+ * @public exported from `@promptbook/core`
+ * @public exported from `@promptbook/wizard`
+ * @public exported from `@promptbook/cli`
+ */
+export declare const _PdfScraperMetadataRegistration: Registration;
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/scrapers/website/WebsiteScraper.d.ts

@@ -0,0 +1,50 @@
+import type { KnowledgePiecePreparedJson } from '../../pipeline/PipelineJson/KnowledgePieceJson';
+import type { string_markdown } from '../../types/typeAliases';
+import type { Converter } from '../_common/Converter';
+import type { Scraper } from '../_common/Scraper';
+import type { ScraperSourceHandler } from '../_common/Scraper';
+import type { ExecutionTools } from '../../execution/ExecutionTools';
+import type { PrepareAndScrapeOptions } from '../../prepare/PrepareAndScrapeOptions';
+import type { ScraperAndConverterMetadata } from '../_common/register/ScraperAndConverterMetadata';
+import type { ScraperIntermediateSource } from '../_common/ScraperIntermediateSource';
+/**
+ * Scraper for websites
+ *
+ * @see `documentationUrl` for more details
+ * @public exported from `@promptbook/website-crawler`
+ */
+export declare class WebsiteScraper implements Converter, Scraper {
+    private readonly tools;
+    private readonly options;
+    /**
+     * Metadata of the scraper which includes title, mime types, etc.
+     */
+    get metadata(): ScraperAndConverterMetadata;
+    /**
+     * Markdown scraper is used internally
+     */
+    private readonly markdownScraper;
+    /**
+     * Showdown converter is used internally
+     */
+    private readonly showdownConverter;
+    constructor(tools: Pick<ExecutionTools, 'fs' | 'llm'>, options: PrepareAndScrapeOptions);
+    /**
+     * Convert the website  to `.md` file and returns intermediate source
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it leaves files on the disk and you are responsible for cleaning them by calling `destroy` method of returned object
+     */
+    $convert(source: ScraperSourceHandler): Promise<ScraperIntermediateSource & {
+        markdown: string_markdown;
+    }>;
+    /**
+     * Scrapes the website and returns the knowledge pieces or `null` if it can't scrape it
+     */
+    scrape(source: ScraperSourceHandler): Promise<ReadonlyArray<Omit<KnowledgePiecePreparedJson, 'sources' | 'preparationIds'>> | null>;
+}
+/**
+ * TODO: [👣] Scraped website in .md can act as cache item - there is no need to run conversion each time
+ * TODO: [🪂] Do it in parallel 11:11
+ * Note: No need to aggregate usage here, it is done by intercepting the llmTools
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

package/esm/typings/src/scrapers/website/createWebsiteScraper.d.ts

@@ -0,0 +1,21 @@
+import type { ExecutionTools } from '../../execution/ExecutionTools';
+import type { PrepareAndScrapeOptions } from '../../prepare/PrepareAndScrapeOptions';
+import { WebsiteScraper } from './WebsiteScraper';
+/**
+ * Factory function to create an instance of WebsiteScraper.
+ * It bundles the scraper class with its metadata.
+ *
+ * @public exported from `@promptbook/website-crawler`
+ */
+export declare const createWebsiteScraper: ((tools: Pick<ExecutionTools, 'llm'>, options: PrepareAndScrapeOptions) => WebsiteScraper) & import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
+    title: string;
+    packageName: string;
+    className: string;
+    mimeTypes: string[];
+    documentationUrl: "https://github.com/webgptorg/promptbook/discussions/@@";
+    isAvailableInBrowser: false;
+    requiredExecutables: never[];
+}>;
+/**
+ * TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
+ */

package/esm/typings/src/scrapers/website/playground/website-scraper-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/esm/typings/src/scrapers/website/register-constructor.d.ts

@@ -0,0 +1,15 @@
+import type { Registration } from '../../utils/$Register';
+/**
+ * Registration of known scraper
+ *
+ * Warning: This is not useful for the end user, it is just a side effect of the mechanism that handles all available known scrapers
+ *
+ * @public exported from `@promptbook/website-crawler`
+ * @public exported from `@promptbook/wizard`
+ * @public exported from `@promptbook/cli`
+ */
+export declare const _WebsiteScraperRegistration: Registration;
+/**
+ * TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/scrapers/website/register-metadata.d.ts

@@ -0,0 +1,28 @@
+import type { Registration } from '../../utils/$Register';
+/**
+ * Metadata of the scraper
+ *
+ * @private within the scraper directory
+ */
+export declare const websiteScraperMetadata: import("type-fest/source/readonly-deep").ReadonlyObjectDeep<{
+    title: string;
+    packageName: string;
+    className: string;
+    mimeTypes: string[];
+    documentationUrl: "https://github.com/webgptorg/promptbook/discussions/@@";
+    isAvailableInBrowser: false;
+    requiredExecutables: never[];
+}>;
+/**
+ * Registration of known scraper metadata
+ *
+ * Warning: This is not useful for the end user, it is just a side effect of the mechanism that handles all available known scrapers
+ *
+ * @public exported from `@promptbook/core`
+ * @public exported from `@promptbook/wizard`
+ * @public exported from `@promptbook/cli`
+ */
+export declare const _WebsiteScraperMetadataRegistration: Registration;
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/scrapers/website/utils/createShowdownConverter.d.ts

@@ -0,0 +1,7 @@
+import { Converter as ShowdownConverter } from 'showdown';
+/**
+ * Create a new showdown converter instance
+ *
+ * @private utility of `WebsiteScraper`
+ */
+export declare function createShowdownConverter(): ShowdownConverter;

package/esm/typings/src/scrapers/website/utils/createShowdownConverter.test.d.ts

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

package/esm/typings/src/scripting/_test/custom-function-async.test.ts.test.d.ts

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

package/esm/typings/src/scripting/_test/custom-function-missing.test.d.ts

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

package/esm/typings/src/scripting/_test/custom-function-with-dependencies.test.d.ts

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

package/esm/typings/src/scripting/_test/custom-function.test.d.ts

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

package/esm/typings/src/scripting/_test/postprocessing.test.d.ts

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

package/esm/typings/src/scripting/_test/script-execution-errors.test.d.ts

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

package/esm/typings/src/scripting/_test/script-execution-tools.test.d.ts

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

package/esm/typings/src/scripting/javascript/JavascriptEvalExecutionTools.d.ts

@@ -0,0 +1,22 @@
+import type { ScriptExecutionTools, ScriptExecutionToolsExecuteOptions } from '../../execution/ScriptExecutionTools';
+import type { JavascriptExecutionToolsOptions } from './JavascriptExecutionToolsOptions';
+/**
+ * ScriptExecutionTools for JavaScript implemented via eval
+ *
+ * Warning: It is used for testing and mocking
+ *          **NOT intended to use in the production** due to its unsafe nature, use `JavascriptExecutionTools` instead.
+ *
+ * @public exported from `@promptbook/javascript`
+ */
+export declare class JavascriptEvalExecutionTools implements ScriptExecutionTools {
+    protected readonly options: JavascriptExecutionToolsOptions;
+    constructor(options?: JavascriptExecutionToolsOptions);
+    /**
+     * Executes a JavaScript
+     */
+    execute(options: ScriptExecutionToolsExecuteOptions): Promise<string>;
+}
+/**
+ * TODO: Put predefined functions (like removeQuotes, spaceTrim, etc.) into annotation OR pass into constructor
+ * TODO: [🧠][💙] Distinct between options passed into ExecutionTools and to ExecutionTools.execute
+ */

package/esm/typings/src/scripting/javascript/JavascriptEvalExecutionTools.test.d.ts

@@ -0,0 +1,4 @@
+export {};
+/**
+ * TODO: Make shared test between JavascriptEvalExecutionTools and JavascriptExecutionTools to test the same functionality when implemented via vm2
+ */

package/esm/typings/src/scripting/javascript/JavascriptExecutionTools.d.ts

@@ -0,0 +1,8 @@
+import { JavascriptEvalExecutionTools } from './JavascriptEvalExecutionTools';
+/**
+ * Placeholder for better implementation of JavascriptExecutionTools - some proper sandboxing
+ *
+ * @alias JavascriptExecutionTools
+ * @public exported from `@promptbook/javascript`
+ */
+export declare const JavascriptExecutionTools: typeof JavascriptEvalExecutionTools;

package/esm/typings/src/scripting/javascript/JavascriptExecutionToolsOptions.d.ts

@@ -0,0 +1,26 @@
+import type { Promisable } from 'type-fest';
+import type { CommonToolsOptions } from '../../execution/CommonToolsOptions';
+import type { string_postprocessing_function_name } from '../../types/typeAliases';
+/**
+ * Options for `JavascriptExecutionTools`
+ */
+export type JavascriptExecutionToolsOptions = CommonToolsOptions & {
+    /**
+     * Functions to be executed in the JavaScript evaluation.
+     *
+     * This can be used in two ways:
+     * 1. To provide custom postprocessing functions. For this case function must receive one string and return a (promise of) string.
+     * 2. As environment for the ECECUTE SCRIPT, For this case function can be any function. [0]
+     *
+     * Note: There are also some built-in functions available:
+     *      @see ./JavascriptEvalExecutionTools.ts
+     */
+    functions?: Record<string_postprocessing_function_name, PostprocessingFunction>;
+};
+/**
+ * Function that can be used to postprocess the output of the LLM
+ */
+export type PostprocessingFunction = ((value: string) => Promisable<string>) | Function;
+/**
+ * TODO: [🧠][💙] Distinct between options passed into ExecutionTools and to ExecutionTools.execute
+ */

package/esm/typings/src/scripting/javascript/postprocessing-functions.d.ts

@@ -0,0 +1,56 @@
+import spaceTrim from 'spacetrim';
+import { extractBlock } from '../../postprocessing/utils/extractBlock';
+import { prettifyMarkdown } from '../../utils/markdown/prettifyMarkdown';
+import { capitalize } from '../../utils/normalization/capitalize';
+import { decapitalize } from '../../utils/normalization/decapitalize';
+import { nameToUriPart } from '../../utils/normalization/nameToUriPart';
+import { nameToUriParts } from '../../utils/normalization/nameToUriParts';
+import { normalizeToKebabCase } from '../../utils/normalization/normalize-to-kebab-case';
+import { normalizeTo_PascalCase } from '../../utils/normalization/normalizeTo_PascalCase';
+import { normalizeTo_SCREAMING_CASE } from '../../utils/normalization/normalizeTo_SCREAMING_CASE';
+import { normalizeTo_camelCase } from '../../utils/normalization/normalizeTo_camelCase';
+import { normalizeTo_snake_case } from '../../utils/normalization/normalizeTo_snake_case';
+import { normalizeWhitespaces } from '../../utils/normalization/normalizeWhitespaces';
+import { removeDiacritics } from '../../utils/normalization/removeDiacritics';
+import { removeEmojis } from '../../utils/removeEmojis';
+import { removeQuotes } from '../../utils/removeQuotes';
+import { trimCodeBlock } from '../../utils/trimCodeBlock';
+import { trimEndOfCodeBlock } from '../../utils/trimEndOfCodeBlock';
+import { unwrapResult } from '../../utils/unwrapResult';
+/**
+ * Collection of utility functions that can be used for post-processing model outputs.
+ * These functions help transform, extract, or format the raw model responses.
+ *
+ * These utilities range from simple string manipulations to markdown processing
+ * and formatting functions for specific types of output.
+ *
+ * @public exported from `@promptbook/javascript`
+ */
+export declare const POSTPROCESSING_FUNCTIONS: {
+    spaceTrim: typeof spaceTrim;
+    removeQuotes: typeof removeQuotes;
+    unwrapResult: typeof unwrapResult;
+    trimEndOfCodeBlock: typeof trimEndOfCodeBlock;
+    trimCodeBlock: typeof trimCodeBlock;
+    trim: (str: string) => string;
+    reverse: (str: string) => string;
+    removeEmojis: typeof removeEmojis;
+    prettifyMarkdown: typeof prettifyMarkdown;
+    capitalize: typeof capitalize;
+    decapitalize: typeof decapitalize;
+    nameToUriPart: typeof nameToUriPart;
+    nameToUriParts: typeof nameToUriParts;
+    removeDiacritics: typeof removeDiacritics;
+    normalizeWhitespaces: typeof normalizeWhitespaces;
+    normalizeToKebabCase: typeof normalizeToKebabCase;
+    normalizeTo_camelCase: typeof normalizeTo_camelCase;
+    normalizeTo_snake_case: typeof normalizeTo_snake_case;
+    normalizeTo_PascalCase: typeof normalizeTo_PascalCase;
+    parseKeywords: (input: string) => string;
+    normalizeTo_SCREAMING_CASE: typeof normalizeTo_SCREAMING_CASE;
+    extractBlock: typeof extractBlock;
+};
+/**
+ * TODO: DRY [🍯], [🧠] Where should be POSTPROCESSING_FUNCTIONS located and how it should be named
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/scripting/javascript/utils/extractVariablesFromJavascript.d.ts

@@ -0,0 +1,14 @@
+import type { string_javascript } from '../../../types/typeAliases';
+import type { string_javascript_name } from '../../../types/typeAliases';
+/**
+ * Parses the given script and returns the list of all used variables that are not defined in the script
+ *
+ * @param script from which to extract the variables
+ * @returns the list of variable names
+ * @throws {ParseError} if the script is invalid
+ * @public exported from `@promptbook/javascript`
+ */
+export declare function extractVariablesFromJavascript(script: string_javascript): Set<string_javascript_name>;
+/**
+ * TODO: [🔣] Support for multiple languages - python, java,...
+ */

package/esm/typings/src/scripting/javascript/utils/extractVariablesFromJavascript.test.d.ts

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

package/esm/typings/src/scripting/javascript/utils/extractVariablesFromScript.test.d.ts

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

package/esm/typings/src/scripting/javascript/utils/preserve.d.ts

@@ -0,0 +1,14 @@
+import type { really_any } from '../../../utils/organization/really_any';
+/**
+ * Does nothing, but preserves the function in the bundle
+ * Compiler is tricked into thinking the function is used
+ *
+ * @param value any function to preserve
+ * @returns nothing
+ * @private internal function of `JavascriptExecutionTools` and `JavascriptEvalExecutionTools`
+ */
+export declare function preserve(func: (...params: ReadonlyArray<really_any>) => unknown): void;
+/**
+ * TODO: Probably remove in favour of `keepImported`
+ * TODO: [1] This maybe does memory leak
+ */

package/esm/typings/src/scripting/python/PythonExecutionTools.d.ts

@@ -0,0 +1,18 @@
+import type { CommonToolsOptions } from '../../execution/CommonToolsOptions';
+import type { ScriptExecutionTools } from '../../execution/ScriptExecutionTools';
+import type { ScriptExecutionToolsExecuteOptions } from '../../execution/ScriptExecutionTools';
+/**
+ * ScriptExecutionTools for Python
+ *
+ * Warning: This is not implemented yet
+ *
+ * @private still in development
+ */
+export declare class PythonExecutionTools implements ScriptExecutionTools {
+    protected readonly options: CommonToolsOptions;
+    constructor(options?: CommonToolsOptions);
+    /**
+     * Executes a Python
+     */
+    execute(options: ScriptExecutionToolsExecuteOptions): Promise<string>;
+}

package/esm/typings/src/scripting/typescript/TypescriptExecutionTools.d.ts

@@ -0,0 +1,18 @@
+import type { CommonToolsOptions } from '../../execution/CommonToolsOptions';
+import type { ScriptExecutionTools } from '../../execution/ScriptExecutionTools';
+import type { ScriptExecutionToolsExecuteOptions } from '../../execution/ScriptExecutionTools';
+/**
+ * ScriptExecutionTools for TypeScript
+ *
+ * Warning: This is not implemented yet
+ *
+ * @private still in development
+ */
+export declare class TypescriptExecutionTools implements ScriptExecutionTools {
+    protected readonly options: CommonToolsOptions;
+    constructor(options?: CommonToolsOptions);
+    /**
+     * Executes a TypeScript
+     */
+    execute(options: ScriptExecutionToolsExecuteOptions): Promise<string>;
+}

package/esm/typings/src/storage/_common/PromptbookStorage.d.ts

@@ -0,0 +1,24 @@
+import type { Promisable } from 'type-fest';
+/**
+ * Storage of objects with asynchronous API
+ *
+ * Note: Naming `PromptbookStorage` not `Storage` to avoid name collision with global `Storage` interface.
+ * Note: This is similar to Web Storage API interface but everything is asynchronous and can store JSON objects.
+ */
+export type PromptbookStorage<TItem> = {
+    /**
+     * 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): Promisable<void>;
+};
+/**
+ * TODO: [💺] Constrain `TItem` to [🚉] JSON-serializable objects only in type level
+ */

package/esm/typings/src/storage/_common/PromptbookStorage.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/esm/typings/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/esm/typings/src/storage/env-storage/$EnvStorage.d.ts

@@ -0,0 +1,40 @@
+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<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;
+}
+/**
+ * TODO: Write file more securely - ensure that there can be no accidental overwriting of existing variables and other content
+ */

package/esm/typings/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/esm/typings/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;
+};