Hugging Face's logo

Spaces:
MCP-1st-Birthday
/
Plan-A-Party
Running

App Files Community
Plan-A-Party / PROJECT_SUMMARY.md
AryamaR's picture
AryamaR
Added application code base & container manifest
ebcff02
preview code
|
raw
history blame contribute delete
14.3 kB

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 

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) 

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

  • Folder structure created
  • All 4 subagents implemented
  • Orchestrator agent with conversational flow
  • Gradio UI with interactive chat
  • Shared context management (PartyContext)
  • MCP integration (Bright Data, Resend, Amazon, Fewsats)
  • CSV parsing for guest lists
  • Theme generation with FLUX.1-dev
  • Email sending via Resend MCP
  • Venue search via Bright Data SERP
  • Amazon shopping with query optimization
  • Natural language theme selection
  • Event metadata collection
  • Dynamic UI updates
  • Graceful degradation for optional MCP servers
  • 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 🎉