# ayuk007/mltunex architecture

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

- Interactive diagram: https://gitdiagram.com/ayuk007/mltunex
- Repository: https://github.com/ayuk007/mltunex

## Overview

##### Project type and purpose
- MLTuneX is an open-source AutoML library (Python package) for model training and hyperparameter tuning.
- It orchestrates data ingestion, model training, evaluation, hyperparameter tuning (via Optuna and GPT guidance), and model persistence.

##### File structure
- Top-level:
- setup.py, pyproject.toml, requirements.txt → packaging/configuration
- src/mltunex/… → core library code
- tests/… → unit and integration tests
- src/mltunex sub-packages:
- ai_handler → GPT-based prompt generation & metadata profiling
- config → global configuration loader
- data → ingestion, loading, splitting
- evaluate → model evaluation and metrics registry
- hyperparam_tuner → tuning orchestration, Optuna integration
- library_trainer → wrappers around sklearn trainers
- model_registry → registering & persisting best models
- trainer → generic training interface
- training_strategy → iteration & parallelization policies
- utils → shared helpers

##### README insights
- Entry point: MLTuneX(data, target_column, task_type).run(...)
- External dependencies: scikit-learn, Optuna, OpenAI API
- Workflow: train → evaluate → tune → save

##### Main components & their relationships
A. User / Client
B. CLI / Python API (main.py)
C. Config module
D. Data Pipeline
1. Ingestion
2. Loading
3. Splitting
E. Trainer
1. Base trainer
2. Library-specific trainers (sklearn)
F. Evaluation
1. Metrics registry
2. Evaluate_model
G. Hyperparameter Tuner
1. Tuning orchestration
2. Optuna tuner
3. AI Handler (GPT prompts & profiling)
H. Training Strategies (iteration / parallelization)
I. Model Registry (persist best model)
J. External services
1. Optuna
2. OpenAI API
K. Output
1. Result CSV
2. Saved model files

Relationships / Data Flow:
- User invokes API → main.py
- main → config loads settings
- Data pipeline reads CSV → produces train/test splits
- Trainer trains a set of models → passes to Evaluate
- Evaluate computes metrics → selects top models
- Hyperparam tuner orchestrates Optuna & optionally AI guidance → tunes top models
- Tuned models retrained via library_trainer → final evaluation
- Model registry saves best model → file system
- Results written to CSV

