# ml-gsai/refusion architecture

> Architecture diagram of the GitHub repository ml-gsai/refusion, 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/ml-gsai/refusion
- Repository: https://github.com/ml-gsai/refusion

## Overview

ReFusion is a masked diffusion language model with training, parallel autoregressive-style inference, and benchmark evaluation. The inference script loads the Qwen3 model and performs block/slot generation; the evaluation entry point invokes lm-evaluation-harness, whose task definitions produce requests for registered model backends and whose evaluator aggregates and reports results. The graph also retains the harness’s task, filtering, and logging capabilities. Some source is unsampled, so unverified relationships are omitted rather than inferred.

Main entry points: [`lm_eval/evaluator.py`](https://github.com/ml-gsai/refusion/blob/main/lm_eval/evaluator.py) (Evaluation Orchestrator), [`qwen3/modeling_qwen3_refusion.py`](https://github.com/ml-gsai/refusion/blob/main/qwen3/modeling_qwen3_refusion.py) (ReFusion Model), [`generate.py`](https://github.com/ml-gsai/refusion/blob/main/generate.py) (Parallel Generation), [`lm_eval/__main__.py`](https://github.com/ml-gsai/refusion/blob/main/lm_eval/__main__.py) (Harness CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_refusion["ReFusion Model"]
  node_config["Qwen3 Configuration"]
  node_model["ReFusion Model"]
  node_cache_utils["Diffusion Cache"]
end

subgraph group_run["Training and Inference"]
  node_train["Model Training<br/>[train.py]"]
  node_generate["Parallel Generation<br/>[generate.py]"]
end

subgraph group_harness["Evaluation Harness"]
  node_eval_entry["Evaluation Entry<br/>[eval.py]"]
  node_cli["Harness CLI<br/>[__main__.py]"]
  node_evaluator["Evaluation Orchestrator<br/>[evaluator.py]"]
  node_model_api["Model Interface<br/>[model.py]"]
  node_registry["Component Registry<br/>[registry.py]"]
  node_backend["vLLM Backend<br/>[vllm_causallms.py]"]
  node_request_cache[("Request Cache<br/>[cache.py]")]
end

subgraph group_evaldata["Tasks and Results"]
  node_tasks["Task Catalog<br/>[__init__.py]"]
  node_task_runtime["Task Runtime<br/>[task.py]"]
  node_instances["Evaluation Requests<br/>[instance.py]"]
  node_filters["Response Filters<br/>[extraction.py]"]
  node_metrics["Metrics<br/>[metrics.py]"]
  node_reporting["Result Reporting"]
end

node_user(("Engineer"))
node_train_data["Training Data"]

node_user -->|"trains model"| node_train
node_train_data -.->|"provides examples"| node_train
node_user -->|"runs inference"| node_generate
node_generate -->|"loads and runs"| node_model
node_generate -.->|"uses cache"| node_cache_utils
node_model -->|"uses configuration"| node_config
node_model -->|"uses cache helpers"| node_cache_utils
node_user -->|"runs evaluation"| node_eval_entry
node_eval_entry -->|"invokes"| node_cli
node_cli -->|"runs evaluation"| node_evaluator
node_cli -->|"loads tasks"| node_tasks
node_evaluator -->|"loads task definitions"| node_tasks
node_tasks -->|"constructs tasks"| node_task_runtime
node_task_runtime -->|"builds requests"| node_instances
node_evaluator -.->|"processes requests"| node_instances
node_evaluator -->|"selects model"| node_registry
node_registry -->|"registers models"| node_model_api
node_evaluator -->|"runs model"| node_model_api
node_backend -.->|"implements interface"| node_model_api
node_evaluator -->|"uses request cache"| node_request_cache
node_evaluator -.->|"applies filters"| node_filters
node_evaluator -->|"aggregates metrics"| node_metrics
node_evaluator -.->|"logs results"| node_reporting

click node_train "https://github.com/ml-gsai/refusion/blob/main/train.py"
click node_generate "https://github.com/ml-gsai/refusion/blob/main/generate.py"
click node_config "https://github.com/ml-gsai/refusion/blob/main/qwen3/configuration_qwen3.py"
click node_model "https://github.com/ml-gsai/refusion/blob/main/qwen3/modeling_qwen3_refusion.py"
click node_cache_utils "https://github.com/ml-gsai/refusion/blob/main/qwen3/diffusion_cache_utils.py"
click node_eval_entry "https://github.com/ml-gsai/refusion/blob/main/eval.py"
click node_cli "https://github.com/ml-gsai/refusion/blob/main/lm_eval/__main__.py"
click node_evaluator "https://github.com/ml-gsai/refusion/blob/main/lm_eval/evaluator.py"
click node_tasks "https://github.com/ml-gsai/refusion/blob/main/lm_eval/tasks/__init__.py"
click node_task_runtime "https://github.com/ml-gsai/refusion/blob/main/lm_eval/api/task.py"
click node_instances "https://github.com/ml-gsai/refusion/blob/main/lm_eval/api/instance.py"
click node_model_api "https://github.com/ml-gsai/refusion/blob/main/lm_eval/api/model.py"
click node_registry "https://github.com/ml-gsai/refusion/blob/main/lm_eval/api/registry.py"
click node_backend "https://github.com/ml-gsai/refusion/blob/main/lm_eval/models/vllm_causallms.py"
click node_filters "https://github.com/ml-gsai/refusion/blob/main/lm_eval/filters/extraction.py"
click node_metrics "https://github.com/ml-gsai/refusion/blob/main/lm_eval/api/metrics.py"
click node_reporting "https://github.com/ml-gsai/refusion/blob/main/lm_eval/loggers/evaluation_tracker.py"
click node_request_cache "https://github.com/ml-gsai/refusion/blob/main/lm_eval/caching/cache.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_config,node_model,node_cache_utils toneBlue
class node_train,node_generate toneAmber
class node_eval_entry,node_cli,node_evaluator,node_model_api,node_registry,node_backend,node_request_cache toneMint
class node_tasks,node_task_runtime,node_instances,node_filters,node_metrics,node_reporting toneRose
class node_user,node_train_data toneIndigo
```

## Components

### ReFusion Model

- [Qwen3 Configuration](https://github.com/ml-gsai/refusion/blob/main/qwen3/configuration_qwen3.py): `qwen3/configuration_qwen3.py`
- [ReFusion Model](https://github.com/ml-gsai/refusion/blob/main/qwen3/modeling_qwen3_refusion.py): `qwen3/modeling_qwen3_refusion.py`
- [Diffusion Cache](https://github.com/ml-gsai/refusion/blob/main/qwen3/diffusion_cache_utils.py): `qwen3/diffusion_cache_utils.py`

### Training and Inference

- [Model Training](https://github.com/ml-gsai/refusion/blob/main/train.py): `train.py`
- [Parallel Generation](https://github.com/ml-gsai/refusion/blob/main/generate.py): `generate.py`

### Evaluation Harness

- [Evaluation Entry](https://github.com/ml-gsai/refusion/blob/main/eval.py): `eval.py`
- [Harness CLI](https://github.com/ml-gsai/refusion/blob/main/lm_eval/__main__.py): `lm_eval/__main__.py`
- [Evaluation Orchestrator](https://github.com/ml-gsai/refusion/blob/main/lm_eval/evaluator.py): `lm_eval/evaluator.py`
- [Model Interface](https://github.com/ml-gsai/refusion/blob/main/lm_eval/api/model.py): `lm_eval/api/model.py`
- [Component Registry](https://github.com/ml-gsai/refusion/blob/main/lm_eval/api/registry.py): `lm_eval/api/registry.py`
- [vLLM Backend](https://github.com/ml-gsai/refusion/blob/main/lm_eval/models/vllm_causallms.py): `lm_eval/models/vllm_causallms.py`
- [Request Cache](https://github.com/ml-gsai/refusion/blob/main/lm_eval/caching/cache.py): `lm_eval/caching/cache.py`

### Tasks and Results

- [Task Catalog](https://github.com/ml-gsai/refusion/blob/main/lm_eval/tasks/__init__.py): `lm_eval/tasks/__init__.py`
- [Task Runtime](https://github.com/ml-gsai/refusion/blob/main/lm_eval/api/task.py): `lm_eval/api/task.py`
- [Evaluation Requests](https://github.com/ml-gsai/refusion/blob/main/lm_eval/api/instance.py): `lm_eval/api/instance.py`
- [Response Filters](https://github.com/ml-gsai/refusion/blob/main/lm_eval/filters/extraction.py): `lm_eval/filters/extraction.py`
- [Metrics](https://github.com/ml-gsai/refusion/blob/main/lm_eval/api/metrics.py): `lm_eval/api/metrics.py`
- [Result Reporting](https://github.com/ml-gsai/refusion/blob/main/lm_eval/loggers/evaluation_tracker.py): `lm_eval/loggers/evaluation_tracker.py`

### Other components

- **Engineer**
- **Training Data**

## Connections

- Engineer → Model Training: trains model
- Training Data → Model Training: provides examples
- Engineer → Parallel Generation: runs inference
- Parallel Generation → ReFusion Model: loads and runs (evidence: `generate.py`)
- Parallel Generation → Diffusion Cache: uses cache (evidence: `generate.py`)
- ReFusion Model → Qwen3 Configuration: uses configuration (evidence: `qwen3/modeling_qwen3_refusion.py`)
- ReFusion Model → Diffusion Cache: uses cache helpers (evidence: `qwen3/modeling_qwen3_refusion.py`)
- Engineer → Evaluation Entry: runs evaluation
- Evaluation Entry → Harness CLI: invokes (evidence: `eval.py`)
- Harness CLI → Evaluation Orchestrator: runs evaluation (evidence: `lm_eval/__main__.py`)
- Harness CLI → Task Catalog: loads tasks (evidence: `lm_eval/__main__.py`)
- Evaluation Orchestrator → Task Catalog: loads task definitions (evidence: `lm_eval/evaluator.py`)
- Task Catalog → Task Runtime: constructs tasks (evidence: `lm_eval/tasks/__init__.py`)
- Task Runtime → Evaluation Requests: builds requests (evidence: `lm_eval/api/task.py`)
- Evaluation Orchestrator → Evaluation Requests: processes requests
- Evaluation Orchestrator → Component Registry: selects model (evidence: `lm_eval/evaluator.py`)
- Component Registry → Model Interface: registers models (evidence: `lm_eval/api/registry.py`)
- Evaluation Orchestrator → Model Interface: runs model (evidence: `lm_eval/evaluator.py`)
- vLLM Backend → Model Interface: implements interface (evidence: `lm_eval/models/vllm_causallms.py`)
- Evaluation Orchestrator → Request Cache: uses request cache (evidence: `lm_eval/evaluator.py`)
- Evaluation Orchestrator → Response Filters: applies filters
- Evaluation Orchestrator → Metrics: aggregates metrics (evidence: `lm_eval/evaluator.py`)
- Evaluation Orchestrator → Result Reporting: logs results
