Merge pull request #47 from srajan-kiyotaka/sracho

added API Refference.

docs/Agent.md

@@ -0,0 +1,13 @@
+# Agent Module API Reference
+
+## Overview
+
+The Agent module provides implementations for different types of agents that operate in various environments.
+
+### Classes
+
+- **GridAgent**: Represents an agent designed to navigate and perform actions within a grid-based environment. For detailed information on the `GridAgent` class and its methods, refer to [GridAgent Documentation](./gridAgent.md).
+
+- **TreeAgent**: Represents an agent specifically designed to navigate and manipulate tree structures. For detailed information on the `TreeAgent` class and its methods, refer to [TreeAgent Documentation](./treeAgent.md).
+
+- **GraphAgent**: Represents an agent specialized in navigating and interacting with graph-based environments. For detailed information on the `GraphAgent` class and its methods, refer to [GraphAgent Documentation](graphAgent.md).

docs/DataStructures.md

@@ -0,0 +1,46 @@
+# Data Structures Module
+
+The Data Structures module provides fundamental classes for constructing and manipulating tree and graph structures used within the World module.
+
+## TreeNode Class
+
+The `TreeNode` class represents a node in a tree structure. It encapsulates the following attributes:
+
+- `id` (int or str): Unique identifier for the node.
+- `val` (any, optional): Value associated with the node. Defaults to `label` if not provided.
+- `children` (list of TreeNode objects): List of child nodes.
+- `edges` (list of int or float, optional): List of edge weights corresponding to each child node. Defaults to a list of 1s if not provided and children are present.
+- `isGoalState` (bool): Indicates if the node is a goal state.
+- `_heatMapValue` (int): Internal attribute used for heat map visualization (default is 0).
+
+### Methods
+
+- `__init__(self, label, children: list, val=None, isGoalState: bool = False, edges: list = [])`: Initializes a TreeNode instance.
+- `__str__(self) -> str`: Returns a string representation of the TreeNode object.
+
+The `TreeNode` class is used extensively in the World module to build hierarchical tree structures. Users can instantiate `TreeNode` objects and customize them by inheriting from the class to add additional attributes or methods tailored to specific applications.
+
+## GraphNode Class
+
+The `GraphNode` class represents a node in a graph structure. It encapsulates the following attributes:
+
+- `id` (int or str): Unique identifier for the node.
+- `val` (any, optional): Value associated with the node. Defaults to `label` if not provided.
+- `neighbors` (list of GraphNode objects): List of neighboring nodes.
+- `edges` (list of int or float, optional): List of edge weights corresponding to each neighboring node. Defaults to a list of 1s if not provided and neighbors are present.
+- `isGoalState` (bool): Indicates if the node is a goal state.
+- `_heatMapValue` (int): Internal attribute used for heat map visualization (default is 0).
+
+### Methods
+
+- `__init__(self, label, neighbors: list, val=None, isGoalState: bool = False, edges: list = [])`: Initializes a GraphNode instance.
+- `__str__(self) -> str`: Returns a string representation of the GraphNode object.
+
+The `GraphNode` class is used in the World module to construct complex networked structures. Users can instantiate `GraphNode` objects and extend their functionality by inheriting from the class to introduce additional attributes or methods specific to their needs.
+
+## Customization
+
+These classes provide a solid foundation for creating and manipulating tree and graph structures within the World module. For specialized requirements, users are encouraged to inherit from `TreeNode` and `GraphNode` classes to tailor them according to specific application scenarios.
+
+By leveraging these customizable data structures, developers can effectively manage and visualize complex relationships within their simulated environments.
+

docs/World.md

@@ -0,0 +1,15 @@
+# World Module API Reference
+
+The `world` module provides functionalities to create and manage different types of worlds using Tkinter-based GUI components.
+
+## Functions
+
+### `getScreenSize() -> tuple`
+
+Returns the screen size for any operating system.
+
+**Raises:**
+- `NotImplementedError`: If the operating system is not supported.
+
+**Returns:**
+- `tuple`: A tuple containing the width and height of the screen.

docs/graphWorld.md

