🎪 EventPulse AI — Physical Event Experience Companion

A smart, conversational AI assistant that helps users discover physical events, plan their attendance, and seamlessly add events to Google Calendar — all through natural language.

---

🎯 Chosen Vertical

Physical Event Experience

EventPulse AI is designed to enhance every step of the physical event journey — from discovery to attendance. Whether it's a concert, sports match, tech conference, food festival, or local meetup, EventPulse helps users:

• Discover events relevant to their interests and location
• Plan their attendance (logistics, what to bring, arrival tips)
• Schedule events directly to Google Calendar via OAuth
• Get answers about venues, accessibility, parking, and tickets

---

🏗️ Approach & Logic

Conversational Core — Gemini AI

EventPulse uses Google Gemini 1.5 Flash as the conversational brain. Each user message is sent to Gemini with a rich system prompt that:

1. Defines the assistant's persona and responsibilities
2. Instructs Gemini to detect calendar intent in the conversation
3. When intent is detected, appends a structured calendar_action JSON block to the response

The Flask backend parses this block, strips it from the visible reply, and surfaces a "Add to Calendar" card in the UI — keeping the UX clean and actionable.

Google Calendar Integration

• Full OAuth 2.0 flow via google-auth-oauthlib
• Credentials stored securely in the Flask server-side session
• Events are created with 60-minute and 10-minute reminders
• Users are redirected to the event in Google Calendar after creation

Conversation Memory

Each browser session maintains a conversation history (stored server-side by session ID), giving Gemini full context to answer follow-up questions naturally.

---

🔧 How the Solution Works

User types message
       │
       ▼
Flask /chat endpoint
       │
       ▼
Gemini 1.5 Flash (with session history + system prompt)
       │
       ├── Detects calendar intent? ──Yes──► Appends calendar_action JSON block
       │                                     Backend parses it
       │                                     Returns clean reply + structured data
       ▼
Frontend renders:
  • Conversational reply (Markdown formatted)
  • [Optional] Calendar card with "Add to Calendar" button
       │
User clicks "Add to Calendar"
       │
       ▼
Flask /calendar/add endpoint
  → Google Calendar API → Event created ✅
  → User redirected to calendar event URL

---

🚀 Setup & Running

Prerequisites

• Python 3.10+
• A Gemini API key from Google AI Studio
• A Google Cloud project with Calendar API enabled and OAuth 2.0 credentials

1. Clone & Install

git clone https://github.com/YOUR_USERNAME/eventpulse-ai.git
cd eventpulse-ai
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Edit .env and add your GEMINI_API_KEY and FLASK_SECRET_KEY

3. Google OAuth Setup

1. Go to Google Cloud Console
2. Create a project → Enable Google Calendar API
3. Create OAuth 2.0 Client ID (Web application)
4. Add http://localhost:5000/calendar/callback as an authorized redirect URI
5. Download the JSON and save as client_secrets.json in the project root

4. Run

python app.py
# Visit http://localhost:5000

---

⚙️ Project Structure

eventpulse-ai/
├── app.py                 # Flask application + Gemini + Calendar logic
├── requirements.txt       # Python dependencies
├── .env.example           # Environment variable template
├── .gitignore
├── templates/
│   ├── index.html         # Main UI (chat interface)
│   └── callback.html      # OAuth redirect handler
└── README.md

---

📐 Assumptions Made

• The app runs on a single server instance (conversation history is in-memory; for production, use Redis or a database)
• Users are assumed to have Google accounts for Calendar integration
• Event recommendations are AI-generated by Gemini based on its knowledge; for real-time event data, a third-party events API (e.g., Ticketmaster, Eventbrite) could be integrated
• Timezone defaults to UTC for calendar events; users should specify their timezone for accuracy
• The client_secrets.json is never committed to the repository (protected by .gitignore)

---

🔒 Security

• OAuth credentials are stored in server-side Flask sessions, never exposed to the client
• client_secrets.json and .env are excluded via .gitignore
• All API calls are server-side only — no API keys are sent to the browser
• Input validation on all /chat and /calendar/add endpoints

---

🌐 Google Services Used

Service	Purpose
Gemini 1.5 Flash	Core LLM for conversation, event understanding, and calendar intent detection
Google Calendar API	Creating and managing calendar events from chat
Google OAuth 2.0	Secure user authentication for Calendar access

---

💡 Evaluation Highlights

• Code Quality: Clean separation of concerns — routing, AI logic, and calendar logic are modular
• Security: No secrets in client-side code; server-side sessions; gitignored credentials
• Efficiency: Gemini Flash model for fast responses; minimal API calls per turn
• Accessibility: Keyboard-navigable UI; semantic HTML; high-contrast design
• Google Services: Meaningful, functional integration of Gemini + Calendar, not just decorative

---

Built for Prompt Wars Virtual — Physical Event Experience vertical.