Enhancements & Next Steps Advanced

class RealTimeRecommender:
    """Wraps a base recommender with real-time signal boosting."""

    def __init__(self, base_model, session_weight=0.3):
        self.base = base_model
        self.session_weight = session_weight
        self.session_actions = {}  # user_id -> list of recent actions

    def log_action(self, user_id, item_id, action_type="click"):
        """Record a user action for real-time boosting."""
        if user_id not in self.session_actions:
            self.session_actions[user_id] = []
        self.session_actions[user_id].append({
            "item_id": item_id,
            "action": action_type,
            "timestamp": time.time()
        })

    def recommend(self, user_idx, n=10):
        """Get recommendations with real-time session boosting."""
        # Get base recommendations
        base_recs = self.base.recommend(user_idx, n=n * 2)
        base_scores = {idx: score for idx, score in base_recs}

        # Boost items similar to recent session activity
        session = self.session_actions.get(user_idx, [])
        if session:
            recent_items = [a["item_id"] for a in session[-5:]]
            for item_idx, score in base_scores.items():
                # Boost score if item is similar to recent actions
                similarity_boost = self._compute_session_boost(
                    item_idx, recent_items
                )
                base_scores[item_idx] = (
                    (1 - self.session_weight) * score +
                    self.session_weight * similarity_boost
                )

        sorted_recs = sorted(
            base_scores.items(), key=lambda x: x[1], reverse=True
        )
        return sorted_recs[:n]

    def _compute_session_boost(self, item_idx, recent_items):
        """Compute similarity between candidate item and recent session."""
        if hasattr(self.base, "item_sim"):
            sims = [self.base.item_sim[item_idx, r] for r in recent_items]
            return np.mean(sims) if sims else 0
        return 0

def mmr_rerank(candidates, item_sim_matrix, lambda_param=0.5, n=10):
    """Maximal Marginal Relevance (MMR) for diversity-aware re-ranking.

    MMR = lambda * relevance(item) - (1-lambda) * max_similarity(item, selected)

    Higher lambda = more relevance, lower lambda = more diversity.

    Args:
        candidates: list of (item_idx, relevance_score)
        item_sim_matrix: item-item similarity matrix
        lambda_param: trade-off between relevance and diversity
        n: number of items to return
    """
    selected = []
    remaining = list(candidates)

    while len(selected) < n and remaining:
        best_score = -float("inf")
        best_idx = 0

        for i, (item, rel_score) in enumerate(remaining):
            # Relevance term
            relevance = lambda_param * rel_score

            # Diversity term (max similarity to already selected items)
            if selected:
                max_sim = max(
                    item_sim_matrix[item, s_item]
                    for s_item, _ in selected
                )
            else:
                max_sim = 0

            diversity = (1 - lambda_param) * (-max_sim)
            mmr_score = relevance + diversity

            if mmr_score > best_score:
                best_score = mmr_score
                best_idx = i

        selected.append(remaining.pop(best_idx))

    return selected

def popularity_fallback(train_df, n=10):
    """Return the most popular items as a cold-start fallback."""
    # Popularity = weighted combination of rating count and average rating
    stats = train_df.groupby("item_id").agg(
        count=("rating", "count"),
        mean=("rating", "mean")
    ).reset_index()

    # Bayesian average (shrinkage toward global mean)
    C = stats["count"].mean()  # Average number of ratings
    m = stats["mean"].mean()    # Global mean rating

    stats["score"] = (
        (stats["count"] * stats["mean"] + C * m) /
        (stats["count"] + C)
    )

    top_items = stats.nlargest(n, "score")
    return list(zip(top_items["item_id"], top_items["score"]))