@promptbook/core 0.100.0-2 → 0.100.0-21

package/umd/index.umd.js

@@ -27,136 +27,258 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.100.0-2';
+    const PROMPTBOOK_ENGINE_VERSION = '0.100.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
      */
 
     /**
-     * Converts PipelineCollection to serialized JSON
+     * Extracts profile image URL from agent definition text and returns cleaned system message
+     * @param systemMessage The original system message that may contain META IMAGE line
+     * @returns Object with profileImageUrl (if found) and cleanedSystemMessage (without META IMAGE line)
      *
-     * Note: Functions `collectionToJson` and `createCollectionFromJson` are complementary
+     * @private - TODO: [🧠] Maybe should be public?
+     */
+    /**
+     * Generates a gravatar URL based on agent name for fallback avatar
+     * @param name The agent name to generate avatar for
+     * @returns Gravatar URL
      *
-     * @public exported from `@promptbook/core`
+     * @private - TODO: [🧠] Maybe should be public?
      */
-    async function collectionToJson(collection) {
-        const pipelineUrls = await collection.listPipelines();
-        const promptbooks = await Promise.all(pipelineUrls.map((url) => collection.getPipelineByUrl(url)));
-        return promptbooks;
+    function generateGravatarUrl(name) {
+        // Use a default name if none provided
+        const safeName = name || 'Anonymous Agent';
+        // Create a simple hash from the name for consistent avatar
+        let hash = 0;
+        for (let i = 0; i < safeName.length; i++) {
+            const char = safeName.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        const avatarId = Math.abs(hash).toString();
+        return `https://www.gravatar.com/avatar/${avatarId}?default=robohash&size=200&rating=x`;
     }
     /**
-     * TODO: [🧠] Maybe clear `sourceFile` or clear when exposing through API or remote server
+     * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
     /**
-     * Checks if value is valid email
+     * Freezes the given object and all its nested objects recursively
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
+     * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
      *
+     * @returns The same object as the input, but deeply frozen
      * @public exported from `@promptbook/utils`
      */
-    function isValidEmail(email) {
-        if (typeof email !== 'string') {
-            return false;
+    function $deepFreeze(objectValue) {
+        if (Array.isArray(objectValue)) {
+            return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
         }
-        if (email.split('\n').length > 1) {
-            return false;
+        const propertyNames = Object.getOwnPropertyNames(objectValue);
+        for (const propertyName of propertyNames) {
+            const value = objectValue[propertyName];
+            if (value && typeof value === 'object') {
+                $deepFreeze(value);
+            }
         }
-        return /^.+@.+\..+$/.test(email);
+        Object.freeze(objectValue);
+        return objectValue;
     }
+    /**
+     * TODO: [🧠] Is there a way how to meaningfully test this utility
+     */
 
     /**
-     * Tests if given string is valid URL.
+     * Generates a regex pattern to match a specific commitment
      *
-     * Note: This does not check if the file exists only if the path is valid
-     * @public exported from `@promptbook/utils`
+     * Note: It always creates new Regex object
+     * Note: Uses word boundaries to ensure only full words are matched (e.g., "PERSONA" matches but "PERSONALITY" does not)
+     *
+     * @private
      */
-    function isValidFilePath(filename) {
-        if (typeof filename !== 'string') {
-            return false;
+    function createCommitmentRegex(commitment) {
+        const escapedCommitment = commitment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const keywordPattern = escapedCommitment.split(/\s+/).join('\\s+');
+        const regex = new RegExp(`^\\s*(?<type>${keywordPattern})\\b\\s+(?<contents>.+)$`, 'gim');
+        return regex;
+    }
+    /**
+     * Generates a regex pattern to match a specific commitment type
+     *
+     * Note: It just matches the type part of the commitment
+     * Note: It always creates new Regex object
+     * Note: Uses word boundaries to ensure only full words are matched (e.g., "PERSONA" matches but "PERSONALITY" does not)
+     *
+     * @private
+     */
+    function createCommitmentTypeRegex(commitment) {
+        const escapedCommitment = commitment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const keywordPattern = escapedCommitment.split(/\s+/).join('\\s+');
+        const regex = new RegExp(`^\\s*(?<type>${keywordPattern})\\b`, 'gim');
+        return regex;
+    }
+
+    /**
+     * Base implementation of CommitmentDefinition that provides common functionality
+     * Most commitments can extend this class and only override the applyToAgentModelRequirements method
+     *
+     * @private
+     */
+    class BaseCommitmentDefinition {
+        constructor(type) {
+            this.type = type;
         }
-        if (filename.split('\n').length > 1) {
-            return false;
+        /**
+         * Creates a regex pattern to match this commitment in agent source
+         * Uses the existing createCommitmentRegex function as internal helper
+         */
+        createRegex() {
+            return createCommitmentRegex(this.type);
         }
-        if (filename.split(' ').length >
-            5 /* <- TODO: [🧠][🈷] Make some better non-arbitrary way how to distinct filenames from informational texts */) {
-            return false;
+        /**
+         * Creates a regex pattern to match just the commitment type
+         * Uses the existing createCommitmentTypeRegex function as internal helper
+         */
+        createTypeRegex() {
+            return createCommitmentTypeRegex(this.type);
         }
-        const filenameSlashes = filename.split('\\').join('/');
-        // Absolute Unix path: /hello.txt
-        if (/^(\/)/i.test(filenameSlashes)) {
-            // console.log(filename, 'Absolute Unix path: /hello.txt');
-            return true;
+        /**
+         * Helper method to create a new requirements object with updated system message
+         * This is commonly used by many commitments
+         */
+        updateSystemMessage(requirements, messageUpdate) {
+            const newMessage = typeof messageUpdate === 'string' ? messageUpdate : messageUpdate(requirements.systemMessage);
+            return {
+                ...requirements,
+                systemMessage: newMessage,
+            };
         }
-        // Absolute Windows path: /hello.txt
-        if (/^([A-Z]{1,2}:\/?)\//i.test(filenameSlashes)) {
-            // console.log(filename, 'Absolute Windows path: /hello.txt');
-            return true;
+        /**
+         * Helper method to append content to the system message
+         */
+        appendToSystemMessage(requirements, content, separator = '\n\n') {
+            return this.updateSystemMessage(requirements, (currentMessage) => {
+                if (!currentMessage.trim()) {
+                    return content;
+                }
+                return currentMessage + separator + content;
+            });
         }
-        // Relative path: ./hello.txt
-        if (/^(\.\.?\/)+/i.test(filenameSlashes)) {
-            // console.log(filename, 'Relative path: ./hello.txt');
-            return true;
+        /**
+         * Helper method to add a comment section to the system message
+         * Comments are lines starting with # that will be removed from the final system message
+         * but can be useful for organizing and structuring the message during processing
+         */
+        addCommentSection(requirements, commentTitle, content, position = 'end') {
+            const commentSection = `# ${commentTitle.toUpperCase()}\n${content}`;
+            if (position === 'beginning') {
+                return this.updateSystemMessage(requirements, (currentMessage) => {
+                    if (!currentMessage.trim()) {
+                        return commentSection;
+                    }
+                    return commentSection + '\n\n' + currentMessage;
+                });
+            }
+            else {
+                return this.appendToSystemMessage(requirements, commentSection);
+            }
         }
-        // Allow paths like foo/hello
-        if (/^[^/]+\/[^/]+/i.test(filenameSlashes)) {
-            // console.log(filename, 'Allow paths like foo/hello');
-            return true;
+    }
+
+    /**
+     * ACTION commitment definition
+     *
+     * The ACTION commitment defines specific actions or capabilities that the agent can perform.
+     * This helps define what the agent is capable of doing and how it should approach tasks.
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * ACTION Can generate code snippets and explain programming concepts
+     * ACTION Able to analyze data and provide insights
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class ActionCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('ACTION');
         }
-        // Allow paths like hello.book
-        if (/^[^/]+\.[^/]+$/i.test(filenameSlashes)) {
-            // console.log(filename, 'Allow paths like hello.book');
-            return true;
+        applyToAgentModelRequirements(requirements, content) {
+            const trimmedContent = content.trim();
+            if (!trimmedContent) {
+                return requirements;
+            }
+            // Add action capability to the system message
+            const actionSection = `Capability: ${trimmedContent}`;
+            return this.appendToSystemMessage(requirements, actionSection, '\n\n');
         }
-        return false;
     }
     /**
-     * TODO: [🍏] Implement for MacOs
+     * Singleton instance of the ACTION commitment definition
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new ActionCommitmentDefinition();
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
      */
 
     /**
-     * Tests if given string is valid URL.
+     * FORMAT commitment definition
      *
-     * Note: Dataurl are considered perfectly valid.
-     * Note: There are two similar functions:
-     * - `isValidUrl` which tests any URL
-     * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
+     * The FORMAT commitment defines the specific output structure and formatting
+     * that the agent should use in its responses. This includes data formats,
+     * response templates, and structural requirements.
      *
-     * @public exported from `@promptbook/utils`
+     * Example usage in agent source:
+     *
+     * ```book
+     * FORMAT Always respond in JSON format with 'status' and 'data' fields
+     * FORMAT Use markdown formatting for all code blocks
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
      */
-    function isValidUrl(url) {
-        if (typeof url !== 'string') {
-            return false;
+    class FormatCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('FORMAT');
         }
-        try {
-            if (url.startsWith('blob:')) {
-                url = url.replace(/^blob:/, '');
-            }
-            const urlObject = new URL(url /* because fail is handled */);
-            if (!['http:', 'https:', 'data:'].includes(urlObject.protocol)) {
-                return false;
+        applyToAgentModelRequirements(requirements, content) {
+            const trimmedContent = content.trim();
+            if (!trimmedContent) {
+                return requirements;
             }
-            return true;
-        }
-        catch (error) {
-            return false;
+            // Add format instructions to the system message
+            const formatSection = `Output Format: ${trimmedContent}`;
+            return this.appendToSystemMessage(requirements, formatSection, '\n\n');
         }
     }
+    /**
+     * Singleton instance of the FORMAT commitment definition
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new FormatCommitmentDefinition();
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
 
     /**
-     * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
+     * Error thrown when a fetch request fails
      *
      * @public exported from `@promptbook/core`
      */
-    class ParseError extends Error {
+    class PromptbookFetchError extends Error {
         constructor(message) {
             super(message);
-            this.name = 'ParseError';
-            Object.setPrototypeOf(this, ParseError.prototype);
+            this.name = 'PromptbookFetchError';
+            Object.setPrototypeOf(this, PromptbookFetchError.prototype);
         }
     }
-    /**
-     * TODO: Maybe split `ParseError` and `ApplyError`
-     */
 
     /**
      * Available remote servers for the Promptbook
@@ -553,76 +675,1480 @@
     }
 
     /**
-     * This error type indicates that the error should not happen and its last check before crashing with some other error
+     * This error type indicates that the error should not happen and its last check before crashing with some other error
+     *
+     * @public exported from `@promptbook/core`
+     */
+    class UnexpectedError extends Error {
+        constructor(message) {
+            super(spaceTrim.spaceTrim((block) => `
+                    ${block(message)}
+
+                    Note: This error should not happen.
+                    It's probably a bug in the pipeline collection
+
+                    Please report issue:
+                    ${block(getErrorReportUrl(new Error(message)).href)}
+
+                    Or contact us on ${ADMIN_EMAIL}
+
+                `));
+            this.name = 'UnexpectedError';
+            Object.setPrototypeOf(this, UnexpectedError.prototype);
+        }
+    }
+
+    /**
+     * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
+     *
+     * @public exported from `@promptbook/core`
+     */
+    class WrappedError extends Error {
+        constructor(whatWasThrown) {
+            const tag = `[🤮]`;
+            console.error(tag, whatWasThrown);
+            super(spaceTrim.spaceTrim(`
+                Non-Error object was thrown
+
+                Note: Look for ${tag} in the console for more details
+                Please report issue on ${ADMIN_EMAIL}
+            `));
+            this.name = 'WrappedError';
+            Object.setPrototypeOf(this, WrappedError.prototype);
+        }
+    }
+
+    /**
+     * Helper used in catch blocks to assert that the error is an instance of `Error`
+     *
+     * @param whatWasThrown Any object that was thrown
+     * @returns Nothing if the error is an instance of `Error`
+     * @throws `WrappedError` or `UnexpectedError` if the error is not standard
+     *
+     * @private within the repository
+     */
+    function assertsError(whatWasThrown) {
+        // Case 1: Handle error which was rethrown as `WrappedError`
+        if (whatWasThrown instanceof WrappedError) {
+            const wrappedError = whatWasThrown;
+            throw wrappedError;
+        }
+        // Case 2: Handle unexpected errors
+        if (whatWasThrown instanceof UnexpectedError) {
+            const unexpectedError = whatWasThrown;
+            throw unexpectedError;
+        }
+        // Case 3: Handle standard errors - keep them up to consumer
+        if (whatWasThrown instanceof Error) {
+            return;
+        }
+        // Case 4: Handle non-standard errors - wrap them into `WrappedError` and throw
+        throw new WrappedError(whatWasThrown);
+    }
+
+    /**
+     * The built-in `fetch' function with a lightweight error handling wrapper as default fetch function used in Promptbook scrapers
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const promptbookFetch = async (urlOrRequest, init) => {
+        try {
+            return await fetch(urlOrRequest, init);
+        }
+        catch (error) {
+            assertsError(error);
+            let url;
+            if (typeof urlOrRequest === 'string') {
+                url = urlOrRequest;
+            }
+            else if (urlOrRequest instanceof Request) {
+                url = urlOrRequest.url;
+            }
+            throw new PromptbookFetchError(spaceTrim__default["default"]((block) => `
+                    Can not fetch "${url}"
+
+                    Fetch error:
+                    ${block(error.message)}
+
+                `));
+        }
+    };
+    /**
+     * TODO: [🧠] Maybe rename because it is not used only for scrapers but also in `$getCompiledBook`
+     */
+
+    /**
+     * Frontend RAG Service that uses backend APIs for processing
+     * This avoids Node.js dependencies in the frontend
+     *
+     * @private - TODO: [🧠] Maybe should be public?
+     */
+    class FrontendRAGService {
+        constructor(config) {
+            this.chunks = [];
+            this.sources = [];
+            this.isInitialized = false;
+            this.config = {
+                maxChunkSize: 1000,
+                chunkOverlap: 200,
+                maxRetrievedChunks: 5,
+                minRelevanceScore: 0.1,
+                ...config,
+            };
+        }
+        /**
+         * Initialize knowledge sources by processing them on the backend
+         */
+        async initializeKnowledgeSources(sources) {
+            if (sources.length === 0) {
+                this.isInitialized = true;
+                return;
+            }
+            try {
+                const response = await promptbookFetch('/api/knowledge/process-sources', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        sources,
+                        config: {
+                            maxChunkSize: this.config.maxChunkSize,
+                            chunkOverlap: this.config.chunkOverlap,
+                        },
+                    }),
+                });
+                if (!response.ok) {
+                    throw new Error(`Failed to process knowledge sources: ${response.status}`);
+                }
+                const result = (await response.json());
+                if (!result.success) {
+                    throw new Error(result.message || 'Failed to process knowledge sources');
+                }
+                this.chunks = result.chunks;
+                this.sources = sources;
+                this.isInitialized = true;
+                console.log(`Initialized RAG service with ${this.chunks.length} chunks from ${sources.length} sources`);
+            }
+            catch (error) {
+                console.error('Failed to initialize knowledge sources:', error);
+                // Don't throw - allow the system to continue without RAG
+                this.isInitialized = true;
+            }
+        }
+        /**
+         * Get relevant context for a user query
+         */
+        async getContextForQuery(query) {
+            if (!this.isInitialized) {
+                console.warn('RAG service not initialized');
+                return '';
+            }
+            if (this.chunks.length === 0) {
+                return '';
+            }
+            try {
+                const response = await promptbookFetch('/api/knowledge/retrieve-context', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        query,
+                        chunks: this.chunks,
+                        config: {
+                            maxRetrievedChunks: this.config.maxRetrievedChunks,
+                            minRelevanceScore: this.config.minRelevanceScore,
+                        },
+                    }),
+                });
+                if (!response.ok) {
+                    console.error(`Failed to retrieve context: ${response.status}`);
+                    return '';
+                }
+                const result = (await response.json());
+                if (!result.success) {
+                    console.error('Context retrieval failed:', result.message);
+                    return '';
+                }
+                return result.context;
+            }
+            catch (error) {
+                console.error('Error retrieving context:', error);
+                return '';
+            }
+        }
+        /**
+         * Get relevant chunks for a query (for debugging/inspection)
+         */
+        async getRelevantChunks(query) {
+            if (!this.isInitialized || this.chunks.length === 0) {
+                return [];
+            }
+            try {
+                const response = await promptbookFetch('/api/knowledge/retrieve-context', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        query,
+                        chunks: this.chunks,
+                        config: {
+                            maxRetrievedChunks: this.config.maxRetrievedChunks,
+                            minRelevanceScore: this.config.minRelevanceScore,
+                        },
+                    }),
+                });
+                if (!response.ok) {
+                    return [];
+                }
+                const result = (await response.json());
+                return result.success ? result.relevantChunks : [];
+            }
+            catch (error) {
+                console.error('Error retrieving relevant chunks:', error);
+                return [];
+            }
+        }
+        /**
+         * Get knowledge base statistics
+         */
+        getStats() {
+            return {
+                sources: this.sources.length,
+                chunks: this.chunks.length,
+                isInitialized: this.isInitialized,
+            };
+        }
+        /**
+         * Check if the service is ready to use
+         */
+        isReady() {
+            return this.isInitialized;
+        }
+        /**
+         * Clear all knowledge sources
+         */
+        clearKnowledgeBase() {
+            this.chunks = [];
+            this.sources = [];
+            this.isInitialized = false;
+        }
+        /**
+         * Add a single knowledge source (for incremental updates)
+         */
+        async addKnowledgeSource(url) {
+            if (this.sources.includes(url)) {
+                console.log(`Knowledge source already exists: ${url}`);
+                return;
+            }
+            try {
+                const response = await promptbookFetch('/api/knowledge/process-sources', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        sources: [url],
+                        config: {
+                            maxChunkSize: this.config.maxChunkSize,
+                            chunkOverlap: this.config.chunkOverlap,
+                        },
+                    }),
+                });
+                if (!response.ok) {
+                    throw new Error(`Failed to process knowledge source: ${response.status}`);
+                }
+                const result = (await response.json());
+                if (!result.success) {
+                    throw new Error(result.message || 'Failed to process knowledge source');
+                }
+                // Add new chunks to existing ones
+                this.chunks.push(...result.chunks);
+                this.sources.push(url);
+                console.log(`Added knowledge source: ${url} (${result.chunks.length} chunks)`);
+            }
+            catch (error) {
+                console.error(`Failed to add knowledge source ${url}:`, error);
+                throw error;
+            }
+        }
+    }
+
+    /**
+     * KNOWLEDGE commitment definition
+     *
+     * The KNOWLEDGE commitment adds specific knowledge, facts, or context to the agent
+     * using RAG (Retrieval-Augmented Generation) approach for external sources.
+     *
+     * Supports both direct text knowledge and external sources like PDFs.
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * KNOWLEDGE The company was founded in 2020 and specializes in AI-powered solutions
+     * KNOWLEDGE https://example.com/company-handbook.pdf
+     * KNOWLEDGE https://example.com/product-documentation.pdf
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class KnowledgeCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('KNOWLEDGE');
+            this.ragService = new FrontendRAGService();
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            var _a;
+            const trimmedContent = content.trim();
+            if (!trimmedContent) {
+                return requirements;
+            }
+            // Check if content is a URL (external knowledge source)
+            if (this.isUrl(trimmedContent)) {
+                // Store the URL for later async processing
+                const updatedRequirements = {
+                    ...requirements,
+                    metadata: {
+                        ...requirements.metadata,
+                        ragService: this.ragService,
+                        knowledgeSources: [
+                            ...(((_a = requirements.metadata) === null || _a === void 0 ? void 0 : _a.knowledgeSources) || []),
+                            trimmedContent,
+                        ],
+                    },
+                };
+                // Add placeholder information about knowledge sources to system message
+                const knowledgeInfo = `Knowledge Source URL: ${trimmedContent} (will be processed for retrieval during chat)`;
+                return this.appendToSystemMessage(updatedRequirements, knowledgeInfo, '\n\n');
+            }
+            else {
+                // Direct text knowledge - add to system message
+                const knowledgeSection = `Knowledge: ${trimmedContent}`;
+                return this.appendToSystemMessage(requirements, knowledgeSection, '\n\n');
+            }
+        }
+        /**
+         * Check if content is a URL
+         */
+        isUrl(content) {
+            try {
+                new URL(content);
+                return true;
+            }
+            catch (_a) {
+                return false;
+            }
+        }
+        /**
+         * Get RAG service instance for retrieving context during chat
+         */
+        getRagService() {
+            return this.ragService;
+        }
+    }
+    /**
+     * Singleton instance of the KNOWLEDGE commitment definition
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new KnowledgeCommitmentDefinition();
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
+    /**
+     * META IMAGE commitment definition
+     *
+     * The META IMAGE commitment sets the agent's avatar/profile image URL.
+     * This commitment is special because it doesn't affect the system message,
+     * but is handled separately in the parsing logic.
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * META IMAGE https://example.com/avatar.jpg
+     * META IMAGE /assets/agent-avatar.png
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class MetaImageCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('META IMAGE');
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            // META IMAGE doesn't modify the system message or model requirements
+            // It's handled separately in the parsing logic for profile image extraction
+            // This method exists for consistency with the CommitmentDefinition interface
+            return requirements;
+        }
+        /**
+         * Extracts the profile image URL from the content
+         * This is used by the parsing logic
+         */
+        extractProfileImageUrl(content) {
+            const trimmedContent = content.trim();
+            return trimmedContent || null;
+        }
+    }
+    /**
+     * Singleton instance of the META IMAGE commitment definition
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new MetaImageCommitmentDefinition();
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
+    /**
+     * META LINK commitment definition
+     *
+     * The `META LINK` commitment represents the link to the person from whom the agent is created.
+     * This commitment is special because it doesn't affect the system message,
+     * but is handled separately in the parsing logic for profile display.
+     *
+     * Example usage in agent source:
+     *
+     * ```
+     * META LINK https://twitter.com/username
+     * META LINK https://linkedin.com/in/profile
+     * META LINK https://github.com/username
+     * ```
+     *
+     * Multiple `META LINK` commitments can be used when there are multiple sources:
+     *
+     * ```book
+     * META LINK https://twitter.com/username
+     * META LINK https://linkedin.com/in/profile
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class MetaLinkCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('META LINK');
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            // META LINK doesn't modify the system message or model requirements
+            // It's handled separately in the parsing logic for profile link extraction
+            // This method exists for consistency with the CommitmentDefinition interface
+            return requirements;
+        }
+        /**
+         * Extracts the profile link URL from the content
+         * This is used by the parsing logic
+         */
+        extractProfileLinkUrl(content) {
+            const trimmedContent = content.trim();
+            return trimmedContent || null;
+        }
+        /**
+         * Validates if the provided content is a valid URL
+         */
+        isValidUrl(content) {
+            try {
+                new URL(content.trim());
+                return true;
+            }
+            catch (_a) {
+                return false;
+            }
+        }
+    }
+    /**
+     * Singleton instance of the META LINK commitment definition
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new MetaLinkCommitmentDefinition();
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
+    /**
+     * MODEL commitment definition
+     *
+     * The MODEL commitment specifies which AI model to use and can also set
+     * model-specific parameters like temperature, topP, and topK.
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * MODEL gpt-4
+     * MODEL claude-3-opus temperature=0.3
+     * MODEL gpt-3.5-turbo temperature=0.8 topP=0.9
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class ModelCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('MODEL');
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            const trimmedContent = content.trim();
+            if (!trimmedContent) {
+                return requirements;
+            }
+            // Parse the model specification
+            const parts = trimmedContent.split(/\s+/);
+            const modelName = parts[0];
+            if (!modelName) {
+                return requirements;
+            }
+            // Start with the model name
+            const updatedRequirements = {
+                ...requirements,
+                modelName,
+            };
+            // Parse additional parameters
+            const result = { ...updatedRequirements };
+            for (let i = 1; i < parts.length; i++) {
+                const param = parts[i];
+                if (param && param.includes('=')) {
+                    const [key, value] = param.split('=');
+                    if (key && value) {
+                        const numValue = parseFloat(value);
+                        if (!isNaN(numValue)) {
+                            switch (key.toLowerCase()) {
+                                case 'temperature':
+                                    result.temperature = numValue;
+                                    break;
+                                case 'topp':
+                                case 'top_p':
+                                    result.topP = numValue;
+                                    break;
+                                case 'topk':
+                                case 'top_k':
+                                    result.topK = Math.round(numValue);
+                                    break;
+                            }
+                        }
+                    }
+                }
+            }
+            return result;
+        }
+    }
+    /**
+     * Singleton instance of the MODEL commitment definition
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new ModelCommitmentDefinition();
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
+    /**
+     * NOTE commitment definition
+     *
+     * The NOTE commitment is used to add comments to the agent source without making any changes
+     * to the system message or agent model requirements. It serves as a documentation mechanism
+     * for developers to add explanatory comments, reminders, or annotations directly in the agent source.
+     *
+     * Key features:
+     * - Makes no changes to the system message
+     * - Makes no changes to agent model requirements
+     * - Content is preserved in metadata.NOTE for debugging and inspection
+     * - Multiple NOTE commitments are aggregated together
+     * - Comments (# NOTE) are removed from the final system message
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * NOTE This agent was designed for customer support scenarios
+     * NOTE Remember to update the knowledge base monthly
+     * NOTE Performance optimized for quick response times
+     * ```
+     *
+     * The above notes will be stored in metadata but won't affect the agent's behavior.
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class NoteCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('NOTE');
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            var _a;
+            // The NOTE commitment makes no changes to the system message or model requirements
+            // It only stores the note content in metadata for documentation purposes
+            const trimmedContent = content.trim();
+            if (!trimmedContent) {
+                return requirements;
+            }
+            // Get existing note content from metadata
+            const existingNoteContent = ((_a = requirements.metadata) === null || _a === void 0 ? void 0 : _a.NOTE) || '';
+            // Merge the new content with existing note content
+            // When multiple NOTE commitments exist, they are aggregated together
+            const mergedNoteContent = existingNoteContent ? `${existingNoteContent}\n${trimmedContent}` : trimmedContent;
+            // Store the merged note content in metadata for debugging and inspection
+            const updatedMetadata = {
+                ...requirements.metadata,
+                NOTE: mergedNoteContent,
+            };
+            // Return requirements with updated metadata but no changes to system message
+            return {
+                ...requirements,
+                metadata: updatedMetadata,
+            };
+        }
+    }
+    /**
+     * Singleton instance of the NOTE commitment definition
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new NoteCommitmentDefinition();
+    /**
+     * [💞] Ignore a discrepancy between file name and entity name
+     */
+
+    /**
+     * PERSONA commitment definition
+     *
+     * The PERSONA commitment modifies the agent's personality and character in the system message.
+     * It defines who the agent is, their background, expertise, and personality traits.
+     *
+     * Key features:
+     * - Multiple PERSONA commitments are automatically merged into one
+     * - Content is placed at the beginning of the system message
+     * - Original content with comments is preserved in metadata.PERSONA
+     * - Comments (# PERSONA) are removed from the final system message
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * PERSONA You are a helpful programming assistant with expertise in TypeScript and React
+     * PERSONA You have deep knowledge of modern web development practices
+     * ```
+     *
+     * The above will be merged into a single persona section at the beginning of the system message.
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class PersonaCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('PERSONA');
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            var _a, _b;
+            // The PERSONA commitment aggregates all persona content and places it at the beginning
+            const trimmedContent = content.trim();
+            if (!trimmedContent) {
+                return requirements;
+            }
+            // Get existing persona content from metadata
+            const existingPersonaContent = ((_a = requirements.metadata) === null || _a === void 0 ? void 0 : _a.PERSONA) || '';
+            // Merge the new content with existing persona content
+            // When multiple PERSONA commitments exist, they are merged into one
+            const mergedPersonaContent = existingPersonaContent
+                ? `${existingPersonaContent}\n${trimmedContent}`
+                : trimmedContent;
+            // Store the merged persona content in metadata for debugging and inspection
+            const updatedMetadata = {
+                ...requirements.metadata,
+                PERSONA: mergedPersonaContent,
+            };
+            // Get the agent name from metadata (which should contain the first line of agent source)
+            // If not available, extract from current system message as fallback
+            let agentName = (_b = requirements.metadata) === null || _b === void 0 ? void 0 : _b.agentName;
+            if (!agentName) {
+                // Fallback: extract from current system message
+                const currentMessage = requirements.systemMessage.trim();
+                const basicFormatMatch = currentMessage.match(/^You are (.+)$/);
+                if (basicFormatMatch && basicFormatMatch[1]) {
+                    agentName = basicFormatMatch[1];
+                }
+                else {
+                    agentName = 'AI Agent'; // Final fallback
+                }
+            }
+            // Remove any existing persona content from the system message
+            // (this handles the case where we're processing multiple PERSONA commitments)
+            const currentMessage = requirements.systemMessage.trim();
+            let cleanedMessage = currentMessage;
+            // Check if current message starts with persona content or is just the basic format
+            const basicFormatRegex = /^You are .+$/;
+            const isBasicFormat = basicFormatRegex.test(currentMessage) && !currentMessage.includes('\n');
+            if (isBasicFormat) {
+                // Replace the basic format entirely
+                cleanedMessage = '';
+            }
+            else if (currentMessage.startsWith('# PERSONA')) {
+                // Remove existing persona section by finding where it ends
+                const lines = currentMessage.split('\n');
+                let personaEndIndex = lines.length;
+                // Find the end of the PERSONA section (next comment or end of message)
+                for (let i = 1; i < lines.length; i++) {
+                    const line = lines[i].trim();
+                    if (line.startsWith('#') && !line.startsWith('# PERSONA')) {
+                        personaEndIndex = i;
+                        break;
+                    }
+                }
+                // Keep everything after the PERSONA section
+                cleanedMessage = lines.slice(personaEndIndex).join('\n').trim();
+            }
+            // Create new system message with persona at the beginning
+            // Format: "You are {agentName}\n{personaContent}"
+            // The # PERSONA comment will be removed later by removeCommentsFromSystemMessage
+            const personaSection = `# PERSONA\nYou are ${agentName}\n${mergedPersonaContent}`; // <- TODO: Use spaceTrim
+            const newSystemMessage = cleanedMessage ? `${personaSection}\n\n${cleanedMessage}` : personaSection;
+            return {
+                ...requirements,
+                systemMessage: newSystemMessage,
+                metadata: updatedMetadata,
+            };
+        }
+    }
+    /**
+     * Singleton instance of the PERSONA commitment definition
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new PersonaCommitmentDefinition();
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
+    /**
+     * RULE commitment definition
+     *
+     * The RULE/RULES commitment adds behavioral constraints and guidelines that the agent must follow.
+     * These are specific instructions about what the agent should or shouldn't do.
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * RULE Always ask for clarification if the user's request is ambiguous
+     * RULES Never provide medical advice, always refer to healthcare professionals
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class RuleCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor(type = 'RULE') {
+            super(type);
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            const trimmedContent = content.trim();
+            if (!trimmedContent) {
+                return requirements;
+            }
+            // Add rule to the system message
+            const ruleSection = `Rule: ${trimmedContent}`;
+            return this.appendToSystemMessage(requirements, ruleSection, '\n\n');
+        }
+    }
+    /**
+     * Singleton instances of the RULE commitment definitions
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new RuleCommitmentDefinition('RULE');
+    /**
+     * Singleton instances of the RULE commitment definitions
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new RuleCommitmentDefinition('RULES');
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
+    /**
+     * SAMPLE commitment definition
+     *
+     * The SAMPLE/EXAMPLE commitment provides examples of how the agent should respond
+     * or behave in certain situations. These examples help guide the agent's responses.
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * SAMPLE When asked about pricing, respond: "Our basic plan starts at $10/month..."
+     * EXAMPLE For code questions, always include working code snippets
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class SampleCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor(type = 'SAMPLE') {
+            super(type);
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            const trimmedContent = content.trim();
+            if (!trimmedContent) {
+                return requirements;
+            }
+            // Add example to the system message
+            const exampleSection = `Example: ${trimmedContent}`;
+            return this.appendToSystemMessage(requirements, exampleSection, '\n\n');
+        }
+    }
+    /**
+     * Singleton instances of the SAMPLE commitment definitions
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new SampleCommitmentDefinition('SAMPLE');
+    /**
+     * Singleton instances of the SAMPLE commitment definitions
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new SampleCommitmentDefinition('EXAMPLE');
+    /**
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
+    /**
+     * STYLE commitment definition
+     *
+     * The STYLE commitment defines how the agent should format and present its responses.
+     * This includes tone, writing style, formatting preferences, and communication patterns.
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * STYLE Write in a professional but friendly tone, use bullet points for lists
+     * STYLE Always provide code examples when explaining programming concepts
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class StyleCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('STYLE');
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            const trimmedContent = content.trim();
+            if (!trimmedContent) {
+                return requirements;
+            }
+            // Add style instructions to the system message
+            const styleSection = `Style: ${trimmedContent}`;
+            return this.appendToSystemMessage(requirements, styleSection, '\n\n');
+        }
+    }
+    /**
+     * Singleton instance of the STYLE commitment definition
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    new StyleCommitmentDefinition();
+    /**
+     * [💞] Ignore a discrepancy between file name and entity name
+     */
+
+    /**
+     * Placeholder commitment definition for commitments that are not yet implemented
+     *
+     * This commitment simply adds its content 1:1 into the system message,
+     * preserving the original behavior until proper implementation is added.
+     *
+     * @public exported from `@promptbook/core`
+     */
+    class NotYetImplementedCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor(type) {
+            super(type);
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            const trimmedContent = content.trim();
+            if (!trimmedContent) {
+                return requirements;
+            }
+            // Add the commitment content 1:1 to the system message
+            const commitmentLine = `${this.type} ${trimmedContent}`;
+            return this.appendToSystemMessage(requirements, commitmentLine, '\n\n');
+        }
+    }
+
+    // Import all commitment definition classes
+    /**
+     * Registry of all available commitment definitions
+     * This array contains instances of all commitment definitions
+     * This is the single source of truth for all commitments in the system
+     *
+     * @private Use functions to access commitments instead of this array directly
+     */
+    const COMMITMENT_REGISTRY = [
+        // Fully implemented commitments
+        new PersonaCommitmentDefinition(),
+        new KnowledgeCommitmentDefinition(),
+        new StyleCommitmentDefinition(),
+        new RuleCommitmentDefinition('RULE'),
+        new RuleCommitmentDefinition('RULES'),
+        new SampleCommitmentDefinition('SAMPLE'),
+        new SampleCommitmentDefinition('EXAMPLE'),
+        new FormatCommitmentDefinition(),
+        new ModelCommitmentDefinition(),
+        new ActionCommitmentDefinition(),
+        new MetaImageCommitmentDefinition(),
+        new MetaLinkCommitmentDefinition(),
+        new NoteCommitmentDefinition(),
+        // Not yet implemented commitments (using placeholder)
+        new NotYetImplementedCommitmentDefinition('EXPECT'),
+        new NotYetImplementedCommitmentDefinition('SCENARIO'),
+        new NotYetImplementedCommitmentDefinition('SCENARIOS'),
+        new NotYetImplementedCommitmentDefinition('BEHAVIOUR'),
+        new NotYetImplementedCommitmentDefinition('BEHAVIOURS'),
+        new NotYetImplementedCommitmentDefinition('AVOID'),
+        new NotYetImplementedCommitmentDefinition('AVOIDANCE'),
+        new NotYetImplementedCommitmentDefinition('GOAL'),
+        new NotYetImplementedCommitmentDefinition('GOALS'),
+        new NotYetImplementedCommitmentDefinition('CONTEXT'),
+    ];
+    /**
+     * Gets a commitment definition by its type
+     * @param type The commitment type to look up
+     * @returns The commitment definition or null if not found
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function getCommitmentDefinition(type) {
+        return COMMITMENT_REGISTRY.find((commitmentDefinition) => commitmentDefinition.type === type) || null;
+    }
+    /**
+     * Gets all available commitment definitions
+     * @returns Array of all commitment definitions
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function getAllCommitmentDefinitions() {
+        return $deepFreeze([...COMMITMENT_REGISTRY]);
+    }
+    /**
+     * Gets all available commitment types
+     * @returns Array of all commitment types
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function getAllCommitmentTypes() {
+        return $deepFreeze(COMMITMENT_REGISTRY.map((commitmentDefinition) => commitmentDefinition.type));
+    }
+    /**
+     * Checks if a commitment type is supported
+     * @param type The commitment type to check
+     * @returns True if the commitment type is supported
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function isCommitmentSupported(type) {
+        return COMMITMENT_REGISTRY.some((commitmentDefinition) => commitmentDefinition.type === type);
+    }
+    /**
+     * TODO: !!!! Maybe create through standardized $register
+     * Note: [💞] Ignore a discrepancy between file name and entity name
+     */
+
+    /**
+     * Parses agent source using the new commitment system with multiline support
+     * This function replaces the hardcoded commitment parsing in the original parseAgentSource
+     *
+     * @private
+     */
+    function parseAgentSourceWithCommitments(agentSource) {
+        var _a, _b, _c;
+        if (!agentSource || !agentSource.trim()) {
+            return {
+                agentName: null,
+                commitments: [],
+                nonCommitmentLines: [],
+            };
+        }
+        const lines = agentSource.split('\n');
+        const agentName = (((_a = lines[0]) === null || _a === void 0 ? void 0 : _a.trim()) || null);
+        const commitments = [];
+        const nonCommitmentLines = [];
+        // Always add the first line (agent name) to non-commitment lines
+        if (lines[0] !== undefined) {
+            nonCommitmentLines.push(lines[0]);
+        }
+        // Parse commitments with multiline support
+        let currentCommitment = null;
+        // Process lines starting from the second line (skip agent name)
+        for (let i = 1; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === undefined) {
+                continue;
+            }
+            // Check if this line starts a new commitment
+            let foundNewCommitment = false;
+            for (const definition of COMMITMENT_REGISTRY) {
+                const typeRegex = definition.createTypeRegex();
+                const match = typeRegex.exec(line.trim());
+                if (match && ((_b = match.groups) === null || _b === void 0 ? void 0 : _b.type)) {
+                    // Save the previous commitment if it exists
+                    if (currentCommitment) {
+                        const fullContent = currentCommitment.contentLines.join('\n');
+                        commitments.push({
+                            type: currentCommitment.type,
+                            content: spaceTrim.spaceTrim(fullContent),
+                            originalLine: currentCommitment.originalStartLine,
+                            lineNumber: currentCommitment.startLineNumber,
+                        });
+                    }
+                    // Extract the initial content from the commitment line
+                    const fullRegex = definition.createRegex();
+                    const fullMatch = fullRegex.exec(line.trim());
+                    const initialContent = ((_c = fullMatch === null || fullMatch === void 0 ? void 0 : fullMatch.groups) === null || _c === void 0 ? void 0 : _c.contents) || '';
+                    // Start a new commitment
+                    currentCommitment = {
+                        type: definition.type,
+                        startLineNumber: i + 1,
+                        originalStartLine: line,
+                        contentLines: initialContent ? [initialContent] : [],
+                    };
+                    foundNewCommitment = true;
+                    break;
+                }
+            }
+            if (!foundNewCommitment) {
+                if (currentCommitment) {
+                    // This line belongs to the current commitment
+                    currentCommitment.contentLines.push(line);
+                }
+                else {
+                    // This line is not part of any commitment
+                    nonCommitmentLines.push(line);
+                }
+            }
+        }
+        // Don't forget to save the last commitment if it exists
+        if (currentCommitment) {
+            const fullContent = currentCommitment.contentLines.join('\n');
+            commitments.push({
+                type: currentCommitment.type,
+                content: spaceTrim.spaceTrim(fullContent),
+                originalLine: currentCommitment.originalStartLine,
+                lineNumber: currentCommitment.startLineNumber,
+            });
+        }
+        return {
+            agentName,
+            commitments,
+            nonCommitmentLines,
+        };
+    }
+    /**
+     * Extracts basic information from agent source using the new commitment system
+     * This maintains compatibility with the original parseAgentSource interface
+     *
+     * @private
+     */
+    function parseAgentSourceBasicInfo(agentSource) {
+        const parseResult = parseAgentSourceWithCommitments(agentSource);
+        // Find PERSONA and META IMAGE commitments
+        let personaDescription = null;
+        let profileImageUrl;
+        for (const commitment of parseResult.commitments) {
+            if (commitment.type === 'PERSONA' && !personaDescription) {
+                personaDescription = commitment.content;
+            }
+            else if (commitment.type === 'META IMAGE' && !profileImageUrl) {
+                profileImageUrl = commitment.content;
+            }
+        }
+        // Generate gravatar fallback if no profile image specified
+        if (!profileImageUrl) {
+            profileImageUrl = generateGravatarUrl(parseResult.agentName);
+        }
+        return {
+            agentName: parseResult.agentName,
+            personaDescription,
+            profileImageUrl,
+        };
+    }
+
+    /**
+     * Parses agent source string into its components
+     */
+    // Cache for parsed agent sources to prevent repeated parsing
+    const parsedAgentSourceCache = new Map();
+    /**
+     * Parses basic information from agent source
+     *
+     * There are 2 similar functions:
+     * - `parseAgentSource` which is a lightweight parser for agent source, it parses basic information and its purpose is to be quick and synchronous. The commitments there are hardcoded.
+     * - `createAgentModelRequirements` which is an asynchronous function that creates model requirements it applies each commitment one by one and works asynchronously.
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function parseAgentSource(agentSource) {
+        // Check if we already parsed this agent source
+        if (parsedAgentSourceCache.has(agentSource)) {
+            return parsedAgentSourceCache.get(agentSource);
+        }
+        // Use the new commitment-based parsing system
+        const result = parseAgentSourceBasicInfo(agentSource);
+        // Cache the result
+        parsedAgentSourceCache.set(agentSource, result);
+        return result;
+    }
+
+    /**
+     * Type guard to check if a string is a valid agent source
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function isValidBook(value) {
+        // Basic validation - agent source should have at least a name (first line)
+        return typeof value === 'string' /* && value.trim().length > 0 */;
+    }
+    /**
+     * Validates and converts a string to agent source branded type
+     * This function should be used when you have a string that you know represents agent source
+     * but need to convert it to the branded type for type safety
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function validateBook(source) {
+        if (!isValidBook(source)) {
+            throw new Error('Invalid agent source: must be a string');
+        }
+        return source;
+    }
+    /**
+     * Default book
+     *
+     * @public exported from `@promptbook/core`
+     */
+    const DEFAULT_BOOK = validateBook(spaceTrim__default["default"](`
+        AI Avatar
+
+        PERSONA A friendly AI assistant that helps you with your tasks
+    `));
+
+    /**
+     * Creates an empty/basic agent model requirements object
+     * This serves as the starting point for the reduce-like pattern
+     * where each commitment applies its changes to build the final requirements
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function createEmptyAgentModelRequirements() {
+        return {
+            systemMessage: '',
+            modelName: '!!!!DEFAULT_MODEL_ID',
+            temperature: 0.7,
+            topP: 0.9,
+            topK: 50,
+        };
+    }
+    /**
+     * Creates a basic agent model requirements with just the agent name
+     * This is used when we have an agent name but no commitments
+     *
+     * @public exported from `@promptbook/core`
+     */
+    function createBasicAgentModelRequirements(agentName) {
+        const empty = createEmptyAgentModelRequirements();
+        return {
+            ...empty,
+            systemMessage: `You are ${agentName || 'AI Agent'}`,
+        };
+    }
+    /**
+     * TODO: !!!! Deduplicate model requirements
+     */
+
+    /**
+     * Removes comment lines (lines starting with #) from a system message
+     * This is used to clean up the final system message before sending it to the AI model
+     * while preserving the original content with comments in metadata
+     *
+     * @param systemMessage The system message that may contain comment lines
+     * @returns The system message with comment lines removed
+     *
+     * @private - TODO: [🧠] Maybe should be public?
+     */
+    function removeCommentsFromSystemMessage(systemMessage) {
+        if (!systemMessage) {
+            return systemMessage;
+        }
+        const lines = systemMessage.split('\n');
+        const filteredLines = lines.filter((line) => {
+            const trimmedLine = line.trim();
+            // Remove lines that start with # (comments)
+            return !trimmedLine.startsWith('#');
+        });
+        return filteredLines.join('\n').trim();
+    }
+
+    /**
+     * Creates agent model requirements using the new commitment system
+     * This function uses a reduce-like pattern where each commitment applies its changes
+     * to build the final requirements starting from a basic empty model
+     *
+     * @private
+     */
+    async function createAgentModelRequirementsWithCommitments(agentSource, modelName) {
+        // Parse the agent source to extract commitments
+        const parseResult = parseAgentSourceWithCommitments(agentSource);
+        // Start with basic agent model requirements
+        let requirements = createBasicAgentModelRequirements(parseResult.agentName);
+        // Store the agent name in metadata so commitments can access it
+        requirements = {
+            ...requirements,
+            metadata: {
+                ...requirements.metadata,
+                agentName: parseResult.agentName,
+            },
+        };
+        // Override model name if provided
+        if (modelName) {
+            requirements = {
+                ...requirements,
+                modelName,
+            };
+        }
+        // Apply each commitment in order using reduce-like pattern
+        for (const commitment of parseResult.commitments) {
+            const definition = getCommitmentDefinition(commitment.type);
+            if (definition) {
+                try {
+                    requirements = definition.applyToAgentModelRequirements(requirements, commitment.content);
+                }
+                catch (error) {
+                    console.warn(`Failed to apply commitment ${commitment.type}:`, error);
+                    // Continue with other commitments even if one fails
+                }
+            }
+        }
+        // Handle MCP servers (extract from original agent source)
+        const mcpServers = extractMcpServers(agentSource);
+        if (mcpServers.length > 0) {
+            requirements = {
+                ...requirements,
+                mcpServers,
+            };
+        }
+        // Add non-commitment lines to system message if they exist
+        const nonCommitmentContent = parseResult.nonCommitmentLines
+            .filter((line, index) => index > 0 || !parseResult.agentName) // Skip first line if it's the agent name
+            .filter((line) => line.trim()) // Remove empty lines
+            .join('\n')
+            .trim();
+        if (nonCommitmentContent) {
+            requirements = {
+                ...requirements,
+                systemMessage: requirements.systemMessage + '\n\n' + nonCommitmentContent,
+            };
+        }
+        // Remove comment lines (lines starting with #) from the final system message
+        // while preserving the original content with comments in metadata
+        const cleanedSystemMessage = removeCommentsFromSystemMessage(requirements.systemMessage);
+        return {
+            ...requirements,
+            systemMessage: cleanedSystemMessage,
+        };
+    }
+    /**
+     * Cache for expensive createAgentModelRequirementsWithCommitments calls
+     * @private
+     */
+    const modelRequirementsCache = new Map();
+    /**
+     * @private - TODO: Maybe should be public
+     */
+    const CACHE_SIZE_LIMIT = 100;
+    /**
+     * Cached version of createAgentModelRequirementsWithCommitments
+     * This maintains the same caching behavior as the original function
+     *
+     * @private
+     */
+    async function createAgentModelRequirementsWithCommitmentsCached(agentSource, modelName) {
+        // Create cache key
+        const cacheKey = `${agentSource}|${modelName || 'default'}`;
+        // Check cache first
+        if (modelRequirementsCache.has(cacheKey)) {
+            return modelRequirementsCache.get(cacheKey);
+        }
+        // Limit cache size to prevent memory leaks
+        if (modelRequirementsCache.size >= CACHE_SIZE_LIMIT) {
+            const firstKey = modelRequirementsCache.keys().next().value;
+            if (firstKey) {
+                modelRequirementsCache.delete(firstKey);
+            }
+        }
+        // Create requirements
+        const requirements = await createAgentModelRequirementsWithCommitments(agentSource, modelName);
+        // Cache the result
+        modelRequirementsCache.set(cacheKey, requirements);
+        return requirements;
+    }
+
+    // TODO: Remove or use:
+    //const CACHE_SIZE_LIMIT = 100; // Prevent memory leaks by limiting cache size
+    /**
+     * Creates model requirements for an agent based on its source
+     * Results are cached to improve performance for repeated calls with the same agentSource and modelName
+     *
+     * There are 2 similar functions:
+     * - `parseAgentSource` which is a lightweight parser for agent source, it parses basic information and its purpose is to be quick and synchronous. The commitments there are hardcoded.
+     * - `createAgentModelRequirements` which is an asynchronous function that creates model requirements it applies each commitment one by one and works asynchronously.
      *
      * @public exported from `@promptbook/core`
      */
