StudyOS: AI-Powered Academic Task Engine

StudyOS turns assignment emails into an organized student workflow. It reads unread Gmail messages with PDF attachments, extracts assignment details with OpenAI, creates structured tasks in Notion, adds deadlines to Google Calendar, and generates a morning briefing for what needs attention next.

This project was built as a student productivity automation tool focused on one simple idea: reduce the manual work between receiving an academic update and actually planning around it.

From inbox to action: Gmail -> AI extraction -> Notion -> Google Calendar -> morning briefing

Quick Look

• Problem: assignment updates are scattered across email threads, PDFs, calendars, and notes
• Solution: one workflow that converts academic emails into structured tasks and reminders
• Outcome: less manual tracking, better visibility, and faster planning for students

What It Does

• Scans unread Gmail messages that match assignment-style queries
• Downloads attached PDF briefs, notices, and assignment sheets
• Extracts task details from email + PDF content using OpenAI
• Creates clean tasks inside a Notion database
• Adds due-date reminders to Google Calendar
• Generates a morning briefing with overdue, today, and upcoming tasks

Demo Highlights

The current project demo shows:

• assignment emails landing in Gmail
• tasks being created in Notion
• deadlines appearing in Google Calendar
• a generated morning briefing summarizing student workload

Demo support files are included in demo_assets/README.md.

Showcase

Gmail Intake

Notion Task Board

Calendar Sync

Morning Briefing

Demo Video

The full walkthrough is available in final_demov3.mp4.

For the public GitHub repo, the cleaner option is to:

• keep the screenshots in the README
• share the full video through your LinkedIn post
• optionally upload the .mp4 later as a GitHub release asset or external video link

Tech Stack

• Python
• Gmail API
• Google Calendar API
• Notion API
• OpenAI API
• PyMuPDF for PDF text extraction

Project Structure

StudyOS/
|-- app/
|   |-- ai_extractor.py
|   |-- ai_service.py
|   |-- auth.py
|   |-- briefing_service.py
|   |-- calendar_service.py
|   |-- gmail_service.py
|   |-- notion_service.py
|   `-- processor.py
|-- demo_assets/
|-- docs/
|-- briefing.py
|-- config.py
|-- main.py
|-- notion_setup.py
|-- pdf_parser.py
|-- requirements.txt
`-- README.md

How It Works

1. main.py fetches unread Gmail messages that match the configured query.
2. app/processor.py reads the message body, downloads PDF attachments, and combines both text sources.
3. app/ai_extractor.py asks OpenAI to return assignment details as structured JSON.
4. app/notion_service.py creates Notion tasks.
5. app/calendar_service.py creates matching Google Calendar events.
6. briefing.py and app/briefing_service.py generate a daily academic summary.

Setup

1. Clone the repo

git clone <your-repo-url>
cd StudyOS

2. Create and activate a virtual environment

python -m venv .venv
.venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Create environment variables

Copy .env.example to .env and fill in your values:

OPENAI_API_KEY=your_openai_api_key
NOTION_API_KEY=your_notion_integration_key
NOTION_DB_ID=your_notion_database_id

5. Add Google OAuth credentials

Place your Google OAuth client file in the project root as:

credentials.json

You will also need to authorize:

• Gmail API access
• Google Calendar API access

6. Prepare Notion

Create a Notion database with these properties:

• Name as title
• Due Date as date
• Priority as select
• Subject as select
• Status as status

Then share that database with your Notion integration.

Usage

Process unread assignment emails

python main.py

Generate a live morning briefing

python briefing.py

Generate a demo morning briefing

python briefing.py --demo

Configuration

The Gmail search filter lives in config.py. The current default is tuned for unread academic emails with PDF attachments.

Notes for Reviewers

• This project uses real external APIs, so it requires API keys and OAuth setup before running.
• The repo intentionally excludes private tokens, credentials, and generated local files.
• Demo input files are included to make the workflow easier to understand and present.

Future Improvements

• stronger date parsing for more natural language cases
• duplicate-task prevention before creating Notion entries
• better subject classification and priority estimation
• a simple web dashboard for non-technical users
• automated testing around extraction and task creation flows

License

This project is released under the MIT License. See LICENSE.