SRC_README.md

🎉 Plan-a-Party Multi-Agent System

A comprehensive party planning system built with LangChain and Gradio, featuring multiple specialized AI agents that work together through an interactive conversational interface to help you plan the perfect party!

✨ Features

🤖 Multi-Agent Architecture

1. Theme Planning Agent - Generates creative party themes and creates beautiful 4x4 invitation cards using FLUX.1-dev
2. Guest Invite Email Agent - Manages guest lists from CSV and sends personalized invitation emails via Resend MCP
3. Venue Search Agent - Searches for party venues using Bright Data MCP SERP search
4. Theme Decor/Favor Shop Agent - Generates shopping lists and builds Amazon carts with intelligent query optimization

🎨 Key Capabilities

• Interactive Chat Interface - Natural language conversation to guide party planning
• Event Metadata Collection - Captures budget, location, and date through conversation
• Theme Generation - AI generates 3 creative, age-appropriate party themes
• Natural Language Theme Selection - Select themes directly in chat (e.g., "I like the first one")
• Invitation Cards - Beautiful 4x4 invitation cards with custom text and images using FLUX.1-dev
• Email Automation - Send invitations to multiple guests via Resend MCP
• Venue Discovery - Search for party venues using Bright Data SERP with location, budget, and guest count filters
• Smart Shopping - Generate theme-based shopping lists with Amazon-optimized search queries
• Cart Building - Build Amazon shopping carts with product links and pricing

🚀 Setup

Prerequisites

• Python 3.8+
• Hugging Face account with API token
• (Optional) Bright Data token for venue search
• (Optional) Zapier Gmail API key for Resend MCP email sending
• (Optional) Amazon MCP server (requires Node.js) for shopping
• (Optional) Fewsats API key for payment processing

Installation

1. Clone or navigate to the project directory:

   cd plan-a-party
   

2. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Set up environment variables: Create a .env file or set environment variables:

   export HUGGINGFACEHUB_API_TOKEN=your_token_here
   export HF_TOKEN=your_token_here
   export BRIGHTDATA_TOKEN=your_brightdata_token  # Optional
   export ZAPIER_GMAIL_API_KEY=your_zapier_key    # Optional
   export FEWSATS_API_KEY=your_fewsats_key        # Optional
   

5. Set up Amazon MCP (Optional):

   cd amazon-mcp
   npm install
   npm run build
   cd ..
   

Environment Variables

Create a .env file or set these environment variables:

# Required
HUGGINGFACEHUB_API_TOKEN=your_token_here
HF_TOKEN=your_token_here

# Optional - for venue search
BRIGHTDATA_TOKEN=your_brightdata_token

# Optional - for email sending
ZAPIER_GMAIL_API_KEY=your_zapier_key

# Optional - for Amazon shopping
FEWSATS_API_KEY=your_fewsats_key

🎯 Usage

Running Locally

python app.py

The Gradio interface will launch at http://localhost:7860

Running on Hugging Face Spaces

1. Push this repository to Hugging Face Spaces
2. Set environment variables in Space settings
3. The app will automatically deploy!

📋 Interactive Workflow

The app uses a conversational interface where you interact naturally:

1. Start Planning → Describe your party (e.g., "I want to plan a birthday party for my 6 year old kid")
2. Provide Details → System asks for budget, location, and date (e.g., "Budget is under $500, in San Jose CA on June 10, 2025")
3. Theme Generation → System automatically generates 3 theme options
4. Select Theme → Choose a theme in natural language (e.g., "I like the first one" or "Let's go with the Minecraft theme")
5. Generate Invitation → Click "Generate Invitation Card" button (appears when all info is ready)
6. Find Venues → Ask to search for venues (e.g., "Search for venues") - uses your stored location
7. Upload Guest List → Upload CSV with name and email columns
8. Send Invitations → Ask to send invitations (e.g., "Send the invitations")
9. Shop for Decor → Ask about shopping (e.g., "What decor items do you recommend?")
10. Build Cart → Select items and ask to build Amazon cart

