@promptbook/javascript 0.111.0-4 → 0.111.0-7

package/umd/src/import-plugins/$fileImportPlugins.d.ts

@@ -0,0 +1,7 @@
+import type { FileImportPlugin } from './FileImportPlugin';
+/**
+ * All available file import plugins
+ *
+ * @private [🥝] Maybe export the import plugins through some package
+ */
+export declare const $fileImportPlugins: ReadonlyArray<FileImportPlugin>;

package/umd/src/import-plugins/AgentFileImportPlugin.d.ts

@@ -0,0 +1,7 @@
+import type { FileImportPlugin } from './FileImportPlugin';
+/**
+ * Plugin for importing agent books *(`.book` files)*
+ *
+ * @private [🥝] Maybe export the import plugins through some package
+ */
+export declare const AgentFileImportPlugin: FileImportPlugin;

package/umd/src/import-plugins/FileImportPlugin.d.ts

@@ -0,0 +1,24 @@
+import type { string_mime_type } from '../types/typeAliases';
+/**
+ * Type for file import plugins
+ *
+ * Each plugin handles a specific set of MIME types or file extensions.
+ */
+export type FileImportPlugin = {
+    /**
+     * Unique name of the plugin
+     */
+    readonly name: string;
+    /**
+     * Checks if the plugin can handle the given MIME type or file extension
+     */
+    canImport(mimeType: string_mime_type): boolean;
+    /**
+     * Processes the file content and returns the string to be placed in the agent book
+     *
+     * @param content - The raw content of the file
+     * @param mimeType - The MIME type of the file
+     * @returns The processed content (e.g. wrapped in code block)
+     */
+    import(content: string, mimeType: string_mime_type): string | Promise<string>;
+};

package/umd/src/import-plugins/JsonFileImportPlugin.d.ts

@@ -0,0 +1,7 @@
+import type { FileImportPlugin } from './FileImportPlugin';
+/**
+ * Plugin for importing JSON files
+ *
+ * @private [🥝] Maybe export the import plugins through some package
+ */
+export declare const JsonFileImportPlugin: FileImportPlugin;

package/umd/src/import-plugins/TextFileImportPlugin.d.ts

@@ -0,0 +1,7 @@
+import type { FileImportPlugin } from './FileImportPlugin';
+/**
+ * Plugin for importing generic text files
+ *
+ * @private [🥝] Maybe export the import plugins through some package
+ */
+export declare const TextFileImportPlugin: FileImportPlugin;

package/umd/src/llm-providers/_common/filterModels.d.ts

@@ -0,0 +1,12 @@
+import type { AvailableModel } from '../../execution/AvailableModel';
+import type { LlmExecutionTools } from '../../execution/LlmExecutionTools';
+/**
+ * Creates a wrapper around LlmExecutionTools that only exposes models matching the filter function
+ *
+ * @param llmTools The original LLM execution tools to wrap
+ * @param predicate Function that determines whether a model should be included
+ * @returns A new LlmExecutionTools instance with filtered models
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function filterModels<TLlmTools extends LlmExecutionTools>(llmTools: TLlmTools, predicate: (model: AvailableModel) => boolean): TLlmTools;

package/umd/src/llm-providers/_common/register/$llmToolsMetadataRegister.d.ts

@@ -0,0 +1,13 @@
+import { $Register } from '../../../utils/misc/$Register';
+import type { LlmToolsMetadata } from './LlmToolsMetadata';
+/**
+ * Register for LLM tools metadata.
+ *
+ * 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.
+ * @public exported from `@promptbook/core`
+ */
+export declare const $llmToolsMetadataRegister: $Register<LlmToolsMetadata>;
+/**
+ * TODO: [®] DRY Register logic
+ */

package/umd/src/llm-providers/_common/register/$llmToolsRegister.d.ts

@@ -0,0 +1,13 @@
+import type { LlmExecutionToolsConstructor } from '../../../execution/LlmExecutionToolsConstructor';
+import { $Register } from '../../../utils/misc/$Register';
+/**
+ * Register for LLM tools.
+ *
+ * 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.
+ * @public exported from `@promptbook/core`
+ */
+export declare const $llmToolsRegister: $Register<LlmExecutionToolsConstructor>;
+/**
+ * TODO: [®] DRY Register logic
+ */

