# aiclub-uit/aicity2026-track2 architecture

> Architecture diagram of the GitHub repository aiclub-uit/aicity2026-track2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aiclub-uit/aicity2026-track2
- Repository: https://github.com/aiclub-uit/aicity2026-track2

## Overview

Team 24’s product is an AI City Challenge Track 2 reproduction pipeline: it prepares public-test inputs, trains or loads vision-language adapters, generates VQA answers and traffic-scene captions, then applies temporal decoding and caption fact corrections before writing submissions. The README documents the overall stages and optional Cosmos-based bundle retraining. Source excerpts show test preparation invoking preprocessing, context construction using WSD helpers, and Cosmos preparation reusing VQA frame-selection logic; unsampled training and pipeline details are represented only at the documented subsystem level.

Main entry points: [`code/run_qwen35_vqa.py`](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/run_qwen35_vqa.py) (VQA adapter), [`code/run_e2e.py`](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/run_e2e.py) (E2E orchestrator), [`code/preprocess_vqa.py`](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/preprocess_vqa.py) (VQA preprocessing), [`code/run_qwen35_caption.py`](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/run_qwen35_caption.py) (Caption adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_datasets["Challenge datasets"]
  node_test_layout["Test layout"]
  node_vqa_prep["VQA preprocessing<br/>[preprocess_vqa.py]"]
  node_caption_prep["Caption preprocessing"]
  node_context["Context builder<br/>[ctx_builder.py]"]
end

subgraph group_models["Adapters and inference"]
  node_vqa_model["VQA adapter<br/>[run_qwen35_vqa.py]"]
  node_caption_model["Caption adapters"]
  node_shipped_adapters["Shipped LoRA adapters"]
  node_cosmos_prep["Cosmos preparation"]
  node_cosmos["Cosmos restyling"]
  node_domain_randomization["Domain randomization<br/>[dr_prep.py]"]
end

subgraph group_reasoning["Reasoning and refinement"]
  node_wsd["Temporal decoding<br/>[wsd.py]"]
  node_fact_v2["Fact correction v2<br/>[fact_stitch.py]"]
  node_fact_v3["Fact correction v3<br/>[fact_stitch3.py]"]
  node_fact_v4["Fact correction v4<br/>[fact_stitch4.py]"]
  node_fact_v5["Fact correction v5<br/>[fact_stitch5.py]"]
end

subgraph group_delivery["Pipeline and outputs"]
  node_orchestrator["E2E orchestrator<br/>[run_e2e.py]"]
  node_submissions["Submission files"]
end

node_operator(("Reproducer"))

node_operator -->|"runs stages"| node_orchestrator
node_datasets -->|"supplies test data"| node_test_layout
node_test_layout -->|"invokes preprocessing"| node_vqa_prep
node_test_layout -->|"invokes preprocessing"| node_caption_prep
node_datasets -->|"supplies frames and annotations"| node_vqa_prep
node_datasets -->|"supplies frames and annotations"| node_caption_prep
node_vqa_prep -.->|"provides prepared evidence"| node_context
node_vqa_prep -->|"provides prediction inputs"| node_vqa_model
node_caption_prep -->|"provides prediction inputs"| node_caption_model
node_context -->|"uses question helpers"| node_wsd
node_context -.->|"supports context route"| node_vqa_model
node_shipped_adapters -->|"loads adapter"| node_vqa_model
node_shipped_adapters -->|"loads adapter"| node_caption_model
node_cosmos_prep -->|"reuses frame selection"| node_vqa_prep
node_cosmos_prep -->|"prepares restyle inputs"| node_cosmos
node_cosmos -->|"provides restyled frames"| node_domain_randomization
node_domain_randomization -->|"supports bundle training"| node_vqa_model
node_vqa_model -->|"provides probabilities"| node_wsd
node_wsd -->|"decodes answers"| node_orchestrator
node_caption_model -.->|"provides draft captions"| node_fact_v2
node_fact_v2 -.->|"refines captions"| node_fact_v3
node_fact_v3 -.->|"refines captions"| node_fact_v4
node_fact_v4 -.->|"refines captions"| node_fact_v5
node_orchestrator -->|"trains and predicts"| node_vqa_model
node_orchestrator -->|"trains and predicts"| node_caption_model
node_orchestrator -->|"writes results"| node_submissions
node_fact_v5 -->|"writes corrected output"| node_submissions

click node_datasets "https://github.com/aiclub-uit/aicity2026-track2/tree/main/data"
click node_test_layout "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/prepare_test_root.py"
click node_vqa_prep "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/preprocess_vqa.py"
click node_caption_prep "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/preprocess_caption.py"
click node_context "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/ctx_builder.py"
click node_vqa_model "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/run_qwen35_vqa.py"
click node_caption_model "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/run_qwen35_caption.py"
click node_shipped_adapters "https://github.com/aiclub-uit/aicity2026-track2/tree/main/artifacts/adapters"
click node_cosmos_prep "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/cosmos_restyle_prep.py"
click node_domain_randomization "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/dr_prep.py"
click node_wsd "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/wsd.py"
click node_fact_v2 "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/fact_stitch.py"
click node_fact_v3 "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/fact_stitch3.py"
click node_fact_v4 "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/fact_stitch4.py"
click node_fact_v5 "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/fact_stitch5.py"
click node_orchestrator "https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/run_e2e.py"
click node_submissions "https://github.com/aiclub-uit/aicity2026-track2/tree/main/submissions"

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_datasets,node_test_layout,node_vqa_prep,node_caption_prep,node_context toneBlue
class node_vqa_model,node_caption_model,node_shipped_adapters,node_cosmos_prep,node_cosmos,node_domain_randomization toneAmber
class node_wsd,node_fact_v2,node_fact_v3,node_fact_v4,node_fact_v5 toneMint
class node_orchestrator,node_submissions toneRose
class node_operator toneIndigo
```

## Components

### Data preparation

- [Challenge datasets](https://github.com/aiclub-uit/aicity2026-track2/tree/main/data): `data`
- [Test layout](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/prepare_test_root.py): `code/prepare_test_root.py`
- [VQA preprocessing](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/preprocess_vqa.py): `code/preprocess_vqa.py`
- [Caption preprocessing](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/preprocess_caption.py): `code/preprocess_caption.py`
- [Context builder](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/ctx_builder.py): `code/ctx_builder.py`

### Adapters and inference

- [VQA adapter](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/run_qwen35_vqa.py): `code/run_qwen35_vqa.py`
- [Caption adapters](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/run_qwen35_caption.py): `code/run_qwen35_caption.py`
- [Shipped LoRA adapters](https://github.com/aiclub-uit/aicity2026-track2/tree/main/artifacts/adapters): `artifacts/adapters`
- [Cosmos preparation](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/cosmos_restyle_prep.py): `code/cosmos_restyle_prep.py`
- **Cosmos restyling**
- [Domain randomization](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/dr_prep.py): `code/dr_prep.py`

### Reasoning and refinement

- [Temporal decoding](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/wsd.py): `code/wsd.py`
- [Fact correction v2](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/fact_stitch.py): `code/fact_stitch.py`
- [Fact correction v3](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/fact_stitch3.py): `code/fact_stitch3.py`
- [Fact correction v4](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/fact_stitch4.py): `code/fact_stitch4.py`
- [Fact correction v5](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/fact_stitch5.py): `code/fact_stitch5.py`

### Pipeline and outputs

- [E2E orchestrator](https://github.com/aiclub-uit/aicity2026-track2/blob/main/code/run_e2e.py): `code/run_e2e.py`
- [Submission files](https://github.com/aiclub-uit/aicity2026-track2/tree/main/submissions): `submissions`

### Other components

- **Reproducer**

## Connections

- Reproducer → E2E orchestrator: runs stages (evidence: `README.md`)
- Challenge datasets → Test layout: supplies test data (evidence: `README.md`)
- Test layout → VQA preprocessing: invokes preprocessing
- Test layout → Caption preprocessing: invokes preprocessing
- Challenge datasets → VQA preprocessing: supplies frames and annotations (evidence: `README.md`)
- Challenge datasets → Caption preprocessing: supplies frames and annotations (evidence: `README.md`)
- VQA preprocessing → Context builder: provides prepared evidence
- VQA preprocessing → VQA adapter: provides prediction inputs (evidence: `README.md`)
- Caption preprocessing → Caption adapters: provides prediction inputs (evidence: `README.md`)
- Context builder → Temporal decoding: uses question helpers (evidence: `code/ctx_builder.py`)
- Context builder → VQA adapter: supports context route
- Shipped LoRA adapters → VQA adapter: loads adapter (evidence: `README.md`)
- Shipped LoRA adapters → Caption adapters: loads adapter (evidence: `README.md`)
- Cosmos preparation → VQA preprocessing: reuses frame selection (evidence: `code/cosmos_restyle_prep.py`)
- Cosmos preparation → Cosmos restyling: prepares restyle inputs (evidence: `README.md`)
- Cosmos restyling → Domain randomization: provides restyled frames (evidence: `README.md`)
- Domain randomization → VQA adapter: supports bundle training (evidence: `README.md`)
- VQA adapter → Temporal decoding: provides probabilities (evidence: `README.md`)
- Temporal decoding → E2E orchestrator: decodes answers (evidence: `code/run_e2e.py`)
- Caption adapters → Fact correction v2: provides draft captions
- Fact correction v2 → Fact correction v3: refines captions (evidence: `code/fact_stitch3.py`)
- Fact correction v3 → Fact correction v4: refines captions (evidence: `code/fact_stitch4.py`)
- Fact correction v4 → Fact correction v5: refines captions (evidence: `code/fact_stitch5.py`)
- E2E orchestrator → VQA adapter: trains and predicts (evidence: `README.md`)
- E2E orchestrator → Caption adapters: trains and predicts (evidence: `README.md`)
- E2E orchestrator → Submission files: writes results (evidence: `README.md`)
- Fact correction v5 → Submission files: writes corrected output (evidence: `code/fact_stitch5.py`)
