# onnx/sklearn-onnx architecture

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

- Interactive diagram: https://gitdiagram.com/onnx/sklearn-onnx
- Repository: https://github.com/onnx/sklearn-onnx

## Overview

##### Project type and purpose
- This is an open-source Python library/tool (skl2onnx) that converts scikit-learn pipelines and models into ONNX format.
- Its main use case is: take a trained scikit-learn estimator, translate it operator by operator into ONNX, and output a .onnx file for high-performance inference (e.g., with ONNX Runtime).

##### File structure
- Top level:
- pyproject.toml, requirements*.txt → build/dependency descriptors
- benchmarks/ → performance tests and plots
- docs/ → user documentation, tutorials, Sphinx configuration
- skl2onnx/ → core package
- tests/ & tests_onnxmltools/ → extensive unit and integration tests
- Inside skl2onnx/:
- __main__.py → CLI entry point (`python -m skl2onnx`)
- convert.py & _parse.py → front-end API for model conversion
- operator_converters/ → one file per scikit-learn operator converter
- algebra/ & common/ → internal graph-manipulation, topology, and ONNX operator factories
- helpers/ → utilities for ONNX graph inspection and extension
- sklapi/ → convenience wrappers around scikit-learn types
- tutorial/ → embedded demo scripts
- CI: .github/workflows (Linting, testing, release)

##### README for additional insights
- Entry function: `to_onnx()`
- External dependencies: onnx, onnxruntime
- Extensibility: supports registering custom converters and external libraries

a. Main components
1. User API / CLI
2. Converter Front-End (`convert.py`, `to_onnx`)
3. Parser (_parse.py)
4. Operator Registry (mapping sklearn operator → converter)
5. Operator Converters (operator_converters/)
7. Graph Builder & Topology (common/, algebra/)
8. ONNX Model Output
9. External Runtime (onnxruntime)
10. Tests & Benchmarks & Docs (supporting modules)
b. Relationships & data flow
- User imports `to_onnx` or calls CLI → feeds sklearn model + sample input
- Parser inspects model metadata, options → builds an internal topology
- For each node in sklearn pipeline:
- Lookup converter in Operator Registry
- Operator Converter emits ONNX operator nodes
- Algebra/Common modules assemble full ONNX graph
- Final graph serialized to .onnx
- (Optional) Benchmarks use onnxruntime to measure performance
c. Architectural patterns
- Plugin/Registry pattern for operator converters
- Modular separation: parsing, conversion, graph construction, serialization
- Layered design: API → conversion engine → graph builder → output
d. Key technologies
- Python 3
- ONNX protobuf model specification
- scikit-learn introspection
- onnxruntime for testing/benchmarks
- Sphinx for documentation

##### Be detailed but focused
- Every major sub-directory as a component
- Plugin registry and modular converter files
- Don’t show every single operator file, but illustrate “operator_converters/*” as one component with many plugins

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "API & CLI Layer"
        User["User API / CLI"]:::core
        API["Front-End Conversion API (to_onnx)"]:::core
    end

    subgraph "Conversion Engine Layer"
        Parser["_parse.py Parser Module"]:::core
        Registry["Supported Operators Registry"]:::core
        RegUtils["Operator Registration Utilities"]:::core
        Converters["Operator Converters (plugin modules)"]:::core
        Shapes["Shape Calculators"]:::core
    end

    subgraph "Graph Builder Layer"
        subgraph "Topology & Builder"
            Topology["Topology Core"]:::core
            GraphBuilder["Graph Builder Opset"]:::core
        end
        Algebra["Algebraic Graph Construction"]:::core
        OptSerialize["ONNX Optimization & Serialization"]:::core
    end

    subgraph "Output & Runtime Layer"
        ONNXModel["ONNX Model Output"]:::core
        SKLearn["scikit-learn"]:::external
        ONNX["onnx"]:::external
        Runtime["onnxruntime"]:::external
        Benchmarks["Benchmarks (ONNX Runtime performance tests)"]:::support
    end

    subgraph "Supporting Artifacts Layer"
        Helpers["Helper Utilities"]:::core
        SKLAPI["scikit-learn API Wrappers"]:::core
        Tutorial["Embedded Tutorials & Demos"]:::core
        Docs["Documentation & Tutorials"]:::support
        Tests["Unit & Integration Tests"]:::support
        CI["CI Workflows"]:::support
    end

    %% Data Flow
    User -->|"calls CLI"| API
    API -->|"invokes"| Parser
    Parser -->|"uses registry"| Registry
    Registry --> RegUtils
    Parser -->|"iterates operators"| Converters
    Converters -->|"emits ops"| Shapes
    Shapes --> Topology
    Topology --> GraphBuilder
    GraphBuilder --> Algebra
    Algebra --> OptSerialize
    OptSerialize --> ONNXModel
    ONNXModel -->|"uses"| ONNX
    ONNXModel -->|"tested by"| Runtime
    Runtime --> Benchmarks
    SKLearn --> API

    %% Support links
    API --> Helpers
    API --> SKLAPI
    API --> Tutorial
    Tests --> API
    Tests --> Converters
    Docs --> Tutorial
    CI --> Tests

    %% Click Events
    click User "https://github.com/onnx/sklearn-onnx/blob/main/skl2onnx/__main__.py"
    click API "https://github.com/onnx/sklearn-onnx/blob/main/skl2onnx/convert.py"
    click Parser "https://github.com/onnx/sklearn-onnx/blob/main/skl2onnx/_parse.py"
    click Registry "https://github.com/onnx/sklearn-onnx/blob/main/skl2onnx/_supported_operators.py"
    click RegUtils "https://github.com/onnx/sklearn-onnx/blob/main/skl2onnx/common/_registration.py"
    click Converters "https://github.com/onnx/sklearn-onnx/tree/main/skl2onnx/operator_converters/"
    click Shapes "https://github.com/onnx/sklearn-onnx/tree/main/skl2onnx/shape_calculators/"
    click Topology "https://github.com/onnx/sklearn-onnx/blob/main/skl2onnx/common/_topology.py"
    click GraphBuilder "https://github.com/onnx/sklearn-onnx/blob/main/skl2onnx/common/graph_builder_opset.py"
    click Algebra "https://github.com/onnx/sklearn-onnx/tree/main/skl2onnx/algebra/"
    click OptSerialize "https://github.com/onnx/sklearn-onnx/blob/main/skl2onnx/common/_onnx_optimisation_common.py"
    click OptSerialize "https://github.com/onnx/sklearn-onnx/blob/main/skl2onnx/algebra/onnx_ops.py"
    click Helpers "https://github.com/onnx/sklearn-onnx/tree/main/skl2onnx/helpers/"
    click SKLAPI "https://github.com/onnx/sklearn-onnx/tree/main/skl2onnx/sklapi/"
    click Tutorial "https://github.com/onnx/sklearn-onnx/tree/main/skl2onnx/tutorial/"
    click Benchmarks "https://github.com/onnx/sklearn-onnx/tree/main/benchmarks/"
    click Docs "https://github.com/onnx/sklearn-onnx/tree/main/docs/"
    click Tests "https://github.com/onnx/sklearn-onnx/tree/main/tests/"
    click CI "https://github.com/onnx/sklearn-onnx/tree/main/.github/workflows/"

    %% Styles
    classDef core fill:#D6E8FF,stroke:#28527a,color:#000
    classDef external fill:#DFF7E3,stroke:#2E7D32,color:#000
    classDef support fill:#F0F0F0,stroke:#444,color:#000
```
