Metadata-Version: 2.4
Name: dimos
Version: 0.0.9
Summary: Powering agentive generalist robotics
Author-email: Dimensional Team <build@dimensionalOS.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dimos-lcm
Requires-Dist: PyTurboJPEG==1.8.2
Requires-Dist: numpy>=1.26.4
Requires-Dist: scipy>=1.15.1
Requires-Dist: reactivex
Requires-Dist: asyncio==3.4.3
Requires-Dist: sortedcontainers==2.4.0
Requires-Dist: pydantic
Requires-Dist: python-dotenv
Requires-Dist: dask[complete]==2025.5.1
Requires-Dist: plum-dispatch==2.5.7
Requires-Dist: structlog<26,>=25.5.0
Requires-Dist: colorlog==6.9.0
Requires-Dist: opencv-python
Requires-Dist: open3d
Requires-Dist: pydantic-settings<3,>=2.11.0
Requires-Dist: textual==3.7.1
Requires-Dist: terminaltexteffects==0.12.2
Requires-Dist: typer<1,>=0.19.2
Requires-Dist: plotext==5.3.2
Requires-Dist: numba>=0.60.0
Requires-Dist: llvmlite>=0.42.0
Requires-Dist: rerun-sdk>=0.20.0
Provides-Extra: misc
Requires-Dist: cerebras-cloud-sdk; extra == "misc"
Requires-Dist: yapf==0.40.2; extra == "misc"
Requires-Dist: typeguard; extra == "misc"
Requires-Dist: empy==3.3.4; extra == "misc"
Requires-Dist: catkin_pkg; extra == "misc"
Requires-Dist: lark; extra == "misc"
Requires-Dist: tiktoken>=0.8.0; extra == "misc"
Requires-Dist: python-multipart==0.0.20; extra == "misc"
Requires-Dist: tensorzero==2025.7.5; extra == "misc"
Requires-Dist: ipykernel; extra == "misc"
Requires-Dist: sentence_transformers; extra == "misc"
Requires-Dist: scikit-learn; extra == "misc"
Requires-Dist: timm>=1.0.15; extra == "misc"
Requires-Dist: edgetam-dimos; extra == "misc"
Requires-Dist: opencv-contrib-python==4.10.0.84; extra == "misc"
Requires-Dist: open_clip_torch==3.2.0; extra == "misc"
Requires-Dist: torchreid==0.2.5; extra == "misc"
Requires-Dist: gdown==5.2.0; extra == "misc"
Requires-Dist: tensorboard==2.20.0; extra == "misc"
Requires-Dist: googlemaps>=4.10.0; extra == "misc"
Requires-Dist: onnx; extra == "misc"
Requires-Dist: einops==0.8.1; extra == "misc"
Requires-Dist: xarm-python-sdk>=1.17.0; extra == "misc"
Provides-Extra: visualization
Requires-Dist: rerun-sdk>=0.20.0; extra == "visualization"
Provides-Extra: agents
Requires-Dist: langchain<2,>=1; extra == "agents"
Requires-Dist: langchain-chroma<2,>=1; extra == "agents"
Requires-Dist: langchain-core<2,>=1; extra == "agents"
Requires-Dist: langchain-openai<2,>=1; extra == "agents"
Requires-Dist: langchain-text-splitters<2,>=1; extra == "agents"
Requires-Dist: langchain-huggingface<2,>=1; extra == "agents"
Requires-Dist: langchain-ollama<2,>=1; extra == "agents"
Requires-Dist: bitsandbytes<1.0,>=0.48.2; sys_platform == "linux" and extra == "agents"
Requires-Dist: ollama>=0.6.0; extra == "agents"
Requires-Dist: anthropic>=0.19.0; extra == "agents"
Requires-Dist: openai; extra == "agents"
Requires-Dist: openai-whisper; extra == "agents"
Requires-Dist: sounddevice; extra == "agents"
Requires-Dist: mcp>=1.0.0; extra == "agents"
Provides-Extra: web
Requires-Dist: fastapi>=0.115.6; extra == "web"
Requires-Dist: sse-starlette>=2.2.1; extra == "web"
Requires-Dist: uvicorn>=0.34.0; extra == "web"
Requires-Dist: ffmpeg-python; extra == "web"
Requires-Dist: soundfile; extra == "web"
Provides-Extra: perception
Requires-Dist: ultralytics>=8.3.70; extra == "perception"
Requires-Dist: filterpy>=1.4.5; extra == "perception"
Requires-Dist: Pillow; extra == "perception"
Requires-Dist: lap>=0.5.12; extra == "perception"
Requires-Dist: transformers[torch]==4.49.0; extra == "perception"
Requires-Dist: moondream; extra == "perception"
Requires-Dist: omegaconf>=2.3.0; extra == "perception"
Requires-Dist: hydra-core>=1.3.0; extra == "perception"
Provides-Extra: unitree
Requires-Dist: dimos[base]; extra == "unitree"
Requires-Dist: unitree-webrtc-connect-leshy>=2.0.7; extra == "unitree"
Provides-Extra: manipulation
Requires-Dist: h5py>=3.7.0; extra == "manipulation"
Requires-Dist: pyrender>=0.1.45; extra == "manipulation"
Requires-Dist: trimesh>=3.22.0; extra == "manipulation"
Requires-Dist: python-fcl>=0.7.0.4; extra == "manipulation"
Requires-Dist: pyquaternion>=0.9.9; extra == "manipulation"
Requires-Dist: matplotlib>=3.7.1; extra == "manipulation"
Requires-Dist: rtree; extra == "manipulation"
Requires-Dist: pandas>=1.5.2; extra == "manipulation"
Requires-Dist: tqdm>=4.65.0; extra == "manipulation"
Requires-Dist: pyyaml>=6.0; extra == "manipulation"
Requires-Dist: contact-graspnet-pytorch; extra == "manipulation"
Requires-Dist: piper-sdk; extra == "manipulation"
Requires-Dist: kaleido>=0.2.1; extra == "manipulation"
Requires-Dist: plotly>=5.9.0; extra == "manipulation"
Provides-Extra: cpu
Requires-Dist: onnxruntime; extra == "cpu"
Requires-Dist: ctransformers==0.2.27; extra == "cpu"
Provides-Extra: cuda
Requires-Dist: cupy-cuda12x==13.6.0; extra == "cuda"
Requires-Dist: nvidia-nvimgcodec-cu12[all]; extra == "cuda"
Requires-Dist: onnxruntime-gpu>=1.17.1; extra == "cuda"
Requires-Dist: ctransformers[cuda]==0.2.27; extra == "cuda"
Requires-Dist: mmengine>=0.10.3; extra == "cuda"
Requires-Dist: mmcv>=2.1.0; extra == "cuda"
Requires-Dist: xformers>=0.0.20; extra == "cuda"
Provides-Extra: dev
Requires-Dist: ruff==0.14.3; extra == "dev"
Requires-Dist: mypy==1.19.0; extra == "dev"
Requires-Dist: pre_commit==4.2.0; extra == "dev"
Requires-Dist: pytest==8.3.5; extra == "dev"
Requires-Dist: pytest-asyncio==0.26.0; extra == "dev"
Requires-Dist: pytest-mock==3.15.0; extra == "dev"
Requires-Dist: pytest-env==1.1.5; extra == "dev"
Requires-Dist: pytest-timeout==2.4.0; extra == "dev"
Requires-Dist: coverage>=7.0; extra == "dev"
Requires-Dist: requests-mock==1.12.1; extra == "dev"
Requires-Dist: terminaltexteffects==0.12.2; extra == "dev"
Requires-Dist: watchdog>=3.0.0; extra == "dev"
Requires-Dist: md-babel-py==1.1.1; extra == "dev"
Requires-Dist: lxml-stubs<1,>=0.5.1; extra == "dev"
Requires-Dist: pandas-stubs<3,>=2.3.2.250926; extra == "dev"
Requires-Dist: types-PySocks<2,>=1.7.1.20251001; extra == "dev"
Requires-Dist: types-PyYAML<7,>=6.0.12.20250915; extra == "dev"
Requires-Dist: types-colorama<1,>=0.4.15.20250801; extra == "dev"
Requires-Dist: types-defusedxml<1,>=0.7.0.20250822; extra == "dev"
Requires-Dist: types-gevent<26,>=25.4.0.20250915; extra == "dev"
Requires-Dist: types-greenlet<4,>=3.2.0.20250915; extra == "dev"
Requires-Dist: types-jmespath<2,>=1.0.2.20250809; extra == "dev"
Requires-Dist: types-jsonschema<5,>=4.25.1.20251009; extra == "dev"
Requires-Dist: types-networkx<4,>=3.5.0.20251001; extra == "dev"
Requires-Dist: types-protobuf<7,>=6.32.1.20250918; extra == "dev"
Requires-Dist: types-psutil<8,>=7.0.0.20251001; extra == "dev"
Requires-Dist: types-pytz<2026,>=2025.2.0.20250809; extra == "dev"
Requires-Dist: types-simplejson<4,>=3.20.0.20250822; extra == "dev"
Requires-Dist: types-tabulate<1,>=0.9.0.20241207; extra == "dev"
Requires-Dist: types-tensorflow<3,>=2.18.0.20251008; extra == "dev"
Requires-Dist: types-tqdm<5,>=4.67.0.20250809; extra == "dev"
Provides-Extra: sim
Requires-Dist: mujoco>=3.3.4; extra == "sim"
Requires-Dist: playground>=0.0.5; extra == "sim"
Requires-Dist: pygame>=2.6.1; extra == "sim"
Provides-Extra: drone
Requires-Dist: pymavlink; extra == "drone"
Provides-Extra: base
Requires-Dist: dimos[agents,perception,sim,visualization,web]; extra == "base"
Dynamic: license-file

