# oceanflowlab/taro architecture

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

- Interactive diagram: https://gitdiagram.com/oceanflowlab/taro
- Repository: https://github.com/oceanflowlab/taro

## Overview

TaRO is a framework and set of model assets for training video-temporal-grounding models and evaluating or demoing them. Its documented training approach moves from supervised imitation of constructed reasoning toward self-exploration, with temporal-sensitivity rewards; the user-facing result is a grounded temporal answer. The graph also captures the verl training runtime and checkpoint/model handling. Some TaRO source files and most verl modules were not excerpted, so their internal call relationships are omitted where the evidence does not show them.

Main entry points: [`verl/trainer/ppo/ray_trainer.py`](https://github.com/oceanflowlab/taro/blob/main/verl/trainer/ppo/ray_trainer.py) (PPO training loop), [`verl/workers`](https://github.com/oceanflowlab/taro/tree/main/verl/workers) (Training workers), [`standalone_eval/evaluate_vtg.py`](https://github.com/oceanflowlab/taro/blob/main/standalone_eval/evaluate_vtg.py) (VTG evaluation), [`verl/single_controller/base/decorator.py`](https://github.com/oceanflowlab/taro/blob/main/verl/single_controller/base/decorator.py) (Worker dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_taro["TaRO application"]
  node_demo["Interactive demo<br/>[demo.py]"]
  node_vtg_data["VTG data<br/>[vtg_dataset.py]"]
  node_reasoning["Constructed reasoning<br/>[utils.py]"]
  node_temporal_reward["Temporal reward<br/>[rewards.py]"]
  node_eval["VTG evaluation<br/>[evaluate_vtg.py]"]
  node_eval_config["Dataset configuration<br/>[dataset_config.py]"]
end

subgraph group_verl_training["Training runtime"]
  node_trainer_entry["PPO training entry<br/>[main_ppo.py]"]
  node_ppo_loop["PPO training loop<br/>[ray_trainer.py]"]
  node_agent_loops["Agent loops"]
  node_reward_loops["Reward loops"]
  node_workers["Training workers"]
  node_rollouts["Inference rollouts"]
  node_tooling["Tools and interactions"]
end

subgraph group_execution["Distributed execution"]
  node_data_protocol["Batch protocol<br/>[protocol.py]"]
  node_dispatch["Worker dispatch<br/>[decorator.py]"]
  node_ray_control["Ray controller<br/>[base.py]"]
end

subgraph group_models["Model runtime"]
  node_engine_config["Engine configuration<br/>[engine.py]"]
  node_model_adapters["Model adapters<br/>[monkey_patch.py]"]
  node_model_merger["Checkpoint merger"]
end

subgraph group_utilities["Shared infrastructure"]
  node_checkpointing["Checkpoint management"]
  node_fsdp_checkpoint["FSDP checkpoints"]
  node_megatron_checkpoint["Megatron checkpoints"]
  node_shared_utilities["Shared utilities"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs"| node_demo
node_researcher -->|"evaluates"| node_eval
node_researcher -->|"trains"| node_trainer_entry
node_vtg_data -.->|"grounds paths"| node_reasoning
node_reasoning -.->|"informs reward"| node_temporal_reward
node_trainer_entry -.->|"starts"| node_ppo_loop
node_ppo_loop -.->|"orchestrates"| node_workers
node_ppo_loop -->|"uses batches"| node_data_protocol
node_ppo_loop -->|"uses"| node_ray_control
node_workers -->|"registers calls"| node_dispatch
node_workers -->|"configures engine"| node_engine_config
node_workers -.->|"invokes"| node_rollouts
node_eval -->|"loads settings"| node_eval_config
node_eval -->|"uses"| node_model_adapters
node_eval -.->|"generates predictions"| node_rollouts
node_agent_loops -.->|"dispatches tools"| node_tooling
node_reward_loops -.->|"scores outputs"| node_temporal_reward
node_checkpointing -->|"specializes"| node_fsdp_checkpoint
node_checkpointing -->|"specializes"| node_megatron_checkpoint
node_ppo_loop -->|"manages checkpoints"| node_checkpointing
node_model_merger -->|"converts weights"| node_megatron_checkpoint
node_dispatch -->|"splits batches"| node_data_protocol
node_dispatch -->|"dispatches workers"| node_ray_control
node_workers -->|"uses runtime helpers"| node_shared_utilities
node_engine_config -.->|"configures execution"| node_model_adapters

click node_demo "https://github.com/oceanflowlab/taro/blob/main/demo.py"
click node_vtg_data "https://github.com/oceanflowlab/taro/blob/main/src/vtg_dataset.py"
click node_reasoning "https://github.com/oceanflowlab/taro/blob/main/src/utils.py"
click node_temporal_reward "https://github.com/oceanflowlab/taro/blob/main/src/rewards.py"
click node_trainer_entry "https://github.com/oceanflowlab/taro/blob/main/verl/trainer/main_ppo.py"
click node_ppo_loop "https://github.com/oceanflowlab/taro/blob/main/verl/trainer/ppo/ray_trainer.py"
click node_eval "https://github.com/oceanflowlab/taro/blob/main/standalone_eval/evaluate_vtg.py"
click node_eval_config "https://github.com/oceanflowlab/taro/blob/main/standalone_eval/dataset_config.py"
click node_agent_loops "https://github.com/oceanflowlab/taro/tree/main/verl/experimental/agent_loop"
click node_reward_loops "https://github.com/oceanflowlab/taro/tree/main/verl/experimental/reward_loop"
click node_workers "https://github.com/oceanflowlab/taro/tree/main/verl/workers"
click node_rollouts "https://github.com/oceanflowlab/taro/tree/main/verl/workers/rollout"
click node_data_protocol "https://github.com/oceanflowlab/taro/blob/main/verl/protocol.py"
click node_dispatch "https://github.com/oceanflowlab/taro/blob/main/verl/single_controller/base/decorator.py"
click node_ray_control "https://github.com/oceanflowlab/taro/blob/main/verl/single_controller/ray/base.py"
click node_engine_config "https://github.com/oceanflowlab/taro/blob/main/verl/workers/config/engine.py"
click node_model_adapters "https://github.com/oceanflowlab/taro/blob/main/verl/models/transformers/monkey_patch.py"
click node_model_merger "https://github.com/oceanflowlab/taro/blob/main/verl/model_merger/base_model_merger.py"
click node_checkpointing "https://github.com/oceanflowlab/taro/blob/main/verl/utils/checkpoint/checkpoint_manager.py"
click node_fsdp_checkpoint "https://github.com/oceanflowlab/taro/blob/main/verl/utils/checkpoint/fsdp_checkpoint_manager.py"
click node_megatron_checkpoint "https://github.com/oceanflowlab/taro/blob/main/verl/utils/checkpoint/megatron_checkpoint_manager.py"
click node_shared_utilities "https://github.com/oceanflowlab/taro/tree/main/verl/utils"
click node_tooling "https://github.com/oceanflowlab/taro/tree/main/verl/tools"

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_demo,node_vtg_data,node_reasoning,node_temporal_reward,node_eval,node_eval_config toneBlue
class node_trainer_entry,node_ppo_loop,node_agent_loops,node_reward_loops,node_workers,node_rollouts,node_tooling toneAmber
class node_data_protocol,node_dispatch,node_ray_control toneMint
class node_engine_config,node_model_adapters,node_model_merger toneRose
class node_checkpointing,node_fsdp_checkpoint,node_megatron_checkpoint,node_shared_utilities,node_researcher toneIndigo
```

## Components

### TaRO application

- [Interactive demo](https://github.com/oceanflowlab/taro/blob/main/demo.py): `demo.py`
- [VTG data](https://github.com/oceanflowlab/taro/blob/main/src/vtg_dataset.py): `src/vtg_dataset.py`
- [Constructed reasoning](https://github.com/oceanflowlab/taro/blob/main/src/utils.py): `src/utils.py`
- [Temporal reward](https://github.com/oceanflowlab/taro/blob/main/src/rewards.py): `src/rewards.py`
- [VTG evaluation](https://github.com/oceanflowlab/taro/blob/main/standalone_eval/evaluate_vtg.py): `standalone_eval/evaluate_vtg.py`
- [Dataset configuration](https://github.com/oceanflowlab/taro/blob/main/standalone_eval/dataset_config.py): `standalone_eval/dataset_config.py`

### Training runtime

- [PPO training entry](https://github.com/oceanflowlab/taro/blob/main/verl/trainer/main_ppo.py): `verl/trainer/main_ppo.py`
- [PPO training loop](https://github.com/oceanflowlab/taro/blob/main/verl/trainer/ppo/ray_trainer.py): `verl/trainer/ppo/ray_trainer.py`
- [Agent loops](https://github.com/oceanflowlab/taro/tree/main/verl/experimental/agent_loop): `verl/experimental/agent_loop`
- [Reward loops](https://github.com/oceanflowlab/taro/tree/main/verl/experimental/reward_loop): `verl/experimental/reward_loop`
- [Training workers](https://github.com/oceanflowlab/taro/tree/main/verl/workers): `verl/workers`
- [Inference rollouts](https://github.com/oceanflowlab/taro/tree/main/verl/workers/rollout): `verl/workers/rollout`
- [Tools and interactions](https://github.com/oceanflowlab/taro/tree/main/verl/tools): `verl/tools`

### Distributed execution

- [Batch protocol](https://github.com/oceanflowlab/taro/blob/main/verl/protocol.py): `verl/protocol.py`
- [Worker dispatch](https://github.com/oceanflowlab/taro/blob/main/verl/single_controller/base/decorator.py): `verl/single_controller/base/decorator.py`
- [Ray controller](https://github.com/oceanflowlab/taro/blob/main/verl/single_controller/ray/base.py): `verl/single_controller/ray/base.py`

### Model runtime

- [Engine configuration](https://github.com/oceanflowlab/taro/blob/main/verl/workers/config/engine.py): `verl/workers/config/engine.py`
- [Model adapters](https://github.com/oceanflowlab/taro/blob/main/verl/models/transformers/monkey_patch.py): `verl/models/transformers/monkey_patch.py`
- [Checkpoint merger](https://github.com/oceanflowlab/taro/blob/main/verl/model_merger/base_model_merger.py): `verl/model_merger/base_model_merger.py`

### Shared infrastructure

- [Checkpoint management](https://github.com/oceanflowlab/taro/blob/main/verl/utils/checkpoint/checkpoint_manager.py): `verl/utils/checkpoint/checkpoint_manager.py`
- [FSDP checkpoints](https://github.com/oceanflowlab/taro/blob/main/verl/utils/checkpoint/fsdp_checkpoint_manager.py): `verl/utils/checkpoint/fsdp_checkpoint_manager.py`
- [Megatron checkpoints](https://github.com/oceanflowlab/taro/blob/main/verl/utils/checkpoint/megatron_checkpoint_manager.py): `verl/utils/checkpoint/megatron_checkpoint_manager.py`
- [Shared utilities](https://github.com/oceanflowlab/taro/tree/main/verl/utils): `verl/utils`

### Other components

- **Researcher**

## Connections

- Researcher → Interactive demo: runs
- Researcher → VTG evaluation: evaluates
- Researcher → PPO training entry: trains
- VTG data → Constructed reasoning: grounds paths
- Constructed reasoning → Temporal reward: informs reward
- PPO training entry → PPO training loop: starts (evidence: `verl/trainer/ppo/ray_trainer.py`)
- PPO training loop → Training workers: orchestrates (evidence: `verl/trainer/ppo/ray_trainer.py`)
- PPO training loop → Batch protocol: uses batches (evidence: `verl/trainer/ppo/ray_trainer.py`)
- PPO training loop → Ray controller: uses (evidence: `verl/trainer/ppo/ray_trainer.py`)
- Training workers → Worker dispatch: registers calls (evidence: `verl/workers/engine_workers.py`)
- Training workers → Engine configuration: configures engine (evidence: `verl/workers/engine_workers.py`)
- Training workers → Inference rollouts: invokes (evidence: `verl/workers/engine_workers.py`)
- VTG evaluation → Dataset configuration: loads settings (evidence: `standalone_eval/evaluate_vtg.py`)
- VTG evaluation → Model adapters: uses (evidence: `standalone_eval/evaluate_vtg.py`)
- VTG evaluation → Inference rollouts: generates predictions
- Agent loops → Tools and interactions: dispatches tools
- Reward loops → Temporal reward: scores outputs
- Checkpoint management → FSDP checkpoints: specializes (evidence: `verl/utils/checkpoint/fsdp_checkpoint_manager.py`)
- Checkpoint management → Megatron checkpoints: specializes (evidence: `verl/utils/checkpoint/megatron_checkpoint_manager.py`)
- PPO training loop → Checkpoint management: manages checkpoints (evidence: `verl/trainer/ppo/ray_trainer.py`)
- Checkpoint merger → Megatron checkpoints: converts weights
- Worker dispatch → Batch protocol: splits batches (evidence: `verl/single_controller/base/decorator.py`)
- Worker dispatch → Ray controller: dispatches workers (evidence: `verl/single_controller/base/decorator.py`)
- Training workers → Shared utilities: uses runtime helpers (evidence: `verl/workers/engine_workers.py`)
- Engine configuration → Model adapters: configures execution