# autogluon/autogluon architecture

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

- Interactive diagram: https://gitdiagram.com/autogluon/autogluon
- Repository: https://github.com/autogluon/autogluon

## Overview

##### Project type and purpose
- AutoGluon is an open-source AutoML library (monorepo of Python packages) that enables fast, accurate ML model training and deployment on tabular, multimodal (image/text), and time‐series data.
- Key use cases:
- TabularPredictor for structured data
- MultiModalPredictor for combined text/image/tabular
- TimeSeriesPredictor for probabilistic forecasting
- EDA toolkit for automated exploratory analysis

##### High-level file structure
- Top-level modules/packages (each with its own setup.py, src, tests):
- common – shared utilities (I/O, serialization, feature metadata)
- core – orchestration (HPO, model trial, scheduler, ensemble)
- tabular – tabular ML workflows (feature engineering, model families, predictor)
- multimodal – deep‐learning pipelines (data modules, learners, models, optim)
- timeseries – forecasting workflows (dataset, models, trainer, metrics)
- eda – automated exploratory data analysis (analysis + visualization)
- features – standalone feature generator library
- Supporting directories:
- docs & tutorials – system documentation, how to install, run examples
- CI & GitHub/actions – build/test pipelines, Dockerfiles, benchmarks
- examples – end-to-end sample scripts

##### Core architectural components
a. Client / API layer
- Predictor classes (TabularPredictor, MultiModalPredictor, TimeSeriesPredictor, EDA CLI)
- User invokes .fit(), .predict(), .analyze()
b. Data ingestion & preprocessing
- common.loaders & savers (load_pandas, load_s3, etc.)
- per-package data modules (tabular/data, multimodal/data, timeseries/dataset)
- feature generators (features/generators)
c. Orchestration & scheduling
- core.hpo (search space, RayTune executor, scheduler)
- core.scheduler (sequential or parallel job scheduling)
- core.callback & early stopping
d. Model training & ensembling
- core.models.abstract + concrete implementations (bagged ensemble, stackers)
- tabular.models (XGBoost, CatBoost, random forest, neural nets, etc.)
- multimodal.learners & models (transformers, fusion layers)
- timeseries models (AutogluonTabular wrappers, Chronos pipelines, ensemble)
e. Utilities & infrastructure
- common.utils (logging, resource management, context)
- core.ray integration (resource calculation, distributed jobs)
- checkpointing & caching (multimodal/utils/cache, common/savers)
f. Extension & registry mechanisms
- autogluon.*.registry for model/component registration
- config & preset YAML files (multimodal/configs, tabular/configs, timeseries/configs)

##### Interactions & data flows
- Data flow:
User data → API layer (.fit) → Data loaders → Feature generation → HPO search loop → Model training → Evaluation → Ensemble building → Predictor artifact
- Control flow:
Predictor invokes scheduler → each trial uses trainer/learner → callbacks report to scheduler/HPO → final model selection
- External integrations:
- Ray cluster for parallel HPO
- S3 / local filesystem for data & model storage
- HuggingFace model hub mirror (CI/hf_mirror)
- Cloud services via tutorials (SageMaker, AWS Lambda)

##### Architectural patterns & design principles
- Modular, layered design: core engine decoupled from domain packages
- Plugin/registry pattern for adding new model families or data handlers
- Configuration‐driven workflows via YAML presets
- Separation of concerns: data, model, training, HPO, orchestration
- Reuse of common utilities across packages

