Added application code base & container manifest

Dockerfile

@@ -0,0 +1,39 @@
+# Simple working Dockerfile for Plan-A-Party
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    curl \
+    ca-certificates \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy Python requirements and install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create invitations directory
+RUN mkdir -p /app/invitations
+
+# Set environment variables for Gradio
+ENV GRADIO_SERVER_NAME="0.0.0.0"
+ENV GRADIO_SERVER_PORT=7860
+ENV PYTHONUNBUFFERED=1
+
+# Expose Gradio port
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:7860/ || exit 1
+
+# Run the application
+CMD ["python", "app.py"]
+

PROJECT_SUMMARY.md

@@ -0,0 +1,360 @@
+# Plan-a-Party Multi-Agent System - Project Summary
+
+## 🎯 Project Overview
+
+A complete multi-agent party planning system built with LangChain and Gradio, featuring 4 specialized subagents coordinated by an orchestrator agent. The system uses an interactive conversational interface where users plan parties through natural language dialogue, with all agents sharing state through a centralized `PartyContext` model.
+
+## 📁 Complete File Structure
+
+```
+plan-a-party/
+├── app.py                          # Main Gradio entrypoint
+├── requirements.txt                 # Python dependencies
+├── README.md                       # Main documentation
+├── PROJECT_SUMMARY.md              # This file (detailed architecture)
+├── .env.example                    # Environment variables template
+├── .gitignore                      # Git ignore rules
+├── invitations/                    # Generated invitation card images
+│   └── invitation_*.png          # Theme-based invitation cards
+└── src/
+    ├── __init__.py
+    ├── config.py                   # Configuration management (model IDs, etc.)
+    ├── party_context.py            # Shared state (Pydantic models)
+    ├── agents/
+    │   ├── __init__.py
+    │   ├── orchestrator.py         # Main orchestrator agent (conversational flow)
+    │   ├── theme_planning_agent.py  # Subagent 1: Themes & invitations
+    │   ├── guest_invite_email_agent.py # Subagent 2: Email sending via Resend MCP
+    │   ├── venue_search_agent.py   # Subagent 3: Bright Data SERP venue search
+    │   └── theme_decor_favor_shop_agent.py # Subagent 4: Shopping with Amazon MCP
+    ├── tools/
+    │   ├── __init__.py
+    │   └── csv_guest_parser.py     # CSV parsing utility for guest lists
+    ├── mcp/
+    │   ├── __init__.py
+    │   └── mcp_clients.py          # MCP clients (Amazon, Fewsats, Resend, BrightData)
+    └── ui/
+        ├── __init__.py
+        └── gradio_ui.py            # Gradio interface (interactive chat UI)
+```
+
+## 🤖 Agent Architecture
+
+### Orchestrator Agent
+- **File**: `src/agents/orchestrator.py`
+- **Role**: Coordinates all subagents using conversational flow management
+- **Key Features**:
+  - **Multi-turn Dialogue**: Progressively collects event details (budget, location, date)
+  - **Natural Language Understanding**: Extracts information from user messages
+  - **Automatic Theme Generation**: Triggers theme generation once party description is provided
+  - **Theme Selection Detection**: Recognizes theme selection from natural language
+  - **Tool Routing**: Routes requests to appropriate subagents based on context
+  - **State Management**: Updates `PartyContext` throughout the conversation
+  - **LLM-based Decision Making**: Uses Hugging Face LLM to decide next actions
+
+**Key Functions**:
+- `orchestrator_chat(user_message, chat_history)` - Main conversational handler
+- `extract_event_details_from_message(message)` - Extracts budget, location, date
+- `extract_theme_selection_from_message(message)` - Detects theme selection
+- `decide_next_action(user_message, context)` - LLM-based routing
+- Wrapper functions for each subagent tool
+
+### Subagent 1: Theme Planning Agent
+- **File**: `src/agents/theme_planning_agent.py`
+- **Capabilities**:
+  - Generates 3 creative party theme options using LLM
+  - Creates invitation text with event details (date, location, budget)
+  - Generates 4x4 invitation card images using FLUX.1-dev
+  - Embeds event metadata in invitation images
+- **Tools**: 
+  - `generate_party_themes(party_description)` - Generates 3 theme options
+  - `generate_invitation_for_theme(selected_theme_name)` - Creates invitation card
+- **Models Used**:
+  - **meta-llama/Llama-3.3-70B-Instruct** - Text generation
+  - **FLUX.1-dev** - Image generation
+
+### Subagent 2: Guest Invite Email Agent
+- **File**: `src/agents/guest_invite_email_agent.py`
+- **Capabilities**:
+  - Parses guest lists from CSV files
+  - Composes personalized invitation emails using LLM
+  - Sends emails via Resend MCP (Zapier integration)
+  - Attaches invitation card images to emails
+- **Tools**: 
+  - `compose_invitation_email()` - Generates email subject and body
+  - `send_guest_invites_via_resend()` - Sends emails to all guests
+- **MCP Integration**: Resend MCP via Zapier Gmail API
+
+### Subagent 3: Venue Search Agent
+- **File**: `src/agents/venue_search_agent.py`
+- **Capabilities**:
+  - Searches for party venues using Bright Data MCP SERP search
+  - Filters by location, budget, and guest count
+  - Extracts venue details (name, URL, rating, price, address, phone)
+  - Formats results for display in chat
+- **Tools**: 
+  - `search_party_venues(location, query, max_results, budget, guest_count)` - Searches venues
+- **MCP Integration**: Bright Data MCP for SERP search
+- **Query Building**: Constructs natural-language queries with filters
+
+### Subagent 4: Theme Decor/Favor Shop Agent
+- **File**: `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(theme_name)` - Generates shopping list
+  - `shop_on_amazon(selected_items, ...)` - Builds Amazon cart
+- **MCP Integration**: 
+  - Amazon MCP (optional, requires Node.js build)
+  - Fewsats MCP (for payment processing)
+- **Query Optimization**: 
+  - `build_amazon_query_from_item_name()` - Cleans item names for better Amazon searches
+  - Strips descriptions, normalizes case, adds "party" keyword when appropriate
+
+## 🛠️ Supporting Components
+
+### Shared Context (`PartyContext`)
+- **File**: `src/party_context.py`
+- **Purpose**: Centralized state management using Pydantic models
+- **Key Fields**:
+  - `event_budget`, `event_location`, `event_date` - Event metadata
+  - `theme_options`, `selected_theme_name` - Theme management
+  - `invitation_text`, `invitation_image_path` - Invitation data
+  - `guest_names`, `guest_emails`, `emails_sent` - Guest list management
+  - `venue_results`, `search_location` - Venue search results
+  - `cart_items`, `decor_items`, `favor_items` - Shopping data
+  - `selected_items`, `order_status`, `order_id` - Order management
+
+### MCP Clients
+- **File**: `src/mcp/mcp_clients.py`
+- **Architecture**: 
+  - `MCPConnectionManager` - Manages connections to all MCP servers
+  - Individual client classes for each service
+- **Clients**:
+  - **AmazonMCPClient** - Product search and cart building (optional, requires build)
+  - **FewsatsMCPClient** - Payment processing with X402/L402 protocols
+  - **ResendMCPClient** - Email sending via Zapier
+  - **BrightDataMCPClient** - SERP search for venues
+- **Graceful Degradation**: Checks for server availability before use
+
+### Tools
+- **CSV Parser** (`src/tools/csv_guest_parser.py`): Handles guest list uploads
+- **Query Builder** (`src/agents/theme_decor_favor_shop_agent.py`): Optimizes Amazon searches
+
+## 🎨 User Interface
+
+### Gradio UI Features
+- **File**: `src/ui/gradio_ui.py`
+- **Design**: Single-page conversational interface (not tab-based)
+- **Key Components**:
+  - **Interactive Chat** - Main conversation area with chatbot
+  - **Cart Preview** - Real-time shopping cart display
+  - **Generate Invitation Card Button** - Appears when all info is ready
+  - **Guest List Upload** - CSV file upload with status display
+  - **Shopping Checkboxes** - Item selection for decor and favors
+  - **Quick Hints** - Suggested workflow guide
+
+### UI Flow
+1. User types party description in chat
+2. System asks for budget, location, date
+3. System generates themes and displays in chat
+4. User selects theme via natural language
+5. "Generate Invitation Card" button becomes visible
+6. User clicks button to generate invitation
+7. User can upload guest list and send invitations
+8. User can search for venues via chat
+9. User can shop for decor/favors via chat
+
+### State Management
+- Uses `gr.State` for chat history
+- Updates `PartyContext` throughout conversation
+- Dynamic UI updates based on context state
+- Button visibility controlled by collected information
+
+## 🔧 Technology Stack
+
+- **LangChain** - Agent framework and tool orchestration
+- **Gradio** - Interactive web UI framework
+- **Hugging Face**:
+  - **Mistral-7B-Instruct-v0.3** - Text generation for all agents
+  - **FLUX.1-dev** - Image generation for invitation cards
+  - **Inference API** - Model access
+- **MCP (Model Context Protocol)**:
+  - **Bright Data MCP** - SERP search for venue discovery
+  - **Zapier MCP** - Email sending via Zapier
+  - **Amazon MCP** - Product search and cart building (optional)
+  - **Fewsats MCP** - Payment processing (X402/L402)
+- **Pydantic** - Data validation and shared context models
+- **Pandas** - CSV processing
+- **langchain-mcp-adapters** - MCP integration library
+
+## 🚀 Deployment
+
+### Local Development
+```bash
+python app.py
+```
+App runs at `http://localhost:7860`
+
+### Hugging Face Spaces
+1. Push repository to Hugging Face Spaces
+2. Set environment variables in Space settings:
+   - `HUGGINGFACEHUB_API_TOKEN`
+   - `HF_TOKEN`
+   - `BRIGHTDATA_TOKEN` (optional)
+   - `ZAPIER_GMAIL_API_KEY` (optional)
+   - `FEWSATS_API_KEY` (optional)
+3. Space auto-deploys
+
+### Amazon MCP Setup (Optional)
+```bash
+cd amazon-mcp
+npm install
+npm run build
+cd ..
+```
+
+## 📋 Complete Workflow
+
+### 1. Initial Conversation
+- User: "I want to plan a birthday party for my 6 year old kid"
+- System: Stores party description, asks for budget, location, date
+
+### 2. Event Details Collection
+- User: "Budget is under $500, in San Jose CA on June 10, 2025"
+- System: Extracts and stores event metadata
+
+### 3. Theme Generation
+- System: Automatically calls `generate_party_themes`
+- System: Displays 3 theme options in chat
+
+### 4. Theme Selection
+- User: "I like the first one" or "Let's go with the Minecraft theme"
+- System: Detects selection, updates `selected_theme_name`
+
+### 5. Invitation Generation
+- System: "Generate Invitation Card" button becomes visible
+- User: Clicks button
+- System: Calls `generate_invitation_for_theme`
+- System: Creates invitation text and image, displays in UI
+
+### 6. Venue Search
+- User: "Search for venues" or "Find venues near me"
+- System: Calls `search_party_venues` with stored location
+- System: Displays formatted venue results in chat
+
+### 7. Guest List Management
+- User: Uploads CSV file
+- System: Parses CSV, stores guest names and emails
+- System: Displays status
+
+### 8. Email Sending
+- User: "Send the invitations" or "Send emails"
+- System: Calls `compose_invitation_email` and `send_guest_invites_via_resend`
+- System: Sends emails with invitation card attachments
+
+### 9. Shopping
+- User: "What decor items do you recommend?" or "Show me shopping options"
+- System: Calls `generate_shopping_list_for_theme`
+- System: Displays items in checkboxes
+- User: Selects items, clicks "Save selected items"
+- User: "Build my Amazon cart" or "Shop on Amazon"
+- System: Calls `shop_on_amazon` with selected items
+- System: Builds cart, displays products with links and prices
+
+## ✅ Implementation Status
+
+- [x] Folder structure created
+- [x] All 4 subagents implemented
+- [x] Orchestrator agent with conversational flow
+- [x] Gradio UI with interactive chat
+- [x] Shared context management (PartyContext)
+- [x] MCP integration (Bright Data, Resend, Amazon, Fewsats)
+- [x] CSV parsing for guest lists
+- [x] Theme generation with FLUX.1-dev
+- [x] Email sending via Resend MCP
+- [x] Venue search via Bright Data SERP
+- [x] Amazon shopping with query optimization
+- [x] Natural language theme selection
+- [x] Event metadata collection
+- [x] Dynamic UI updates
+- [x] Graceful degradation for optional MCP servers
+- [x] Documentation (README, PROJECT_SUMMARY)
+
+## 🔮 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
+- [ ] Real-time order placement with Fewsats
+- [ ] Image customization options
+- [ ] Multiple invitation card styles
+
+## 📝 Key Design Decisions
+
+### Conversational Interface
+- Chose chat-based UI over tab-based for better user experience
+- Natural language interaction feels more intuitive
+- Progressive information gathering through dialogue
+
+### Shared Context
+- Centralized state management prevents data duplication
+- Pydantic models ensure type safety
+- Global instance allows easy access across agents
+
+### MCP Integration
+- Graceful degradation ensures app works even if optional services unavailable
+- Clear error messages guide users on setup
+- Modular design allows easy addition of new MCP servers
+
+### Query Optimization
+- Amazon search queries optimized from item names
+- Improves product matching accuracy
+- Reduces failed searches
+
+### Open Source Models
+- All models are open-source (Mistral-7B, FLUX.1-dev)
+- No proprietary dependencies
+- Accessible via Hugging Face Inference API
+
+## 🔐 Security & Privacy
+
+- All API keys stored as environment variables
+- No hardcoded credentials
+- Guest data only stored in session (not persisted)
+- Email sending requires explicit user action
+- Amazon shopping is demo mode (no real orders)
+
+## 📊 Performance Considerations
+
+- LLM calls have timeouts to prevent hanging
+- MCP calls are async for better performance
+- Image generation cached in `invitations/` directory
+- Chat history managed efficiently with Gradio State
+- Query optimization reduces failed Amazon searches
+
+## 🐛 Known Limitations
+
+- Amazon MCP requires Node.js build (optional)
+- Email sending requires Zapier Gmail API key
+- Venue search requires Bright Data token
+- Image generation can be slow (depends on FLUX.1-dev API)
+- Chat history not persisted across sessions
+
+## 📚 Additional Resources
+
+- See `README.md` for quick start guide
+- See `src/deployment/` for deployment documentation
+- See individual agent files for detailed implementation
+
+---
+
+**Built for Hugging Face MCP Hackathon** 🎉

README.md

@@ -1,12 +1,251 @@
----
-title: Plan A Party
-emoji: 🏃
-colorFrom: red
-colorTo: red
-sdk: docker
-pinned: false
-license: mit
-short_description: AI-Powered Private Event Planner
+# 🎉 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
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+**Built for the Hugging Face MCP-1st-Birthday Hackathon** 🎉

app.py

@@ -0,0 +1,7 @@
+# app.py
+from src.ui.gradio_ui import build_interface
+
+demo = build_interface()
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860)

requirements.txt

@@ -0,0 +1,15 @@
+langchain>=0.1.0
+langgraph>=0.0.40
+langchain-huggingface>=0.0.1
+langchain-mcp-adapters>=0.1.0
+huggingface_hub>=0.20.0
+gradio>=4.0.0
+pandas>=2.0.0
+python-dotenv>=1.0.0
+requests>=2.31.0
+pydantic>=2.0.0
+pillow>=10.0.0
+beautifulsoup4>=4.12.0
+lxml>=4.9.0
+email-validator>=2.0.0
+

src/__init__.py

