| title | emoji | colorFrom | colorTo | sdk | sdk_version | app_file | pinned | hf_oauth | hf_oauth_scopes | license | short_description | tags | sponsors | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
RUCHE |
💬 |
yellow |
purple |
gradio |
6.0.1 |
app.py |
false |
true |
|
mit |
ROS2-based Unified Control for Hugging-face Embodied-agents |
|
Gradio, Hugging Face, OpenAI |
TL;DR FOR MCP-1ST-BIRTHDAY REVIEWERS
- README file of Space "RUCHE" on Hugging Face org "MCP-1st-Birthday"
- Link to the Final Video
- Links to posts on Social Media: Discord, Instagram, LinkedIn,
- Used products:
- The team behind RUCHE
Project RUCHE (acronym of ROS2-based Unified Control for Hugging-face Embodied-agents) is an Open Source project developed by the B-AROL-O Team.
Additionally, Ruché is a red Italian wine grape variety from the Piedmont region, hence the name RUCHE was chosen to continue the B-AROL-O Team tradition of giving wine-sounding names to our projects, along the line of ARNEIS, FREISA, RAMIE, etc.
Here is a short video which explains what the RUCHE project is able to do:
In a nutshell, RUCHE is a Gradio-based chatbot which allows a person to interact and control one or more robots using natural language instead of sending low-level commands or communicating using ROS topics.
The RUCHE project was created in response to the "MCP's 1st Birthday" Virtual Hackathon, hosted by Anthropic and Gradio with additional support from Hugging Face, OpenAI, Gemini, Modal, Sambanova, ElevenLabs, Blaxel, Llamaindex and Nebius.
The team released RUCHE v1.0.0 on 2025-11-30 - a few hours before the closure time of the Hackathon.
Here is a simplified block diagram which illustrates the main components of the RUCHE System Architecture and their interactions:
The following sections provide more details of the main blocks shown in the architecture diagram.
For simplicity the components are grouped in packages which represent where the components have been deployed during the MCP-1st-Birthday Hackathon.
However, most of the software components in the RUCHE architecture can run inside Docker Containers, therefore they may be relocated quite easily - for instance, they can be executed inside a Dev Container and debugged using Visual Studio Code as explained in chapter "How to run the RUCHE project".
The core of the RUCHE application is app.py, a Gradio 6 application which can be deployed either inside a Hugging Face Space, or locally in a Dev Container for development and test.
The main app.py implements a chatbot which acts as a main interface to the end user.
The chatbot waits for user inputs, then performs the inference using a LLM (Large Language Model) to analyze the user prompt and execute a suitable action in response.
In order to interact with the robots and provide more context to the LLM, app.py uses the tools exposed by ros-mcp-server, a dedicated MCP server whose purpose is to expose to the LLM the topics provided by ruche_ros2_control - one of the ROS 2 Jazzy nodes which are available inside the ros2_pkg package.
In its current implementation, the Large Language Model is provided by one Inference Provider available through Hugging Face InferenceClient API.
This approach simplified a lot the deployment of the RUCHE application, which did not have to deal with installing and running the LLM locally.
Additionally, Hugging Face Hub provides an easy way for testing different LLMs - for the MCP-1st-Birthday Hackathon we chose gpt-oss-20b released by OpenAI which the B-AROL-O team had already successfully used in the previous project FREISA-GPT. However, other more sophisticated models can easily be selected by means of a simple parameter change in the InferenceClient() constructor inside app.py.
This ROS 2 package uses a ros2_control controller to control either a simulated or a real robot for the RUCHE project.
We chose to adopt the standard ros2_control framework in order to be able to easily interface with other mainstream ROS 2 applications such as Gazebo, RViz, etc.
In its current implementation, RUCHE ros2_pkg consists of two ROS 2 nodes:
-
The
ruche_ros2_controlnode which may be configured to control either a simulated robot, or a physical one and exposes a unified interface. -
The
ros2_bt_bridgehas the purpose to translate ROS 2 topics and commands to simple messages which are broadcasted using the BLE (Bluetooth Low Energy) protocol.
In order to communicate with the BLE device, ros2_bt_bridge uses the Python Bleak package which provides an abstraction of the BLE device on Windows, Linux and macOS.
For the sake of demonstrating the control of a physical robot, we chose the Elegoo Smart Car Kit v3 - an inexpensive four-wheeled robot which is ideal for education. However, the architecture of RUCHE is quite flexible and may easily be adapted to more sophisticated and capable robots.
The BLE messages sent by ros2_bt_bridge are captured by the BLE-to-UART dongle and delivered to the UART which is connected to the Arduino UNO installed on the robot.
An Arduino sketch running on the Arduino UNO is running the control loop which acts on the following inputs:
- Commands received from the UART
- Distance retrieved from the ultrasonic sensor
and provides the following output:
- Power to the four DC Motors (rotation performed through differential drive)
- Position of the Servo Motor for rotating the ultrasonic sensor
- Send the updated robot state through the UART
The main branch of the RUCHE project is automatically synchronized to space https://huggingface.co/spaces/MCP-1st-Birthday/RUCHE, therefore to run the project you can simply open this URL inside a web browser
- Click Sign in with Hugging Face, then enter your message and wait for the results
You can use GitHub Codespaces to create a Development Environment for the RUCHE project:
-
From your browser open https://github.com/B-AROL-O/RUCHE
-
Choose either the
main(production) branch or other branches / Pull Requests you want to test -
Click the <> Code button, then in tab "Codespaces" click + to create a new codespace
-
Open a bash Terminal and type:
# Login to Hugging Face uv run hf auth login # Run the RUCHE chatbot app uv run app.py
-
Continue as described in section "Inside the Hugging Face Space"
The RUCHE project can easily be run using a Development Container.
Prerequisites:
- A laptop or desktop PC running a recent version of Windows, macOS or Linux
- Visual Studio Code with the following extensions: Dev Containers
- A recent release of Docker (either Docker Engine or Docker Desktop)
Create a local Development Environment with the following steps:
-
Launch Visual Studio
-
Open the Command Palette and type:
Git: Clone
then specify the repository: https://github.com/B-AROL-O/RUCHE
-
Open the Command Palette and type:
Dev Containers: Rebuild and Reopen in Container
-
Open a bash Terminal and type:
# Login to Hugging Face uv run hf auth login # Run the RUCHE chatbot app uv run app.py
-
Read the instructions displayed in the terminal and open the link in your browser
-
Continue as described in section "Inside the Hugging Face Space"
The B-AROL-O Team welcomes external contributions 🙏🙏
Contributions may consist either of implementation of features or bugfixes (but we can also accept donation of hardware and/or beverages 😉).
If you need a suggestion about what you may contribute, please have a look at the issues in the RUCHE backlog with the help wanted label.
Contributions will be subject to the project license terms (documented in chapter "Copyright and License" below) and they may be delivered as standard Pull Requests.
Before being accepted, a Pull Requests must pass all the checks, then it will be reviewed by one or more Project Maintainers who may request changes. If the PR is accepted, the maintainer will merge it into the main branch of the RUCHE codebase.
All the authors of Pull Requests which have been accepted and merged are listed in this page.
Please help us make the RUCHE project even better!
The RUCHE codebase contains a few *.excalidraw.json files, which are diagrams created using the Excalidraw tool.
To view or modify the diagrams you have several options as detailed below.
From your preferred browser, open https://excalidraw.com/, then click the "Hamburger" icon at the top left of the page and select the Open menu.
Locate the *.excalidraw.json file on your file system, or download it first. The diagram will then be displayed on your browser.
From Excalidraw you will then have several options, such as exporting the diagram as a *.png or *.svg file, modifying the diagram, saving the file after the diagram was modified, etc.
If you are browsing the RUCHE codebase inside Visual Studio Code, make sure you have the Excalidraw Extension installed.
NOTE: The extension is already pre-installed in the RUCHE Dev Container.
Right click the file *.excalidraw.json > Open With..., then select the Excalidraw editor.
If you are browsing the RUCHE codebase from https://vscode.dev, make sure you have the Visual Studio Code Excalidraw Extension installed.
Right click the file *.excalidraw.json > Open With..., then select the Excalidraw editor.
For more specific help about how to use Excalidraw, please refer to the documentation available at https://docs.excalidraw.com/.
The RUCHE project has strict code rules, which are enforced with Super-Linter. All Super-Linter checks must pass before a Pull-Request can be reviewed and merged.
While this might might discourage some potential contributors, we chose to adopt Super-Linter to mitigate the risk of conflicts and reduce the chances that buggy code will go straight to production.
If you run into troubles with Super-Linter when you push your feature branch or create a Pull Request, please refer to the Super-Linter documentation.
If you believe that some Super-Linter rules should be relaxed, consider adding a new a Super-Linter configuration rule or modifying an existing one:
- The Super-Linter GitHub workflow can be inspected at
.github/workflows/linter.yml - The files which override the default configuration for each linter are stored under
.github/linters/ - The default configuration of all linters can be inspected at https://github.com/super-linter/super-linter/tree/main/TEMPLATES
Prettier is an opinionated Code Formatter which is able to check and verify the structure of source files in serveral formats, such as Markdown, Python and others. Most Super-Linter checks ensure that the code in the RUCHE codebase aligns with Prettier preferred formatting.
To verify that one or more files are in line with Super-Linter expectations you can run the following command:
prettier filenameIf Prettier notices some misalignment you can easily reformat them before creating the Pull Request:
prettier -w filenameYou may follow @baroloteam on Instagram or @baroloteam on X to get notified about the progress of the RUCHE project.
Please report bugs and feature requests on https://github.com/B-AROL-O/RUCHE/issues, or DM B-AROL-O Team on X about security issues or other non-public topics.
Copyright (C) 2025, B-AROL-O Team, all rights reserved.
NOTE: This repository is based upon https://github.com/arol-polito/python-project-template.
The source code contained in this repository and the executable distributions are licensed under the terms of the MIT license as detailed in the LICENSE file.
Please note that your contribution to the project Documentation is licensed under a Creative Commons Attribution-Share Alike 4.0 License. see https://creativecommons.org/licenses/by-sa/4.0/