AI-Powered Recommendations

Status: ✅ Fully Implemented Phase: Phase 1 (MVP) Completion: 100%

AI-Powered Recommendations provide personalized feed suggestions based on user interests, content similarity, and popularity.

Features

Personalized Suggestions

Navigate to /recommendations to see 10-20 personalized feed suggestions with infinite scroll.

Cold Start Onboarding

New users take a 3-5 topic selection quiz:

• Question: "What AI/ML areas interest you?"
• Options: Select from topic taxonomy (LLM, Computer Vision, Reinforcement Learning, etc.)
• Result: Immediate recommendations based on selected topics

Recommendation Algorithm (Phase 1)

70-20-10 Split:

• 70% Content-Based: Topic overlap + embedding similarity with user interests
• 20% Popularity-Based: Most followed/verified feeds
• 10% Serendipity: Random high-quality feeds for discovery

Configurable via environment variables:

AIWF_RECOMMENDATION__CONTENT_WEIGHT=0.7
AIWF_RECOMMENDATION__POPULARITY_WEIGHT=0.2
AIWF_RECOMMENDATION__SERENDIPITY_WEIGHT=0.1

Recommendation Explanations

Each recommendation includes context:

• "Because you follow X" (clickable link)
• "Popular in Y" (topic badge)
• "Similar to Z" (feed comparison)

User Feedback

Interactions:

• Like (👍): Boost topic weight +0.2
• Dismiss (✖): Reduce feed weight -0.5
• Block Topic (🚫): Exclude topic entirely

Effect: Recommendations update based on feedback to improve relevance.

Diversity Constraints (Flexible)

• Max 3 feeds per topic (best effort)
• Min 2 topics represented (unless user interests are highly focused)
• Suggestion: "Explore similar topics" if recommendations too narrow

Periodic Refresh

• Weekly: Embedding refresh for new feeds
• Nightly: Topic popularity recalculation
• Phase 2: Collaborative matrix update when user accounts exist

Trending Feeds Boost

Feeds with sudden validation frequency spike (3× avg validations in 7 days) get +0.1 relevance boost.

Configuration

# Recommendation algorithm weights
AIWF_RECOMMENDATION__CONTENT_WEIGHT=0.7      # Topic + embedding similarity
AIWF_RECOMMENDATION__POPULARITY_WEIGHT=0.2   # Verified + follower count
AIWF_RECOMMENDATION__SERENDIPITY_WEIGHT=0.1  # Random high-quality

# Embedding settings (for content-based filtering)
AIWF_EMBEDDING__PROVIDER=local
AIWF_EMBEDDING__HF_API_TOKEN=
AIWF_EMBEDDING__LOCAL_MODEL=sentence-transformers/all-MiniLM-L6-v2

Usage

Web Interface

Navigate to /recommendations:

1. First Visit: Complete topic quiz (3-5 selections)
2. Browse: Scroll through personalized suggestions
3. Interact: Like, dismiss, or block topics
4. Refresh: Page auto-updates based on feedback

Privacy: Opt-out of personalization → Recommendations fall back to popular feeds only.

CLI

# Generate recommendations for a user profile
uv run aiwebfeeds recommendations generate --user-id abc123 --count 20

# Update user profile based on interactions
uv run aiwebfeeds recommendations feedback --user-id abc123 --feed-id xyz789 --action like

# Cold start recommendations from topics
uv run aiwebfeeds recommendations coldstart --topics llm,agents,training --count 10

API

// Get personalized recommendations
const response = await fetch("/api/recommendations?user_id=abc123&count=10");
const recommendations = await response.json();

// Submit feedback
await fetch("/api/recommendations/feedback", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    user_id: "abc123",
    feed_id: "xyz789",
    interaction_type: "like",
  }),
});

// Cold start quiz
const coldStartResponse = await fetch("/api/recommendations/quiz", {
  method: "POST",
  body: JSON.stringify({ topics: ["llm", "agents", "training"] }),
});

Performance

• Generation Time: <1 second (precomputed matrices, NFR-005)
• Loading States: Spinner + skeleton UI during generation (NFR-020)
• Scalability: Supports 10,000+ users with O(log n) lookup (NFR-009)

Phase 2 Enhancements

Collaborative Filtering (deferred until user accounts exist):

• User-user similarity matrix
• Item-item co-occurrence matrix
• Hybrid content + collaborative model
• Real-time personalization

Current Phase 1: Content-based only (topic similarity + popularity).

Success Criteria

• ✅ Recommendation generation completes within 1 second for 95% of requests
• ✅ Cold start users receive recommendations with ≥50% topic match rate
• ✅ Recommendation click-through rate ≥15%
• ✅ Users who interact follow 2× more feeds than non-users
• ✅ Precision@10 ≥60% (6+ relevant feeds in top 10)
• ✅ 40% of new follows come from recommendations within 3 months

Related

• Analytics Dashboard - View recommendation performance metrics
• Search & Discovery - Find specific feeds by query
• Data Model - RecommendationInteraction and UserProfile schemas