@@ -0,0 +1,114 @@
+# API Reference: CreateGraphWorld Class
+
+Class representing a graph world.
+
+## Constructor
+
+### `__init__(self, worldName: str, worldInfo: dict, radius: int = 20, fontSize: int = 12, fontBold: bool = True, fontItalic: bool = True, nodeColor: str = "gray", goalColor: str = "green", width: int = SCREEN_WIDTH, height: int = SCREEN_HEIGHT, lineThickness: int = 2, arrowShape: tuple = (10, 12, 5), buttonBgColor: str = "#7FC7D9", buttonFgColor: str = "#332941", textFont: str = "Helvetica", textSize: int = 24, textWeight: str = "bold", buttonText: str = "Start Agent", logoPath: str = None)`
+
+The constructor method for CreateGraphWorld, which initializes an instance of the class representing a graph world. It takes various parameters such as worldName, worldInfo, and optional parameters for visualization settings like radius, fontSize, and nodeColor. It sets up the graphical representation of the world using Tkinter for visualization and constructs the graph data structure based on the provided worldInfo.
+
+#### Parameters
+
+- `worldName` (str): The name of the world.
+- `worldInfo` (dict): Dictionary containing information about the world.
+  - 'goals' (list): List of goal node IDs.
+  - 'adj' (dict): Adjacency list representing graph connections.
+  - 'position' (dict): Dictionary of node positions with node IDs as keys.
+  - 'edges' (dict, optional): Dictionary of edge information. Default is None.
+  - 'vals' (dict, optional): Dictionary of node values. Default is None.
+- `radius` (int): Radius of nodes in the visualization. Default is 20.
+- `fontSize` (int): Font size for node labels. Default is 12.
+- `fontBold` (bool): Whether node labels are bold. Default is True.
+- `fontItalic` (bool): Whether node labels are italic. Default is True.
+- `nodeColor` (str): Color of nodes. Default is "gray".
+- `goalColor` (str): Color of goal nodes. Default is "green".
+- `width` (int): Width of the visualization canvas. Default is SCREEN_WIDTH.
+- `height` (int): Height of the visualization canvas. Default is SCREEN_HEIGHT.
+- `lineThickness` (int): Thickness of lines connecting nodes. Default is 2.
+- `arrowShape` (tuple): Shape of arrows indicating edge directions. Default is (10, 12, 5).
+- `buttonBgColor` (str): Background color of buttons. Default is "#7FC7D9".
+- `buttonFgColor` (str): Foreground color of buttons. Default is "#332941".
+- `textFont` (str): Font family of button text. Default is "Helvetica".
+- `textSize` (int): Font size of button text. Default is 24.
+- `textWeight` (str): Font weight of button text. Default is "bold".
+- `buttonText` (str): Text displayed on buttons. Default is "Start Agent".
+- `logoPath` (str, optional): File path to the logo image. Default is None.
+
+#### Attributes
+
+- `worldID` (str): Class identifier for the graph world.
+- `nodeMap` (dict): Dictionary mapping node IDs to canvas objects.
+- `root` (TreeNode): The root of the graph data structure.
+
+## Methods
+
+### `aboutWorld()`
+
+Generates and returns a detailed textual representation of the attributes of the graph world. It uses the PrettyTable library to organize and present information such as world name, node colors, button settings, and visualization dimensions in a tabular format.
+
+#### Returns
+
+- `str`: The attributes of the world.
+
+### `summary()`
+
+Creates a summary of the graph world by generating a table that lists each node ID along with its corresponding number of visits. This method is particularly useful for visualizing statistical data related to the exploration of nodes within the graph.
+
+#### Returns
+
+- `str`: The summary of the world.
+
+### `constructWorld()`
+
+Initiates the process of constructing the graphical representation of the graph world. It calls internal methods _drawEdges, _drawNodes, and _addStartButton to draw edges between nodes, visualize nodes themselves, and add a start button for agent interaction.
+
+### `changeNodeColor(nodeId: int, color: str)`
+
+Changes the color of a specific node identified by nodeId to the new color specified by color. This method updates the visual representation on the canvas by modifying the fill color of the corresponding node object.
+
+#### Parameters
+
+- `nodeId` (int): ID of the node to change the color of.
+- `color` (str): New color to set for the node.
+
+### `changeNodeText(nodeId: int, newText: str)`
+
+Updates the text displayed on a node identified by nodeId to newText. This method modifies the text attribute of the node label object associated with the specified node on the visualization canvas.
+
+#### Parameters
+
+- `nodeId` (int): ID of the node to change the text of.
+- `newText` (str): New text to set for the node.
+
+### `getNode(nodeId: int)`
+
+Retrieves and returns the node object corresponding to the provided nodeId. This method is useful for accessing specific nodes within the graph world, allowing external components or agents to interact with individual nodes directly.
+
+#### Parameters
+
+- `nodeId` (int): ID of the node to retrieve the pointer for.
+
+#### Returns
+
+- `Node`: Pointer to the node with the given `nodeId`.
+
+### `setAgent(agent: Agent)`
+
+Sets the agent that will interact with the graph world. The agent parameter should be an instance of an agent class capable of running algorithms within the context of the graph world. This method prepares the environment for agent-based simulations or algorithms.
+
+#### Parameters
+
+- `agent` (Agent): The agent to be set.
+
+### `showWorld()`
+
+Displays the constructed graph world visualization to the user. This method starts the main event loop of the Tkinter application, allowing the graphical user interface (GUI) to render and remain interactive until the user closes the window or exits the application.
+
+### `__str__()`
+
+This method returns a string that describes the attributes of the graph world. It utilizes the aboutWorld() method to generate a human-readable summary of the key attributes such as world name, dimensions, node colors, and button settings.
+
+#### Returns
+
+- `str`: The attributes of the world.

