# caraj7/t2i-r1 architecture

> Architecture diagram of the GitHub repository caraj7/t2i-r1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/caraj7/t2i-r1
- Repository: https://github.com/caraj7/t2i-r1

## Overview

##### Project Type and Purpose
- This is a research‐oriented, full‐stack machine‐learning pipeline for text‐to‐image generation (T2I) with reinforcement learning (RL) and Chain‐of‐Thought (CoT) reasoning.
- The core novelty is the BiCoT‐GRPO trainer that optimizes both semantic‐level and token‐level CoT during T2I model training.

##### High‐Level Architecture Components
a. Data Layer
- data/geneval_and_t2i_data_final.json: Prompt examples and ground truths
- data/prompt/reasoning_prompt.txt: Template for semantic‐level CoT
b. Configuration & Orchestration
- src/t2i-r1/configs/*.json: Zero3 and offload settings
- src/scripts/run_grpo.sh: Entry point for launching the BiCoT‐GRPO training
c. Semantic‐level CoT Module (“janus”)
- src/t2i-r1/src/janus/janusflow/models: CLIP encoder, VLM modeling, image processing
- Responsible for planning global image structure (object layout, attributes)
d. Token‐level CoT Generator (“open_r1”)
- src/t2i-r1/src/open_r1/trainer/grpo_trainer.py: GRPO algorithm implementation
- src/t2i-r1/src/open_r1/grpo.py: Core RL loop coordinating token‐by‐token generation
e. Reward Model Suite
- src/t2i-r1/src/utils/GroundingDINO: Object detection reward
- src/t2i-r1/src/utils/LLaVA-NeXT: ORM reward via LLaVA
- src/t2i-r1/src/utils/reward_*.py: wrappers for HPS, GIT, ORM, custom rewards
- These modules produce scalar rewards used by the GRPO trainer
f. Inference Module
- src/t2i-r1/src/infer/reason_inference.py: Runs semantic CoT + generator for testing or demo
g. External Dependencies & Environments
- Python, PyTorch, TorchVision, Transformers, TRL, Conda environment
- Dockerfile/ environment.yaml under GroundingDINO (for reproducibility)

##### Relationships and Data Flow
- User/data prompts → Semantic‐level CoT “janusflow” → text reasoning output
- Text reasoning + prompt → Token‐level CoT generator (open_r1) → image tokens
- Generated images → Reward Model Suite (GroundingDINO, LLaVA, HPS, GIT) → scalar rewards
- GRPO trainer ingests rewards + model gradients → updates both CoT policy and image generator
- Config files parameterize the flow (Zero3 offloading, checkpoint paths)
- Inference script uses the trained checkpoint for one‐shot generation

##### Architectural Patterns & Design Principles
- Modular separation of concerns: reasoning vs generation vs reward computation
- Pluggable reward functions: external repos are vendored under src/utils
- Configuration‐driven: high reuse of scripts and JSON configs for scaling and ablation
- Ensemble reward composition within a single RL training loop (BiCoT‐GRPO)

##### Capturing Essential Elements
- BiCoT‐GRPO feedback loop: CoT policies and generator policies updated by composite rewards
- Interaction between semantic and token CoT levels within the trainer
- External repos as sub‐components of the Reward Suite, noting they are pip‐installed from vendored code

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Data Layer"
    DL1["geneval_and_t2i_data_final.json"]:::data
    DL2["reasoning_prompt.txt"]:::data
  end

  subgraph "Configuration & Orchestration"
    CFG1["zero3.json"]:::config
    CFG2["zero3_offload.json"]:::config
    SCRIPT["run_grpo.sh"]:::config
  end

  subgraph "Semantic-level CoT (janusflow)"
    Clip["clip_encoder.py"]:::core
    ImgProc["image_processing_vlm.py"]:::core
    Model["modeling_vlm.py"]:::core
    ProcVLM["processing_vlm.py"]:::core
    Siglip["siglip_vit.py"]:::core
    UVit["uvit.py"]:::core
    JANUS["janusflow"]:::core
    Clip --> JANUS
    ImgProc --> JANUS
    Model --> JANUS
    ProcVLM --> JANUS
    Siglip --> JANUS
    UVit --> JANUS
  end

  subgraph "Token-level CoT (open_r1)"
    GRPOCore["grpo.py"]:::core
    TrainerFile["grpo_trainer.py"]:::core
    OPENR1["open_r1"]:::core
    GRPOCore --> OPENR1
    TrainerFile --> OPENR1
  end

  subgraph "BiCoT-GRPO Trainer"
    TRAINER["GRPO Trainer"]:::core
  end

  subgraph "Reward Model Suite"
    GDINO["GroundingDINO"]:::reward
    LLAVA["LLaVA-NeXT"]:::reward
    RG["reward_gdino.py"]:::reward
    RGIT["reward_git.py"]:::reward
    RHPS["reward_hps.py"]:::reward
    RORM["reward_orm.py"]:::reward
  end

  subgraph "Inference Module"
    INFER["reason_inference.py"]:::core
  end

  %% Data & Config flows
  DL1 -->|"prompt examples"| JANUS
  DL2 -->|"reasoning template"| JANUS
  CFG1 -.-> TRAINER
  CFG2 -.-> TRAINER
  SCRIPT -.-> TRAINER

  %% Core pipeline
  JANUS -->|"reasoning output"| OPENR1
  OPENR1 -->|"image tokens"| TRAINER
  TRAINER -->|"calls reward models"| GDINO
  TRAINER -->|"calls reward models"| LLAVA
  TRAINER -->|"calls reward models"| RG
  TRAINER -->|"calls reward models"| RGIT
  TRAINER -->|"calls reward models"| RHPS
  TRAINER -->|"calls reward models"| RORM

  %% Feedback loop
  GDINO -->|"reward signal"| TRAINER
  LLAVA -->|"reward signal"| TRAINER
  RG -->|"reward signal"| TRAINER
  RGIT -->|"reward signal"| TRAINER
  RHPS -->|"reward signal"| TRAINER
  RORM -->|"reward signal"| TRAINER

  TRAINER -->|"gradient update"| JANUS
  TRAINER -->|"gradient update"| OPENR1

  %% Inference
  JANUS -->|"semantic CoT"| INFER
  OPENR1 -->|"generator"| INFER

  %% Click Events
  click DL1 "https://github.com/caraj7/t2i-r1/blob/main/data/geneval_and_t2i_data_final.json"
  click DL2 "https://github.com/caraj7/t2i-r1/blob/main/data/prompt/reasoning_prompt.txt"
  click CFG1 "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/configs/zero3.json"
  click CFG2 "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/configs/zero3_offload.json"
  click SCRIPT "https://github.com/caraj7/t2i-r1/blob/main/src/scripts/run_grpo.sh"
  click Clip "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/janus/janusflow/models/clip_encoder.py"
  click ImgProc "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/janus/janusflow/models/image_processing_vlm.py"
  click Model "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/janus/janusflow/models/modeling_vlm.py"
  click ProcVLM "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/janus/janusflow/models/processing_vlm.py"
  click Siglip "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/janus/janusflow/models/siglip_vit.py"
  click UVit "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/janus/janusflow/models/uvit.py"
  click GRPOCore "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/open_r1/grpo.py"
  click TrainerFile "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/open_r1/trainer/grpo_trainer.py"
  click GDINO "https://github.com/caraj7/t2i-r1/tree/main/src/t2i-r1/src/utils/GroundingDINO/"
  click LLAVA "https://github.com/caraj7/t2i-r1/tree/main/src/t2i-r1/src/utils/LLaVA-NeXT/"
  click RG "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/utils/reward_gdino.py"
  click RGIT "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/utils/reward_git.py"
  click RHPS "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/utils/reward_hps.py"
  click RORM "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/utils/reward_orm.py"
  click INFER "https://github.com/caraj7/t2i-r1/blob/main/src/t2i-r1/src/infer/reason_inference.py"

  %% Styles
  classDef data fill:#ddd,stroke:#333;
  classDef core fill:#ccf,stroke:#333;
  classDef reward fill:#cfc,stroke:#333;
  classDef config fill:#fcf,stroke:#333;
```
