# trademaster-ntu/finworld architecture

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

- Interactive diagram: https://gitdiagram.com/trademaster-ntu/finworld
- Repository: https://github.com/trademaster-ntu/finworld

## Overview

FinWorld is an end-to-end financial AI research platform. A typical workflow acquires market data, preprocesses it into task datasets, trains forecasting or trading/portfolio models, and evaluates their outputs. The repository also includes LLM agents for financial research and a vendored VERL stack for distributed LLM/RL training. README statements support the broad task flow and capabilities; source excerpts clarify selected agent, model, registry, logging, and VERL internals. Several implementation paths are unsampled, so links for those branches rely on the README rather than inspected call chains.

Main entry points: [`finworld/registry.py`](https://github.com/trademaster-ntu/finworld/blob/main/finworld/registry.py) (Component registry), [`finworld/models`](https://github.com/trademaster-ntu/finworld/tree/main/finworld/models) (Financial models), [`finworld/base/async_multistep_agent.py`](https://github.com/trademaster-ntu/finworld/blob/main/finworld/base/async_multistep_agent.py) (Multistep agent runtime), [`finworld/trainer`](https://github.com/trademaster-ntu/finworld/tree/main/finworld/trainer) (Task trainers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data pipeline"]
  node_downloaders["Market downloaders"]
  node_processors["Data processors"]
  node_datasets["Task datasets"]
  node_registry["Component registry<br/>[registry.py]"]
end

subgraph group_models["Models and tasks"]
  node_timeembed["Time embeddings<br/>[time.py]"]
  node_modelzoo["Financial models"]
  node_environment["Trading environments"]
  node_forecast["Forecasting tasks"]
  node_trade["Trading tasks"]
  node_portfolio["Portfolio tasks"]
end

subgraph group_agents["Agents and tools"]
  node_agent["Financial agents"]
  node_agentcore["Multistep agent runtime"]
  node_llm["LLM providers<br/>[base.py]"]
  node_research["Deep research<br/>[deep_researcher.py]"]
  node_tools["Agent tools<br/>[tools.py]"]
  node_executor["Python execution"]
  node_memory["Agent memory<br/>[memory.py]"]
end

subgraph group_runtime["Training and evaluation"]
  node_evaluation["Evaluation metrics"]
  node_visualization["Reports and plots"]
  node_trainer["Task trainers"]
  node_verlengine["Distributed engines"]
  node_verlcheckpoint["Training checkpoints"]
  node_logging["Experiment logging<br/>[logger.py]"]
end

node_user(("Researcher"))

node_user -->|"select data"| node_downloaders
node_downloaders -->|"acquire for"| node_processors
node_processors -->|"prepare data"| node_datasets
node_datasets -->|"train from"| node_trainer
node_registry -->|"registers"| node_downloaders
node_registry -->|"registers"| node_processors
node_registry -->|"registers"| node_datasets
node_registry -->|"registers"| node_environment
node_registry -->|"registers"| node_modelzoo
node_datasets -.->|"provides time data"| node_timeembed
node_timeembed -.->|"embeds features"| node_modelzoo
node_modelzoo -->|"supports forecasting"| node_forecast
node_modelzoo -->|"supports trading"| node_trade
node_modelzoo -->|"supports portfolios"| node_portfolio
node_environment -->|"encapsulates task"| node_trade
node_environment -->|"encapsulates task"| node_portfolio
node_trainer -->|"evaluates results"| node_evaluation
node_evaluation -->|"presents metrics"| node_visualization
node_user -.->|"request research"| node_agent
node_agent -.->|"runs through"| node_agentcore
node_agentcore -->|"uses models"| node_llm
node_agentcore -->|"invokes tools"| node_tools
node_agentcore -->|"uses memory"| node_memory
node_research -->|"queries model"| node_llm
node_research -.->|"searches web"| node_tools
node_tools -->|"dispatches code"| node_executor
node_trainer -.->|"distributed training"| node_verlengine
node_verlengine -.->|"saves state"| node_verlcheckpoint
node_trainer -->|"tracks runs"| node_logging

click node_downloaders "https://github.com/trademaster-ntu/finworld/tree/main/finworld/downloader"
click node_processors "https://github.com/trademaster-ntu/finworld/tree/main/finworld/processor"
click node_datasets "https://github.com/trademaster-ntu/finworld/tree/main/finworld/data"
click node_registry "https://github.com/trademaster-ntu/finworld/blob/main/finworld/registry.py"
click node_timeembed "https://github.com/trademaster-ntu/finworld/blob/main/finworld/models/embed/time.py"
click node_modelzoo "https://github.com/trademaster-ntu/finworld/tree/main/finworld/models"
click node_environment "https://github.com/trademaster-ntu/finworld/tree/main/finworld/environment"
click node_forecast "https://github.com/trademaster-ntu/finworld/tree/main/finworld/trainer/time"
click node_trade "https://github.com/trademaster-ntu/finworld/tree/main/finworld/trainer"
click node_portfolio "https://github.com/trademaster-ntu/finworld/tree/main/finworld/trainer"
click node_evaluation "https://github.com/trademaster-ntu/finworld/tree/main/finworld/evaluator"
click node_visualization "https://github.com/trademaster-ntu/finworld/tree/main/finworld/plot"
click node_agent "https://github.com/trademaster-ntu/finworld/tree/main/finworld/agent/agent"
click node_agentcore "https://github.com/trademaster-ntu/finworld/blob/main/finworld/base/async_multistep_agent.py"
click node_llm "https://github.com/trademaster-ntu/finworld/blob/main/finworld/models/llm_provider/base.py"
click node_research "https://github.com/trademaster-ntu/finworld/blob/main/finworld/tools/deep_researcher.py"
click node_tools "https://github.com/trademaster-ntu/finworld/blob/main/finworld/tools/tools.py"
click node_executor "https://github.com/trademaster-ntu/finworld/blob/main/finworld/tools/executor/local_python_executor.py"
click node_memory "https://github.com/trademaster-ntu/finworld/blob/main/finworld/memory/memory.py"
click node_trainer "https://github.com/trademaster-ntu/finworld/tree/main/finworld/trainer"
click node_verlengine "https://github.com/trademaster-ntu/finworld/tree/main/libs/verl/verl/workers/engine"
click node_verlcheckpoint "https://github.com/trademaster-ntu/finworld/blob/main/libs/verl/verl/utils/checkpoint/checkpoint_manager.py"
click node_logging "https://github.com/trademaster-ntu/finworld/blob/main/finworld/log/logger.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_downloaders,node_processors,node_datasets,node_registry toneBlue
class node_timeembed,node_modelzoo,node_environment,node_forecast,node_trade,node_portfolio toneAmber
class node_agent,node_agentcore,node_llm,node_research,node_tools,node_executor,node_memory toneMint
class node_evaluation,node_visualization,node_trainer,node_verlengine,node_verlcheckpoint,node_logging toneRose
class node_user toneIndigo
```

## Components

### Data pipeline

- [Market downloaders](https://github.com/trademaster-ntu/finworld/tree/main/finworld/downloader): `finworld/downloader`
- [Data processors](https://github.com/trademaster-ntu/finworld/tree/main/finworld/processor): `finworld/processor`
- [Task datasets](https://github.com/trademaster-ntu/finworld/tree/main/finworld/data): `finworld/data`
- [Component registry](https://github.com/trademaster-ntu/finworld/blob/main/finworld/registry.py): `finworld/registry.py`

### Models and tasks

- [Time embeddings](https://github.com/trademaster-ntu/finworld/blob/main/finworld/models/embed/time.py): `finworld/models/embed/time.py`
- [Financial models](https://github.com/trademaster-ntu/finworld/tree/main/finworld/models): `finworld/models`
- [Trading environments](https://github.com/trademaster-ntu/finworld/tree/main/finworld/environment): `finworld/environment`
- [Forecasting tasks](https://github.com/trademaster-ntu/finworld/tree/main/finworld/trainer/time): `finworld/trainer/time`
- [Trading tasks](https://github.com/trademaster-ntu/finworld/tree/main/finworld/trainer): `finworld/trainer`
- [Portfolio tasks](https://github.com/trademaster-ntu/finworld/tree/main/finworld/trainer): `finworld/trainer`

### Agents and tools

- [Financial agents](https://github.com/trademaster-ntu/finworld/tree/main/finworld/agent/agent): `finworld/agent/agent`
- [Multistep agent runtime](https://github.com/trademaster-ntu/finworld/blob/main/finworld/base/async_multistep_agent.py): `finworld/base/async_multistep_agent.py`
- [LLM providers](https://github.com/trademaster-ntu/finworld/blob/main/finworld/models/llm_provider/base.py): `finworld/models/llm_provider/base.py`
- [Deep research](https://github.com/trademaster-ntu/finworld/blob/main/finworld/tools/deep_researcher.py): `finworld/tools/deep_researcher.py`
- [Agent tools](https://github.com/trademaster-ntu/finworld/blob/main/finworld/tools/tools.py): `finworld/tools/tools.py`
- [Python execution](https://github.com/trademaster-ntu/finworld/blob/main/finworld/tools/executor/local_python_executor.py): `finworld/tools/executor/local_python_executor.py`
- [Agent memory](https://github.com/trademaster-ntu/finworld/blob/main/finworld/memory/memory.py): `finworld/memory/memory.py`

### Training and evaluation

- [Evaluation metrics](https://github.com/trademaster-ntu/finworld/tree/main/finworld/evaluator): `finworld/evaluator`
- [Reports and plots](https://github.com/trademaster-ntu/finworld/tree/main/finworld/plot): `finworld/plot`
- [Task trainers](https://github.com/trademaster-ntu/finworld/tree/main/finworld/trainer): `finworld/trainer`
- [Distributed engines](https://github.com/trademaster-ntu/finworld/tree/main/libs/verl/verl/workers/engine): `libs/verl/verl/workers/engine`
- [Training checkpoints](https://github.com/trademaster-ntu/finworld/blob/main/libs/verl/verl/utils/checkpoint/checkpoint_manager.py): `libs/verl/verl/utils/checkpoint/checkpoint_manager.py`
- [Experiment logging](https://github.com/trademaster-ntu/finworld/blob/main/finworld/log/logger.py): `finworld/log/logger.py`

### Other components

- **Researcher**

## Connections

- Researcher → Market downloaders: select data (evidence: `README.md`)
- Market downloaders → Data processors: acquire for (evidence: `README.md`)
- Data processors → Task datasets: prepare data (evidence: `README.md`)
- Task datasets → Task trainers: train from (evidence: `README.md`)
- Component registry → Market downloaders: registers (evidence: `finworld/registry.py`)
- Component registry → Data processors: registers (evidence: `finworld/registry.py`)
- Component registry → Task datasets: registers (evidence: `finworld/registry.py`)
- Component registry → Trading environments: registers (evidence: `finworld/registry.py`)
- Component registry → Financial models: registers (evidence: `finworld/registry.py`)
- Task datasets → Time embeddings: provides time data (evidence: `README.md`)
- Time embeddings → Financial models: embeds features (evidence: `README.md`)
- Financial models → Forecasting tasks: supports forecasting (evidence: `README.md`)
- Financial models → Trading tasks: supports trading (evidence: `README.md`)
- Financial models → Portfolio tasks: supports portfolios (evidence: `README.md`)
- Trading environments → Trading tasks: encapsulates task (evidence: `README.md`)
- Trading environments → Portfolio tasks: encapsulates task (evidence: `README.md`)
- Task trainers → Evaluation metrics: evaluates results (evidence: `README.md`)
- Evaluation metrics → Reports and plots: presents metrics (evidence: `README.md`)
- Researcher → Financial agents: request research (evidence: `README.md`)
- Financial agents → Multistep agent runtime: runs through (evidence: `finworld/agent/agent/deep_researcher_agent/deep_researcher_agent.py`)
- Multistep agent runtime → LLM providers: uses models (evidence: `finworld/base/async_multistep_agent.py`)
- Multistep agent runtime → Agent tools: invokes tools (evidence: `finworld/base/async_multistep_agent.py`)
- Multistep agent runtime → Agent memory: uses memory (evidence: `finworld/base/async_multistep_agent.py`)
- Deep research → LLM providers: queries model (evidence: `finworld/tools/deep_researcher.py`)
- Deep research → Agent tools: searches web (evidence: `README.md`)
- Agent tools → Python execution: dispatches code
- Task trainers → Distributed engines: distributed training (evidence: `README.md`)
- Distributed engines → Training checkpoints: saves state (evidence: `libs/verl/verl/workers/engine/fsdp/engine_impl.py`)
- Task trainers → Experiment logging: tracks runs (evidence: `README.md`)
