# gzaraunitn/autolabel architecture

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

- Interactive diagram: https://gitdiagram.com/gzaraunitn/autolabel
- Repository: https://github.com/gzaraunitn/autolabel

## Overview

##### Project Type and Purpose
- This is an academic / research-oriented machine-learning framework for open-set video domain adaptation.
- It uses a CLIP backbone to extract visual–text features and adapts across video datasets.

##### File Structure
Top-level directories:
- clip/            ← CLIP backbone, tokenizer, model zoo
- configs/         ← global + per-setting YAMLs
- data/            ← CSVs, transforms, dataset & dataloader code
- txt/             ← dataset splits (source/target video lists)
- modules/         ← custom CLIP modules, loss functions, prompts
- loops/           ← training_step.py & test_step.py (the engine)
- utils/           ← schedulers, solvers, attribute JSONs, misc utils
- scripts/ & train.py ← experiment entry points

Key patterns:
– Modular separation: data ↔ model ↔ training loops ↔ utils
– Config-driven experiment runner (train.py + autolabel.yaml + configs/)
– Core ML flow in loops/ + modules/

##### Readme Insights
- Single-script experiments: a user picks a “setting” YAML and calls train.py or scripts/run.sh
- Data paths must be configured inside data/dataloader.py
- Dependencies (PyTorch, CLIP, etc.) defined in autolabel.yaml

