6.1.3. VulcanAI Console and manager

Note

VulcanAI is currently in active development, and new features and improvements are being added regularly. Current version is in Beta stage.

In the previous tutorial (Tools for Turtlesim), we created a package that contains a shared ROS 2 node and the tools needed to control TurtleSim using VulcanAI. Now, we will create the main script that will be used to run the VulcanAI console and manage the interaction between the user, the agent, and the tools.

VulcanAI console is a command-line interface that allows users to interact with the VulcanAI agent. It provides a simple way to input natural language commands and check the agent’s responses. VulcanAI console already includes the manager that handles the creation and management of agents, tools, and user contexts. Therefore, we only need to create a script that initializes the console, registers the tools we created, and starts the interaction loop.

6.1.3.1. Write the main method

In the same file where we define the SharedNode class, we can write the main method that will be used as the entry point for the package.

Just add the following content at the end of the ros2_node.py file:

def main(args=None):
    # Create a ROS 2 node that will be used by the tools to avoid
    # recurrent creation and destruction of DDS Participants
    rclpy.init(args=args)
    node = SharedNode(name="vulcanai_shared_node")

    user_context = """\
You are controlling the turtlesim simulation from ROS 2.
The simulation has one or more turtles that can move around, drawing on the screen as they go."""

    console = VulcanConsole()
    console.manager.register_tools_from_entry_points("turtle_tools")
    console.manager.add_user_context(user_context)
    # Add the shared node to the console manager blackboard to be used by tools
    console.manager.bb["main_node"] = node
    console.run()


if __name__ == '__main__':
    main()

And the following include at the beginning of the file:

from vulcanai import VulcanConsole

6.1.3.1.1. Examine the code

First, we initialize the rclpy library and create an instance of the SharedNode class.

rclpy.init(args=args)
node = SharedNode(name="vulcanai_shared_node")

Then, we write a brief context that will inform the agent about the purpose of the node, which is to control TurtleSim.

    user_context = """\
You are controlling the turtlesim simulation from ROS 2.
The simulation has one or more turtles that can move around, drawing on the screen as they go."""

Next, we will use the VulcanConsole as the main interface for the user to interact with the agent. This object already includes all classes and logic necessary to create and manage agents, tools and user contexts. We only need to specify the name of the module where the tools will be installed after building the package, and add the user context to the console manager.

console = VulcanConsole()
console.manager.register_tools_from_entry_points("turtle_tools")
console.manager.add_user_context(user_context)

Finally, we manually add the shared node to the console manager blackboard, so it can be accessed by the tools and call the run method to start the console.

# Add the shared node to the console manager blackboard to be used by tools
console.manager.bb["main_node"] = node
console.run()

The last two lines call the main method when the script is executed directly.

if __name__ == '__main__':
    main()

As you can see, the main method is quite simple, as most of the complexity is encapsulated in the SharedNode class. Instantiating the console and registering the tools is very straightforward.

6.1.3.2. Build the package

Now, we only need to build the package and run the ros2_node.py script to start the console and interact with the agent.

However, we will first add the recently created ros2_node.py file to the setup.py file, so it can be installed and run using the ros2 run command. Additionally, we will create a new entry-point for the package, where we will install the tools. Replace the entry_points section of the setup.py file with the following content:

entry_points={
    "console_scripts": [
        "vulcanai_turtlesim_demo = vulcanai_turtlesim_demo.ros2_node:main",
    ],
    "turtle_tools": [
        "turtle_tools = vulcanai_turtlesim_demo.turtlesim_tools",
    ],
},

Then, go to the root of your workspace and build the package:

cd ~/<your_workspace> && \
source /opt/vulcanexus/${VULCANEXUS_DISTRO}/setup.bash && \
colcon build --packages-select vulcanai_turtlesim_demo && \
source install/setup.bash

Remember that if VulcanAI is installed in a virtual environment, you need to activate it before sourcing the workspace. Check the Running VulcanAI from virtual environment with Vulcanexus section for more details.

After successfully building the package, the node is ready to be launched and tested. Continue with the Using VulcanAI to control TurtleSim tutorial to learn how to use the created tools to control TurtleSim through natural language instructions.

6.1.3.3. Get all the code

Instead of following all the steps in the VulcanAI Tools and VulcanAI Console and manager tutorials, you can also get all the code with the following command:

cd ~/<your_workspace> && \
mkdir temp && \
mkdir src && \
git clone https://github.com/eProsima/vulcanexus.git temp/ && \
cp -r temp/code/vulcanai_turtlesim/vulcanai_turtlesim_demo src/. && \
rm -rf temp/ && \
source /opt/vulcanexus/${VULCANEXUS_DISTRO}/setup.bash && \
colcon build --packages-select vulcanai_turtlesim_demo && \
source install/setup.bash

Remember to replace <your_workspace> with the path to your ROS 2 workspace. The code will be downloaded to the src/vulcanai_turtlesim_demo folder of your workspace and can be directly built and run. Getting the code this way is equivalent to following all the steps in the previous tutorials.