# robochallenge/robochallengeinference architecture
> Architecture diagram of the GitHub repository robochallenge/robochallengeinference, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/robochallenge/robochallengeinference
- Repository: https://github.com/robochallenge/robochallengeinference
## Overview
1. **What this repo is for**
- This is an inference/runtime package for RoboChallenge robotics tasks, not a training repo.
- The core job is to connect a policy implementation to a robot API, with a mock robot server for local debugging.
2. **Main execution entrypoints**
- `test.py` is the primary test runner used during local evaluation.
- `demo.py` is the place to plug in custom inference logic; the README points to it as the file to modify for your policy.
- These scripts sit above the rest of the repo and orchestrate loading data, querying robot state, and sending actions.
3. **Robot interface boundary**
- `robot/interface_client.py` is the client-facing boundary to the robot’s direct HTTP API.
- The README defines the key endpoints this layer targets: `clock-sync`, `state.pkl`, and `action`.
- This layer is responsible for adapting model output into the robot’s required action shape and timing.
4. **Job/runtime orchestration**
- `robot/job_worker.py` appears to manage the execution loop for a job: polling state, invoking inference, and pushing actions.
- Architecturally, this is the control-plane piece that sits between the evaluation harness and the robot interface.
- It likely handles queueing, timing, and the “pending actions” style backpressure exposed by the API.
5. **Mock robot subsystem**
- `mock_server/mock_robot_server.py` provides a local stand-in for the real robot service.
- `mock_server/mock_rc_robot.py` likely implements the simulated robot behavior and state transitions.
- `mock_server/mock_settings.py` is a key configuration boundary: it selects the active `ROBOT_TAG` and `RECORD_DATA_DIR`.
- `mock_server/utils.py` supports the mock environment with helper functions.
6. **How local testing works**
- The intended local loop is: start the mock server, then run `test.py` against it.
- `test.py` consumes the mock API just like the real interface, so model behavior can be validated without hardware access.
- This means the mock server is the main architectural substitute for the production robot during development.
7. **Dataset / episode storage**
- The `20250919/` tree contains task-specific recorded episodes used for evaluation or replay.
- Each task folder, such as `arrange_paper_cups`, `pour_fries_into_plate`, `press_three_buttons`, and `shred_scrap_paper`, contains one or more `episode_*` directories.
- Each episode is organized into `meta/`, `states/`, and `videos/`, making the dataset a multimodal bundle of metadata, time-series robot state, and camera recordings.
8. **Episode file structure**
- `meta/episode_meta.json` stores episode-level metadata.
- `states/*.jsonl` stores time-ordered robot state traces; some tasks use one stream (`states.jsonl`), others split per arm (`left_states.jsonl`, `right_states.jsonl`).
- `videos/*.mp4` contains synchronized camera feeds, with camera names indicating viewpoint and robot type.
9. **Observation and action flow**
- The robot API returns a pickle payload from `state.pkl` containing robot state, timestamp, current action, pending action count, and selected camera images.
- The policy consumes these observations and emits a batch of actions through `POST /action`.
- The data flow is therefore: camera/state observation in, batched control commands out, with the robot server enforcing shape and control-mode consistency.
10. **Robot-type dependent control contract**
- The repository is explicitly built around multiple robot families: Aloha, Arx5, Ur5, and Franka.
- Action shape and camera availability depend on the robot tag and the chosen `action_type` (`joint` vs `pos`, and `left/right` variants).
- This is an important architectural boundary: the inference code must be aware of robot-specific action semantics, not just task semantics.
11. **Shared utilities**
- `utils/enums.py`, `utils/log.py`, and `utils/util.py` hold cross-cutting support for the rest of the system.
- These modules are the common infrastructure for type/enum definitions, logging, and helper logic used by both the robot client and mock server.
12. **Packaging and runtime assumptions**
- `requirements.txt` indicates a Python-based runtime.
- The repo is built for a single-process local development workflow but maps cleanly onto a remote robot service in production.
- The main architectural boundary is between the policy/runtime code in this repo and the external robot service defined by the README API.
Main entry points: [`mock_server/mock_robot_server.py`](https://github.com/robochallenge/robochallengeinference/blob/main/mock_server/mock_robot_server.py) (Mock server), [`20250919`](https://github.com/robochallenge/robochallengeinference/tree/main/20250919) (Episodes), [`robot/interface_client.py`](https://github.com/robochallenge/robochallengeinference/blob/main/robot/interface_client.py) (Interface client), [`robot/job_worker.py`](https://github.com/robochallenge/robochallengeinference/blob/main/robot/job_worker.py) (Job worker)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_entrypoints["Entry points"]
node_test_py["test.py
runner
[test.py]"]
node_demo_py["demo.py
policy hook
[demo.py]"]
end
subgraph group_robot_runtime["Robot runtime"]
node_job_worker["Job worker
control loop
[job_worker.py]"]
node_interface_client["Interface client
robot client"]
node_robot_api[("Robot API
external service")]
end
subgraph group_mock_robot["Mock robot"]
node_mock_server["Mock server
api server"]
node_mock_rc_robot["Mock robot
simulated robot
[mock_rc_robot.py]"]
node_mock_settings["Mock settings
config
[mock_settings.py]"]
node_mock_utils["Mock utils
helpers
[utils.py]"]
end
subgraph group_shared["Shared utils"]
node_enums["Enums
shared types
[enums.py]"]
node_log["Logging
[log.py]"]
node_util["Util helpers
shared helpers
[util.py]"]
end
subgraph group_dataset["Recorded data"]
node_episode_bundle[("Episodes")]
node_arrange_task["Arrange cups
task data"]
node_pour_task["Pour fries
task data"]
node_press_task["Press buttons
task data"]
node_shred_task["Shred paper
task data"]
end
node_test_py -->|"runs"| node_job_worker
node_demo_py -->|"implements policy for"| node_job_worker
node_job_worker -->|"sends actions"| node_interface_client
node_interface_client -->|"calls"| node_robot_api
node_test_py -->|"targets"| node_mock_server
node_mock_server -->|"drives"| node_mock_rc_robot
node_mock_server -->|"reads config"| node_mock_settings
node_mock_server -->|"uses"| node_mock_utils
node_job_worker -->|"invokes"| node_demo_py
node_interface_client -->|"uses"| node_enums
node_interface_client -->|"uses"| node_util
node_mock_server -->|"logs with"| node_log
node_mock_server -->|"uses"| node_util
node_mock_rc_robot -->|"uses"| node_enums
node_episode_bundle -->|"contains"| node_arrange_task
node_episode_bundle -->|"contains"| node_pour_task
node_episode_bundle -->|"contains"| node_press_task
node_episode_bundle -->|"contains"| node_shred_task
click node_test_py "https://github.com/robochallenge/robochallengeinference/blob/main/test.py"
click node_demo_py "https://github.com/robochallenge/robochallengeinference/blob/main/demo.py"
click node_job_worker "https://github.com/robochallenge/robochallengeinference/blob/main/robot/job_worker.py"
click node_interface_client "https://github.com/robochallenge/robochallengeinference/blob/main/robot/interface_client.py"
click node_mock_server "https://github.com/robochallenge/robochallengeinference/blob/main/mock_server/mock_robot_server.py"
click node_mock_rc_robot "https://github.com/robochallenge/robochallengeinference/blob/main/mock_server/mock_rc_robot.py"
click node_mock_settings "https://github.com/robochallenge/robochallengeinference/blob/main/mock_server/mock_settings.py"
click node_mock_utils "https://github.com/robochallenge/robochallengeinference/blob/main/mock_server/utils.py"
click node_enums "https://github.com/robochallenge/robochallengeinference/blob/main/utils/enums.py"
click node_log "https://github.com/robochallenge/robochallengeinference/blob/main/utils/log.py"
click node_util "https://github.com/robochallenge/robochallengeinference/blob/main/utils/util.py"
click node_episode_bundle "https://github.com/robochallenge/robochallengeinference/tree/main/20250919"
click node_arrange_task "https://github.com/robochallenge/robochallengeinference/tree/main/20250919/arrange_paper_cups"
click node_pour_task "https://github.com/robochallenge/robochallengeinference/tree/main/20250919/pour_fries_into_plate"
click node_press_task "https://github.com/robochallenge/robochallengeinference/tree/main/20250919/press_three_buttons"
click node_shred_task "https://github.com/robochallenge/robochallengeinference/tree/main/20250919/shred_scrap_paper"
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_test_py,node_demo_py toneBlue
class node_job_worker,node_interface_client,node_robot_api toneAmber
class node_mock_server,node_mock_rc_robot,node_mock_settings,node_mock_utils toneMint
class node_enums,node_log,node_util toneRose
class node_episode_bundle,node_arrange_task,node_pour_task,node_press_task,node_shred_task toneIndigo
```
## Components
### Entry points
Scripts that launch local inference and evaluation loops.
- [test.py](https://github.com/robochallenge/robochallengeinference/blob/main/test.py): runner · Primary local evaluation entrypoint. · `test.py`
- [demo.py](https://github.com/robochallenge/robochallengeinference/blob/main/demo.py): policy hook · User-editable inference entrypoint for custom policy logic. · `demo.py`
### Robot runtime
Client boundary and job orchestration between policy code and robot service.
- [Job worker](https://github.com/robochallenge/robochallengeinference/blob/main/robot/job_worker.py): control loop · Coordinates state polling, inference calls, and action submission. · `robot/job_worker.py`
- [Interface client](https://github.com/robochallenge/robochallengeinference/blob/main/robot/interface_client.py): robot client · HTTP boundary for robot state, clock sync, and action submission. · `robot/interface_client.py`
- **Robot API**: external service · Production robot service exposing state and action endpoints.
### Mock robot
Local stand-in for the production robot API used during development.
- [Mock server](https://github.com/robochallenge/robochallengeinference/blob/main/mock_server/mock_robot_server.py): api server · Local HTTP server that emulates the robot interface. · `mock_server/mock_robot_server.py`
- [Mock robot](https://github.com/robochallenge/robochallengeinference/blob/main/mock_server/mock_rc_robot.py): simulated robot · Simulated robot state and behavior used by the mock server. · `mock_server/mock_rc_robot.py`
- [Mock settings](https://github.com/robochallenge/robochallengeinference/blob/main/mock_server/mock_settings.py): config · Selects robot tag and recording directory for the mock environment. · `mock_server/mock_settings.py`
- [Mock utils](https://github.com/robochallenge/robochallengeinference/blob/main/mock_server/utils.py): helpers · Support functions for the mock robot environment. · `mock_server/utils.py`
### Shared utils
Cross-cutting enums, logging, and helper utilities.
- [Enums](https://github.com/robochallenge/robochallengeinference/blob/main/utils/enums.py): shared types · Shared constants and type-like definitions. · `utils/enums.py`
- [Logging](https://github.com/robochallenge/robochallengeinference/blob/main/utils/log.py): shared logging · Common logging setup used across runtime and server code. · `utils/log.py`
- [Util helpers](https://github.com/robochallenge/robochallengeinference/blob/main/utils/util.py): shared helpers · General-purpose helper functions. · `utils/util.py`
### Recorded data
Task episodes used for evaluation, replay, and debugging.
- [Episodes](https://github.com/robochallenge/robochallengeinference/tree/main/20250919): recorded episodes · Per-task multimodal episode bundles with metadata, states, and videos. · `20250919`
- [Arrange cups](https://github.com/robochallenge/robochallengeinference/tree/main/20250919/arrange_paper_cups): task data · Recorded episode data for arrange_paper_cups. · `20250919/arrange_paper_cups`
- [Pour fries](https://github.com/robochallenge/robochallengeinference/tree/main/20250919/pour_fries_into_plate): task data · Recorded episode data for pour_fries_into_plate. · `20250919/pour_fries_into_plate`
- [Press buttons](https://github.com/robochallenge/robochallengeinference/tree/main/20250919/press_three_buttons): task data · Recorded episode data for press_three_buttons. · `20250919/press_three_buttons`
- [Shred paper](https://github.com/robochallenge/robochallengeinference/tree/main/20250919/shred_scrap_paper): task data · Recorded episode data for shred_scrap_paper. · `20250919/shred_scrap_paper`
## Connections
- test.py → Job worker: runs · Local evaluation entrypoint launches the job execution loop.
- demo.py → Job worker: implements policy for · Custom inference logic is plugged into the runtime loop.
- Job worker → Interface client: sends actions · Execution loop pushes observations and actions through the robot boundary.
- Interface client → Robot API: calls · Client talks to the production robot HTTP API.
- test.py → Mock server: targets · Local testing is commonly run against the mock robot server.
- Mock server → Mock robot: drives · HTTP server delegates robot behavior and state transitions.
- Mock server → Mock settings: reads config · Mock server is configured by robot tag and recording directory.
- Mock server → Mock utils: uses · Server relies on support helpers for the emulated environment.
- Job worker → demo.py: invokes · Runtime calls the policy hook to produce actions.
- Interface client → Enums: uses · Robot client shares action/state definitions with the rest of the repo.
- Interface client → Util helpers: uses · Client relies on common helper functions.
- Mock server → Logging: logs with · Mock server uses shared logging infrastructure.
- Mock server → Util helpers: uses · Mock server uses common helper functions.
- Mock robot → Enums: uses · Simulated robot follows shared control and state conventions.
- Episodes → Arrange cups: contains · Dataset root organizes task-specific episode collections.
- Episodes → Pour fries: contains · Dataset root organizes task-specific episode collections.
- Episodes → Press buttons: contains · Dataset root organizes task-specific episode collections.
- Episodes → Shred paper: contains · Dataset root organizes task-specific episode collections.