# toyhouse/mlx-finetune-record architecture

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

- Interactive diagram: https://gitdiagram.com/toyhouse/mlx-finetune-record
- Repository: https://github.com/toyhouse/mlx-finetune-record

## Overview

Based on our analysis of the file tree and the README, this project is a comprehensive, unified pipeline for fine-tuning and deploying Apple MLX-based language models. It’s structured as a full-stack machine learning (ML) workflow that spans from configuration management and data processing through training (with support for LoRA and full fine-tuning), adapter fusion, deployment (with Ollama integration), and benchmarking/evaluation.

##### Main Components

a. Configurations Layer:
– Model Configurations (YAML files in configs/model_configs/)
– Data Configurations (YAML files in configs/data_configs/)
– Training Configurations (YAML files in configs/training_configs/)
– Deployment Configurations (YAML files in configs/deployment_configs/)
– Benchmark Configurations (YAML files in configs/benchmark_configs/)
- This layer holds the centralized parameters, enabling flexibility, and drives the dynamic behavior of other parts of the pipeline.

b. Data & Preprocessing:
- “Data” folder as a source for structured JSONL training, validation, and test data.
- How scripts under utils (e.g., config_loader.py, data_loader.py) and various data directories connect to the training module.
- “pretrained_models” directory if model weights are fetched externally.

c. Training Pipeline:
– The core training script (scripts/train.py) with its use of configurations.
– The integration of LoRA adapters (which are saved to the adapters/ folder).
– EXO Parallel Processing support through dedicated training configurations (configs/training_configs/exo_parallel.yaml) and monitoring (scripts/monitor_exo.py).

d. Adapter Fusion:
- A distinct “Fusion” component that takes the adapters produced during training and fuses them with the base model.
- This is handled by scripts such as fuse.py and results in fused models saved in the fused_model/ directory.
- That this step creates a final model ready for deployment.

e. Deployment:
– Creation of modelfiles (modelfiles/) for deployment to Ollama.
– Scripts like create_ollama_model.py, and templates (templates/ollama_modelfile.template).
– Integration with third-party tools (e.g., Ollama, as outlined in the README).

f. Benchmarking & Evaluation:
- A “Benchmarking & Evaluation” component representing:
– The scripts for benchmarking (scripts/benchmark.py, eval.py).
– The storage of benchmark datasets and results under benchmarks/ (with subfolders for datasets, results, visualizations, and reports).
– How the performance data is generated and later visualized/reported (via scripts like generate_report.py).

g. Utility and Auxiliary Components:
- Additional modules like:
– The agentic_workflow folder (with specific agent scripts like acemath_agent.py, formatter_agent.py, etc.) that encapsulate the core logic for processing tasks.
– Other scripts and helper modules (CLI interfaces, conversion scripts, testing utilities, etc.) which support the overall pipeline.
- While these might be more granular, they can be grouped into “Workflow Components” if needed.

##### Relationships & Data/Control Flow

- From the “Configurations” component to “Training” and “Deployment” (indicating that YAML files drive both training and deployment behavior).
- From “Data” into “Training” (data ingestion for model fine-tuning).
- From “Training” to “Adapters” (adapter weights are produced) then to “Fusion”, and finally to “Deployment”.
- From “Training” and “Fusion” to “Benchmarking & Evaluation” (to validate the results).

##### Architectural Patterns & Design Principles

