---
title: Recommendation LLM Explainer
emoji: 🎬
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 6.3.0
app_file: app.py
pinned: false
---

# AI-Powered Explainable Recommendations

This project is a high-fidelity demonstration of how Large Language Models (LLMs) can bridge the "explainability gap" in recommendation systems. It transforms opaque collaborative filtering data into transparent, persona-aligned narratives.

![Demo Application](home-page-recos.jpg)

## 🚀 Overview

Instead of providing a "black box" list of suggestions, this system uses LLMs to synthesize natural language explanations based on user personas and collaborative filtering logic.

### Key Features
- **Specialist Centroids**: Personas built by aggregating top "specialists" for specific genres.
- **Layered Re-ranking**: Incorporates Genre Affinity Boosts and Recency Bias.
- **Narrative Synthesis**: Uses LiteLLM to generate 3-sentence explanations in "Logic-Driven" or "Social-Behavioral" styles.

## 🛠 Tech Stack

- **Interface**: [Gradio](https://gradio.app/)
- **Recommendation Engine**: Python (`pandas`, `numpy`, `scikit-learn`)
- **LLM Integration**: [LiteLLM](https://github.com/BerriAI/litellm)
- **Data Source**: [MovieLens Latest Small](https://grouplens.org/datasets/movielens/latest/)
- **Visuals**: [TMDB API](https://www.themoviedb.org/documentation/api) for movie posters.

## 📁 Quick Start

1.  **Environment Setup**:
    Create a `.env` file:
    ```env
    HF_TOKEN=your_huggingface_token
    TMDB_API_KEY=your_tmdb_api_key
    ```
2.  **Install Dependencies**:
    ```bash
    pip install -r requirements.txt
    ```
3.  **Data Preparation**:
    ```bash
    python data_prep.py
    ```
4.  **Run the Application**:
    ```bash
    python app.py
    ```

## 📜 Acknowledgments & Data Sources

- **Dataset**: This project uses the **MovieLens Latest Dataset - Small** provided by [GroupLens Research](https://grouplens.org/datasets/movielens/).
- **Images**: Movie posters are retrieved using the **TMDB API**. *Note: This product uses the TMDB API but is not endorsed or certified by TMDB.*