# mingrui-yu/sharpa_rl_unilab architecture

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

- Interactive diagram: https://gitdiagram.com/mingrui-yu/sharpa_rl_unilab
- Repository: https://github.com/mingrui-yu/sharpa_rl_unilab
- Video tour (about a minute): https://gitdiagram.com/mingrui-yu/sharpa_rl_unilab/video

## Overview

This package provides a UniLab Manager-Based Sharpa Wave task and a policy lifecycle: configure/train a PPO, APPO, or FlashSAC teacher, optionally distill it into a student, then evaluate checkpoints or record playback. Task manager terms define physical actions, observations, reset/randomization, rewards and episode endings; training adapters connect the task to algorithm runners and shared HORA models. README documents these capabilities, but sampled excerpts do not establish every manager-term or runner call, so uncertain wiring is omitted. UniLab simulation and manager lifecycle remain external.

Main entry points: [`src/sharpa_rl_unilab/tasks/sharpa_inhand/teacher_env.py`](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/teacher_env.py) (Observation and reset adapter), [`src/sharpa_rl_unilab/training/teacher_runtime.py`](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/teacher_runtime.py) (Teacher runtime), [`src/sharpa_rl_unilab/cli.py`](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/cli.py) (Task CLI), [`src/sharpa_rl_unilab/training/playback.py`](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/playback.py) (Policy playback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_task["Manipulation task"]
  node_task_env["Observation and reset adapter<br/>[teacher_env.py]"]
  node_protocol["Observation protocol<br/>[protocol.py]"]
  node_terms_action["Incremental actions<br/>[action.py]"]
  node_terms_observation["Tactile observations<br/>[observation.py]"]
  node_terms_reset["Grasp reset<br/>[reset.py]"]
  node_terms_randomization["Physical randomization<br/>[randomization.py]"]
  node_terms_rewards["Rewards and termination<br/>[rewards.py]"]
  node_grasp_registry["Grasp registry<br/>[grasp_registry.py]"]
  node_rotation_registry["Rotation registry"]
end

subgraph group_learning["Policy learning"]
  node_ppo["PPO runtime<br/>[ppo_runtime.py]"]
  node_appo["APPO runtime<br/>[appo_runtime.py]"]
  node_flashsac["FlashSAC runtime"]
  node_hora["Shared HORA models<br/>[models.py]"]
  node_distribution["Policy distribution<br/>[distribution.py]"]
  node_on_policy["PPO/APPO adapters<br/>[on_policy.py]"]
end

subgraph group_lifecycle["Training lifecycle"]
  node_cli["Task CLI<br/>[cli.py]"]
  node_config["Task configuration<br/>[config.py]"]
  node_teacher["Teacher runtime<br/>[teacher_runtime.py]"]
  node_student["Student distillation<br/>[student_runtime.py]"]
  node_checkpoint["Checkpoint handling<br/>[checkpoints.py]"]
  node_compare["Algorithm comparison<br/>[compare_rl_algo.py]"]
end

subgraph group_evaluation["Evaluation and playback"]
  node_evaluation["Checkpoint evaluation<br/>[evaluation.py]"]
  node_playback["Policy playback<br/>[playback.py]"]
  node_rendering["Video rendering<br/>[rendering.py]"]
end

node_user(("Engineer"))
node_unilab["UniLab manager and simulator"]
node_external_sim["MuJoCo backend"]

node_user -->|"selects run"| node_cli
node_cli -->|"composes config"| node_config
node_cli -->|"starts training"| node_teacher
node_cli -->|"evaluates checkpoint"| node_evaluation
node_cli -->|"plays checkpoint"| node_playback
node_config -->|"configures task"| node_unilab
node_unilab -->|"creates environment"| node_task_env
node_task_env -->|"validates layout"| node_protocol
node_task_env -->|"reads observations"| node_terms_observation
node_terms_observation -->|"resolves action term"| node_terms_action
node_unilab -->|"dispatches actions"| node_terms_action
node_unilab -->|"dispatches resets"| node_terms_reset
node_unilab -->|"dispatches events"| node_terms_randomization
node_unilab -->|"computes episode outcome"| node_terms_rewards
node_terms_reset -->|"uses grasp cache"| node_grasp_registry
node_config -.->|"selects rotation task"| node_rotation_registry
node_teacher -->|"constructs environment"| node_task_env
node_teacher -.->|"runs PPO"| node_ppo
node_teacher -.->|"runs APPO"| node_appo
node_teacher -.->|"runs FlashSAC"| node_flashsac
node_ppo -->|"uses policy"| node_hora
node_appo -->|"uses policy"| node_hora
node_flashsac -->|"uses policy"| node_hora
node_ppo -->|"uses adapter"| node_on_policy
node_appo -->|"uses adapter"| node_on_policy
node_on_policy -->|"computes distribution"| node_distribution
node_teacher -->|"saves teacher"| node_checkpoint
node_student -->|"loads and saves"| node_checkpoint
node_student -->|"collects rollouts"| node_task_env
node_student -->|"builds student actor"| node_hora
node_evaluation -->|"loads checkpoint"| node_checkpoint
node_evaluation -->|"runs episodes"| node_task_env
node_playback -->|"loads checkpoint"| node_checkpoint
node_playback -->|"runs policy"| node_task_env
node_playback -->|"records video"| node_rendering
node_compare -->|"launches runs"| node_cli
node_compare -.->|"launches distillation"| node_student
node_compare -.->|"launches evaluation"| node_evaluation
node_unilab -.->|"uses backend"| node_external_sim

click node_cli "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/cli.py"
click node_config "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/config.py"
click node_task_env "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/teacher_env.py"
click node_protocol "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/protocol.py"
click node_terms_action "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/action.py"
click node_terms_observation "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/observation.py"
click node_terms_reset "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/reset.py"
click node_terms_randomization "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/randomization.py"
click node_terms_rewards "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/rewards.py"
click node_grasp_registry "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/grasp_registry.py"
click node_rotation_registry "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/rotation_registry.py"
click node_ppo "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/ppo_runtime.py"
click node_appo "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/appo_runtime.py"
click node_flashsac "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/flashsac_runtime.py"
click node_hora "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/algos/hora/models.py"
click node_distribution "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/algos/hora/distribution.py"
click node_on_policy "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/algos/hora/on_policy.py"
click node_teacher "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/teacher_runtime.py"
click node_student "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/student_runtime.py"
click node_checkpoint "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/checkpoints.py"
click node_evaluation "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/evaluation.py"
click node_playback "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/playback.py"
click node_rendering "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/rendering.py"
click node_compare "https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tools/compare_rl_algo.py"

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_task_env,node_protocol,node_terms_action,node_terms_observation,node_terms_reset,node_terms_randomization,node_terms_rewards,node_grasp_registry,node_rotation_registry toneBlue
class node_ppo,node_appo,node_flashsac,node_hora,node_distribution,node_on_policy toneAmber
class node_cli,node_config,node_teacher,node_student,node_checkpoint,node_compare toneMint
class node_evaluation,node_playback,node_rendering toneRose
class node_user,node_unilab,node_external_sim toneIndigo
```

## Components

### Manipulation task

- [Observation and reset adapter](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/teacher_env.py): `src/sharpa_rl_unilab/tasks/sharpa_inhand/teacher_env.py`
- [Observation protocol](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/protocol.py): `src/sharpa_rl_unilab/tasks/sharpa_inhand/protocol.py`
- [Incremental actions](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/action.py): `src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/action.py`
- [Tactile observations](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/observation.py): `src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/observation.py`
- [Grasp reset](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/reset.py): `src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/reset.py`
- [Physical randomization](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/randomization.py): `src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/randomization.py`
- [Rewards and termination](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/rewards.py): `src/sharpa_rl_unilab/tasks/sharpa_inhand/terms/rewards.py`
- [Grasp registry](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/grasp_registry.py): `src/sharpa_rl_unilab/tasks/sharpa_inhand/grasp_registry.py`
- [Rotation registry](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/rotation_registry.py): `src/sharpa_rl_unilab/tasks/sharpa_inhand/rotation_registry.py`

### Policy learning

- [PPO runtime](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/ppo_runtime.py): `src/sharpa_rl_unilab/training/ppo_runtime.py`
- [APPO runtime](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/appo_runtime.py): `src/sharpa_rl_unilab/training/appo_runtime.py`
- [FlashSAC runtime](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/flashsac_runtime.py): `src/sharpa_rl_unilab/training/flashsac_runtime.py`
- [Shared HORA models](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/algos/hora/models.py): `src/sharpa_rl_unilab/algos/hora/models.py`
- [Policy distribution](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/algos/hora/distribution.py): `src/sharpa_rl_unilab/algos/hora/distribution.py`
- [PPO/APPO adapters](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/algos/hora/on_policy.py): `src/sharpa_rl_unilab/algos/hora/on_policy.py`

### Training lifecycle

- [Task CLI](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/cli.py): `src/sharpa_rl_unilab/cli.py`
- [Task configuration](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tasks/sharpa_inhand/config.py): `src/sharpa_rl_unilab/tasks/sharpa_inhand/config.py`
- [Teacher runtime](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/teacher_runtime.py): `src/sharpa_rl_unilab/training/teacher_runtime.py`
- [Student distillation](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/student_runtime.py): `src/sharpa_rl_unilab/training/student_runtime.py`
- [Checkpoint handling](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/checkpoints.py): `src/sharpa_rl_unilab/training/checkpoints.py`
- [Algorithm comparison](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/tools/compare_rl_algo.py): `src/sharpa_rl_unilab/tools/compare_rl_algo.py`

### Evaluation and playback

- [Checkpoint evaluation](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/evaluation.py): `src/sharpa_rl_unilab/training/evaluation.py`
- [Policy playback](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/playback.py): `src/sharpa_rl_unilab/training/playback.py`
- [Video rendering](https://github.com/mingrui-yu/sharpa_rl_unilab/blob/main/src/sharpa_rl_unilab/training/rendering.py): `src/sharpa_rl_unilab/training/rendering.py`

### Other components

- **Engineer**
- **UniLab manager and simulator**
- **MuJoCo backend**

## Connections

- Engineer → Task CLI: selects run
- Task CLI → Task configuration: composes config
- Task CLI → Teacher runtime: starts training
- Task CLI → Checkpoint evaluation: evaluates checkpoint
- Task CLI → Policy playback: plays checkpoint
- Task configuration → UniLab manager and simulator: configures task
- UniLab manager and simulator → Observation and reset adapter: creates environment
- Observation and reset adapter → Observation protocol: validates layout
- Observation and reset adapter → Tactile observations: reads observations
- Tactile observations → Incremental actions: resolves action term
- UniLab manager and simulator → Incremental actions: dispatches actions
- UniLab manager and simulator → Grasp reset: dispatches resets
- UniLab manager and simulator → Physical randomization: dispatches events
- UniLab manager and simulator → Rewards and termination: computes episode outcome
- Grasp reset → Grasp registry: uses grasp cache
- Task configuration → Rotation registry: selects rotation task
- Teacher runtime → Observation and reset adapter: constructs environment
- Teacher runtime → PPO runtime: runs PPO
- Teacher runtime → APPO runtime: runs APPO
- Teacher runtime → FlashSAC runtime: runs FlashSAC
- PPO runtime → Shared HORA models: uses policy
- APPO runtime → Shared HORA models: uses policy
- FlashSAC runtime → Shared HORA models: uses policy
- PPO runtime → PPO/APPO adapters: uses adapter
- APPO runtime → PPO/APPO adapters: uses adapter
- PPO/APPO adapters → Policy distribution: computes distribution
- Teacher runtime → Checkpoint handling: saves teacher
- Student distillation → Checkpoint handling: loads and saves
- Student distillation → Observation and reset adapter: collects rollouts
- Student distillation → Shared HORA models: builds student actor
- Checkpoint evaluation → Checkpoint handling: loads checkpoint
- Checkpoint evaluation → Observation and reset adapter: runs episodes
- Policy playback → Checkpoint handling: loads checkpoint
- Policy playback → Observation and reset adapter: runs policy
- Policy playback → Video rendering: records video
- Algorithm comparison → Task CLI: launches runs
- Algorithm comparison → Student distillation: launches distillation
- Algorithm comparison → Checkpoint evaluation: launches evaluation
- UniLab manager and simulator → MuJoCo backend: uses backend