amazon-science/AdaRec

amazon-science/AdaRec

Description: Adaptive Generative Recommendations with Large Language Models

Language: Jupyter Notebook

License: Apache-2.0

Stars: 7

Forks: 3

Open issues: 5

Created: 2025-12-12T03:52:24Z

Pushed: 2026-04-07T06:39:20Z

Default branch: main

Fork: no

Archived: no

README:

AdaRec: Adaptive Generative Recommendations with Large Language Models

AdaRec is a counterfactual inference framework for customer outcomes using few-shot in-context learning. Built with CatBoost, Polars, and DSPy, it generates natural language customer profiles and predicts counterfactual outcomes using Large Language Models with AWS Bedrock.

For more information, refer to our FMSD @ ICML 2025 paper: AdaRec: Adaptive Generative Recommendations with Large Language Models.

What AdaRec Does

AdaRec transforms tabular customer data into rich narrative profiles and uses them to predict counterfactual outcomes:

1. Profile Generation: Converts customer features into natural language narratives 2. Counterfactual Prediction: Predicts customer behavior under different treatments/promotions 3. Few-Shot Learning: Uses similar customers as examples for better predictions 4. Product Recommendations: Generates ideal product descriptions and matches them to catalog items

Installation

Requirements

• Python 3.12
• AWS Account with Bedrock access
• UV package manager (recommended)

Setup

1. Clone the repository

git clone https://github.com/amazon-science/AdaRec
cd AdaRec

2. Install dependencies

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

3. Configure AWS Bedrock

# Set up AWS credentials
aws configure
# Ensure you have access to Claude models in your region

4. Prepare example dataset

python script/prepare_example_dataset.py

Quick Start

1. Run the Getting Started Notebook

The easiest way to understand AdaRec is through our comprehensive example:

jupyter notebook notebook/getting_started.ipynb

This notebook demonstrates the complete workflow using the UCI Online Retail dataset:

• Data preprocessing with Polars
• Profile generation (template → narrative)
• Counterfactual prediction with few-shot learning
• Comparison with gradient boosting baseline
• Product recommendation via semantic similarity

2. Basic Usage Example

import polars as pl
from src.counterfactual import BaseProfileGenerator, BatchProfileGenerator, BatchPredictor

# Load your customer data
df = pl.read_csv('your_customer_data.csv')

# Generate template profiles
generator = BaseProfileGenerator(
df=df,
feature_config='config/customer_feature_config.yaml',
treatment_config='config/treatment_config.yaml',
outcome_config='config/outcome_config.yaml'
)

# Generate narrative profiles using LLMs
batch_generator = BatchProfileGenerator(
df=df,
model_config='config/model_config.yaml',
feature_config='config/customer_feature_config.yaml',
treatment_config='config/treatment_config.yaml',
outcome_config='config/outcome_config.yaml'
)
narrative_profiles = batch_generator.generate_batch_narrative_profiles()

# Do the same for reference dataset to get few-shot examples from
ref_batch_generator = BatchProfileGenerator(
df=ref_df,
model_config='config/model_config.yaml',
feature_config='config/customer_feature_config.yaml',
treatment_config='config/treatment_config.yaml',
outcome_config='config/outcome_config.yaml'
)
ref_narrative_profiles = ref_batch_generator.generate_batch_narrative_profiles()

# Make counterfactual predictions
predictor = BatchPredictor(
generator=batch_generator,
customer_profile_column='narrative_profile',
outcome_config='config/outcome_config.yaml',
model_config='config/model_config.yaml',
reference_generator=ref_batch_generator, # Historical data for few-shot examples
similarity_features=['recency', 'total_sales', 'purchase_frequency'],
top_k_examples=3
)

predictions = predictor.generate_predictions()

Core Components

Profile Generation

• BaseProfileGenerator: Converts tabular features to template text profiles
• BatchProfileGenerator: Uses LLMs to create natural narrative profiles from templates

Counterfactual Prediction

• BatchPredictor: Generates counterfactual predictions using few-shot learning
• SimilaritySearcher: Finds similar customers for few-shot examples

Data Processing

• transform.py: Polars-based data preprocessing utilities
• Feature engineering and imputation
• Stratified sampling and train/test splits
• Outcome resampling for imbalanced datasets

Configuration

AdaRec uses YAML configuration files for flexibility:

Model Configuration (config/model_config.yaml)

• AWS Bedrock model settings
• Batch processing parameters
• System prompts for profile generation and prediction

Feature Configuration (config/customer_feature_config.yaml)

• Maps tabular columns to natural language descriptions
• Organizes features by domain (RFM, preferences, etc.)

Treatment Configuration (config/treatment_config.yaml)

• Defines promotional treatments/interventions
• Treatment descriptions for profile generation

Outcome Configuration (config/outcome_config.yaml)

• Target variables and their descriptions
• Outcome distributions for context

Project Structure

AdaRec/
├── config/ # YAML configuration files
├── data/ # Example datasets
├── notebook/ # Jupyter notebooks and examples
│ ├── getting_started.ipynb # Main tutorial
│ └── src/ # Notebook-specific source code
├── script/ # Data preparation scripts
├── src/ # Main source code
│ ├── counterfactual/ # Core AdaRec components
│ ├── data_processing/ # Polars utilities
│ └── evaluation/ # Metrics and evaluation
└── research/ # Research pipeline for the original paper

Usage Examples

Predicting Sales

Predict customer sales behavior under normal conditions without promotions:

1. Prepare organic sales data:

• customer_id: Unique customer identifier
• Customer behavior features (recency, frequency, monetary value, category preferences)
• Historical organic sales data (no promotional periods)

2. Configure for organic prediction:

• Map customer features in customer_feature_config.yaml (RFM metrics, purchase patterns)
• Set treatment to "No Promotion" in treatment_config.yaml
• Specify sales outcomes in outcome_config.yaml (baseline sales amount, purchase likelihood)

3. **Run…