@promptbook/remote-server 0.101.0-2 → 0.101.0-21

package/README.md

@@ -49,6 +49,51 @@ npm install @promptbook/remote-server
 ```
 
 
+Remote server implementation for Promptbook, enabling distributed execution of promptbook pipelines across network boundaries with REST API and WebSocket support.
+
+## 🎯 Purpose and Motivation
+
+This package provides a remote server that allows promptbook pipelines to be executed over the network. It enables distributed architectures where promptbook execution can be centralized on powerful servers while clients can access the functionality remotely, making it ideal for scaling promptbook applications and providing API access to promptbook collections.
+
+## 🔧 High-Level Functionality
+
+The package provides remote server capabilities:
+- **HTTP REST API**: RESTful endpoints for pipeline execution and management
+- **WebSocket Support**: Real-time communication for streaming execution results
+- **Authentication**: Support for both anonymous and application-based authentication
+- **Pipeline Management**: Remote access to promptbook collections and pipelines
+- **Execution Orchestration**: Distributed execution of promptbook pipelines
+- **OpenAI Compatibility**: OpenAI-compatible API endpoints for seamless integration
+
+## ✨ Key Features
+
+- 🌐 **Remote Execution** - Execute promptbook pipelines over HTTP/WebSocket
+- 🔐 **Authentication Modes** - Support for anonymous and application-based access
+- 📡 **Real-time Communication** - WebSocket support for streaming results
+- 🔌 **OpenAI Compatible** - Use promptbooks as OpenAI-compatible models
+- 🚀 **Scalable Architecture** - Distribute promptbook execution across servers
+- 📊 **Pipeline Management** - Remote access to collections and individual pipelines
+- 🛡️ **Security** - Configurable authentication and access control
+- ⚡ **High Performance** - Optimized for concurrent pipeline execution
+
+## 📦 Exported Entities
+
+### Version Information
+- `BOOK_LANGUAGE_VERSION` - Current book language version
+- `PROMPTBOOK_ENGINE_VERSION` - Current engine version
+
+### Server Management
+- `startRemoteServer` - Start the remote promptbook server
+
+### Configuration Types
+- `RemoteServerOptions` - Configuration options for remote server (type)
+
+### Authentication Types
+- `Identification` - Base identification interface (type)
+- `ApplicationModeIdentification` - Application mode identification (type)
+- `AnonymousModeIdentification` - Anonymous mode identification (type)
+
+> 💡 This package provides remote server functionality for promptbook applications. For the core functionality, see [@promptbook/core](#-packages) or install all packages with `npm i ptbk`
 
 
 ---

package/esm/index.es.js

@@ -31,7 +31,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.101.0-2';
+const PROMPTBOOK_ENGINE_VERSION = '0.101.0-21';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -2878,75 +2878,32 @@ function countUsage(llmTools) {
  */
 
 /**
- * Predefined profiles for LLM providers to maintain consistency across the application
- * These profiles represent each provider as a virtual persona in chat interfaces
+ * Takes an item or an array of items and returns an array of items
  *
- * @private !!!!
+ * 1) Any item except array and undefined returns array with that one item (also null)
+ * 2) Undefined returns empty array
+ * 3) Array returns itself
+ *
+ * @private internal utility
  */
-const LLM_PROVIDER_PROFILES = {
-    OPENAI: {
-        name: 'OPENAI',
-        fullname: 'OpenAI GPT',
-        color: '#10a37f', // OpenAI's signature green
-        // Note: avatarSrc could be added when we have provider logos available
-    },
-    ANTHROPIC: {
-        name: 'ANTHROPIC',
-        fullname: 'Anthropic Claude',
-        color: '#d97706', // Anthropic's orange/amber color
-    },
-    AZURE_OPENAI: {
-        name: 'AZURE_OPENAI',
-        fullname: 'Azure OpenAI',
-        color: '#0078d4', // Microsoft Azure blue
-    },
-    GOOGLE: {
-        name: 'GOOGLE',
-        fullname: 'Google Gemini',
-        color: '#4285f4', // Google blue
-    },
-    DEEPSEEK: {
-        name: 'DEEPSEEK',
-        fullname: 'DeepSeek',
-        color: '#7c3aed', // Purple color for DeepSeek
-    },
-    OLLAMA: {
-        name: 'OLLAMA',
-        fullname: 'Ollama',
-        color: '#059669', // Emerald green for local models
-    },
-    REMOTE: {
-        name: 'REMOTE',
-        fullname: 'Remote Server',
-        color: '#6b7280', // Gray for remote/proxy connections
-    },
-    MOCKED_ECHO: {
-        name: 'MOCKED_ECHO',
-        fullname: 'Echo (Test)',
-        color: '#8b5cf6', // Purple for test/mock tools
-    },
-    MOCKED_FAKE: {
-        name: 'MOCKED_FAKE',
-        fullname: 'Fake LLM (Test)',
-        color: '#ec4899', // Pink for fake/test tools
-    },
-    VERCEL: {
-        name: 'VERCEL',
-        fullname: 'Vercel AI',
-        color: '#000000', // Vercel's black
-    },
-    MULTIPLE: {
-        name: 'MULTIPLE',
-        fullname: 'Multiple Providers',
-        color: '#6366f1', // Indigo for combined/multiple providers
-    },
-};
+function arrayableToArray(input) {
+    if (input === undefined) {
+        return [];
+    }
+    if (input instanceof Array) {
+        return input;
+    }
+    return [input];
+}
+
 /**
- * TODO: Refactor this - each profile must be alongside the provider definition
- * TODO: [🕛] Unite `AgentBasicInformation`, `ChatParticipant`, `LlmExecutionTools` +  `LlmToolsMetadata`
- * Note: [💞] Ignore a discrepancy between file name and entity name
+ * Profile for Multiple providers aggregation
  */
-
+const MULTIPLE_PROVIDER_PROFILE = {
+    name: 'MULTIPLE',
+    fullname: 'Multiple Providers',
+    color: '#6366f1',
+};
 /**
  * Multiple LLM Execution Tools is a proxy server that uses multiple execution tools internally and exposes the executor interface externally.
  *
@@ -2957,12 +2914,10 @@ class MultipleLlmExecutionTools {
     /**
      * Gets array of execution tools in order of priority
      */
-    constructor(...llmExecutionTools) {
+    constructor(title, ...llmExecutionTools) {
+        this.title = title;
         this.llmExecutionTools = llmExecutionTools;
     }
-    get title() {
-        return 'Multiple LLM Providers';
-    }
     get description() {
         const innerModelsTitlesAndDescriptions = this.llmExecutionTools
             .map(({ title, description }, index) => {
@@ -2984,7 +2939,7 @@ class MultipleLlmExecutionTools {
             `);
     }
     get profile() {
-        return LLM_PROVIDER_PROFILES.MULTIPLE;
+        return MULTIPLE_PROVIDER_PROFILE;
     }
     /**
      * Check the configuration of all execution tools
@@ -3048,7 +3003,7 @@ class MultipleLlmExecutionTools {
                         return await llmExecutionTools.callEmbeddingModel(prompt);
                     // <- case [🤖]:
                     default:
-                        throw new UnexpectedError(`Unknown model variant "${prompt.modelRequirements.modelVariant}"`);
+                        throw new UnexpectedError(`Unknown model variant "${prompt.modelRequirements.modelVariant}" in ${llmExecutionTools.title}`);
                 }
             }
             catch (error) {
@@ -3069,7 +3024,7 @@ class MultipleLlmExecutionTools {
             //     2) AnthropicClaude throw PipelineExecutionError: Parameter `{knowledge}` is not defined
             //     3) ...
             spaceTrim((block) => `
-                          All execution tools failed:
+                          All execution tools of ${this.title} failed:
 
                           ${block(errors
                 .map(({ error, llmExecutionTools }, i) => `${i + 1}) **${llmExecutionTools.title}** thrown **${error.name || 'Error'}:** ${error.message}`)
@@ -3078,11 +3033,11 @@ class MultipleLlmExecutionTools {
                     `));
         }
         else if (this.llmExecutionTools.length === 0) {
-            throw new PipelineExecutionError(`You have not provided any \`LlmExecutionTools\``);
+            throw new PipelineExecutionError(`You have not provided any \`LlmExecutionTools\` into ${this.title}`);
         }
         else {
             throw new PipelineExecutionError(spaceTrim((block) => `
-                          You have not provided any \`LlmExecutionTools\` that support model variant "${prompt.modelRequirements.modelVariant}"
+                          You have not provided any \`LlmExecutionTools\` that support model variant "${prompt.modelRequirements.modelVariant}" into ${this.title}
 
                           Available \`LlmExecutionTools\`:
                           ${block(this.description)}
@@ -3112,7 +3067,7 @@ class MultipleLlmExecutionTools {
  *
  * @public exported from `@promptbook/core`
  */
