🧠 Smart Scheduler Assistant

Your Personal AI Executive Assistant for Calendar Management

📖 Introduction

Your inbox is not the problem. Your calendar chaos is.

Every day, important meetings hide inside emails. Dates get missed. Context gets lost. And humans are forced to manually connect dots machines are better at.

So for Day 29 of my 30 Days, 30 AI Agents challenge, I built something deeply personal to my own workflow:

Smart Scheduler Assistant

An AI-powered multi-agent system that reads your Gmail, understands intent, and manages your Google Calendar for you — automatically.

Not rules.
Not filters.
Not “if this then that”.

Actual reasoning.

🌟 What It Does

This isn't just a script; it's an intelligent entity that lives in your terminal and manages your time.

• 📥 Reads your latest emails intelligently: Connects directly to Gmail to fetch unread messages.
• 🧠 Filters noise vs. important conversations: Distinguishes between newsletters, spam, and actual meeting requests.
• 📅 Extracts dates, times, locations, intent: Understands natural language nuances like "next Tuesday afternoon" or "lunch at potential client's office".
• ✅ Creates, updates, or deletes calendar events: Interacts with Google Calendar API to manage your schedule in real-time.
• 💾 Keeps memory of context and past actions: Uses SQLite to remember what it has done and maintain conversation continuity.
• 💬 Lets you talk to it in plain English: Chat with it like you would with a human PA.

🏗️ Under The Hood

The system is built as a coordinated team of autonomous agents, orchestrated by the Agno framework.

The Agent Team

Technical Architecture

Diagram could not be rendered

Powered By

• Agno: The backbone for multi-agent orchestration.
• Nebius LLMs (Qwen 3 32B): The intelligence providing high-speed, accurate reasoning.
• Gmail + Google Calendar APIs: The tools for real-world interaction.
• SQLite: The long-term memory for continuity.

💡 Why I Built This

Because knowledge workers don’t need more tools. They need fewer decisions.

Calendars shouldn’t be managed manually in 2025. If an email implies a meeting, the system should act — responsibly, transparently, and with human oversight.

We don’t need AI that chats more. We need AI that quietly gets work done.

🚀 Getting Started

Follow this comprehensive guide to set up your own Smart Scheduler Assistant.

📋 Prerequisites

Before you begin, ensure you have the following:

1. Python 3.9+ installed on your system.
2. A Google Cloud Platform (GCP) account.
3. Nebius API Key for the LLM.

📥 1. Clone the Repository

bash
git clone https://github.com/ujjwaltiwari01/email_to_calendar_scheduler.git
cd email_to_calendar_scheduler

🔧 2. Environment Setup

It's recommended to use a virtual environment to keep dependencies isolated.

Using uv (Recommended for speed):

bash
# Install uv if you haven't already
pip install uv

# Sync dependencies
uv sync

Using standard pip:

bash
# Create virtual environment
python -m venv .venv

# Activate it
# Windows:
.venv\Scripts\activate
# Mac/Linux:
source .venv/bin/activate

# Install requirements
pip install -r requirements.txt

🔑 3. Configuration

Create a .env file in the root directory of the project. You can copy the example file:

bash
cp .env.example .env

Open .env and add your configuration:

ini
NEBIUS_API_KEY="your_nebius_api_key_here"
TIMEZONE="Asia/Kolkata" # Change to your local timezone (e.g., America/New_York)

☁️ 4. Google Cloud Setup (Critical Step)

This project requires access to your Gmail and Calendar. You need to create an OAuth 2.0 Client ID.

👇 Click here for detailed Google Cloud Setup Instructions

1. Create a Project:

   • Go to the Google Cloud Console.
   • Click the project dropdown top-left > New Project.
   • Name it Smart Scheduler and create it.

2. Enable APIs:

   • Go to APIs & Services > Library.
   • Search for "Gmail API" -> Click Enable.
   • Search for "Google Calendar API" -> Click Enable.

3. Configure OAuth Consent Screen:

   • Go to APIs & Services > OAuth consent screen.
   • Select External > Create.
   • Fill in:
     • App Name: Smart Scheduler
     • User Support Email: Your email
     • Developer Contact It: Your email
   • Click Save and Continue.
   • Scopes: Add https://www.googleapis.com/auth/gmail.readonly and https://www.googleapis.com/auth/calendar.
   • Test Users: Add your own email address (important for testing).

4. Create Credentials:

   • Go to APIs & Services > Credentials.
   • Click Create Credentials > OAuth client ID.
   • Application Type: Desktop app.
   • Name: Scheduler Client.
   • Click Create.

5. Download JSON:

   • Download the JSON file.
   • Rename it to credentials.json.
   • Place it in the root folder of this project.

🔐 5. First-Time Authentication

Run the authentication script to generate your user token. This will open a browser window asking for permission.

bash
python authenticate.py

• Select your Google account.
• Click Advanced > Go to Smart Scheduler (unsafe) (since it's a test app).
• Click Continue to grant permissions.

✅ Once successful, a token.json file will appear in your folder. You are ready to go!

🎮 Usage

Run the main application:

bash
python main.py

Example Commands

Once the assistant is running, try these commands:

"Check my unread emails from the last 24 hours and tell me if there are any meetings."

"I have a meeting with the design team next Friday at 2 PM. Schedule it."

"Find the email from John about the project review and put it on my calendar."

"What's on my schedule for tomorrow?"

📂 Project Directory

A look at how the code is organized:

text
email_to_calendar_scheduler/
├── 📂 tmp/
│   └── data.db            # 🧠 Persistent memory storage (SQLite)
├── 📂 .venv/              # 🐍 Virtual Environment
├── .env                   # 🔑 API Keys and Config
├── authenticate.py        # 🔐 Google OAuth Authentication Script
├── credentials.json       # 🎟️ Google App Credentials (You provide this)
├── main.py                # 🚀 Main Entry Point
├── pyproject.toml         # 📦 Project metadata
├── README.md              # 📄 You are reading this!
├── requirements.txt       # 📋 Python Dependencies
└── token.json             # 🎟️ User Access Token (Generated after auth)

⚠️ Troubleshooting

🤝 Contributing

This project is open source and I welcome contributions!

1. Fork the repository.
2. Create a new Branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

📜 License

Distributed under the MIT License. See LICENSE for more information.

📣 Connect

If you’re a founder, operator, or professional drowning in inbox-to-calendar friction — comment “Scheduler AI” or DM me.

• GitHub: ujjwaltiwari01

#AI #AIAgents #Automation #Productivity #OpenSource #MultiAgentSystems #Founders #BuildInPublic #30Days30AIAgents