# xtrose29/rt-safe architecture

> Architecture diagram of the GitHub repository xtrose29/rt-safe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xtrose29/rt-safe
- Repository: https://github.com/xtrose29/rt-safe

## Overview

RT-SAFE is a benchmark for evaluating embodied agents’ navigation safety in a live Unreal environment. The principal workflow configures a task, constructs and runs the world, has an agent perceive observations and choose actions while traffic and hazards continue evolving, then records and evaluates outcomes. The repository also includes model transports, traffic simulation, experiment runners and result analysis, plus a website presenting benchmark results and examples. The graph follows the supplied tree and README; some implementation links are necessarily unverified because the source excerpts are partial.

Main entry points: [`manager/world_manager.py`](https://github.com/xtrose29/rt-safe/blob/main/manager/world_manager.py) (World manager), [`base/rt_agent.py`](https://github.com/xtrose29/rt-safe/blob/main/base/rt_agent.py) (RT agent), [`evaluation/run_experiment_matrix.py`](https://github.com/xtrose29/rt-safe/blob/main/evaluation/run_experiment_matrix.py) (Experiment runners), [`SimWorld/simworld/traffic/controller/traffic_controller.py`](https://github.com/xtrose29/rt-safe/blob/main/SimWorld/simworld/traffic/controller/traffic_controller.py) (SimWorld traffic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_world_manager["World manager<br/>[world_manager.py]"]
  node_communicator["RT communicator<br/>[rt_communicator.py]"]
  node_unrealcv["UnrealCV bridge<br/>[rt_unrealcv.py]"]
  node_scenario["Scenario runner<br/>[run_scenario.py]"]
end

subgraph group_agent["Agent decisions"]
  node_agent_runtime["RT agent<br/>[rt_agent.py]"]
  node_action_space["Action space<br/>[rt_action_space.py]"]
  node_llm["Model adapters<br/>[rt_llm.py]"]
end

subgraph group_world["Simulation world"]
  node_traffic_system["RT traffic system"]
  node_traffic_controller["Traffic controller"]
  node_sim_traffic["SimWorld traffic"]
  node_actors["Traffic actors<br/>[vehicle.py]"]
  node_signals["Signals and junctions<br/>[intersection.py]"]
end

subgraph group_research["Evaluation and presentation"]
  node_evaluator["Safety evaluator<br/>[rt_evaluator.py]"]
  node_experiment_runner["Experiment runners"]
  node_metrics["Evaluation metrics"]
  node_aggregation["Result aggregation"]
  node_replay["Rollout replay"]
  node_website["Benchmark website<br/>[rtsafe.tsx]"]
end

node_user(("Benchmark user"))
node_model_service(("Model provider"))
node_unreal(("Unreal runtime"))

node_user -.->|"starts run"| node_scenario
node_scenario -.->|"sets up world"| node_world_manager
node_world_manager -->|"coordinates agent"| node_agent_runtime
node_agent_runtime -->|"requests decision"| node_llm
node_llm -.->|"queries model"| node_model_service
node_agent_runtime -->|"uses actions"| node_action_space
node_agent_runtime -->|"records outcomes"| node_evaluator
node_world_manager -->|"uses bridge"| node_communicator
node_communicator -->|"delegates transport"| node_unrealcv
node_unrealcv -.->|"exchanges state"| node_unreal
node_world_manager -->|"coordinates traffic"| node_traffic_controller
node_traffic_controller -->|"extends controller"| node_sim_traffic
node_sim_traffic -->|"manages actors"| node_actors
node_sim_traffic -.->|"coordinates signals"| node_signals
node_user -.->|"selects evaluation"| node_experiment_runner
node_experiment_runner -.->|"runs scenarios"| node_world_manager
node_experiment_runner -.->|"scores rollouts"| node_metrics
node_metrics -.->|"feeds summaries"| node_aggregation
node_aggregation -.->|"publishes results"| node_website
node_experiment_runner -.->|"supports replay"| node_replay

click node_world_manager "https://github.com/xtrose29/rt-safe/blob/main/manager/world_manager.py"
click node_agent_runtime "https://github.com/xtrose29/rt-safe/blob/main/base/rt_agent.py"
click node_action_space "https://github.com/xtrose29/rt-safe/blob/main/base/rt_action_space.py"
click node_llm "https://github.com/xtrose29/rt-safe/blob/main/llm/rt_llm.py"
click node_evaluator "https://github.com/xtrose29/rt-safe/blob/main/base/rt_evaluator.py"
click node_communicator "https://github.com/xtrose29/rt-safe/blob/main/base/rt_communicator.py"
click node_unrealcv "https://github.com/xtrose29/rt-safe/blob/main/base/rt_unrealcv.py"
click node_traffic_system "https://github.com/xtrose29/rt-safe/blob/main/base/rt_traffic_system.py"
click node_traffic_controller "https://github.com/xtrose29/rt-safe/blob/main/base/rt_traffic_controller.py"
click node_sim_traffic "https://github.com/xtrose29/rt-safe/blob/main/SimWorld/simworld/traffic/controller/traffic_controller.py"
click node_actors "https://github.com/xtrose29/rt-safe/blob/main/SimWorld/simworld/agent/vehicle.py"
click node_signals "https://github.com/xtrose29/rt-safe/blob/main/SimWorld/simworld/traffic/base/intersection.py"
click node_scenario "https://github.com/xtrose29/rt-safe/blob/main/run_scenario.py"
click node_experiment_runner "https://github.com/xtrose29/rt-safe/blob/main/evaluation/run_experiment_matrix.py"
click node_metrics "https://github.com/xtrose29/rt-safe/blob/main/utils/evaluation_metrics.py"
click node_aggregation "https://github.com/xtrose29/rt-safe/blob/main/evaluation/aggregate_results.py"
click node_replay "https://github.com/xtrose29/rt-safe/blob/main/evaluation/replay_recorded_rollout_video.py"
click node_website "https://github.com/xtrose29/rt-safe/blob/main/website/app/rtsafe.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_world_manager,node_communicator,node_unrealcv,node_scenario,node_user toneBlue
class node_agent_runtime,node_action_space,node_llm toneAmber
class node_traffic_system,node_traffic_controller,node_sim_traffic,node_actors,node_signals toneMint
class node_evaluator,node_experiment_runner,node_metrics,node_aggregation,node_replay,node_website toneRose
class node_model_service,node_unreal toneIndigo
```

## Components

### Runtime orchestration

- [World manager](https://github.com/xtrose29/rt-safe/blob/main/manager/world_manager.py): `manager/world_manager.py`
- [RT communicator](https://github.com/xtrose29/rt-safe/blob/main/base/rt_communicator.py): `base/rt_communicator.py`
- [UnrealCV bridge](https://github.com/xtrose29/rt-safe/blob/main/base/rt_unrealcv.py): `base/rt_unrealcv.py`
- [Scenario runner](https://github.com/xtrose29/rt-safe/blob/main/run_scenario.py): `run_scenario.py`

### Agent decisions

- [RT agent](https://github.com/xtrose29/rt-safe/blob/main/base/rt_agent.py): `base/rt_agent.py`
- [Action space](https://github.com/xtrose29/rt-safe/blob/main/base/rt_action_space.py): `base/rt_action_space.py`
- [Model adapters](https://github.com/xtrose29/rt-safe/blob/main/llm/rt_llm.py): `llm/rt_llm.py`

### Simulation world

- [RT traffic system](https://github.com/xtrose29/rt-safe/blob/main/base/rt_traffic_system.py): `base/rt_traffic_system.py`
- [Traffic controller](https://github.com/xtrose29/rt-safe/blob/main/base/rt_traffic_controller.py): `base/rt_traffic_controller.py`
- [SimWorld traffic](https://github.com/xtrose29/rt-safe/blob/main/SimWorld/simworld/traffic/controller/traffic_controller.py): `SimWorld/simworld/traffic/controller/traffic_controller.py`
- [Traffic actors](https://github.com/xtrose29/rt-safe/blob/main/SimWorld/simworld/agent/vehicle.py): `SimWorld/simworld/agent/vehicle.py`
- [Signals and junctions](https://github.com/xtrose29/rt-safe/blob/main/SimWorld/simworld/traffic/base/intersection.py): `SimWorld/simworld/traffic/base/intersection.py`

### Evaluation and presentation

- [Safety evaluator](https://github.com/xtrose29/rt-safe/blob/main/base/rt_evaluator.py): `base/rt_evaluator.py`
- [Experiment runners](https://github.com/xtrose29/rt-safe/blob/main/evaluation/run_experiment_matrix.py): `evaluation/run_experiment_matrix.py`
- [Evaluation metrics](https://github.com/xtrose29/rt-safe/blob/main/utils/evaluation_metrics.py): `utils/evaluation_metrics.py`
- [Result aggregation](https://github.com/xtrose29/rt-safe/blob/main/evaluation/aggregate_results.py): `evaluation/aggregate_results.py`
- [Rollout replay](https://github.com/xtrose29/rt-safe/blob/main/evaluation/replay_recorded_rollout_video.py): `evaluation/replay_recorded_rollout_video.py`
- [Benchmark website](https://github.com/xtrose29/rt-safe/blob/main/website/app/rtsafe.tsx): `website/app/rtsafe.tsx`

### Other components

- **Benchmark user**
- **Model provider**
- **Unreal runtime**

## Connections

- Benchmark user → Scenario runner: starts run
- Scenario runner → World manager: sets up world
- World manager → RT agent: coordinates agent (evidence: `manager/world_manager.py`)
- RT agent → Model adapters: requests decision (evidence: `base/rt_agent.py`)
- Model adapters → Model provider: queries model
- RT agent → Action space: uses actions (evidence: `base/rt_agent.py`)
- RT agent → Safety evaluator: records outcomes (evidence: `base/rt_agent.py`)
- World manager → RT communicator: uses bridge (evidence: `manager/world_manager.py`)
- RT communicator → UnrealCV bridge: delegates transport (evidence: `base/rt_communicator.py`)
- UnrealCV bridge → Unreal runtime: exchanges state
- World manager → Traffic controller: coordinates traffic (evidence: `manager/world_manager.py`)
- Traffic controller → SimWorld traffic: extends controller (evidence: `base/rt_traffic_controller.py`)
- SimWorld traffic → Traffic actors: manages actors (evidence: `SimWorld/simworld/traffic/controller/traffic_controller.py`)
- SimWorld traffic → Signals and junctions: coordinates signals (evidence: `SimWorld/simworld/traffic/controller/traffic_controller.py`)
- Benchmark user → Experiment runners: selects evaluation
- Experiment runners → World manager: runs scenarios
- Experiment runners → Evaluation metrics: scores rollouts
- Evaluation metrics → Result aggregation: feeds summaries
- Result aggregation → Benchmark website: publishes results
- Experiment runners → Rollout replay: supports replay