-function joinLlmExecutionTools(...llmExecutionTools) {
+function joinLlmExecutionTools(title, ...llmExecutionTools) {
     if (llmExecutionTools.length === 0) {
         const warningMessage = spaceTrim(`
             You have not provided any \`LlmExecutionTools\`
@@ -3144,30 +3099,27 @@ function joinLlmExecutionTools(...llmExecutionTools) {
         };
         */
     }
-    return new MultipleLlmExecutionTools(...llmExecutionTools);
+    return new MultipleLlmExecutionTools(title || 'Multiple LLM Providers joined by `joinLlmExecutionTools`', ...llmExecutionTools);
 }
 /**
  * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
  */
 
 /**
- * Takes an item or an array of items and returns an array of items
+ * Just returns the given `LlmExecutionTools` or joins multiple into one
  *
- * 1) Any item except array and undefined returns array with that one item (also null)
- * 2) Undefined returns empty array
- * 3) Array returns itself
- *
- * @private internal utility
+ * @public exported from `@promptbook/core`
  */
-function arrayableToArray(input) {
-    if (input === undefined) {
-        return [];
-    }
-    if (input instanceof Array) {
-        return input;
-    }
-    return [input];
+function getSingleLlmExecutionTools(oneOrMoreLlmExecutionTools) {
+    const _llms = arrayableToArray(oneOrMoreLlmExecutionTools);
+    const llmTools = _llms.length === 1
+        ? _llms[0]
+        : joinLlmExecutionTools('Multiple LLM Providers joined by `getSingleLlmExecutionTools`', ..._llms);
+    return llmTools;
 }
+/**
+ * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
+ */
 
 /**
  * Prepares the persona for the pipeline
@@ -3186,8 +3138,7 @@ async function preparePersona(personaDescription, tools, options) {
         pipeline: await collection.getPipelineByUrl('https://promptbook.studio/promptbook/prepare-persona.book'),
         tools,
     });
-    const _llms = arrayableToArray(tools.llm);
-    const llmTools = _llms.length === 1 ? _llms[0] : joinLlmExecutionTools(..._llms);
+    const llmTools = getSingleLlmExecutionTools(tools.llm);
     const availableModels = (await llmTools.listModels())
         .filter(({ modelVariant }) => modelVariant === 'CHAT')
         .map(({ modelName, modelDescription }) => ({
@@ -3231,6 +3182,7 @@ async function preparePersona(personaDescription, tools, options) {
     };
 }
 /**
+ * TODO: [😩] DRY `preparePersona` and `selectBestModelFromAvailable`
  * TODO: [🔃][main] If the persona was prepared with different version or different set of models, prepare it once again
  * TODO: [🏢] Check validity of `modelName` in pipeline
  * TODO: [🏢] Check validity of `systemMessage` in pipeline
@@ -4349,9 +4301,7 @@ async function preparePipeline(pipeline, tools, options) {
     if (tools === undefined || tools.llm === undefined) {
         throw new MissingToolsError('LLM tools are required for preparing the pipeline');
     }
-    // TODO: [🚐] Make arrayable LLMs -> single LLM DRY
-    const _llms = arrayableToArray(tools.llm);
-    const llmTools = _llms.length === 1 ? _llms[0] : joinLlmExecutionTools(..._llms);
+    const llmTools = getSingleLlmExecutionTools(tools.llm);
     const llmToolsWithUsage = countUsage(llmTools);
     //    <- TODO: [🌯]
     /*
@@ -5511,9 +5461,7 @@ async function executeAttempts(options) {
         $scriptPipelineExecutionErrors: [],
         $failedResults: [], // Track all failed attempts
     };
-    // TODO: [🚐] Make arrayable LLMs -> single LLM DRY
-    const _llms = arrayableToArray(tools.llm);
-    const llmTools = _llms.length === 1 ? _llms[0] : joinLlmExecutionTools(..._llms);
+    const llmTools = getSingleLlmExecutionTools(tools.llm);
     attempts: for (let attemptIndex = -jokerParameterNames.length; attemptIndex < maxAttempts; attemptIndex++) {
         const isJokerAttempt = attemptIndex < 0;
         const jokerParameterName = jokerParameterNames[jokerParameterNames.length + attemptIndex];
@@ -6033,9 +5981,7 @@ async function getKnowledgeForTask(options) {
         return ''; // <- Note: Np knowledge present, return empty string
     }
     try {
-        // TODO: [🚐] Make arrayable LLMs -> single LLM DRY
-        const _llms = arrayableToArray(tools.llm);
-        const llmTools = _llms.length === 1 ? _llms[0] : joinLlmExecutionTools(..._llms);
+        const llmTools = getSingleLlmExecutionTools(tools.llm);
         const taskEmbeddingPrompt = {
             title: 'Knowledge Search',
             modelRequirements: {
@@ -6636,13 +6582,13 @@ function createPipelineExecutor(options) {
                     // Calculate and update tldr based on pipeline progress
                     const cv = newOngoingResult;
                     // Calculate progress based on parameters resolved vs total parameters
-                    const totalParameters = pipeline.parameters.filter(p => !p.isInput).length;
+                    const totalParameters = pipeline.parameters.filter((p) => !p.isInput).length;
                     let resolvedParameters = 0;
                     let currentTaskTitle = '';
                     // Get the resolved parameters from output parameters
                     if (cv === null || cv === void 0 ? void 0 : cv.outputParameters) {
                         // Count how many output parameters have non-empty values
-                        resolvedParameters = Object.values(cv.outputParameters).filter(value => value !== undefined && value !== null && String(value).trim() !== '').length;
+                        resolvedParameters = Object.values(cv.outputParameters).filter((value) => value !== undefined && value !== null && String(value).trim() !== '').length;
                     }
                     // Try to determine current task from execution report
                     if (((_a = cv === null || cv === void 0 ? void 0 : cv.executionReport) === null || _a === void 0 ? void 0 : _a.promptExecutions) && cv.executionReport.promptExecutions.length > 0) {
@@ -6898,7 +6844,7 @@ function $registeredLlmToolsMessage() {
  * @public exported from `@promptbook/core`
  */
 function createLlmToolsFromConfiguration(configuration, options = {}) {
-    const { isVerbose = DEFAULT_IS_VERBOSE, userId } = options;
+    const { title = 'LLM Tools from Configuration', isVerbose = DEFAULT_IS_VERBOSE, userId } = options;
     const llmTools = configuration.map((llmConfiguration) => {
         const registeredItem = $llmToolsRegister
             .list()
@@ -6930,7 +6876,7 @@ function createLlmToolsFromConfiguration(configuration, options = {}) {
             ...llmConfiguration.options,
         });
     });
-    return joinLlmExecutionTools(...llmTools);
+    return joinLlmExecutionTools(title, ...llmTools);
 }
 /**
  * TODO: [🎌] Together with `createLlmToolsFromConfiguration` + 'EXECUTION_TOOLS_CLASSES' gets to `@promptbook/core` ALL model providers, make this more efficient
@@ -8179,8 +8125,11 @@ function startRemoteServer(options) {
         if (isAnonymous === true) {
             // Note: Anonymous mode
             // TODO: Maybe check that configuration is not empty
-            const { llmToolsConfiguration } = identification;
-            llm = createLlmToolsFromConfiguration(llmToolsConfiguration, { isVerbose });
+            const { userId, llmToolsConfiguration } = identification;
+            llm = createLlmToolsFromConfiguration(llmToolsConfiguration, {
+                title: `LLM Tools for anonymous user "${userId}" on server`,
+                isVerbose,
+            });
         }
         else if (isAnonymous === false && createLlmExecutionTools !== null) {
             // Note: Application mode
@@ -8214,7 +8163,7 @@ function startRemoteServer(options) {
     });
     // Note: OpenAI-compatible chat completions endpoint
     app.post('/v1/chat/completions', async (request, response) => {
-        // TODO: !!!! Make more promptbook-native:
+        // TODO: [🧠][🦢] Make OpenAI  compatible more promptbook-native - make reverse adapter from LlmExecutionTools to OpenAI-compatible:
         try {
             const params = request.body;
             const { model, messages } = params;