---
title: Plan-A-Party - AI-Powered Private Event Planner
emoji: 🎉 🥳 
colorFrom: pink
colorTo: blue
sdk: docker
app_file: app.py
pinned: false
license: mit
short_description: MCP 1st Birthday party Hackathon Submission
tags:
  - mcp-in-action-track-creative
  - mcp-in-action-track-consumer
  - model-context-protocol
  - mcp
  - gradio
  - mcp-1st-birthday
---

# 🎉 Plan-A-Party - AI-Powered Private Event Planner

> **A complete multi-agent party planning system that transforms event planning from a stressful task into a delightful conversation.** Built with LangChain, Gradio 6, and Model Context Protocol (MCP) integrations.

---

## 📖 Table of Contents

- [What is Plan-A-Party App](#-what-is-plan-a-party-app)
- [Gradio 6 & Advanced Features](#-gradio-6--advanced-features)
- [System Architecture](#-system-architecture)
- [Real-World Usefulness & Potential](#-real-world-usefulness--potential)
- [Quick Start Guide](#-quick-start-guide)
- [Features](#-features)
- [Technology Stack](#-technology-stack)
- [Project Structure](#-project-structure)
- [MCP Integrations](#-mcp-integrations)
- [Example Workflows](#-example-workflows)
- [Setup & Configuration](#-setup--configuration)
- [Known Limitations](#-known-limitations)
- [Future Enhancements](#-future-enhancements)

---

## 🎯 What is Plan-A-Party App

**Plan-A-Party** is a complete AI-powered party planning system that transforms event planning from a stressful, time-consuming task into a delightful conversation. Built with cutting-edge multi-agent AI technology, it coordinates four specialized AI agents to handle every aspect of party planning—from theme selection and venue discovery to invitation generation, guest management, and shopping for decor and party favors.

The app uses **natural language conversation** as its primary interface, allowing users to plan their entire event by simply chatting with an AI assistant. Instead of navigating complex forms or multiple applications, users describe their party vision, and the system intelligently guides them through each step while handling the technical details behind the scenes.

### **Why It's Easy to Use**

- **No learning curve** — Just chat naturally in plain English
- **Single-page interface** — Everything happens in one place, no tab switching
- **Progressive information gathering** — System only asks for details when needed
- **Context-aware responses** — AI remembers the entire conversation
- **Visual feedback** — Real-time updates for cart previews, invitations, and status
- **Smart button visibility** — Features appear only when ready to use
- **Proactive guidance** — Helpful hints about next steps throughout
- **Streamlined workflow** — Logical flow from description to shopping
- **Error recovery** — Clear, actionable error messages
- **Zero configuration** — Works out of the box, optional features gracefully degrade

---

### **MCP Integration with Gradio**

The application seamlessly integrates **Model Context Protocol (MCP)** servers through Gradio's event system:

- **Async MCP Calls**: Background processing for venue searches, email sending, and product searches
- **Real-time Updates**: MCP results displayed immediately in chat interface
- **Graceful Degradation**: App continues to work even if optional MCP servers are unavailable
- **User Feedback**: Clear status messages during MCP operations

---

## 🏗️ System Architecture

Plan-A-Party follows a **multi-agent orchestration pattern** with a centralized orchestrator coordinating specialized subagents.

### **Architecture Overview**

```
┌─────────────────────────────────────────────────────────────┐
│                    Gradio UI Layer                           │
│  (Interactive Chat, File Upload, Image Display, Cart)       │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              Orchestrator Agent                              │
│  • Conversational Flow Management                            │
│  • LLM-based Decision Making                                 │
│  • Tool Routing & Context Summarization                     │
│  • Natural Language Understanding                            │
└──────┬──────────┬──────────┬──────────┬─────────────────────┘
       │          │          │          │
       ▼          ▼          ▼          ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Theme   │ │ Guest    │ │ Venue    │ │ Shopping │
│Planning │ │ Invite   │ │ Search   │ │ Agent    │
│ Agent   │ │ Agent    │ │ Agent    │ │          │
└────┬────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
     │          │             │            │
     ▼          ▼             ▼            ▼
┌─────────────────────────────────────────────────────────────┐
│              Shared PartyContext (Pydantic Model)            │
│  • Event Metadata (budget, location, date)                  │
│  • Theme Options & Selection                                 │
│  • Guest Lists & Email Status                                │
│  • Venue Results                                            │
│  • Shopping Cart & Order Status                              │
└─────────────────────────────────────────────────────────────┘
     │          │             │            │
     ▼          ▼             ▼            ▼
┌─────────────────────────────────────────────────────────────┐
│                    MCP Integration Layer                     │
│  • Bright Data MCP (SERP Search)                            │
│  • Resend MCP (Email via Zapier)                            │
│  • Amazon MCP (Product Search)                              │
│  • Fewsats MCP (Payment Processing)                         │
└─────────────────────────────────────────────────────────────┘
     │          │             │            │
     ▼          ▼             ▼            ▼
┌─────────────────────────────────────────────────────────────┐
│              External Services & APIs                        │
│  • Hugging Face Inference API (LLM & Image Gen)             │
│  • Google/Bing Search (via Bright Data)                     │
│  • Gmail API (via Zapier)                                   │
│  • Amazon Product API                                       │
└─────────────────────────────────────────────────────────────┘
```

### **Component Details**

#### **1. Orchestrator Agent** (`src/agents/orchestrator.py`)
- **Role**: Central coordinator managing conversation flow and tool routing
- **Key Functions**:
  - `orchestrator_chat()`: Main conversational entrypoint
  - `decide_next_action()`: LLM-based decision making for tool selection
  - `extract_event_details_from_message()`: Information extraction from natural language
  - `extract_theme_selection_from_message()`: Theme selection detection
  - `summarize_party_context()`: Context compression for LLM prompts
- **LLM Model**: `meta-llama/Llama-3.3-70B-Instruct` (via Hugging Face)
- **Decision Logic**: JSON-based action selection (`ask_user` vs `call_tool`)

#### **2. Theme Planning Agent** (`src/agents/theme_planning_agent.py`)
- **Capabilities**:
  - Generates 3 creative, age-appropriate theme options
  - Creates invitation text with embedded event details
  - Generates 4x4 invitation card images using FLUX.1-dev
- **Tools**:
  - `generate_party_themes()`: Theme generation
  - `generate_invitation_for_theme()`: Invitation card creation
- **Models**: 
  - Text: `meta-llama/Llama-3.3-70B-Instruct`
  - Image: `black-forest-labs/FLUX.1-dev`

#### **3. Guest Invite Email Agent** (`src/agents/guest_invite_email_agent.py`)
- **Capabilities**:
  - Parses CSV guest lists (name, email columns)
  - Composes personalized invitation emails using LLM
  - Sends emails via Resend MCP (Zapier Gmail integration)
  - Attaches invitation card images
- **Tools**:
  - `compose_invitation_email()`: Email content generation
  - `send_guest_invites_via_resend()`: Batch email sending

#### **4. Venue Search Agent** (`src/agents/venue_search_agent.py`)
- **Capabilities**:
  - Searches for party venues using Bright Data MCP SERP
  - Filters by location, budget, and guest count
  - Extracts and formats venue details (name, URL, rating, price, address, phone)
- **Tools**:
  - `search_party_venues()`: Venue discovery with intelligent query building
- **MCP Integration**: Bright Data MCP for Google/Bing search results

#### **5. Theme Decor/Favor Shop Agent** (`src/agents/theme_decor_favor_shop_agent.py`)
- **Capabilities**:
  - Generates theme-based shopping lists (decor + favors) using LLM
  - Optimizes Amazon search queries from item names
  - Integrates with Amazon MCP for product search
  - Builds shopping carts with product links and pricing
  - Supports Fewsats MCP for payment processing (future)
- **Tools**:
  - `generate_shopping_list_for_theme()`: Shopping list generation
  - `shop_on_amazon()`: Amazon cart building
- **Query Optimization**: Cleans item names, normalizes case, adds contextual keywords

### **Shared Context Management**

**`PartyContext`** (`src/party_context.py`) is a Pydantic model that serves as the single source of truth:

```python
class PartyContext(BaseModel):
    # Event metadata
    party_description: Optional[str]
    event_budget: Optional[str]
    event_location: Optional[str]
    event_date: Optional[str]
    
    # Theme management
    theme_options: List[ThemeOption]
    selected_theme_name: Optional[str]
    invitation_text: Optional[str]
    invitation_image_path: Optional[str]
    
    # Guest management
    guest_names: List[str]
    guest_emails: List[str]
    emails_sent: bool
    
    # Venue search
    venue_results: List[VenueResult]
    
    # Shopping
    cart_items: List[Dict[str, Any]]
    decor_items: List[ShoppingItem]
    favor_items: List[ShoppingItem]
    selected_items: List[str]
    order_status: Optional[str]
```

**Benefits**:
- **Type Safety**: Pydantic validation ensures data integrity
- **Global Access**: Single instance (`party_context`) accessible from all agents
- **State Persistence**: Maintains state throughout the conversation
- **Serialization**: Easy JSON conversion for LLM context summarization

### **MCP Client Architecture**

**`MCPConnectionManager`** (`src/mcp/mcp_clients.py`) provides a unified interface for all MCP servers:

- **Multi-Server Support**: Manages connections to multiple MCP servers simultaneously
- **Async Operations**: All MCP calls are asynchronous for better performance
- **Error Handling**: Graceful degradation when servers are unavailable
- **Tool Discovery**: Automatic tool loading from MCP servers

**Client Classes**:
- `AmazonMCPClient`: Product search and cart building
- `FewsatsMCPClient`: Payment processing (X402/L402 protocols)
- `ResendMCPClient`: Email sending via Zapier
- `BrightDataMCPClient`: SERP search for venues

---

## 🌍 Real-World Usefulness & Potential

### **Use Cases**
- **Personal events**: Birthday parties, anniversaries, graduations, baby showers, bridal showers
- **Corporate events**: Team building activities, company celebrations
- **Time-strapped planners**: Busy parents, event planners, small business owners
- **Budget-conscious users**: Cost-effective venue and decor options

### **Market Opportunity**
- Event planning industry: $5.6 billion globally
- Party supply market: $3.2 billion in the US
- Online event planning tools: Growing 15% annually

### **Competitive Advantages**
- **AI-powered personalization**: Age-appropriate, budget-aware theme generation
- **End-to-end solution**: Complete workflow (themes, venues, invites, shopping) in one place
- **Natural language interface**: No learning curve, conversational experience
- **Real-time MCP integration**: Live venue search, actual product pricing, direct email sending

### **Expansion Potential**
- **Short-term**: Multi-language support, calendar integration, RSVP management, budget tracking
- **Medium-term**: Mobile apps, social sharing, collaborative planning, vendor booking
- **Long-term**: Enterprise edition, API access, white-label solutions, VR previews

### **Monetization**
- Freemium model (free basic, premium $9.99/month)
- Commission-based (venue bookings, Amazon affiliate, vendor referrals)
- Enterprise licensing (B2B sales, custom integrations)
- API access (developer usage, white-label fees)

### **Social Impact**
- Makes professional planning accessible to everyone
- Reduces planning time from days to hours
- Eliminates stress of coordinating multiple vendors
- Helps small businesses (venues, vendors) reach more customers

---

## 🚀 Quick Start Guide

### **For End Users**

1. **Start a Conversation**
   ```
   "I want to plan a birthday party for my 6-year-old"
   ```

2. **Provide Details** (when asked)
   ```
   "Budget is under $500, in San Jose CA on June 10, 2025 for about 30 guests"
   ```

3. **Choose a Theme**
   - Review the 3 AI-generated options
   - Select via natural language: "I like the superhero theme"

4. **Find a Venue**
   - Ask: "Search for venues" or "Find venues near me"
   - Review results and book directly on venue websites

5. **Generate Invitation**
   - Click "Generate Invitation Card" button (appears when ready)
   - Review the custom invitation with embedded event details

6. **Send Invitations**
   - Upload CSV file with `name` and `email` columns
   - Ask: "Send the invitations"
   - Emails are sent automatically with invitation card attached

7. **Shop for Supplies**
   - Ask: "What decor items do you recommend?"
   - Select items from checkboxes
   - Ask: "Build my Amazon cart"
   - Review cart preview and click links to complete purchase

### **For Developers**

See [Setup & Configuration](#-setup--configuration) section below.

---

## ✨ Features

### **Core Features**

- 🎨 **AI Theme Generation**: 3 creative, age-appropriate theme options per party
- 🖼️ **Custom Invitation Cards**: AI-generated images with embedded event details using FLUX.1-dev
- 🏨 **Intelligent Venue Search**: Real-time venue discovery with ratings, pricing, and contact info
- 📧 **Automated Email Invitations**: Personalized emails sent via Resend MCP with invitation attachments
- 🛍️ **Smart Shopping Assistant**: Theme-based decor and favor recommendations with Amazon cart building
- 💬 **Natural Language Interface**: Plan entire party through conversational chat
- 📊 **CSV Guest Management**: Easy guest list upload and management

### **Advanced Features**

- **Multi-Agent Orchestration**: 4 specialized agents coordinated by intelligent orchestrator
- **Context-Aware Responses**: System remembers entire conversation and provides relevant suggestions
- **Progressive Information Gathering**: Only asks for details when needed
- **Real-time Cart Preview**: See shopping cart updates as you select items
- **Dynamic UI Updates**: Components appear/disappear based on workflow progress
- **Graceful Error Handling**: Clear, actionable error messages
- **MCP Integration**: Seamless integration with multiple external services

---

## 🛠️ Technology Stack

### **Core Frameworks**
- **LangChain**: Multi-agent orchestration and tool management
- **LangGraph**: Agent workflow management (future enhancement)
- **Gradio 6**: Modern web UI framework with advanced components
- **Pydantic**: Data validation and shared context models

### **AI Models** (via Hugging Face)
- **Text Generation**: `meta-llama/Llama-3.3-70B-Instruct`
- **Image Generation**: `black-forest-labs/FLUX.1-dev`

### **MCP Servers**
- **Bright Data MCP**: SERP search for venue discovery
- **Resend MCP** (via Zapier): Email sending with attachments
- **Amazon MCP**: Product search and cart building
- **Fewsats MCP**: Payment processing (X402/L402 protocols)

### **Supporting Libraries**
- **pandas**: CSV parsing for guest lists
- **Pillow**: Image processing for invitation cards
- **beautifulsoup4**: HTML parsing for venue search results
- **python-dotenv**: Environment variable management

---

## 📁 Project Structure

```
Plan-A-Party/
├── app.py                          # Main Gradio entrypoint
├── requirements.txt                # Python dependencies
├── Dockerfile                      # Docker configuration for Spaces
├── README.md                       # This file
├── PROJECT_SUMMARY.md              # Detailed architecture documentation
├── SRC_README.md                   # Source code documentation
│
├── invitations/                    # Generated invitation card images
│   └── invitation_*.png
│
└── src/
    ├── __init__.py
    ├── config.py                   # Configuration management
    ├── party_context.py            # Shared state (Pydantic models)
    │
    ├── agents/
    │   ├── __init__.py
    │   ├── orchestrator.py         # Main orchestrator agent
    │   ├── theme_planning_agent.py # Theme & invitation generation
    │   ├── guest_invite_email_agent.py # Email sending
    │   ├── venue_search_agent.py   # Venue discovery
    │   └── theme_decor_favor_shop_agent.py # Shopping assistant
    │
    ├── tools/
    │   ├── __init__.py
    │   └── csv_guest_parser.py     # CSV parsing utility
    │
    ├── mcp/
    │   ├── __init__.py
    │   └── mcp_clients.py          # MCP client integrations
    │
    └── ui/
        ├── __init__.py
        └── gradio_ui.py            # Gradio interface implementation
```

---

## 🔌 MCP Integrations

### **Bright Data MCP** (Venue Search)
- **Purpose**: Real-time venue discovery via SERP search
- **Tools Used**: `search_engine` (Google/Bing search)
- **Features**:
  - Location-based search
  - Budget and guest count filtering
  - Rating and pricing extraction
  - Direct booking links

### **Resend MCP** (Email Sending)
- **Purpose**: Send invitation emails with attachments
- **Integration**: Via Zapier Gmail API
- **Features**:
  - Personalized email composition
  - Invitation card attachments
  - Batch sending to multiple recipients
  - Delivery status tracking

### **Amazon MCP** (Shopping)
- **Purpose**: Product search and cart building
- **Features**:
  - Intelligent query optimization
  - Product matching and pricing
  - Shopping cart assembly
  - Direct purchase links
- **Status**: Optional (requires Node.js build)

### **Fewsats MCP** (Payments)
- **Purpose**: Payment processing for orders
- **Protocols**: X402 and L402
- **Features**:
  - Payment header generation
  - Offer management
  - Order tracking
- **Status**: Future enhancement

---

## 📝 Example Workflows

### **Example 1: Children's Birthday Party**

```
User: "I want to plan a birthday party for my 6-year-old"

Assistant: "Awesome! 🎉 I can help you plan your private party end-to-end...
            First, tell me a few basics:
            1) Your approximate budget
            2) The city/state location
            3) The date of the event"

User: "Budget is under $500, in San Jose CA on June 10, 2025 for about 30 kids"

Assistant: "Perfect! Here's what I have so far:
            - Budget: under $500
            - Location: San Jose CA
            - Date: June 10, 2025
            
            🎨 I've generated 3 theme options for you:
            
            1. Superhero Adventure
               A thrilling superhero-themed party with capes, masks, and heroic activities...
            
            2. Princess Enchanted Garden
               A magical princess party with tiaras, wands, and fairy tale decorations...
            
            3. Space Explorer Mission
               An out-of-this-world space adventure with rockets, planets, and astronaut activities...
            
            👉 Tell me which theme you'd like to use..."

User: "I like the superhero one"

Assistant: "Great choice! You've selected Superhero Adventure 🎉
            Before we create your invitation card, let's find a venue.
            I can search for party venues near San Jose CA within your budget.
            👉 Would you like me to search for some venue options now?"

User: "Yes, please search for venues"

Assistant: "Here are some venue options I found in San Jose CA:
            
            1. Kids' Party Place
               – Family-friendly venue perfect for superhero parties
               • 📍 Address: 123 Main St, San Jose, CA
               • ⭐ Approx. rating: 4.5/5
               • 💰 Price indication: $$
               • 🔗 More details: [venue website]
            
            [More venues...]
            
            🔔 Please review these options and reserve your favorite venue.
            Once you've booked one, tell me which venue you chose..."

User: "We booked Kids' Party Place"

Assistant: "Awesome — venue locked in and theme selected! 🎉
            I've created your invitation card using your date, location and theme.
            You'll see the image below in the UI.
            
            Next, please upload your guest list CSV using the Guest List CSV uploader,
            and I'll help you send this invitation to all your guests."
```

### **Example 2: Corporate Team Building Event**

```
User: "Planning a team building event for 50 people"

Assistant: [Asks for budget, location, date]

User: "$2000 budget, Mountain View CA, September 15, 2025"

Assistant: [Generates corporate-appropriate themes]

User: "Let's go with the outdoor adventure theme"

Assistant: [Searches for venues suitable for team building]

User: [Books venue, uploads guest list, sends invitations]

Assistant: [Generates shopping list for team building activities and supplies]
```

---

## ⚙️ Setup & Configuration

### **Environment Variables**

Required:
- `HUGGINGFACEHUB_API_TOKEN` or `HF_TOKEN`: Hugging Face API token for model access

Optional (for full functionality):
- `BRIGHTDATA_TOKEN`: Bright Data API token for venue search
- `ZAPIER_GMAIL_API_KEY`: Zapier API key for email sending
- `FEWSATS_API_KEY`: Fewsats API key for payment processing

### **Local Development**

```bash
# Clone repository
git clone <repository-url>
cd Plan-A-Party

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export HUGGINGFACEHUB_API_TOKEN="your_token"
export BRIGHTDATA_TOKEN="your_token"  # Optional
export ZAPIER_GMAIL_API_KEY="your_key"  # Optional

# Run application
python app.py
```


### **Guest List CSV Format**

Your CSV file should have the following columns:
- `name`: Guest's name
- `email`: Guest's email address

Example:
```csv
name,email
John Doe,john@example.com
Jane Smith,jane@example.com
```

---

## 🐛 Known Limitations

1. **Amazon MCP**: Requires Node.js build (optional feature)
2. **Email Sending**: Requires Zapier Gmail API key configuration
3. **Venue Search**: Requires Bright Data token for full functionality
4. **Image Generation**: Speed depends on FLUX.1-dev API availability
5. **Session Persistence**: Chat history not persisted across browser sessions
6. **Payment Processing**: Fewsats integration is prepared but not fully implemented

---
## 🎬 Demo and Social Media Post

- Demo video link 
   https://drive.google.com/drive/folders/1fHQCAJUVrTFX3JinAXuc-cvWtV_Qen-X?usp=sharing

- LinkedIn post link
   https://www.linkedin.com/feed/update/urn:li:activity:7401038429691756545/

---
## 👥 Plan-A-Party Team members

- AryamaR
- Tanmoys2905

## 📚 Additional Resources

- **Detailed Architecture**: See `PROJECT_SUMMARY.md` for comprehensive system design
- **Source Code Documentation**: See `SRC_README.md` for code-level details
- **Hugging Face Spaces**: [View Live Demo](https://huggingface.co/spaces)

---

## 🤝 Contributing

This project was built for the **Hugging Face MCP Hackathon**. Feedbacks are welcome!

---

## 📄 License

MIT License - see LICENSE file for details

---

## 🙏 Acknowledgments

- **Hugging Face** for providing the Inference API and model hosting
- **LangChain** team for the excellent agent framework
- **Gradio** team for the powerful UI framework
- **MCP Contributors** for the Model Context Protocol implementations
- **Bright Data, Zapier, Amazon, Fewsats** for MCP server integrations

---

**Built for Hugging Face MCP Hackathon** 🎉

*Made with ❤️ using LangChain, Gradio 6, and Model Context Protocol*