@peebles-group/agentlib-js 1.0.3 → 1.0.5

package/README.md

@@ -8,6 +8,10 @@ A lightweight Node.js library for building AI agents with LLM providers and MCP
 npm install @peebles-group/agentlib-js
 ```
 
+## Testing
+
+Run `npm test` to run the test script under `tests/test.js`.
+
 ## Quick Start
 
 1. **Set up API keys**
@@ -40,11 +44,11 @@ import { Agent, LLMService } from '@peebles-group/agentlib-js';
 import dotenv from 'dotenv';
 dotenv.config();
 
-// Initialize LLM service for direct tasks
+// Initialize LLM service
 const llm = new LLMService('openai', process.env.OPENAI_API_KEY);
 
 // Simple agent
-const agent = new Agent('openai', process.env.OPENAI_API_KEY, {
+const agent = new Agent(llm, {
   model: 'gpt-4o-mini'
 });
 agent.addInput({ role: 'user', content: 'Hello!' });
@@ -52,7 +56,7 @@ const response = await agent.run();
 console.log(response.output_text);
 
 // Agent with MCP servers (auto-installs packages)
-const mcpAgent = new Agent('openai', process.env.OPENAI_API_KEY, { 
+const mcpAgent = new Agent(llm, { 
   model: 'gpt-4o-mini', 
   enableMCP: true 
 });
@@ -64,6 +68,34 @@ await mcpAgent.addMCPServer('browser', {
 });
 ```
 
+## Prompt Management
+
+Manage prompts efficiently using the `PromptLoader`. Support for yml/db/md/json/txt files.
+
+```javascript
+import { PromptLoader } from '@peebles-group/agentlib-js';
+
+// Load prompts from a file
+const loader = await PromptLoader.create('./prompts.yml');
+
+/*
+prompts.yml
+
+system_instruction: |
+  Write an essay on {{topic}}.
+  Make sure to make it {{depth}}.
+*/
+
+// Get and format a prompt
+const prompt = loader.getPrompt('system_instruction').format({
+  topic: 'AI Agents',
+  depth: 'detailed'
+});
+
+agent.addInput({ role: 'user', content: prompt });
+
+```
+
 ## Structured Outputs
 
 AgentLib supports type-safe structured outputs using Zod schemas for reliable JSON responses.

package/index.js

@@ -1,2 +1,3 @@
 export { LLMService } from './src/llmService.js';
-export { Agent } from './src/Agent.js';
+export { Agent } from './src/Agent.js';
+export { PromptLoader } from './src/prompt-loader/promptLoader.js';

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@peebles-group/agentlib-js",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A minimal JavaScript library implementing concurrent async agents for illustrating multi-agent systems and other agentic design patterns including recursive ones purely through function calling loops.",
   "main": "index.js",
   "type": "module",
   "scripts": {
     "start": "node index.js",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "cd tests && node test.js"
   },
   "author": "Peebles Group",
   "license": "MIT",
@@ -16,11 +16,11 @@
     "openai": "^6.0.0"
   },
   "devDependencies": {
+    "@peebles-group/agentlib-js": "^1.0.5",
     "dotenv": "^16.6.1",
     "js-yaml": "^4.1.0",
     "mongodb": "^6.20.0",
     "openai": "^5.16.0",
-    "agentlib-js": "^1.0.0",
     "playwright": "^1.55.0",
     "prompt-sync": "^4.2.0",
     "sqlite": "^5.1.1",
@@ -33,4 +33,4 @@
     "README.md",
     "LICENSE"
   ]
-}
+}

package/src/Agent.js

@@ -1,44 +1,93 @@
-import { LLMService } from "./llmService.js";
 import { defaultModel } from "./config.js";
 import { MCPManager } from "./mcp/MCPManager.js";
