# microsoft/flaml architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/flaml
- Repository: https://github.com/microsoft/flaml

## Overview

##### Project Type and Purpose
- This is a Python library (not a deployed service) that provides:
- Automated Machine Learning (AutoML) with low compute footprint (“automl” module).
- Hyperparameter tuning as a standalone tool (“tune” module).
- An LLM‐based multi‐agent conversation framework (“autogen” module).
- Online learning support (“onlineml” module).
- Defaults & presets for common learners (“default” folder).
- Integrations with MLflow, AzureML, Spark, HuggingFace, XGBoost, LightGBM, scikit‐learn, etc.

##### File‐Structure Analysis
- Top‐level “flaml/” folder: source code, subdivided by functionality:
- flaml/automl – core AutoML engine (task definitions, model selection, search loop, state).
- flaml/tune – general-purpose hyperparameter tuning library (searchers, schedulers, trials).
- flaml/autogen – multi-agent orchestration (Agent classes, chain-of-thought, LLM wrappers).
- flaml/onlineml – streaming/online learning support.
- flaml/default – default HP configurations for various learners.
- flaml/fabric – MLflow adapter.
- flaml/config, logger, utils, version.
- Other top‐level dirs:
- test/ – comprehensive unit tests.
- notebook/ and tutorials/ – Jupyter examples.
- website/ – Docusaurus‐based documentation and blog.
- CI/CD config under .github/workflows, Dockerfiles, pyproject.toml, setup.py.

##### Insights from README
- The library exposes three main APIs:
a. AutoML as sklearn‐style estimator: “from flaml import AutoML; automl.fit(...)”
b. Hyperparameter tuning: “from flaml import tune; tune.run(...)”
c. Multi‐agent LLM orchestration: “from flaml import autogen; autogen.AssistantAgent(...)”
- Integrations: OpenAI API, ChatCompletion, MLflow, Spark, AzureML, HuggingFace.

##### Main Components
a. API Layer (User Interface)
– AutoML API
– Tune API
– Autogen API
– OnlineML API
b. Core Engines
– flaml.automl.AutomlEngine (task factory, search loop, model manager)
– flaml.tune.Tuner (trial runner, scheduler, searchers)
– flaml.autogen.AgentFramework (agents, conversation manager)
– flaml.onlineml.OnlineTrialRunner
c. Extension/Plugin Modules
– Searchers: blendsearch, CFO, Flow2, online_searcher
– Schedulers: trial_scheduler, online_scheduler
– Default configurations: JSON presets under flaml/default
– Third‐party wrapper modules: spark.utils, nlp/huggingface, fabric/mlflow
d. External Services and Libraries
– LLM providers: OpenAI API
– ML frameworks: scikit‐learn, XGBoost, LightGBM, SparkML, HuggingFace Transformers
– MLOps: MLflow, AzureML pipelines
– Data storage/log: local file system, object_store, MLflow Tracking
e. Configuration & Orchestration
– flaml/config
– CLI entry points (setup.py console_scripts if any)
– CI/CD pipelines (.github/workflows)

##### Interactions and Data Flow
- User code calls API Layer → Core Engine starts search or chat →
- For AutoML/Tune: Core Engine selects configs → TrialScheduler dispatches trials →
– Each trial uses specific estimator (XGB, LGBM, RF, custom) or user-defined function
– Records metrics via flaml/logger or MLflow adapter → Scheduler/Searcher uses metrics to guide next configs
- For Autogen: Conversation Manager sends messages to Agent classes →
– Agents wrap OpenAI.Completion/ChatCompletion → optional caching, tuning, templating → returns responses → conversation continues
- OnlineML: streams data, updates model incrementally.
- Default module supplies search space presets loaded by engines.
- Config module reads user options; logging streams to console or MLflow.

##### Architectural Patterns and Principles
- Modular “Engine + Plugin” design: engines orchestrate workflows, plugins (searchers, schedulers, estimators) are registered dynamically.
- Separation of concerns:
- API Layer for user interface
- Core logic for search orchestration
- Plugins for algorithmic strategies
- Integrations/adapters for external systems
- Extensibility via config‐driven defaults and Python extension points.
- Observer pattern for logging/tracking (logger & fabric/mlflow).

##### Detailed Elements
- Module names and high‐level class names (AutomlEngine, Tuner, AgentFramework)
- Plugin subfolders (searcher, scheduler, default)
- External adapters (fabric/mlflow.py, nlp/huggingface)

