# nssmd/roborsi architecture

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

- Interactive diagram: https://gitdiagram.com/nssmd/roborsi
- Repository: https://github.com/nssmd/roborsi

## Overview

RoboRSI is a multi-agent harness for robot self-evolution. Its principal workflow turns a user task into a Manager-led plan, Engineer execution through robot tools, and independent review; failures can lead to gated skill changes, while successful workflows can be consolidated or used for policy learning. The repository also includes frozen evaluation, dataset curation, chat channels, and web cockpit capabilities. The graph combines README-documented workflow with relationships visible in the supplied excerpts and SOURCE INDEX; unsampled implementation links are omitted where evidence is insufficient.

Main entry points: [`roborsi/agents/engineer.py`](https://github.com/nssmd/roborsi/blob/main/roborsi/agents/engineer.py) (Engineer), [`roborsi/embodied/agent_loop/rollout.py`](https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/agent_loop/rollout.py) (Agent rollout), [`frontend/web/src/App.tsx`](https://github.com/nssmd/roborsi/blob/main/frontend/web/src/App.tsx) (Web cockpit), [`roborsi/agents/manager_chat.py`](https://github.com/nssmd/roborsi/blob/main/roborsi/agents/manager_chat.py) (Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_roles["Task roles"]
  node_manager["Manager<br/>[manager_chat.py]"]
  node_planner["Planner<br/>[planner.py]"]
  node_engineer["Engineer<br/>[engineer.py]"]
  node_reviewer["Reviewer<br/>[reviewer.py]"]
  node_persistent["Role sessions"]
end

subgraph group_runtime["Robot execution"]
  node_rollout["Agent rollout<br/>[rollout.py]"]
  node_prompttools["Prompt tools<br/>[prompt_tools.py]"]
  node_skills["Robot skills<br/>[__init__.py]"]
  node_environment["Robot environment<br/>[env.py]"]
  node_vlm["Vision-language I/O<br/>[vlm_io.py]"]
end

subgraph group_evolution["Evolution and learning"]
  node_skilltree["Task-skill tree<br/>[scaffold.py]"]
  node_workspace["Task workspace<br/>[workspace.py]"]
  node_proposal["Skill proposals<br/>[proposal_safety.py]"]
  node_learning["Policy learning<br/>[auto_apply.py]"]
  node_curation["Dataset curation<br/>[service.py]"]
  node_evaluation["Frozen evaluation<br/>[suite.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_webapi["Web cockpit service<br/>[server.py]"]
  node_webapp["Web cockpit<br/>[App.tsx]"]
  node_webhooks["Web data hooks<br/>[hooks.ts]"]
  node_webformat["Display formatting<br/>[format.ts]"]
  node_webprimitives["UI primitives<br/>[primitives.tsx]"]
end

subgraph group_platform["Platform services"]
  node_runmode["Run mode<br/>[runtime_mode.py]"]
  node_providers["Model providers<br/>[registry.py]"]
  node_channels["Chat channels<br/>[manager.py]"]
  node_channelbase["Channel interface<br/>[base.py]"]
  node_channelagent["Channel agent<br/>[agent.py]"]
  node_trace[("Trace database<br/>[trace_db.py]")]
end

node_user(("Task requester"))

node_user -->|"submits task"| node_manager
node_manager -->|"decomposes tasks"| node_planner
node_planner -->|"provides plan"| node_engineer
node_engineer -->|"runs episode"| node_rollout
node_rollout -->|"dispatches tools"| node_prompttools
node_rollout -->|"acts in"| node_environment
node_rollout -->|"uses model I/O"| node_vlm
node_prompttools -->|"exposes skills"| node_skills
node_engineer -->|"submits trace"| node_reviewer
node_reviewer -->|"proposes revision"| node_proposal
node_reviewer -->|"locates failure"| node_skilltree
node_proposal -->|"requests gate"| node_manager
node_engineer -->|"records outcome"| node_workspace
node_engineer -.->|"records execution"| node_trace
node_engineer -->|"supplies experience"| node_learning
node_learning -.->|"prepares training data"| node_curation
node_evaluation -->|"freezes mutations"| node_runmode
node_persistent -->|"uses channel agent"| node_channelagent
node_channels -->|"initializes channels"| node_channelbase
node_manager -->|"uses sessions"| node_persistent
node_rollout -.->|"selects model"| node_providers
node_webapi -.->|"serves cockpit"| node_webapp
node_webapp -->|"reads data"| node_webhooks
node_webapp -->|"formats views"| node_webformat
node_webapp -->|"renders controls"| node_webprimitives

click node_manager "https://github.com/nssmd/roborsi/blob/main/roborsi/agents/manager_chat.py"
click node_planner "https://github.com/nssmd/roborsi/blob/main/roborsi/agents/planner.py"
click node_engineer "https://github.com/nssmd/roborsi/blob/main/roborsi/agents/engineer.py"
click node_reviewer "https://github.com/nssmd/roborsi/blob/main/roborsi/agents/reviewer.py"
click node_persistent "https://github.com/nssmd/roborsi/blob/main/roborsi/agents/persistent_agent.py"
click node_rollout "https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/agent_loop/rollout.py"
click node_prompttools "https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/agent_loop/prompt_tools.py"
click node_skills "https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/skills/__init__.py"
click node_environment "https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/agent_loop/env.py"
click node_vlm "https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/agent_loop/vlm_io.py"
click node_skilltree "https://github.com/nssmd/roborsi/blob/main/roborsi/agent/lifecycle/scaffold.py"
click node_workspace "https://github.com/nssmd/roborsi/blob/main/roborsi/agents/workspace.py"
click node_proposal "https://github.com/nssmd/roborsi/blob/main/roborsi/agents/proposal_safety.py"
click node_learning "https://github.com/nssmd/roborsi/blob/main/roborsi/learning/auto_apply.py"
click node_curation "https://github.com/nssmd/roborsi/blob/main/roborsi/data/curation/service.py"
click node_evaluation "https://github.com/nssmd/roborsi/blob/main/roborsi/evaluation/suite.py"
click node_runmode "https://github.com/nssmd/roborsi/blob/main/roborsi/runtime_mode.py"
click node_providers "https://github.com/nssmd/roborsi/blob/main/roborsi/providers/registry.py"
click node_channels "https://github.com/nssmd/roborsi/blob/main/roborsi/channels/manager.py"
click node_channelbase "https://github.com/nssmd/roborsi/blob/main/roborsi/channels/base.py"
click node_channelagent "https://github.com/nssmd/roborsi/blob/main/roborsi/channels/core/agent.py"
click node_trace "https://github.com/nssmd/roborsi/blob/main/roborsi/store/trace_db.py"
click node_webapi "https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/board/web/server.py"
click node_webapp "https://github.com/nssmd/roborsi/blob/main/frontend/web/src/App.tsx"
click node_webhooks "https://github.com/nssmd/roborsi/blob/main/frontend/web/src/lib/hooks.ts"
click node_webformat "https://github.com/nssmd/roborsi/blob/main/frontend/web/src/lib/format.ts"
click node_webprimitives "https://github.com/nssmd/roborsi/blob/main/frontend/web/src/components/primitives.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_manager,node_planner,node_engineer,node_reviewer,node_persistent toneBlue
class node_rollout,node_prompttools,node_skills,node_environment,node_vlm toneAmber
class node_skilltree,node_workspace,node_proposal,node_learning,node_curation,node_evaluation toneMint
class node_webapi,node_webapp,node_webhooks,node_webformat,node_webprimitives,node_user toneRose
class node_runmode,node_providers,node_channels,node_channelbase,node_channelagent,node_trace toneIndigo
```

## Components

### Task roles

- [Manager](https://github.com/nssmd/roborsi/blob/main/roborsi/agents/manager_chat.py): `roborsi/agents/manager_chat.py`
- [Planner](https://github.com/nssmd/roborsi/blob/main/roborsi/agents/planner.py): `roborsi/agents/planner.py`
- [Engineer](https://github.com/nssmd/roborsi/blob/main/roborsi/agents/engineer.py): `roborsi/agents/engineer.py`
- [Reviewer](https://github.com/nssmd/roborsi/blob/main/roborsi/agents/reviewer.py): `roborsi/agents/reviewer.py`
- [Role sessions](https://github.com/nssmd/roborsi/blob/main/roborsi/agents/persistent_agent.py): `roborsi/agents/persistent_agent.py`

### Robot execution

- [Agent rollout](https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/agent_loop/rollout.py): `roborsi/embodied/agent_loop/rollout.py`
- [Prompt tools](https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/agent_loop/prompt_tools.py): `roborsi/embodied/agent_loop/prompt_tools.py`
- [Robot skills](https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/skills/__init__.py): `roborsi/embodied/skills/__init__.py`
- [Robot environment](https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/agent_loop/env.py): `roborsi/embodied/agent_loop/env.py`
- [Vision-language I/O](https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/agent_loop/vlm_io.py): `roborsi/embodied/agent_loop/vlm_io.py`

### Evolution and learning

- [Task-skill tree](https://github.com/nssmd/roborsi/blob/main/roborsi/agent/lifecycle/scaffold.py): `roborsi/agent/lifecycle/scaffold.py`
- [Task workspace](https://github.com/nssmd/roborsi/blob/main/roborsi/agents/workspace.py): `roborsi/agents/workspace.py`
- [Skill proposals](https://github.com/nssmd/roborsi/blob/main/roborsi/agents/proposal_safety.py): `roborsi/agents/proposal_safety.py`
- [Policy learning](https://github.com/nssmd/roborsi/blob/main/roborsi/learning/auto_apply.py): `roborsi/learning/auto_apply.py`
- [Dataset curation](https://github.com/nssmd/roborsi/blob/main/roborsi/data/curation/service.py): `roborsi/data/curation/service.py`
- [Frozen evaluation](https://github.com/nssmd/roborsi/blob/main/roborsi/evaluation/suite.py): `roborsi/evaluation/suite.py`

### User interfaces

- [Web cockpit service](https://github.com/nssmd/roborsi/blob/main/roborsi/embodied/board/web/server.py): `roborsi/embodied/board/web/server.py`
- [Web cockpit](https://github.com/nssmd/roborsi/blob/main/frontend/web/src/App.tsx): `frontend/web/src/App.tsx`
- [Web data hooks](https://github.com/nssmd/roborsi/blob/main/frontend/web/src/lib/hooks.ts): `frontend/web/src/lib/hooks.ts`
- [Display formatting](https://github.com/nssmd/roborsi/blob/main/frontend/web/src/lib/format.ts): `frontend/web/src/lib/format.ts`
- [UI primitives](https://github.com/nssmd/roborsi/blob/main/frontend/web/src/components/primitives.tsx): `frontend/web/src/components/primitives.tsx`

### Platform services

- [Run mode](https://github.com/nssmd/roborsi/blob/main/roborsi/runtime_mode.py): `roborsi/runtime_mode.py`
- [Model providers](https://github.com/nssmd/roborsi/blob/main/roborsi/providers/registry.py): `roborsi/providers/registry.py`
- [Chat channels](https://github.com/nssmd/roborsi/blob/main/roborsi/channels/manager.py): `roborsi/channels/manager.py`
- [Channel interface](https://github.com/nssmd/roborsi/blob/main/roborsi/channels/base.py): `roborsi/channels/base.py`
- [Channel agent](https://github.com/nssmd/roborsi/blob/main/roborsi/channels/core/agent.py): `roborsi/channels/core/agent.py`
- [Trace database](https://github.com/nssmd/roborsi/blob/main/roborsi/store/trace_db.py): `roborsi/store/trace_db.py`

### Other components

- **Task requester**

## Connections

- Task requester → Manager: submits task (evidence: `README.md`)
- Manager → Planner: decomposes tasks (evidence: `README.md`)
- Planner → Engineer: provides plan (evidence: `README.md`)
- Engineer → Agent rollout: runs episode (evidence: `roborsi/agents/engineer.py`)
- Agent rollout → Prompt tools: dispatches tools (evidence: `roborsi/embodied/agent_loop/rollout.py`)
- Agent rollout → Robot environment: acts in (evidence: `roborsi/embodied/agent_loop/rollout.py`)
- Agent rollout → Vision-language I/O: uses model I/O (evidence: `roborsi/embodied/agent_loop/rollout.py`)
- Prompt tools → Robot skills: exposes skills (evidence: `README.md`)
- Engineer → Reviewer: submits trace (evidence: `README.md`)
- Reviewer → Skill proposals: proposes revision (evidence: `README.md`)
- Reviewer → Task-skill tree: locates failure (evidence: `README.md`)
- Skill proposals → Manager: requests gate (evidence: `README.md`)
- Engineer → Task workspace: records outcome (evidence: `roborsi/agents/engineer.py`)
- Engineer → Trace database: records execution
- Engineer → Policy learning: supplies experience (evidence: `README.md`)
- Policy learning → Dataset curation: prepares training data
- Frozen evaluation → Run mode: freezes mutations (evidence: `roborsi/runtime_mode.py`)
- Role sessions → Channel agent: uses channel agent (evidence: `roborsi/agents/persistent_agent.py`)
- Chat channels → Channel interface: initializes channels (evidence: `roborsi/channels/manager.py`)
- Manager → Role sessions: uses sessions (evidence: `roborsi/agents/manager_chat.py`)
- Agent rollout → Model providers: selects model
- Web cockpit service → Web cockpit: serves cockpit
- Web cockpit → Web data hooks: reads data (evidence: `frontend/web/src/App.tsx`)
- Web cockpit → Display formatting: formats views
- Web cockpit → UI primitives: renders controls