📁 Project Structure

plan-a-party/
├── app.py                      # Gradio entrypoint
├── requirements.txt            # Python dependencies
├── README.md                   # This file
├── PROJECT_SUMMARY.md          # Detailed architecture documentation
├── .env.example               # Example environment variables
├── invitations/               # Generated invitation card images
└── src/
    ├── config.py              # Configuration management
    ├── party_context.py       # Shared state between agents (Pydantic models)
    ├── agents/
    │   ├── orchestrator.py    # Main orchestrator agent (conversational flow)
    │   ├── theme_planning_agent.py
    │   ├── guest_invite_email_agent.py
    │   ├── venue_search_agent.py
    │   └── theme_decor_favor_shop_agent.py
    ├── tools/
    │   └── csv_guest_parser.py
    ├── mcp/
    │   └── mcp_clients.py     # MCP clients (Amazon, Fewsats, Resend, BrightData)
    └── ui/
        └── gradio_ui.py       # Gradio interface (interactive chat)

🔧 Technologies Used

• LangChain - Agent framework and tool orchestration
• Gradio - Interactive web UI framework
• Hugging Face - Open-source LLMs and image generation
  • Mistral-7B-Instruct-v0.3 - Text generation
  • FLUX.1-dev - Image generation for invitation cards
• MCP (Model Context Protocol) - Integration protocol for external services
  • Bright Data MCP - SERP search for venue discovery
  • Resend MCP - Email sending via Zapier
  • Amazon MCP - Product search and cart building
  • Fewsats MCP - Payment processing (X402/L402 protocols)
• Pydantic - Data validation and shared context models
• Pandas - CSV processing

📝 CSV Format for Guest List

Your guest list CSV should have two columns:

name,email
John Doe,john@example.com
Jane Smith,jane@example.com

🎨 Architecture Highlights

Shared Context (PartyContext)

• Centralized state management using Pydantic models
• Stores event metadata (budget, location, date)
• Manages theme options and selections
• Tracks guest lists, venue results, and shopping cart items

Conversational Flow

• Multi-turn dialogue to progressively gather requirements
• Natural language understanding for theme selection
• Context-aware responses based on collected information
• Dynamic UI updates based on conversation state

MCP Integration

• Graceful Degradation - App works even if optional MCP servers are unavailable
• Bright Data - Real-time SERP search for venue discovery
• Resend - Reliable email delivery via Zapier integration
• Amazon - Optional shopping with intelligent query optimization
• Fewsats - Payment processing for future order placement

Query Optimization

• Amazon search queries are automatically optimized from item names
• Strips descriptions, normalizes case, and adds relevant keywords
• Improves product matching accuracy

🛠️ Development

Adding New Agents

1. Create a new file in src/agents/
2. Implement agent functions with @tool decorators
3. Add agent wrapper to orchestrator in src/agents/orchestrator.py
4. Update TOOL_ROUTER dictionary in orchestrator
5. Update Gradio UI if needed

Testing

Each agent can be tested independently:

from src.agents.theme_planning_agent import generate_party_themes

result = generate_party_themes.invoke({
    "party_description": "Birthday party for 5 year old"
})
print(result)

🔮 Future Enhancements

• Order tracking and status updates
• Multi-language support
• Theme customization options
• Calendar integration for date selection
• Budget tracking and alerts
• Guest RSVP management
• Venue booking integration

📄 License

This project is open source and available for the Hugging Face MCP Hackathon.

🤝 Contributing

This is a hackathon project. Feel free to fork and extend!

🙏 Acknowledgments

• Hugging Face for open-source models and infrastructure
• LangChain team for the agent framework
• Bright Data for SERP search capabilities
• All open-source contributors

---

Built for the Hugging Face MCP-1st-Birthday Hackathon 🎉