# Google Calendar AI Agent

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](https://console.cloud.google.com/).
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**:
   ```bash
   git clone <repository_url>
   cd calendar-agent
   ```

2. **Create and activate a virtual environment**:
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   ```

3. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

4. **Configure Environment Variables**:
   Create a `.env` file in the root directory:
   ```env
   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:

```bash
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](https://render.com/) 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 test@gmail.com"*
  - *"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:
   ```bash
   ruff check .
   ```
3. Run tests using `pytest`:
   ```bash
   pytest tests/
   ```