##### Essential details to capture
- Predictor → core.hpo & core.scheduler → per-package learner/trainer
- Data modules feeding feature generators & model inputs
- Model registry & ensemble building in core.models
- Common utilities (logging, resource management) underpinning all workflows
- Config & preset files driving default hyperparameters and pipelines

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Users
    User["User"]:::external

    %% External Services
    subgraph "External Services"
        RayCluster["Ray Cluster"]:::external
        S3["S3 / Local FS"]:::external
        HFHub["HuggingFace Model Hub"]:::external
    end

    %% Common Utilities Layer
    subgraph "Common Utilities" 
        direction TB
        Utils["common.utils"]:::common
        Loaders["Loaders"]:::common
        Savers["Savers"]:::common
        FeaturesMeta["Feature Metadata & Types"]:::common
    end

    %% Core Engine Layer
    subgraph "Core Engine" 
        direction TB
        HPO["core.hpo"]:::core
        Scheduler["core.scheduler"]:::core
        Callbacks["core.callbacks"]:::core
        RayInt["core.ray"]:::core
        ModelsEngine["core.models & Ensemble"]:::core
        LearnerCore["core.learner & trainer"]:::core
    end

    %% Domain Packages
    subgraph "Domain Packages"
        direction TB

        subgraph Tabular
            direction TB
            TabPred["TabularPredictor API"]:::domain
            TabConfigs["Tabular Configs & Presets"]:::domain
            TabLearner["Tabular Learner & Trainer"]:::domain
            TabModels["Tabular Model Families"]:::domain
            TabRegistry["Tabular Registry"]:::domain
        end

        subgraph MultiModal
            direction TB
            MMPred["MultiModalPredictor API"]:::domain
            MMConfigs["MultiModal Configs & Presets"]:::domain
            MMData["MultiModal Data Modules"]:::domain
            MMLearners["MultiModal Learners"]:::domain
            MMModels["MultiModal Models & Fusion"]:::domain
            MMOptim["MultiModal Optimizers"]:::domain
            MMUtils["MultiModal Utils"]:::domain
        end

        subgraph TimeSeries
            direction TB
            TSPred["TimeSeriesPredictor API"]:::domain
            TSConfigs["TimeSeries Configs & Presets"]:::domain
            TSDataset["TimeSeries Dataset"]:::domain
            TSModels["TimeSeries Models"]:::domain
            TSTrainer["TimeSeries Trainer & Learner"]:::domain
            TSUtils["TimeSeries Utils & Transforms"]:::domain
        end

        subgraph EDA
            direction TB
            EDACLI["EDA CLI & Auto-analyze"]:::domain
            EDAAnalysis["EDA Analysis Modules"]:::domain
            EDAViz["EDA Visualization Modules"]:::domain
            EDAUtils["EDA Utils & State"]:::domain
        end

        subgraph Features
            direction TB
            FGens["Feature Generators"]:::common
            FVects["Feature Vectorizers"]:::common
            FUtils["Features Utils"]:::common
        end
    end

    %% User interactions
    User -->|".fit(), .predict(), .analyze()"| TabPred
    User -->|".fit(), .predict()"| MMPred
    User -->|".fit(), .predict()"| TSPred
    User -->|".analyze()"| EDACLI

    %% Data & Config flows
    TabPred -->|uses| TabConfigs
    MMPred -->|uses| MMConfigs
    TSPred -->|uses| TSConfigs

    TabPred -->|loads data via| Loaders
    MMPred -->|loads data via| MMData
    TSPred -->|loads data via| TSDataset
    EDACLI -->|loads data via| Loaders

    Loaders -->|metadata| FeaturesMeta
    TabDataFlow[Feature Generation]:::common -->|generates features| FGens
    FGens --> FVects
    FVects -->|features| TabPred

    %% Core control & orchestration
    TabPred -->|schedules jobs via| Scheduler
    MMPred -->|schedules jobs via| Scheduler
    TSPred -->|schedules jobs via| Scheduler

    Scheduler -->|trains via| LearnerCore
    LearnerCore -->|executes search| HPO
    HPO -->|reports metrics| Callbacks
    Callbacks -->|controls| Scheduler

    %% Model Engines
    LearnerCore -->|builds models| ModelsEngine
    TabLearner -->|implements| LearnerCore
    MMLearners -->|implements| LearnerCore
    TSTrainer -->|implements| LearnerCore

    ModelsEngine -->|ensemble| TabModels
    ModelsEngine -->|ensemble| MMModels
    ModelsEngine -->|ensemble| TSModels

    TabRegistry -->|registers models| TabModels
    MMUtils -->|registry| MMModels
    TSUtils -->|transforms| TSDataset

    %% Utilities & infra
    Utils -->|logging & context| Scheduler
    Utils -->|resource mgmt| RayInt
    RayInt -->|executes tasks on| RayCluster
    Savers -->|stores artifacts on| S3
    MMUtils -->|caching| Savers
    FeaturesMeta -->|metadata| FGens
    HFHub -.->|mirror CI| Savers

    %% Click Events
    click Utils "https://github.com/autogluon/autogluon/tree/master/common/src/autogluon/common/utils"
    click Loaders "https://github.com/autogluon/autogluon/tree/master/common/src/autogluon/common/loaders"
    click Savers "https://github.com/autogluon/autogluon/tree/master/common/src/autogluon/common/savers"
    click FeaturesMeta "https://github.com/autogluon/autogluon/tree/master/common/src/autogluon/common/features"
    click HPO "https://github.com/autogluon/autogluon/tree/master/core/src/autogluon/core/hpo"
    click Scheduler "https://github.com/autogluon/autogluon/tree/master/core/src/autogluon/core/scheduler"
    click Callbacks "https://github.com/autogluon/autogluon/tree/master/core/src/autogluon/core/callbacks"
    click RayInt "https://github.com/autogluon/autogluon/tree/master/core/src/autogluon/core/ray"
    click ModelsEngine "https://github.com/autogluon/autogluon/tree/master/core/src/autogluon/core/models"
    click LearnerCore "https://github.com/autogluon/autogluon/tree/master/core/src/autogluon/core/learner"
    click LearnerCore "https://github.com/autogluon/autogluon/tree/master/core/src/autogluon/core/trainer"
    click TabPred "https://github.com/autogluon/autogluon/blob/master/tabular/src/autogluon/tabular/predictor/predictor.py"
    click TabConfigs "https://github.com/autogluon/autogluon/tree/master/tabular/src/autogluon/tabular/configs"
    click TabLearner "https://github.com/autogluon/autogluon/tree/master/tabular/src/autogluon/tabular/learner"
    click TabLearner "https://github.com/autogluon/autogluon/blob/master/tabular/src/autogluon/tabular/trainer/auto_trainer.py"
    click TabModels "https://github.com/autogluon/autogluon/tree/master/tabular/src/autogluon/tabular/models"
    click TabRegistry "https://github.com/autogluon/autogluon/tree/master/tabular/src/autogluon/tabular/registry"
    click MMPred "https://github.com/autogluon/autogluon/blob/master/multimodal/src/autogluon/multimodal/predictor.py"
    click MMConfigs "https://github.com/autogluon/autogluon/tree/master/multimodal/src/autogluon/multimodal/configs"
    click MMData "https://github.com/autogluon/autogluon/tree/master/multimodal/src/autogluon/multimodal/data"
    click MMLearners "https://github.com/autogluon/autogluon/tree/master/multimodal/src/autogluon/multimodal/learners"
    click MMModels "https://github.com/autogluon/autogluon/tree/master/multimodal/src/autogluon/multimodal/models"
    click MMOptim "https://github.com/autogluon/autogluon/tree/master/multimodal/src/autogluon/multimodal/optim"
    click MMUtils "https://github.com/autogluon/autogluon/tree/master/multimodal/src/autogluon/multimodal/utils"
    click TSPred "https://github.com/autogluon/autogluon/blob/master/timeseries/src/autogluon/timeseries/predictor.py"
    click TSConfigs "https://github.com/autogluon/autogluon/tree/master/timeseries/src/autogluon/timeseries/configs"
    click TSDataset "https://github.com/autogluon/autogluon/tree/master/timeseries/src/autogluon/timeseries/dataset"
    click TSModels "https://github.com/autogluon/autogluon/tree/master/timeseries/src/autogluon/timeseries/models"
    click TSTrainer "https://github.com/autogluon/autogluon/blob/master/timeseries/src/autogluon/timeseries/trainer.py"
    click TSTrainer "https://github.com/autogluon/autogluon/blob/master/timeseries/src/autogluon/timeseries/learner.py"
    click TSUtils "https://github.com/autogluon/autogluon/tree/master/timeseries/src/autogluon/timeseries/utils"
    click TSUtils "https://github.com/autogluon/autogluon/tree/master/timeseries/src/autogluon/timeseries/transforms"
    click EDACLI "https://github.com/autogluon/autogluon/blob/master/eda/src/autogluon/eda/auto/simple.py"
    click EDAAnalysis "https://github.com/autogluon/autogluon/tree/master/eda/src/autogluon/eda/analysis"
    click EDAViz "https://github.com/autogluon/autogluon/tree/master/eda/src/autogluon/eda/visualization"
    click EDAUtils "https://github.com/autogluon/autogluon/tree/master/eda/src/autogluon/eda/utils"
    click EDAUtils "https://github.com/autogluon/autogluon/blob/master/eda/src/autogluon/eda/state.py"
    click FGens "https://github.com/autogluon/autogluon/tree/master/features/src/autogluon/features/generators"
    click FVects "https://github.com/autogluon/autogluon/tree/master/features/src/autogluon/features/vectorizers"
    click FUtils "https://github.com/autogluon/autogluon/blob/master/features/src/autogluon/features/utils.py"

    %% Styles
    classDef core fill:#cfe2f3,stroke:#333,stroke-width:1px;
    classDef domain fill:#d9ead3,stroke:#333,stroke-width:1px;
    classDef common fill:#fff2cc,stroke:#333,stroke-width:1px;
    classDef external fill:#ebebeb,stroke:#333,stroke-width:1px;
    class User external
    class RayCluster,S3,HFHub external
    class Utils,Loaders,Savers,FeaturesMeta,FGens,FVects,FUtils common
    class HPO,Scheduler,Callbacks,RayInt,ModelsEngine,LearnerCore core
    class TabPred,TabConfigs,TabLearner,TabModels,TabRegistry domain
    class MMPred,MMConfigs,MMData,MMLearners,MMModels,MMOptim,MMUtils domain
    class TSPred,TSConfigs,TSDataset,TSModels,TSTrainer,TSUtils domain
    class EDACLI,EDAAnalysis,EDAViz,EDAUtils domain
```
