Event Planner

Plan events by searching venues and generating itineraries with Google Maps links.

Quick Start

Plan a night out:

uv run {baseDir}/scripts/plan_event.py "night out" \
  --location "Times Square, NYC" \
  --party-size 4 \
  --budget medium \
  --duration 4h

Plan a weekend day:

uv run {baseDir}/scripts/plan_event.py "weekend day" \
  --location "Central Park, NYC" \
  --party-size 2 \
  --budget "$100 per person" \
  --preferences "outdoors, casual dining"

Plan a date night:

uv run {baseDir}/scripts/plan_event.py "date night" \
  --location "SoHo, NYC" \
  --budget high \
  --duration 3h

Event Types

night-out: Dinner + 1-2 bars/lounges (3-4 hours)
weekend-day: Brunch/lunch + activity + dinner (6-8 hours)
date-night: Romantic restaurant + dessert/drinks spot (2-3 hours)
team-event: Group activity + dinner venue (3-5 hours)
lunch: Single restaurant recommendation
dinner: Single restaurant recommendation
trip: Multi-day itinerary with daily plans

Parameters

--location: City, address, or landmark (required)
--party-size: Number of people (default: 2)
--budget: "low/medium/high" or "$X per person" (default: medium)
--duration: Hours available (e.g., "3h", "full day")
--preferences: Comma-separated (e.g., "vegetarian, outdoor seating, live music")
--start-time: When to start (default: inferred from event type)
--output: text|json (default: text)
--date: Target date in YYYY-MM-DD format for day-specific checks (default: today)

Output Format

Default (text): Markdown itinerary with timeline, venue details, travel info, and Google Maps link

JSON: Structured data with all venue details, coordinates, and parsed metadata

Limitations

API limits: Google Places API has usage quotas (check your billing)
Real-time data: Venue hours may change; always confirm before going
Budget estimates: Based on Google's price level (0-4), not exact costs
Travel times: Uses Google Directions API when available; falls back to distance-based estimates with 30% buffer
Opening hours: Places without verified hours will show warnings; do not assume availability
Event venues: Cultural centers, theaters, and event spaces may have variable hours depending on scheduled events

API Requirements

The event planner uses:

Google Places API (New): Required for venue search
Google Directions API: Optional but recommended for accurate travel times

Both APIs can use the same GOOGLE_PLACES_API_KEY if enabled in Google Cloud Console.

Error Handling

Invalid location → Returns error with suggestions
No venues found → Relaxes filters and retries
API failures → Retry with exponential backoff (3 attempts)

event-planner