##### Main Components & Interactions
a. Experiment Runner
– Entry point: scripts/run.sh or train.py
– Parses CLI flags, loads a config YAML
b. Configuration
– configs/config.yaml + configs/setting/*.yaml drive dataset paths, hyperparams
c. Data Ingestion
– txt/ holds file lists per domain
– data/data_utils.py & data/custom_transforms.py define preprocessing
– data/dataset.py builds a torch.utils.data.Dataset
– data/dataloader.py wraps with DataLoader
d. Model
– clip/ module handles loading CLIP backbone, tokenizer, pre‐trained weights
– modules/clip_modules.py augments CLIP for video frames or features
– modules/prompts.py builds text prompts for open-set classes
– modules/kll_loss.py computes the open-set adaptation loss
e. Training Engine
– loops/training_step.py encapsulates one train iteration: forward, loss, backward
– loops/test_step.py runs validation or domain adaptation evaluation
f. Optimization & Scheduling
– utils/solver.py configures optimizers (SGD/Adam)
– utils/lr_scheduler.py sets learning-rate schedules
g. Outputs
– Checkpoints, logs, validation metrics (written to disk / console)

Data Flow (simplified):
[Runner] → load [Config] → init [Dataset/Dataloader] → init [Model + Prompts]
→ init [Optimizer + Scheduler]
→ loop: (Dataloader → Model → Loss → Optimizer.step → Scheduler.step)
→ periodically call TestStep → write metrics & checkpoints

##### Architectural Patterns & Principles
- Separation of concerns: keep data, model, training, utils in distinct packages
- Configuration-first design: no hard-coded paths or hyperparams
- Single responsibility: each file/class does one job (e.g., kll_loss only computes its loss)

##### Detailed Elements
- Config loader → YAML files
- Data pipeline: txt files → custom_transforms → Dataset → DataLoader
- Model stack: CLIP backbone → prompt module → projection heads
- Loss computation: kll_loss
- Optimizer & LR scheduler
- Training loop vs. test loop
- External resources: disk paths, pre-trained weights
- Output artifacts: model checkpoints, metrics

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration & Entry"
        RunnerCLI["scripts/run.sh"]:::blue
        RunnerScript["train.py"]:::blue
        GlobalYAML["autolabel.yaml"]:::blue
        ConfigLoader["configs/config.yaml"]:::blue
        PerSetting["configs/setting/*.yaml"]:::blue
    end

    subgraph "Data Ingestion"
        Txt["txt/ (file lists)"]:::green
        Transforms["data/custom_transforms.py"]:::green
        DataUtils["data/data_utils.py"]:::green
        Dataset["data/dataset.py"]:::green
        Dataloader["data/dataloader.py"]:::green
    end

    subgraph "Model Stack"
        CLIPBackbone["clip/ (clip.py, model.py, model_zoo.py, simple_tokenizer.py)"]:::orange
        ClipModules["modules/clip_modules.py"]:::orange
        Prompts["modules/prompts.py"]:::orange
        KLLLoss["modules/kll_loss.py"]:::orange
    end

    subgraph "Training Engine"
        TrainStep["loops/training_step.py"]:::purple
        TestStep["loops/test_step.py"]:::purple
    end

    subgraph "Utils & Infrastructure"
        Solver["utils/solver.py"]:::gray
        Scheduler["utils/lr_scheduler.py"]:::gray
        UtilsGen["utils/utils.py"]:::gray
        Attributes["utils/attributes.py"]:::gray
    end

    Outputs["Checkpoints & Logs"]:::gray

    %% Connections
    RunnerCLI -->|"invokes"| RunnerScript
    RunnerScript -->|"loads"| ConfigLoader
    RunnerScript -->|"uses settings"| PerSetting
    RunnerScript -->|"uses global"| GlobalYAML

    ConfigLoader -->|"configures"| Txt
    ConfigLoader -->|"configures"| Transforms
    ConfigLoader -->|"configures"| Dataset
    ConfigLoader -->|"configures"| CLIPBackbone

    Txt -->|"provides paths"| Dataset
    Transforms -->|"applies to"| Dataset
    DataUtils -->|"utilities for"| Dataset
    Dataset -->|"yields samples"| Dataloader

    Dataloader -->|"feeds"| TrainStep
    CLIPBackbone -->|"initializes model"| TrainStep
    ClipModules -->|"augments CLIP"| TrainStep
    Prompts -->|"provides prompts"| TrainStep

    TrainStep -->|"calls loss"| KLLLoss
    KLLLoss -->|"computes loss"| TrainStep

    TrainStep -->|"uses optimizer"| Solver
    Solver -->|"updates weights"| TrainStep
    TrainStep -->|"calls scheduler"| Scheduler
    Scheduler -->|"updates lr"| TrainStep

    TrainStep -->|"periodic eval"| TestStep
    TrainStep -->|"saves artifacts"| Outputs
    TestStep -->|"writes metrics"| Outputs

    %% Click Events
    click RunnerScript "https://github.com/gzaraunitn/autolabel/blob/main/train.py"
    click RunnerCLI "https://github.com/gzaraunitn/autolabel/blob/main/scripts/run.sh"
    click GlobalYAML "https://github.com/gzaraunitn/autolabel/blob/main/autolabel.yaml"
    click ConfigLoader "https://github.com/gzaraunitn/autolabel/blob/main/configs/config.yaml"
    click PerSetting "https://github.com/gzaraunitn/autolabel/blob/main/configs/setting/*.yaml"
    click Txt "https://github.com/gzaraunitn/autolabel/tree/main/txt/"
    click Transforms "https://github.com/gzaraunitn/autolabel/blob/main/data/custom_transforms.py"
    click DataUtils "https://github.com/gzaraunitn/autolabel/blob/main/data/data_utils.py"
    click Dataset "https://github.com/gzaraunitn/autolabel/blob/main/data/dataset.py"
    click Dataloader "https://github.com/gzaraunitn/autolabel/blob/main/data/dataloader.py"
    click CLIPBackbone "https://github.com/gzaraunitn/autolabel/blob/main/clip/clip.py"
    click ClipModules "https://github.com/gzaraunitn/autolabel/blob/main/modules/clip_modules.py"
    click Prompts "https://github.com/gzaraunitn/autolabel/blob/main/modules/prompts.py"
    click KLLLoss "https://github.com/gzaraunitn/autolabel/blob/main/modules/kll_loss.py"
    click TrainStep "https://github.com/gzaraunitn/autolabel/blob/main/loops/training_step.py"
    click TestStep "https://github.com/gzaraunitn/autolabel/blob/main/loops/test_step.py"
    click Solver "https://github.com/gzaraunitn/autolabel/blob/main/utils/solver.py"
    click Scheduler "https://github.com/gzaraunitn/autolabel/blob/main/utils/lr_scheduler.py"
    click UtilsGen "https://github.com/gzaraunitn/autolabel/blob/main/utils/utils.py"
    click Attributes "https://github.com/gzaraunitn/autolabel/blob/main/utils/attributes.py"

    %% Styles
    classDef blue fill:#D0E1FF,stroke:#2F62FF,color:#000
    classDef green fill:#DFFFD0,stroke:#2FCC00,color:#000
    classDef orange fill:#FFD8B0,stroke:#FF8C00,color:#000
    classDef purple fill:#E8D0FF,stroke:#8C2FFF,color:#000
    classDef gray fill:#F0F0F0,stroke:#888, color:#000
```
