| Name | oorb-cli JSON |
| Version |
1.0.10
JSON |
| download |
| home_page | None |
| Summary | Intelligent CLI assistant for ROS and ROS2 questions |
| upload_time | 2025-08-28 12:49:55 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
ros
ros2
chatbot
cli
robotics
ai
assistant
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# OORB CLI – Robotics coding Assistant
**OORB** (Open Organic Robotics Benchmark) is an open-source initiative focused on advancing robotics through AI-powered tools and benchmarks.
**OORB CLI** is a command-line assistant designed to answer questions and assist with tasks related to **ROS2** (Robot Operating System 2). Powered by modern language models and enhanced with vector search and retrieval-augmented generation, it serves as an intelligent tool for roboticists and developers working with ROS2.
---
## Features
* Focused exclusively on **ROS2**
* Interactive and one-shot Q&A modes
* Backend support for **OpenAI**, **Azure OpenAI**, and **Ollama**
* Local inference support with Ollama
* Retrieval-augmented answers with Milvus vector store
* **Configurable ROS distro support** - Specify your target ROS2 distribution
* **Custom retrieval endpoint support** - Use your own vector database or API
* Configurable model, temperature, and backend preferences
* **Tool calling capabilities** with access to:
- `read_file` - Read and analyze files
- `write_file` - Create and modify files
- `search_in_files` - Search across file contents
- `run_command` - Execute system commands
- `list_directory` - Browse directory structures
- `edit_file_lines` - Make precise file edits
### Recent Enhancements
* **ROS Distro Selection**: Set your preferred ROS2 distribution (humble, jazzy, rolling, etc.)
* **Custom Retrieval Endpoints**: Connect to your own vector database or knowledge API
* **Enhanced Configuration**: Multiple ways to configure settings via environment variables or CLI options
* **Endpoint Testing**: Built-in tools to test and validate retrieval API connectivity
### Note:
You can find a quick demo of the CLI on the following link : [link](https://youtu.be/6o50YBeWZ04)
---
## Installation
### Option 1: Install from PyPI (Recommended)
```bash
pip install oorb-cli
```
The CLI is available on [PyPI](https://pypi.org/project/oorb-cli/) and can be installed directly via pip.
### Option 2: Development Installation
#### 1. Clone the repository
```bash
git clone https://github.com/OORB-Open-Organic-Robotics/oorb-cli
cd oorb-cli
```
#### 2. Create virtual environment and install dependencies using `uv`
```bash
uv venv
source .venv/bin/activate
uv pip install -e .
```
This installs the CLI in *editable mode*, allowing you to make changes to the source code without reinstalling.
> **Note:** `uv pip install -e .` is functionally equivalent to `pip install -e .`, but uses `uv` for faster dependency resolution and isolated builds.
---
## Configuration
Set the appropriate API key depending on the backend you intend to use.
### OpenAI
```bash
export OPENAI_API_KEY="your-key"
```
### Azure OpenAI
```bash
export AZURE_OPENAI_API_KEY="your-key"
export AZURE_OPENAI_ENDPOINT="your-endpoint"
```
### ROS Distro Configuration
Specify your target ROS2 distribution for enhanced retrieval and distro-specific answers:
```bash
# Set default ROS distro (overrides auto-detection)
export OORB_ROS_DISTRO=humble
# Or use the standard ROS environment variable
export ROS_DISTRO=humble
```
**Supported ROS2 Distributions:**
- `humble` (LTS) - Ubuntu 20.04, 22.04
- `iron` - Ubuntu 22.04
- `jazzy` (LTS) - Ubuntu 24.04
- `rolling` - Latest development version
- Legacy ROS1: `noetic`, `melodic`
### Custom Retrieval Endpoint
Configure your own vector database or retrieval API:
```bash
# Use custom retrieval endpoint
export OORB_RETRIEVAL_ENDPOINT="http://your-server:8000"
# Or use the standard configuration
export RETRIEVAL_API_BASE_URL="http://your-server:8000"
```
---
## Usage
Once installed, the CLI becomes available via the `oorb` command (or `python oorb_cli.py` if unlinked).
### Main Commands
#### `chat` - Interactive ROS2 Assistant
Start an interactive chat session or ask a single question with full customization options.
**Basic Usage:**
```bash
# Interactive mode
oorb chat
# Single question mode
oorb chat -p "How do I create a custom message type in ROS2?"
# With specific ROS distro
oorb chat --distro humble -p "create a publisher node"
oorb chat -d jazzy
# With custom retrieval endpoint
oorb chat --retrieval-endpoint http://localhost:9000 -p "setup navigation stack"
```
**Available Options:**
- `-b, --backend` - Choose LLM backend: `azure`, `openai`, or `ollama`
- `-m, --model` - Specify model name (e.g., `gpt-4o-mini`, `gpt-3.5-turbo`)
- `-t, --temperature` - Set response creativity (0.0-1.0, default: 0.3)
- `-d, --distro` - ROS distro to use (e.g., humble, jazzy, rolling)
- `-r, --retrieval-endpoint` - Custom retrieval API endpoint URL
- `-p, --prompt` - Single prompt for non-interactive mode
- `--use-tools/--no-tools` - Enable/disable tool calling (default: auto-detect)
**Examples:**
```bash
# Use specific backend and model with ROS distro
oorb chat -b openai -m gpt-4o-mini -d humble -t 0.7
# Quick question with custom settings
oorb chat -b azure -m gpt-3.5-turbo -d jazzy -p "Create a ROS2 launch file for navigation"
# Use custom retrieval endpoint
oorb chat -r http://my-vector-db:8000 -d rolling -p "Setup SLAM toolbox"
# Disable tools for faster responses
oorb chat --no-tools -d humble -p "What is a ROS2 node?"
```
#### `list-distros` - View Supported ROS Distributions
Display all supported ROS distributions with detailed information.
**Basic Usage:**
```bash
oorb list-distros
```
**What it shows:**
- All supported ROS/ROS2 distributions
- LTS (Long Term Support) status
- Compatible Ubuntu versions
- Current vs. available distros
- Configuration instructions
#### `test-retrieval` - Test Retrieval Endpoint
Test connectivity and features of retrieval API endpoints.
**Basic Usage:**
```bash
# Test current configured endpoint
oorb test-retrieval
# Test specific endpoint
oorb test-retrieval --endpoint http://localhost:9000
```
**Available Options:**
- `-e, --endpoint` - Specific endpoint URL to test
**What it shows:**
- Endpoint accessibility status
- Available API endpoints (e.g., /retrieve, /health, /docs)
- Configuration suggestions
- Connection diagnostics
#### `list-models` - View Available Models
Display all available models for different backends.
**Basic Usage:**
```bash
oorb list-models
```
**Available Options:**
- `-b, --backend` - Filter by specific backend: `azure`, `openai`, or `ollama`
**Examples:**
```bash
# List all models
oorb list-models
# List only OpenAI models
oorb list-models -b openai
# List only local Ollama models
oorb list-models -b ollama
```
#### `status` - System Health Check
Check system configuration, API keys, and service availability.
**Basic Usage:**
```bash
oorb status
```
**What it shows:**
- API key configuration status
- Ollama service status and available models
- Retrieval API connectivity and endpoint information
- Current ROS distro detection
- Available backends
- Configuration warnings and errors
- Quick setup recommendations
---
## Advanced Configuration
### Priority Order for Settings
OORB CLI uses the following priority order for configuration:
**ROS Distro Selection:**
1. `--distro` command line parameter
2. `OORB_ROS_DISTRO` environment variable
3. `ROS_DISTRO` environment variable (standard ROS)
4. Auto-detection from installed ROS distributions
**Retrieval Endpoint Selection:**
1. `--retrieval-endpoint` command line parameter
2. `OORB_RETRIEVAL_ENDPOINT` environment variable
3. `RETRIEVAL_API_BASE_URL` environment variable
4. Default: `http://localhost:8000`
### Configuration Examples
```bash
# Set persistent defaults via environment
export OORB_ROS_DISTRO=humble
export OORB_RETRIEVAL_ENDPOINT=http://my-vector-db:8000
export OPENAI_API_KEY=your-api-key
# Override defaults for specific commands
oorb chat -d jazzy -r http://localhost:9000 -p "your question"
# Test your configuration
oorb status
oorb test-retrieval
oorb list-distros
```
---
## Contributing
We welcome contributions to the OORB CLI project! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) file for detailed guidelines on how to contribute to the project.
---
## License
This project is open-source and available under the appropriate license. Please check the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "oorb-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Fayez Zouari <fayez.zouari@insat.ucar.tn>, Ousswa Chouchane <ousswachouchane@aucegypt.edu>",
"keywords": "ros, ros2, chatbot, cli, robotics, ai, assistant",
"author": null,
"author_email": "Fayez Zouari <fayez.zouari@insat.ucar.tn>, Ousswa Chouchane <ousswachouchane@aucegypt.edu>",
"download_url": "https://files.pythonhosted.org/packages/a5/24/d6f1ce501e7f1cc7612ffaa2b515292b048a033d857d3264d63148409a4d/oorb_cli-1.0.10.tar.gz",
"platform": null,
"description": "# OORB CLI \u2013 Robotics coding Assistant\n\n**OORB** (Open Organic Robotics Benchmark) is an open-source initiative focused on advancing robotics through AI-powered tools and benchmarks. \n\n**OORB CLI** is a command-line assistant designed to answer questions and assist with tasks related to **ROS2** (Robot Operating System 2). Powered by modern language models and enhanced with vector search and retrieval-augmented generation, it serves as an intelligent tool for roboticists and developers working with ROS2.\n\n---\n\n## Features\n\n* Focused exclusively on **ROS2**\n* Interactive and one-shot Q&A modes\n* Backend support for **OpenAI**, **Azure OpenAI**, and **Ollama**\n* Local inference support with Ollama\n* Retrieval-augmented answers with Milvus vector store\n* **Configurable ROS distro support** - Specify your target ROS2 distribution\n* **Custom retrieval endpoint support** - Use your own vector database or API\n* Configurable model, temperature, and backend preferences\n* **Tool calling capabilities** with access to:\n - `read_file` - Read and analyze files\n - `write_file` - Create and modify files\n - `search_in_files` - Search across file contents\n - `run_command` - Execute system commands\n - `list_directory` - Browse directory structures\n - `edit_file_lines` - Make precise file edits\n\n### Recent Enhancements\n\n* **ROS Distro Selection**: Set your preferred ROS2 distribution (humble, jazzy, rolling, etc.)\n* **Custom Retrieval Endpoints**: Connect to your own vector database or knowledge API\n* **Enhanced Configuration**: Multiple ways to configure settings via environment variables or CLI options\n* **Endpoint Testing**: Built-in tools to test and validate retrieval API connectivity\n\n### Note: \nYou can find a quick demo of the CLI on the following link : [link](https://youtu.be/6o50YBeWZ04)\n\n\n---\n\n\n## Installation\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install oorb-cli\n```\n\nThe CLI is available on [PyPI](https://pypi.org/project/oorb-cli/) and can be installed directly via pip.\n\n### Option 2: Development Installation\n\n#### 1. Clone the repository\n\n```bash\ngit clone https://github.com/OORB-Open-Organic-Robotics/oorb-cli\ncd oorb-cli\n```\n\n#### 2. Create virtual environment and install dependencies using `uv`\n\n```bash\nuv venv\nsource .venv/bin/activate\nuv pip install -e .\n```\n\nThis installs the CLI in *editable mode*, allowing you to make changes to the source code without reinstalling.\n\n> **Note:** `uv pip install -e .` is functionally equivalent to `pip install -e .`, but uses `uv` for faster dependency resolution and isolated builds.\n\n---\n\n## Configuration\n\nSet the appropriate API key depending on the backend you intend to use.\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=\"your-key\"\n```\n\n### Azure OpenAI\n\n```bash\nexport AZURE_OPENAI_API_KEY=\"your-key\"\nexport AZURE_OPENAI_ENDPOINT=\"your-endpoint\"\n```\n\n### ROS Distro Configuration\n\nSpecify your target ROS2 distribution for enhanced retrieval and distro-specific answers:\n\n```bash\n# Set default ROS distro (overrides auto-detection)\nexport OORB_ROS_DISTRO=humble\n\n# Or use the standard ROS environment variable\nexport ROS_DISTRO=humble\n```\n\n**Supported ROS2 Distributions:**\n- `humble` (LTS) - Ubuntu 20.04, 22.04\n- `iron` - Ubuntu 22.04\n- `jazzy` (LTS) - Ubuntu 24.04\n- `rolling` - Latest development version\n- Legacy ROS1: `noetic`, `melodic`\n\n### Custom Retrieval Endpoint\n\nConfigure your own vector database or retrieval API:\n\n```bash\n# Use custom retrieval endpoint\nexport OORB_RETRIEVAL_ENDPOINT=\"http://your-server:8000\"\n\n# Or use the standard configuration\nexport RETRIEVAL_API_BASE_URL=\"http://your-server:8000\"\n```\n---\n\n## Usage\n\nOnce installed, the CLI becomes available via the `oorb` command (or `python oorb_cli.py` if unlinked).\n\n### Main Commands\n\n#### `chat` - Interactive ROS2 Assistant\n\nStart an interactive chat session or ask a single question with full customization options.\n\n**Basic Usage:**\n```bash\n# Interactive mode\noorb chat\n\n# Single question mode\noorb chat -p \"How do I create a custom message type in ROS2?\"\n\n# With specific ROS distro\noorb chat --distro humble -p \"create a publisher node\"\noorb chat -d jazzy\n\n# With custom retrieval endpoint\noorb chat --retrieval-endpoint http://localhost:9000 -p \"setup navigation stack\"\n```\n\n**Available Options:**\n- `-b, --backend` - Choose LLM backend: `azure`, `openai`, or `ollama`\n- `-m, --model` - Specify model name (e.g., `gpt-4o-mini`, `gpt-3.5-turbo`)\n- `-t, --temperature` - Set response creativity (0.0-1.0, default: 0.3)\n- `-d, --distro` - ROS distro to use (e.g., humble, jazzy, rolling)\n- `-r, --retrieval-endpoint` - Custom retrieval API endpoint URL\n- `-p, --prompt` - Single prompt for non-interactive mode\n- `--use-tools/--no-tools` - Enable/disable tool calling (default: auto-detect)\n\n**Examples:**\n```bash\n# Use specific backend and model with ROS distro\noorb chat -b openai -m gpt-4o-mini -d humble -t 0.7\n\n# Quick question with custom settings\noorb chat -b azure -m gpt-3.5-turbo -d jazzy -p \"Create a ROS2 launch file for navigation\"\n\n# Use custom retrieval endpoint\noorb chat -r http://my-vector-db:8000 -d rolling -p \"Setup SLAM toolbox\"\n\n# Disable tools for faster responses\noorb chat --no-tools -d humble -p \"What is a ROS2 node?\"\n```\n\n#### `list-distros` - View Supported ROS Distributions\n\nDisplay all supported ROS distributions with detailed information.\n\n**Basic Usage:**\n```bash\noorb list-distros\n```\n\n**What it shows:**\n- All supported ROS/ROS2 distributions\n- LTS (Long Term Support) status\n- Compatible Ubuntu versions\n- Current vs. available distros\n- Configuration instructions\n\n#### `test-retrieval` - Test Retrieval Endpoint\n\nTest connectivity and features of retrieval API endpoints.\n\n**Basic Usage:**\n```bash\n# Test current configured endpoint\noorb test-retrieval\n\n# Test specific endpoint\noorb test-retrieval --endpoint http://localhost:9000\n```\n\n**Available Options:**\n- `-e, --endpoint` - Specific endpoint URL to test\n\n**What it shows:**\n- Endpoint accessibility status\n- Available API endpoints (e.g., /retrieve, /health, /docs)\n- Configuration suggestions\n- Connection diagnostics\n\n#### `list-models` - View Available Models\n\nDisplay all available models for different backends.\n\n**Basic Usage:**\n```bash\noorb list-models\n```\n\n**Available Options:**\n- `-b, --backend` - Filter by specific backend: `azure`, `openai`, or `ollama`\n\n**Examples:**\n```bash\n# List all models\noorb list-models\n\n# List only OpenAI models\noorb list-models -b openai\n\n# List only local Ollama models\noorb list-models -b ollama\n```\n\n#### `status` - System Health Check\n\nCheck system configuration, API keys, and service availability.\n\n**Basic Usage:**\n```bash\noorb status\n```\n\n**What it shows:**\n- API key configuration status\n- Ollama service status and available models\n- Retrieval API connectivity and endpoint information\n- Current ROS distro detection\n- Available backends\n- Configuration warnings and errors\n- Quick setup recommendations\n\n---\n\n## Advanced Configuration\n\n### Priority Order for Settings\n\nOORB CLI uses the following priority order for configuration:\n\n**ROS Distro Selection:**\n1. `--distro` command line parameter\n2. `OORB_ROS_DISTRO` environment variable\n3. `ROS_DISTRO` environment variable (standard ROS)\n4. Auto-detection from installed ROS distributions\n\n**Retrieval Endpoint Selection:**\n1. `--retrieval-endpoint` command line parameter\n2. `OORB_RETRIEVAL_ENDPOINT` environment variable\n3. `RETRIEVAL_API_BASE_URL` environment variable\n4. Default: `http://localhost:8000`\n\n### Configuration Examples\n\n```bash\n# Set persistent defaults via environment\nexport OORB_ROS_DISTRO=humble\nexport OORB_RETRIEVAL_ENDPOINT=http://my-vector-db:8000\nexport OPENAI_API_KEY=your-api-key\n\n# Override defaults for specific commands\noorb chat -d jazzy -r http://localhost:9000 -p \"your question\"\n\n# Test your configuration\noorb status\noorb test-retrieval\noorb list-distros\n```\n\n---\n\n## Contributing\n\nWe welcome contributions to the OORB CLI project! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) file for detailed guidelines on how to contribute to the project.\n\n---\n\n## License\n\nThis project is open-source and available under the appropriate license. Please check the LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Intelligent CLI assistant for ROS and ROS2 questions",
"version": "1.0.10",
"project_urls": null,
"split_keywords": [
"ros",
" ros2",
" chatbot",
" cli",
" robotics",
" ai",
" assistant"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ca66ac5f934df2fd824b17c5a894135efd9448050e876d2e071b00329a313ab2",
"md5": "daa8576d4251ab350531ed1806417103",
"sha256": "76ff83114021b3310acae2e2442855281ee99bd7a1bfdc380140285847e383e4"
},
"downloads": -1,
"filename": "oorb_cli-1.0.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "daa8576d4251ab350531ed1806417103",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 38372,
"upload_time": "2025-08-28T12:49:54",
"upload_time_iso_8601": "2025-08-28T12:49:54.731732Z",
"url": "https://files.pythonhosted.org/packages/ca/66/ac5f934df2fd824b17c5a894135efd9448050e876d2e071b00329a313ab2/oorb_cli-1.0.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a524d6f1ce501e7f1cc7612ffaa2b515292b048a033d857d3264d63148409a4d",
"md5": "6f35d075909348633d5dc6436127cb6a",
"sha256": "b5311bc2bb6ddff560c0e17dc824a4136260eadbc11d1754c45d1f8e7195486e"
},
"downloads": -1,
"filename": "oorb_cli-1.0.10.tar.gz",
"has_sig": false,
"md5_digest": "6f35d075909348633d5dc6436127cb6a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 43104,
"upload_time": "2025-08-28T12:49:55",
"upload_time_iso_8601": "2025-08-28T12:49:55.582886Z",
"url": "https://files.pythonhosted.org/packages/a5/24/d6f1ce501e7f1cc7612ffaa2b515292b048a033d857d3264d63148409a4d/oorb_cli-1.0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 12:49:55",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "oorb-cli"
}