<div align="center">
   <img width="1000" alt="banner_bordered_trimmed" src="https://github.com/user-attachments/assets/15283d94-ad95-42c9-abd5-6565a222a837" /> </a>
    <h4 align="center">Program Atoms</h4>
    <h4 align="center">The Agentive Operating System for Generalist Robotics</h4>


<br>

[![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/8m6HMArf)
[![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers)
[![Forks](https://img.shields.io/github/forks/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/fork)
[![Contributors](https://img.shields.io/github/contributors/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/graphs/contributors)
<br>
![Nix](https://img.shields.io/badge/Nix-flakes-5277C3?style=flat-square&logo=NixOS&logoColor=white)
![NixOS](https://img.shields.io/badge/NixOS-supported-5277C3?style=flat-square&logo=NixOS&logoColor=white)
![CUDA](https://img.shields.io/badge/CUDA-12.x-76B900?style=flat-square&logo=nvidia&logoColor=white)
[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/)

<p align="center">
  <a href="#the-dimensional-framework">Features</a> •
  <a href="#installation">Installation</a> •
  <a href="#documentation">Documentation</a> •
  <a href="#development">Development</a> •
  <a href="#contributing">Contributing</a>
</p>

</div>

> \[!NOTE]
>
> ⚠️ **Alpha Pre-Release: Expect Breaking Changes** ⚠️

# The Dimensional Framework

Dimensional is the open-source, universal operating system for generalist robotics. On DimOS, developers
can design, build, and run physical ("dimensional") applications that run on any humanoid, quadruped,
drone, or wheeled embodiment.

**Programming physical robots is now as simple as programming digital software**: Composable, Modular, Repeatable.

Core Features:
- **Navigation:** Production navigation stack for any robot with lidar: SLAM, terrain analysis, collision
  avoidance, route planning, exploration.
- **Dashboard:** The DimOS command center gives developers the tooling to debug, visualize, compose, and
  test dimensional applications in real-time. Control your robot via waypoint, agent query, keyboard,
  VR, more.
- **Modules:** Standalone components (equivalent to ROS nodes) that publish and subscribe to typed
  In/Out streams that communicate over DimOS transports. The building blocks of Dimensional.
- **Agents (experimental):** DimOS agents understand physical space, subscribe to sensor streams, and call
  **physical** tools. Emergence appears when agents have physical agency.
- **MCP (experimental):** Vibecode robots by giving your AI editor (Cursor, Claude Code) MCP access to run
  physical commands (move forward 1 meter, jump, etc.).
- **Manipulation (unreleased)** Classical (OMPL, IK, GraspGen), Agentive (TAMP), and VLA-native manipulation stack runs out-of-the-box on any DimOS supported arm embodiment.
- **Transport/Middleware:** DimOS native Python transport supports LCM, DDS, and SHM, plus ROS 2.
- **Robot integrations:** We integrate with the majority of hardware OEMs and are moving fast to cover
  them all. Supported and/or immediate roadmap:

  | Category | Platforms |
  | --- | --- |
  | Quadrupeds | Unitree Go2, Unitree B1, AGIBOT D1 Max/Pro, Dobot Rover |
  | Drones | DJI Mavic 2, Holybro x500 |
  | Humanoids | Unitree G1, Booster K1, AGIBOT X2, ABIBOT A2 |
  | Arms | OpenARMs, xARM 6/7, AgileX Piper, HighTorque Pantera |

# Getting Started

## Installation

Supported/tested matrix:

| Platform | Status | Tested | Required System deps |
| --- | --- | --- | --- |
| Linux | supported | Ubuntu 22.04, 24.04 | See below |
| macOS | experimental beta | not CI-tested | `brew install gnu-sed gcc portaudio git-lfs libjpeg-turbo python` |

Note: macOS is usable but expect inconsistent/flaky behavior (rather than hard errors/crashes).

```sh
sudo apt-get update
sudo apt-get install -y curl g++ portaudio19-dev git-lfs libturbojpeg python3-dev
# install uv for python
curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH"
```

Option 1: Install in a virtualenv

```sh

uv venv && . .venv/bin/activate
uv pip install 'dimos[base,unitree]'
# replay recorded data to test that the system is working
# IMPORTANT: First replay run will show a black rerun window while 2.4 GB downloads from LFS
dimos --replay run unitree-go2
```

Option 2: Run without installing

```sh
uvx --from 'dimos[base,unitree]' dimos --replay run unitree-go2
```

### Test Installation

#### Control a robot in a simulation (no robot required)


```sh
export DISPLAY=:1 # Or DISPLAY=:0 if getting GLFW/OpenGL X11 errors
# ignore the warp warnings
dimos --viewer-backend rerun-web --simulation run unitree-go2
```

#### Control a real robot (Unitree Go2 over WebRTC)

```sh
export ROBOT_IP=<YOUR_ROBOT_IP>
dimos --viewer-backend rerun-web run unitree-go2
```

After running dimOS open http://localhost:7779 to control robot movement.

#### Dimensional Agents

> \[!NOTE]
>
> **Experimental Beta: Potential unstoppable robot sentience**

```sh
export OPENAI_API_KEY=<your private key>
dimos --viewer-backend rerun-web run unitree-go2-agentic
```

After running that, open a new terminal and run the following to start giving instructions to the agent.
```sh
# activate the venv in this new terminal
source .venv/bin/activate

# then tell the agent "explore the room"
# then tell it to go to something, ex: "go to the door"
humancli
```

# The Dimensional Library

### Modules

Modules are subsystems on a robot that operate autonomously and communicate with other subsystems using standardized messages. See below a simple robot connection module that sends streams of continuous `cmd_vel` to the robot and recieves `color_image` to a simple `Listener` module.

```py
import threading, time, numpy as np
from dimos.core import In, Module, Out, rpc
from dimos.core.blueprints import autoconnect
from dimos.msgs.geometry_msgs import Twist
from dimos.msgs.sensor_msgs import Image
from dimos.msgs.sensor_msgs.image_impls.AbstractImage import ImageFormat

class RobotConnection(Module):
    cmd_vel: In[Twist]
    color_image: Out[Image]

    @rpc
    def start(self):
        threading.Thread(target=self._image_loop, daemon=True).start()

    def _image_loop(self):
        while True:
            img = Image.from_numpy(
                np.zeros((120, 160, 3), np.uint8),
                format=ImageFormat.RGB,
                frame_id="camera_optical",
            )
            self.color_image.publish(img)
            time.sleep(0.2)

class Listener(Module):
    color_image: In[Image]

    @rpc
    def start(self):
        self.color_image.subscribe(lambda img: print(f"image {img.width}x{img.height}"))

if __name__ == "__main__":
    autoconnect(
        RobotConnection.blueprint(),
        Listener.blueprint(),
    ).build().loop()
```

### Blueprints

Blueprints are how robots are constructed on Dimensional; instructions for how to construct and wire modules. You compose them with
`autoconnect(...)`, which connects streams by `(name, type)` and returns a `ModuleBlueprintSet`.

Blueprints can be composed, remapped, and have transports overridden if `autoconnect()` fails due to conflicting variable names or `In[]` and `Out[]` message types.

A blueprint example that connects the image stream from a robot to an LLM Agent for reasoning and action execution.
```py
from dimos.core.blueprints import autoconnect
from dimos.core.transport import LCMTransport
from dimos.msgs.sensor_msgs import Image
from dimos.robot.unitree.connection.go2 import go2_connection
from dimos.agents.agent import llm_agent

blueprint = autoconnect(
    go2_connection(),
    llm_agent(),
).transports({("color_image", Image): LCMTransport("/color_image", Image)})

# Run the blueprint
blueprint.build().loop()
```

# Development

```sh
GIT_LFS_SKIP_SMUDGE=1 git clone -b dev https://github.com/dimensionalOS/dimos.git
cd dimos
```

Then pick one of two development paths:

Option A: Devcontainer
```sh
./bin/dev
```

Option B: Editable install with uv
```sh
uv venv && . .venv/bin/activate
uv pip install -e '.[base,dev]'
```

For system deps, Nix setups, and testing, see `/docs/development/README.md`.

### Monitoring & Debugging

DimOS comes with a number of monitoring tools:
- Run `lcmspy` to see how fast messages are being published on streams.
- Run `skillspy` to see how skills are being called, how long they are running, which are active, etc.
- Run `agentspy` to see the agent's status over time.
- If you suspect there is a bug within DimOS itself, you can enable extreme logging by prefixing the dimos command with `DIMOS_LOG_LEVEL=DEBUG RERUN_SAVE=1 `. Ex: `DIMOS_LOG_LEVEL=DEBUG RERUN_SAVE=1 dimos --replay run unitree-go2`


# Documentation

Concepts:
- [Modules](/docs/concepts/modules.md): The building blocks of DimOS, modules run in parallel and are singleton python classes.
- [Streams](/docs/api/sensor_streams/index.md): How modules communicate, a Pub / Sub system.
- [Blueprints](/dimos/core/README_BLUEPRINTS.md): a way to group modules together and define their connections to each other.
- [RPC](/dimos/core/README_BLUEPRINTS.md#calling-the-methods-of-other-modules): how one module can call a method on another module (arguments get serialized to JSON-like binary data).
- [Skills](/dimos/core/README_BLUEPRINTS.md#defining-skills): An RPC function, except it can be called by an AI agent (a tool for an AI).

## Contributing

We welcome contributions! See our [Bounty List](https://docs.google.com/spreadsheets/d/1tzYTPvhO7Lou21cU6avSWTQOhACl5H8trSvhtYtsk8U/edit?usp=sharing) for open requests for contributions. If you would like to suggest a feature or sponsor a bounty, open an issue.
