Auto-Scheduling Bot

A FastAPI web application that connects to Gmail, detects meeting-scheduling email threads using an LLM (GPT-5.2 via Agno), proposes available calendar slots, and automatically creates Google Calendar events with Google Meet links once a time is confirmed.

How It Works

1. Connect a Google account via the dashboard (/dashboard).
2. A background job checks the account for new emails every 2 minutes.
3. Email threads are sent to GPT-5.2 (through the Agno framework) for analysis:
   • Scheduling request — the bot checks the user's calendar, finds 3-5 available weekday slots (9 AM – 5 PM in the user's timezone, soonest first), and replies with the options.
   • Slot confirmation — the bot verifies the slot is still free. If available it creates a Google Calendar event with a Google Meet link and replies with the confirmation. If no longer available it re-proposes new slots.
   • Not scheduling-related — the thread is skipped.

Prerequisites

Requirement	Version
Python	3.11+
PostgreSQL	14+
Google Cloud project	Gmail API + Calendar API enabled
OpenAI API key	For GPT-5.2 via Agno

Quick Start

1. Clone & install

git clone <repo-url> auto-scheduling
cd auto-scheduling

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install all dependencies (creates .venv automatically)
uv sync

2. Create the PostgreSQL database

createdb auto_scheduling
# or via psql:
# CREATE DATABASE auto_scheduling;

3. Configure environment

copy .env.example .env     # Windows
# cp .env.example .env     # macOS / Linux

Fill in the values:

Variable	Description
GOOGLE_CLIENT_ID	OAuth 2.0 client ID (Web application type)
GOOGLE_CLIENT_SECRET	OAuth 2.0 client secret
OPENAI_API_KEY	OpenAI API key
DATABASE_URL	PostgreSQL connection string
BASE_URL	Public URL of the app (default http://localhost:8080)

Important: In Google Cloud Console, add http://localhost:8080/auth/google-callback as an Authorized redirect URI for your OAuth client.

4. Run database migrations

Migrations run automatically on app startup, but you can also run them manually:

uv run alembic upgrade head

5. Start the server

uv run uvicorn src.app:create_app --factory --host 0.0.0.0 --port 8080 --reload

Or use the entry point:

uv run python main.py

Open http://localhost:8080/dashboard and click Connect Account.

Database Migrations (Alembic)

# Apply all pending migrations
uv run alembic upgrade head

# Create a new migration after modifying models
uv run alembic revision --autogenerate -m "describe your change"

# Show current migration status
uv run alembic current

# Roll back one migration
uv run alembic downgrade -1

Project Structure

auto-scheduling/
├── main.py                         # Uvicorn entry point
├── alembic/                        # Database migrations
│   ├── env.py                      # Alembic environment config
│   ├── script.py.mako              # Migration file template
│   └── versions/                   # Migration scripts
├── alembic.ini                     # Alembic settings
├── src/
│   ├── app.py                      # FastAPI app factory + lifespan
│   ├── config.py                   # Settings from .env
│   ├── database.py                 # SQLAlchemy engine & session
│   ├── models.py                   # Connection + ProcessedThread models
│   ├── schemas.py                  # Pydantic schemas (LLM output + API)
│   ├── auth.py                     # Google OAuth web-flow routes
│   ├── dashboard.py                # Dashboard page + REST API
│   ├── gmail.py                    # Gmail API helpers (threads, replies)
│   ├── calendar_service.py         # Calendar availability + event creation
│   ├── agent.py                    # Agno / GPT-5.2 email-thread analyser
│   ├── scheduler.py                # APScheduler cron jobs per connection
│   └── templates/
│       └── dashboard.html          # Dashboard UI (Tailwind CSS)
├── pyproject.toml                  # Project metadata & dependencies (uv)
├── uv.lock                         # Locked dependency versions
├── requirements.txt                # Legacy pip requirements (reference only)
├── .env.example
├── .gitignore
└── plan.md

Google OAuth Scopes

Scope	Purpose
openid	OpenID Connect
userinfo.email	Read user email address
userinfo.profile	Read display name
gmail.readonly	Read email threads
gmail.send	Send reply emails
gmail.modify	Mark threads as read
calendar	Full calendar access (availability + event creation)

Tech Stack

• uv — fast Python package manager & runner
• FastAPI + Uvicorn — async web framework & ASGI server
• PostgreSQL + SQLAlchemy + Alembic — persistent storage & migrations
• Agno + OpenAI GPT-5.2 — LLM email analysis
• APScheduler — background cron jobs
• Google APIs — Gmail & Calendar
• Tailwind CSS — dashboard UI