Adapter Integration Guide

This guide explains how to use the recommendation library adapters to integrate external recommendation libraries with RecoAgent's Intelligent Recommendations solution.

Overview

The adapter framework allows you to plug in any recommendation library while maintaining a consistent interface. This enables you to:

• Use the best algorithm for your specific use case
• Switch between libraries without changing your code
• Combine multiple libraries in a single pipeline
• Leverage existing infrastructure and expertise

Supported Libraries

Microsoft Recommenders

• Algorithms: SAR, NCF, Wide&Deep, DeepFM, xDeepFM, FastAI
• Best for: Production-ready algorithms with good documentation
• Install: pip install recommenders

RecBole

• Algorithms: 100+ algorithms including BPR, NGCF, LightGCN, SASRec, GRU4Rec
• Best for: Research and experimentation with state-of-the-art models
• Install: pip install recbole

Implicit

• Algorithms: Fast ALS, BPR, LMF
• Best for: Large-scale implicit feedback datasets
• Install: pip install implicit

DLRM

• Algorithms: Facebook's DLRM model
• Best for: Production systems with categorical features
• Install: pip install torch

Surprise

• Algorithms: SVD, KNN, SlopeOne, CoClustering, NMF
• Best for: Classic collaborative filtering algorithms
• Install: pip install scikit-surprise

Quick Start

1. Basic Usage

from recoagent.packages.recommendations.adapters import (
    MicrosoftRecommendersAdapter,
    ImplicitAdapter,
    get_available_adapters
)

# Check available adapters
available = get_available_adapters()
print(f"Available adapters: {available}")

# Create an adapter
adapter = ImplicitAdapter()

# Set algorithm
adapter.set_algorithm("als")

# Train model
train_results = adapter.fit(train_data)
print(f"Training success: {train_results['success']}")

# Get recommendations
recommendations = adapter.predict("user_123", n_recommendations=10)
for rec in recommendations:
    print(f"Item: {rec.item_id}, Score: {rec.score}")

2. Using the Registry

from recoagent.packages.recommendations.adapters import (
    get_best_adapter,
    create_adapter,
    AdapterCapability
)

# Find the best adapter for your needs
best_adapter = get_best_adapter(
    required_capabilities=[
        AdapterCapability.COLLABORATIVE_FILTERING,
        AdapterCapability.IMPLICIT_FEEDBACK
    ],
    preferred_library="implicit"
)

# Create the adapter
adapter = create_adapter(best_adapter)

3. Configuration

from recoagent.packages.recommendations.adapters import AdapterConfig

# Configure adapter
config = AdapterConfig(
    batch_size=1024,
    max_workers=8,
    model_params={
        "algorithm": "als",
        "factors": 50,
        "regularization": 0.01
    }
)

adapter = ImplicitAdapter(config)

Advanced Usage

1. Custom Data Format

from recoagent.packages.recommendations.adapters.utils import convert_to_standard_format

# Convert your data to standard format
standard_data = convert_to_standard_format(
    your_data, 
    source_format="movielens"  # or "amazon", "custom"
)

# Train with standard data
adapter.fit(standard_data)

2. Batch Predictions

# Predict for multiple users
user_ids = ["user_1", "user_2", "user_3"]
batch_results = adapter.predict_batch(user_ids, n_recommendations=10)

for user_id, recommendations in batch_results.items():
    print(f"User {user_id}: {len(recommendations)} recommendations")

3. Model Evaluation

# Evaluate model performance
metrics = adapter.evaluate(test_data, metrics=["ndcg", "precision", "recall"])
print(f"NDCG@10: {metrics['ndcg']:.3f}")
print(f"Precision@10: {metrics['precision']:.3f}")

4. Model Persistence

# Save trained model
save_results = adapter.save_model("models/my_model.pkl")
print(f"Model saved: {save_results['success']}")

# Load model
load_results = adapter.load_model("models/my_model.pkl")
print(f"Model loaded: {load_results['success']}")

Library-Specific Examples

Microsoft Recommenders

from recoagent.packages.recommendations.adapters import MicrosoftRecommendersAdapter

# Create adapter
adapter = MicrosoftRecommendersAdapter()

# Available algorithms
algorithms = adapter.get_supported_algorithms()
print(f"Available algorithms: {algorithms}")