##### Architectural patterns & design principles
- Modular layering (data → training → evaluation → tuning → persistence)
- Strategy pattern (training_strategy for iteration/parallelization)
- Plugin-like extensibility (library_trainer, model_registry can support new libraries)
- Single responsibility per sub-package

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User / Client"]:::external
    User -->|"invoke MLTuneX().run()"| API["CLI / Python API\nmain.py"]:::internal

    %% Core Pipeline
    subgraph "Configuration"
        Config["Config Module\nconfig.py"]:::internal
    end
    API -->|"load settings"| Config

    subgraph "Data Pipeline"
        direction TB
        BaseData["Base Data Interface\nbase.py"]:::internal
        Ingestion["Data Ingestion\ningestion.py"]:::internal
        Loader["Data Loader\nloader.py"]:::internal
        Splitter["Data Splitter\nsplitter.py"]:::internal
        BaseData --> Ingestion
        Ingestion --> Loader
        Loader --> Splitter
    end
    Config -->|"config"| BaseData
    API -->|"data source"| BaseData

    subgraph "Training"
        direction TB
        GenTrainer["Generic Trainer Interface\nbase.py"]:::internal
        TrainerImpl["Trainer Implementation\ntrainer.py"]:::internal
        LibraryBase["Library Trainer Base\nbase.py"]:::internal
        SklearnTrainer["Scikit-Learn Trainer\nsklearn_trainer.py"]:::internal
        LibLoader["Library Trainer Loader\nlibrary_trainer.py"]:::internal
        GenTrainer --> TrainerImpl
        TrainerImpl --> LibraryBase
        LibraryBase --> SklearnTrainer
        LibraryBase --> LibLoader
    end
    Splitter -->|"train_data/test_data"| GenTrainer

    subgraph "Evaluation"
        direction TB
        EvalBase["Evaluation Base\nbase.py"]:::internal
        EvalModel["Model Evaluation\nevaluate_model.py"]:::internal
        MetricsReg["Metrics Registry\nmetrics_registry.py"]:::internal
        EvalBase --> EvalModel
        EvalModel --> MetricsReg
    end
    GenTrainer -->|"model artifact"| EvalBase
    EvalModel -->|"metrics"| API

    subgraph "Hyperparameter Tuner"
        direction TB
        TunerBase["Tuner Base Interface\nbase.py"]:::internal
        TunerCore["Hyperparameter Tuner Core\nhyperparameter_tuner.py"]:::internal
        Orchestration["Tuning Orchestration\nhyperparameter_tuning_orchestration.py"]:::internal
        OptunaTuner["Optuna Integration\noptuna_tuner.py"]:::internal
        TunerBase --> TunerCore
        TunerCore --> Orchestration
        Orchestration --> OptunaTuner
    end
    EvalModel -->|"top models"| TunerCore

    subgraph "AI Handler"
        direction TB
        Prompt["Prompt Generation\nprompt.py"]:::internal
        HyperGen["Hyperparam Suggestion Generator\nhyperparam_generator.py"]:::internal
        Profiler["Metadata Profiler\nmetadata_profiler.py"]:::internal
        Prompt --> HyperGen
        HyperGen --> Profiler
    end
    TunerCore -->|"param suggestions"| Prompt
    Profiler -->|"profiled params"| Orchestration

    subgraph "Training Strategies"
        direction TB
        Iteration["Iteration Strategy\niteration_strategy.py"]:::internal
        Parallel["Parallelization Strategy\nparallelization_strategy.py"]:::internal
    end
    Orchestration --> Iteration
    Orchestration --> Parallel
    Iteration --> GenTrainer
    Parallel --> GenTrainer

    subgraph "Model Registry"
        direction TB
        RegBase["Registry Base Interface\nbase.py"]:::internal
        RegImpl["Registry Implementation\nmodel_registry.py"]:::internal
        SkReg["Scikit-Learn Registry\nsklearn_registry.py"]:::internal
        RegBase --> RegImpl
        RegImpl --> SkReg
    end
    GenTrainer -->|"final model artifact"| RegBase

    subgraph "External Services"
        direction TB
        Optuna["Optuna"]:::external
        OpenAI["OpenAI GPT"]:::external
    end
    OptunaTuner -->|"optuna calls"| Optuna
    Prompt -->|"API calls"| OpenAI

    subgraph "Outputs"
        direction TB
        CSV["Result CSV"]:::output
        ModelFile["Saved Model Files"]:::output
    end
    MetricsReg --> CSV
    SkReg --> ModelFile

    %% Click Events
    click API "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/main.py"
    click Config "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/config/config.py"
    click BaseData "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/data/base.py"
    click Ingestion "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/data/ingestion.py"
    click Loader "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/data/loader.py"
    click Splitter "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/data/splitter.py"
    click GenTrainer "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/trainer/base.py"
    click TrainerImpl "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/trainer/trainer.py"
    click LibraryBase "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/library_trainer/base.py"
    click SklearnTrainer "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/library_trainer/sklearn_trainer.py"
    click LibLoader "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/library_trainer/library_trainer.py"
    click EvalBase "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/evaluate/base.py"
    click EvalModel "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/evaluate/evaluate_model.py"
    click MetricsReg "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/evaluate/metrics_registry.py"
    click TunerBase "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/hyperparam_tuner/base.py"
    click TunerCore "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/hyperparam_tuner/hyperparameter_tuner.py"
    click Orchestration "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/hyperparam_tuner/hyperparameter_tuning_orchestration.py"
    click OptunaTuner "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/hyperparam_tuner/optuna_tuner.py"
    click Prompt "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/ai_handler/prompt.py"
    click HyperGen "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/ai_handler/hyperparam_generator.py"
    click Profiler "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/ai_handler/metadata_profiler.py"
    click Iteration "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/training_strategy/iteration_strategy.py"
    click Parallel "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/training_strategy/parallelization_strategy.py"
    click RegBase "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/model_registry/base.py"
    click RegImpl "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/model_registry/model_registry.py"
    click SkReg "https://github.com/ayuk007/mltunex/blob/main/src/mltunex/model_registry/sklearn_registry.py"

    %% Styles
    classDef internal fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef external fill:#FFD54F,stroke:#FF8F00,color:#BF360C
    classDef output fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
```
