A lightweight recommendation system designed for small e-commerce shops running on CPU-only environments. RecSys-Lite provides multiple recommendation algorithms, automatic hyperparameter optimization, fast recommendation serving via Faiss, and a React widget for displaying recommendations.

• Multiple Recommendation Algorithms:

  • ALS and BPR via the implicit library
  • Item2Vec embeddings via gensim
  • Hybrid matrix factorization via LightFM
  • GRU4Rec session-based model via PyTorch
  • EASE‑R linear item‑item model (state‑of‑the‑art accuracy, CPU friendly)

• Hyperparameter Optimization:

  • Automatic tuning via Optuna
  • Optimizes for HR@20 and NDCG@20 metrics
  • Saves best model parameters

• Fast Recommendation Serving:

  • Faiss IVF-Flat index for approximate nearest neighbor search
  • FastAPI endpoint for recommendations
  • Incremental model updates

• React Widget:

  • Responsive carousel for displaying recommendations
  • Customizable with CSS classes
  • Available as NPM package

• GDPR Compliance:

  • EU data residency
  • User data export and deletion functionality
  • Complete audit trail

The system is composed of several components:

1. Data Layer: DuckDB for storing user-item interactions and item metadata
2. Model Layer: Various recommendation algorithms and Optuna for hyperparameter optimization
3. Serving Layer: Faiss for ANN search, FastAPI for the recommendation API
4. Frontend Layer: React widget for displaying recommendations
5. Update Worker: Background process for incremental model updates

For a more detailed architecture overview, see docs/architecture.md.

# Clone the repository
git clone https://github.com/tomascupr/recsys-lite.git
cd recsys-lite

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python dependencies using Poetry (recommended)
poetry install

# Or install using pip
pip install -e .

# Or use Docker
docker compose -f docker/docker-compose.yml up -d

# Ingest data into DuckDB
recsys-lite ingest --events path/to/events.parquet --items path/to/items.csv --db recsys.db

# File-based streaming: continuously append new *.parquet files that appear in a directory
recsys-lite stream-ingest data/incremental --db recsys.db --poll-interval 5

# Message queue-based streaming (requires additional dependencies)
# Install message queue dependencies: pip install recsys-lite[mq]

# RabbitMQ streaming
recsys-lite queue-ingest rabbitmq --db recsys.db --rabbitmq-host localhost --rabbitmq-queue events

# Kafka streaming
recsys-lite queue-ingest kafka --db recsys.db --kafka-servers localhost:9092 --kafka-topic events

# Train ALS model
recsys-lite train als --db recsys.db --output model_artifacts/als

# Train item2vec model
recsys-lite train item2vec --db recsys.db --output model_artifacts/item2vec

# Train EASE-R model
recsys-lite train ease --db recsys.db --output model_artifacts/ease

# Run hyperparameter optimization
recsys-lite optimize als --db recsys.db --trials 20 --metric ndcg@20

# Start API service
recsys-lite serve --model model_artifacts/als --port 8000

# Start update worker for incremental model updates
recsys-lite worker --model model_artifacts/als --db recsys.db --interval 60

# Install the widget package
npm install recsys-lite-widget

# Import and use in your React application
import { RecommendationCarousel } from 'recsys-lite-widget';

function App() {
  return (
    <RecommendationCarousel
      apiUrl="https://your-api-url"
      userId="user123"
      count={5} 
    />
  );
}

GET /recommend?user_id=<user_id>&k=<k>&use_faiss=<true|false>

Returns a list of recommended items for a user.

Parameters:

• user_id (required): User ID to get recommendations for
• k (optional): Number of recommendations to return (default: 10)
• use_faiss (optional): Whether to use Faiss index for similarity search (default: true)

Response:

{
  "user_id": "user123",
  "recommendations": [
    {
      "item_id": "item456",
      "score": 0.95,
      "title": "Product Title",
      "category": "Category",
      "brand": "Brand",
      "price": 99.99,
      "img_url": "https://example.com/image.jpg"
    },
    ...
  ]
}

Error Responses:

• 404 Not Found: User ID not found
• 400 Bad Request: Invalid parameters
• 500 Internal Server Error: Server error

GET /similar-items?item_id=<item_id>&k=<k>

Returns a list of items similar to the given item.

Parameters:

• item_id (required): Item ID to find similar items for
• k (optional): Number of similar items to return (default: 10)

Response:

[
  {
    "item_id": "item789",
    "score": 0.92,
    "title": "Similar Product",
    "category": "Category",
    "brand": "Brand",
    "price": 79.99,
    "img_url": "https://example.com/similar.jpg"
  },
  ...
]

Error Responses:

• 404 Not Found: Item ID not found
• 400 Bad Request: Invalid parameters
• 500 Internal Server Error: Server error

GET /health

Returns the health status of the API.

Response:

{
  "status": "ok",
  "version": "0.1.1",
  "model_type": "als",
  "uptime_seconds": 3600
}

GET /metrics

Returns service metrics for monitoring.

Response:

{
  "uptime_seconds": 3600,
  "request_count": 1500,
  "recommendation_count": 15000,
  "error_count": 5,
  "recommendations_per_second": 4.16,
  "cache_hit_ratio": 0.85
}

The React widget provides a responsive carousel for displaying recommendations:

import { RecommendationCarousel } from 'recsys-lite-widget';