@@ -0,0 +1,2 @@
+"""Plan-a-Party multi-agent system."""
+

src/agents/__init__.py

@@ -0,0 +1,2 @@
+"""Agent modules for Plan-a-Party system."""
+

src/agents/guest_invite_email_agent.py

@@ -0,0 +1,324 @@
+# src/agents/guest_invite_email_agent.py
+
+"""
+Guest-Invite Email Agent (LangChain + Resend MCP)
+
+- Composes invitation email subject/body from party context
+- Sends emails to all guests via Resend MCP "send_email" tool
+- Exposes `guest_invite_tool` for orchestrator / other agents
+"""
+
+import os
+import json
+import asyncio
+from typing import List, Dict, Tuple, Optional
+
+from langchain_core.tools import tool, Tool
+from langchain_core.messages import HumanMessage
+# Note: AgentExecutor removed - using tools directly
+from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint
+
+from langchain_mcp_adapters.client import MultiServerMCPClient
+
+from src.config import TEXT_MODEL
+from src.party_context import party_context
+
+
+# -------------------------------------------------------------------
+# 1. LLM for generating subject/body
+# -------------------------------------------------------------------
+
+def get_text_llm() -> ChatHuggingFace:
+    """Open-source HF model for email copy generation."""
+    llm = HuggingFaceEndpoint(
+        repo_id=TEXT_MODEL,
+        task="text-generation",
+        max_new_tokens=512,
+        temperature=0.7,
+        do_sample=True,
+    )
+    return ChatHuggingFace(llm=llm)
+
+
+text_llm = get_text_llm()
+
+
+# -------------------------------------------------------------------
+# 2. Resend MCP tooling
+# -------------------------------------------------------------------
+
+async def _get_resend_send_email_tool_async():
+    """
+    Initialize MultiServerMCPClient for the Resend MCP server and
+    return the `send_email` tool.
+
+    You MUST have the Resend MCP server build path and RESEND_API_KEY
+    configured via environment variables.
+    """
+
+    zapier_gmail_api_key = os.getenv("ZAPIER_GMAIL_API_KEY")
+    if not zapier_gmail_api_key:
+        raise ValueError(
+            "ZAPIER_GMAIL_API_KEY not set. "
+            "Get it from the Zapier dashboard."
+        )
+    
+    # Strip surrounding quotes if present (common issue from .env files)
+    zapier_gmail_api_key = zapier_gmail_api_key.strip('"').strip("'")
+
+    client = MultiServerMCPClient(
+        {
+            "zapier_gmail": {
+                "url": "https://mcp.zapier.com/api/mcp/s/" + zapier_gmail_api_key + "/mcp",
+                "transport": "streamable_http",  # Zapier MCP uses HTTP/JSON
+            }
+        }
+    )
+
+    # Get tools from all configured servers
+    tools = await client.get_tools()
+
+    # Find the gmail_send_email tool (name comes from the MCP server)
+    send_tool = None
+    for t in tools:
+        print(f"[get_resend_send_email_tool_async] Tool name: {t.name}")
+        if t.name == "gmail_send_email":
+            send_tool = t
+            break
+
+    if send_tool is None:
+        raise RuntimeError("Could not find 'gmail_send_email' tool from Zapier Gmail MCP server.")
+
+    return client, send_tool
+
+
+def _get_resend_send_email_tool_sync():
+    """Sync wrapper for getting the Zapier Gmail gmail_send_email tool."""
+    try:
+        # Check if there's already a running event loop
+        loop = asyncio.get_running_loop()
+        # If we reach here, there IS a running loop - we need to create a task
+        # This shouldn't normally happen in our sync context, but handle it gracefully
+        raise RuntimeError(
+            "Cannot call _get_resend_send_email_tool_sync from an async context. "
+            "Use _get_resend_send_email_tool_async instead."
+        )
+    except RuntimeError as e:
+        if "no running event loop" in str(e):
+            # No running loop - safe to use asyncio.run()
+            return asyncio.run(_get_resend_send_email_tool_async())
+        else:
+            # Different RuntimeError - re-raise it
+            raise
+
+
+# -------------------------------------------------------------------
+# 3. Tools: Compose subject/body + send via Resend MCP
+# -------------------------------------------------------------------
+
+@tool
+def compose_invitation_email() -> str:
+    """
+    Compose a subject and email body using the shared party_context.
+
+    Requires:
+        - party_context.party_description (optional but helpful)
+        - party_context.selected_theme_name
+        - party_context.invitation_text
+
+    Returns:
+        JSON string: {"subject": "...", "body": "..."}
+    """
+    if not party_context.invitation_text or not party_context.selected_theme_name:
+        return json.dumps(
+            {
+                "error": "invitation_text or selected_theme_name missing in party_context"
+            }
+        )
+
+    prompt = f"""
+You are writing an email invitation for a kids' party.
+
+Party description:
+{party_context.party_description}
+
+Selected theme:
+{party_context.selected_theme_name}
+
+Invitation card text:
+{party_context.invitation_text}
+
+Task:
+1. Create a concise, fun email subject line (max 10 words).
+2. Create a friendly email body that:
+   - Greets the recipient by name placeholder: {{guest_name}}
+   - Summarizes the party
+   - Mentions key details from the invitation
+   - Includes a polite RSVP request
+
+Return ONLY valid JSON:
+{{
+  "subject": "...",
+  "body": "..."
+}}
+"""
+    resp = text_llm.invoke([HumanMessage(content=prompt)])
+    content = resp.content
+
+    # Try to parse JSON
+    try:
+        data = json.loads(content)
+    except Exception:
+        start = content.find("{")
+        end = content.rfind("}")
+        json_str = content[start : end + 1]
+        data = json.loads(json_str)
+
+    # Optionally store in context if you add these fields
+    # party_context.email_subject = data.get("subject")
+    # party_context.email_body_template = data.get("body")
+
+    return json.dumps(data, ensure_ascii=False)
+
+
+@tool
+async def send_guest_invites_via_resend() -> str:
+    """
+    Send the invitation email to all guests in party_context via Resend MCP.
+
+    Requires:
+        - party_context.guest_names
+        - party_context.guest_emails
+        - party_context.invitation_text
+        - party_context.selected_theme_name
+
+    Behavior:
+        - Uses compose_invitation_email() to get subject/body
+        - For each guest, personalizes body using guest name
+        - Calls Resend MCP `send_email` tool
+        - Returns a summary string of send results
+    """
+    if not party_context.guest_emails:
+        return "No guest emails found in party_context.guest_emails."
+
+    if not party_context.invitation_text or not party_context.selected_theme_name:
+        return (
+            "Cannot send invites: invitation_text or selected_theme_name "
+            "missing in party_context."
+        )
+
+    # 1. Get subject/body
+    summary_json = compose_invitation_email.invoke({})
+    try:
+        summary = json.loads(summary_json)
+    except Exception:
+        return f"Could not parse composed email JSON: {summary_json}"
+
+    subject = summary.get("subject", "You're invited!")
+    body_template = summary.get("body", party_context.invitation_text)
+
+    sender_email = os.getenv("SENDER_EMAIL_ADDRESS", "onboarding@resend.dev")
+
+    # 2. Load Resend MCP tool (async)
+    client, send_tool = await _get_resend_send_email_tool_async()
+
+    # 3. Send to each guest
+    results = []
+    print(f"[send_guest_invites_via_resend] Sending to {len(party_context.guest_emails)} guests")
+    names = party_context.guest_names or [""] * len(party_context.guest_emails)
+
+    for name, email in zip(names, party_context.guest_emails):
+        guest_name = name or "there"
+        # Simple personalization
+        body = body_template.replace("{guest_name}", guest_name)
+
+        # Clean up email addresses
+        email = email.strip().replace(" ", "")
+
+        try:
+            # Zapier Gmail MCP expects these parameters:
+            # - instructions: natural language description
+            # - to: recipient email (can be array)
+            # - subject: email subject
+            # - body: email body text
+            tool_input = {
+                "instructions": f"Send an invitation email to {guest_name} at {email}",
+                "to": [email],
+                "subject": subject,
+                "body": body
+            }
+
+            # Use ainvoke for async invocation
+            send_result = await send_tool.ainvoke(tool_input)
+            results.append(f"{email}: {send_result}")
+            print(f"[send_guest_invites_via_resend] Sent to {email}: {send_result}")
+        except Exception as e:
+            results.append(f"{email}: ERROR {str(e)}")
+            print(f"[send_guest_invites_via_resend] Error sending to {email}: {str(e)}")
+    
+    # Close client properly (async)
+    try:
+        await client.close()
+    except Exception:
+        pass
+
+    # You could also store this in party_context if you want
+    # party_context.email_send_status = results
+
+    summary_str = "Guest invite send results:\n" + "\n".join(results)
+    return summary_str
+
+
+# -------------------------------------------------------------------
+# 4. Subagent (simplified - tools are used directly)
+# -------------------------------------------------------------------
+# Note: AgentExecutor removed for LangChain 1.0+ compatibility
+# Tools are called directly by the orchestrator or UI
+
+
+async def _run_guest_invite_agent_async() -> str:
+    """
+    Async wrapper to be used by the sync function.
+
+    It will:
+      - Compose subject/body
+      - Send invites to all guests in party_context via Resend MCP
+    """
+    # Directly call the send tool since AgentExecutor was removed
+    result = await send_guest_invites_via_resend.ainvoke({})
+    return result
+
+
+def _run_guest_invite_agent() -> str:
+    """
+    Synchronous wrapper for the orchestrator to call.
+    Handles the async execution internally.
+    """
+    try:
+        # Check if there's already a running event loop
+        loop = asyncio.get_running_loop()
+        # If we're already in an async context, we can't use asyncio.run()
+        # Instead, we need to create a task or use a different approach
+        raise RuntimeError(
+            "guest_invite_email_agent cannot be called from within an async context. "
+            "Please use the async version directly or call from a sync context."
+        )
+    except RuntimeError as e:
+        if "no running event loop" in str(e):
+            # No running loop - safe to use asyncio.run()
+            return asyncio.run(_run_guest_invite_agent_async())
+        else:
+            # Different RuntimeError - re-raise it
+            raise
+
+
+guest_invite_tool = Tool.from_function(
+    func=_run_guest_invite_agent,
+    name="guest_invite_email_agent",
+    description=(
+        "Subagent that sends invitation emails to all guests using the Resend MCP "
+        "server and the current party_context (guest list + invitation text). "
+        "Call this AFTER the theme-planning agent has generated invitation_text "
+        "and the guest CSV has been uploaded."
+    ),
+)

src/agents/orchestrator.py

