RecomNext | Recommendation as a Service

Scenarios

A scenario is a named placement (slug) that bundles logic type, algorithm, nextQL filters and boosters, constraints, segmentation, and optional rule references. Fetch recommendations with the scenario slug to apply the full config at request time.

Prerequisites

Logic types (use cases)

Setting	Type	Default	Description
user-to-item	logicType	—	Homepage “For you”, personalized rails. Requires userId.
item-to-item	logicType	—	PDP related (co-occurrence). Requires itemId.
similar-products	logicType	—	Vector similarity on PDP. Requires itemId + embeddings.
items-to-items	logicType	—	Cart upsell from multiple seeds. Requires itemIds.
recently-viewed	logicType	—	Continue browsing. Requires userId.

Algorithm registry

algorithm selects the scoring implementation. If omitted, the default for the logic type is used. Response includes algorithm for debugging and A/B analysis.

Setting	Type	Default	Description
weighted-history	user-to-item	default	30d weighted interactions + popularity fallback.
co-occurrence	item-to-item	default	Co-interaction matrix + category fallback.
vector-similarity	similar-products	default	Qdrant nearest neighbors.
multi-seed-co-occurrence	items-to-items	default	Cart co-occurrence across seeds.
multi-seed-hybrid	items-to-items	—	RRF fusion of co-occurrence + vectors.
elsa-cf	user-to-item, item-to-item	—	Requires offline trained factors.
realm-sequential	user-to-item	—	Session sequential model (offline).
beeformer-multimodal	similar-products	—	Text + image embeddings (offline).

List options: GET /recommendations/algorithms andGET /recommendations/algorithms/:logicType.

Scenario settings

Setting	Type	Default	Description
slug	string	—	Stable URL-safe ID used in API and tracking.
filter	nextQL	—	Hard filter applied to candidates.
boosters	string[]	—	Score multipliers: boost by N where condition.
rulesSlugs	string[]	—	Reusable rules merged before scenario filter.
segmentationId	string	—	Diversity balancing config.
itemsPerSegment	number	—	Max items per segment in results.
minItems / maxItems	number	6 / 12	Auto-fill and cap on count.
autoRelaxConstraints	boolean	true	Relax diversity when below minItems.
autoExpandSegments	boolean	true	Increase per-segment slots when below minItems.

Constraints

Setting	Type	Default	Description
maxPerCategory	number	—	Diversity cap per category in result set.
injectLongTail	boolean	false	Inject low-exposure items.
longTailPercentage	0–100	10	Share of slots for long-tail when injectLongTail true.
freshnessBoostDays	number	—	Boost items within N days of freshness date.
purchasedItemsMaxPercent	0–100	10	Cap already-purchased items; pass userId at fetch.

Use case

Homepage diversity

maxPerCategory: 2 with segmentation by genre prevents one genre dominating the carousel.

Use case

Cart — hide already purchased

Pass userId on cart upsell fetch with purchasedItemsMaxPercent: 5.

Vector tuning (qdrantSettings)

Used by vector-similarity and hybrid algorithms.

Setting	Type	Default	Description
score_threshold	number	—	Minimum similarity score for candidates.
hnsw_ef	number	—	Search accuracy vs latency tradeoff.
filter_categories	string[]	—	Restrict vector search to categories.
exact	boolean	—	Exact search mode (slower, more accurate).

Hybrid tuning (hybridSettings)

For multi-seed-hybrid on cart-style placements.

Setting	Type	Default	Description
strategy	rrf \| centroid \| adaptive	rrf	How multiple seeds fuse.
rrfK	number	—	RRF smoothing constant.
coTopK / vectorTopK	number	—	Candidate pool sizes per signal.
categoryBoost	number	—	Multiplier when candidate category matches a seed.
minCoSupport	number	—	Minimum seed support for co-occurrence candidates.
enabled	boolean	—	Scenario-level hybrid kill switch.

Processing order

Algorithm candidates → rule filters → scenario filter → rule + scenario boosters → constraints → segment balancing → min/max auto-fill.

Per-request filter overrides are not supported on the unified API — tune via scenarios, rules, or multiple scenarios for preset filter combinations.

Full scenario example

POST /scenarios
{
  "name": "PDP — Similar PC games",
  "slug": "pdp-similar-pc",
  "logicType": "similar-products",
  "algorithm": "vector-similarity",
  "filter": "'stock' > 0 and 'platform' in ['pc', 'multi']",
  "boosters": [
    "boost by 1.4 where 'featured' = true",
    "boost by 1.2 where 'genre' in ['rpg', 'action']"
  ],
  "constraints": {
    "maxPerCategory": 2,
    "injectLongTail": true,
    "longTailPercentage": 15,
    "freshnessBoostDays": 14,
    "purchasedItemsMaxPercent": 10
  },
  "qdrantSettings": {
    "score_threshold": 0.35
  },
  "segmentationId": "by-genre",
  "itemsPerSegment": 1,
  "minItems": 6,
  "maxItems": 12,
  "rulesSlugs": ["in-stock"],
  "autoRelaxConstraints": true,
  "autoExpandSegments": true
}

Experiments

Attach an A/B experiment to a scenario: variants point to different scenario slugs (e.g. control vs boosted). Assignment uses userId at fetch time. See Analytics and experiments.