# Use SAR algorithm
adapter.set_algorithm("sar", similarity_type="jaccard", time_decay_coefficient=30)

# Train
train_results = adapter.fit(train_data)

RecBole

from recoagent.packages.recommendations.adapters import RecBoleAdapter

# Create adapter
adapter = RecBoleAdapter()

# Use LightGCN algorithm
adapter.set_algorithm("lightgcn", embedding_size=64, n_layers=3)

# Train with custom parameters
train_results = adapter.fit(
    train_data,
    epochs=50,
    learning_rate=0.001,
    batch_size=256
)

Implicit

from recoagent.packages.recommendations.adapters import ImplicitAdapter

# Create adapter
adapter = ImplicitAdapter()

# Use ALS with custom parameters
adapter.set_algorithm("als", factors=100, regularization=0.01, iterations=20)

# Train
train_results = adapter.fit(train_data)

Performance Optimization

1. Batch Size Tuning

# For large datasets
config = AdapterConfig(
    batch_size=2048,  # Increase for better GPU utilization
    max_workers=16    # Parallel processing
)

2. Memory Management

# For memory-constrained environments
config = AdapterConfig(
    batch_size=256,    # Smaller batches
    cache_size=1000   # Limit cache size
)

3. Algorithm Selection

# For speed vs accuracy trade-offs
fast_config = AdapterConfig(
    model_params={"algorithm": "sar"}  # Fast algorithm
)

accurate_config = AdapterConfig(
    model_params={"algorithm": "ncf"}   # More accurate but slower
)

Error Handling

1. Library Availability

from recoagent.packages.recommendations.adapters import get_available_adapters

available = get_available_adapters()
if "microsoft_recommenders" not in available:
    print("Microsoft Recommenders not installed")
    print("Install with: pip install recommenders")

2. Graceful Fallback

try:
    adapter = MicrosoftRecommendersAdapter()
except ImportError:
    print("Microsoft Recommenders not available, falling back to Implicit")
    adapter = ImplicitAdapter()

3. Training Errors

train_results = adapter.fit(train_data)
if not train_results["success"]:
    print(f"Training failed: {train_results['error']}")
    # Handle error appropriately

Best Practices

1. Data Preparation

# Ensure data quality
def validate_data(data):
    required_columns = ["user_id", "item_id", "score"]
    missing = set(required_columns) - set(data.columns)
    if missing:
        raise ValueError(f"Missing columns: {missing}")
    
    # Check for duplicates
    duplicates = data.duplicated(subset=["user_id", "item_id"]).sum()
    if duplicates > 0:
        print(f"Warning: {duplicates} duplicate interactions found")
    
    return data

# Use validated data
clean_data = validate_data(train_data)
adapter.fit(clean_data)

2. Model Selection

# Choose algorithm based on data characteristics
def select_algorithm(data):
    n_users = data["user_id"].nunique()
    n_items = data["item_id"].nunique()
    sparsity = len(data) / (n_users * n_items)
    
    if sparsity < 0.01:  # Very sparse
        return "sar"  # Good for sparse data
    elif n_users > 100000:  # Large scale
        return "als"  # Fast and scalable
    else:
        return "ncf"  # More accurate for smaller datasets

3. Evaluation Strategy

# Comprehensive evaluation
def evaluate_model(adapter, test_data):
    metrics = adapter.evaluate(test_data, metrics=[
        "ndcg", "precision", "recall", "hit_rate"
    ])
    
    # Log results
    for metric, value in metrics.items():
        print(f"{metric}: {value:.3f}")
    
    return metrics

Troubleshooting

Common Issues

1. Import Errors

   # Check if library is installed
   try:
       import recommenders
   except ImportError:
       print("Install with: pip install recommenders")

2. Memory Issues

   # Reduce batch size
   config = AdapterConfig(batch_size=128)

3. Slow Training

   # Use faster algorithms
   adapter.set_algorithm("sar")  # Instead of "ncf"

4. Poor Performance

   # Tune hyperparameters
   adapter.set_algorithm("als", factors=100, regularization=0.01)

Getting Help

• Check the API Reference
• See Examples
• Join our Community Discord
• Open an Issue

Next Steps

• Learn about Two-Tower Retrieval
• Explore Feature Store Integration
• Read about Causal Inference
• See LLM Integration Patterns