<RecommendationCarousel
  apiUrl="https://your-api-url"
  userId="user123"
  count={10}
  title="Recommended For You"
  className="custom-container"
  containerClassName="carousel-inner"
  cardClassName="product-card"
  onItemClick={(item) => console.log('Clicked item:', item)}
  fetchItemDetails={async (itemIds) => {
    // Optional: Fetch additional item details
    const response = await fetch(`/api/items?ids=${itemIds.join(',')}`);
    return await response.json();
  }}
/>

You can customize the appearance of the widget using CSS classes:

/* Example custom styling */
.custom-container {
  max-width: 1200px;
  margin: 0 auto;
}

.carousel-inner {
  padding: 10px 0;
}

.product-card {
  border-radius: 8px;
  box-shadow: 0 2px 5px rgba(0,0,0,0.1);
  transition: transform 0.3s ease;
}

.product-card:hover {
  transform: translateY(-5px);
}

The system can be deployed using Docker:

# Create directories for persistence
mkdir -p data/incremental model_artifacts

# Start the complete system
docker compose -f docker/docker-compose.yml up -d

# Run tests
docker compose -f docker/docker-compose.test.yml up

For data persistence with Docker, map these volumes:

volumes:
  - ./data:/data                         # Database and event data
  - ./model_artifacts:/app/model_artifacts  # Trained models
  - ./logs:/var/log                       # Log files

Expected format for events data (Parquet):

• user_id: string - Unique user identifier
• item_id: string - Item identifier
• ts: int64 - Unix timestamp
• qty: int - Quantity purchased/viewed

Sample data structure:

┌────────────┬────────────┬────────────┬──────┐
│  user_id   │  item_id   │     ts     │ qty  │
├────────────┼────────────┼────────────┼──────┤
│ user_12345 │ item_67890 │ 1626533119 │ 1    │
│ user_12345 │ item_24680 │ 1626533135 │ 2    │
│ user_67890 │ item_13579 │ 1626533257 │ 1    │
└────────────┴────────────┴────────────┴──────┘

Expected format for items data (CSV):

• item_id: string - Item identifier
• category: string - Item category
• brand: string - Item brand
• price: float - Item price
• img_url: string - URL to item image

Sample data structure:

┌────────────┬──────────────┬────────────┬───────┬───────────────────────────────┐
│  item_id   │   category   │   brand    │ price │           img_url             │
├────────────┼──────────────┼────────────┼───────┼───────────────────────────────┤
│ item_67890 │ Electronics  │ TechBrand  │ 99.99 │ https://example.com/img1.jpg  │
│ item_24680 │ Clothing     │ FashionCo  │ 49.99 │ https://example.com/img2.jpg  │
│ item_13579 │ Home         │ HomeMakers │ 29.99 │ https://example.com/img3.jpg  │
└────────────┴──────────────┴────────────┴───────┴───────────────────────────────┘

1. Create a new model file in src/recsys_lite/models/
2. Implement the model class extending BaseRecommender
3. Update src/recsys_lite/models/__init__.py to export the new model
4. Add CLI command in src/recsys_lite/cli.py
5. Add tests in tests/test_models.py

Example model implementation:

from recsys_lite.models.base import BaseRecommender

class MyNewModel(BaseRecommender):
    def __init__(self, params=None):
        super().__init__(params)
        self.params = params or {}
        
    def fit(self, user_items):
        # Implementation logic
        pass
        
    def recommend(self, user_id, n=10):
        # Implementation logic
        pass
        
    def similar_items(self, item_id, n=10):
        # Implementation logic
        pass
        
    def save(self, path):
        # Implementation logic
        pass
        
    @classmethod
    def load(cls, path):
        # Implementation logic
        pass

# Run all tests
pytest

# Run a specific test
pytest tests/test_models.py::test_als_model

# Run with coverage
pytest --cov=src tests/

# Run linting
ruff .

# Run type checking
mypy .

RecSys-Lite is designed with GDPR compliance in mind:

The gdpr export-user command exports all data associated with a user, including:

• Raw event data (interactions with items)
• Timestamps of interactions
• Item metadata for interacted items

The export is provided in JSON format and includes all information stored about the user.

The gdpr delete-user command removes all user data from the system:

1. Deletes raw events from the database
2. Marks the user for removal from models
3. Removes user vectors during the next update cycle

After deletion, the user will no longer receive personalized recommendations.

All GDPR-related operations are logged with timestamps, including:

• Data export requests
• Data deletion requests
• Model updates after deletion
• API access patterns

RecSys-Lite can be configured using environment variables:

API returns "Model not found" error:

• Check that the model directory exists and contains all required files
• Verify the model was trained successfully
• Try retraining the model

Poor recommendation quality:

• Increase the number of factors in the model
• Run hyperparameter optimization
• Use a hybrid model like LightFM with item features
• Check data quality and increase training data volume

Update worker not updating recommendations:

• Check worker logs for errors
• Verify incremental data is in the correct format
• Check database connectivity

High memory usage:

• Reduce the number of factors in models
• Decrease FAISS_NPROBE value
• Reduce BATCH_SIZE for updates
• Consider using a smaller model like ALS instead of LightFM

• Python 3.11+
• DuckDB 0.8.1+
• CPU with 8+ cores
• 16GB+ RAM

Apache License 2.0

We welcome contributions to RecSys-Lite! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

For more details, see our Contributing Guide.

RecSys-Lite is maintained by the RecSys-Lite Team. Special thanks to all contributors!