@@ -0,0 +1,791 @@
+"""Orchestrator Agent - Coordinates all subagents."""
+import os
+import json
+from typing import List, Dict, Any, Optional
+
+from langchain_core.messages import HumanMessage
+from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint
+from langchain_core.tools import Tool
+
+from src.config import TEXT_MODEL
+from src.party_context import party_context
+
+# Import subagent tools
+from src.agents.theme_planning_agent import generate_party_themes, generate_invitation_for_theme
+from src.agents.guest_invite_email_agent import compose_invitation_email, _run_guest_invite_agent
+from src.agents.venue_search_agent import search_party_venues
+from src.agents.theme_decor_favor_shop_agent import generate_shopping_list_for_theme, shop_on_amazon
+from src.tools.csv_guest_parser import parse_guest_csv
+from typing import List, Dict, Any, Optional
+from src.party_context import party_context
+from src.agents.theme_decor_favor_shop_agent import (
+    generate_shopping_list_for_theme,
+    shop_on_amazon,
+)
+
+# ---------- LLM factory & global instance ----------
+
+def get_orchestrator_llm() -> ChatHuggingFace:
+    """Get the orchestrator LLM."""
+    llm = HuggingFaceEndpoint(
+        repo_id=TEXT_MODEL,
+        task="text-generation",
+        max_new_tokens=512,
+        temperature=0.3,  # Lower temperature for more deterministic orchestration
+        do_sample=False,
+    )
+    return ChatHuggingFace(llm=llm)
+
+
+orchestrator_llm = get_orchestrator_llm()
+
+
+# ---------- Wrapper tools (subagents) ----------
+
+def theme_planning_wrapper(
+    party_description: Optional[str] = None,
+    selected_theme_name: Optional[str] = None,
+) -> str:
+    """Wrapper for theme planning operations."""
+    if selected_theme_name:
+        return generate_invitation_for_theme.invoke({"selected_theme_name": selected_theme_name})
+    elif party_description:
+        return generate_party_themes.invoke({"party_description": party_description})
+    else:
+        return "Error: Either party_description or selected_theme_name must be provided"
+
+
+def guest_invite_wrapper(csv_file_path: Optional[str] = None, send_emails: bool = False) -> str:
+    """Wrapper for guest invite operations."""
+    if csv_file_path and os.path.exists(csv_file_path):
+        print(f"[guest_invite_wrapper] CSV file exists: {csv_file_path}")
+        try:
+            names, emails = parse_guest_csv(csv_file_path)
+            party_context.guest_names = names
+            party_context.guest_emails = emails
+            print(f"[guest_invite_wrapper] Loaded {len(names)} guests from CSV file")
+            return f"Successfully loaded {len(names)} guests from CSV file."
+        except Exception as e:
+            print(f"[guest_invite_wrapper] Error loading CSV: {str(e)}")
+            return f"Error loading CSV: {str(e)}"
+
+    if send_emails:
+        print(f"[guest_invite_wrapper] Sending emails to {len(party_context.guest_emails)} guests")
+        return _run_guest_invite_agent()
+    else:
+        if party_context.guest_names:
+            print(f"[guest_invite_wrapper] Guest list loaded: {len(party_context.guest_names)} guests")
+            return f"Guest list loaded: {len(party_context.guest_names)} guests. Ready to send invitations."
+        else:
+            return "Please upload a guest list CSV file first."
+
+
+def venue_search_wrapper(
+    location: str,
+    query: Optional[str] = None,
+    max_results: int = 5,
+    budget: str = "",
+    guest_count: int = 0,
+) -> str:
+    """Wrapper for venue search operations."""
+    search_query = query or "party venue"
+    return search_party_venues.invoke({
+        "location": location,
+        "query": search_query,
+        "max_results": max_results,
+        "budget": budget,
+        "guest_count": guest_count,
+    })
+
+
+def shopping_wrapper(
+    selected_items: Optional[List[str]] = None,
+    shop_on_amazon_flag: bool = False,
+    fewsats_api_key: Optional[str] = None,
+    shipping_address: Optional[Dict[str, Any]] = None,
+    user_info: Optional[Dict[str, Any]] = None,
+) -> str:
+    """
+    Wrapper for shopping operations.
+
+    Demo semantics:
+    - If shop_on_amazon_flag is False → just generate the decor + favor list.
+    - If True:
+        * Use given selected_items OR fall back to party_context.selected_items.
+        * Build cart via MCP-backed Amazon search.
+    """
+    if not shop_on_amazon_flag:
+        # generate decor + favors list based on current theme
+        return generate_shopping_list_for_theme.invoke({"theme_name": None})
+
+    # shop_on_amazon_flag = True
+    if not selected_items:
+        if party_context.selected_items:
+            selected_items = party_context.selected_items
+        else:
+            return (
+                "No items selected for shopping yet. "
+                "Pick decor/favor items in the **Decor & Favors (Shopping)** section, "
+                "click **Save selected items**, then ask me to build your cart."
+            )
+
+    return shop_on_amazon.invoke(
+        {
+            "selected_items": selected_items,
+            "fewsats_api_key": fewsats_api_key,
+            "shipping_address": shipping_address,
+            "user_info": user_info,
+        }
+    )
+
+
+
+# Map tool names (what the LLM will output) to wrapper functions
+
+TOOL_ROUTER = {
+    "theme_planning_agent": theme_planning_wrapper,
+    "venue_search_agent": venue_search_wrapper,
+    "guest_invite_email_agent": guest_invite_wrapper,
+    "theme_decor_favor_shop_agent": shopping_wrapper,
+}
+# ---------- Context summarization ----------
+
+def summarize_party_context() -> str:
+    """Create a compact JSON summary of current party_context for the LLM."""
+    state = {
+        "party_description": party_context.party_description,
+        "event_budget": party_context.event_budget,
+        "event_location": party_context.event_location,
+        "event_date": party_context.event_date,
+        "has_themes": bool(party_context.theme_options),
+        "theme_count": len(party_context.theme_options),
+        "selected_theme_name": party_context.selected_theme_name,
+        "has_invitation": bool(party_context.invitation_text),
+        "guest_count": len(party_context.guest_emails),
+        "emails_sent": party_context.emails_sent,
+        "has_venue_results": bool(party_context.venue_results),
+        "decor_items_count": len(party_context.decor_items),
+        "favor_items_count": len(party_context.favor_items),
+        "selected_items_count": len(party_context.selected_items),
+        "order_status": party_context.order_status,
+    }
+    return json.dumps(state, ensure_ascii=False)
+
+
+# ---------- LLM policy for next action ----------
+
+def decide_next_action(user_message: str, history: List[Dict[str, str]]) -> Dict[str, Any]:
+    """
+    Ask the LLM what to do next:
+    - Ask the user something? (action='ask_user')
+    - Call a tool?         (action='call_tool')
+    Returns a JSON dict.
+    """
+    context_summary = summarize_party_context()
+
+    # Turn last few messages into a transcript for the LLM
+    transcript_lines = []
+    for turn in history[-8:]:
+        role = turn.get("role", "user")
+        content = turn.get("content", "")
+        prefix = "User" if role == "user" else "Assistant"
+        transcript_lines.append(f"{prefix}: {content}")
+    transcript = "\n".join(transcript_lines)
+
+    policy_prompt = f"""
+You are the proactive orchestrator agent for a multi-agent party planning system.
+
+You NEVER call external APIs yourself. You decide whether to:
+- Ask the user a follow-up question proactively, OR
+- Call one of these tools:
+
+1. theme_planning_agent
+   - party_description: str (optional)
+   - selected_theme_name: str (optional)
+   Use it to: generate 3 theme options OR generate an invitation card for a selected theme. Based on the party description generate age-appropriate themes for the  party. 
+
+2. venue_search_agent
+   - location: str
+   - query: str (optional)
+   - max_results: int (optional)
+   - budget: str (optional)
+   - guest_count: int (optional)
+   Use it to: search for party venues near a given city/state within budget and suitable for the guest count.
+
+3. guest_invite_email_agent
+   - csv_file_path: str (optional)
+   - send_emails: bool (optional)
+   Use it to: load guest list from CSV and send invitation emails.
+ 
+
+4. theme_decor_favor_shop_agent
+   - selected_items: List[str] (optional)
+   - shop_on_amazon_flag: bool (optional)
+   - fewsats_api_key: str (optional)
+   - shipping_address: dict (optional)
+   - user_info: dict (optional)
+   Use it to: generate decor/favor shopping lists OR place orders via Amazon+Fewsats MCP.
+
+Current shared state (party_context) as JSON:
+{context_summary}
+
+Recent conversation:
+{transcript}
+
+User just said:
+"{user_message}"
+
+Decide the next action in EXACTLY one of these JSON formats:
+
+If you want to ask the user for more info or confirmation:
+
+{{
+  "action": "ask_user",
+  "message_to_user": "your friendly question or response (1–3 sentences)"
+}}
+
+If you want to call a tool:
+
+{{
+  "action": "call_tool",
+  "tool_name": "<one of: theme_planning_agent, guest_invite_email_agent, venue_search_agent, theme_decor_favor_shop_agent>",
+  "tool_args": {{ ... }},
+  "message_to_user": "what you will tell the user after calling the tool (1–3 sentences, friendly)"
+}}
+
+High-level flow for this app:
+
+- If you don't yet know event_date or event_location, first ASK the user for them.
+- When the user describes the party and you have date & location, and they express interest in themes,
+  call theme_planning_agent(party_description=...).
+- When themes exist and the user says which theme they like (e.g. "I like the superhero one"),
+  call theme_planning_agent(selected_theme_name="chosen theme name") to generate an invitation card.
+- When a guest CSV has been uploaded (handled by the UI; state shows guest_count > 0),
+  and the user confirms sending invites, call guest_invite_email_agent with send_emails=true.
+- When user asks for venues and you know a location (and ideally budget / guest count),call venue_search_agent with those parameters.
+- When user wants decor and favors, call theme_decor_favor_shop_agent to generate a shopping list.
+- When user wants to place the order and you know selected_items and have a FEWSATS key and address,
+  call theme_decor_favor_shop_agent with shop_on_amazon_flag=true.
+
+NEVER mention tool names in message_to_user. Speak like a normal assistant.
+Return ONLY the JSON object, with no extra commentary.
+"""
+
+    resp = orchestrator_llm.invoke([HumanMessage(content=policy_prompt)])
+    content = resp.content.strip()
+
+    # Extract JSON robustly
+    start = content.find("{")
+    end = content.rfind("}") + 1
+    json_str = content[start:end] if start != -1 and end > start else content
+
+    try:
+        parsed = json.loads(json_str)
+    except Exception:
+        parsed = {
+            "action": "ask_user",
+            "message_to_user": (
+                "Sorry, I got a bit confused. Could you please restate what you'd like to do next for your party?"
+            ),
+        }
+        # NEW: store the raw decision in context for UI/debugging
+    # COMMENTED OUT: agent trace logging
+    # try:
+    #     party_context.last_decision = parsed
+    #     pretty = json.dumps(parsed, indent=2, ensure_ascii=False)
+    #     party_context.reasoning_log.append(f"Decision:\n{pretty}")
+    #     # keep only last N entries so it doesn't explode
+    #     if len(party_context.reasoning_log) > 30:
+    #         party_context.reasoning_log = party_context.reasoning_log[-30:]
+    # except Exception:
+    #     pass
+
+    return parsed
+
+
+# ---------- Optional: LangChain Tool objects (for external use) ----------
+
+theme_planning_tool = Tool.from_function(
+    func=theme_planning_wrapper,
+    name="theme_planning_agent",
+    description=(
+        "Plan party themes and create invitation cards. "
+        "Call with party_description to generate 3 theme options, "
+        "or with selected_theme_name to generate invitation card for that theme."
+    ),
+)
+
+
+
+venue_search_tool = Tool.from_function(
+    func=venue_search_wrapper,
+    name="venue_search_agent",
+    description=(
+        "Search for party venues by location. "
+        "Call with location (e.g., 'Santa Clara CA') and optional query and max_results."
+    ),
+)
+
+guest_invite_tool = Tool.from_function(
+    func=guest_invite_wrapper,
+    name="guest_invite_email_agent",
+    description=(
+        "Manage guest invitations. "
+        "Call with csv_file_path to load guest list from CSV, "
+        "or with send_emails=True to send invitation emails to all loaded guests."
+    ),
+)
+
+shopping_tool = Tool.from_function(
+    func=shopping_wrapper,
+    name="theme_decor_favor_shop_agent",
+    description=(
+        "Generate shopping lists for decor and party favors based on theme, "
+        "or shop on Amazon for selected items using Fewsats payment. "
+        "Call without shop_on_amazon_flag to generate list, "
+        "or with shop_on_amazon_flag=True to place orders."
+    ),
+)
+
+orchestrator_tools = [
+    theme_planning_tool,
+    guest_invite_tool,
+    venue_search_tool,
+    shopping_tool,
+]
+
+
+# ---------- Optional extractor (used only in early flow) ----------
+
+def extract_event_details_from_message(message: str) -> Dict[str, Optional[str]]:
+    """
+    Use the LLM to pull budget, location, and date out of a natural language message.
+    Returns dict with keys: budget, location, date (values may be None).
+    """
+    prompt = f"""
+You are an information extraction assistant.
+
+From the following user message, extract:
+- approximate budget (e.g. "$500", "under 300 dollars", "no budget limit")
+- event location (e.g. "San Jose CA")
+- event date (e.g. "June 10, 2025" or "2025-06-10")
+
+User message:
+{message}
+
+Return ONLY valid JSON in this exact format:
+{{
+  "budget": "string or null",
+  "location": "string or null",
+  "date": "string or null"
+}}
+If something is not present, set it to null.
+"""
+    try:
+        resp = orchestrator_llm.invoke([HumanMessage(content=prompt)])
+        content = resp.content.strip()
+        start = content.find("{")
+        end = content.rfind("}") + 1
+        json_str = content[start:end] if start != -1 and end > start else content
+        data = json.loads(json_str)
+        return {
+            "budget": data.get("budget"),
+            "location": data.get("location"),
+            "date": data.get("date"),
+        }
+    except Exception:
+        return {"budget": None, "location": None, "date": None}
+
+
+def extract_theme_selection_from_message(message: str, available_themes: List[str]) -> Optional[str]:
+    """
+    Use the LLM to detect which theme the user selected from natural language.
+    Returns the theme name if found, None otherwise.
+    """
+    if not available_themes:
+        return None
+    
+    themes_list = "\n".join([f"- {t}" for t in available_themes])
+    prompt = f"""
+You are an information extraction assistant.
+
+The user has these theme options available:
+{themes_list}
+
+From the following user message, determine if they are selecting one of these themes.
+The user might say things like:
+- "I like the superhero one"
+- "Let's go with theme 1"
+- "I choose the princess theme"
+- "The first option"
+- "Superhero Adventure"
+
+User message:
+{message}
+
+Return ONLY valid JSON in this exact format:
+{{
+  "selected_theme": "exact theme name from the list above, or null if no theme is clearly selected"
+}}
+
+If the user is clearly selecting a theme, return the exact theme name from the list.
+If it's ambiguous or no theme is mentioned, return null.
+"""
+    try:
+        resp = orchestrator_llm.invoke([HumanMessage(content=prompt)])
+        content = resp.content.strip()
+        start = content.find("{")
+        end = content.rfind("}") + 1
+        json_str = content[start:end] if start != -1 and end > start else content
+        data = json.loads(json_str)
+        selected = data.get("selected_theme")
+        # Verify it's actually in the available themes list
+        if selected and selected in available_themes:
+            return selected
+        return None
+    except Exception:
+        return None
+
+
+# ---------- Main chat entrypoint ----------
+def orchestrator_chat(user_message: str, history: Optional[List[Dict[str, str]]] = None) -> str:
+    """
+    Main chat entrypoint.
+
+    Flow:
+    1. First user message -> treat as party_description, ask for budget/location/date.
+    2. Subsequent messages -> extract & fill budget/location/date.
+    3. Once all present -> generate themes automatically.
+    4. After themes -> user picks theme -> we guide them to venue search.
+    5. After user says they booked a venue -> we create the invitation card.
+    6. After that -> send guest emails, decor/cart, etc.
+    """
+    history = history or []
+    user_message = user_message.strip()
+    user_lower = user_message.lower()
+
+    # STEP 1: first message = party description
+    if party_context.party_description is None:
+        party_context.party_description = user_message
+        return (
+            "Awesome! 🎉 I can help you plan your private party end-to-end — themes, venues, invitations, "
+            "guest emails, and decor shopping.\n\n"
+            "First, tell me a few basics so I can suggest good themes:\n"
+            "1) Your approximate **budget**\n"
+            "2) The **city/state location** of the event\n"
+            "3) The **date** of the event\n\n"
+            "You can answer in one sentence, for example:\n"
+            "\"Budget is under $700, in Sunnyvale CA on December 10, 2025 for about 60 people.\""
+        )
+
+    # STEP 2: fill missing budget/location/date
+    missing_budget = party_context.event_budget is None
+    missing_location = party_context.event_location is None
+    missing_date = party_context.event_date is None
+
+    if missing_budget or missing_location or missing_date:
+        extracted = extract_event_details_from_message(user_message)
+
+        if missing_budget and extracted.get("budget"):
+            party_context.event_budget = extracted["budget"]
+        if missing_location and extracted.get("location"):
+            party_context.event_location = extracted["location"]
+            party_context.search_location = extracted["location"]
+        if missing_date and extracted.get("date"):
+            party_context.event_date = extracted["date"]
+
+        still_missing = []
+        if party_context.event_budget is None:
+            still_missing.append("budget")
+        if party_context.event_location is None:
+            still_missing.append("location")
+        if party_context.event_date is None:
+            still_missing.append("date")
+
+        if still_missing:
+            parts = ", ".join(still_missing)
+            return (
+                "Got it, thanks! I’m still missing your "
+                f"**{parts}**. Please share that so I can propose good themes and venues."
+            )
+
+        # We now have all three -> generate themes automatically
+        try:
+            print(f"[orchestrator] Generating themes for: {party_context.party_description}")
+            result = theme_planning_wrapper(party_description=party_context.party_description)
+            print(f"[orchestrator] Theme generation result: {result[:100]}...")
+            print(f"[orchestrator] Theme options count: {len(party_context.theme_options)}")
+
+            import time
+            if not party_context.theme_options:
+                time.sleep(1)
+                print(f"[orchestrator] After wait, theme options count: {len(party_context.theme_options)}")
+
+            if party_context.theme_options:
+                theme_names = [t.name for t in party_context.theme_options]
+                theme_descriptions = [t.description for t in party_context.theme_options]
+                return (
+                    f"Perfect! Here’s what I have so far:\n"
+                    f"- Budget: {party_context.event_budget}\n"
+                    f"- Location: {party_context.event_location}\n"
+                    f"- Date: {party_context.event_date}\n\n"
+                    "🎨 **I’ve generated 3 theme options for you below.**\n\n"
+                    f"1. **{theme_names[0] if len(theme_names) > 0 else 'Theme 1'}**\n"
+                    f"   {theme_descriptions[0] if len(theme_descriptions) > 0 else ''}\n\n"
+                    f"2. **{theme_names[1] if len(theme_names) > 1 else 'Theme 2'}**\n"
+                    f"   {theme_descriptions[1] if len(theme_descriptions) > 1 else ''}\n\n"
+                    f"3. **{theme_names[2] if len(theme_names) > 2 else 'Theme 3'}**\n"
+                    f"   {theme_descriptions[2] if len(theme_descriptions) > 2 else ''}\n\n"
+                    "👉 **Tell me which theme you’d like to use** "
+                    "(e.g., \"I like the first one\" or \"Let’s go with Superhero Adventure\").\n"
+                    "After we lock your theme, I’ll help you find some venue options before we create your invitation card."
+                )
+            else:
+                return (
+                    f"Great! I’ve captured:\n"
+                    f"- Budget: {party_context.event_budget}\n"
+                    f"- Location: {party_context.event_location}\n"
+                    f"- Date: {party_context.event_date}\n\n"
+                    "I’m generating theme options now — they’ll appear below the chat in a moment."
+                )
+        except Exception as e:
+            import traceback
+            error_details = traceback.format_exc()
+            print(f"[orchestrator] Error generating themes: {e}\n{error_details}")
+            return (
+                f"Great! I have all your details. However, I ran into an issue generating themes: {e}\n"
+                "Please try again or tell me how you’d like to continue."
+            )
+
+    # STEP 3: Check if user is selecting a theme (before LLM decision)
+    if party_context.theme_options and not party_context.selected_theme_name:
+        available_theme_names = [t.name for t in party_context.theme_options]
+        selected_theme = extract_theme_selection_from_message(user_message, available_theme_names)
+        if selected_theme:
+            party_context.selected_theme_name = selected_theme
+            # After theme selection, we push them to venue search (not invitation yet)
+            msg = (
+                f"Great choice! You’ve selected **{selected_theme}** 🎉\n\n"
+                "Before we create your invitation card, let’s find a venue.\n"
+            )
+            if party_context.event_location:
+                msg += (
+                    f"I can search for party venues near **{party_context.event_location}** "
+                    f"within your budget {party_context.event_budget or ''}.\n\n"
+                    "👉 Would you like me to search for some venue options now?"
+                )
+            else:
+                msg += (
+                    "Please confirm the city/state where you want to host the party, "
+                    "then I’ll search for venues for you."
+                )
+            return msg
+
+    # STEP 3b: Detect when user says they booked / chose a venue, then create invitation
+    if party_context.venue_results and not party_context.invitation_text:
+        if any(word in user_lower for word in ["booked", "reserved", "we chose", "we picked", "we decided", "going with", "we selected"]):
+            # We could parse which venue, but for now we just proceed to invitation creation
+            if not party_context.selected_theme_name:
+                return (
+                    "Nice, sounds like you’ve booked a venue! 🎉\n"
+                    "Now tell me which theme you’d like to use for your invitation (e.g., “Superhero Adventure”)."
+                )
+
+            # We have a theme + venues and event details → create invitation card
+            try:
+                _ = generate_invitation_for_theme.invoke(
+                    {"selected_theme_name": party_context.selected_theme_name}
+                )
+                return (
+                    "Awesome — venue locked in and theme selected! 🎉\n\n"
+                    "I’ve created your invitation card using your date, location and theme. "
+                    "You’ll see the image below in the UI.\n\n"
+                    "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."
+                )
+            except Exception as e:
+                return (
+                    "Great, thanks for confirming your venue. I tried to create the invitation card but hit an error: "
+                    f"{e}\nPlease try again or tell me and we’ll retry."
+                )
+
+    # STEP 4: after details are set, use LLM-based decision system
+    decision = decide_next_action(user_message, history)
+    action = decision.get("action")
+    message_to_user = (decision.get("message_to_user") or "").strip()
+
+    if action == "call_tool":
+        tool_name = decision.get("tool_name")
+        tool_args = decision.get("tool_args", {}) or {}
+
+        # 🧠 Auto-fill context for venue search tool (budget + guest_count)
+        if tool_name == "venue_search_agent":
+            if not tool_args.get("location") and party_context.event_location:
+                tool_args["location"] = party_context.event_location
+            if not tool_args.get("budget") and party_context.event_budget:
+                tool_args["budget"] = party_context.event_budget
+            if (not tool_args.get("guest_count") or tool_args.get("guest_count") == 0) and party_context.guest_emails:
+                tool_args["guest_count"] = len(party_context.guest_emails)
+
+        # 🎨 Handle explicit theme selection via tool call
+        if tool_name == "theme_planning_agent" and tool_args.get("selected_theme_name"):
+            party_context.selected_theme_name = tool_args.get("selected_theme_name")
+
+        # 🛍️ Pre-check for shopping: auto-fill selected_items BEFORE tool call
+        if tool_name == "theme_decor_favor_shop_agent":
+            if tool_args.get("shop_on_amazon_flag") and not tool_args.get("selected_items"):
+                if party_context.selected_items:
+                    tool_args["selected_items"] = party_context.selected_items
+                else:
+                    return (
+                        "No items selected for shopping yet. "
+                        "Pick decor/favor items in the **Decor & Favors (Shopping)** section, "
+                        "click **Save selected items**, then ask me to build your cart."
+                    )
+
+        tool_fn = TOOL_ROUTER.get(tool_name)
+        if tool_fn is None:
+            return (
+                message_to_user
+                or "I tried to pick the right helper agent, but something went wrong. Could you rephrase what you want?"
+            )
+
+        # COMMENTED OUT: agent trace logging
+        # # NEW: log tool call BEFORE calling it (for ALL tools)
+        # try:
+        #     party_context.reasoning_log.append(
+        #         f"Calling tool: {tool_name} with args: {json.dumps(tool_args, ensure_ascii=False)}"
+        #     )
+        #     if len(party_context.reasoning_log) > 30:
+        #         party_context.reasoning_log = party_context.reasoning_log[-30:]
+        # except Exception:
+        #     pass
+
+        try:
+            tool_result = tool_fn(**tool_args)
+            
+            # COMMENTED OUT: agent trace logging
+            # # NEW: log tool result (truncated)
+            # try:
+            #     result_str = str(tool_result)[:200]
+            #     party_context.reasoning_log.append(f"Tool result (truncated): {result_str}...")
+            #     if len(party_context.reasoning_log) > 30:
+            #         party_context.reasoning_log = party_context.reasoning_log[-30:]
+            # except Exception:
+            #     pass
+
+            # 🏨 For venue search, show the tool result + instructions to book & then tell us
+            if tool_name == "venue_search_agent":
+                hint = (
+                    message_to_user
+                    or "Here are some venue ideas I found that match your location, budget, and guest count:"
+                )
+                followup = (
+                    "\n\n🔔 Please review these options, check availability, and reserve your favorite venue "
+                    "on their websites or Yelp pages.\n"
+                    "Once you’ve booked one, tell me which venue you chose "
+                    "(e.g., “We booked #2” or “We chose Bella Gardens”), and I’ll create your invitation card."
+                )
+                return f"{hint}\n\n{tool_result}{followup}"
+
+            # 📧 For guest invites, distinguish between loading CSV vs sending emails
+            if tool_name == "guest_invite_email_agent":
+                sent_flag = bool(tool_args.get("send_emails"))
+                if sent_flag:
+                    party_context.emails_sent = True
+                    guest_n = len(party_context.guest_emails)
+                    base_msg = (
+                        f"Done! I’ve sent your invitation email to **{guest_n} guests** 🎉\n"
+                    )
+                    next_hint = (
+                        "\n Next, I can help you plan decor and party favors and build an Amazon cart for you. "
+                        "Just say something like *“Help me with decor and favors”*."
+                    )
+                    return base_msg + next_hint
+                else:
+                    base_msg = tool_result or "I’ve loaded your guest list."
+                    next_hint = (
+                        "\n\nWhen you’re ready, tell me something like *“Send the invitations”* "
+                        "and I’ll email your guests using the invitation card we created."
+                    )
+                    return base_msg + next_hint
+
+            # 🛍️ Decor & favor shopping
+            if tool_name == "theme_decor_favor_shop_agent":
+                # Note: tool_result is already computed above, selected_items already auto-filled if needed
+                if tool_args.get("shop_on_amazon_flag"):
+                    # Cart was built; cart_items + order_status set in party_context
+                    base_msg = (
+                        "I've built an Amazon cart based on your saved decor & favor selections. 🛒\n"
+                        "You should now see your cart updated in the **Cart Preview** panel on the right."
+                    )
+                    if tool_result:
+                        # Append MCP-derived details (product titles, links, etc.)
+                        return base_msg + "\n\n" + str(tool_result)
+                    return base_msg
+                else:
+                    # Just created shopping list, no cart yet
+                    base_msg = (
+                        "I've created a shopping list of decor and party favors for your theme. 🎉\n"
+                        "Use the checkboxes under **Decor & Favors (Shopping)** to pick what you like, "
+                        "then click **Save selected items**, and ask me when you're ready to build your Amazon cart."
+                    )
+                    return base_msg
+        
+            # 🎨 For theme_planning_agent used only for invitation generation (fallback)
+            if tool_name == "theme_planning_agent" and tool_args.get("selected_theme_name"):
+                if party_context.invitation_text:
+                    return (
+                        "Your invitation card is ready! 🎉\n\n"
+                        "You can see the image below. Next, please upload your guest list CSV using the "
+                        "**Guest List CSV** uploader, and I’ll help you send this card to all your guests."
+                    )
+
+            # Default for other tools
+            return message_to_user or "Done! I’ve updated your party plan based on that step."
+
+        except Exception as e:
+            return f"Something went wrong while calling my helper agent ({tool_name}): {e}"
+
+    # STEP 5: no tool call → just respond, plus proactive hints
+    if not message_to_user:
+        message_to_user = "How would you like to continue planning your party?"
+
+    hints = []
+
+    # Invitation exists but no guests loaded yet
+    if party_context.invitation_text and not party_context.guest_emails:
+        hints.append(
+            "📧 Your invitation card is ready! When you’re ready, upload your guest list CSV using the "
+            "**Guest List CSV** upload below and I’ll help you send the invitations."
+        )
+
+    # Guests loaded but emails not sent
+    if party_context.guest_emails and not party_context.emails_sent:
+        hints.append(
+            f"📧 I see we have **{len(party_context.guest_emails)} guests** in your list. "
+            "If you’d like me to email them the invitation, just say something like "
+            "*“Send the invitations”* or *“Go ahead and email everyone.”*"
+        )
+
+    # Emails sent, but decor not planned
+    if party_context.emails_sent and not party_context.decor_items:
+        hints.append(
+            "🛍️ Invitations are taken care of! Next, I can help you plan decor & party favors and build an Amazon cart. "
+            "Try saying *“Help me with decor and favors”*."
+        )
+
+    # Decor items exist, but no cart yet
+    if party_context.decor_items and not getattr(party_context, "cart_items", []):
+        hints.append(
+            "🛍️ I’ve generated decor and favor ideas. Use the checkboxes under **Decor & Favors (Shopping)** "
+            "to pick your items, then tell me when you’re ready to build your cart."
+        )
+
+    if hints:
+        message_to_user = message_to_user + "\n\n" + "\n\n".join(hints)
+
+    return message_to_user
+
+
+__all__ = ["orchestrator_chat", "orchestrator_tools"]

