> ## Documentation Index
> Fetch the complete documentation index at: https://ihub.learnille.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Personalization Signals for "For You" Recommendations

> Migrated from the previous Learnille internal documentation hub

## Purpose

This document outlines how we personalize the "For You" recommendations for each user. We use a weighted signal system that learns from user behavior to surface the most relevant courses and consultations.

## How It Works

Instead of calculating personalization on every request, we:

1. **Pre-compute** a user interest profile (embedding) from their activity
2. **Store** this profile and update it when behavior changes
3. **Match** the user profile against product profiles using vector similarity
4. **Serve** personalized recommendations instantly

This approach is efficient - we only recalculate when the user's preferences actually change.

## Signal Categories

### Strong Intent Signals (Highest Impact)

These indicate direct purchase or learning intent:

| Signal | Weight | Description |
| - | - | - |
| **Wishlist Items** | 5.0 | Products the user explicitly saved for later |
| **Cart Items** | 4.0 | Products added to cart (even if abandoned) |
| **Enrolled Products** | 3.0 | Categories the user has already invested in |

### Explicit Preferences (User-Declared)

What users tell us about themselves:

| Signal | Weight | Source |
| - | - | - |
| **Primary Interest Category** | 3.0 | Student profile setup |
| **Other Interests** | 2.0 | Secondary interests in profile |
| **Learning Objectives** | 2.0 | Goals stated in profile |

### Behavioral Signals (Implicit)

What we learn from user actions:

| Signal | Weight | Notes |
| - | - | - |
| **Recent Views** | 2.0 | Products viewed in last 7-30 days (decays over time) |
| **Search Queries** | 1.5 | Keywords and categories from search history |
| **High Ratings** | 1.5 | Products rated 4-5 stars by the user |
| **Engagement Time** | 1.0 | Categories where user spends the most time |

### Negative Signals (Exclusions)

What we avoid recommending:

| Signal | Effect | Rationale |
| - | - | - |
| **Already Enrolled** | Excluded | Never recommend what they already have |
| **Low Ratings (1-2 stars)** | Deprioritized | User showed dissatisfaction with similar content |

## When Recommendations Update

We recalculate a user's profile when their preferences change:

| Event | Update Timing | Why |
| - | - | - |
| User enrolls in course/consultation | Immediate | Strong signal - they paid for it |
| User adds to wishlist | Within 1 minute | Shows clear interest |
| User removes from wishlist | Within 1 minute | Preferences changed |
| User adds to cart | Within 5 minutes | Purchase intent (might checkout) |
| User gives 4-5 star review | Immediate | Positive affinity |
| User gives 1-2 star review | Immediate | Negative signal to incorporate |
| User updates profile interests | Immediate | Explicit preference change |

## Cold Start (New Users)

For users without activity history:

1. Use their **Primary Interest Category** from profile setup
2. If no profile yet → show **Trending/Popular** content
3. Build personalized recommendations after first interactions

## Data Sources

| Data | Where It Lives | What We Use |
| - | - | - |
| Wishlist | `wishlist` table | Product IDs, timestamps |
| Cart | `cart_items` table | Product IDs |
| Enrollments | `enrollment` table | Course/consultation IDs, categories |
| Views | `impression` table | Entity IDs, view counts, recency |
| Reviews | `review` table | Ratings, product associations |
| Profile | `student` table | Interest category, objectives, skills |
| Search | OpenSearch logs | Query terms, filters used |

## Key Decisions

* **Event-driven updates only**: We don't recalculate on a schedule. If a user hasn't interacted, their preferences haven't changed.
* **Weighted averaging**: Stronger signals (wishlist, cart) influence recommendations more than weak signals (views).
* **Recency matters**: Recent views weighted higher than old ones (decay function).
* **Negative signals excluded**: We never recommend already-purchased items.

## Success Metrics

* Click-through rate on "For You" section
* Conversion rate from recommendations
* Wishlist additions from recommendations
* User engagement with personalized vs non-personalized content

## Technical Implementation

See: `docs/flows/` for integration details (if created)

**Key files:**

* `server/src/recommendation/services/user-embedding.service.ts` - Signal collection and embedding calculation
* `server/src/recommendation/listeners/user-embedding.listener.ts` - Event handlers for updates
* `server/src/recommendation/processors/user-embedding.processor.ts` - Background job processing

## Last Updated

2025-01-27


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.