##### Final Checklist
- Clear, consistent labels for each component
- Extensibility points (where new searchers/schedulers/models can be plugged in)
- Keep it at a single page, focusing on major modules and their interactions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% API Layer
    subgraph "API Layer"
        direction TB
        AutoML_API["AutoML API"]:::core
        Tune_API["Tune API"]:::core
        Autogen_API["Autogen API"]:::core
        OnlineML_API["OnlineML API"]:::core
    end

    %% Core Engines & Plugins
    subgraph "Core Engines & Plugins"
        direction TB

        %% Core Engines
        AutomlEngine["AutomlEngine"]:::core
        Tuner["Tuner"]:::core
        AgentFramework["AgentFramework"]:::core
        OnlineTrialRunner["OnlineTrialRunner"]:::core

        %% Plugins
        subgraph "Searchers" 
            direction TB
            BlendSearch["blendsearch"]:::plugin
            CFO["cfo_cat"]:::plugin
            Flow2["flow2"]:::plugin
            OnlineSearcher["online_searcher"]:::plugin
        end

        subgraph "Schedulers"
            direction TB
            TrialScheduler["trial_scheduler"]:::plugin
            OnlineScheduler["online_scheduler"]:::plugin
        end

        DefaultConfigs["Default HP Configs"]:::plugin
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        OpenAI["OpenAI API"]:::external
        MLFrameworks["ML Frameworks"]:::external
        MLflow["MLflow"]:::external
        AzureML["AzureML"]:::external
        Spark["Spark"]:::external
    end

    %% Artefacts
    subgraph "Artefacts & CI/CD"
        direction TB
        Tests["Unit Tests"]:::artefact
        Notebooks["Notebooks & Tutorials"]:::artefact
        Docs["Documentation & Website"]:::artefact
        CICD["CI/CD Workflows"]:::artefact
    end

    %% Connections: API -> Core
    AutoML_API -->|"invoke fit()"| AutomlEngine
    Tune_API -->|"run()"| Tuner
    Autogen_API -->|"start chat()"| AgentFramework
    OnlineML_API -->|"stream data()"| OnlineTrialRunner

    %% Core -> Plugins
    AutomlEngine -->|"use default configs"| DefaultConfigs
    AutomlEngine -->|"register searchers"| BlendSearch
    AutomlEngine -->|"register searchers"| CFO
    AutomlEngine -->|"register searchers"| Flow2
    AutomlEngine -->|"register searchers"| OnlineSearcher
    Tuner -->|"use schedulers"| TrialScheduler
    Tuner -->|"use schedulers"| OnlineScheduler

    %% Core -> External
    AutomlEngine -->|"train models"| MLFrameworks
    AutomlEngine -->|"log metrics"| MLflow
    Tuner -->|"evaluate trial"| MLFrameworks
    Tuner -->|"log metrics"| MLflow
    AgentFramework -->|"send prompt"| OpenAI
    AgentFramework -->|"log conversation"| MLflow
    OnlineTrialRunner -->|"update model"| MLFrameworks

    %% Config & Adapter
    AutomlEngine -->|"load config()"| Config
    Tuner -->|"load config()"| Config
    AgentFramework -->|"load config()"| Config
    Config["Config Module"]:::core
    Version["Versioning"]:::core
    MLflowAdapter["MLflow Adapter"]:::core

    %% Side edges
    Tests --- AutoML_API
    Notebooks --- Tune_API
    Docs --- Autogen_API
    CICD --- Tests

    %% Click Events
    click AutoML_API "https://github.com/microsoft/flaml/blob/main/flaml/automl/__init__.py"
    click AutomlEngine "https://github.com/microsoft/flaml/blob/main/flaml/automl/automl.py"
    click BlendSearch "https://github.com/microsoft/flaml/blob/main/flaml/tune/searcher/blendsearch.py"
    click CFO "https://github.com/microsoft/flaml/blob/main/flaml/tune/searcher/cfo_cat.py"
    click Flow2 "https://github.com/microsoft/flaml/blob/main/flaml/tune/searcher/flow2.py"
    click OnlineSearcher "https://github.com/microsoft/flaml/blob/main/flaml/tune/searcher/online_searcher.py"
    click TrialScheduler "https://github.com/microsoft/flaml/blob/main/flaml/tune/scheduler/trial_scheduler.py"
    click OnlineScheduler "https://github.com/microsoft/flaml/blob/main/flaml/tune/scheduler/online_scheduler.py"
    click DefaultConfigs "https://github.com/microsoft/flaml/tree/main/flaml/default/"
    click Tuner "https://github.com/microsoft/flaml/blob/main/flaml/tune/tune.py"
    click AgentFramework "https://github.com/microsoft/flaml/blob/main/flaml/autogen/agentchat/agent.py"
    click OpenAI "https://github.com/microsoft/flaml/blob/main/flaml/autogen/oai/completion.py"
    click Config "https://github.com/microsoft/flaml/blob/main/flaml/config.py"
    click MLflowAdapter "https://github.com/microsoft/flaml/blob/main/flaml/fabric/mlflow.py"
    click OnlineTrialRunner "https://github.com/microsoft/flaml/blob/main/flaml/onlineml/trial_runner.py"
    click OnlineML_API "https://github.com/microsoft/flaml/blob/main/flaml/onlineml/__init__.py"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#0288D1,stroke-width:1px
    classDef plugin fill:#E8F5E9,stroke:#388E3C,stroke-width:1px
    classDef external fill:#FFF3E0,stroke:#F57C00,stroke-width:1px
    classDef artefact fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px
```