src/agents/theme_decor_favor_shop_agent.py

@@ -0,0 +1,379 @@
+"""Subagent 4: Theme Decor/Favor Shop Agent - 
+   1) Generates theme-based decor & favor shopping lists (LLM)
+   2) Builds an Amazon cart via MCP (demo mode, no real orders)
+"""
+import json
+from typing import List, Optional, Dict, Any
+from langchain_core.tools import tool
+from langchain_core.messages import HumanMessage
+from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint
+
+from src.config import TEXT_MODEL
+from src.party_context import party_context, ShoppingItem
+from src.mcp.mcp_clients import amazon_mcp
+
+
+# ==========================================================
+#  LLM for generating theme-based shopping list
+# ==========================================================
+
+def get_text_llm() -> ChatHuggingFace:
+    """Get the text generation LLM used for decor/favor suggestions."""
+    llm = HuggingFaceEndpoint(
+        repo_id=TEXT_MODEL,
+        task="text-generation",
+        max_new_tokens=512,
+        temperature=0.7,
+        do_sample=True,
+    )
+    return ChatHuggingFace(llm=llm)
+
+
+text_llm = get_text_llm()
+
+
+@tool
+def generate_shopping_list_for_theme(theme_name: Optional[str] = None) -> str:
+    """
+    Generate a list of decor items and party favors based on the selected party theme.
+    
+    Args:
+        theme_name: The selected theme name (optional, uses party_context if not provided)
+        
+    Returns:
+        JSON string with shopping list items, and also updates:
+        - party_context.decor_items
+        - party_context.favor_items
+    """
+    theme = theme_name or party_context.selected_theme_name
+    if not theme:
+        return json.dumps({"error": "No theme selected. Please select a theme first."})
+    
+    party_description = party_context.party_description or ""
+    
+    prompt = f"""You are a party planning expert. Based on the party theme "{theme}" and party description "{party_description}", create a comprehensive shopping list of decor items and age-appropriate party favors.
+
+Generate:
+- 5-8 decor items (decorations, banners, balloons, table settings, etc.)
+- 2-3 common decor items that are likely to be useful for any party (e.g., tablecloths, plates, cups, napkins, etc.)
+- 5-8 party favor items (small gifts, toys, treats, etc.)
+- 2-3 common party favor items that are likely to be useful for any party (e.g., gift bags, party favors, etc.)
+
+For each item, provide:
+- A clear, specific name that would work well as an Amazon search query.
+  - Include the theme and type of item, e.g. "graduation party banner decorations", "princess birthday party favor bags".
+  - Avoid vague or cute names like "Magical Unicorn Table of Dreams".
+- Category: "decor" or "favor"
+- A brief description (1 sentence)
+
+Return ONLY valid JSON in this exact format:
+{{
+  "decor_items": [
+    {{"name": "Item Name", "category": "decor", "description": "Brief description"}},
+    ...
+  ],
+  "favor_items": [
+    {{"name": "Item Name", "category": "favor", "description": "Brief description"}},
+    ...
+  ]
+}}
+
+Make items specific, age-appropriate, and theme-relevant!"""
+
+    try:
+        response = text_llm.invoke([HumanMessage(content=prompt)])
+        content = response.content.strip()
+        
+        # Try to extract JSON robustly
+        try:
+            parsed = json.loads(content)
+        except json.JSONDecodeError:
+            start = content.find("{")
+            end = content.rfind("}") + 1
+            if start >= 0 and end > start:
+                json_str = content[start:end]
+                parsed = json.loads(json_str)
+            else:
+                raise ValueError("Could not parse JSON from response")
+        
+        # Create ShoppingItem objects
+        decor_items: List[ShoppingItem] = []
+        favor_items: List[ShoppingItem] = []
+        
+        for item_data in parsed.get("decor_items", []):
+            item = ShoppingItem(
+                name=item_data.get("name", ""),
+                category="decor",
+                description=item_data.get("description", "")
+            )
+            decor_items.append(item)
+        
+        for item_data in parsed.get("favor_items", []):
+            item = ShoppingItem(
+                name=item_data.get("name", ""),
+                category="favor",
+                description=item_data.get("description", "")
+            )
+            favor_items.append(item)
+        
+        # Update party context so the UI can show checkboxes
+        party_context.decor_items = decor_items
+        party_context.favor_items = favor_items
+        
+        result = {
+            "theme": theme,
+            "decor_items": [
+                {"name": item.name, "description": item.description}
+                for item in decor_items
+            ],
+            "favor_items": [
+                {"name": item.name, "description": item.description}
+                for item in favor_items
+            ],
+            "total_items": len(decor_items) + len(favor_items),
+        }
+        
+        return json.dumps(result, indent=2, ensure_ascii=False)
+        
+    except Exception as e:
+        error_msg = f"Error generating shopping list: {str(e)}"
+        print("[generate_shopping_list_for_theme] ERROR:", error_msg)
+
+        # Fallback items so the UI still has something to show
+        fallback_decor = [
+            {"name": f"{theme} Theme Banner", "description": "Colorful banner matching the theme"},
+            {"name": f"{theme} Balloons", "description": "Theme-colored balloons"},
+            {"name": "Table Decorations", "description": "Table centerpieces and decorations"},
+        ]
+        fallback_favor = [
+            {"name": "Party Favor Bags", "description": "Small gift bags for guests"},
+            {"name": "Theme Stickers", "description": "Fun stickers matching the theme"},
+        ]
+        
+        decor_items = [
+            ShoppingItem(name=item["name"], category="decor", description=item["description"])
+            for item in fallback_decor
+        ]
+        favor_items = [
+            ShoppingItem(name=item["name"], category="favor", description=item["description"])
+            for item in fallback_favor
+        ]
+        
+        party_context.decor_items = decor_items
+        party_context.favor_items = favor_items
+        
+        return json.dumps(
+            {
+                "theme": theme,
+                "decor_items": fallback_decor,
+                "favor_items": fallback_favor,
+                "total_items": len(fallback_decor) + len(fallback_favor),
+                "note": "Generated fallback list due to error",
+            },
+            indent=2,
+        )
+
+def build_amazon_query_from_item_name(item_name: str) -> str:
+    """
+    Turn a human-friendly item name into a cleaner Amazon search query.
+    - Strip any long descriptions after " - " or " – "
+    - Force lowercase
+    - Optionally append 'party' if it looks like decor/favors without that word
+    """
+    # Split off descriptions like "Graduation Banner – black and gold"
+    for sep in [" – ", " - "]:
+        if sep in item_name:
+            item_name = item_name.split(sep, 1)[0]
+
+    q = item_name.strip().lower()
+
+    # If it doesn't already mention 'party' but clearly looks like decor/favors,
+    # lightly bias toward party supplies.
+    keywords = ["banner", "balloons", "tablecloth", "table runner", "favor", "goodie bag", "cups", "plates"]
+    if any(k in q for k in keywords) and "party" not in q:
+        q = q + " party"
+
+    return q
+
+# ==========================================================
+#  Amazon MCP cart builder (demo mode, no real checkout)
+# ==========================================================
+
+@tool
+def shop_on_amazon(
+    selected_items: List[str],
+    fewsats_api_key: Optional[str] = None,
+    shipping_address: Optional[Dict[str, Any]] = None,
+    user_info: Optional[Dict[str, Any]] = None,
+) -> str:
+    """
+    Build an Amazon 'cart' for the selected items using the Amazon MCP server.
+
+    ⚠️ Demo / hackathon mode:
+    - We DO NOT place real orders.
+    - FEWSATS key, shipping_address, and user_info are accepted but not required.
+    - We only search products and prepare a cart summary with Amazon links.
+
+    Args:
+        selected_items: List of item names the user selected (decor / favors).
+        fewsats_api_key: Optional Fewsats API key (kept for future extension).
+        shipping_address: Optional shipping address.
+        user_info: Optional user info.
+
+    Returns:
+        A human-friendly summary of the cart and also updates:
+        - party_context.cart_items
+        - party_context.order_status
+    """
+    if not selected_items:
+        return (
+            "No items selected for shopping. Please choose some decor or favors first "
+            "in the **Decor & Favors (Shopping)** section and click **Save selected items**."
+        )
+
+    cart_items: List[Dict[str, Any]] = []
+    failed_items: List[str] = []
+
+    for item_name in selected_items:
+        try:
+            # NOTE: amazon_mcp.search_product is a **sync** wrapper that internally
+            # uses asyncio.run(...) to talk to the async MCP manager.
+            #search_result = amazon_mcp.search_product(item_name)
+            query = build_amazon_query_from_item_name(item_name)
+            search_result = amazon_mcp.search_product(query)
+
+
+            # Be defensive about schema differences
+            products = (
+                search_result.get("products")
+                or search_result.get("items")
+                or search_result.get("data")  # in case server returns {"data": [...]}
+                or []
+            )
+
+            if not products:
+                failed_items.append(f"{item_name} (no products found)")
+                continue
+
+            # Take the first product as a simple heuristic
+            product = products[0]
+
+            title = (
+                product.get("title")
+                or product.get("name")
+                or item_name
+            )
+            url = (
+                product.get("url")
+                or product.get("productUrl")
+                or product.get("link")
+                or ""
+            )
+
+            # Try to extract a price if present (schema-agnostic)
+            price_value = None
+            currency = None
+
+            price_info = product.get("price")
+            if isinstance(price_info, (int, float)):
+                price_value = float(price_info)
+            elif isinstance(price_info, dict):
+                # Common patterns: {"amount": 12.99, "currency": "USD"} or {"value": 12.99}
+                price_value = (
+                    price_info.get("amount")
+                    or price_info.get("value")
+                )
+                currency = (
+                    price_info.get("currency")
+                    or price_info.get("currency_code")
+                )
+
+            cart_items.append(
+                {
+                    "requested_name": item_name,
+                    "title": title,
+                    "url": url,
+                    "price": price_value,
+                    "currency": currency,
+                }
+            )
+        except Exception as e:
+            failed_items.append(f"{item_name} (error during search: {str(e)})")
+
+    # Store cart in shared context for the UI to render
+    party_context.order_status = "cart_ready"
+    # type: ignore[attr-defined] in case cart_items wasn't in PartyContext dataclass
+    party_context.cart_items = cart_items  # type: ignore[attr-defined]
+
+    # Compute a rough total (only where we have numeric prices)
+    numeric_prices = [
+        c["price"] for c in cart_items
+        if isinstance(c.get("price"), (int, float))
+    ]
+    total_estimate = sum(numeric_prices) if numeric_prices else None
+    currency = None
+    for c in cart_items:
+        if c.get("currency"):
+            currency = c["currency"]
+            break
+
+    # Build human-friendly message
+    msg_lines: List[str] = []
+    msg_lines.append("🛒 I’ve built an Amazon cart for your selected items.\n")
+
+    if cart_items:
+        msg_lines.append("**Cart items (click links to review on Amazon):**")
+        for c in cart_items:
+            line = f"• **{c['title']}**"
+            if c.get("price") is not None:
+                if currency:
+                    line += f" – ~{c['price']} {currency}"
+                else:
+                    line += f" – ~{c['price']}"
+            if c.get("url"):
+                line += f"\n  {c['url']}"
+            msg_lines.append(line)
+    else:
+        msg_lines.append("I couldn’t find any matching products for your selections.")
+
+    if total_estimate is not None:
+        total_str = f"{total_estimate:.2f}"
+        if currency:
+            msg_lines.append(
+                f"\n**Estimated total (before tax & shipping):** ~{total_str} {currency}"
+            )
+        else:
+            msg_lines.append(
+                f"\n**Estimated total (before tax & shipping):** ~{total_str}"
+            )
+
+    if failed_items:
+        msg_lines.append("\nSome items could not be matched:")
+        for fi in failed_items:
+            msg_lines.append(f"• {fi}")
+
+    msg_lines.append(
+        "\n💡 *No real orders were placed.* This is a demo cart builder. "
+        "You can open the Amazon links above to review and complete checkout manually."
+    )
+
+    # Mention FEWSATS if user provided it, but clarify no payment was done
+    if fewsats_api_key:
+        msg_lines.append(
+            "\n🔐 You provided a FEWSATS API key. In a future version, I can use it to "
+            "automate payment and order placement, but in this demo I only prepare the cart."
+        )
+
+    # Hint for UI: cart_preview panel should now show items from party_context.cart_items
+    msg_lines.append(
+        "\n🛒 You should now see your cart updated in the **Cart Preview** panel on the right."
+    )
+
+    return "\n".join(msg_lines)
+
+
+__all__ = [
+    "generate_shopping_list_for_theme",
+    "build_amazon_query_from_item_name",
+    "shop_on_amazon",
+]

