Google Calendar AI Agent Server

A production-ready Google Calendar AI Agent built on the Agent + Driver architecture. The Agent reasons in natural language, delegates actions to modular Tools, and uses the Driver to communicate with the Google Calendar API. It is powered by the Groq API with tool calling execution loops and supports both SQLite and PostgreSQL backends.

---

Architecture Overview

calendar-agent/
│
├── agents/
│   ├── calendar_agent.py   # Reasoning loop using Groq Llama-3.3 Function Calling
│   └── prompts.py          # System instructions & few-shot patterns
│
├── drivers/
│   ├── google_calendar_driver.py  # Communicates with official Google APIs & handles ICS
│   └── auth.py             # Initiates OAuth 2.0 flow & stores tokens in DB
│
├── tools/
│   ├── base.py             # Defines BaseTool exposing MCP-compliant metadata
│   ├── create_event.py     # Create events with double booking conflict checks
│   ├── list_events.py      # Lists upcoming events
│   ├── update_event.py     # Modifies event values
│   ├── delete_event.py     # Cancels events
│   ├── search_events.py    # Text search & advanced post-filters
│   ├── free_time.py        # Smart availability slot finder (24-hour day scans)
│   └── recurring.py        # Formats recurrence rule strings
│
├── models/
│   └── schemas.py          # Pydantic validation schemas
│
├── memory/
│   └── chat_memory.py      # SQLite & PostgreSQL database adapter
│
├── tests/                  # Test suite covering driver, agents, and conflicts
│   └── test_agent.py
│
├── config.py               # Application configurations
├── main.py                 # FastAPI API router & interactive dashboard console
└── Dockerfile              # Docker runtime setup

---

Core Technologies

• Python 3.12+
• FastAPI & Uvicorn (REST Endpoints)
• Google Calendar API (via official google-api-python-client)
• Google OAuth 2.0 (with database token storage)
• Pydantic v2 & Pydantic Settings
• Groq API (groq SDK with llama-3.3-70b-versatile)
• icalendar (ICS serialization)
• SQLite (Local development database)
• PostgreSQL (Production database, e.g., Neon Postgres)

---

Google Cloud Console Setup

To connect the application to the Google Calendar API, you must configure an OAuth Client ID:

1. Go to the Google Cloud Console.
2. Create or select a project.
3. Search for and enable the Google Calendar API.
4. Navigate to APIs & Services > OAuth consent screen:
   • Choose External user type.
   • Fill in app name, developer support email, and save.
   • In the Scopes step, add .../auth/calendar and .../auth/calendar.events.
   • In the Audience (or Test users) step, add your Gmail account as an approved tester.
5. Navigate to Credentials > Create Credentials > OAuth client ID:
   • Application Type: Web application.
   • Authorized redirect URIs: Add http://localhost:8080/oauth2callback (and your production URL if hosting).
   • Click Create and copy your Client ID and Client Secret.

---

Installation & Setup

1. Clone the repository:

   git clone <repository_url>
   cd calendar-agent
   

2. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure Environment Variables: Create a .env file in the root directory:

   GROQ_API_KEY="your-groq-api-key"
   GOOGLE_CLIENT_ID="your-google-oauth-client-id"
   GOOGLE_CLIENT_SECRET="your-google-oauth-client-secret"
   GOOGLE_REDIRECT_URI="http://localhost:8080/oauth2callback"
   DB_PATH="calendar_agent.db"
   DATABASE_URL=""
   

   (Note: Leave DATABASE_URL empty to use local SQLite, or enter a Postgres connection string to connect to a PostgreSQL database).

---

Running Locally

To run the FastAPI server and UI dashboard locally:

python -m uvicorn main:app --host 0.0.0.0 --port 8080 --reload

Open http://localhost:8080 in your web browser.

1. Click Connect Google Calendar to authenticate.
2. Sign in with your test Google Account and approve the permissions.
3. You will be redirected back to the dashboard, which will load your upcoming events and let you chat with the AI Agent!

---

Production Deployment on Render

This project is fully ready for deployment on Render (Free Tier):

1. Go to Render and create a new Web Service.
2. Connect your GitHub repository.
3. Select Docker as the Runtime (Render automatically detects your Dockerfile).
4. Set the Instance Type to Free.
5. Add the following Environment Variables:
   • GROQ_API_KEY = gsk_...
   • GOOGLE_CLIENT_ID = ...
   • GOOGLE_CLIENT_SECRET = ...
   • DATABASE_URL = your-neon-postgres-connection-string (highly recommended to persist tokens across container restarts!)
   • GOOGLE_REDIRECT_URI = https://<your-subdomain>.onrender.com/oauth2callback
   • OAUTHLIB_INSECURE_TRANSPORT = 1
6. Click Create Web Service.
7. Add https://<your-subdomain>.onrender.com/oauth2callback to your Authorized redirect URIs in the Google Cloud Console.

---

Example Prompt Interactions

You can ask the agent natural language commands:

• Scheduling:
  • "Schedule a meeting tomorrow at 3 PM for 45 minutes called 'Project Review' and invite [email protected]"
  • "Schedule gym every Monday at 7am"
• Move/Reschedule:
  • "Move my 3 PM dentist appointment tomorrow to Friday at 1 PM"
• List / Summarize:
  • "Summarise my schedule today"
  • "What's on my calendar next week?"
• Availability:
  • "Am I free after 5 PM today?"
  • "Find a one-hour free slot tomorrow morning"
• Add virtual meetings:
  • "Add a Google Meet link to my interview event tomorrow"
• Conflict Resolution:
  • If a slot overlaps, the Agent will ask: "There is an overlap with 'Weekly Sync'. Would you like me to book it anyway or schedule it right after at 4 PM instead?"

---

API Endpoints

Calendar Management

• GET /events: List events with optional time_min and time_max parameters.
• POST /events: Create an event.
• PATCH /events/{id}: Modify an existing event.
• DELETE /events/{id}: Delete an event.

AI & Analytics

• POST /chat: Interact with the agent. Payload: {"message": "string", "session_id": "string"}.
• GET /summary: Returns a short AI-generated schedule summary of the day.
• GET /analytics: Computes statistics like meeting hours today, weekly workload, monthly meeting time, busiest weekdays, and workload overload alerts.

Model Context Protocol (MCP)

• GET /mcp/tools: Exposes all agent tools in MCP format.
• POST /mcp/execute: Executes an MCP tool.

---

Contribution Guide

1. Ensure all code is typed and formatted using Ruff.
2. Run Ruff check:

   ruff check .
   

3. Run tests using pytest:

   pytest tests/