package/umd/src/llm-providers/_common/register/$provideEnvFilename.d.ts

@@ -0,0 +1,12 @@
+import type { string_filename } from '../../../types/typeAliases';
+/**
+ * Provides the path to the `.env` file
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file
+ *
+ * @private within the repository - for CLI utils
+ */
+export declare function $provideEnvFilename(): Promise<string_filename | null>;
+/**
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

package/umd/src/llm-providers/_common/register/$provideLlmToolsConfigurationFromEnv.d.ts

@@ -0,0 +1,19 @@
+import type { LlmToolsConfiguration } from './LlmToolsConfiguration';
+/**
+ * Provides LLM tools configuration by reading environment variables.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file
+ *
+ * It looks for environment variables:
+ * - `process.env.OPENAI_API_KEY`
+ * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
+ * - ...
+ *
+ * @see Environment variables documentation or .env file for required variables.
+ * @returns A promise that resolves to the LLM tools configuration, or null if configuration is incomplete or missing.
+ * @public exported from `@promptbook/node`
+ */
+export declare function $provideLlmToolsConfigurationFromEnv(): Promise<LlmToolsConfiguration>;
+/**
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

package/umd/src/llm-providers/_common/register/$provideLlmToolsForTestingAndScriptsAndPlayground.d.ts

@@ -0,0 +1,27 @@
+import '../../../_packages/cli.index';
+import type { LlmExecutionToolsWithTotalUsage } from '../utils/count-total-usage/LlmExecutionToolsWithTotalUsage';
+import type { CreateLlmToolsFromConfigurationOptions } from './createLlmToolsFromConfiguration';
+type GetLlmToolsForTestingAndScriptsAndPlaygroundOptions = CreateLlmToolsFromConfigurationOptions & {
+    /**
+     * Flag indicating whether the cache should be reloaded or reused
+     * When set to true, the existing cache will not be used but thinks will be still saved to the cache
+     *
+     * @default false
+     */
+    isCacheReloaded?: boolean;
+};
+/**
+ * Returns LLM tools for testing purposes
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file
+ *
+ * @private within the repository - JUST FOR TESTS, SCRIPTS AND PLAYGROUND
+ */
+export declare function $provideLlmToolsForTestingAndScriptsAndPlayground(options?: GetLlmToolsForTestingAndScriptsAndPlaygroundOptions): Promise<LlmExecutionToolsWithTotalUsage>;
+export {};
+/**
+ * Note: [⚪] This should never be in any released package
+ * TODO: [👷‍♂️] Write a comprehensive manual about the construction of LLM tools
+ * TODO: This should be maybe not under `_common` but under `utils-internal` / `utils/internal`
+ * TODO: [®] DRY Register logi
+ */

package/umd/src/llm-providers/_common/register/$provideLlmToolsForWizardOrCli.d.ts

@@ -0,0 +1,58 @@
+import { Promisable } from 'type-fest';
+import type { Identification } from '../../../remote-server/socket-types/_subtypes/Identification';
+import type { string_app_id, string_url } from '../../../types/typeAliases';
+import type { chococake } from '../../../utils/organization/really_any';
+import type { CacheLlmToolsOptions } from '../utils/cache/CacheLlmToolsOptions';
+import type { LlmExecutionToolsWithTotalUsage } from '../utils/count-total-usage/LlmExecutionToolsWithTotalUsage';
+type ProvideLlmToolsForWizardOrCliOptions = {
+    /**
+     * If true, user will be always prompted for login
+     *
+     * Note: This is used in `ptbk login` command
+     */
+    isLoginloaded?: true;
+} & Pick<CacheLlmToolsOptions, 'isCacheReloaded'> & ({
+    /**
+     * Use local keys and execute LLMs directly
+     */
+    readonly strategy: 'BRING_YOUR_OWN_KEYS';
+} | {
+    /**
+     * Do not use local keys but login to Promptbook server and execute LLMs there
+     */
+    readonly strategy: 'REMOTE_SERVER';
+    /**
+     * URL of the remote server
+     *
+     * @default `DEFAULT_REMOTE_SERVER_URL`
+     */
+    readonly remoteServerUrl?: string_url;
+    /**
+     * Identifier of the application which will be passed to the remote server identification
+     *
+     * Note: This can be some id or some semantic name like "email-agent"
+     */
+    readonly appId: string_app_id;
+    /**
+     *
+     *
+     * Note: When login prompt fails, `process.exit(1)` is called
+     */
+    loginPrompt(): Promisable<Identification<chococake>>;
+});
+/**
+ * Returns LLM tools for CLI
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file and also writes this .env file
+ *
+ * @private within the repository - for CLI utils
+ */
+export declare function $provideLlmToolsForWizardOrCli(options?: ProvideLlmToolsForWizardOrCliOptions): Promise<LlmExecutionToolsWithTotalUsage>;
+export {};
+/**
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ * TODO: [👷‍♂️] Write a comprehensive manual about the construction of LLM tools
+ * TODO: [🥃] Allow `ptbk make` without llm tools
+ * TODO: This should be maybe not under `_common` but under `utils-internal` / `utils/internal`
+ * TODO: [®] DRY Register logic
+ */