src/agents/theme_planning_agent.py

@@ -0,0 +1,286 @@
+"""Subagent 1: Theme Planning Agent - Generates themes and invitation cards."""
+import os
+import json
+from typing import Optional, Dict, Any
+from huggingface_hub import InferenceClient
+from langchain_core.tools import tool
+from langchain_core.messages import HumanMessage
+from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint
+
+from src.config import HF_TOKEN, TEXT_MODEL, IMAGE_MODEL, INVITATION_IMAGE_DIR
+from src.party_context import party_context, ThemeOption
+
+
+def get_text_llm() -> ChatHuggingFace:
+    """Get the text generation LLM."""
+    llm = HuggingFaceEndpoint(
+        repo_id=TEXT_MODEL,
+        task="text-generation",
+        max_new_tokens=512,
+        temperature=0.7,
+        do_sample=True,
+        timeout=30,  # 30 second timeout
+    )
+    return ChatHuggingFace(llm=llm)
+
+
+def get_image_client() -> InferenceClient:
+    """Get the image generation client."""
+    if not HF_TOKEN:
+        raise ValueError("HF_TOKEN or HUGGINGFACEHUB_API_TOKEN must be set")
+    return InferenceClient(provider="auto", api_key=HF_TOKEN)
+
+
+# Initialize clients
+text_llm = get_text_llm()
+image_client = get_image_client()
+
+
+@tool
+def generate_party_themes(party_description: str) -> str:
+    """
+    Generate 3 creative party theme options based on the party description.
+
+    Args:
+        party_description: User's party description
+            (e.g., "I want to plan a birthday party for my 5 year old kid")
+
+    Returns:
+        JSON string with 3 theme options in the format:
+        {
+          "themes": [
+            {"id": 1, "name": "...", "description": "..."},
+            {"id": 2, "name": "...", "description": "..."},
+            {"id": 3, "name": "...", "description": "..."}
+          ]
+        }
+    """
+    prompt = f"""You are a creative party planning assistant. Based on the following party description, propose EXACTLY 3 age-appropriate party themes that would be perfect for this event.
+
+Party description: {party_description}
+
+For each theme, provide:
+- A catchy, fun name
+- A brief description (2-3 sentences) explaining why this theme is suitable and what makes it special
+
+Return ONLY valid JSON in this exact format:
+{{
+  "themes": [
+    {{"id": 1, "name": "Theme Name 1", "description": "Description of theme 1"}},
+    {{"id": 2, "name": "Theme Name 2", "description": "Description of theme 2"}},
+    {{"id": 3, "name": "Theme Name 3", "description": "Description of theme 3"}}
+  ]
+}}
+"""
+
+    # Always record the description in shared context
+    party_context.party_description = party_description
+
+    try:
+        response = text_llm.invoke([HumanMessage(content=prompt)])
+        content = response.content.strip()
+
+        # Try direct JSON parse
+        try:
+            parsed = json.loads(content)
+        except json.JSONDecodeError:
+            # Try to extract JSON substring
+            start = content.find("{")
+            end = content.rfind("}") + 1
+            if start >= 0 and end > start:
+                json_str = content[start:end]
+                parsed = json.loads(json_str)
+            else:
+                raise ValueError("Could not parse JSON from response")
+
+        # Build ThemeOption objects
+        themes = []
+        for idx, theme_data in enumerate(parsed.get("themes", []), start=1):
+            theme = ThemeOption(
+                id=theme_data.get("id", idx),
+                name=theme_data.get("name", f"Theme {idx}"),
+                description=theme_data.get("description", "")
+            )
+            themes.append(theme)
+
+        if not themes:
+            raise ValueError("No themes found in LLM response")
+
+        # ✅ Update party context so UI/orchestrator can see the options
+        party_context.theme_options = themes
+
+        return json.dumps(parsed, indent=2, ensure_ascii=False)
+
+    except Exception as e:
+        # Fallback themes if LLM output is bad
+        error_msg = f"Error generating themes: {str(e)}"
+        print("[generate_party_themes] ", error_msg)
+
+        fallback_themes = [
+            {
+                "id": 1,
+                "name": "Superhero Adventure",
+                "description": "A heroic party with capes, masks, and superpowers!",
+            },
+            {
+                "id": 2,
+                "name": "Princess & Knights",
+                "description": "A magical royal celebration with crowns and castles!",
+            },
+            {
+                "id": 3,
+                "name": "Space Explorer",
+                "description": "Blast off into space with rockets, stars, and planets!",
+            },
+        ]
+
+        themes = [ThemeOption(**t) for t in fallback_themes]
+        party_context.theme_options = themes
+
+        return json.dumps({"themes": fallback_themes}, indent=2, ensure_ascii=False)
+
+@tool
+def generate_invitation_for_theme(selected_theme_name: str) -> str:
+    """
+    Generate invitation text and 4x4 invitation card image for the selected theme.
+    
+    Args:
+        selected_theme_name: The name of the selected theme
+        
+    Returns:
+        JSON string with invitation details
+    """
+    if not party_context.party_description:
+        return json.dumps({"error": "Party description not set. Please generate themes first."})
+    
+    party_context.selected_theme_name = selected_theme_name
+    
+    # Generate invitation text informed by structured event details
+    event_date = party_context.event_date or "[Date to be announced]"
+    event_location = party_context.event_location or "[Location to be announced]"
+    budget = party_context.event_budget or "[Budget not specified]"
+
+    invitation_prompt = f"""You are writing a warm, fun invitation for the selected theme party.
+
+Theme: "{selected_theme_name}"
+
+Party description:
+{party_context.party_description}
+
+Event details (work these naturally into the copy):
+- Date: {event_date}
+- Location: {event_location}
+- Budget context: {budget} (use only to set the tone; do NOT mention the exact budget)
+
+The invitation should:
+- Be 3–5 short sentences and age-appropriate for the selected theme.
+- Invitatopn card should have embedded welcome message for the guest.
+- Be warm and welcoming
+- Use the actual date and location values above (no placeholders for those two)
+- Include placeholders only for time and RSVP deadline (e.g., "Time: [To be announced]", "Please RSVP by [date]")
+- Match the energy of the theme
+
+Write the invitation text now:"""
+
+    try:
+        text_response = text_llm.invoke([HumanMessage(content=invitation_prompt)])
+        invitation_text = text_response.content.strip()
+        
+        # Generate invitation card image with all details embedded
+        event_date = party_context.event_date or "[Date to be announced]"
+        event_location = party_context.event_location or "[Location to be announced]"
+        occasion = party_context.party_description or "Special Celebration"
+        
+        image_prompt = f"""Create a beautiful 4x4 inch square invitation card for the party according to the selected party theme. It should be age-appropriate.
+
+REQUIREMENTS - ALL TEXT MUST BE VISIBLE AND READABLE IN THE IMAGE:
+1. Theme: {selected_theme_name} - incorporate this theme visually throughout
+2. Event Date: {event_date} - display this prominently on the card
+3. Location: {event_location} - include this clearly visible
+4. Occasion: {occasion} - reflect this in the design
+5. Invitation Text: {invitation_text} - embed this text clearly readable on the card
+
+The card should have:
+- Make sure the full text above is actually written on the card (not just implied), keep the layout clean and readable.
+  Center the text and leave some breathing room.
+- A bright, colorful, and fun background that matches the {selected_theme_name} theme
+- Invitation event and theme based message embeded inside the picture Beautiful, age-appropriate illustrations related to the theme-
+- ALL TEXT (date, location, occasion, invitation message) clearly visible and readable and in English
+- Professional, polished design suitable for printing
+- Happy, festive atmosphere
+- Text should be in English language only and large enough to read when printed
+
+Style: Colorful, fun, kid-friendly, professional invitation card design with all text embedded and clearly visible."""
+        
+        # Generate image using FLUX.1-dev
+        img = image_client.text_to_image(
+            image_prompt,
+            model=IMAGE_MODEL
+        )
+        
+        # Save image
+        image_filename = f"invitation_{selected_theme_name.replace(' ', '_').lower()}.png"
+        image_path = os.path.join(INVITATION_IMAGE_DIR, image_filename)
+        os.makedirs(INVITATION_IMAGE_DIR, exist_ok=True)
+        
+        # InferenceClient.text_to_image returns a PIL Image
+        if hasattr(img, 'save'):
+            img.save(image_path)
+        else:
+            # Fallback: try to save as bytes or convert
+            from PIL import Image
+            import io
+            if isinstance(img, bytes):
+                with open(image_path, 'wb') as f:
+                    f.write(img)
+            else:
+                # Try to open as image
+                img_pil = Image.open(io.BytesIO(img)) if hasattr(img, '__bytes__') else Image.fromarray(img)
+                img_pil.save(image_path)
+        
+        # Update party context
+        party_context.invitation_text = invitation_text
+        party_context.invitation_image_path = image_path
+        
+        result = {
+            "selected_theme": selected_theme_name,
+            "invitation_text": invitation_text,
+            "image_path": image_path,
+            "status": "success"
+        }
+        
+        return json.dumps(result, indent=2, ensure_ascii=False)
+        
+    except Exception as e:
+        error_msg = f"Error generating invitation: {str(e)}"
+        return json.dumps({
+            "error": error_msg,
+            "selected_theme": selected_theme_name,
+            "status": "error"
+        })
+
+
+def theme_planning_entry(party_description: Optional[str] = None, selected_theme_name: Optional[str] = None) -> str:
+    """
+    Main entry point for theme planning agent.
+    
+    Args:
+        party_description: User's party description (for generating themes)
+        selected_theme_name: Selected theme name (for generating invitation)
+        
+    Returns:
+        Result string
+    """
+    if selected_theme_name:
+        # Generate invitation for selected theme
+        return generate_invitation_for_theme.invoke({"selected_theme_name": selected_theme_name})
+    elif party_description:
+        # Generate theme options
+        return generate_party_themes.invoke({"party_description": party_description})
+    else:
+        return json.dumps({"error": "Either party_description or selected_theme_name must be provided"})
+
+
+# Export tools for orchestrator
+__all__ = ['generate_party_themes', 'generate_invitation_for_theme', 'theme_planning_entry']
+

