GMF Core: an open-source recommendation and decisioning engine for marketplaces

Muhail01 — Wed, 22 Jul 2026 20:25:47 +0000

While building GILLZY, a digital goods marketplace, I ended up working on a problem that appears in almost every sufficiently large marketplace:

How do you turn behavioral events and catalog candidates into explainable, safe, and reproducible recommendation decisions?

At first, recommendation logic tends to be simple.

Fetch some products.

Calculate a score.

Sort them.

Return the top N.

But as a marketplace grows, the pipeline quickly becomes more complicated:

multiple candidate sources;
feature signals;
deterministic ranking;
model-assisted scoring;
diversity constraints;
business and safety guardrails;
exploration;
fallbacks;
telemetry attribution;
explainability;
experimentation.

The problem is that these systems often become tightly coupled to one product and one private database schema.

So I extracted the reusable parts into an independent Apache-2.0 open-source project:

GMF Core

GMF Core is an open-source recommendation, ranking, telemetry, and decisioning engine designed for marketplaces and discovery products.

GitHub:

https://github.com/Muhail01/GMF-Core

Current release: v0.1.0

The pipeline

Event Ingest
    ↓
Candidate Providers
    ↓
Feature Signals
    ↓
Deterministic Baseline Ranking
    ↓
Optional Model Scoring
    ↓
Diversity Rerank
    ↓
Policy / Guardrails
    ↓
Controlled Exploration
    ↓
Explainable Decision
    ↓
Decision Log + Transactional Outbox
    ↓
Impression / Click / Outcome Telemetry

The core idea is that a recommendation should not be treated as just a sorted list.

It is a decision.

**Every response gets a stable decision_id,** which allows downstream impression, click, and outcome events to be connected back to the exact decision that produced the result.

What is included in v0.1.0

The current release already includes:

standalone Go API;
pluggable candidate providers;
deterministic weighted ranking;
stable tie-breaking;
optional model-assisted scoring;
deterministic model rollout;
automatic fallback to baseline ranking;
diversity-aware reranking;
policy and guardrails;
controlled exploration;
explainable score breakdowns;
persisted decision lookup;
PostgreSQL storage;
in-memory storage;
transactional outbox;
reference outbox worker;
idempotent telemetry ingestion;
TypeScript telemetry SDK;
OpenAPI 3.1;
Docker Compose;
property and fuzz tests;
benchmarks;
privacy-safe observability hooks;
automated CI and public-boundary checks.

**The project intentionally does not contain private marketplace data**, production ranking coefficients, fraud logic, payment systems, KYC, paid advertising billing, credentials, or proprietary model configuration.

The public core is vendor-neutral.

Run the full stack

The reference stack includes GMF Core, PostgreSQL, and the outbox worker.

git clone https://github.com/Muhail01/GMF-Core.git
cd GMF-Core

docker compose up --build

Check that the API is alive:

curl -s http://localhost:8080/healthz

Request recommendations:

curl -s -X POST http://localhost:8080/v1/recommendations \
  -H 'Content-Type: application/json' \
  -d '{
    "surface":"home",
    "session_id":"demo-session",
    "limit":4,
    "context":{"category":"games"}
  }'

The response contains a decision_id, ranked items, scores, reason codes, and score breakdowns.

You can then retrieve the persisted decision:

curl -s http://localhost:8080/v1/decisions/<decision-id>

And send telemetry linked to that exact decision:

curl -s -X POST http://localhost:8080/v1/events \
  -H 'Content-Type: application/json' \
  -d '{
    "event_id":"evt-1",
    "event_type":"recommendation_impression",
    "session_id":"demo-session",
    "decision_id":"<decision-id>",
    "item_id":"game-1",
    "surface":"home"
  }'

This gives you a full chain:

**recommendation request**
→ decision
→ ranked items
→ score breakdown
→ persisted decision
→ impression
→ click
→ outcome
Why deterministic ranking still matters

One design decision I wanted to preserve is that the system must remain useful even without an external model.

The baseline ranking path is deterministic.

Optional model scoring can be enabled on top of it, but model failure does not make the recommendation system unavailable.

The intended behavior is:

baseline ranking
        ↓
optional model scorer
        ↓
model available? ── yes → hybrid result
        │
        no
        ↓
safe baseline fallback

This makes it possible to experiment with learned ranking without turning the model provider into a single point of failure.

Explainability

Each returned item can include a score breakdown and reason code.

Instead of returning only:

item A
item B
item C

the system can preserve information about why those items were selected and how the final ranking was produced.

That becomes useful for:

debugging;
experiments;
model comparison;
ranking regressions;
policy analysis;
telemetry attribution.
Transactional outbox

**Decisions and telemetry** events can be persisted together with outbox messages.

The reference worker is intentionally provider-neutral.

A deployment can connect it to systems such as:

Kafka;
NATS;
webhooks;
queues;
analytical pipelines.

The core itself does not require one specific messaging vendor.

What I am looking for now

The project is still early, and I would especially appreciate technical feedback on:

the decision pipeline;
API boundaries;
ranking and reranking abstractions;
model fallback semantics;
feature-store integration;
telemetry contracts;
transactional outbox design;
observability.

I have also opened contribution-sized issues for things such as:

Go client SDK;
Python SDK;
React telemetry hooks;
Redis decision cache;
Prometheus integration;
OpenTelemetry integration;
Kafka outbox sink;
NATS outbox sink;
ClickHouse telemetry storage;
feature-store provider interface;
benchmark documentation.

Some are intentionally marked as good first issue so that contributors do not need to understand an entire marketplace codebase before making a useful first contribution.

Repository

⭐ GMF Core:

https://github.com/Muhail01/GMF-Core




**The project is licensed under Apache-2.0.**

I am particularly interested in criticism from people who have worked on recommendation systems, ranking infrastructure, marketplaces, experimentation platforms, or large-scale telemetry systems.

What would you change in this architecture before building a v0.2?

DEV Community: Muhail01

GMF Core: an open-source recommendation and decisioning engine for marketplaces

GMF Core

The pipeline