package/umd/src/llm-providers/_common/register/$provideLlmToolsFromEnv.d.ts

@@ -0,0 +1,41 @@
+import { MultipleLlmExecutionTools } from '../../_multiple/MultipleLlmExecutionTools';
+import type { CreateLlmToolsFromConfigurationOptions } from './createLlmToolsFromConfiguration';
+/**
+ * Automatically configures LLM tools from environment variables in Node.js
+ *
+ * This utility function detects available LLM providers based on environment variables
+ * and creates properly configured LLM execution tools for each detected provider.
+ *
+ * Note: This function is not cached, every call creates new instance of `MultipleLlmExecutionTools`
+ *
+ * Supports environment variables from .env files when dotenv is configured
+ * Note: `$` is used to indicate that this function is not a pure function - it uses filesystem to access `.env` file
+ *
+ * It looks for environment variables:
+ * - `process.env.OPENAI_API_KEY`
+ * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
+ * - ...
+ *
+ * @param options Configuration options for the LLM tools
+ * @returns A unified interface containing all detected and configured LLM tools
+ * @public exported from `@promptbook/node`
+ */
+export declare function $provideLlmToolsFromEnv(options?: CreateLlmToolsFromConfigurationOptions): Promise<MultipleLlmExecutionTools>;
+/**
+ * TODO: The architecture for LLM tools configuration consists of three key functions:
+ * 1. `$provideLlmToolsFromEnv` - High-level function that detects available providers from env vars and returns ready-to-use LLM tools
+ * 2. `$provideLlmToolsConfigurationFromEnv` - Middle layer that extracts configuration objects from environment variables
+ * 3. `createLlmToolsFromConfiguration` - Low-level function that instantiates LLM tools from explicit configuration
+ *
+ * This layered approach allows flexibility in how tools are configured:
+ * - Use $provideLlmToolsFromEnv for automatic detection and setup in Node.js environments
+ * - Use $provideLlmToolsConfigurationFromEnv to extract config objects for modification before instantiation
+ * - Use createLlmToolsFromConfiguration for explicit control over tool configurations
+ *
+ * TODO: [🧠][🍛] Which name is better `$provideLlmToolsFromEnv` or `$provideLlmToolsFromEnvironment`?
+ * TODO: [🧠] Is there some meaningfull way how to test this util
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ * TODO: [🥃] Allow `ptbk make` without llm tools
+ * TODO: This should be maybe not under `_common` but under `utils`
+ * TODO: [®] DRY Register logic
+ */

package/umd/src/llm-providers/_common/register/$registeredLlmToolsMessage.d.ts

@@ -0,0 +1,22 @@
+import type { string_filename, string_markdown } from '../../../types/typeAliases';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Pass the `.env` file which was used to configure LLM tools
+ *
+ * Note: `$` is used to indicate that this variable is making side effect
+ *
+ * @private internal log of `$provideLlmToolsConfigurationFromEnv` and `$registeredLlmToolsMessage`
+ */
+export declare function $setUsedEnvFilename(filepath: string_filename): $side_effect;
+/**
+ * Creates a message with all registered LLM tools
+ *
+ * Note: This function is used to create a (error) message when there is no constructor for some LLM provider
+ *
+ * @private internal function of `createLlmToolsFromConfiguration` and `$provideLlmToolsFromEnv`
+ */
+export declare function $registeredLlmToolsMessage(): string_markdown;
+/**
+ * TODO: [®] DRY Register logic
+ * TODO: [🧠][⚛] Maybe pass env as argument
+ */

