@promptbook/anthropic-claude 0.92.0-9 → 0.92.0

package/README.md

@@ -23,10 +23,6 @@
 
 
 
-<blockquote style="color: #ff8811">
-    <b>⚠ Warning:</b> This is a pre-release version of the library. It is not yet ready for production use. Please look at <a href="https://www.npmjs.com/package/@promptbook/core?activeTab=versions">latest stable release</a>.
-</blockquote>
-
 ## 📦 Package `@promptbook/anthropic-claude`
 
 - Promptbooks are [divided into several](#-packages) packages, all are published from [single monorepo](https://github.com/webgptorg/promptbook).
@@ -482,7 +478,7 @@ Or you can install them separately:
 -   **[@promptbook/legacy-documents](https://www.npmjs.com/package/@promptbook/legacy-documents)** - Read knowledge from legacy documents like `.doc`, `.rtf`,…
 -   **[@promptbook/website-crawler](https://www.npmjs.com/package/@promptbook/website-crawler)** - Crawl knowledge from the web
 -   **[@promptbook/editable](https://www.npmjs.com/package/@promptbook/editable)** - Editable book as native javascript object with imperative object API
--   **[@promptbook/templates](https://www.npmjs.com/package/@promptbook/templates)** - Usefull templates and examples of books which can be used as a starting point
+-   **[@promptbook/templates](https://www.npmjs.com/package/@promptbook/templates)** - Useful templates and examples of books which can be used as a starting point
 -   **[@promptbook/types](https://www.npmjs.com/package/@promptbook/types)** - Just typescript types used in the library
 -   ⭐ **[@promptbook/cli](https://www.npmjs.com/package/@promptbook/cli)** - Command line interface utilities for promptbooks
 -   🐋 **[Docker image](https://hub.docker.com/r/hejny/promptbook/)** - Promptbook server

package/esm/index.es.js

@@ -1,5 +1,6 @@
 import spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import Anthropic from '@anthropic-ai/sdk';
+import Bottleneck from 'bottleneck';
 import colors from 'colors';
 import { randomBytes } from 'crypto';
 import { io } from 'socket.io-client';
@@ -18,7 +19,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.92.0-9';
+const PROMPTBOOK_ENGINE_VERSION = '0.92.0';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -129,7 +130,7 @@ const CONNECTION_TIMEOUT_MS = 7 * 1000;
 const CONNECTION_RETRIES_LIMIT = 5;
 // <- TODO: [🧜‍♂️]
 /**
- * @@@
+ * Default settings for parsing and generating CSV files in Promptbook.
  *
  * @public exported from `@promptbook/core`
  */
@@ -139,6 +140,14 @@ Object.freeze({
     newline: '\n',
     skipEmptyLines: true,
 });
+/**
+ * Default rate limits (requests per minute)
+ *
+ * Note: Adjust based on the provider tier you are have
+ *
+ * @public exported from `@promptbook/core`
+ */
+const DEFAULT_MAX_REQUESTS_PER_MINUTE = 60;
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name
  * TODO: [🧠][🧜‍♂️] Maybe join remoteServerUrl and path into single value
@@ -199,7 +208,7 @@ class UnexpectedError extends Error {
                     ${block(message)}
 
                     Note: This error should not happen.
-                    It's probbably a bug in the pipeline collection
+                    It's probably a bug in the pipeline collection
 
                     Please report issue:
                     ${block(getErrorReportUrl(new Error(message)).href)}
@@ -399,8 +408,12 @@ function checkSerializableAsJson(options) {
  */
 
 /**
- * @@@
+ * Creates a deep clone of the given object
+ *
+ * Note: This method only works for objects that are fully serializable to JSON and do not contain functions, Dates, or special types.
  *
+ * @param objectValue The object to clone.
+ * @returns A deep, writable clone of the input object.
  * @public exported from `@promptbook/utils`
  */
 function deepClone(objectValue) {
@@ -468,7 +481,7 @@ function computeUsage(value) {
 /**
  * List of available Anthropic Claude models with pricing
  *
- * Note: Done at 2024-08-16
+ * Note: Done at 2025-05-06
  *
  * @see https://docs.anthropic.com/en/docs/models-overview
  * @public exported from `@promptbook/anthropic-claude`
@@ -482,8 +495,8 @@ const ANTHROPIC_CLAUDE_MODELS = exportJson({
             modelName: 'claude-3-5-sonnet-20240620',
             modelDescription: 'Latest Claude model with great reasoning, coding, and language understanding capabilities. 200K context window. Optimized balance of intelligence and speed.',
             pricing: {
-                prompt: computeUsage(`$3.00 / 1M tokens`),
-                output: computeUsage(`$15.00 / 1M tokens`),
+                prompt: computeUsage(`$2.50 / 1M tokens`),
+                output: computeUsage(`$12.50 / 1M tokens`),
             },
         },
         {
@@ -492,8 +505,8 @@ const ANTHROPIC_CLAUDE_MODELS = exportJson({
             modelName: 'claude-3-opus-20240229',
             modelDescription: 'Most capable Claude model excelling at complex reasoning, coding, and detailed instruction following. 200K context window. Best for sophisticated tasks requiring nuanced understanding.',
             pricing: {
-                prompt: computeUsage(`$15.00 / 1M tokens`),
-                output: computeUsage(`$75.00 / 1M tokens`),
+                prompt: computeUsage(`$12.00 / 1M tokens`),
+                output: computeUsage(`$60.00 / 1M tokens`),
             },
         },
         {
@@ -552,8 +565,8 @@ const ANTHROPIC_CLAUDE_MODELS = exportJson({
             modelName: 'claude-3-7-sonnet-20250219',
             modelDescription: 'Latest generation Claude model with advanced reasoning and language understanding. Enhanced capabilities over 3.5 with improved domain knowledge. 200K context window.',
             pricing: {
-                prompt: computeUsage(`$3.00 / 1M tokens`),
-                output: computeUsage(`$15.00 / 1M tokens`),
+                prompt: computeUsage(`$2.50 / 1M tokens`),
+                output: computeUsage(`$12.50 / 1M tokens`),
             },
         },
         {
@@ -604,7 +617,7 @@ class PipelineExecutionError extends Error {
         super(message);
         this.name = 'PipelineExecutionError';
         // TODO: [🐙] DRY - Maybe $randomId
-        this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid simmilar char conflicts   */)}`;
+        this.id = `error-${$randomToken(8 /* <- TODO: To global config + Use Base58 to avoid similar char conflicts   */)}`;
         Object.setPrototypeOf(this, PipelineExecutionError.prototype);
     }
 }
@@ -631,13 +644,13 @@ function $getCurrentDate() {
  */
 const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
 /**
- * @@@
+ * Placeholder value indicating a parameter is missing its value.
  *
  * @private within the repository
  */
 const RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
 /**
- * @@@
+ * Placeholder value indicating a parameter is restricted and cannot be used directly.
  *
  * @private within the repository
  */
@@ -1174,10 +1187,10 @@ for (let i = 0; i < defaultDiacriticsRemovalMap.length; i++) {
 */
 
 /**
- * @@@
+ * Removes diacritic marks (accents) from characters in a string.
  *
- * @param input @@@
- * @returns @@@
+ * @param input The string containing diacritics to be normalized.
+ * @returns The string with diacritics removed or normalized.
  * @public exported from `@promptbook/utils`
  */
 function removeDiacritics(input) {
@@ -1296,14 +1309,18 @@ $deepFreeze({
 /**
  * Make UncertainNumber
  *
- * @param value
+ * @param value value of the uncertain number, if `NaN` or `undefined`, it will be set to 0 and `isUncertain=true`
+ * @param isUncertain if `true`, the value is uncertain, otherwise depends on the value
  *
  * @private utility for initializating UncertainNumber
  */
-function uncertainNumber(value) {
+function uncertainNumber(value, isUncertain) {
     if (value === null || value === undefined || Number.isNaN(value)) {
         return UNCERTAIN_ZERO_VALUE;
     }
+    if (isUncertain === true) {
+        return { value, isUncertain };
+    }
     return { value };
 }
 
@@ -1369,6 +1386,8 @@ class AnthropicClaudeExecutionTools {
          * Anthropic Claude API client.
          */
         this.client = null;
+        const rate = this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE;
+        this.limiter = new Bottleneck({ minTime: 60000 / rate });
     }
     get title() {
         return 'Anthropic Claude';
@@ -1420,8 +1439,6 @@ class AnthropicClaudeExecutionTools {
             //                                            <- TODO: [🌾] Make some global max cap for maxTokens
             temperature: modelRequirements.temperature,
             system: modelRequirements.systemMessage,
-            // <- TODO: [🈁] Use `seed` here AND/OR use is `isDeterministic` for entire execution tools
-            // <- Note: [🧆]
             messages: [
                 {
                     role: 'user',
@@ -1430,14 +1447,14 @@ class AnthropicClaudeExecutionTools {
                     //    @see https://docs.anthropic.com/en/docs/test-and-evaluate/strengthen-guardrails/increase-consistency#specify-the-desired-output-format
                 },
             ],
-            // TODO: Is here some equivalent of user identification?> user: this.options.user,
         };
         const start = $getCurrentDate();
-        let complete;
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
-        const rawResponse = await client.messages.create(rawRequest).catch((error) => {
+        const rawResponse = await this.limiter
+            .schedule(() => client.messages.create(rawRequest))
+            .catch((error) => {
             if (this.options.isVerbose) {
                 console.info(colors.bgRed('error'), error);
             }
@@ -1457,12 +1474,11 @@ class AnthropicClaudeExecutionTools {
             throw new PipelineExecutionError(`Returned content is not "text" type but "${contentBlock.type}"`);
         }
         const resultContent = contentBlock.text;
-        // eslint-disable-next-line prefer-const
-        complete = $getCurrentDate();
+        const complete = $getCurrentDate();
         const usage = computeAnthropicClaudeUsage(rawPromptContent || '', resultContent || '', rawResponse);
         return exportJson({
             name: 'promptResult',
-            message: `Result of \`AzureOpenAiExecutionTools.callChatModel\``,
+            message: `Result of \`AnthropicClaudeExecutionTools.callChatModel\``,
             order: [],
             value: {
                 content: resultContent,
@@ -1479,83 +1495,59 @@ class AnthropicClaudeExecutionTools {
             },
         });
     }
-    /*
-    TODO: [👏]
-    public async callCompletionModel(
-        prompt: Pick<Prompt, 'content' | 'parameters' | 'modelRequirements'>,
-    ): Promise<CompletionPromptResult> {
-
+    /**
+     * Calls Anthropic Claude API to use a completion model.
+     */
+    async callCompletionModel(prompt) {
         if (this.options.isVerbose) {
             console.info('🖋 Anthropic Claude callCompletionModel call');
         }
-
         const { content, parameters, modelRequirements } = prompt;
-
-        // TODO: [☂] Use here more modelRequirements
         if (modelRequirements.modelVariant !== 'COMPLETION') {
             throw new PipelineExecutionError('Use callCompletionModel only for COMPLETION variant');
         }
-
+        const client = await this.getClient();
         const modelName = modelRequirements.modelName || this.getDefaultChatModel().modelName;
-        const modelSettings = {
+        const rawPromptContent = templateParameters(content, { ...parameters, modelName });
+        const rawRequest = {
             model: modelName,
-            max_tokens: modelRequirements.maxTokens || 2000, // <- Note: 2000 is for lagacy reasons
-            //                                                  <- TODO: [🌾] Make some global max cap for maxTokens
-            // <- TODO: Use here `systemMessage`, `temperature` and `seed`
-        };
-
-        const rawRequest: xxxx.Completions.CompletionCreateParamsNonStreaming = {
-            ...modelSettings,
+            max_tokens_to_sample: modelRequirements.maxTokens || 2000,
+            temperature: modelRequirements.temperature,
             prompt: rawPromptContent,
-            user: this.options.user,
         };
-        const start: string_date_iso8601 = $getCurrentDate();
-        let complete: string_date_iso8601;
-
-        if (this.options.isVerbose) {
-            console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
-        }
-        const rawResponse = await this.client.completions.create(rawRequest).catch((error) => {
-                if (this.options.isVerbose) {
-                    console.info(colors.bgRed('error'), error);
-                }
-                throw error;
-            });
-
-
+        const start = $getCurrentDate();
+        const rawResponse = await this.limiter
+            .schedule(() => client.completions.create(rawRequest))
+            .catch((error) => {
+            if (this.options.isVerbose) {
+                console.info(colors.bgRed('error'), error);
+            }
+            throw error;
+        });
         if (this.options.isVerbose) {
             console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
         }
-
-        if (!rawResponse.choices[0]) {
-            throw new PipelineExecutionError('No choises from Anthropic Claude');
-        }
-
-        if (rawResponse.choices.length > 1) {
-            // TODO: This should be maybe only warning
-            throw new PipelineExecutionError('More than one choise from Anthropic Claude');
+        if (!rawResponse.completion) {
+            throw new PipelineExecutionError('No completion from Anthropic Claude');
         }
-
-        const resultContent = rawResponse.choices[0].text;
-        // eslint-disable-next-line prefer-const
-        complete = $getCurrentDate();
-        const usage = { price: 'UNKNOWN', inputTokens: 0, outputTokens: 0 /* <- TODO: [🐞] Compute usage * / } satisfies Usage;
-
-
-
-        return $exportJson({ name: 'promptResult',message: Result of \`AzureOpenAiExecutionTools callChatModel\`, order: [],value:{
-            content: resultContent,
-            modelName: rawResponse.model || model,
-            timing: {
-                start,
-                complete,
+        const resultContent = rawResponse.completion;
+        const complete = $getCurrentDate();
+        const usage = computeAnthropicClaudeUsage(rawPromptContent, resultContent, rawResponse);
+        return exportJson({
+            name: 'promptResult',
+            message: `Result of \`AnthropicClaudeExecutionTools.callCompletionModel\``,
+            order: [],
+            value: {
+                content: resultContent,
+                modelName: rawResponse.model || modelName,
+                timing: { start, complete },
+                usage,
+                rawPromptContent,
+                rawRequest,
+                rawResponse,
             },
-            usage,
-            rawResponse,
-            // <- [🗯]
         });
     }
-    */
     // <- Note: [🤖] callXxxModel
     /**
      * Get the model that should be used as default
@@ -1564,7 +1556,7 @@ class AnthropicClaudeExecutionTools {
         const model = ANTHROPIC_CLAUDE_MODELS.find(({ modelName }) => modelName.startsWith(defaultModelName));
         if (model === undefined) {
             throw new UnexpectedError(spaceTrim((block) => `
-                          Cannot find model in OpenAI models with name "${defaultModelName}" which should be used as default.
+                          Cannot find model in Anthropic Claude models with name "${defaultModelName}" which should be used as default.
 
                           Available models:
                           ${block(ANTHROPIC_CLAUDE_MODELS.map(({ modelName }) => `- "${modelName}"`).join('\n'))}
@@ -1634,7 +1626,7 @@ class AuthenticationError extends Error {
 }
 
 /**
- * This error indicates that the pipeline collection cannot be propperly loaded
+ * This error indicates that the pipeline collection cannot be properly loaded
  *
  * @public exported from `@promptbook/core`
  */
@@ -1698,7 +1690,7 @@ class MissingToolsError extends Error {
         super(spaceTrim$1((block) => `
                     ${block(message)}
 
-                    Note: You have probbably forgot to provide some tools for pipeline execution or preparation
+                    Note: You have probably forgot to provide some tools for pipeline execution or preparation
 
                 `));
         this.name = 'MissingToolsError';
@@ -1889,7 +1881,7 @@ function deserializeError(error) {
  * Tests if given string is valid URL.
  *
  * Note: Dataurl are considered perfectly valid.
- * Note: There are two simmilar functions:
+ * Note: There are two similar functions:
  * - `isValidUrl` which tests any URL
  * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
  *
@@ -1976,10 +1968,10 @@ class RemoteLlmExecutionTools {
     }
     get title() {
         // TODO: [🧠] Maybe fetch title+description from the remote server (as well as if model methods are defined)
-        return 'Remote server';
+        return 'Promptbook remote server';
     }
     get description() {
-        return 'Use all models by your remote server';
+        return `Models from Promptbook remote server ${this.options.remoteServerUrl}`;
     }
     /**
      * Check the configuration of all execution tools
@@ -1994,7 +1986,7 @@ class RemoteLlmExecutionTools {
      * List all available models that can be used
      */
     async listModels() {
-        // TODO: [👒] Listing models (and checking configuration) probbably should go through REST API not Socket.io
+        // TODO: [👒] Listing models (and checking configuration) probably should go through REST API not Socket.io
         const socket = await createRemoteClient(this.options);
         socket.emit('listModels-request', {
             identification: this.options.identification,
@@ -2111,7 +2103,8 @@ const createAnthropicClaudeExecutionTools = Object.assign((options) => {
  */
 
 /**
- * @@@
+ * Safely retrieves the global scope object (window in browser, global in Node.js)
+ * regardless of the JavaScript environment in which the code is running
  *
  * Note: `$` is used to indicate that this function is not a pure function - it access global scope
  *
@@ -2122,10 +2115,10 @@ function $getGlobalScope() {
 }
 
 /**
- * @@@
+ * Normalizes a text string to SCREAMING_CASE (all uppercase with underscores).
  *
- * @param text @@@
- * @returns @@@
+ * @param text The text string to be converted to SCREAMING_CASE format.
+ * @returns The normalized text in SCREAMING_CASE format.
  * @example 'HELLO_WORLD'
  * @example 'I_LOVE_PROMPTBOOK'
  * @public exported from `@promptbook/utils`
@@ -2177,10 +2170,10 @@ function normalizeTo_SCREAMING_CASE(text) {
  */
 
 /**
- * @@@
+ * Normalizes a text string to snake_case format.
  *
- * @param text @@@
- * @returns @@@
+ * @param text The text string to be converted to snake_case format.
+ * @returns The normalized text in snake_case format.
  * @example 'hello_world'
  * @example 'i_love_promptbook'
  * @public exported from `@promptbook/utils`
@@ -2190,11 +2183,11 @@ function normalizeTo_snake_case(text) {
 }
 
 /**
- * Register is @@@
+ * Global registry for storing and managing registered entities of a given type.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it accesses and adds variables in global scope.
  *
- * @private internal utility, exported are only signleton instances of this class
+ * @private internal utility, exported are only singleton instances of this class
  */
 class $Register {
     constructor(registerName) {
@@ -2238,10 +2231,10 @@ class $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 thare can be more @@@
+ * @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`
  */
 const $llmToolsRegister = new $Register('llm_execution_tools_constructors');