EventGen AI

A personalized event recommendation system that matches users with events based on their personality preferences and location.

🎯 What Does This Do?

EventGen AI helps you discover events that match your personality and preferences. Simply answer a short questionnaire, and the system will:

1. Generate a personality profile based on your answers
2. Search for events in your area (currently focused on Toronto)
3. Match events to your personality using AI embeddings
4. Recommend the top events with personalized explanations

🏗️ System Overview

EventGen AI uses a two-stage pipeline:

1. Event Collection: Searches Eventbrite using Tavily AI to find event URLs, then extracts detailed information using GPT
2. Personalized Matching: Converts both user preferences and events into 10-dimensional personality embeddings, then ranks events by similarity

For detailed architecture information, see ARCHITECTURE.md.

🚀 Getting Started

Prerequisites

Before you begin, make sure you have:

• Python 3.11+ installed (Download here)
• Git installed
• API Keys (you'll need these):
  • OpenAI API key (Get one here)
  • Tavily API key (Get one here)
  • Google Maps API key (Get one here) - Optional, for geocoding

---

Step 1: Clone the Repository

git clone https://github.com/ece1786-2025/EventGenAI.git
cd EventGenAI

---

Step 2: Set Up Python Environment

Option A: Using venv (Recommended)

On Windows:

# Create virtual environment
python -m venv .venv

# Activate it
.\.venv\Scripts\Activate.ps1
# If that doesn't work, try:
.\.venv\Scripts\activate.bat

On Mac/Linux:

python3 -m venv .venv
source .venv/bin/activate

Option B: Using Conda

conda create -n eventgenai python=3.11
conda activate eventgenai

💡 Tip: You'll see (.venv) or (eventgenai) in your terminal when the environment is active.

---

Step 3: Install Dependencies

# Upgrade pip first
python -m pip install --upgrade pip

# Install all required packages
pip install -r requirements.txt

---

Step 4: Configure API Keys

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and add your API keys:

   OPENAI_API_KEY=your-openai-api-key-here
   TAVILY_API_KEY=your-tavily-api-key-here
   GOOGLE_MAPS_API_KEY=your-google-maps-api-key-here

⚠️ Important: Never commit your .env file to Git. It's already in .gitignore.

---

🎮 How to Use

Running the Event Collection Pipeline

The pipeline has two main stages:

Stage 1: Collect Event URLs (Using Tavily AI)

This stage searches Eventbrite by category and collects event URLs.

python backend/pipeline.py --stage 1 --categories music arts food-and-drink --location "Toronto, Canada" --max-events-per-subcategory 10

Parameters:

• --stage 1: Run only Stage 1 (URL collection)
• --categories: Which event categories to search (space-separated)
  • Available: music, arts, food-and-drink, sports-and-fitness, health, business, science-and-tech
• --location: City and country to search in
• --max-events-per-subcategory: How many events to collect per subcategory (default: 10)

Output:

• CSV files saved to: data/search_results/csv_files/
• Master JSON updated: data/search_results/all_events_master.json

---

Stage 2: Extract Event Details (Using GPT)

This stage processes the collected URLs and extracts detailed event information using GPT.

python backend/pipeline.py --stage 2 --stage2-batch-size 10

Parameters:

• --stage 2: Run only Stage 2 (event detail extraction)
• --stage2-batch-size: How many events to process at once (default: 10)

Output:

• Updated master JSON with event details: data/search_results/all_events_master.json
• Raw GPT responses saved to: data/search_results/gpt_responses/

---

Running Both Stages Together

python backend/pipeline.py --stage all --categories music arts --location "Toronto, Canada" --max-events-per-subcategory 10 --stage2-batch-size 10

This will:

1. Collect event URLs for the specified categories
2. Extract detailed information for all collected events
3. Remove expired events automatically

---

Generating Event Embeddings

After collecting events, generate personality embeddings for each event:

cd backend/event_manager/event_embedding
python generate_event_embeddings.py

Output:

• Events with embeddings saved to: data/search_results/all_events_with_embedding.json

---

Running the Backend API

Start the Flask server to handle user questionnaire submissions:

cd backend
python app.py

The API will be available at: http://127.0.0.1:5000

Available Endpoints:

• POST /embedding - Submit questionnaire answers and get user profile

---

Using the Frontend

1. Open the questionnaire:

   # Open directly in your browser (double click the file):
   frontend/index.html

2. Fill out the questionnaire with your preferences

3. Submit to generate your personality profile

---

Getting Personalized Recommendations

Once you have:

• Event data with embeddings (all_events_with_embedding.json)
• Your user profile (saved in data/users/)

Run the ranking system:

cd backend/filter_rankings
python ranking.py

This will output your top recommended events based on personality similarity.

---

📊 Example Workflow

Here's a complete example of collecting events and getting recommendations:

# 1. Activate your environment
.\.venv\Scripts\activate.bat  # Windows
# source .venv/bin/activate    # Mac/Linux

# 2. Collect 100 music events from Toronto
python backend/pipeline.py --stage 1 --categories music --location "Toronto, Canada" --max-events-per-subcategory 10

# 3. Extract event details
python backend/pipeline.py --stage 2 --stage2-batch-size 10

# 4. Generate event embeddings
cd backend/event_manager/event_embedding
python generate_event_embeddings.py

# 5. Start the backend API (in a new terminal)
cd backend
python app.py

# 6. Open frontend/index.html in your browser and fill out the questionnaire

# 7. Get recommendations
cd backend/filter_rankings
python ranking.py

---

� Troubleshooting

Common Issues

Virtual Environment Problems

Issue: "Fatal error in launcher" or "Unable to create process"

Your .venv was created on a different computer or copied from elsewhere.

Solution:

# Delete and recreate
Remove-Item -Recurse -Force .venv
python -m venv .venv
.\.venv\Scripts\activate.bat
pip install -r requirements.txt

Issue: PowerShell execution policy blocks scripts

Solution: Use activate.bat instead:

.\.venv\Scripts\activate.bat

---

Package Installation Issues

Issue: Packages fail to install

Solution: Upgrade pip first:

python -m pip install --upgrade pip
pip install -r requirements.txt

Issue: pip command not found

Solution: Use:

python -m pip install -r requirements.txt

---

API Key Issues

Issue: "TAVILY_API_KEY not found in environment"

Solution:

1. Make sure you copied .env.example to .env
2. Edit .env and add your actual API keys (not placeholder text)
3. Restart your terminal/Python script

---

Pipeline Issues

Issue: Stage 1 finds no events

Possible causes:

• Invalid category name (check available categories below)
• Tavily API rate limit reached
• Network connection issues

Solution:

• Use correct category names: music, arts, food-and-drink, sports-and-fitness, health, business, science-and-tech
• Wait a few minutes if rate limited
• Check your internet connection

Issue: Stage 2 processes very slowly

This is expected - GPT needs to visit each event page and extract information. Processing 10 events takes approximately 2-3 minutes.

Solution: Reduce --stage2-batch-size if experiencing timeout issues.

---

�📁 Project Structure

EventGenAI/
├── backend/
│   ├── app.py                           # Flask API server
│   ├── pipeline.py                      # Main pipeline orchestrator
│   ├── profile_manager/                 # User personality profiling
│   │   ├── model.py                    # Embedding generation
│   │   ├── prompt_builder.py          # Prompt engineering
│   │   └── system_prompt.txt          # LLM instructions for users
│   ├── event_manager/                   # Event data collection
│   │   ├── tavily_search.py           # Stage 1: URL collection
│   │   ├── gpt_scraper.py             # Stage 2: Detail extraction
│   │   ├── event_types.py             # Category definitions
│   │   └── event_embedding/            # Event personality modeling
│   │       ├── event_model.py         # Event embedding generation
│   │       ├── generate_event_embeddings.py  # Batch processor
│   │       └── system_prompt_event.txt # LLM instructions for events
│   ├── filter_rankings/                 # Recommendation engine
│   │   ├── ranking.py                 # Cosine similarity ranking
│   │   └── google_geo.py              # Geocoding utilities
│   ├── response_generator/              # Natural language generation
│   │   ├── generator.py               # Explanation generator
│   │   └── system_prompt.txt          # LLM instructions
│   └── test_validation/                 # Testing & validation
│       ├── event_embedding_sanity_check/
│       └── event_user_matching/
├── frontend/
│   └── index.html                       # User questionnaire interface
├── data/
│   ├── search_results/                  # Event data storage
│   │   ├── all_events_master.json     # Main event database
│   │   ├── all_events_with_embedding.json  # Events with embeddings
│   │   ├── csv_files/                 # Stage 1 outputs
│   │   ├── gpt_responses/             # Stage 2 raw responses
│   │   └── raw_responses/             # Tavily raw responses
│   └── users/                           # User profiles
├── .env.example                         # Environment template
├── requirements.txt                     # Python dependencies
├── README.md                            # This file
└── ARCHITECTURE.md                      # Detailed system architecture

---

📚 Additional Documentation

• ARCHITECTURE.md - Complete system architecture and design
• WEB_CRAWLER_SUMMARY.md - Web crawler documentation

---

🎓 Available Event Categories

When running Stage 1, you can choose from these categories:

• music - Concerts, festivals, live performances
• arts - Art shows, theater, exhibitions
• food-and-drink - Food festivals, tastings, dining events
• sports-and-fitness - Sports events, fitness classes, marathons
• health - Wellness, yoga, meditation events
• business - Networking, conferences, professional development
• science-and-tech - Tech meetups, hackathons, science talks

Each category has multiple subcategories that are automatically searched.

---

💡 Tips for Best Results

1. Start Small: Test with 1-2 categories first before running the full pipeline
2. Monitor Progress: Stage 1 shows real-time progress; Stage 2 can be slow for large datasets
3. Check Logs: Raw responses are saved for debugging - check data/search_results/
4. Batch Sizing: For Stage 2, use smaller batches (5-10) to avoid timeouts
5. Regular Updates: Re-run Stage 1 periodically to get fresh events

---

👥 Contributors

• Kunlong Li (1007833025)
• Yuchen Zhou (1011816867)

---

📄 License

University of Toronto - ECE1786 Course Project (2025)

---

🔗 Useful Links

• OpenAI API Documentation
• Tavily API Documentation
• Google Maps Geocoding API
• Eventbrite Platform

---

Need help? Check ARCHITECTURE.md for system design details.