+import { PromptLoader } from "./prompt-loader/promptLoader.js";
+import { fileURLToPath } from 'url';
+import path, { dirname } from 'path';
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const promptLoader = await PromptLoader.create(path.join(__dirname, 'prompts', 'agentPrompts.yml'));
+
+/**
+ * Represents an LLM-based agent capable of tool calling.
+ */
 export class Agent {
-  constructor(provider, apiKey, {model = defaultModel, tools = [], inputSchema = null, outputSchema = null, enableMCP = false} = {}) {
-    this.llmService = new LLMService(provider, apiKey);
+  /**
+   * @param {object} llmService - The LLM service used for communication with LLM client.
+   * @param {object} [options] - Configuration options for the agent.
+   * @param {string} [options.model=defaultModel] - The model identifier to use.
+   * @param {Array<object>} [options.tools=[]] - Array of native tools available to the agent.
+   * @param {zod object|null} [options.inputSchema=null] - Zod schema for validating input messages.
+   * @param {zod object|null} [options.outputSchema=null] - Zod schema for expected final output format.
+   * @param {boolean} [options.enableMCP=false] - Whether to enable MCP (Model Context Protocol) usage.
+   * @param {boolean} [options.redundantToolInfo=true] - Whether to include tool descriptions in the system prompt.
+   * @param {object} [options...] - Additional options passed to the LLM service.
+   */
+  constructor(llmService, { model = defaultModel, tools = [], inputSchema = null, outputSchema = null, enableMCP = false, redundantToolInfo = true, ...options } = {}) {
+    this.llmService = llmService;
     this.model = model;
     this.nativeTools = tools;
     this.inputSchema = inputSchema;
     this.outputSchema = outputSchema;
     this.mcpManager = enableMCP ? new MCPManager() : null;
-    this.updateSystemPrompt();
+    this.redundantToolInfo = redundantToolInfo;
+    this.additionalOptions = options;
+    this.input = [];
+
+    if (this.redundantToolInfo) {
+      this.updateSystemPrompt();
+    }
   }
 
+  /**
+   * Adds a new MCP server for remote tool access.
+   * @param {string} serverName - A unique name for the server.
+   * @param {object} config - Configuration details for the MCP server connection.
+   * @returns {Promise<object>} The result of adding the server.
+   * @throws {Error} If MCP is not enabled.
+   */
   async addMCPServer(serverName, config) {
     if (!this.mcpManager) {
       throw new Error("MCP is not enabled for this agent");
-    } 
+    }
 
     const result = await this.mcpManager.addServer(serverName, config);
-    this.updateSystemPrompt();
+    if (this.redundantToolInfo) {
+      this.updateSystemPrompt();
+    }
     return result;
   }
 
+  /**
+   * Removes an existing MCP server.
+   * @param {string} serverName - The unique name of the server to remove.
+   * @returns {Promise<boolean>} True if the server was successfully removed, false otherwise.
+   */
   async removeMCPServer(serverName) {
     if (!this.mcpManager) return false;
 
     const result = await this.mcpManager.removeServer(serverName);
-    if (result) this.updateSystemPrompt();
+    if (result && this.redundantToolInfo) {
+      this.updateSystemPrompt();
+    }
     return result;
   }
 
   /**
-   * Add a native tool at runtime
-   * Expected shape: { name: string, description?: string, func: (args) => Promise<any> | any }
+   * Adds a native tool to the agent's array of tools.
+   * @param {object} tool - The tool object.
+   * @param {string} tool.name - The unique name of the tool.
+   * @param {function} tool.func - The function to execute when the tool is called.
+   * @param {string} [tool.description=''] - A description for the LLM on when to use the tool.
+   * @returns {object} The added tool object.
+   * @throws {Error} If the tool is invalid or a name collision occurs.
    */
   addTool(tool) {
     if (!tool || typeof tool !== 'object') {
-      throw new Error("Invalid tool: expected an object");
+      throw new Error('Invalid tool: expected an object');
     }
+
     const { name, func } = tool;
     if (typeof name !== 'string' || name.trim() === '') {
       throw new Error("Invalid tool: missing valid 'name' (string)");
@@ -47,7 +96,6 @@ export class Agent {
       throw new Error("Invalid tool: missing 'func' (function)");
     }
 
-    // Prevent name collisions across native and MCP tools
     const nameExistsInNative = this.nativeTools.some(t => t && t.name === name);
     const nameExistsInMCP = this.mcpManager ? this.mcpManager.getAllTools().some(t => t && t.name === name) : false;
     if (nameExistsInNative || nameExistsInMCP) {
@@ -59,30 +107,45 @@ export class Agent {
     }
 
     this.nativeTools.push(tool);
-    this.updateSystemPrompt();
+    if (this.redundantToolInfo) {
+      this.updateSystemPrompt();
+    }
     return tool;
   }
 
+  /**
+   * Retrieves all available tools, including native and MCP tools.
+   * @returns {Array<object>} An array of all tools.
+   */
   getAllTools() {
     const mcpTools = this.mcpManager ? this.mcpManager.getAllTools() : [];
     return [...this.nativeTools, ...mcpTools];
   }
 
+  /**
+   * Gets status information about the MCP manager.
+   * @returns {object} Information about the MCP manager, or { enabled: false } if disabled.
+   */
   getMCPInfo() {
     return this.mcpManager ? this.mcpManager.getServerInfo() : { enabled: false };
   }
 
-  // Mentioning the tools in the system prompt for maximum reliability
+  /**
+   * Updates the system prompt with descriptions of all currently available tools.
+   */
   updateSystemPrompt() {
     const allTools = this.getAllTools();
+    const toolDescriptions = allTools.map(tool => `${tool.name}: ${tool.description}`).join('; ');
     this.input = [{
       role: 'system',
-      content: 'You are a tool-calling agent. You have access to the following tools: ' +
-      allTools.map(tool => `${tool.name}: ${tool.description}`).join('; ') +
-      '. Use these tools to answer the user\'s questions.'
+      content: promptLoader.getPrompt('systemPrompt').format({ toolDescriptions })
     }];
   }
 
+  /**
+   * Adds user instruction or assistant response to the current conversation history.
+   * @param {object} input - The message object to add.
+   */
   addInput(input) {
     if (this.inputSchema) {
       this.inputSchema.parse(input);
@@ -91,74 +154,75 @@ export class Agent {
   }
 
   /**
-   * Run the agent for a single step
+   * Runs the agent for a single conversational turn, including tool use if necessary.
+   * This method handles the multi-step reasoning: LLM -> Tool Execution -> LLM Final Response.
+   * @returns {Promise<object>} The final response object from the LLM, including execution details.
    */
   async run() {
     const allTools = this.getAllTools();
+    const executed = []
 
-    // Step 1: send input to model
     let response = await this.llmService.chat(this.input, {
       model: this.model,
       outputSchema: this.outputSchema,
       tools: allTools,
+      ...this.additionalOptions
     });
 
     const { output, rawResponse } = response;
 
-    // Step 2: Clean and add the response to input history
-    // Remove parsed_arguments (if it exists) from function calls before adding to history
-    const cleanedOutput = rawResponse.output.map(item => {
-      if (item.type === "function_call" && item.parsed_arguments) {
-        const { parsed_arguments, ...cleanItem } = item;
-        return cleanItem;
+    rawResponse.output.forEach(item => {
+      if (item.type === "function_call") {
+        const { parsed_arguments, ...rest } = item;
+        const cleanedItem = { ...rest, arguments: JSON.stringify(item.arguments) };
+        this.addInput(cleanedItem);
+      } else {
+        this.addInput(item);
       }
-      return item;
     });
-      
-    this.input = this.input.concat(cleanedOutput);
 
-    // Step 3: collect all function calls
     const functionCalls = rawResponse.output.filter(item => item.type === "function_call");
 
     if (functionCalls.length > 0) {
       for (const call of functionCalls) {
         let args;
-        try {
-          args = JSON.parse(call.arguments);
-        } catch (err) {
-          console.error("Failed to parse function call arguments:", call.arguments);
-          continue;
-        }
+        args = JSON.parse(call.arguments);
+        call.arguments = args
+        executed.push(call)
 
         const tool = allTools.find(t => t.name === call.name);
         if (!tool || !tool.func) {
           throw new Error(`Tool ${call.name} not found or missing implementation.`);
         }
 
-        // Step 4: execute the function
         const result = await tool.func(args);
 
-        // Step 5: append function call output to input
         this.input.push({
           type: "function_call_output",
           call_id: call.call_id,
           output: JSON.stringify(result),
         });
       }
-
+      
       // Step 6: send updated input back to model for final response
       response = await this.llmService.chat(this.input, {
         tools: allTools,
         model: this.model,
         outputSchema: this.outputSchema,
+        ...this.additionalOptions
       });
     }
+    response.executed = executed;
     return response;
   }
 
+  /**
+   * Performs cleanup operations, primarily closing MCP server connections.
+   * @returns {Promise<void>}
+   */
   async cleanup() {
     if (this.mcpManager) {
       await this.mcpManager.cleanup();
     }
   }
-}
+}

package/src/config.js

@@ -1 +1,2 @@
-export const defaultModel = 'gpt-4o-mini';
+export const defaultProvider = 'openai';
+export const defaultModel = 'gpt-5';

package/src/llmService.js

@@ -1,30 +1,25 @@
-import { validateProviderName } from './providers/registry.js';
+import { getAllowedProviders, validateProviderName } from './providers/registry.js';
 
 export class LLMService {
     constructor(provider, apiKey) {
         this.provider = validateProviderName(provider);
+        this.providerNamespace = getAllowedProviders()[this.provider]?.namespace;
         this.apiKey = apiKey;
-        this.client = null;  
+        this.client = this._getProviderClient();
 
         if (!apiKey) {
             throw new Error(`API key is required for provider: ${provider}`);
         }
     }
 
-    async _getProviderClient() {
-
-        if (!this.client) {
-            const provider = await import(`./providers/${this.provider}.js`);
-            this.client = provider.createClient(this.apiKey);
-        }
-        return this.client;
+    // Instead of using a dynamic import here, we use the imported registry namespace
+    _getProviderClient() {
+        // Returns the client instance for the specified provider
+        return this.providerNamespace.createClient(this.apiKey);
     }
 
-    async chat(input, {inputSchema = null, outputSchema = null, ...options} = {}) {
-        const client = await this._getProviderClient();
-        const provider = await import(`./providers/${this.provider}.js`);
-        
-        return provider.chat(client, input, {
+    async chat(input, {inputSchema = null, outputSchema = null, ...options} = {}) {        
+        return this.providerNamespace.chat(this.client, input, {
             inputSchema, 
             outputSchema, 
             ...options

package/src/prompt-loader/loadStrategies.js

@@ -0,0 +1,63 @@
+import { promises as fs } from 'fs';
+import http from 'http';
+import https from 'https';
+import sqlite3 from 'sqlite3';
+
+export const loadStrategies = {
+    /**
+     * Loads and parses a file from the local file system.
+     * @param {string} path - The file path.
+     * @returns {Promise<string>} The file contents.
+     */
+    file: async (path) => {
+        try {
+            const fileContents = await fs.readFile(path, 'utf-8');
+            return fileContents;
+        } catch (error) {
+            throw new Error(`File loading error: ${error.message}`);
+        }
+    },
+
+    /**
+     * Loads and parses data from a URL.
+     * @param {string} path - The URL.
+     * @param {string} parserName - The key of the parser (e.g., 'json', 'yaml').
+     * @returns {Promise<string>} The URL contents.
+     */
+    url: (path) => {
+        const protocol = path.startsWith('https') ? https : http;
+
+        return new Promise((resolve, reject) => {
+            protocol.get(path, (response) => {
+                let data = '';
+                response.on('data', (chunk) => data += chunk);
+                response.on('end', () => {
+                    try {
+                        // Use the specified parser
+                        resolve(data);
+                    } catch (error) {
+                        reject(error); // Pass up parsing error
+                    }
+                });
+            }).on('error', (error) => {
+                reject(new Error(`URL loading error: ${error.message}`));
+            });
+        });
+    },
+
+    /**
+     * Loads prompt data from an SQLite database.
+     * @param {string} path - The path to the SQLite DB file.
+     * @returns {Promise<object>} The prompt data object in key-value pairs of signature: { prompt: string, output: string }.
+     */
+    sqlite: (path) => {
+        return new Promise((resolve, reject) => {
+            const db = new sqlite3.Database(path, sqlite3.OPEN_READONLY, (err) => {
+                if (err) {
+                    return reject(new Error(`SQLite connection error: ${err.message}`));
+                }
+            });
+            resolve(db);
+        });
+    }
+};

package/src/prompt-loader/parseStrategies.js

@@ -0,0 +1,79 @@
+import yaml from 'js-yaml';
+
+export const parseStrategies = {
+    /**
+     * Parses a YAML string.
+     * @param {string} data - The raw YAML string.
+     * @returns {object} The parsed JavaScript object.
+     */
+    yaml: (data) => {
+        try {
+            return yaml.load(data);
+        } catch (error) {
+            throw new Error(`YAML parsing error: ${error.message}`);
+        }
+    },
+
+    /**
+     * Parses a JSON string.
+     * @param {string} data - The raw JSON string.
+     * @returns {object} The parsed JavaScript object.
+     */
+    json: (data) => {
+        try {
+            return JSON.parse(data);
+        } catch (error) {
+            throw new Error(`JSON parsing error: ${error.message}`);
+        }
+    },
+
+    /**
+     * Parses a sqlite database.
+     * @param {object} db - The sqlite database.
+     * @returns {object} The parsed sqlite database in key-value pairs of signature: { prompt: string, output: string }.
+     */
+    sqlite: (db) => {
+        return new Promise((resolve, reject) => {
+            const query = 'SELECT signature, prompt, output FROM prompt_store';
+            db.all(query, [], (err, rows) => {
+                if (err) {
+                    return reject(new Error(`SQLite query error: ${err.message}`));
+                }
+
+                const data = {};
+                rows.forEach(row => {
+                    data[row.signature] = { prompt: row.prompt, output: row.output };
+                });
+
+                db.close((err) => {
+                    if (err) {
+                        console.error(`SQLite close error: ${err.message}`);
+                    }
+                });
+                resolve(data);
+            });
+        });
+    },
+
+    /**
+     * Parses a custom text format.
+     * Sections are delimited by a delimiter at the start of a line (default is '#').
+     * The first line of a section is the key.
+     * @param {string} data - The raw text data.
+     * @param {string} delimiter - The delimiter at the start of a line (default is '#').
+     * @returns {object} A dictionary of sections.
+     */
+    customText: (data, delimiter = '#') => {
+        // Use RegExp to split only on delimiters at the beginning of a line
+        const sections = data.split(new RegExp(`^${delimiter}`, 'm'));
+        const sectionDict = sections.reduce((acc, section) => {
+            const lines = section.trim().split('\n');
+            const key = lines.shift();
+            if (key) {
+                acc[key.trim()] = lines.join('\n');
+            }
+            return acc;
+        }, {});
+        return sectionDict;
+    }
+};

package/src/prompt-loader/promptLoader.js

@@ -0,0 +1,188 @@
+import { loadStrategies } from './loadStrategies.js';
+import { parseStrategies } from './parseStrategies.js';
+import path from 'path';
+
+class Prompt {
+    /**
+     * @param {string} templateString The raw prompt string.
+     * @param {string} startDel The start delimiter, e.g., '{{'
+     * @param {string} endDel The end delimiter, e.g., '}}'
+     */
+    constructor(templateString, startDel = '{{', endDel = '}}') {
+        this.template = templateString;
+        this.delimiterStart = startDel;
+        this.delimiterEnd = endDel;
+
+        // Escape special chars so user delimiters like '?' don't break regex logic.
+        const escapedStart = this.delimiterStart.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&');
+        const escapedEnd = this.delimiterEnd.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&');
+
+        // Matches start delimiter, captures variable name (alphanumeric + dots), matches end.
+        this.varRegex = new RegExp(`${escapedStart}\\s*([a-zA-Z0-9_.]+)\\s*${escapedEnd}`, 'g');
+
+        this.variables = this._discoverVariables();
+    }
+
+    /**
+     * Discovers all unique variables in the template.
+     * @returns {Set<string>} A set of variable names.
+     */
+    _discoverVariables() {
+        const vars = new Set();
+        let match;
+        this.varRegex.lastIndex = 0;
+        while ((match = this.varRegex.exec(this.template)) !== null) {
+            vars.add(match[1].trim());
+        }
+        this.varRegex.lastIndex = 0;
+        return vars;
+    }
+
+    /**
+     * Formats the prompt template with the given variables.
+     * @param {object} variables - An object where keys are variable names.
+     * @returns {string} The formatted prompt string.
+     */
+    format(variables = {}) {
+        return this.template.replace(this.varRegex, (match, varPath) => {
+            const cleanPath = varPath.trim();
+            const value = variables[cleanPath];
+
+            // If value is undefined, leave the variable intact
+            return value !== undefined ? String(value) : match;
+        });
+    }
+
+    /**
+     * @returns {string[]} An array of variable names found in the prompt.
+     */
+    getVars() {
+        return Array.from(this.variables);
+    }
+}
+
+
+// --- Main Prompt Loader Class ---
+
+/**
+ * Handles loading prompts from various sources and provides
+ * access to formatted Prompt objects.
+ * * Use the static `PromptLoader.create()` method to instantiate.
+ */
+class PromptLoader {
+    /**
+     * Private constructor. Use `PromptLoader.create()` to instantiate.
+     * @param {object} promptData - The raw, parsed object (e.g., { "greeting": "..." })
+     * @param {object} [options] - Options passed from create, including delimiter settings.
+     */
+    constructor(promptData, options = {}) {
+        this.prompts = new Map();
+
+        const startDel = options.delimiterStart || '{{';
+        const endDel = options.delimiterEnd || '}}';
+
+        for (const [key, value] of Object.entries(promptData)) {
+            let promptString;
+
+            // Handle different data structures
+            if (typeof value === 'string') {
+                // E.g., { "greeting": "Hello {{name}}" }
+                promptString = value;
+            } else if (value && typeof value.prompt === 'string') {
+                // E.g., { "greeting": { "prompt": "Hello {{name}}", "output": "..." } }
+                promptString = value.prompt;
+            }
+
+            if (promptString) {
+                // Pass custom delimiters to the Prompt constructor
+                this.prompts.set(key, new Prompt(promptString, startDel, endDel));
+            } else {
+                console.warn(`No valid prompt string found for key: ${key}`);
+            }
+        }
+    }
+
+    static _determineLoader(resourcePathOrUrl, parserName) {
+        // SQLite requires a specific loader (db connection), regardless of path
+        if (parserName === 'sqlite') return 'sqlite';
+
+        // Otherwise, check protocol
+        const isUrl = resourcePathOrUrl.startsWith('http://') || resourcePathOrUrl.startsWith('https://');
+        return isUrl ? 'url' : 'file';
+    }
+
+    /**
+     * Determines the parser name based on the resource path.
+     * @param {string} resourcePath - The path or URL of the resource.
+     * @returns {string} The name of the parser strategy ('yaml', 'json', 'sqlite', or 'customText').
+     */
+    static _determineParser(resourcePath) {
+        const cleanPath = resourcePath.split('?')[0];
+        const extension = path.extname(cleanPath).toLowerCase();
+
+        const map = {
+            '.yaml': 'yaml',
+            '.yml': 'yaml',
+            '.json': 'json',
+            '.db': 'sqlite',
+            '.sqlite': 'sqlite',
+            '.txt': 'customText',
+            '.md': 'customText'
+        };
+
+        return map[extension] || 'customText';
+    }
+
+    /**
+     * Asynchronously creates and initializes a PromptLoader.
+     * This is the main entry point for the class.
+     * @param {string} resourcePathOrUrl - The file path or URL to the prompt resource.
+     * @param {object} [options] - Optional settings.
+     * @param {string} [options.parser] - Explicitly set the parser (overrides extension analysis).
+     * @returns {Promise<PromptLoader>} A new, initialized PromptLoader instance.
+     */
+    static async create(resourcePathOrUrl, options = {}) {
+        // 1. Determine Strategies
+        const parserName = options.parser || PromptLoader._determineParser(resourcePathOrUrl);
+        const loaderName = PromptLoader._determineLoader(resourcePathOrUrl, parserName);
+
+        // 2. Validate
+        if (!loadStrategies[loaderName]) throw new Error(`Unknown loader: ${loaderName}`);
+        if (!parseStrategies[parserName]) throw new Error(`Unknown parser: ${parserName}`);
+
+        // 3. Universal Execution Flow
+        // 'rawResource' adapts: it's a String for files, or a DbConnection for sqlite
+        const rawResource = await loadStrategies[loaderName](resourcePathOrUrl);
+
+        // The parser strategy handles its specific input type (String or DbConnection)
+        const promptData = await parseStrategies[parserName](rawResource);
+
+        return new PromptLoader(promptData, options);
+    }
+
+    /**
+     * Retrieves an initialized Prompt object by its ID.
+     * @param {string} id - The key of the prompt.
+     * @returns {Prompt | undefined} The Prompt object, or undefined if not found.
+     */
+    getPrompt(id) {
+        const prompt = this.prompts.get(id);
+        if (!prompt) {
+            console.error(`Prompt ID "${id}" does not exist.`);
+            return undefined;
+        }
+        return prompt;
+    }
+
+    /**
+     * @returns {Map<string, Prompt>} A map of all loaded prompt objects.
+     */
+    getAllPrompts() {
+        return this.prompts;
+    }
+}
+
+export {
+    PromptLoader,
+    Prompt,
+};

package/src/prompt-loader/tests/test-prompts.json

@@ -0,0 +1,9 @@
+{
+    "greeting_simple": "Hello, {{user_name}}! Welcome to the system.",
+    "analyzer_complex": "Review the following text and perform a {{task_type}} analysis.\nFocus on {{metric_1}} and {{metric_2}}.\n\n***TEXT TO ANALYZE***\n{{raw_text_input}}\n***END OF TEXT***\n\nProvide your output as a JSON object.",
+    "summarizer_with_metadata": {
+        "prompt": "Summarize the document titled '{{document_title}}' into a maximum of {{word_count}} words.",
+        "output": "plain_text",
+        "version": 2.1
+    }
+}

package/src/prompt-loader/tests/test-prompts.md

@@ -0,0 +1,12 @@
+# greeting_simple
+Hello, {{user_name}}! Welcome to the system.
+
+# analyzer_complex
+Review the following text and perform a {{task_type}} analysis.
+Focus on {{metric_1}} and {{metric_2}}.
+
+***TEXT TO ANALYZE***
+{{raw_text_input}}
+***END OF TEXT***
+
+Provide your output as a JSON object.

package/src/prompt-loader/tests/test-prompts.txt

@@ -0,0 +1,12 @@
+# greeting_simple
+Hello, {{user_name}}! Welcome to the system.
+
+# analyzer_complex
+Review the following text and perform a {{task_type}} analysis.
+Focus on {{metric_1}} and {{metric_2}}.
+
+***TEXT TO ANALYZE***
+{{raw_text_input}}
+***END OF TEXT***
+
+Provide your output as a JSON object.

package/src/prompt-loader/tests/test-prompts.yaml

@@ -0,0 +1,16 @@
+greeting_simple: "Hello, {{user_name}}! Welcome to the system."
+
+analyzer_complex: |
+  Review the following text and perform a {{task_type}} analysis.
+  Focus on {{metric_1}} and {{metric_2}}.
+  
+  ***TEXT TO ANALYZE***
+  {{raw_text_input}}
+  ***END OF TEXT***
+  
+  Provide your output as a JSON object.
+
+summarizer_with_metadata:
+  prompt: "Summarize the document titled '{{document_title}}' into a maximum of {{word_count}} words."
+  output: "plain_text"
+  version: 2.1

package/src/prompt-loader/tests/test-script.js

@@ -0,0 +1,151 @@
+import {
+    PromptLoader
+} from '../promptLoader.js';
+import { LLMService } from '@peebles-group/agentlib-js';
+import dotenv from 'dotenv';
+dotenv.config({ path: '../../../.env' });
+
+const llm = new LLMService('openai', process.env.OPENAI_API_KEY);
+
+const DB_FILE = './test-prompts.db';
+const YAML_FILE = './test-prompts.yaml';
+const JSON_FILE = './test-prompts.json';
+const TXT_FILE = './test-prompts.txt';
+const MD_FILE = './test-prompts.md';
+
+const COMMON_VARIABLES = {
+    user_name: 'Arsen',
+    current_date: 'Monday'
+};
+
+const FILE_EXPECTED = "Hello, Arsen! Welcome to the system.";
+
+const DB_EXPECTED = "Hello, Arsen! Welcome to the system. Today is Monday.";
+
+const TEST_MAP = [
+    {
+        name: "YAML Test (.yaml)",
+        path: YAML_FILE,
+        signature: "greeting_simple",
+        variables: COMMON_VARIABLES,
+        expected: FILE_EXPECTED
+    },
+    {
+        name: "JSON Test (.json)",
+        path: JSON_FILE,
+        signature: "greeting_simple",
+        variables: COMMON_VARIABLES,
+        expected: FILE_EXPECTED
+    },
+    {
+        name: "Text Test (.txt)",
+        path: TXT_FILE,
+        signature: "greeting_simple",
+        variables: COMMON_VARIABLES,
+        expected: FILE_EXPECTED
+    },
+    {
+        name: "Markdown Test (.md)",
+        path: MD_FILE,
+        signature: "greeting_simple",
+        variables: COMMON_VARIABLES,
+        expected: FILE_EXPECTED
+    },
+    {
+        name: "SQLite Test (.db)",
+        path: DB_FILE,
+        signature: "greeting_simple",
+        variables: COMMON_VARIABLES,
+        expected: DB_EXPECTED
+    },
+];
+
+async function runTest(testName, resourcePath, promptSignature, variables, expectedOutput) {
+    let loader;
+    console.log(`\n--- Running Test: ${testName} ---`);
+    console.log(`   Resource Path: ${resourcePath}`);
+    try {
+        loader = await PromptLoader.create(resourcePath);
+        const prompt = loader.getPrompt(promptSignature);
+
+        if (!prompt) {
+            console.error(`[FAIL]: Prompt signature "${promptSignature}" not found.`);
+            const availableKeys = Array.from(loader.getAllPrompts().keys());
+            console.log(`   [WARNING]: Available keys found in file: [${availableKeys.join(', ')}]`);
+            return false;
+        }
+
+        const formatted = prompt.format(variables)
+            .replace(/\s+/g, ' ')
+            .trim();
+
+        const cleanExpected = expectedOutput.replace(/\s+/g, ' ').trim();
+
+        if (formatted === cleanExpected) {
+            console.log(`[PASS]: Prompt loaded and formatted correctly.`);
+            return true;
+        } else {
+            console.error(`[FAIL]: Output Mismatch.`);
+            console.error(`   Expected: "${cleanExpected}"`);
+            console.error(`   Received: "${formatted}"`);
+            return false;
+        }
+
+    } catch (error) {
+        console.error(`[FATAL FAIL]: Error during ${testName}: ${error.message}`);
+        return false;
+    }
+}
+
+async function main() {
+    console.log("Starting PromptLoader Versatility Test (Custom Delimiter mode)");
+
+    let allPassed = true;
+
+    for (const testCase of TEST_MAP) {
+        const passed = await runTest(
+            testCase.name,
+            testCase.path,
+            testCase.signature,
+            testCase.variables,
+            testCase.expected
+        );
+        allPassed = allPassed && passed;
+    }
+
+    console.log("\n----------------------------------------------------");
+    console.log(allPassed ? "[SUCCESS]: ALL TESTS PASSED SUCCESSFULLY!" : "[FAILURE]: ONE OR MORE TESTS FAILED. CHECK LOGS ABOVE.");
+    console.log("----------------------------------------------------");
+
+    // --- LLM Service Test ---
+    console.log("\n--- Starting LLM Service Test ---");
+
+    const LLM_TEST_SIGNATURE = 'analyzer_complex';
+    const LLM_TEST_PATH = YAML_FILE;
+
+    try {
+        const loader = await PromptLoader.create(LLM_TEST_PATH);
+        const prompt = loader.getPrompt(LLM_TEST_SIGNATURE);
+
+        if (!prompt) {
+            console.error(`[LLM TEST FAIL]: Prompt signature '${LLM_TEST_SIGNATURE}' not found in ${LLM_TEST_PATH}. Skipping LLM call.`);
+            return;
+        }
+
+        const formattedPrompt = prompt.format(COMMON_VARIABLES);
+
+        const input = [{ role: 'user', content: formattedPrompt }];
+
+        console.log(`[INFO]: Sending prompt to LLM: "${formattedPrompt}"`);
+
+        const response = await llm.chat(input, { model: 'gpt-4o-mini' });
+
+        console.log(`\n[LLM RESPONSE]:`);
+        console.log(response);
+
+    } catch (error) {
+        console.error(`[LLM TEST FAIL]: Failed to execute LLM call.`, error.message);
+    }
+}
+
+main();

package/src/prompts/agentPrompts.yml

@@ -0,0 +1,3 @@
+systemPrompt: |
+  You are a tool-calling agent. You have access to the following tools: {{toolDescriptions}}. 
+  Use these tools to answer the user's questions.

package/src/providers/openai.js

@@ -36,7 +36,7 @@ export async function chat(client, input, { inputSchema, outputSchema, ...option
         }
         return {output: output, rawResponse: response};
     } catch (error) {
-        console.error(`Error during OpenAI chat completion:`, error);
+        console.error(`Error during OpenAI chat response creation:`, error);
         throw error;
     }
 }

package/src/providers/registry.js

@@ -1,18 +1,31 @@
-const ALLOWED_PROVIDERS = Object.freeze(['openai', 'gemini']);
+import * as OpenAIProvider from './openai.js';
+import * as GeminiProvider from './gemini.js';
+// Need to import namespaces when adding new providers here
+
+const ALLOWED_PROVIDERS = {
+    openai: {name: 'OpenAI', namespace: OpenAIProvider},
+    gemini: {name: 'Gemini', namespace: GeminiProvider},
+};
+// Need to add new providers to this object in this format
 
 export function getAllowedProviders() {
-    return [...ALLOWED_PROVIDERS];
+    // Procedure that returns the object
+    return ALLOWED_PROVIDERS;
 }
 
 export function validateProviderName(providerName) {
+    // Checks if a valid provider name has been passed and returns normalized name
     if (typeof providerName !== 'string') {
         throw new TypeError('Provider name must be a string.');
     }
 
-    const normalizedName = providerName.trim().toLowerCase();
+    const normalize = text => text.trim().toLowerCase();
+
+    const allowedProviders = Object.values(getAllowedProviders()).map(provider => normalize(provider.name));
+    const normalizedName = normalize(providerName); // this part is ok
 
-    if (!ALLOWED_PROVIDERS.includes(normalizedName)) {
-        throw new Error(`Unsupported provider. Allowed providers: ${ALLOWED_PROVIDERS.join(', ')}`);
+    if (!allowedProviders.includes(normalizedName)) {
+        throw new Error(`Unsupported provider. Allowed providers: ${allowedProviders.join(', ')}`);
     }
 
     return normalizedName;