- A modular and configurable design: The system is divided into distinct stages (configuration, training, fusion, deployment, evaluation) that interact through well-defined configuration files.
- Separation of concerns:
- Configurations are decoupled from the processing logic.
- Each pipeline stage (training, fusion, deployment) is represented as a standalone module.
- Use of parallel processing (via EXO) as a performance-enhancing feature within the training pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TB

    %% Configurations Layer
    subgraph "Configurations Layer"
        configModel["Model YAMLs"]
        configData["Data YAMLs"]
        configTrain["Training YAMLs"]
        configDeploy["Deployment YAMLs"]
        configBenchmark["Benchmark YAMLs"]
    end

    %% Data & Preprocessing Layer
    subgraph "Data & Preprocessing"
        dataSources["Data (JSONL)"]
        dataLoader["Data Loader Script"]
        configLoader["Config Loader Script"]
        pretrained["Pretrained Models"]
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        trainingScript["Training Script"]
        exoConfig["EXO Parallel Config"]
        trainingMonitor["Training Monitor"]
        unifiedPipeline["Unified Pipeline"]
    end

    %% Adapter Fusion
    subgraph "Adapter Fusion"
        fusionScript["Fusion Script"]
        fusedModel["Fused Model"]
    end

    %% Deployment Layer
    subgraph "Deployment"
        deployConfigs["Deployment Configs"]
        ollamaScript["Ollama Deployment Script"]
        modelfileTemplate["Modelfile Template"]
        deployedModels["Deployed Model Files"]
    end

    %% Benchmarking & Evaluation
    subgraph "Benchmarking & Evaluation"
        benchmarkScript["Benchmark Script"]
        evalScript["Evaluation Script"]
        benchmarks["Benchmarks & Results"]
    end

    %% Utility & Workflow Components
    subgraph "Utility & Workflow Components"
        agenticWorkflow["Agentic Workflow"]
        cliHelpers["CLI & Helpers"]
    end

    %% Relationships & Data Flow

    %% Configurations to Training and Deployment
    configTrain -->|"drives"| trainingScript
    configModel -->|"drives"| trainingScript
    configData -->|"drives"| trainingScript
    configDeploy -->|"drives"| deployConfigs
    configBenchmark -->|"feeds"| benchmarkScript

    %% Data & Preprocessing to Training
    dataSources -->|"ingests"| trainingScript
    dataLoader -->|"supports"| trainingScript
    configLoader -->|"supports"| trainingScript
    pretrained -->|"provides"| trainingScript

    %% Training Pipeline Internal Connections
    trainingScript -->|"initiates"| exoConfig
    trainingScript -->|"monitors"| trainingMonitor
    trainingScript -->|"orchestrates"| unifiedPipeline

    %% Training to Fusion and Benchmarking
    trainingScript -->|"produces adapters"| fusionScript
    trainingScript -->|"outputs"| benchmarkScript

    %% Adapter Fusion to Deployment and Benchmarking
    fusionScript -->|"fuses model"| fusedModel
    fusedModel -->|"delivers"| deployedModels
    fusionScript -->|"feeds"| benchmarkScript

    %% Deployment Internal Connections
    deployConfigs -->|"configures"| deployedModels
    ollamaScript -->|"integrates"| deployedModels
    modelfileTemplate -->|"templates"| deployedModels

    %% Benchmarking Connections
    benchmarkScript -->|"generates"| benchmarks
    evalScript -->|"evaluates"| benchmarks

    %% Utility supporting Training
    agenticWorkflow ---|"assists"| trainingScript
    cliHelpers ---|"supports"| trainingScript

    %% Cross-layer: Unified Pipeline triggers Fusion
    unifiedPipeline -->|"triggers fusion"| fusionScript


    %% Click Events
    click configModel "https://github.com/toyhouse/mlx-finetune-record/tree/main/configs/model_configs/"
    click configData "https://github.com/toyhouse/mlx-finetune-record/tree/main/configs/data_configs/"
    click configTrain "https://github.com/toyhouse/mlx-finetune-record/tree/main/configs/training_configs/"
    click configDeploy "https://github.com/toyhouse/mlx-finetune-record/tree/main/configs/deployment_configs/"
    click configBenchmark "https://github.com/toyhouse/mlx-finetune-record/tree/main/configs/benchmark_configs/"
    
    click dataSources "https://github.com/toyhouse/mlx-finetune-record/tree/main/data/"
    click dataLoader "https://github.com/toyhouse/mlx-finetune-record/blob/main/utils/data_loader.py"
    click configLoader "https://github.com/toyhouse/mlx-finetune-record/blob/main/utils/config_loader.py"
    click pretrained "https://github.com/toyhouse/mlx-finetune-record/tree/main/pretrained_models"
    
    click trainingScript "https://github.com/toyhouse/mlx-finetune-record/blob/main/scripts/train.py"
    click exoConfig "https://github.com/toyhouse/mlx-finetune-record/blob/main/configs/training_configs/exo_parallel.yaml"
    click trainingMonitor "https://github.com/toyhouse/mlx-finetune-record/blob/main/scripts/monitor_exo.py"
    click unifiedPipeline "https://github.com/toyhouse/mlx-finetune-record/blob/main/scripts/train_fuse_deploy.py"
    
    click fusionScript "https://github.com/toyhouse/mlx-finetune-record/blob/main/scripts/fuse.py"
    
    click deployConfigs "https://github.com/toyhouse/mlx-finetune-record/tree/main/configs/deployment_configs/"
    click ollamaScript "https://github.com/toyhouse/mlx-finetune-record/blob/main/scripts/create_ollama_model.py"
    click modelfileTemplate "https://github.com/toyhouse/mlx-finetune-record/blob/main/templates/Modelfile_Template.txt"
    click deployedModels "https://github.com/toyhouse/mlx-finetune-record/tree/main/modelfiles/"
    
    click benchmarkScript "https://github.com/toyhouse/mlx-finetune-record/blob/main/scripts/benchmark.py"
    click evalScript "https://github.com/toyhouse/mlx-finetune-record/blob/main/scripts/eval.py"
    click benchmarks "https://github.com/toyhouse/mlx-finetune-record/tree/main/benchmarks/"
    
    click agenticWorkflow "https://github.com/toyhouse/mlx-finetune-record/tree/main/agentic_workflow/"
    click cliHelpers "https://github.com/toyhouse/mlx-finetune-record/blob/main/cli.py"

    %% Styles
    class configModel,configData,configTrain,configDeploy,configBenchmark configClass
    class dataSources,dataLoader,configLoader,pretrained dataClass
    class trainingScript,exoConfig,trainingMonitor,unifiedPipeline trainClass
    class fusionScript,fusedModel fusionClass
    class deployConfigs,ollamaScript,modelfileTemplate,deployedModels deployClass
    class benchmarkScript,evalScript,benchmarks benchClass
    class agenticWorkflow,cliHelpers utilityClass

    %% Class Definitions
    classDef configClass fill:#80bfff,stroke:#333,stroke-width:2px;
    classDef dataClass fill:#7CFC00,stroke:#333,stroke-width:2px;
    classDef trainClass fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef fusionClass fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef deployClass fill:#DA70D6,stroke:#333,stroke-width:2px;
    classDef benchClass fill:#FA8072,stroke:#333,stroke-width:2px;
    classDef utilityClass fill:#FFFF99,stroke:#333,stroke-width:2px;
```