src/agents/venue_search_agent.py

@@ -0,0 +1,219 @@
+"""Subagent 3: Venue Search Agent - Uses Bright Data MCP SERP to find party venues."""
+
+from typing import Optional, List, Dict, Any
+from langchain_core.tools import tool
+
+from src.party_context import party_context, VenueResult
+from src.mcp.mcp_clients import brightdata_mcp
+
+import asyncio
+
+
+def _build_query(location: str, query: str, budget: Optional[str], guest_count: Optional[int]) -> str:
+    """
+    Build a natural-language query string for SERP based on party info.
+    """
+    base = query or "party venue"
+    parts = [base]
+
+    if guest_count and guest_count > 0:
+        parts.append(f"for about {guest_count} guests")
+
+    if budget:
+        parts.append(f"under {budget}")
+
+    parts.append(f"in {location}")
+    return " ".join(parts)
+
+
+def _format_serp_results(
+    location: str,
+    venues: List[VenueResult],
+    original_query: str,
+) -> str:
+    """
+    Create a natural-language, nicely formatted summary of found venues.
+    """
+    if not venues:
+        return (
+            f"I tried searching for venues in **{location}** for:\n"
+            f"> {original_query}\n\n"
+            "but I couldn’t find anything reliable from the search results.\n"
+            "You might want to try a broader location or a higher budget."
+        )
+
+    lines = []
+    lines.append(
+        f"Here are some venue options I found in **{location}** that could work for your party:\n"
+    )
+
+    for i, v in enumerate(venues, start=1):
+        entry = [f"{i}. **{v.name}**"]
+
+        # Small natural-language description
+        if v.description:
+            entry.append(f"   – {v.description}")
+
+        if v.address:
+            entry.append(f"   • 📍 Address: {v.address}")
+
+        if v.rating is not None:
+            entry.append(f"   • ⭐ Approx. rating: {v.rating}/5")
+
+        if v.price_level:
+            entry.append(f"   • 💰 Price indication: {v.price_level}")
+
+        if v.phone:
+            entry.append(f"   • 📞 Contact: {v.phone}")
+
+        if v.url:
+            entry.append(f"   • 🔗 More details & booking: {v.url}")
+
+        lines.append("\n".join(entry))
+
+    lines.append(
+        "\n💡 *Tip*: Use the links above to check exact pricing, availability, and to confirm capacity for your guest count."
+    )
+
+    return "\n\n".join(lines)
+
+
+@tool
+def search_party_venues(
+    location: str,
+    query: str = "party venue",
+    max_results: int = 5,
+    budget: str = "",
+    guest_count: int = 0,
+) -> str:
+    """
+    Search for party venues using Bright Data MCP SERP.
+
+    Args:
+        location: City and state (e.g., "Sunnyvale, CA")
+        query: Base search query (default: "party venue")
+        max_results: Maximum number of results to return
+        budget: Optional budget description (e.g., "$700", "under $1000")
+        guest_count: Optional approximate guest count (e.g., 60)
+
+    Returns:
+        A natural-language, nicely formatted string describing the venues.
+    """
+    # Remember location in shared context
+    party_context.search_location = location
+
+    # Build NL query for SERP
+    full_query = _build_query(location, query, budget, guest_count)
+
+    try:
+        # Call Bright Data MCP SERP asynchronously
+        serp_response = asyncio.run(
+            brightdata_mcp.serp_search(
+                query=full_query,
+                search_engine="google",
+                country="us",
+                language="en",
+                results_count=max_results,
+                parse_results=True,
+            )
+        )
+
+        # Handle CallToolResult object - extract the actual data
+        if not isinstance(serp_response, dict):
+            # If it's a CallToolResult or similar object, try to extract content
+            if hasattr(serp_response, 'content'):
+                if isinstance(serp_response.content, list) and len(serp_response.content) > 0:
+                    import json
+                    first_content = serp_response.content[0]
+                    if hasattr(first_content, 'text'):
+                        try:
+                            serp_response = json.loads(first_content.text)
+                        except (json.JSONDecodeError, AttributeError):
+                            serp_response = {"text": first_content.text}
+                    elif hasattr(first_content, 'data'):
+                        serp_response = first_content.data
+                else:
+                    serp_response = serp_response.content if serp_response.content else {}
+            elif hasattr(serp_response, '__dict__'):
+                serp_response = serp_response.__dict__
+            else:
+                # Fallback: try to convert to dict
+                serp_response = dict(serp_response) if hasattr(serp_response, '__iter__') else {}
+
+        # Ensure serp_response is a dict
+        if not isinstance(serp_response, dict):
+            serp_response = {}
+
+        # The exact schema depends on Bright Data; we assume something like:
+        # {
+        #   "results": [
+        #       {
+        #           "title": "...",
+        #           "url": "...",
+        #           "snippet": "...",
+        #           "rating": ...,
+        #           "price_level": "...",
+        #           "address": "...",
+        #           "phone": "..."
+        #       },
+        #       ...
+        #   ]
+        # }
+        raw_results = serp_response.get("results", []) or serp_response.get("data", []) or serp_response.get("organic", [])
+
+        venues: List[VenueResult] = []
+        for r in raw_results[:max_results]:
+            title = r.get("title") or r.get("name") or "Venue"
+            url = r.get("url") or r.get("link") or ""
+            snippet = r.get("snippet") or r.get("description") or ""
+            rating = r.get("rating")  # may be float or None
+            price = r.get("price_level") or r.get("price") or None
+            address = r.get("address") or r.get("location") or None
+            phone = r.get("phone") or r.get("telephone") or None
+
+            venue = VenueResult(
+                name=title,
+                url=url,
+                rating=float(rating) if isinstance(rating, (int, float, str)) and str(rating).replace(".", "", 1).isdigit() else None,
+                price_level=price,
+                address=address,
+                phone=phone,
+                description=snippet,
+            )
+            venues.append(venue)
+
+        # Save into shared context so other agents / UI can reuse
+        party_context.venue_results = venues
+
+        # Return nicely formatted result text
+        return _format_serp_results(location, venues, full_query)
+
+    except Exception as e:
+        return (
+            f"Sorry, I ran into an issue while searching for venues in **{location}**.\n\n"
+            f"Technical details: `{e}`\n\n"
+            "You can try asking again with a slightly different location or budget description."
+        )
+
+
+def venue_search_entry(
+    location: str,
+    query: Optional[str] = None,
+    max_results: int = 5,
+    budget: str = "",
+    guest_count: int = 0,
+) -> str:
+    """
+    Main entry point for venue search agent, compatible with orchestrator wrapper.
+    """
+    search_query = query or "party venue"
+    return search_party_venues.invoke({
+        "location": location,
+        "query": search_query,
+        "max_results": max_results,
+        "budget": budget,
+        "guest_count": guest_count,
+    })
+
+
+__all__ = ["search_party_venues", "venue_search_entry"]

src/config.py

@@ -0,0 +1,28 @@
+"""Configuration management for the Plan-a-Party app."""
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Hugging Face tokens
+HF_TOKEN = os.getenv("HF_TOKEN") or os.getenv("HUGGINGFACEHUB_API_TOKEN")
+HUGGINGFACEHUB_API_TOKEN = os.getenv("HUGGINGFACEHUB_API_TOKEN")
+
+# Email configuration
+SMTP_HOST = os.getenv("SMTP_HOST", "smtp.gmail.com")
+SMTP_PORT = int(os.getenv("SMTP_PORT", "465"))
+SMTP_USER = os.getenv("SMTP_USER")
+SMTP_PASSWORD = os.getenv("SMTP_PASSWORD")
+FROM_EMAIL = os.getenv("FROM_EMAIL")
+
+# MCP API keys (user-provided at runtime)
+FEWSATS_API_KEY = os.getenv("FEWSATS_API_KEY", "")
+
+# Model configurations
+TEXT_MODEL = os.getenv("TEXT_MODEL", "meta-llama/Llama-3.3-70B-Instruct")
+IMAGE_MODEL = os.getenv("IMAGE_MODEL", "black-forest-labs/FLUX.1-dev")
+
+# File paths
+INVITATION_IMAGE_DIR = "invitations"
+os.makedirs(INVITATION_IMAGE_DIR, exist_ok=True)
+

src/mcp/__init__.py

@@ -0,0 +1,2 @@
+"""MCP client modules for Plan-a-Party system."""
+

src/mcp/mcp_clients.py

@@ -0,0 +1,343 @@
+"""
+Real MCP clients for Amazon, Fewsats, and Resend using langchain-mcp-adapters.
+"""
+
+import os
+import asyncio
+from typing import Dict, Any, Optional
+
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain_mcp_adapters.tools import load_mcp_tools
+
+
+# ----------------------------------------------------
+# 1. CONFIGURATION FOR YOUR MCP SERVERS
+# ----------------------------------------------------
+# Check if amazon-mcp server exists before adding it
+AMAZON_MCP_PATH = "amazon-mcp/build/index.js"
+amazon_mcp_available = os.path.exists(AMAZON_MCP_PATH)
+
+MCP_SERVERS = {
+    "resend": {
+        "url": "https://mcp.zapier.com/api/mcp/s/" + (os.getenv("ZAPIER_GMAIL_API_KEY") or "") + "/mcp",
+        "transport": "sse",
+    },
+    "brightdata": {
+        "url": "https://mcp.brightdata.com/sse?token=" + (os.getenv("BRIGHTDATA_TOKEN") or ""),
+        "transport": "sse",
+    },
+}
+
+# Only add Amazon MCP if the server file exists
+if amazon_mcp_available:
+    MCP_SERVERS["amazon"] = {
+        "transport": "stdio",
+        "command": "node",
+        "args": [AMAZON_MCP_PATH],
+    }
+else:
+    print(f"[WARNING] Amazon MCP server not found at {AMAZON_MCP_PATH}. Amazon shopping will be disabled.")
+    print(f"[INFO] To enable Amazon shopping, build the amazon-mcp server:")
+    print(f"      cd amazon-mcp && npm install && npm run build")
+
+
+# ----------------------------------------------------
+# 2. MCP Session Manager
+# ----------------------------------------------------
+class MCPConnectionManager:
+    """Manages MCP sessions for all servers."""
+
+    def __init__(self):
+        self.client = MultiServerMCPClient(MCP_SERVERS)
+
+    async def call_tool(self, server: str, tool_name: str, params: dict):
+        """Call a specific tool from the given MCP server."""
+        async with self.client.session(server) as session:
+            tools = await load_mcp_tools(session)
+
+            # Find the matching tool
+            tool = next((t for t in tools if t.name == tool_name), None)
+            if not tool:
+                raise ValueError(f"Tool '{tool_name}' not found in MCP server '{server}'.")
+
+            result = await session.call_tool(tool_name, params)
+            # Extract content from CallToolResult if it's not already a dict
+            if hasattr(result, 'content'):
+                # CallToolResult.content can be a list of TextContent or other content types
+                if isinstance(result.content, list) and len(result.content) > 0:
+                    # Get the first content item, which is usually the actual data
+                    content = result.content[0]
+                    if hasattr(content, 'text'):
+                        # If it's TextContent, parse the JSON
+                        import json
+                        try:
+                            return json.loads(content.text)
+                        except (json.JSONDecodeError, AttributeError):
+                            return {"text": content.text}
+                    elif hasattr(content, 'data'):
+                        return content.data
+                # If content is directly accessible
+                return result.content if not isinstance(result.content, list) else result.content[0] if result.content else {}
+            # If result is already a dict or has a dict-like interface
+            if hasattr(result, '__dict__'):
+                return result.__dict__
+            return result
+
+
+mcp_manager = MCPConnectionManager()
+
+
+# ----------------------------------------------------
+# 3. AMAZON MCP CLIENT
+# ----------------------------------------------------
+class AmazonMCPClient:
+    """
+    Thin sync wrapper around async MCP calls to the Amazon server.
+
+    Server id: "amazon"  (from your mcp.json)
+    Tools (from server.py):
+      - search
+      - get_payment_offers
+      - get_payment_offers_x402
+      - pay_with_x402
+      - get_order_by_external_id
+      - get_order_by_payment_token
+      - get_user_orders
+    """
+
+    def __init__(self):
+        self.available = amazon_mcp_available
+
+    # ---------- internal async helpers ----------
+
+    async def _search_product_async(self, query: str) -> Dict[str, Any]:
+        if not self.available:
+            return {
+                "error": "Amazon MCP server not available",
+                "message": "The amazon-mcp server has not been built. Please run: cd amazon-mcp && npm install && npm run build",
+                "products": []
+            }
+        try:
+            # server tool signature: async def search(q: str) -> Dict
+            return await mcp_manager.call_tool(
+                "amazon",
+                "search",
+                {"q": query},
+            )
+        except Exception as e:
+            return {
+                "error": str(e),
+                "message": f"Error calling Amazon MCP: {e}",
+                "products": []
+            }
+
+    async def _get_payment_offers_async(
+        self,
+        asin: str,
+        shipping_address: Dict[str, Any],
+        user: Dict[str, Any],
+        quantity: int = 1,
+    ) -> Dict[str, Any]:
+        return await mcp_manager.call_tool(
+            "amazon",
+            "get_payment_offers",
+            {
+                "asin": asin,
+                "shipping_address": shipping_address,
+                "user": user,
+                "quantity": quantity,
+            },
+        )
+
+    async def _pay_with_x402_async(
+        self,
+        x_payment: str,
+        asin: str,
+        shipping_address: Dict[str, Any],
+        user: Dict[str, Any],
+        quantity: int = 1,
+    ) -> Dict[str, Any]:
+        return await mcp_manager.call_tool(
+            "amazon",
+            "pay_with_x402",
+            {
+                "x_payment": x_payment,
+                "asin": asin,
+                "shipping_address": shipping_address,
+                "user": user,
+                "quantity": quantity,
+            },
+        )
+
+    # ---------- public sync wrappers ----------
+
+    def search_product(self, query: str) -> Dict[str, Any]:
+        """Sync wrapper around the async search call."""
+        import asyncio
+        return asyncio.run(self._search_product_async(query))
+
+    def get_payment_offers(
+        self,
+        asin: str,
+        shipping_address: Dict[str, Any],
+        user: Dict[str, Any],
+        quantity: int = 1,
+    ) -> Dict[str, Any]:
+        return asyncio.run(
+            self._get_payment_offers_async(
+                asin=asin,
+                shipping_address=shipping_address,
+                user=user,
+                quantity=quantity,
+            )
+        )
+
+    def pay_with_x402(
+        self,
+        x_payment: str,
+        asin: str,
+        shipping_address: Dict[str, Any],
+        user: Dict[str, Any],
+        quantity: int = 1,
+    ) -> Dict[str, Any]:
+        return asyncio.run(
+            self._pay_with_x402_async(
+                x_payment=x_payment,
+                asin=asin,
+                shipping_address=shipping_address,
+                user=user,
+                quantity=quantity,
+            )
+        )
+
+
+# Create singleton instance
+amazon_mcp = AmazonMCPClient()
+
+
+# ----------------------------------------------------
+# 4. FEWSATS MCP CLIENT (X402 + L402 payments)
+# ----------------------------------------------------
+class FewsatsMCPClient:
+    """Payment client for X402 & L402 flows."""
+
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key or os.getenv("FEWSATS_API_KEY")
+
+    async def create_x402_header(self, x402_payload: dict, chain: str = "base-sepolia"):
+        return await mcp_manager.call_tool(
+            "amazon",
+            "x402.createHeader",
+            {
+                "payload": x402_payload,
+                "chain": chain,
+                "apiKey": self.api_key,
+            }
+        )
+
+    async def pay_offer(self, offer_id: str, l402_offer: dict):
+        return await mcp_manager.call_tool(
+            "amazon",
+            "l402.payOffer",
+            {
+                "offerId": offer_id,
+                "l402": l402_offer,
+                "apiKey": self.api_key,
+            }
+        )
+
+
+fewsats_mcp = FewsatsMCPClient()
+
+
+# ----------------------------------------------------
+# 5. RESEND EMAIL MCP CLIENT (send invitations)
+# ----------------------------------------------------
+class ResendMCPClient:
+    """Client for sending emails with attachments (invitation card)."""
+
+    async def send_email(
+        self,
+        from_email: str,
+        to_email: str,
+        subject: str,
+        text_body: str,
+        attachment_bytes: Optional[bytes] = None,
+    ):
+        payload = {
+            "from": from_email,
+            "to": to_email,
+            "subject": subject,
+            "text": text_body,
+        }
+
+        if attachment_bytes:
+            payload["attachments"] = [
+                {
+                    "filename": "invitation.png",
+                    "content": attachment_bytes.decode("latin1"),  # MCP expects string
+                }
+            ]
+
+        return await mcp_manager.call_tool(
+            "resend",
+            "gmail_send_email",
+            payload
+        )
+
+
+resend_mcp = ResendMCPClient()
+
+# ----------------------------------------------------
+# 6. BRIGHT DATA MCP CLIENT (SERP / web search)
+# ----------------------------------------------------
+class BrightDataMCPClient:
+    """
+    Client for Bright Data MCP operations (SERP / web search).
+    Used by the venue_search_agent to find good party venues.
+    """
+
+    async def serp_search(
+        self,
+        query: str,
+        search_engine: str = "google",
+        country: str = "us",
+        language: str = "en",
+        results_count: int = 5,
+        parse_results: bool = True,
+    ) -> Dict[str, Any]:
+        """
+        Call the Bright Data `search_engine` tool.
+
+        The exact output schema depends on Bright Data, but typically includes
+        a list of search results with title, url, snippet, etc.
+        """
+        params = {
+            "query": query,
+            "search_engine": search_engine,
+            "country": country,
+            "language": language,
+            "results_count": results_count,
+            "parse_results": parse_results,
+        }
+
+        # Tool name "search_engine" comes from Bright Data MCP docs.
+        return await mcp_manager.call_tool(
+            "brightdata",
+            "search_engine",
+            params,
+        )
+
+
+brightdata_mcp = BrightDataMCPClient()
+
+# ----------------------------------------------------
+# EXPORT EVERYTHING
+# ----------------------------------------------------
+__all__ = [
+    "amazon_mcp",
+    "fewsats_mcp",
+    "resend_mcp",
+    "brightdata_mcp", 
+    "mcp_manager",
+]

