APiGen Recommendation

ML-based recommendation engine module for APiGen applications.

Purpose

Provides a complete recommendation system with collaborative filtering, content-based filtering, hybrid algorithms, A/B testing, and ML model training infrastructure.

Features

Recommendation Algorithms

• Collaborative Filtering
  • User-based collaborative filtering
  • Item-based collaborative filtering
  • Matrix factorization (SVD/ALS)
  • Popularity-based (cold start fallback)
• Content-Based Filtering
  • Feature-based similarity
  • TF-IDF text content filtering
• Hybrid Algorithms
  • Weighted hybrid (combines multiple algorithms)
  • Switching hybrid (selects algorithm based on user profile)
  • Cascade hybrid (refines results through multiple stages)

Similarity Metrics

• Cosine similarity
• Pearson correlation
• Jaccard similarity

A/B Testing Framework

• Experiment creation and management
• Variant traffic allocation
• User bucketing (deterministic assignment)
• Statistical analysis (CTR, conversion rate, revenue per user)
• Real-time metrics tracking

ML Model Training

• Training data provider
• Model versioning and storage
• Async training pipeline
• Event-driven architecture

Caching

• Caffeine-based caching
• Per-user cache invalidation
• Configurable TTL

Usage

Gradle:

dependencies {
    implementation 'com.jnzader:apigen-recommendation:1.0.0-SNAPSHOT'
}

Maven:

<dependency>
    <groupId>com.jnzader</groupId>
    <artifactId>apigen-recommendation</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

Recommendation Endpoints

Method	Endpoint	Description
POST	/api/v1/recommendations	Get personalized recommendations
GET	/api/v1/recommendations/user/{userId}	Get recommendations for user
POST	/api/v1/recommendations/async	Get recommendations asynchronously
POST	/api/v1/recommendations/similar-items	Find similar items
GET	/api/v1/recommendations/similar-items/{itemId}	Find similar items (GET)
POST	/api/v1/recommendations/clicks	Record recommendation click
POST	/api/v1/recommendations/conversions	Record conversion
GET	/api/v1/recommendations/statistics	Get performance statistics
POST	/api/v1/recommendations/cache/invalidate/user/{userId}	Invalidate user cache
POST	/api/v1/recommendations/cache/invalidate	Invalidate all caches

Experiment Endpoints

Method	Endpoint	Description
POST	/api/v1/experiments	Create experiment
GET	/api/v1/experiments/running	Get running experiments
GET	/api/v1/experiments/{experimentId}	Get experiment by ID
GET	/api/v1/experiments/name/{name}	Get experiment by name
POST	/api/v1/experiments/{experimentId}/start	Start experiment
POST	/api/v1/experiments/{experimentId}/pause	Pause experiment
POST	/api/v1/experiments/{experimentId}/resume	Resume experiment
POST	/api/v1/experiments/{experimentId}/stop	Stop experiment
POST	/api/v1/experiments/{experimentId}/complete	Complete experiment
GET	/api/v1/experiments/{experimentName}/user/{userId}/variant	Get user's variant
GET	/api/v1/experiments/user/{userId}/variants	Get all user variants
POST	/api/v1/experiments/{experimentName}/user/{userId}/impression	Record impression
POST	/api/v1/experiments/{experimentName}/user/{userId}/click	Record click
POST	/api/v1/experiments/{experimentName}/user/{userId}/conversion	Record conversion
GET	/api/v1/experiments/{experimentId}/analysis	Get statistical analysis
GET	/api/v1/experiments/{experimentId}/statistics	Get variant statistics
POST	/api/v1/experiments/{experimentId}/result	Set experiment result

Algorithm Types

public enum AlgorithmType {
    COLLABORATIVE_USER_BASED,      // User-based CF
    COLLABORATIVE_ITEM_BASED,      // Item-based CF
    COLLABORATIVE_MATRIX_FACTORIZATION, // SVD/ALS
    CONTENT_BASED,                 // Feature-based
    CONTENT_BASED_TFIDF,           // TF-IDF text
    HYBRID_WEIGHTED,               // Weighted combination
    HYBRID_SWITCHING,              // Dynamic selection
    HYBRID_CASCADE,                // Multi-stage refinement
    POPULARITY_BASED,              // Popular items
    RANDOM,                        // A/B testing baseline
    ASSOCIATION_RULES,             // Frequently bought together
    KNOWLEDGE_BASED,               // Rule-based
    DEEP_LEARNING                  // Neural network based
}

Entities

• Recommendation - Stored recommendation with metadata
• UserInteraction - User interaction event (view, click, purchase)
• ItemFeature - Item attributes for content-based filtering
• Experiment - A/B testing experiment configuration
• ExperimentVariant - Experiment variant with algorithm and traffic
• RecommendationModel - Trained ML model metadata

Example Usage

Getting Recommendations

@Autowired
private RecommendationService recommendationService;

// Get recommendations with context
RecommendationContext context = RecommendationContext.builder()
    .userId("user123")
    .itemType("product")
    .maxResults(10)
    .build();

RecommendationResult result = recommendationService.getRecommendations(context);

// Get recommendations with specific algorithm
RecommendationResult result = recommendationService.getRecommendations(
    context,
    AlgorithmType.HYBRID_WEIGHTED
);

Creating an A/B Test

@Autowired
private ExperimentService experimentService;

// Create experiment
Experiment experiment = experimentService.createExperiment(
    "recommendation_algorithm_test",
    "Testing user-based vs item-based CF",
    "Item-based CF will have higher CTR",
    BigDecimal.valueOf(100),  // 100% traffic
    "data-science-team"
);

// Add control variant
experimentService.addVariant(
    experiment.getId(),
    "control",
    "User-based CF",
    BigDecimal.valueOf(50),
    true,  // isControl
    AlgorithmType.COLLABORATIVE_USER_BASED,
    null
);

// Add treatment variant
experimentService.addVariant(
    experiment.getId(),
    "treatment",
    "Item-based CF",
    BigDecimal.valueOf(50),
    false,
    AlgorithmType.COLLABORATIVE_ITEM_BASED,
    null
);

// Start experiment
experimentService.startExperiment(experiment.getId());

Recording Interactions

@Autowired
private UserInteractionService interactionService;

// Record a view
interactionService.recordView("user123", "product456");

// Record a purchase
interactionService.recordPurchase("user123", "product456", BigDecimal.valueOf(99.99));

Dependencies

This module requires:

• apigen-core - Base services and Result pattern
• Spring Boot 4.0.2+
• Java 25+
• SMILE ML library for matrix factorization
• Apache Commons Text for TF-IDF
• Caffeine for caching

See main README for complete documentation.