package/umd/src/llm-providers/_common/register/LlmToolsConfiguration.d.ts

@@ -0,0 +1,30 @@
+import type { string_title } from '../../../types/typeAliases';
+import type { Registered } from '../../../utils/misc/$Register';
+import type { LlmToolsOptions } from './LlmToolsOptions';
+/**
+ * Configuration definition for LLM execution tools, containing provider-specific settings
+ * that can be passed during runtime to instantiate and configure LLM tools properly.
+ *
+ * The Promptbook LLM tools architecture involves several related types:
+ * - `LlmToolsMetadata`: Contains static metadata about the tool, such as name, version, and capabilities
+ * - `LlmToolsConfiguration`: Runtime configuration from environment variables or settings
+ * - `LlmToolsOptions`: Provider-specific options for instantiating tools
+ * - `Registered`: The record of a registered tool in the global registry
+ */
+export type LlmToolsConfiguration = ReadonlyArray<Registered & {
+    /**
+     * Human-readable name for this specific provider configuration
+     * Used in UI components and logs for identifying this particular configuration
+     */
+    readonly title: string_title;
+    /**
+     * Provider-specific configuration options used for instantiating and configuring LLM tools
+     * Contains values like API keys, model preferences, endpoint URLs, and other settings
+     */
+    readonly options: LlmToolsOptions;
+}>;
+/**
+ * TODO: [🧠][🌰] `title` is redundant BUT maybe allow each provider pass it's own title for tracking purposes
+ * TODO: Maybe instead of `LlmToolsConfiguration[number]` make `LlmToolsConfigurationItem`
+ * TODO: [®] DRY Register logic
+ */

package/umd/src/llm-providers/_common/register/LlmToolsMetadata.d.ts

@@ -0,0 +1,57 @@
+import { MODEL_ORDERS, MODEL_TRUST_LEVELS } from '../../../constants';
+import type { string_name, string_title } from '../../../types/typeAliases';
+import type { Registered } from '../../../utils/misc/$Register';
+import type { string_SCREAMING_CASE } from '../../../utils/normalization/normalizeTo_SCREAMING_CASE';
+import type { LlmToolsConfiguration } from './LlmToolsConfiguration';
+/**
+ * Metadata definition for LLM execution tools that provides information about a provider's capabilities,
+ * configuration options, and relationships within the registry system.
+ *
+ * The Promptbook LLM tools architecture involves several related types:
+ * - `LlmToolsMetadata`: Contains static metadata about the tool, such as name, version, and capabilities
+ * - `LlmToolsConfiguration`: Runtime configuration from environment variables or settings
+ * - `LlmToolsOptions`: Provider-specific options for instantiating tools
+ * - `Registered`: The record of a registered tool in the global registry
+ */
+export type LlmToolsMetadata = Registered & {
+    /**
+     * Human-readable display name for the LLM provider
+     * Used in UI components and documentation references
+     */
+    readonly title: string_title;
+    /**
+     * How is the model is trusted?
+     */
+    readonly trustLevel: keyof typeof MODEL_TRUST_LEVELS;
+    /**
+     * How is the model provider important and should be sorted in the list of available providers?
+     */
+    readonly order: (typeof MODEL_ORDERS)[keyof typeof MODEL_ORDERS] | number;
+    /**
+     * List of environment variables that can be used to configure the provider
+     *
+     * If `[]`, empty array, it means that the provider is available automatically without any configuration
+     * If `null`, it means that the provider can not be configured via environment variables
+     */
+    readonly envVariables: ReadonlyArray<string_name & string_SCREAMING_CASE> | null;
+    /**
+     * Provides a default configuration template for this LLM provider
+     * Used to generate example configurations or as fallback when no specific configuration is provided
+     * @returns A standardized configuration object for this LLM provider
+     */
+    getBoilerplateConfiguration(): LlmToolsConfiguration[number];
+    /**
+     * Creates a provider-specific configuration object from environment variables
+     * Used to automatically configure LLM tools based on available environment settings
+     *
+     * @param env Dictionary of environment variables (key-value pairs)
+     * @returns Configuration object for this LLM provider if required variables are present, or null if configuration is not possible
+     */
+    createConfigurationFromEnv(env: Record<string_name, string>): LlmToolsConfiguration[number] | null;
+};
+/**
+ * TODO: [🕛] Extend this
+ * TODO: Add configuration schema and maybe some documentation link
+ * TODO: Maybe constrain LlmToolsConfiguration[number] by generic to ensure that `createConfigurationFromEnv` and `getBoilerplateConfiguration` always create same `packageName` and `className`
+ * TODO: [®] DRY Register logic
+ */