src/party_context.py

@@ -0,0 +1,68 @@
+"""Shared party context between subagents."""
+from typing import List, Optional, Dict, Any
+from pydantic import BaseModel
+
+
+class ThemeOption(BaseModel):
+    """A party theme option."""
+    id: int
+    name: str
+    description: str 
+
+
+class VenueResult(BaseModel):
+    """A venue search result."""
+    name: str
+    url: str
+    rating: Optional[float] = None
+    price_level: Optional[str] = None
+    address: Optional[str] = None
+    phone: Optional[str] = None
+    description: Optional[str] = None
+
+
+class ShoppingItem(BaseModel):
+    """A decor or favor item."""
+    name: str
+    category: str  # "decor" or "favor"
+    description: Optional[str] = None
+
+
+class PartyContext(BaseModel):
+    """Shared context for the party planning workflow."""
+    party_description: Optional[str] = None
+
+    # Event metadata captured via chat
+    event_budget: Optional[str] = None
+    event_location: Optional[str] = None
+    event_date: Optional[str] = None
+
+    # Theme planning
+    theme_options: List[ThemeOption] = []
+    selected_theme_name: Optional[str] = None
+    invitation_text: Optional[str] = None
+    invitation_image_path: Optional[str] = None
+    
+    # Guest list (from CSV)
+    guest_names: List[str] = []
+    guest_emails: List[str] = []
+    emails_sent: bool = False
+    
+    # Venue search
+    venue_results: List[VenueResult] = []
+    search_location: Optional[str] = None
+    
+    # Decor & shopping
+    cart_items: List[Dict[str, Any]] = [] 
+    decor_items: List[ShoppingItem] = []
+    favor_items: List[ShoppingItem] = []
+    selected_items: List[str] = []
+    order_status: Optional[str] = None
+    order_id: Optional[str] = None
+    reasoning_log: List[str] = []          # human-friendly step log
+    last_decision: Optional[Dict[str, Any]] = None  # raw JSON from decide_next_action
+
+
+# Global shared context instance
+party_context = PartyContext()
+

src/tools/__init__.py

@@ -0,0 +1,2 @@
+"""Tool modules for Plan-a-Party system."""
+

src/tools/csv_guest_parser.py

@@ -0,0 +1,60 @@
+"""Helper to parse uploaded CSV guest lists."""
+import pandas as pd
+from typing import List, Tuple
+import io
+
+
+def parse_guest_csv(file_path: str) -> Tuple[List[str], List[str]]:
+    """
+    Parse a CSV file with guest information.
+    
+    Expected columns: 'name' and 'email' (case-insensitive)
+    
+    Args:
+        file_path: Path to the CSV file
+        
+    Returns:
+        Tuple of (guest_names, guest_emails)
+    """
+    try:
+        df = pd.read_csv(file_path)
+        
+        # Normalize column names (case-insensitive)
+        df.columns = df.columns.str.lower().str.strip()
+        
+        # Check for required columns
+        if 'name' not in df.columns or 'email' not in df.columns:
+            raise ValueError("CSV must contain 'name' and 'email' columns")
+        
+        # Extract and clean data
+        names = df['name'].astype(str).str.strip().tolist()
+        emails = df['email'].astype(str).str.strip().tolist()
+        
+        # Filter out empty rows
+        valid_pairs = [(n, e) for n, e in zip(names, emails) if n and e and '@' in e]
+        names = [n for n, e in valid_pairs]
+        emails = [e for n, e in valid_pairs]
+        
+        return names, emails
+        
+    except Exception as e:
+        raise ValueError(f"Error parsing CSV: {str(e)}")
+
+
+def parse_guest_csv_from_bytes(csv_bytes: bytes) -> Tuple[List[str], List[str]]:
+    """Parse CSV from bytes (for Gradio file uploads)."""
+    df = pd.read_csv(io.BytesIO(csv_bytes))
+    df.columns = df.columns.str.lower().str.strip()
+    
+    if 'name' not in df.columns or 'email' not in df.columns:
+        raise ValueError("CSV must contain 'name' and 'email' columns")
+    
+    names = df['name'].astype(str).str.strip().tolist()
+    emails = df['email'].astype(str).str.strip().tolist()
+    
+    valid_pairs = [(n, e) for n, e in zip(names, emails) if n and e and '@' in e]
+    names = [n for n, e in valid_pairs]
+    emails = [e for n, e in valid_pairs]
+    
+    return names, emails
+

src/ui/__init__.py

@@ -0,0 +1,2 @@
+"""UI modules for Plan-a-Party system."""
+

src/ui/gradio_ui.py

