# lfan-ke/es-moe architecture

> Architecture diagram of the GitHub repository lfan-ke/es-moe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lfan-ke/es-moe
- Repository: https://github.com/lfan-ke/es-moe

## Overview

ES-MoE Toolkit is a Python library that adds expert-sparse mixture-of-experts blocks to Ultralytics YOLO, plus scripts for training and evaluating research runs. The main workflow is to register the block, graft it into a model configuration, build the YOLO model, and route auxiliary router loss into training; the `equip` entry point combines these steps. Separate capabilities support custom experts and balancing losses, DDP training, YOLO-Master recipe comparisons, and routing and metric analysis. The source excerpts show core runtime behavior; script relationships beyond indexed imports are omitted where not evidenced.

Main entry points: [`esmoe/__init__.py`](https://github.com/lfan-ke/es-moe/blob/main/esmoe/__init__.py) (Public API and CLI), [`esmoe/inject.py`](https://github.com/lfan-ke/es-moe/blob/main/esmoe/inject.py) (Register and equip), [`scripts/report.py`](https://github.com/lfan-ke/es-moe/blob/main/scripts/report.py) (Metric reporting), [`esmoe/trainer.py`](https://github.com/lfan-ke/es-moe/blob/main/esmoe/trainer.py) (DDP trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Model integration"]
  node_entrypoints["Public API and CLI<br/>[__init__.py]"]
  node_injection["Register and equip<br/>[inject.py]"]
  node_grafting["Config grafting<br/>[graft.py]"]
  node_registry["Block registry<br/>[registry.py]"]
end

subgraph group_runtime["MoE runtime"]
  node_moe["ESMoE block<br/>[module.py]"]
  node_auxloss["Aux loss collection<br/>[aux_loss.py]"]
end

subgraph group_training["Training"]
  node_trainer["DDP trainer<br/>[trainer.py]"]
  node_upstream["Upstream recipe<br/>[upstream.py]"]
end

subgraph group_experiments["Research runs"]
  node_train["Protocol training<br/>[train.py]"]
  node_parity["Recipe parity<br/>[recipe_parity.py]"]
  node_sameconfig["Same-config runs<br/>[same_config.py]"]
  node_verify["Run verification<br/>[verify.py]"]
end

subgraph group_analysis["Result analysis"]
  node_routing["Routing analysis<br/>[routing.py]"]
  node_report["Metric reporting<br/>[report.py]"]
  node_charts["Charts<br/>[charts.py]"]
  node_backfill["Result backfill<br/>[backfill.py]"]
  node_demo["Demo export<br/>[demo_export.py]"]
end

node_user(("Engineer"))
node_ultralytics["Ultralytics YOLO"]

node_user -->|"calls"| node_entrypoints
node_entrypoints -->|"exposes"| node_injection
node_entrypoints -->|"exposes"| node_grafting
node_injection -->|"grafts config"| node_grafting
node_injection -->|"builds model"| node_ultralytics
node_injection -->|"routes trainer"| node_trainer
node_grafting -->|"loads config"| node_ultralytics
node_ultralytics -->|"builds block"| node_moe
node_moe -->|"publishes loss"| node_registry
node_auxloss -->|"reads losses"| node_registry
node_auxloss -->|"walks blocks"| node_moe
node_injection -->|"adds router loss"| node_auxloss
node_trainer -->|"arms workers"| node_injection
node_trainer -->|"adjusts optimizer"| node_upstream
node_user -->|"runs protocol"| node_train
node_train -->|"uses package"| node_entrypoints
node_parity -->|"uses package"| node_entrypoints
node_sameconfig -->|"reads metrics"| node_report
node_verify -->|"uses package"| node_entrypoints
node_routing -->|"loads model"| node_entrypoints
node_routing -->|"compares runs"| node_report
node_charts -->|"reads aggregates"| node_report
node_charts -->|"reads comparisons"| node_sameconfig
node_backfill -->|"uses reporting"| node_report
node_demo -->|"uses parity data"| node_parity
node_demo -->|"uses package"| node_entrypoints

click node_entrypoints "https://github.com/lfan-ke/es-moe/blob/main/esmoe/__init__.py"
click node_injection "https://github.com/lfan-ke/es-moe/blob/main/esmoe/inject.py"
click node_grafting "https://github.com/lfan-ke/es-moe/blob/main/esmoe/graft.py"
click node_registry "https://github.com/lfan-ke/es-moe/blob/main/esmoe/registry.py"
click node_moe "https://github.com/lfan-ke/es-moe/blob/main/esmoe/module.py"
click node_auxloss "https://github.com/lfan-ke/es-moe/blob/main/esmoe/aux_loss.py"
click node_trainer "https://github.com/lfan-ke/es-moe/blob/main/esmoe/trainer.py"
click node_upstream "https://github.com/lfan-ke/es-moe/blob/main/esmoe/upstream.py"
click node_train "https://github.com/lfan-ke/es-moe/blob/main/scripts/train.py"
click node_parity "https://github.com/lfan-ke/es-moe/blob/main/scripts/recipe_parity.py"
click node_sameconfig "https://github.com/lfan-ke/es-moe/blob/main/scripts/same_config.py"
click node_verify "https://github.com/lfan-ke/es-moe/blob/main/scripts/verify.py"
click node_routing "https://github.com/lfan-ke/es-moe/blob/main/scripts/routing.py"
click node_report "https://github.com/lfan-ke/es-moe/blob/main/scripts/report.py"
click node_charts "https://github.com/lfan-ke/es-moe/blob/main/scripts/charts.py"
click node_backfill "https://github.com/lfan-ke/es-moe/blob/main/scripts/backfill.py"
click node_demo "https://github.com/lfan-ke/es-moe/blob/main/scripts/demo_export.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entrypoints,node_injection,node_grafting,node_registry toneBlue
class node_moe,node_auxloss toneAmber
class node_trainer,node_upstream toneMint
class node_train,node_parity,node_sameconfig,node_verify toneRose
class node_routing,node_report,node_charts,node_backfill,node_demo,node_user,node_ultralytics toneIndigo
```

## Components

### Model integration

- [Public API and CLI](https://github.com/lfan-ke/es-moe/blob/main/esmoe/__init__.py): `esmoe/__init__.py`
- [Register and equip](https://github.com/lfan-ke/es-moe/blob/main/esmoe/inject.py): `esmoe/inject.py`
- [Config grafting](https://github.com/lfan-ke/es-moe/blob/main/esmoe/graft.py): `esmoe/graft.py`
- [Block registry](https://github.com/lfan-ke/es-moe/blob/main/esmoe/registry.py): `esmoe/registry.py`

### MoE runtime

- [ESMoE block](https://github.com/lfan-ke/es-moe/blob/main/esmoe/module.py): `esmoe/module.py`
- [Aux loss collection](https://github.com/lfan-ke/es-moe/blob/main/esmoe/aux_loss.py): `esmoe/aux_loss.py`

### Training

- [DDP trainer](https://github.com/lfan-ke/es-moe/blob/main/esmoe/trainer.py): `esmoe/trainer.py`
- [Upstream recipe](https://github.com/lfan-ke/es-moe/blob/main/esmoe/upstream.py): `esmoe/upstream.py`

### Research runs

- [Protocol training](https://github.com/lfan-ke/es-moe/blob/main/scripts/train.py): `scripts/train.py`
- [Recipe parity](https://github.com/lfan-ke/es-moe/blob/main/scripts/recipe_parity.py): `scripts/recipe_parity.py`
- [Same-config runs](https://github.com/lfan-ke/es-moe/blob/main/scripts/same_config.py): `scripts/same_config.py`
- [Run verification](https://github.com/lfan-ke/es-moe/blob/main/scripts/verify.py): `scripts/verify.py`

### Result analysis

- [Routing analysis](https://github.com/lfan-ke/es-moe/blob/main/scripts/routing.py): `scripts/routing.py`
- [Metric reporting](https://github.com/lfan-ke/es-moe/blob/main/scripts/report.py): `scripts/report.py`
- [Charts](https://github.com/lfan-ke/es-moe/blob/main/scripts/charts.py): `scripts/charts.py`
- [Result backfill](https://github.com/lfan-ke/es-moe/blob/main/scripts/backfill.py): `scripts/backfill.py`
- [Demo export](https://github.com/lfan-ke/es-moe/blob/main/scripts/demo_export.py): `scripts/demo_export.py`

### Other components

- **Engineer**
- **Ultralytics YOLO**

## Connections

- Engineer → Public API and CLI: calls (evidence: `README.md`)
- Public API and CLI → Register and equip: exposes (evidence: `esmoe/__init__.py`)
- Public API and CLI → Config grafting: exposes (evidence: `esmoe/__init__.py`)
- Register and equip → Config grafting: grafts config (evidence: `esmoe/inject.py`)
- Register and equip → Ultralytics YOLO: builds model (evidence: `esmoe/inject.py`)
- Register and equip → DDP trainer: routes trainer (evidence: `esmoe/inject.py`)
- Config grafting → Ultralytics YOLO: loads config (evidence: `esmoe/graft.py`)
- Ultralytics YOLO → ESMoE block: builds block (evidence: `README.md`)
- ESMoE block → Block registry: publishes loss (evidence: `esmoe/module.py`)
- Aux loss collection → Block registry: reads losses (evidence: `esmoe/aux_loss.py`)
- Aux loss collection → ESMoE block: walks blocks (evidence: `esmoe/aux_loss.py`)
- Register and equip → Aux loss collection: adds router loss (evidence: `README.md`)
- DDP trainer → Register and equip: arms workers (evidence: `esmoe/trainer.py`)
- DDP trainer → Upstream recipe: adjusts optimizer (evidence: `esmoe/trainer.py`)
- Engineer → Protocol training: runs protocol (evidence: `README.md`)
- Protocol training → Public API and CLI: uses package (evidence: `scripts/train.py`)
- Recipe parity → Public API and CLI: uses package (evidence: `scripts/recipe_parity.py`)
- Same-config runs → Metric reporting: reads metrics (evidence: `scripts/same_config.py`)
- Run verification → Public API and CLI: uses package (evidence: `scripts/verify.py`)
- Routing analysis → Public API and CLI: loads model (evidence: `scripts/routing.py`)
- Routing analysis → Metric reporting: compares runs (evidence: `scripts/routing.py`)
- Charts → Metric reporting: reads aggregates (evidence: `scripts/charts.py`)
- Charts → Same-config runs: reads comparisons (evidence: `scripts/charts.py`)
- Result backfill → Metric reporting: uses reporting (evidence: `scripts/backfill.py`)
- Demo export → Recipe parity: uses parity data (evidence: `scripts/demo_export.py`)
- Demo export → Public API and CLI: uses package (evidence: `scripts/demo_export.py`)
