GRE-MC architecture · API v0.1

Complete missing modalities, then rank with graph context.

morel is an open-source Python library that completes missing item modalities from graph context, then ranks with LightGCN. Build a paper-faithful, deterministic pipeline you can benchmark, inspect, and self-host.

Get started View on GitHubstar

Graph retrieval
Modality completion
Paper-faithful
Serving foundation

Python 3.10+MIT licensearxiv 2605.00670659 tests · 84.57% coverage · verified 2026-10-15

Built on the shoulders of

sentence-transformers
PyTorch
FastAPI
Prometheus
Astro
Ruff
mypy
Docker

Product overview

One library, one pipeline, one recommender.

morel consolidates retrieval, completion, and ranking into a single, configurable Python package. You get research-grade fidelity without giving up the engineering surface you need to ship.

Four retrieval strategies

BFS, anchor, ACS, and MAGE. Pick the trade-off between recall and latency that fits your corpus.

Unified pipeline

One entry point — `morel.Pipeline` — drives retrieval, completion, and ranking. Configurable, swappable, observable.

CPU & GPU

Runs end-to-end on CPU for moderate corpora. CUDA acceleration kicks in automatically when available.

Fidelity-first

Every algorithm ties to a paper equation. The FIDELITY.json report makes the math auditable.

Read the documentation

What's inside

Everything you'd build, composed for you.

Each module is independently usable and tested. Together they form a coherent pipeline that you can read top-to-bottom.

Modality completion

VQ and Gumbel-VQ codebooks reconstruct missing modalities directly from graph context — no imputation hacks, no side features.

VQ · Gumbel-VQ
Usage + balance losses
Deterministic seeds

Graph retrieval

BFS, anchor, ACS, and MAGE retrieval over the item co-occurrence graph. Pick the strategy that fits your latency budget.

Four strategies
Per-modality top-K
Budgeted expansion

Paper-faithful

Every algorithm ties to a paper equation. The build emits a machine-rendered fidelity report — every implementation choice is auditable.

FIDELITY.json
Equation registry
Regression tests

Serving foundation

FastAPI inference server with token auth, Prometheus metrics, and a cached model loader. Same code in dev and in prod.

FastAPI · Uvicorn
Prometheus
Docker · Compose

Reproducible by default

Deterministic seeding, machine-rendered manifests, benchmark fixtures, and automated quality gates.

Seeded RNG
Manifests per run
CI benchmarks

Composable config

A frozen dataclass tree, overridable field by field. Defaults that match the paper; overrides that don't surprise you.

Frozen dataclasses
YAML + env
Strict types

From zero to ranked

Five lines to a trained recommender.

The public API is small by design. Build the graph, attach the corpus, run the pipeline, rank — same surface, same types, same code from notebook to production.

01
Build the graph
Stream interactions into a CSR matrix. Compute item co-occurrence on demand.
02
Mask the modalities
Bernoulli, structured, or custom masking — pluggable in one call.
03
Run the pipeline
One Pipeline call returns completed embeddings and routing weights.
04
Rank with LightGCN
BPR-trained ranker returns top-K. Same head serves in dev and in prod.

Run the demo API reference

pipeline.py

import torch
from morel import Config, Pipeline
from morel.data import bipartite, cooccurrence, bernoulli
from morel.recommend import Light

# 1. Build the bipartite user-item interaction graph.
ui = bipartite(users, items, interactions)

# 2. Build the item co-occurrence graph and a 40% modality mask.
adjacency = cooccurrence(ui)
mask = bernoulli(items, modalities=2, ratio=0.4, seed=42)

# 3. Attach your corpus and run the GRE-MC pipeline.
pipeline = Pipeline(Config.defaults(), dims={"visual": 16, "text": 8})
pipeline.attach(features, mask, adjacency)

output = pipeline(features, mask, adjacency, training=False)

# 4. Rank with the LightGCN-style head.
scores = Light(users=20, items=50, embed=32, layers=2)(
    torch.arange(20), torch.arange(50), ui
)
print(scores.shape)  # (20, 50)

Same code runs in a notebook, in a script, and inside the FastAPI server.

Performance

Numbers that don't move on you.

The repository ships reproducible benchmark fixtures for forward passes, retrieval, dataset construction, and training. Run them locally on representative hardware before setting a latency budget.

Tests passing

659

Code coverage

84.57%

Retrieval strategies

Codebook entries

100

Recall@10

Measure locally

Compare against a LightGCN baseline on your catalog.

NDCG@10

Measure locally

Report the masking policy, split, and dataset version.

Run the suite yourself — pytest benchmarks/ --benchmark-only --no-cov(last verified 2026-10-15)

Benchmark methodology Readiness evidence

Ship in five minutes

From pip install to ranked recommendations.

Clone the repo, install the dev extras, and run the demo on synthetic data. The same code path scales to real catalogs and to production inference.

Get started View on GitHub

morel — quickstart⌘

# 1. Get the code
git clone https://github.com/sachncs/morel
cd morel

# 2. Sandbox it
python3 -m venv .venv
source .venv/bin/activate

# 3. Install
pip install -e ".[dev]"

# 4. Run the demo
python examples/demo.py

Architecture

The pipeline, end to end.

From raw interactions to ranked recommendations in four composable stages. Click through to see what each one does.

Stage 01

Bipartite interactions

Stream user–item interactions into a CSR matrix. Bernoulli mask the modality slots you want to stress-test.

morel data mask

Where it fits

One pipeline, many catalogs.

morel is domain-agnostic by design. Wherever you have a user–item graph with incomplete features, you have a place for it.

E-commerce

Finish the catalog before ranking.

Long-tail SKUs rarely have clean visual or textual features. morel completes them from co-occurrence so the ranker never sees a hole.

Sparse-catalog evaluation

Measure

Streaming & media

Recommendations that don't break on cold assets.

When a poster or synopsis is missing, the graph context fills it in. The LightGCN head ranks against a complete embedding.

Cold-start evaluation

Measure

Marketplaces

One pipeline, many modalities.

Text, image, audio — morel treats them uniformly through per-modality anchors and a shared completion codebook.

Modalities handled per pipeline

Configurable

FAQ

Questions, answered.

morel is an open-source Python library with research-grade fidelity. Every algorithm ties to a paper equation, and the codebase ships with a fidelity report, regression tests, and automated quality gates. The same code runs in notebooks and self-hosted deployments.

No. morel runs end-to-end on CPU for moderate corpora. For larger corpora or faster training, a CUDA-enabled PyTorch install unlocks GPU acceleration automatically; benchmark your own catalog before setting a capacity target.

morel layers graph retrieval and modality completion ahead of LightGCN. The repository includes benchmark fixtures so you can measure the effect on your own corpus; results depend on the graph, modalities, masking policy, and training configuration.

MIT. Use it in commercial products, modify it, ship it. Attribution is appreciated but not required.

Yes. morel exposes a thin encoder interface; swap in any model that returns an L2-normalized tensor. The default encoder wraps sentence-transformers and a torchvision backbone.