package/umd/src/llm-providers/_common/register/LlmToolsOptions.d.ts

@@ -0,0 +1,17 @@
+import type { TODO_object } from '../../../utils/organization/TODO_object';
+/**
+ * Options for configuring LLM (Large Language Model) tools.
+ *
+ * This type is used to pass provider-specific options to LLM execution tools.
+ *
+ *
+ * The Promptbook LLM tools architecture involves several related types:
+ * - `LlmToolsMetadata`: Contains static metadata about the tool, such as name, version, and capabilities
+ * - `LlmToolsConfiguration`: Runtime configuration from environment variables or settings
+ * - `LlmToolsOptions`: Provider-specific options for instantiating tools
+ * - `Registered`: The record of a registered tool in the global registry
+ */
+export type LlmToolsOptions = TODO_object;
+/**
+ * TODO: [®] DRY Register logic
+ */

package/umd/src/llm-providers/_common/register/createLlmToolsFromConfiguration.d.ts

@@ -0,0 +1,55 @@
+import type { string_markdown_text, string_mime_type_with_wildcard, string_user_id } from '../../../types/typeAliases';
+import { MultipleLlmExecutionTools } from '../../_multiple/MultipleLlmExecutionTools';
+import type { LlmToolsConfiguration } from './LlmToolsConfiguration';
+/**
+ * Options for `$provideLlmToolsFromEnv`
+ *
+ * @private internal type for `$provideLlmToolsFromEnv` and `$provideLlmToolsForTestingAndScriptsAndPlayground`
+ */
+export type CreateLlmToolsFromConfigurationOptions = {
+    /**
+     * Title of the LLM tools
+     *
+     * @default 'LLM Tools from Configuration'
+     */
+    readonly title?: string_mime_type_with_wildcard & string_markdown_text;
+    /**
+     * This will will be passed to the created `LlmExecutionTools`
+     *
+     * @default false
+     */
+    readonly isVerbose?: boolean;
+    /**
+     * Identifier of the end user
+     *
+     * Note: This is passed to the LLM tools providers to identify misuse
+     */
+    readonly userId?: string_user_id;
+};
+/**
+ * Creates LLM execution tools from provided configuration objects
+ *
+ * Instantiates and configures LLM tool instances for each configuration entry,
+ * combining them into a unified interface via MultipleLlmExecutionTools.
+ *
+ * Note: This function is not cached, every call creates new instance of `MultipleLlmExecutionTools`
+ *
+ * @param configuration Array of LLM tool configurations to instantiate
+ * @param options Additional options for configuring the LLM tools
+ * @returns A unified interface combining all successfully instantiated LLM tools
+ * @public exported from `@promptbook/core`
+ */
+export declare function createLlmToolsFromConfiguration(configuration: LlmToolsConfiguration, options?: CreateLlmToolsFromConfigurationOptions): MultipleLlmExecutionTools;
+/**
+ * TODO: [🎌] Together with `createLlmToolsFromConfiguration` + 'EXECUTION_TOOLS_CLASSES' gets to `@promptbook/core` ALL model providers, make this more efficient
+ * TODO: [🧠][🎌] Dynamically install required providers
+ * TODO: We should implement an interactive configuration wizard that would:
+ *       1. Detect which LLM providers are available in the environment
+ *       2. Guide users through required configuration settings for each provider
+ *       3. Allow testing connections before completing setup
+ *       4. Generate appropriate configuration code for application integration
+ * TODO: [🧠][🍛] Which name is better `createLlmToolsFromConfig` or `createLlmToolsFromConfiguration`?
+ * TODO: [🧠] Is there some meaningfull way how to test this util
+ * TODO: This should be maybe not under `_common` but under `utils`
+ * TODO: [®] DRY Register logic
+ */

package/umd/src/llm-providers/_common/register/createLlmToolsFromConfiguration.test.d.ts

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

package/umd/src/llm-providers/_common/utils/assertUniqueModels.d.ts

