Project Info

Stream - Smart AI Email Agents

Inspiration

As students juggling classes, work, and extracurriculars, email is a crucial tool—but Gmail’s interface often feels clunky and outdated. Important messages get buried, spam gets through, and finding what you need is harder than it should be. At Team Stream, we envisioned a Gmail experience that’s smarter, more intuitive, and powered by AI. So we built Stream, an AI-enhanced email system that simplifies inbox management and introduces conversational interactions, making your email feel more like your assistant, not your chore.

How we built it

We built Stream using Flask as our backend framework and JavaScript/HTML for the frontend interface. Key technologies and components: Google OAuth for secure login and permissioned access to users' Gmail inboxes. Gemini API (via Google’s Vertex AI) to: Categorize emails into smart folders (e.g., Work, School, Promotions, Events). Power an AI email assistant that allows users to talk to their inbox—ask it things like "Show me all unread school-related emails from this week" or "Summarize emails I got today." Gmail API to fetch, label, and manipulate email threads in real-time. Flask routes serve dynamic content and relay user interactions between the frontend and Gemini.

Challenges we ran into

Integrating OAuth and Gmail API was tricky. Dealing with scopes, tokens, and threading models required careful debugging and sandbox testing.

Accomplishments we're proud of

Created a functional AI email assistant with natural language understanding. Successfully classified emails using Gemini with high accuracy, and auto-labeled them into categories. Built a full-stack web app that integrates several complex APIs under one cohesive user experience. Demoed real-time email conversation with the Gemini-powered agent. Smart reply templates powered by Gemini—get quick, tone-matching suggestions for professional, casual, or apologetic emails. Save time and reply right.

What we learned

How to work with Google’s suite of APIs, including Gmail, OAuth, and Gemini. Build production-ready Flask endpoints and serve dynamic content. Fine-tuning prompts and understanding prompt engineering for email-related tasks. Frontend/backend coordination using asynchronous requests and Google’s data models.

What's next

Mobile version so users can manage smart folders and AI chat on the go Google Chrome Extension that overlays directly onto Gmail, allowing users to manage smart folders and chat with the AI assistant within the Gmail interface itself. Further Gemini training to understand tone and urgency

A modern email management system that uses AI to automatically categorize your emails with a beautiful Next.js frontend and Flask backend.

Architecture

Flask Backend (Port 5000): Handles Gmail API, OAuth authentication, and AI categorization
Next.js Frontend (Port 3000): Modern React-based UI with server-side rendering

Prerequisites

Python 3.8+
Node.js 16+
Gmail API credentials (credentials.json)

Setup Instructions

1. Flask Backend Setup

# Install Python dependencies
pip install -r requirements.txt

# Ensure you have credentials.json in the root directory
# (Download from Google Cloud Console with Gmail API enabled)

2. Next.js Frontend Setup

# Navigate to the Next.js directory
cd stream-nextjs

# Install Node.js dependencies
npm install

# Return to root directory
cd ..

Starting the Application

Method 1: Manual Start (Recommended for Development)

Terminal 1 - Start Flask Backend:

python app.py

This starts the Flask server on http://localhost:5000

Terminal 2 - Start Next.js Frontend:

cd stream-nextjs
npm run dev

This starts the Next.js server on http://localhost:3000

Method 2: Quick Test

You can test if everything is working by:

Start Flask backend: python app.py
Test health endpoint: Visit http://localhost:5000/api/health
Start Next.js frontend: cd stream-nextjs && npm run dev
Visit http://localhost:3000

Features

Gmail Integration: Secure OAuth2 authentication with Gmail
AI Categorization: Uses Google's Gemini 2.0 Flash for intelligent email categorization
Real-time Processing: Live progress tracking during categorization
Modern UI: Beautiful, responsive interface built with Next.js and Tailwind CSS
Email Viewer: Rich email content display with HTML support, image handling, and link previews
Custom Categories: Support for user-defined categorization queries
Fallback System: Graceful degradation to rule-based categorization if AI fails

Usage

Login: Visit http://localhost:3000 and authenticate with Google
View Inbox: Browse your emails in a modern interface
Categorize: Click the magic wand icon or visit /categorize
Custom Queries: Add specific categorization instructions like "by priority" or "by project"
View Results: Browse categorized emails in an organized grid layout

API Endpoints

Flask Backend (Port 5000)

GET / - Authentication check
GET /login - Start OAuth flow
GET /api/emails - Fetch emails
GET /api/email/<id> - Get specific email
POST /categorize - Start categorization
GET /categorize_status/<session_id> - Check categorization progress
GET /categorize_results/<session_id> - Get categorization results

Next.js Frontend (Port 3000)

All routes proxy to Flask backend for API calls
Modern React pages for UI

Troubleshooting

Flask Won't Start

Check if Python dependencies are installed: pip install -r requirements.txt
Verify credentials.json is in the root directory
Test import: python -c "import app; print('OK')"

Next.js Won't Start

Check if Node.js dependencies are installed: cd stream-nextjs && npm install
Verify Node.js version: node --version (should be 16+)

Categorization Fails

Ensure Flask backend is running on port 5000
Check if Gemini API key is valid in utils.py
System will fallback to rule-based categorization if AI fails

Authentication Issues

Verify credentials.json has correct redirect URIs
Check that Gmail API is enabled in Google Cloud Console
Clear browser cookies and try again

Development Notes

The system is designed to be fault-tolerant with multiple fallback mechanisms
AI categorization uses Google's Gemini 2.0 Flash model
Session management handles concurrent categorization requests
The frontend gracefully handles backend failures with mock data

File Structure

Stream/
├── app.py                 # Flask backend main file
├── utils.py              # Email processing and AI categorization
├── requirements.txt      # Python dependencies
├── credentials.json      # Google OAuth credentials (not in repo)
├── templates/           # Flask HTML templates (legacy)
├── static/             # Static assets and CSS
└── stream-nextjs/      # Next.js frontend
    ├── src/app/        # Next.js app router pages
    ├── src/components/ # React components
    └── src/lib/        # Utility libraries

License

This project is licensed under the MIT License - see the LICENSE file for details.

Analysis

Compare with all teams

View

Metric

Edward Lu
3

Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.

Technology

Found in codeClaimed only

CSSIn code
FlaskIn code
HTMLIn code
JavaScriptIn code
Next.jsIn code
PythonIn code
ReactIn code
Tailwind CSSIn code
TypeScriptIn code

9 of 9 appear in the indexed code.

AI coding agents

No AI coding agent signals were found in this repository.

Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.

Codebase size

Source size

539 KB

Source files

Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.