ros2ai 🤖

ros2ai is a next-generation ROS 2 command line interface extension with OpenAI and Ollama.

see overview slide deck for more information.

Motivation

• (Just for fun 😝)
• Getting answers against the questions directly without browsing, clicking and typing many times.
• Easy to use for everyone, especially for ROS 2 beginners and students who do not really know ros2cli.
• Multiple language support.
• Multiple LLMs support (with OpenAI Python API)

Demo 🖥️

See how it works 🔥

https://github.com/fujitatomoya/ros2ai/assets/43395114/78a0799b-40e3-4dc8-99cb-488994e94769

Supported ROS Distribution

Installation

Docker Container

see available images for tomoyafujita/ros2ai@dockerhub

docker run -it --rm --net=host -e OPENAI_API_KEY=$OPENAI_API_KEY tomoyafujita/ros2ai:humble

[!NOTE] OPENAI_API_KEY environmental variable is not required if using Ollama. And it is expecting that Ollama runs on the host system mostly, so that container is bound to the host network interface.

https://github.com/fujitatomoya/ros2ai/assets/43395114/2af4fd44-2ccf-472c-9153-c3c19987dc96

Required Package

• rolling / kilted / jazzy

  pip install openai ollama validators --break-system-packages --ignore-installed
  

[!NOTE] see PEP 668 – Marking Python base environments as “externally managed” why --break-system-packages is required.

• humble

  pip install openai ollama validators --ignore-installed
  

Build

No released package is available, needs to be build in colcon workspace.

source /opt/ros/rolling/setup.bash
mkdir -p colcon_ws/src
cd colcon_ws/src
git clone https://github.com/fujitatomoya/ros2ai.git
cd ..
colcon build --symlink-install --packages-select ros2ai

Usage

Prerequisites

As described in overview diagram, ros2ai uses only OpenAI Python API but backend implementation can be replaced with Ollama that provides the compatible API with OpenAI. User need to choose either of them is used by ros2ai as following configuration, otherwise it falls back to use OpenAI.

• OpenAI

  ros2ai requires OpenAI API key

  export OPENAI_API_KEY='your-api-key-here'
  

[!CAUTION] Do not share or expose your OpenAI API key.

• Ollama

  ros2ai requires Ollama service running, see more details for How to install Ollama to Linux

File truncated at 100 lines see the full file

Changelog for package ros2ai

0.1.1 (2025-11-06)

• Support Kilted Kaiju with docker image. (#67)
• change OPENAI_TEMPERATURE default into 1.0.
• enable gemini-cli github action. (#64)
• support codespell check via github action. (#61)
• add nightly workflow files for each distro. (#57)
• remove Iron Irwini support, which is E.O.L. (#56)
• use 127.0.0.1 instead of localhost that is invalid URL by validator. (#53)
• Fix a typo in package.xml (#50)
• enable blank_issues_enabled.
• update issue templates.
• add issue templates. (#48)
• ROSCon 2024 talk slide (draft) (#44)
• github workflow status shows rolling branch.
• add --net=host option to docker command for Ollama use case. (#46)
• 20240916 overview update (#43)
• pull llama3.1 before example tutorial.
• add mirror-rolling-to-main.yaml.
• add architecture overview.
• Validate the URL before calling OpenAI APIs. (#42)
• Doc update for Ollama Support. (#40)
• remove backticks from the executable command line string.
• adjust some parameters and variables for Ollama OpenAI support (#38)
• add [--dry-run]{.title-ref} to the test script.
• Enable the use of self-hosted LLMs (#36) Co-authored-by: Tomoya Fujita <<Tomoya.Fujita@sony.com>>
• joke sub-command is not gonna be developed.
• Jazzy Jalisco support (#33)
• docker command should be checked before docker login.
• some comment fixes with gpt-4o.
• configure AI model with [gpt-4o]{.title-ref} by default. (#32)
• add signal handler for SIGINT and SIGTERM. (#29)
• add [--break-system-packages]{.title-ref} option to pip install.
• fix openai rosdep (#27)
• minor script bug fix.
• ROS distribution is always set with completion API.
• add ROS Developers POdcast interview.
• fetch ROS_DISTRO env value to set completion request. (#24)
• script bug fix.
• add demo video with docker containers in marp.
• add doc section for docker container support. (#20)
• fujitatomoya/support dockerfiles and test (#18)
• add workflows badges in the top page.
• support github workflows with rolling distro. (#15)
• add overview slide deck on the top README.md
• update package.xml
• support temperature param for chat.completion.
• add html version presentation slide deck.
• update oveview markdown presentation.
• add overview markdown presentation with proposals.
• update README.md
• support execute subcommand. (#9)
• add system attribution for query command.
• change copyright into the correct one.
• remove redundant class just for stream option.
• support max token via command line option.
• change default model into gpt-4 since it has better response time.
• default streaming response.
• support streaming responses. (#4)
• support list option for status subcommand to show models.
• support query subcommand. (#1)
• add add_global_arguments method.
• ros2ai status subcommand support.
• add class OpenAiConfig.
• command stub completed for ai and status command.
• add config methods and constants.
• add mock command line for ros2ci.
• add basic ros2 package structure.
• Initial commit
• Contributors: Tomoya Fujita, Barry Xu, Jeremie Deray