-    class UnexpectedError extends Error {
-        constructor(message) {
-            super(spaceTrim.spaceTrim((block) => `
-                    ${block(message)}
-
-                    Note: This error should not happen.
-                    It's probably a bug in the pipeline collection
-
-                    Please report issue:
-                    ${block(getErrorReportUrl(new Error(message)).href)}
-
-                    Or contact us on ${ADMIN_EMAIL}
-
-                `));
-            this.name = 'UnexpectedError';
-            Object.setPrototypeOf(this, UnexpectedError.prototype);
+    async function createAgentModelRequirements(agentSource, modelName = '!!!!DEFAULT_MODEL_ID') {
+        // Use the new commitment-based system
+        return createAgentModelRequirementsWithCommitmentsCached(agentSource, modelName);
+    }
+    /**
+     * Extracts MCP servers from agent source
+     *
+     * @param agentSource The agent source string that may contain MCP lines
+     * @returns Array of MCP server identifiers
+     *
+     * @private TODO: [🧠] Maybe should be public
+     */
+    function extractMcpServers(agentSource) {
+        if (!agentSource) {
+            return [];
         }
+        const lines = agentSource.split('\n');
+        const mcpRegex = /^\s*MCP\s+(.+)$/i;
+        const mcpServers = [];
+        // Look for MCP lines
+        for (const line of lines) {
+            const match = line.match(mcpRegex);
+            if (match && match[1]) {
+                mcpServers.push(match[1].trim());
+            }
+        }
+        return mcpServers;
     }
 
     /**
-     * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
+     * Converts PipelineCollection to serialized JSON
+     *
+     * Note: Functions `collectionToJson` and `createCollectionFromJson` are complementary
      *
      * @public exported from `@promptbook/core`
      */
-    class WrappedError extends Error {
-        constructor(whatWasThrown) {
-            const tag = `[🤮]`;
-            console.error(tag, whatWasThrown);
-            super(spaceTrim.spaceTrim(`
-                Non-Error object was thrown
+    async function collectionToJson(collection) {
+        const pipelineUrls = await collection.listPipelines();
+        const promptbooks = await Promise.all(pipelineUrls.map((url) => collection.getPipelineByUrl(url)));
+        return promptbooks;
+    }
+    /**
+     * TODO: [🧠] Maybe clear `sourceFile` or clear when exposing through API or remote server
+     */
 
-                Note: Look for ${tag} in the console for more details
-                Please report issue on ${ADMIN_EMAIL}
-            `));
-            this.name = 'WrappedError';
-            Object.setPrototypeOf(this, WrappedError.prototype);
+    /**
+     * Checks if value is valid email
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    function isValidEmail(email) {
+        if (typeof email !== 'string') {
+            return false;
+        }
+        if (email.split('\n').length > 1) {
+            return false;
         }
+        return /^.+@.+\..+$/.test(email);
     }
 
     /**
-     * Helper used in catch blocks to assert that the error is an instance of `Error`
+     * Tests if given string is valid URL.
      *
-     * @param whatWasThrown Any object that was thrown
-     * @returns Nothing if the error is an instance of `Error`
-     * @throws `WrappedError` or `UnexpectedError` if the error is not standard
+     * Note: This does not check if the file exists only if the path is valid
+     * @public exported from `@promptbook/utils`
+     */
+    function isValidFilePath(filename) {
+        if (typeof filename !== 'string') {
+            return false;
+        }
+        if (filename.split('\n').length > 1) {
+            return false;
+        }
+        if (filename.split(' ').length >
+            5 /* <- TODO: [🧠][🈷] Make some better non-arbitrary way how to distinct filenames from informational texts */) {
+            return false;
+        }
+        const filenameSlashes = filename.split('\\').join('/');
+        // Absolute Unix path: /hello.txt
+        if (/^(\/)/i.test(filenameSlashes)) {
+            // console.log(filename, 'Absolute Unix path: /hello.txt');
+            return true;
+        }
+        // Absolute Windows path: /hello.txt
+        if (/^([A-Z]{1,2}:\/?)\//i.test(filenameSlashes)) {
+            // console.log(filename, 'Absolute Windows path: /hello.txt');
+            return true;
+        }
+        // Relative path: ./hello.txt
+        if (/^(\.\.?\/)+/i.test(filenameSlashes)) {
+            // console.log(filename, 'Relative path: ./hello.txt');
+            return true;
+        }
+        // Allow paths like foo/hello
+        if (/^[^/]+\/[^/]+/i.test(filenameSlashes)) {
+            // console.log(filename, 'Allow paths like foo/hello');
+            return true;
+        }
+        // Allow paths like hello.book
+        if (/^[^/]+\.[^/]+$/i.test(filenameSlashes)) {
+            // console.log(filename, 'Allow paths like hello.book');
+            return true;
+        }
+        return false;
+    }
+    /**
+     * TODO: [🍏] Implement for MacOs
+     */
+
+    /**
+     * Tests if given string is valid URL.
      *
-     * @private within the repository
+     * Note: Dataurl are considered perfectly valid.
+     * Note: There are two similar functions:
+     * - `isValidUrl` which tests any URL
+     * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
+     *
+     * @public exported from `@promptbook/utils`
      */
-    function assertsError(whatWasThrown) {
-        // Case 1: Handle error which was rethrown as `WrappedError`
-        if (whatWasThrown instanceof WrappedError) {
-            const wrappedError = whatWasThrown;
-            throw wrappedError;
+    function isValidUrl(url) {
+        if (typeof url !== 'string') {
+            return false;
         }
-        // Case 2: Handle unexpected errors
-        if (whatWasThrown instanceof UnexpectedError) {
-            const unexpectedError = whatWasThrown;
-            throw unexpectedError;
+        try {
+            if (url.startsWith('blob:')) {
+                url = url.replace(/^blob:/, '');
+            }
+            const urlObject = new URL(url /* because fail is handled */);
+            if (!['http:', 'https:', 'data:'].includes(urlObject.protocol)) {
+                return false;
+            }
+            return true;
         }
-        // Case 3: Handle standard errors - keep them up to consumer
-        if (whatWasThrown instanceof Error) {
-            return;
+        catch (error) {
+            return false;
+        }
+    }
+
+    /**
+     * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
+     *
+     * @public exported from `@promptbook/core`
+     */
+    class ParseError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = 'ParseError';
+            Object.setPrototypeOf(this, ParseError.prototype);
         }
-        // Case 4: Handle non-standard errors - wrap them into `WrappedError` and throw
-        throw new WrappedError(whatWasThrown);
     }
+    /**
+     * TODO: Maybe split `ParseError` and `ApplyError`
+     */
 
     /**
      * Function isValidJsonString will tell you if the string is valid JSON or not
@@ -873,33 +2399,6 @@
         return orderedValue;
     }
 
-    /**
-     * Freezes the given object and all its nested objects recursively
-     *
-     * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
-     * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
-     *
-     * @returns The same object as the input, but deeply frozen
-     * @public exported from `@promptbook/utils`
-     */
-    function $deepFreeze(objectValue) {
-        if (Array.isArray(objectValue)) {
-            return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
-        }
-        const propertyNames = Object.getOwnPropertyNames(objectValue);
-        for (const propertyName of propertyNames) {
-            const value = objectValue[propertyName];
-            if (value && typeof value === 'object') {
-                $deepFreeze(value);
-            }
-        }
-        Object.freeze(objectValue);
-        return objectValue;
-    }
-    /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
-     */
-
     /**
      * Checks if the value is [🚉] serializable as JSON
      * If not, throws an UnexpectedError with a rich error message and tracking
@@ -2121,19 +3620,6 @@
      * TODO: [🧠][🌂] Add id to all errors
      */
 
-    /**
-     * Error thrown when a fetch request fails
-     *
-     * @public exported from `@promptbook/core`
-     */
-    class PromptbookFetchError extends Error {
-        constructor(message) {
-            super(message);
-            this.name = 'PromptbookFetchError';
-            Object.setPrototypeOf(this, PromptbookFetchError.prototype);
-        }
-    }
-
     /**
      * Index of all custom errors
      *
@@ -5835,37 +7321,6 @@
         return value;
     }
 
-    /**
-     * The built-in `fetch' function with a lightweight error handling wrapper as default fetch function used in Promptbook scrapers
-     *
-     * @public exported from `@promptbook/core`
-     */
-    const promptbookFetch = async (urlOrRequest, init) => {
-        try {
-            return await fetch(urlOrRequest, init);
-        }
-        catch (error) {
-            assertsError(error);
-            let url;
-            if (typeof urlOrRequest === 'string') {
-                url = urlOrRequest;
-            }
-            else if (urlOrRequest instanceof Request) {
-                url = urlOrRequest.url;
-            }
-            throw new PromptbookFetchError(spaceTrim__default["default"]((block) => `
-                    Can not fetch "${url}"
-
-                    Fetch error:
-                    ${block(error.message)}
-
-                `));
-        }
-    };
-    /**
-     * TODO: [🧠] Maybe rename because it is not used only for scrapers but also in `$getCompiledBook`
-     */
-
     /**
      * Factory function that creates a handler for processing knowledge sources.
      * Provides standardized processing of different types of knowledge sources
@@ -5920,7 +7375,23 @@
             //    <- TODO: [🥬] Encapsulate sha256 to some private utility function
             const rootDirname = path.join(process.cwd(), DEFAULT_DOWNLOAD_CACHE_DIRNAME);
             const filepath = path.join(...nameToSubfolderPath(hash /* <- TODO: [🎎] Maybe add some SHA256 prefix */), `${basename.substring(0, MAX_FILENAME_LENGTH)}.${mimeTypeToExtension(mimeType)}`);
-            await tools.fs.mkdir(path.dirname(path.join(rootDirname, filepath)), { recursive: true });
+            // Note: Try to create cache directory, but don't fail if filesystem has issues
+            try {
+                await tools.fs.mkdir(path.dirname(path.join(rootDirname, filepath)), { recursive: true });
+            }
+            catch (error) {
+                // Note: If we can't create cache directory, we'll handle it when trying to write the file
+                //       This handles read-only filesystems, permission issues, and missing parent directories
+                if (error instanceof Error && (error.message.includes('EROFS') ||
+                    error.message.includes('read-only') ||
+                    error.message.includes('EACCES') ||
+                    error.message.includes('EPERM') ||
+                    error.message.includes('ENOENT'))) ;
+                else {
+                    // Re-throw other unexpected errors
+                    throw error;
+                }
+            }
             const fileContent = Buffer.from(await response.arrayBuffer());
             if (fileContent.length > DEFAULT_MAX_FILE_SIZE /* <- TODO: Allow to pass different value to remote server */) {
                 throw new LimitReachedError(`File is too large (${Math.round(fileContent.length / 1024 / 1024)}MB). Maximum allowed size is ${Math.round(DEFAULT_MAX_FILE_SIZE / 1024 / 1024)}MB.`);
@@ -5935,7 +7406,8 @@
                 if (error instanceof Error && (error.message.includes('EROFS') ||
                     error.message.includes('read-only') ||
                     error.message.includes('EACCES') ||
-                    error.message.includes('EPERM'))) {
+                    error.message.includes('EPERM') ||
+                    error.message.includes('ENOENT'))) {
                     // Return a handler that works directly with the downloaded content
                     return {
                         source: name,
@@ -11632,18 +13104,28 @@
      * @public exported from `@promptbook/core`
      */
     function book(strings, ...values) {
-        const pipelineString = prompt(strings, ...values);
-        if (!isValidPipelineString(pipelineString)) {
+        const bookString = prompt(strings, ...values);
+        if (!isValidPipelineString(bookString)) {
             // TODO: Make the CustomError for this
             throw new Error(spaceTrim__default["default"](`
                 The string is not a valid pipeline string
 
                 book\`
-                    ${pipelineString}
+                    ${bookString}
                 \`
             `));
         }
-        return pipelineString;
+        if (!isValidBook(bookString)) {
+            // TODO: Make the CustomError for this
+            throw new Error(spaceTrim__default["default"](`
+                The string is not a valid book
+
+                book\`
+                    ${bookString}
+                \`
+            `));
+        }
+        return bookString;
     }
     /**
      * TODO: [🧠][🈴] Where is the best location for this file
@@ -11994,6 +13476,7 @@
     exports.CompletionFormfactorDefinition = CompletionFormfactorDefinition;
     exports.CsvFormatError = CsvFormatError;
     exports.CsvFormatParser = CsvFormatParser;
+    exports.DEFAULT_BOOK = DEFAULT_BOOK;
     exports.DEFAULT_BOOKS_DIRNAME = DEFAULT_BOOKS_DIRNAME;
     exports.DEFAULT_BOOK_OUTPUT_PARAMETER_NAME = DEFAULT_BOOK_OUTPUT_PARAMETER_NAME;
     exports.DEFAULT_BOOK_TITLE = DEFAULT_BOOK_TITLE;
@@ -12038,6 +13521,7 @@
     exports.NAME = NAME;
     exports.NonTaskSectionTypes = NonTaskSectionTypes;
     exports.NotFoundError = NotFoundError;
+    exports.NotYetImplementedCommitmentDefinition = NotYetImplementedCommitmentDefinition;
     exports.NotYetImplementedError = NotYetImplementedError;
     exports.ORDER_OF_PIPELINE_JSON = ORDER_OF_PIPELINE_JSON;
     exports.PENDING_VALUE_PLACEHOLDER = PENDING_VALUE_PLACEHOLDER;
@@ -12086,9 +13570,12 @@
     exports.compilePipeline = compilePipeline;
     exports.computeCosineSimilarity = computeCosineSimilarity;
     exports.countUsage = countUsage;
+    exports.createAgentModelRequirements = createAgentModelRequirements;
+    exports.createBasicAgentModelRequirements = createBasicAgentModelRequirements;
     exports.createCollectionFromJson = createCollectionFromJson;
     exports.createCollectionFromPromise = createCollectionFromPromise;
     exports.createCollectionFromUrl = createCollectionFromUrl;
+    exports.createEmptyAgentModelRequirements = createEmptyAgentModelRequirements;
     exports.createLlmToolsFromConfiguration = createLlmToolsFromConfiguration;
     exports.createPipelineExecutor = createPipelineExecutor;
     exports.createSubcollection = createSubcollection;
@@ -12096,17 +13583,23 @@
     exports.executionReportJsonToString = executionReportJsonToString;
     exports.extractParameterNamesFromTask = extractParameterNamesFromTask;
     exports.filterModels = filterModels;
+    exports.getAllCommitmentDefinitions = getAllCommitmentDefinitions;
+    exports.getAllCommitmentTypes = getAllCommitmentTypes;
+    exports.getCommitmentDefinition = getCommitmentDefinition;
     exports.getPipelineInterface = getPipelineInterface;
     exports.identificationToPromptbookToken = identificationToPromptbookToken;
+    exports.isCommitmentSupported = isCommitmentSupported;
     exports.isPassingExpectations = isPassingExpectations;
     exports.isPipelineImplementingInterface = isPipelineImplementingInterface;
     exports.isPipelineInterfacesEqual = isPipelineInterfacesEqual;
     exports.isPipelinePrepared = isPipelinePrepared;
+    exports.isValidBook = isValidBook;
     exports.isValidPipelineString = isValidPipelineString;
     exports.joinLlmExecutionTools = joinLlmExecutionTools;
     exports.limitTotalUsage = limitTotalUsage;
     exports.makeKnowledgeSourceHandler = makeKnowledgeSourceHandler;
     exports.migratePipeline = migratePipeline;
+    exports.parseAgentSource = parseAgentSource;
     exports.parsePipeline = parsePipeline;
     exports.pipelineJsonToString = pipelineJsonToString;
     exports.prepareKnowledgePieces = prepareKnowledgePieces;
@@ -12118,6 +13611,7 @@
     exports.unpreparePipeline = unpreparePipeline;
     exports.usageToHuman = usageToHuman;
     exports.usageToWorktime = usageToWorktime;
+    exports.validateBook = validateBook;
     exports.validatePipeline = validatePipeline;
     exports.validatePipelineString = validatePipelineString;