docs/gridAgent.md

@@ -0,0 +1,80 @@
+# GridAgent Class
+
+The `GridAgent` class represents an agent that operates within a grid world environment.
+
+## Parameters
+
+- `world` (CreateGridWorld): The grid world object in which the agent operates.
+- `agentName` (str): The name of the agent.
+- `agentColor` (str, optional): The color of the agent. Defaults to "blue".
+- `heatMapView` (bool, optional): Whether to enable the heat map view. Defaults to True.
+- `heatMapColor` (str, optional): The color of the heat map. Defaults to "#FFA732".
+- `agentPos` (tuple, optional): The initial position of the agent. Defaults to (0, 0).
+- `heatGradient` (float, optional): The gradient value for the heat map. Defaults to 0.05.
+
+## Attributes
+
+- `algorithmCallBack` (function): Callback function for the agent's algorithm.
+
+## Public Methods
+
+### `__str__()`
+
+Returns a string describing the attributes of the agent.
+
+### `aboutAgent()`
+
+Prints information about the agent including its name, color, and the world it operates in.
+
+### `summary()`
+
+Returns a summary of the agent's run including start time, end time, and elapsed time.
+
+### `setStartState(i: int, j: int)`
+
+Sets the start state of the agent to the specified position (i, j) on the grid world.
+
+- Raises `ValueError` if the specified start position is invalid.
+
+### `setAlgorithmCallBack(algorithmCallBack: function)`
+
+Sets the callback function for the agent's algorithm.
+
+### `runAlgorithm()`
+
+Executes the callback function set by `setAlgorithmCallBack()`. Raises `ValueError` if the callback function is not set.
+
+### `getHeatMapColor(value: float)`
+
+Maps a numeric value to a color on the heat map.
+
+- Args:
+  - `value` (float): The value to be mapped.
+
+- Returns:
+  - `str`: The RGB color string representing the mapped value on the heat map.
+
+### `moveAgent(i: int, j: int, delay: float=0.5)`
+
+Moves the agent to the specified position (i, j) on the grid world.
+
+- Args:
+  - `i` (int): The row index of the target position.
+  - `j` (int): The column index of the target position.
+  - `delay` (float, optional): The delay in seconds before moving the agent. Defaults to 0.5 seconds.
+
+- Returns:
+  - `bool`: True if the agent successfully moves to the target position, False otherwise.
+
+### Internal Methods
+
+These methods are not intended to be directly called by users but support the functionality of the class:
+
+- `_warmerColor(color: str, sValue: float)`: Generates a warmer color from the given color based on saturation value.
+- `checkGoalState(i: int, j: int)`: Checks if the specified position (i, j) on the grid world is a goal state.
+- `checkBlockState(i: int, j: int)`: Checks if the specified position (i, j) on the grid world is blocked or empty.
+
+
+## Usage
+
+The `GridAgent` class provides methods to control the agent's movement within a grid world, interact with its environment, and visualize heat maps. It serves as a foundation for implementing agent-based simulations and experiments within defined grid-based environments.