Logic & algorithms
Recommendation logics and algorithm deep dives.
05 - Logic types & algorithms
Related: ML models · Worked examples
Search algorithms are omitted from this pack.
Matrix
| Logic | Intent | Required inputs | Default algorithm | Also available |
|---|---|---|---|---|
user-to-item | Personalized “for you” | userId | weighted-history | elsa-cf, realm-sequential |
item-to-item | Related to one product | itemId | co-occurrence | elsa-cf |
items-to-items | Related to a set (cart) | itemIds[] | multi-seed-co-occurrence | multi-seed-hybrid |
similar-products | Content/vector similarity | itemId | vector-similarity | beeformer-multimodal |
recently-viewed | Recency of views | userId | recency | - |
1. user-to-item → weighted-history (default)
Idea
Rank items the user already engaged with by weighted interaction strength, then fill with popular items if needed.
Score
total_weight(item) = Σ event.weight × type_multiplier(type)
window = last 30 days
type_multiplier: purchase=4, rating=3, cart=2, else 1
Over-fetch count × 4. If still short, append 7-day popular items (by count) with score 0.5 when no personal weight.
Flow
Tweaks
- Scenario filter/boosters/constraints as usual.
- Event quality & identity merge dominate accuracy.
- Type multipliers are code constants (not Admin fields).
2. item-to-item → co-occurrence (default)
Idea
“Users who interacted with seed also interacted with …”
Score
co_count = number of user co-interactions between seed and candidate in 30 days (self-join on user_id).
Fallback: same category catalog items with score 0.5.
Flow
Example
If 40 users touched both seed S and item R in 30d, R scores 40 (before boosters).
Tweaks
- Needs enough overlapping users; sparse catalogs rely on category fallback.
- Pass
userIdto enable purchase cap.
3. items-to-items → multi-seed-co-occurrence (default)
Idea
Aggregate co-occurrence across multiple seeds (cart). Candidates matching a seed category get a ×2 category boost (legacy hardcoded).
Score (simplified)
base = aggregated co_count across seeds
score = base × (2 if category matches any seed else 1)
Fallback: same-category catalog fill.
Tweaks
- Prefer this for classic cart rails.
- For vector+co fusion, switch algorithm to
multi-seed-hybrid.
4. items-to-items → multi-seed-hybrid
Idea
Fuse collaborative (multi-seed co-occurrence) and vector (Qdrant) ranked lists with RRF, with strategies:
| Strategy | Behavior |
|---|---|
rrf | Per-seed fan-out + RRF fuse |
centroid | Average seed vectors → one Qdrant query (good when cart is homogeneous) |
adaptive | Homogeneity ratio unique(seed categories)/seedCount; ≤0.5 → centroid, else RRF fan-out |
RRF contribution per list:
score(id) += 1 / (rrfK + rank_index + 1)
Typical rrfK ≈ 60 (configurable). Missing legs degrade gracefully (union of available lists).
Key hybridSettings
| Knob | Role |
|---|---|
enabled | If false → fall back to multi-seed-co-occurrence |
strategy | rrf / centroid / adaptive |
rrfK, coTopK, vectorTopK | Fusion / fan-out sizes |
minCoSupport | Min distinct seeds that must support a candidate |
categoryBoost | Multiplier for category match (hybrid path) |
qdrantSettings | Vector engine tuning (threshold, ef, …) |
V1 fusion mode is RRF (weighted fusion reserved).
5. similar-products → vector-similarity (default)
Idea
Nearest neighbors of the seed’s embedding in Qdrant.
Score
Qdrant similarity score (higher = closer). Settings from tenant defaults + scenario qdrantSettings:
| Knob | Role |
|---|---|
score_threshold | Drop weak neighbors |
hnsw_ef | Search quality vs latency |
filter_categories | Restrict neighbor categories |
quantization_rescore / oversampling | Quantized index behavior |
Flow
Tweaks
- Embedding template / reindex quality dominates.
- Raise threshold → fewer but “stronger” neighbors; may trigger minItems auto-relax.
6. recently-viewed → recency
Idea
Items the user viewed in 30d, ordered by most recent view time.
Notes
- Uses
type = 'view'only for ordering source. - Still runs through scenario post-process when a scenario is attached.
7. ML algorithms (summary - details in ch.06)
| Algorithm | Logics | Online scoring |
|---|---|---|
elsa-cf | user-to-item, item-to-item | Dot product of user↔item or item↔item factors; fallback to weighted-history / co-occurrence if factors missing |
realm-sequential | user-to-item | Session/sequence-aware next-item from GRU factors; fallback weighted-history |
beeformer-multimodal | similar-products | NN in Qdrant using beeFormer embeddings |
Choosing logic for a placement
Driffle PDP similar rail uses similar-products + scenario pdp-similar-products (vector path).