@@ -0,0 +1,12 @@
+import { AvailableModel } from '../../../execution/AvailableModel';
+/**
+ * Utility to assert that all models in the provided array have unique `modelName` values.
+ *
+ * This is internal utility for unit tests to ensure no duplicate model names exist.
+ *
+ * @private internal utility of unit tests
+ */
+export declare function assertUniqueModels(models: ReadonlyArray<AvailableModel>): void;
+/**
+ * Note: [⚪] This should never be in any released package
+ */

package/umd/src/llm-providers/_common/utils/cache/CacheItem.d.ts

@@ -0,0 +1,33 @@
+import type { PromptResult } from '../../../../execution/PromptResult';
+import type { Prompt } from '../../../../types/Prompt';
+import type { string_date_iso8601 } from '../../../../types/typeAliases';
+import type { string_semantic_version } from '../../../../types/typeAliases';
+import type { string_promptbook_version } from '../../../../version';
+/**
+ * Represents a single item stored in the LLM cache.
+ */
+export type CacheItem = {
+    /**
+     * The date and time when the cache item was created, in ISO 8601 format.
+     */
+    date: string_date_iso8601;
+    /**
+     * The version of the Promptbook library used when this cache item was created.
+     */
+    promptbookVersion?: string_promptbook_version;
+    /**
+     * The version of the Book language used when this cache item was created.
+     */
+    bookVersion?: string_semantic_version;
+    /**
+     * The prompt that was sent to the LLM.
+     */
+    prompt: Prompt;
+    /**
+     * The response received from the LLM.
+     */
+    promptResult: PromptResult;
+};
+/**
+ * TODO: [🧠] Should be this exported alongsite `cacheLlmTools` through `@promptbook/utils` OR through `@promptbook/types`
+ */

package/umd/src/llm-providers/_common/utils/cache/CacheLlmToolsOptions.d.ts

@@ -0,0 +1,27 @@
+import type { PromptbookStorage } from '../../../../storage/_common/PromptbookStorage';
+import type { CacheItem } from './CacheItem';
+/**
+ * Options for configuring caching behavior for LlmExecutionTools.
+ */
+export type CacheLlmToolsOptions = {
+    /**
+     * The cache provider instance to use for storing and retrieving cached data.
+     *
+     * @default MemoryStorage
+     */
+    storage: PromptbookStorage<CacheItem>;
+    /**
+     * When set to `true`, the cache will be reloaded regardless of whether the data is already present in the cache.
+     * This can be useful for debugging or when you want to ensure that the latest data is always fetched.
+     * Data will ne still saved to the cache.
+     *
+     * @default false
+     */
+    isCacheReloaded?: boolean;
+    /**
+     * If true, the preparation logs additional information
+     *
+     * @default DEFAULT_IS_VERBOSE
+     */
+    readonly isVerbose?: boolean;
+};

package/umd/src/llm-providers/_common/utils/cache/cacheLlmTools.d.ts

@@ -0,0 +1,20 @@
+import type { LlmExecutionTools } from '../../../../execution/LlmExecutionTools';
+import type { CacheLlmToolsOptions } from './CacheLlmToolsOptions';
+/**
+ * Intercepts LLM tools and counts total usage of the tools
+ *
+ * Note: It can take extended `LlmExecutionTools` and cache the
+ * Note: Returns full proxy of all LLM tool properties and methods
+ *
+ * @param llmTools LLM tools to be intercepted with usage counting, it can contain extra methods like `totalUsage`
+ * @returns Full proxy of LLM tools with same functionality with added caching
+ * @public exported from `@promptbook/core`
+ */
+export declare function cacheLlmTools<TLlmTools extends LlmExecutionTools>(llmTools: TLlmTools, options?: Partial<CacheLlmToolsOptions>): TLlmTools;
+/**
+ * TODO: [🧠][💸] Maybe make some common abstraction `interceptLlmTools` and use here (or use javascript Proxy?)
+ * TODO: [🧠] Is there some meaningfull way how to test this util
+ * TODO: [👷‍♂️] Comprehensive manual about construction of llmTools
+ *            Detailed explanation about caching strategies and appropriate storage selection for different use cases
+ *            Examples of how to combine multiple interceptors for advanced caching, logging, and usage tracking
+ */

