RobotecAI · maciejmajek · Jun 3, 2025 · May 29, 2025 · May 29, 2025 · May 29, 2025
diff --git a/docs/demos/agriculture.md b/docs/demos/agriculture.md
@@ -15,19 +15,21 @@ optimally by calling the RAI agent to decide what to do.
     Ensure that every command is run in a sourced shell using `source setup_shell.sh`
     Ensure ROS 2 is sourced.
 
-1. **Download the Latest Release**
+1. Follow the RAI setup instructions in the [quick setup guide](../setup/install.md#setting-up-developer-environment).
+
+2. Download the Latest Release
 
     ```bash
     ./scripts/download_demo.sh agriculture
     ```
 
-2. **Run the Simulation**
+3. Run the Simulation
 
     ```bash
     ./demo_assets/agriculture/RAIAgricultureDemo/RAIAgricultureDemo.GameLauncher -bg_ConnectToAssetProcessor=0
     ```
 
-3. **Start the Tractor Node**
+4. Start the Tractor Node
 
     ```bash
     python examples/agriculture-demo.py --tractor_number 1

diff --git a/docs/demos/debugging_assistant.md b/docs/demos/debugging_assistant.md
@@ -18,8 +18,7 @@ where you can ask questions about your ROS 2 setup and execute common debugging
 
 ## Running the Assistant
 
-1. Make sure you have RAI installed and configured according to the
-   [quick setup guide](../setup/install.md)
+1. Follow the RAI setup instructions in the [quick setup guide](../setup/install.md#setting-up-developer-environment).
 
 2. Launch the debugging assistant:
 

diff --git a/docs/demos/manipulation.md b/docs/demos/manipulation.md
@@ -18,7 +18,7 @@ manipulation techniques.
 
     Make sure ROS 2 is sourced. (e.g. `source /opt/ros/humble/setup.bash`)
 
-1. Follow the RAI setup instructions in the [quick setup guide](../setup/install.md).
+1. Follow the RAI setup instructions in the [quick setup guide](../setup/install.md#setting-up-developer-environment).
 2. Download additional dependencies:
 
     ```shell

diff --git a/docs/demos/rosbot_xl.md b/docs/demos/rosbot_xl.md
@@ -16,13 +16,15 @@ platform in a nice apartment.
 
     Make sure ROS 2 is sourced. (e.g. `source /opt/ros/humble/setup.bash`)
 
-1. Download the newest binary release:
+1. Follow the RAI setup instructions in the [quick setup guide](../setup/install.md#setting-up-developer-environment).
+
+2. Download the newest binary release:
 
     ```bash
     ./scripts/download_demo.sh rosbot
     ```
 
-2. Install and download required packages
+3. Install and download required packages
 
     ```bash
     sudo apt install ros-${ROS_DISTRO}-navigation2 ros-${ROS_DISTRO}-nav2-bringup

diff --git a/docs/setup/install.md b/docs/setup/install.md
@@ -1,16 +1,65 @@
 # Quick setup guide
 
-Before going further, make sure you have ROS 2 (Jazzy or Humble) installed and sourced on your
-system. If you don't have ROS 2 follow the installation documentation for
-[Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debs.html) or
-[Jazzy](https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debs.html). Make sure that
-`ros-dev-tools` are installed.
+Before going further, make sure you have ROS 2 (jazzy or humble) installed and sourced on your system.
 
 !!! tip "Docker images"
 
     RAI has experimental docker images. See the [docker](setup_docker.md) for
     instructions.
 
+There are two ways to start using RAI:
+
+1. Installing RAI using pip (recommended for end users)
+
+2. Setting up a developer environment using poetry (recommended for developers)
+
+## Installing RAI
+
+??? tip "Virtual environment"
+
+    We recommend installing RAI in a virtual environment (e.g., [virtualenv](https://docs.python.org/3/library/venv.html), [uv](https://docs.astral.sh/uv/), or [poetry](https://python-poetry.org/docs/)) to keep your dependencies organized. Make sure to use the same version of python as the one used for ROS 2 (typically `python3.10` for Humble and `python3.12` for Jazzy).
+
+    If you plan to use ROS 2 commands (`ros2 run` or `ros2 launch`), you'll need to add your virtual environment's Python packages to your `$PYTHONPATH`. This step is only necessary for ROS 2 integration - if you're just running RAI directly with Python, you can skip this step.
+
+    For reference, here's how to set this up when installing RAI from source: [setup_shell.sh](https://github.com/RobotecAI/rai/blob/245efa95cdb83a81294bc28da814962bff84be20/setup_shell.sh#L32)
+
+1.  Install core functionality:
+
+    ```bash
+    pip install rai-core
+    ```
+
+2.  Initialize the global configuration file:
+
+    ```bash
+    rai-config-init
+    ```
+
+3.  Optionally install ROS 2 dependencies:
+
+    ```bash
+    sudo apt install ros-${ROS_DISTRO}-rai-interfaces
+    ```
+
+!!! important "Package availability"
+
+    `rai_openset` and `rai_nomad` are not yet available through pip. If your workflow relies on openset detection or NoMaD integration, please refer to the
+    [developer environment instructions](#setting-up-developer-environment) setup.
+
+    `rai_interfaces` is available as `apt` package. However, due to package distribution delays, the latest version may not be immediately available. If you encounter missing imports, please build `rai_interfaces` from [source](https://github.com/RobotecAI/rai_interfaces).
+
+??? tip "RAI modules"
+
+    RAI is a modular framework. You can install only the modules you need.
+
+    | Module | Description | Documentation |
+    |--------|-------------|-------------|
+    | rai-core | Core functionality | [link](../API_documentation/overview.md) |
+    | rai-whoami | Embodiment module | [link](https://github.com/RobotecAI/rai/tree/{{branch}}/src/rai_whoami) |
+    | rai-s2s | Speech-to-Speech module | [link](../speech_to_speech/overview.md) |
+    | rai-sim | Simulation module | [link](../simulation_and_benchmarking/overview.md) |
+    | rai-bench | Benchmarking module | [link](../simulation_and_benchmarking/overview.md) |
+
 ??? tip "RAI outside of ROS 2"
 
     RAI can be used outside of ROS 2. This means that no ROS 2 related features will be available.
@@ -23,7 +72,7 @@ system. If you don't have ROS 2 follow the installation documentation for
 
     If you later decide to integrate with ROS 2, you can simply install and source ROS 2, and all ROS 2-specific RAI features (such as connectors, aggregators, and tools) will become available automatically.
 
-## 1. Setting up the workspace:
+## Setting up developer environment
 
 ### 1.1 Install poetry
 

diff --git a/docs/setup/vendors.md b/docs/setup/vendors.md
@@ -93,5 +93,5 @@ For configuration use `Speech Recognition` tab in [RAI Configurator][configurato
 
 Usage examples can be found in [Voice Interface Tutorial][s2s]
 
-[configurator]: ./install.md#14-configure-rai
+[configurator]: ./install.md#15-configure-rai
 [s2s]: ../tutorials/voice_interface.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -74,6 +74,7 @@ nav:
   - Home:
     - Overview: index.md
     - Is RAI a good fit for me?: intro/what_is_rai.md
+    - Getting started: setup/install.md
   - Getting started:
     - Local setup: setup/install.md
     - Docker setup: setup/setup_docker.md

diff --git a/src/rai_core/README.md b/src/rai_core/README.md
@@ -2,11 +2,6 @@
 
 RAI is a flexible AI agent framework to develop and deploy Embodied AI features for your robots.
 
-📚 Visit [robotecai.github.io/rai](https://robotecai.github.io/rai/) for the latest documentation, setup
-guide and tutorials. 📚
-
----
-
 <div align="center">
 
 ![rai-image](https://raw.githubusercontent.com/RobotecAI/rai/refs/heads/development/docs/imgs/RAI_simple_diagram_medium.png)
@@ -30,6 +25,29 @@ guide and tutorials. 📚
 
 ---
 
+## Installation
+
+1. Install RAI:
+
+```bash
+pip install rai-core
+```
+
+2. Initialize the global configuration file:
+
+```bash
+rai-config-init
+```
+
+3. Optionally install ROS 2 dependencies:
+
+```bash
+sudo apt install ros-${ROS_DISTRO}-rai-interfaces
+```
+
+For more visit [robotecai.github.io/rai](https://robotecai.github.io/rai/) for the latest documentation, setup
+guide and tutorials.
+
 ## 🎯 Overview
 
 | Category                       | Description                                       | Features                                                                                                                                                           |

diff --git a/src/rai_whoami/README.md b/src/rai_whoami/README.md
@@ -9,6 +9,29 @@ It generates a comprehensive system prompt (embodiment info) for robots controll
 
 ---
 
+## Installation
+
+1. Install rai whoami:
+
+```bash
+pip install rai-whoami
+```
+
+2. Initialize the global configuration file (if not already done):
+
+```bash
+rai-config-init
+```
+
+3. Optionally install ROS 2 dependencies:
+
+```bash
+sudo apt install ros-${ROS_DISTRO}-rai-interfaces
+```
+
+For more visit [robotecai.github.io/rai](https://robotecai.github.io/rai/) for the latest documentation, setup
+guide and tutorials.
+
 ## How It Works
 
 Given a directory containing robot documentation (documents, images, URDFs), RAI Whoami processes these resources to produce a structured representation of the robot, including: