---
title: "My RecoFM AI Agent Demo"
emoji: "🎬"
colorFrom: pink
colorTo: red
sdk: gradio
sdk_version: 4.31.0
app_file: app.py
license: apache-2.0
tags:
  - agent-demo-track
  - recommender-system
  - gradio
---

# Movie Recommender System

# Tag: **agent-demo-track**

A hybrid movie recommender system that combines collaborative filtering, language model embeddings, and graph convolutional networks to provide personalized movie recommendations.

## Features

### Dual Embedding Types

- **Pure Language Model (LLM) Embeddings**  
  Generated for each movie title using Mistral AI.

- **Graph-Enhanced Embeddings (LLM + GCL)**  
  Combines language understanding with user interaction patterns to enrich the embeddings.

---

### Hybrid Input

- **Movie Selection**  
  Select movies you've previously enjoyed.

- **Natural Language Query**  
  Describe the kind of movie you're looking for in natural language.

- **Weight Adjustment (α)**  
  Adjust the balance between your movie selections and your text description to personalize the recommendations.

---

### Algorithm

- **Embedding Aggregation**  
  Convert the user preference into an embedding and aggregate it with embeddings of previously watched movies to create a query embedding.

- **Retrieval Phase**  
  Retrieve the top 100 candidate movies based on cosine similarity between the query embedding and movie embeddings.

- **Ranking Phase**  
  Use an AI agent to rank the top 100 candidates and select the final top 10 recommendations, considering:
  - User preferences  
  - Viewing history  
  - Weight parameter (α)
## Requirements

1. Python 3.8+
2. Virtual environment (recommended)
3. Mistral AI API key (get one at https://console.mistral.ai/)

Install the required packages:

```bash
pip install -r requirements.txt
```

## Environment Setup

1. Create a `.env` file in the project root:
```bash
MISTRAL_API_KEY=your_api_key_here
```

2. Ensure you have the necessary data files in the `amazon_movies_2023` directory:
   - `title_embeddings.npz`: Movie title embeddings from Mistral AI
   - `gcl_embeddings.npz`: Graph-enhanced embeddings
   - `title_embeddings_mapping.csv`: Movie metadata mapping

## Usage

1. Activate your virtual environment:
```bash
source venv/bin/activate  # On Unix/macOS
```

2. Run the recommender app:
```bash
python movie_recommender_app.py
```

3. Open your browser to the local URL shown in the terminal (typically http://127.0.0.1:7860)

## How It Works

1. **Movie Selection:**
   - Search and select up to 5 movies you've enjoyed
   - The system uses these as a baseline for your taste

2. **Text Preferences:**
   - Describe what you're looking for (e.g., "A thrilling sci-fi movie with deep philosophical themes")
   - Your description is converted to embeddings using Mistral AI

3. **Preference Weighting:**
   - Use the α slider to balance between your selected movies and text description
   - α = 0: Only use movie history
   - α = 1: Only use text description
   - Values in between combine both signals

4. **Embedding Types:**
   - LLM: Pure language model embeddings for semantic understanding
   - LLM + GCL: Graph-enhanced embeddings that also consider user interaction patterns

## Data Processing

For information about the dataset processing pipeline, see [DATA_PROCESSING.md](DATA_PROCESSING.md)

## Contributing

Feel free to open issues or submit pull requests with improvements!