package/umd/src/llm-providers/_common/utils/count-total-usage/LlmExecutionToolsWithTotalUsage.d.ts

@@ -0,0 +1,22 @@
+import type { Observable } from 'rxjs';
+import type { LlmExecutionTools } from '../../../../execution/LlmExecutionTools';
+import type { Usage } from '../../../../execution/Usage';
+/**
+ * LLM tools with option to get total usage of the execution
+ */
+export type LlmExecutionToolsWithTotalUsage = LlmExecutionTools & {
+    /**
+     * Get total cost of the execution up to this point
+     */
+    getTotalUsage(): Usage;
+    /**
+     * Observable of total cost of the execution up to this point
+     *
+     * Note: This does report the cost of the last prompt, not the total cost of the execution up to this point
+     */
+    spending(): Observable<Usage>;
+};
+/**
+ * TODO: [👷‍♂️] Write a comprehensive manual about the construction of LLM tools
+ * Note: [🥫] Not using getter `get totalUsage` but `getTotalUsage` to allow this object to be proxied
+ */

package/umd/src/llm-providers/_common/utils/count-total-usage/countUsage.d.ts

@@ -0,0 +1,21 @@
+import type { LlmExecutionTools } from '../../../../execution/LlmExecutionTools';
+import type { LlmExecutionToolsWithTotalUsage } from './LlmExecutionToolsWithTotalUsage';
+/**
+ * Intercepts LLM tools and counts total usage of the tools.
+ *
+ * This function wraps the provided `LlmExecutionTools` with a proxy that tracks the cumulative
+ * usage (tokens, cost, etc.) across all model calls. It provides a way to monitor spending
+ * in real-time through an observable.
+ *
+ * @param llmTools - The LLM tools to be intercepted and tracked
+ * @returns Full proxy of the tools with added usage tracking capabilities
+ * @public exported from `@promptbook/core`
+ */
+export declare function countUsage<TLlmTools extends LlmExecutionTools>(llmTools: TLlmTools): TLlmTools & LlmExecutionToolsWithTotalUsage;
+/**
+ * TODO: [🧠][💸] Maybe make some common abstraction `interceptLlmTools` and use here (or use javascript Proxy?)
+ * TODO: [🧠] Is there some meaningfull way how to test this util
+ * TODO: [🧠][🌯] Maybe a way how to hide ability to `get totalUsage`
+ *     > const [llmToolsWithUsage,getUsage] = countTotalUsage(llmTools);
+ * TODO: [👷‍♂️] Write a comprehensive manual explaining the construction and usage of LLM tools in the Promptbook ecosystem
+ */

package/umd/src/llm-providers/_common/utils/count-total-usage/limitTotalUsage.d.ts

@@ -0,0 +1,36 @@
+import type { LlmExecutionTools } from '../../../../execution/LlmExecutionTools';
+import type { Usage } from '../../../../execution/Usage';
+import type { PromptbookStorage } from '../../../../storage/_common/PromptbookStorage';
+import type { TODO_any } from '../../../../utils/organization/TODO_any';
+import type { LlmExecutionToolsWithTotalUsage } from './LlmExecutionToolsWithTotalUsage';
+/**
+ * Options for the `limitTotalUsage` function.
+ */
+type LimitTotalUsageOptions = {
+    /**
+     * The usage limits to apply.
+     *
+     * @default ZERO_USAGE
+     */
+    maxTotalUsage: Usage;
+    /**
+     * The storage mechanism to use for tracking usage across multiple executions or instances.
+     *
+     * @default MemoryStorage which will not persist when the process ends
+     */
+    storage: PromptbookStorage<TODO_any>;
+};
+/**
+ * Wraps LlmExecutionTools to limit the total usage based on provided limits.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function limitTotalUsage(llmTools: LlmExecutionTools, options?: Partial<LimitTotalUsageOptions>): LlmExecutionToolsWithTotalUsage;
+export {};
+/**
+ * TODO: Maybe internally use `countTotalUsage`
+ * TODO: [🧠][💸] Maybe make some common abstraction `interceptLlmTools` and use here (or use javascript Proxy?)
+ * TODO: [🧠] Is there some meaningfull way how to test this util
+ * TODO: [🧠][🌯] Maybe a way how to hide ability to `get totalUsage`
+ * TODO: [👷‍♂️] Write a comprehensive manual about the construction of LLM tools
+ */