# bayeswitnesses/m2cgen architecture

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

- Interactive diagram: https://gitdiagram.com/bayeswitnesses/m2cgen
- Repository: https://github.com/bayeswitnesses/m2cgen

## Overview

##### Project type and purpose
- m2cgen is an open‐source **code‐generation library/CLI tool** written in Python.
- It takes a trained statistical or ML model (e.g., scikit‐learn, XGBoost, LightGBM, StatsModels, Lightning) and **transpiles** it into native code in one of many target languages (C, Java, Go, JavaScript, etc.).

##### High‐level file‐structure analysis
- **Top‐level**:
- generated_code_examples/ – sample outputs in all supported languages (not part of core runtime).
- m2cgen/ – the core Python package.
- CLI entrypoint files: `__main__.py`, `cli.py`.
- setup files & CI configs (Dockerfile, Makefile, GitHub workflows, tests/).
- **m2cgen/** subpackages:
- ast.py – definition of in‐memory model representation (AST).
- assemblers/ – logic to convert AST into an intermediate “assembly” for different model families (linear, tree, ensemble, SVM).
- interpreters/ – language‐specific code generators that traverse assembly/AST and output source code.
- exporters.py – public API functions (`export_to_python`, `export_to_java`, …) wiring together model → AST → assembler → interpreter → code.
- cli.py & __main__.py – parse command‐line arguments & invoke exporters.

##### Important architectural patterns & principles
- **Pipeline**: model → AST → assembler → interpreter → code.
- **Strategy/Factory**: each target language has its own interpreter/ code_generator class that implements a common interface.
- **Visitor**: interpreters walk over AST/assembly to emit code.
- **Separation of concerns**:
- AST encapsulates model math in a neutral form.
- Assemblers transform AST into language‐agnostic operations.
- Interpreters handle language syntax, formatting, imports.

##### Main components & relationships
- **User Interfaces**
- Python API (`m2cgen.exporters.export_to_<lang>(model)`)
- CLI (`m2cgen/__main__.py`, `m2cgen/cli.py`)
- **Model Loader** (external): accepts a fitted sklearn/lightgbm/etc. model.
- **AST Generator** (`m2cgen.ast`)
- **Assembler** (`m2cgen.assemblers.*`)
- **Interpreter / Code Generator** (`m2cgen.interpreters.<lang>`)
- **Output Writer**: returns source code string or writes to file.
- **Tests**: ensure correct assembly & interpretation for each language & model type.

User → CLI/API → AST Generator → Assembler → Interpreter → Generated Code → User

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    ExternalML["ML Libraries\n(scikit-learn,\nXGBoost, LightGBM, etc.)"]:::external

    %% User Interface Layer
    subgraph "User Interaction" 
        direction TB
        User["User"]:::external
        subgraph "CLI Entrypoints" 
            direction TB
            Main["__main__.py"]:::ui
            CLIFile["cli.py"]:::ui
        end
        Exporters["exporters.py"]:::ui
    end

    %% Core Pipeline Layer
    subgraph "Core Pipeline" 
        direction TB
        AST["ast.py"]:::core
        subgraph "Assemblers" 
            direction TB
            BaseAsm["base.py"]:::core
            LinearAsm["linear.py"]:::core
            TreeAsm["tree.py"]:::core
            EnsembleAsm["ensemble.py"]:::core
            BoostingAsm["boosting.py"]:::core
            SvmAsm["svm.py"]:::core
            FallbackExpr["fallback_expressions.py"]:::core
            AsmUtils["utils.py"]:::core
        end
    end

    %% Interpreters Layer
    subgraph "Interpreters (Code Generators)" 
        direction TB
        CInterp["C"]:::interp
        CSharpInterp["C#"]:::interp
        DartInterp["Dart"]:::interp
        ElixirInterp["Elixir"]:::interp
        FSharpInterp["F#"]:::interp
        GoInterp["Go"]:::interp
        HaskellInterp["Haskell"]:::interp
        JavaInterp["Java"]:::interp
        JSInterp["JavaScript"]:::interp
        PHPInterp["PHP"]:::interp
        PSInterp["PowerShell"]:::interp
        PythonInterp["Python"]:::interp
        RInterp["R"]:::interp
        RubyInterp["Ruby"]:::interp
        RustInterp["Rust"]:::interp
        VBInterp["Visual Basic"]:::interp
    end

    %% Output & Tools & Tests
    CodeOut["Generated Code"]:::gray
    Tools["generate_code_examples.py"]:::gray
    subgraph "Tests" 
        direction TB
        UnitAsmTests["tests/assemblers/"]:::gray
        IntTests["tests/interpreters/"]:::gray
        CLITests["test_cli.py\ntests/test_cli.py"]:::gray
        ExporterTests["test_exporters.py"]:::gray
        ASTTests["test_ast.py"]:::gray
        E2ETests["tests/e2e/"]:::gray
    end

    %% Flow Connections
    User -->|"invokes"| Main
    User -->|"invokes"| CLIFile
    Main -->|"calls"| Exporters
    CLIFile -->|"calls"| Exporters
    ExternalML -->|"model input"| Exporters
    Exporters -->|"build AST"| AST
    AST -->|"to assembly"| BaseAsm
    BaseAsm --> LinearAsm
    BaseAsm --> TreeAsm
    BaseAsm --> EnsembleAsm
    BaseAsm --> BoostingAsm
    BaseAsm --> SvmAsm
    BaseAsm --> FallbackExpr
    BaseAsm --> AsmUtils
    LinearAsm -->|"assembly"| CInterp
    TreeAsm -->|"assembly"| CInterp
    EnsembleAsm -->|"assembly"| CInterp
    BoostingAsm -->|"assembly"| CInterp
    SvmAsm -->|"assembly"| CInterp
    AsmUtils -->|"shared ops"| CInterp
    CInterp -->|"emit code"| CodeOut
    CSharpInterp -->|"emit code"| CodeOut
    DartInterp -->|"emit code"| CodeOut
    ElixirInterp -->|"emit code"| CodeOut
    FSharpInterp -->|"emit code"| CodeOut
    GoInterp -->|"emit code"| CodeOut
    HaskellInterp -->|"emit code"| CodeOut
    JavaInterp -->|"emit code"| CodeOut
    JSInterp -->|"emit code"| CodeOut
    PHPInterp -->|"emit code"| CodeOut
    PSInterp -->|"emit code"| CodeOut
    PythonInterp -->|"emit code"| CodeOut
    RInterp -->|"emit code"| CodeOut
    RubyInterp -->|"emit code"| CodeOut
    RustInterp -->|"emit code"| CodeOut
    VBInterp -->|"emit code"| CodeOut
    CodeOut -->|"code delivered"| User
    Tools -->|"bulk generation"| CodeOut

    %% Click Events
    click Main "https://github.com/bayeswitnesses/m2cgen/blob/master/m2cgen/__main__.py"
    click CLIFile "https://github.com/bayeswitnesses/m2cgen/blob/master/m2cgen/cli.py"
    click Exporters "https://github.com/bayeswitnesses/m2cgen/blob/master/m2cgen/exporters.py"
    click AST "https://github.com/bayeswitnesses/m2cgen/blob/master/m2cgen/ast.py"
    click BaseAsm "https://github.com/bayeswitnesses/m2cgen/blob/master/m2cgen/assemblers/base.py"
    click LinearAsm "https://github.com/bayeswitnesses/m2cgen/blob/master/m2cgen/assemblers/linear.py"
    click TreeAsm "https://github.com/bayeswitnesses/m2cgen/blob/master/m2cgen/assemblers/tree.py"
    click EnsembleAsm "https://github.com/bayeswitnesses/m2cgen/blob/master/m2cgen/assemblers/ensemble.py"
    click BoostingAsm "https://github.com/bayeswitnesses/m2cgen/blob/master/m2cgen/assemblers/boosting.py"
    click SvmAsm "https://github.com/bayeswitnesses/m2cgen/blob/master/m2cgen/assemblers/svm.py"
    click FallbackExpr "https://github.com/bayeswitnesses/m2cgen/blob/master/m2cgen/assemblers/fallback_expressions.py"
    click AsmUtils "https://github.com/bayeswitnesses/m2cgen/blob/master/m2cgen/assemblers/utils.py"
    click CInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/c/"
    click CSharpInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/c_sharp/"
    click DartInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/dart/"
    click ElixirInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/elixir/"
    click FSharpInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/f_sharp/"
    click GoInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/go/"
    click HaskellInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/haskell/"
    click JavaInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/java/"
    click JSInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/javascript/"
    click PHPInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/php/"
    click PSInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/powershell/"
    click PythonInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/python/"
    click RInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/r/"
    click RubyInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/ruby/"
    click RustInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/rust/"
    click VBInterp "https://github.com/bayeswitnesses/m2cgen/tree/master/m2cgen/interpreters/visual_basic/"
    click Tools "https://github.com/bayeswitnesses/m2cgen/blob/master/tools/generate_code_examples.py"
    click CodeOut "https://github.com/bayeswitnesses/m2cgen/tree/master/generated_code_examples/"

    %% Styles
    classDef ui fill:#c6f6d5,stroke:#4CAF50
    classDef core fill:#bee3f8,stroke:#3182CE
    classDef interp fill:#fbd38d,stroke:#DD6B20
    classDef gray fill:#e2e8f0,stroke:#A0AEC0
    classDef external fill:#edf2f7,stroke-dasharray: 5 5,stroke:#718096
```
