# sachncs/morel architecture

> Architecture diagram of the GitHub repository sachncs/morel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sachncs/morel
- Repository: https://github.com/sachncs/morel

## Overview

morel is a Python research and inference package for robust multimodal recommendation. Its central workflow prepares interaction graphs and partially missing item features, retrieves graph context, completes missing modalities through routed codebooks, and ranks items; training and evaluation support that workflow. It also offers a data-lifecycle CLI and an optional inference API. The graph follows the README and sampled pipeline, retrieval, and server code; some subsystem links are omitted where source wiring was not sampled.

Main entry points: [`morel/pipeline/composer.py`](https://github.com/sachncs/morel/blob/master/morel/pipeline/composer.py) (GRE-MC pipeline), [`morel/serve/app.py`](https://github.com/sachncs/morel/blob/master/morel/serve/app.py) (Inference API), [`morel/data/build.py`](https://github.com/sachncs/morel/blob/master/morel/data/build.py) (Build graphs), [`morel/data/acquire.py`](https://github.com/sachncs/morel/blob/master/morel/data/acquire.py) (Acquire data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data lifecycle"]
  node_acquire["Acquire data<br/>[acquire.py]"]
  node_extract["Extract data<br/>[extract.py]"]
  node_build["Build graphs<br/>[build.py]"]
  node_mask["Mask modalities<br/>[mask.py]"]
  node_store[("Dataset store<br/>[store.py]")]
end

subgraph group_model["GRE-MC model"]
  node_pipeline["GRE-MC pipeline<br/>[composer.py]"]
  node_retrieve["Graph retrieval<br/>[pipeline.py]"]
  node_encode["Feature encoding<br/>[transformer.py]"]
  node_route["Codebook routing<br/>[router.py]"]
  node_codebook["Modality codebook<br/>[codebook.py]"]
  node_complete["Completion decoder<br/>[decoders.py]"]
  node_recommend["Item ranking<br/>[light.py]"]
end

subgraph group_experiments["Training and evaluation"]
  node_trainer["Model training<br/>[trainer.py]"]
  node_eval["Evaluation and ablations<br/>[completion.py]"]
  node_experiment["Experiment services<br/>[experiment.py]"]
end

subgraph group_serving["Inference service"]
  node_api["Inference API<br/>[app.py]"]
  node_loader["Model loader<br/>[loader.py]"]
  node_auth["Scoped authentication<br/>[auth.py]"]
  node_updater["Model updates<br/>[update.py]"]
end

node_user(("Researcher or caller"))

node_user -->|"starts data lifecycle"| node_acquire
node_user -->|"provides features and graph"| node_pipeline
node_pipeline -->|"retrieves context"| node_retrieve
node_pipeline -->|"encodes features"| node_encode
node_pipeline -->|"routes representations"| node_route
node_pipeline -->|"uses codebook"| node_codebook
node_pipeline -->|"completes modalities"| node_complete
node_user -->|"requests ranking"| node_recommend
node_user -->|"starts training"| node_trainer
node_trainer -->|"trains model"| node_pipeline
node_user -->|"requests evaluation"| node_eval
node_user -->|"runs experiment"| node_experiment
node_user -->|"sends request"| node_api
node_api -->|"checks scope"| node_auth
node_api -->|"loads pipeline"| node_loader
node_api -->|"dispatches updates"| node_updater
node_loader -->|"provides model"| node_pipeline
node_acquire -->|"extracts archive"| node_extract
node_extract -->|"prepares inputs"| node_build
node_build -->|"supports masking"| node_mask
node_build -->|"stores dataset"| node_store

click node_acquire "https://github.com/sachncs/morel/blob/master/morel/data/acquire.py"
click node_extract "https://github.com/sachncs/morel/blob/master/morel/data/extract.py"
click node_build "https://github.com/sachncs/morel/blob/master/morel/data/build.py"
click node_mask "https://github.com/sachncs/morel/blob/master/morel/data/mask.py"
click node_store "https://github.com/sachncs/morel/blob/master/morel/data/store.py"
click node_pipeline "https://github.com/sachncs/morel/blob/master/morel/pipeline/composer.py"
click node_retrieve "https://github.com/sachncs/morel/blob/master/morel/retrieve/pipeline.py"
click node_encode "https://github.com/sachncs/morel/blob/master/morel/encode/transformer.py"
click node_route "https://github.com/sachncs/morel/blob/master/morel/route/router.py"
click node_codebook "https://github.com/sachncs/morel/blob/master/morel/codebook/codebook.py"
click node_complete "https://github.com/sachncs/morel/blob/master/morel/complete/decoders.py"
click node_recommend "https://github.com/sachncs/morel/blob/master/morel/recommend/light.py"
click node_trainer "https://github.com/sachncs/morel/blob/master/morel/train/trainer.py"
click node_eval "https://github.com/sachncs/morel/blob/master/morel/eval/completion.py"
click node_experiment "https://github.com/sachncs/morel/blob/master/morel/app/experiment.py"
click node_api "https://github.com/sachncs/morel/blob/master/morel/serve/app.py"
click node_loader "https://github.com/sachncs/morel/blob/master/morel/serve/loader.py"
click node_auth "https://github.com/sachncs/morel/blob/master/morel/serve/auth.py"
click node_updater "https://github.com/sachncs/morel/blob/master/morel/serve/update.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_acquire,node_extract,node_build,node_mask,node_store toneBlue
class node_pipeline,node_retrieve,node_encode,node_route,node_codebook,node_complete,node_recommend toneAmber
class node_trainer,node_eval,node_experiment toneMint
class node_api,node_loader,node_auth,node_updater toneRose
class node_user toneIndigo
```

## Components

### Data lifecycle

- [Acquire data](https://github.com/sachncs/morel/blob/master/morel/data/acquire.py): `morel/data/acquire.py`
- [Extract data](https://github.com/sachncs/morel/blob/master/morel/data/extract.py): `morel/data/extract.py`
- [Build graphs](https://github.com/sachncs/morel/blob/master/morel/data/build.py): `morel/data/build.py`
- [Mask modalities](https://github.com/sachncs/morel/blob/master/morel/data/mask.py): `morel/data/mask.py`
- [Dataset store](https://github.com/sachncs/morel/blob/master/morel/data/store.py): `morel/data/store.py`

### GRE-MC model

- [GRE-MC pipeline](https://github.com/sachncs/morel/blob/master/morel/pipeline/composer.py): `morel/pipeline/composer.py`
- [Graph retrieval](https://github.com/sachncs/morel/blob/master/morel/retrieve/pipeline.py): `morel/retrieve/pipeline.py`
- [Feature encoding](https://github.com/sachncs/morel/blob/master/morel/encode/transformer.py): `morel/encode/transformer.py`
- [Codebook routing](https://github.com/sachncs/morel/blob/master/morel/route/router.py): `morel/route/router.py`
- [Modality codebook](https://github.com/sachncs/morel/blob/master/morel/codebook/codebook.py): `morel/codebook/codebook.py`
- [Completion decoder](https://github.com/sachncs/morel/blob/master/morel/complete/decoders.py): `morel/complete/decoders.py`
- [Item ranking](https://github.com/sachncs/morel/blob/master/morel/recommend/light.py): `morel/recommend/light.py`

### Training and evaluation

- [Model training](https://github.com/sachncs/morel/blob/master/morel/train/trainer.py): `morel/train/trainer.py`
- [Evaluation and ablations](https://github.com/sachncs/morel/blob/master/morel/eval/completion.py): `morel/eval/completion.py`
- [Experiment services](https://github.com/sachncs/morel/blob/master/morel/app/experiment.py): `morel/app/experiment.py`

### Inference service

- [Inference API](https://github.com/sachncs/morel/blob/master/morel/serve/app.py): `morel/serve/app.py`
- [Model loader](https://github.com/sachncs/morel/blob/master/morel/serve/loader.py): `morel/serve/loader.py`
- [Scoped authentication](https://github.com/sachncs/morel/blob/master/morel/serve/auth.py): `morel/serve/auth.py`
- [Model updates](https://github.com/sachncs/morel/blob/master/morel/serve/update.py): `morel/serve/update.py`

### Other components

- **Researcher or caller**

## Connections

- Researcher or caller → Acquire data: starts data lifecycle
- Researcher or caller → GRE-MC pipeline: provides features and graph
- GRE-MC pipeline → Graph retrieval: retrieves context
- GRE-MC pipeline → Feature encoding: encodes features
- GRE-MC pipeline → Codebook routing: routes representations
- GRE-MC pipeline → Modality codebook: uses codebook
- GRE-MC pipeline → Completion decoder: completes modalities
- Researcher or caller → Item ranking: requests ranking
- Researcher or caller → Model training: starts training
- Model training → GRE-MC pipeline: trains model
- Researcher or caller → Evaluation and ablations: requests evaluation
- Researcher or caller → Experiment services: runs experiment
- Researcher or caller → Inference API: sends request
- Inference API → Scoped authentication: checks scope
- Inference API → Model loader: loads pipeline
- Inference API → Model updates: dispatches updates
- Model loader → GRE-MC pipeline: provides model
- Acquire data → Extract data: extracts archive
- Extract data → Build graphs: prepares inputs
- Build graphs → Mask modalities: supports masking
- Build graphs → Dataset store: stores dataset