@@ -0,0 +1,682 @@
+import os
+from typing import List, Dict, Tuple, Optional
+
+import gradio as gr
+
+from src.agents.orchestrator import orchestrator_chat, guest_invite_wrapper
+from src.party_context import party_context
+
+# -------------------------------------------------
+# 🎨 Custom theme (vibrant but still professional)
+# -------------------------------------------------
+party_theme = gr.themes.Soft(
+    primary_hue="pink",
+    secondary_hue="indigo",
+    neutral_hue="slate",
+).set(
+    body_background_fill="#050816",
+    body_background_fill_dark="#020617",
+    body_text_color="#e5e7eb",
+    body_text_color_subdued="#9ca3af",
+    button_primary_background_fill="#ec4899",
+    button_primary_background_fill_hover="#db2777",
+    button_primary_text_color="#f9fafb",
+    button_secondary_background_fill="#111827",
+    button_secondary_background_fill_hover="#1f2937",
+    button_secondary_text_color="#e5e7eb",
+    block_background_fill="#020617",
+    block_border_width="0px",
+    block_shadow="0 18px 45px rgba(15,23,42,0.6)",
+)
+
+# 💅 Extra CSS polish – injected via <style> tag (no css= on Blocks)
+party_css = """
+.gradio-container {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif;
+}
+
+/* Big gradient header */
+#hero-header {
+  background: radial-gradient(circle at top left, #f97316, #ec4899, #6366f1);
+  border-radius: 1.5rem;
+  padding: 1.5rem 1.75rem;
+  color: white;
+  box-shadow: 0 18px 45px rgba(15,23,42,0.6);
+}
+
+#hero-header h1 {
+  font-size: 2rem;
+  font-weight: 800;
+  letter-spacing: 0.02em;
+  margin-bottom: 0.35rem;
+}
+
+#hero-header p {
+  margin: 0.15rem 0;
+  font-size: 0.95rem;
+  opacity: 0.96;
+}
+
+/* Generic card containers (cart, flow, invitation, guest list, decor) */
+.section-card {
+  border-radius: 1.25rem;
+  border: 1px solid rgba(148,163,184,0.35);
+  background: rgba(15,23,42,0.98);
+  padding: 0.9rem 1rem;
+  color: #f9fafb !important;
+}
+
+.section-card * {
+  color: #e5e7eb !important;
+}
+
+/* Cart panel */
+#cart-preview-panel {
+  border-radius: 1.25rem;
+  border: 1px solid rgba(148,163,184,0.4);
+  background: radial-gradient(circle at top, rgba(251,113,133,0.14), rgba(15,23,42,1));
+  padding: 0.9rem 0.85rem;
+  font-size: 0.9rem;
+  color: #f9fafb !important;
+}
+
+#cart-preview-panel * {
+  color: #e5e7eb !important;
+}
+
+/* Section titles */
+.section-title {
+  font-weight: 700 !important;
+  font-size: 1.05rem !important;
+  color: #f9fafb !important;
+}
+
+/* Chat panel styling */
+.party-chat-panel {
+  border-radius: 1.25rem;
+  background: radial-gradient(circle at top, rgba(148,163,184,0.12), rgba(15,23,42,1));
+  border: 1px solid rgba(148,163,184,0.25);
+  padding: 0.9rem;
+}
+
+/* Chatbot bubbles */
+.party-chatbot .wrap {
+  background: transparent !important;
+}
+.party-chatbot .message.user {
+  background: rgba(15,118,110,0.16) !important;
+  border-radius: 1.1rem !important;
+}
+.party-chatbot .message.bot {
+  background: rgba(79,70,229,0.18) !important;
+  border-radius: 1.1rem !important;
+}
+
+/* Textbox + buttons row */
+.party-input-row textarea {
+  border-radius: 999px !important;
+}
+
+/* Make primary button pill-shaped */
+button.primary {
+  border-radius: 999px !important;
+  font-weight: 600 !important;
+}
+
+/* Smaller headings inside right column */
+#cart-preview-panel h1,
+#cart-preview-panel h2,
+#cart-preview-panel h3 {
+  font-size: 1rem;
+}
+"""
+
+
+# =================================================
+#  Handlers & helpers
+# =================================================
+
+def get_cart_preview_text() -> str:
+    """
+    Build a human-friendly cart preview from party_context.cart_items.
+    Assumes theme_decor_favor_shop_agent.shop_on_amazon() stored a list of dicts.
+    """
+    cart = getattr(party_context, "cart_items", []) or []
+
+    if not cart:
+        return (
+            "🛒 **Cart Preview**\n\n"
+            "Your cart is currently empty.\n"
+            "Once I shop for decor and favors on Amazon, you’ll see matching items here."
+        )
+
+    lines: List[str] = []
+    lines.append("🛒 **Amazon Cart Preview**\n")
+
+    total_prices: List[float] = []
+    currency: Optional[str] = None
+
+    for idx, item in enumerate(cart, start=1):
+        title = item.get("title") or item.get("requested_name") or f"Item {idx}"
+        url = item.get("url") or ""
+        price = item.get("price")
+
+        if isinstance(price, (int, float)):
+            total_prices.append(float(price))
+
+        if not currency and item.get("currency"):
+            currency = item["currency"]
+
+        line = f"{idx}. **{title}**"
+        if price is not None:
+            if currency:
+                line += f" – ~{price} {currency}"
+            else:
+                line += f" – ~{price}"
+        if url:
+            line += f"\n   {url}"
+
+        lines.append(line)
+
+    if total_prices:
+        total = sum(total_prices)
+        if currency:
+            lines.append(f"\n**Estimated total (before tax & shipping):** ~{total:.2f} {currency}")
+        else:
+            lines.append(f"\n**Estimated total (before tax & shipping):** ~{total:.2f}")
+
+    lines.append(
+        "\n💡 *No real orders are placed here.* "
+        "Open the Amazon links to review and complete checkout manually."
+    )
+
+    return "\n".join(lines)
+
+
+# ---------- Chat submit handler ----------
+
+def chat_submit(
+    user_message: str,
+    history: Optional[List[Dict]] = None,
+) -> Tuple[List[Dict], List[Dict], Dict, Dict, Dict, Dict]:
+    """
+    Main chat handler.
+    - Sends user message + history to orchestrator_chat (LLM + tools).
+    - Updates Chatbot.
+    - Updates "Generate Invitation Card" button visibility based on required info.
+    - Updates shopping_checkboxes with decor & favor items.
+    - Updates cart_preview markdown if a cart is ready.
+
+    Returns (in order):
+    - chat_history (state)
+    - chatbot messages
+    - generate_invitation_btn.update
+    - shopping_checkboxes.update
+    - cart_preview.update
+    """
+    history = history or []
+    user_message = (user_message or "").strip()
+
+    def _cart_preview_update():
+        # Only refresh when a cart is ready
+        if getattr(party_context, "order_status", None) == "cart_ready":
+            return gr.update(value=get_cart_preview_text(), visible=True)
+        # Otherwise, leave as-is 
+        return gr.update(value=get_cart_preview_text())
+
+    # If user just hit Enter on empty input, keep state, only refresh cart preview
+    if not user_message:
+        return (
+            history,
+            history,
+            gr.update(),          # no change to generate button
+            gr.update(),          # no change to shopping checkboxes
+            _cart_preview_update(),
+            # COMMENTED OUT: agent trace
+            # gr.update(value=get_agent_trace_text()), 
+            gr.update(),
+        )
+
+    # 1) Get orchestrator reply (this may call tools and update party_context)
+    try:
+        reply = orchestrator_chat(user_message, history)
+    except Exception as e:
+        print(f"[chat_submit] Error in orchestrator_chat: {e}")
+        import traceback
+        traceback.print_exc()
+        reply = f"I encountered an error: {e}. Please try again."
+
+    # 2) Build new history (Gradio 6 expects list[dict] with role/content)
+    new_history = history + [
+        {"role": "user", "content": user_message},
+        {"role": "assistant", "content": reply},
+    ]
+
+    # 3) "Generate Invitation Card" button visibility
+    has_all_info = (
+        party_context.event_date is not None
+        and party_context.event_location is not None
+        and party_context.selected_theme_name is not None
+    )
+
+    print(
+        f"[chat_submit] Checking requirements - Date: {party_context.event_date}, "
+        f"Location: {party_context.event_location}, Theme: {party_context.selected_theme_name}"
+    )
+    print(f"[chat_submit] All info available: {has_all_info}")
+
+    if has_all_info:
+        generate_btn_update = gr.update(visible=True, interactive=True)
+    else:
+        generate_btn_update = gr.update(visible=False, interactive=False)
+
+    # 4) Shopping list (decor + favors) → CheckboxGroup
+    if party_context.decor_items or party_context.favor_items:
+        shopping_choices: List[str] = []
+        for item in party_context.decor_items:
+            shopping_choices.append(f"decor: {item.name} – {item.description}")
+        for item in party_context.favor_items:
+            shopping_choices.append(f"favor: {item.name} – {item.description}")
+
+        shopping_update = gr.update(
+            choices=shopping_choices,
+            visible=True,
+            value=[],  # nothing selected by default
+        )
+    else:
+        # no update if nothing new
+        shopping_update = gr.update()
+
+    # 5) Cart preview (Markdown)
+    cart_preview_update = _cart_preview_update()
+
+    # COMMENTED OUT: agent trace
+    # # 6) Agent trace (Markdown)
+    # agent_trace_update = gr.update(value=get_agent_trace_text())
+
+    return (
+        new_history,          # chat_history state
+        new_history,          # chatbot messages
+        generate_btn_update,  # "Generate Invitation Card" button
+        shopping_update,      # Decor & favors checkbox list
+        cart_preview_update,  # Cart preview markdown
+        # COMMENTED OUT: agent trace
+        # agent_trace_update,  # Agent trace markdown
+        gr.update(),          # Placeholder for agent_trace
+    )
+
+   
+
+# ---------- Invitation generation handler ----------
+
+def generate_invitation_card(
+    history: Optional[List[Dict]] = None,
+) -> Tuple[List[Dict], List[Dict], Dict, Dict]:
+    """
+    Called when user clicks "Generate Invitation Card" button.
+    Generates the invitation card with all details embedded.
+    """
+    history = history or []
+
+    if not party_context.selected_theme_name:
+        assistant_msg = (
+            "Please confirm which theme you’re going with in the chat first "
+            "before generating the invitation card."
+        )
+        new_history = history + [{"role": "assistant", "content": assistant_msg}]
+        return new_history, new_history, gr.update(visible=False), gr.update(visible=False)
+
+    from src.agents.theme_planning_agent import generate_invitation_for_theme
+
+    try:
+        print(f"[generate_invitation_card] Generating invitation for theme: {party_context.selected_theme_name}")
+        raw_result = generate_invitation_for_theme.invoke({
+            "selected_theme_name": party_context.selected_theme_name
+        })
+        print(f"[generate_invitation_card] Raw result (first 300 chars): {str(raw_result)[:300]}")
+
+        # Assume the tool either:
+        #  - updates party_context.invitation_image_path + invitation_text
+        #  - OR returns a JSON blob with those fields.
+        invitation_text = getattr(party_context, "invitation_text", None)
+        image_path = getattr(party_context, "invitation_image_path", None)
+
+        # Try to parse JSON if raw_result is a JSON-like string
+        if isinstance(raw_result, str):
+            raw_str = raw_result.strip()
+            if raw_str.startswith("{") and raw_str.endswith("}"):
+                try:
+                    data = json.loads(raw_str)
+                    invitation_text = data.get("invitation_text", invitation_text)
+                    image_path = data.get("image_path", image_path)
+                except Exception:
+                    pass
+
+        # Build a nice assistant message
+        if not invitation_text:
+            # Fallback: generic text using context
+            invitation_text = (
+                f"You're invited to a **{party_context.selected_theme_name}** party on "
+                f"**{party_context.event_date}** at **{party_context.event_location}**! 🎉\n\n"
+                "I’ve tried to embed these details into the invitation image as well."
+            )
+
+        if image_path and os.path.exists(image_path):
+            assistant_msg = (
+                f"🎉 **Your invitation card is ready!**\n\n"
+                f"{invitation_text}\n\n"
+                f"Check the image below — it should have your theme, date and venue text baked into the design."
+            )
+            image_update = gr.update(value=image_path, visible=True)
+        else:
+            assistant_msg = (
+                f"I generated the invitation message, but I couldn’t find a valid image file yet.\n\n"
+                f"{invitation_text}\n\n"
+                "Please check the server logs for `invitation_image_path` or try again."
+            )
+            image_update = gr.update(visible=False)
+
+    except Exception as e:
+        import traceback
+        error_details = traceback.format_exc()
+        print(f"[generate_invitation_card] Error: {e}\n{error_details}")
+        assistant_msg = f"❌ Error generating invitation card: {e}. Please try again."
+        image_update = gr.update(visible=False)
+
+    new_history = history + [
+        {"role": "user", "content": "Generate invitation card"},
+        {"role": "assistant", "content": assistant_msg},
+    ]
+
+    # Hide the button to avoid duplicate spam; you can keep it visible=True if you prefer re-gen
+    generate_btn_update = gr.update(visible=False)
+
+    return new_history, new_history, generate_btn_update, image_update
+
+
+# ---------- Guest CSV upload handler ----------
+
+def upload_guest_csv(file, history: Optional[List[Dict]] = None) -> Tuple[List[Dict], List[Dict], str]:
+    """
+    Handle guest CSV upload.
+    - Calls guest_invite_wrapper(csv_file_path=...) to load guests into party_context.
+    - Appends a status message into the chat.
+    """
+    history = history or []
+
+    if file is None:
+        msg = "Please upload a CSV file with 'name' and 'email' columns."
+        new_history = history + [{"role": "assistant", "content": msg}]
+        return new_history, new_history, msg
+
+    try:
+        print(f"[upload_guest_csv] Uploading guest list from CSV file: {file.name}")
+        result = guest_invite_wrapper(csv_file_path=file.name, send_emails=False)
+        assistant_msg = (
+            f"{result} Once you’re ready, tell me in chat if I should send "
+            "invitations to everyone."
+        )
+    except Exception as e:
+        assistant_msg = f"❌ Error loading guest list: {e}"
+
+    new_history = history + [{"role": "assistant", "content": assistant_msg}]
+    return new_history, new_history, assistant_msg
+
+
+# ---------- Shopping selection handler ----------
+
+def update_shopping_selection(
+    selected_items: List[str],
+    history: Optional[List[Dict]] = None,
+) -> Tuple[List[Dict], List[Dict]]:
+    """
+    Update selected shopping items in shared context.
+    The actual order placement will be driven by orchestrator_chat once user confirms in natural language.
+    """
+    history = history or []
+    selected_items = selected_items or []
+
+    cleaned = [
+        s.split(": ", 1)[1] if ": " in s else s
+        for s in selected_items
+    ]
+    party_context.selected_items = cleaned
+
+    assistant_msg = (
+        f"Great, I’ve saved {len(cleaned)} items for your decor & favors. "
+        "Just tell me in chat when you’re ready for me to build your Amazon cart."
+    )
+    new_history = history + [{"role": "assistant", "content": assistant_msg}]
+    return new_history, new_history
+
+##adding helper to turn reasoning_log into text
+# COMMENTED OUT: agent trace function
+# def get_agent_trace_text() -> str:
+#     log = getattr(party_context, "reasoning_log", []) or []
+#     if not log:
+#         return (
+#             "🧠 **Agent Trace**\n\n"
+#             "No internal steps recorded yet. As the planner routes between sub-agents, "
+#             "you'll see decisions and tool calls here."
+#         )
+#     return "🧠 **Agent Trace (latest steps)**\n\n" + "\n\n---\n\n".join(log[-10:])
+
+# =================================================
+#  Build interface
+# =================================================
+
+def build_interface():
+    with gr.Blocks(
+        title="Plan-A-Party 🎉 (Multi-Agent Party Planner)",
+    ) as demo:
+        # Inject custom CSS (since this Gradio version doesn't support css=)
+        gr.HTML(f"<style>{party_css}</style>")
+
+        # Hero header
+        with gr.Row(elem_id="hero-header"):
+            with gr.Column(scale=3):
+                gr.Markdown(
+                    """
+                    <h1>🎉 Plan-A-Party – Your AI Party Planner </h1>
+                    <p>Describe your party and I’ll help you:</p>
+                    <p>✨ Pick a theme · 🏨 Find a venue · 📨 Send invites · 🛍️ Build a decor & favors cart</p>
+                    """
+                )
+            with gr.Column(scale=1):
+                gr.Markdown(
+                    """
+                    <p style="text-align:right; font-size:0.85rem; opacity:0.9;">
+                    Powered by multi-agent LLM orchestration + MCP<br/>
+                    <span style="opacity:0.8;">Private to your browser session.</span>
+                    </p>
+                    """
+                )
+
+        # Global chat history state (list of {"role": ..., "content": ...})
+        chat_history = gr.State([])
+
+        with gr.Row():
+            # LEFT: main chat
+            with gr.Column(scale=3, elem_classes=["party-chat-panel"]):
+                chatbot = gr.Chatbot(
+                    label="Party Planning Chat",
+                    height=360,
+                    elem_classes=["party-chatbot"],
+                )
+
+                with gr.Row(elem_classes=["party-input-row"]):
+                    user_input = gr.Textbox(
+                        placeholder="“e.g., We're hosting a 5th birthday for 60 guests in Sunnyvale next month…”",
+                        scale=8,
+                        lines=2,
+                        show_label=False,
+                    )
+                    send_btn = gr.Button("Send ✨", variant="primary", scale=1)
+
+            # RIGHT: cart preview + quick hints
+            with gr.Column(scale=1):
+                with gr.Column(elem_classes=["section-card"]):
+                    gr.Markdown(
+                        "### 🛒 Cart Preview",
+                        elem_classes=["section-title"],
+                    )
+                    gr.Markdown(
+                        "As I shop for decor & favors, I’ll build an Amazon cart here so you can review it.",
+                    )
+                    cart_preview = gr.Markdown(
+                        value=get_cart_preview_text(),
+                        elem_id="cart-preview-panel",
+                    )
+                # COMMENTED OUT: Agent trace panel
+                # # Agent trace panel (NEW)
+                # with gr.Column(elem_classes=["section-card"]):
+                #     gr.Markdown(
+                #         "### 🧠 Agent Trace",
+                #         elem_classes=["section-title"],
+                #     )
+                #     agent_trace = gr.Markdown(
+                #         value=get_agent_trace_text(),
+                #     )
+
+                gr.Markdown(
+                    """
+                    #### 🔍 Suggested flow
+                    1. Describe your party  
+                    2. Approve a theme in chat  
+                    3. Let me find venues  
+                    4. Generate your invite card  
+                    5. Upload guest list & send invites  
+                    6. Ask me to shop decor & favors  
+                    """,
+                    elem_classes=["section-card"],
+                )
+
+        # --- Generate Invitation Card Button ---
+        with gr.Column(elem_classes=["section-card"]):
+            gr.Markdown(
+                "### 🎨 Invitation Card",
+                elem_classes=["section-title"],
+            )
+            gr.Markdown(
+                "After you’ve described your party, picked a theme in chat, and I know your **date & location**, "
+                "this button will light up so you can generate your invitation card.",
+            )
+            generate_invitation_btn = gr.Button(
+                "Generate Invitation Card 🖼️",
+                variant="primary",
+                visible=False,
+            )
+
+            invitation_image = gr.Image(
+                label="Your Invitation Card",
+                visible=False,
+                type="filepath",
+            )
+
+        # --- Guest list upload ---
+        with gr.Column(elem_classes=["section-card"]):
+            gr.Markdown(
+                "### 📧 Guest List & Invites",
+                elem_classes=["section-title"],
+            )
+            gr.Markdown(
+                "Upload a CSV with columns: **name**, **email**. "
+                "Once it’s loaded, just say in chat if you’d like me to send invitations.",
+            )
+            guest_csv = gr.File(label="Guest List CSV", file_types=[".csv"])
+            guest_status = gr.Textbox(
+                label="Guest List Status",
+                interactive=False,
+            )
+
+        # --- Decor & favors shopping hooks ---
+        with gr.Column(elem_classes=["section-card"]):
+            gr.Markdown(
+                "### 🛍️ Decor & Favors (Shopping)",
+                elem_classes=["section-title"],
+            )
+            gr.Markdown(
+                "I’ll propose theme-matching decor and party favors. "
+                "Select what you like, then ask me in chat to build your Amazon cart.",
+            )
+
+            shopping_checkboxes = gr.CheckboxGroup(
+                choices=[],
+                label="Suggested items (populated by decor agent)",
+                interactive=True,
+            )
+            update_shopping_btn = gr.Button("Save selected items 💾", variant="secondary")
+
+            fewsats_api_key = gr.Textbox(
+                label="FEWSATS_API_KEY (optional for future auto-checkout)",
+                type="password",
+                placeholder="For this demo, checkout is still manual on Amazon.",
+            )
+
+        # === Wire up events ===
+
+        # COMMENTED OUT: agent_trace component - using placeholder
+        agent_trace_placeholder = gr.Markdown(visible=False)
+
+        # Chat send (button)
+        send_btn.click(
+            fn=chat_submit,
+            inputs=[user_input, chat_history],
+            outputs=[
+                chat_history,            # 1: updated history state
+                chatbot,                 # 2: chatbot display
+                generate_invitation_btn, # 3: button visibility
+                shopping_checkboxes,     # 4: shopping list
+                cart_preview,            # 5: cart preview
+                # COMMENTED OUT: agent trace
+                # agent_trace,              # 6: agent trace
+                agent_trace_placeholder,  # 6: placeholder
+            ],
+        ).then(
+            fn=lambda: "",  # Clear input after sending
+            inputs=[],
+            outputs=[user_input],
+        )
+
+        # Chat send (Enter)
+        user_input.submit(
+            fn=chat_submit,
+            inputs=[user_input, chat_history],
+            outputs=[
+                chat_history,
+                chatbot,
+                generate_invitation_btn,
+                shopping_checkboxes,
+                cart_preview,
+                # COMMENTED OUT: agent trace
+                # agent_trace,
+                agent_trace_placeholder,  # placeholder
+            ],
+        ).then(
+            fn=lambda: "",
+            inputs=[],
+            outputs=[user_input],
+        )
+
+        # Generate invitation card button
+        generate_invitation_btn.click(
+            fn=generate_invitation_card,
+            inputs=[chat_history],
+            outputs=[chat_history, chatbot, generate_invitation_btn, invitation_image],
+        )
+
+        # Guest CSV upload
+        guest_csv.upload(
+            fn=upload_guest_csv,
+            inputs=[guest_csv, chat_history],
+            outputs=[chat_history, chatbot, guest_status],
+        )
+
+        # Shopping selection update
+        update_shopping_btn.click(
+            fn=update_shopping_selection,
+            inputs=[shopping_checkboxes, chat_history],
+            outputs=[chat_history, chatbot],
+        )
+
+    return demo