Enhanced Documentation and Utility Script Addition (#48)

## Documentation Enhancement and Script Development for AgenticJS

- **Node.js Script Development:** Created a Node.js script designed to
automatically generate a markdown document detailing the structure and
codebase of the AgenticJS library. This script facilitates easy
navigation and understanding of the library’s layout for developers.
  
- **Added Detailed Comments:** Introduced comprehensive comments across
all utility files, agents, and stores. These comments elucidate the
purpose, usage, and functionality of each component within the AgenticJS
library, enhancing the documentation's clarity and usefulness for both
current and future developers.

package.json

@@ -20,7 +20,8 @@
     "test:unit:debug": "node --inspect-brk node_modules/.bin/jest --runInBand --verbose --testPathPattern='tests/unit'",
     "play:react": "cd playground/react && npm run dev",
     "play:sb": "cd playground/react && npm run storybook",
-    "play:node": "cd playground/nodejs && node index.js"
+    "play:node": "cd playground/nodejs && node index.js",
+    "code-snapshot": "node xscripts/codeSnapshot.js"
   },
   "packageManager": "[email protected]",
   "repository": {

src/agents/baseAgent.js

@@ -1,3 +1,14 @@
+/**
+ * Base Agent Definition.
+ *
+ * This file defines the BaseAgent class, which serves as the foundational component for all agents within the library. 
+ * It includes fundamental methods for setting environment variables, managing agent status, and abstract methods 
+ * for task execution which must be implemented by subclasses to handle specific tasks.
+ *
+ * Usage:
+ * Extend this class to create specialized agents with specific behaviors suited to different types of tasks and workflows.
+ */
+
 import { v4 as uuidv4 } from 'uuid';
 import { AGENT_STATUS_enum } from '../utils/enums';
 

src/agents/index.js

@@ -1,2 +1,14 @@
+/**
+ * Agent Exports Centralization.
+ *
+ * This file serves as the central export point for all agent-related classes within the AgenticJS library. By consolidating 
+ * agent exports here, it simplifies the import process for external files and maintains a clean and organized code structure. 
+ * This setup enhances modularity and reusability of agent components.
+ *
+ * Usage:
+ * Import agent classes from this file to access and utilize different types of agents across the library. This centralization 
+ * aids in maintaining consistency and ease of updates to the agent architecture.
+ */
+
 export * from './baseAgent';
 export * from './reactChampionAgent';

src/agents/reactChampionAgent.js

@@ -1,3 +1,20 @@
+/**
+ * Enhanced ReAct Agent Implementation.
+ *
+ * This file implements the ReactChampionAgent, a variation of the traditional ReAct (Reasoning and Action) agent model,
+ * tailored to enhance the agent's capabilities through iterative feedback loops. Unlike the original ReAct pattern that typically 
+ * follows a linear execution path, our Reflex Act model introduces a round-trip communication process, enabling continuous refinement 
+ * and fine-tuning of actions based on real-time feedback.
+ *
+ * This enhanced approach allows the agent to dynamically adjust its strategies and responses, significantly improving adaptability 
+ * and decision-making accuracy in complex scenarios. The model is designed for environments where ongoing interaction and meticulous 
+ * state management are crucial.
+ *
+ * Usage:
+ * Deploy this agent in applications that demand high levels of interaction and precise control over state transitions, ensuring 
+ * optimal performance and nuanced agent behavior.
+ */
+
 import { BaseAgent } from './baseAgent';
 import { getApiKey } from '../utils/agents';
 import { getParsedJSON } from '../utils/parser';

src/stores/agentStore.js

@@ -1,4 +1,14 @@
-import { AGENT_STATUS_enum, TASK_STATUS_enum } from "../utils/enums";
+/**
+ * Agent Store Configuration.
+ *
+ * This file configures a Zustand store specifically for managing the state of agents within the AgenticJS library. 
+ * It outlines actions and state changes related to the lifecycle of agents, including task execution, status updates, and error handling.
+ *
+ * Usage:
+ * Employ this store to handle state updates for agents dynamically throughout the lifecycle of their tasks and interactions.
+ */
+
+import { AGENT_STATUS_enum } from "../utils/enums";
 import { logger } from "../utils/logger";
 
 const useAgentStore = (set, get) => ({

src/stores/index.js

@@ -1 +1,14 @@
+/**
+ * Store Modules Centralization.
+ *
+ * This file acts as the central export point for all state management store modules within the AgenticJS library. It consolidates 
+ * the exports of various stores such as agentStore, taskStore, and teamStore, facilitating easier and more organized access across 
+ * the library. This centralization supports modular architecture and enhances maintainability by grouping all store-related 
+ * exports in one place.
+ *
+ * Usage:
+ * Import store modules from this file to access and manage the application's state related to agents, tasks, and teams efficiently. 
+ * This setup ensures that updates and changes to store configurations are propagated consistently throughout the application.
+ */
+
 export * from './teamStore';

src/stores/taskStore.js

@@ -1,3 +1,13 @@
+/**
+ * Task Store Management.
+ *
+ * Defines the Zustand store slice for task management, handling task lifecycle events such as completion, updates, and errors.
+ * It ensures tasks are managed consistently with the ability to react to changes in task status and handle errors effectively.
+ *
+ * Usage:
+ * Use this store to manage tasks within your application, providing a robust system for updating and tracking task progress and state.
+ */
+
 import { TASK_STATUS_enum, AGENT_STATUS_enum} from "../utils/enums";
 import { getTaskTitleForLogs} from '../utils/tasks';
 import { logger } from "../utils/logger";

src/stores/workflowController.js

@@ -1,3 +1,13 @@
+/**
+ * Workflow Controller Setup.
+ *
+ * Configures and controls the task execution workflow within a team context, using a queue system to manage the sequential
+ * execution of tasks based on their statuses. It ensures tasks are processed in the correct order and handles status updates.
+ *
+ * Usage:
+ * Integrate this controller to manage the flow of tasks within your application, ensuring tasks are executed in an orderly and efficient manner.
+ */
+
 import PQueue from 'p-queue';
 import { TASK_STATUS_enum } from '../utils/enums';
 

src/subscribers/taskSubscriber.js

@@ -1,3 +1,13 @@
+/**
+ * Task Status Subscriber.
+ *
+ * Listens to changes in task status within the library's state management system, providing logs and reactive behaviors to these changes.
+ * This helps in monitoring task progression and debugging issues in real-time.
+ *
+ * Usage:
+ * Deploy this subscriber to actively monitor and respond to changes in task status, enhancing the observability and responsiveness of your application.
+ */
+
 import { TASK_STATUS_enum } from '../utils/enums';
 import { getTaskTitleForLogs } from '../utils/tasks';
 import { logPrettyTaskCompletion, logPrettyTaskStatus } from "../utils/prettyLogs";

src/subscribers/teamSubscriber.js

@@ -1,3 +1,13 @@
+/**
+ * Workflow Status Subscriber.
+ *
+ * Monitors changes in the workflow status, logging significant events and updating the system state accordingly. 
+ * This is crucial for maintaining a clear overview of workflow progress and handling potential issues promptly.
+ *
+ * Usage:
+ * Use this subscriber to keep track of workflow statuses, enabling proactive management of workflows and their states.
+ */
+
 import { logPrettyWorkflowStatus, logPrettyWorkflowResult } from "../utils/prettyLogs";
 import { WORKFLOW_STATUS_enum } from '../utils/enums';
 

src/utils/agents.js

@@ -1,3 +1,14 @@
+/**
+ * Agent Utility Functions.
+ *
+ * This file provides utility functions specifically designed to support agent operations within the AgenticJS library. 
+ * Functions include retrieving API keys based on agent configurations and cleaning JSON strings for parsing. These utilities 
+ * aid in configuring agents accurately and handling their data interactions.
+ *
+ * Usage:
+ * Use these utilities to manage agent configurations and preprocess data formats essential for the smooth operation of agents.
+ */
+
 function getApiKey(llmConfig, env) {
     if (llmConfig?.apiKey) return llmConfig.apiKey;
 

src/utils/enums.js

@@ -1,3 +1,14 @@
+/**
+ * Enumeration Definitions.
+ *
+ * This file defines various enumerations used throughout the AgenticJS library, such as agent statuses, task statuses, 
+ * and workflow states. These enums provide a standardized set of constants that facilitate clear and consistent state management 
+ * and behavior handling across different components of the library.
+ *
+ * Usage:
+ * Reference these enums to ensure consistent state management and behavior checks across the library's various functional areas.
+ */
+
 //──── Agent Status Definitions ───────────────────────────────────────
 // 
 // INITIAL: The agent is set up and waiting to start the task.

src/utils/errors.js

@@ -1,3 +1,15 @@
+/**
+ * Custom Error Definitions.
+ *
+ * This file defines custom error classes for handling specific error scenarios within the AgenticJS library. It includes 
+ * errors for API invocation failures and more nuanced errors that provide detailed diagnostic information. Custom errors 
+ * enhance error handling by making it more informative and actionable.
+ *
+ * Usage:
+ * Utilize these custom errors to throw and catch exceptions that require specific handling strategies, thereby improving 
+ * the robustness and reliability of error management in the application.
+ */
+
 class LLMInvocationError extends Error {
     constructor(message, originalError = null, recommendedAction = null, context = {}) {
         super(message);

src/utils/llmCostCalculator.js

@@ -1,3 +1,14 @@
+/**
+ * LLM Cost Calculation Utilities.
+ *
+ * This file contains functions for calculating the costs associated with using large language models (LLMs) based on 
+ * token usage and model-specific pricing. It helps in budgeting and monitoring the financial aspects of using LLMs within 
+ * the AgenticJS library.
+ *
+ * Usage:
+ * Apply these functions to compute and track costs as part of operational management and optimization of LLM usage in projects.
+ */
+
 import {logger} from "./logger";
 
 const modelsPricing = [

src/utils/logger.js

@@ -1,3 +1,14 @@
+/**
+ * Logging Utility.
+ *
+ * This file sets up and configures the logging system used across the AgenticJS library. It allows for setting log levels 
+ * dynamically and provides a centralized logger that can be imported and used throughout the library.
+ *
+ * Usage:
+ * Import this logger to add logging capabilities to any part of the application, facilitating debugging and tracking of 
+ * application flow and state changes.
+ */
+
 import log from 'loglevel';
 
 // Set initial log level

src/utils/parser.js

@@ -1,3 +1,14 @@
+/**
+ * Data Parsing Utilities.
+ *
+ * This file offers functions for parsing and sanitizing data formats, particularly focusing on JSON structures that agents 
+ * might receive or need to process. These utilities ensure that data handled by agents is in the correct format and free of 
+ * errors that could disrupt processing.
+ *
+ * Usage:
+ * Leverage these parsing utilities to preprocess or clean data before it is fed into agents or other processing functions within the library.
+ */
+
 // Utility function to clean up JSON string. to be able to parse it. later
 
 //Examples Input

src/utils/prettyLogs.js

@@ -1,3 +1,14 @@
+/**
+ * Pretty Logging Utilities.
+ *
+ * Enhances log outputs by formatting them into more readable and visually appealing structures. This file contains functions 
+ * that generate styled log entries for various operational states and outcomes within the AgenticJS library, making it easier 
+ * to interpret and review logs.
+ *
+ * Usage:
+ * Use these functions to output enhanced visual logs for better clarity and easier debugging during development and monitoring.
+ */
+
 import ansis from "ansis";
 import { logger } from "./logger";
 

src/utils/prompts.js

@@ -1,3 +1,13 @@
+/**
+ * Prompt Templates for Agents.
+ *
+ * This file provides templates for constructing prompts that are used to interact with language models within the AgenticJS library. 
+ * These templates ensure that interactions are consistent and properly formatted, facilitating effective communication with LLMs.
+ *
+ * Usage:
+ * Utilize these templates when setting up dialogues or commands for agents to ensure they are correctly interpreted by the underlying LLMs.
+ */
+
 import { zodToJsonSchema } from "zod-to-json-schema";
 
 const ReActAgentEnhancedPrompt = `

src/utils/tasks.js

@@ -1,3 +1,13 @@
+/**
+ * Task Utility Functions.
+ *
+ * This file includes utility functions for managing task properties and behaviors within the AgenticJS library. It offers 
+ * capabilities to interpolate task descriptions with dynamic data and retrieve concise titles for logging purposes.
+ *
+ * Usage:
+ * Implement these utilities to dynamically manage task data and enhance logging outputs with more informative task descriptions.
+ */
+
 function getTaskTitleForLogs(task) {
     return task.title || (task.description ? task.description.split(" ").slice(0, 3).join(" ") + '...' : 'Untitled');
   }

xscripts/codeSnapshot.js

@@ -0,0 +1,90 @@
+const fs = require('fs');
+const path = require('path');
+const util = require('util');
+
+const readdir = util.promisify(fs.readdir);
+const readFile = util.promisify(fs.readFile);
+const writeFile = util.promisify(fs.writeFile);
+const stat = util.promisify(fs.stat);
+
+const INSTRUCTIONS_PROMPT = `This markdown document provides a comprehensive snapshot of the entire codebase for the AgenticJS library. It is designed to facilitate easy understanding and navigation of the library's structure and contents for both developers and automated systems.
+
+**Directory Structure**
+
+The 'Directory Structure' section visually represents the hierarchical arrangement of all files and directories within the AgenticJS project. This tree-like structure helps in quickly locating files and understanding the organizational layout of the project.
+
+**File Contents**
+
+Following the directory structure, the 'File Contents' section includes detailed listings of each JavaScript file within the AgenticJS library. Each file entry is prefixed with its relative path from the base directory, ensuring clear context and easy access. The content of each file is enclosed in code blocks, formatted for JavaScript, providing exact details of the code written in the library`;
+
+
+const baseDirectory = './src';  // Adjust the base directory as needed
+const outputFilePath = './output.md';
+
+// Function to recursively get all file paths
+async function getFiles(dir) {
+    const subdirs = await readdir(dir);
+    const files = await Promise.all(subdirs.map(async (subdir) => {
+        const res = path.resolve(dir, subdir);
+        return (await stat(res)).isDirectory() ? getFiles(res) : res;
+    }));
+    return files.reduce((a, f) => a.concat(f), []);
+}
+
+// Function to generate directory tree structure
+async function generateDirStructure(dir, prefix = '') {
+    const dirContents = await readdir(dir, { withFileTypes: true });
+    let structure = '';
+    for (const dirent of dirContents) {
+        const filePath = path.resolve(dir, dirent.name);
+        if (dirent.isDirectory()) {
+            structure += `${prefix}└── ${dirent.name}\n`;
+            structure += await generateDirStructure(filePath, `${prefix}    `);
+        } else if (!dirent.name.startsWith('_DONTUSE')) {
+            structure += `${prefix}└── ${dirent.name}\n`;
+        }
+    }
+    return structure;
+}
+
+// Function to create the markdown document
+async function createMarkdownFile(files, dirStructure) {
+    let markdownContent = `# Code Snapshot for AgenticJS\n\n`;
+    markdownContent += `${INSTRUCTIONS_PROMPT} \n\n`;
+    markdownContent += `## Directory Structure\n\n\`\`\`\n${dirStructure}\`\`\`\n\n`;
+    markdownContent += `## File Contents\n\n`;
+    for (const file of files) {
+        const fileName = path.basename(file);
+        if (path.extname(file) === '.js' && !fileName.startsWith('_DONTUSE')) {
+
+            let relativePath = path.relative(baseDirectory, file);
+            relativePath = path.normalize(relativePath).replace(/\\/g, '/'); // Normalize and replace backslashes
+            relativePath = `./src/${relativePath}`; // Prepend with ./src/
+
+            // // Normalize the path here before printing
+            // let relativePath = path.relative(path.resolve(__dirname, baseDirectory), file);
+            // // relativePath = `./${relativePath}`; // Ensures path starts with ./
+            // relativePath = `./src/${relativePath}`; // Ensures path starts with ./src/
+            // relativePath = relativePath.replace(/\\/g, '/'); // Normalize Windows paths
+
+            const content = await readFile(file, 'utf8');
+            markdownContent += `### ${relativePath}\n\n`;
+            markdownContent += "```js\n";
+            markdownContent += `//--------------------------------------------\n`;
+            markdownContent += `// File: ${relativePath}\n`;
+            markdownContent += `//--------------------------------------------\n\n`;
+            markdownContent += `${content}\n`;
+            markdownContent += "```\n\n";
+        }
+    }
+    await writeFile(outputFilePath, markdownContent, 'utf8');
+}
+
+// Main function to execute the script
+async function main() {
+    const files = await getFiles(baseDirectory);
+    const dirStructure = await generateDirStructure(baseDirectory);
+    await createMarkdownFile(files, dirStructure);
+}
+
+main().catch(err => console.error(err));