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:**
   ```bash
   cd plan-a-party
   ```

2. **Create a virtual environment:**
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

3. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

4. **Set up environment variables:**
   Create a `.env` file or set environment variables:
   ```bash
   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):**
   ```bash
   cd amazon-mcp
   npm install
   npm run build
   cd ..
   ```

### Environment Variables

Create a `.env` file or set these environment variables:

```ini
# 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

```bash
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:

```csv
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:

```python
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** 🎉