> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runtimelabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Calendar Integration

This guide helps developers connect memory trace data with Google Calendar by converting structured JSON to `.ics` files and syncing them using the Google Calendar API.

## Overview

This module enables end-to-end calendar integration:

* Converts memory traces (JSON) to `.ics` files
* Authenticates Google Calendar access
* Syncs events from `.ics` to the user's Google Calendar

## Setup Instructions

### 1. Create Google Cloud Project

Google Cloud Console: [https://console.cloud.google.com/](https://console.cloud.google.com/)

* Select or create a project
* Navigate to **APIs & Services → Library**
* Enable **Google Calendar API**

### 2. Enable Calendar API

Follow the official quickstart guide:\
[https://developers.google.com/calendar/api/quickstart/python](https://developers.google.com/calendar/api/quickstart/python)

### 3. Create OAuth 2.0 Credentials

* Go to **APIs & Services → Credentials**

* Click **+ CREATE CREDENTIALS** → **OAuth client ID**

* If prompted to configure the consent screen:
  * Choose "External", click "Create"
  * Fill in App name, support email, contact info
  * Click "Save and Continue" through remaining steps

* On OAuth creation page:
  * Application type: Desktop App
  * Name: `Calendar Sync Local`
  * Click "Create"

### 4. Download and Store Credentials

* After creation, download the JSON file

* Save as:

  `calendar/credentials.json`

* Add to `.gitignore`:

  `calendar/credentials.json`
  `calendar/token.json`

## Run the Sync Script

From the project root:

```
python modules/calendar_io/sync_google_json.py
```

On first run:

* Auth flow opens in browser
* On success, `token.json` is generated
* Future runs reuse the token unless revoked

## Python Module Overview

### authenticate\_google()

Handles the full OAuth authentication lifecycle:

* Loads existing token from `calendar/token.json` if available
* Falls back to browser-based auth via `InstalledAppFlow`
* On success, stores updated credentials for reuse

### convert\_json\_folder\_to\_ics(input\_dir, output\_dir)

* Parses each `.json` memory file in `input_dir`
* Validates traces via `validate_memory_trace(trace)`
* Generates `.ics` format VEVENT strings
* Outputs `.ics` calendar files to `output_dir`

Example Data I/O:

```
input_dir = Path("data/conversation/raw")  
output_dir = Path("data/conversation/processed")  
convert_json_folder_to_ics(input_dir, output_dir)
```

### `parse_ics_and_sync(ics_path, service)`

* Parses `.ics` file using `ics.Calendar`

* Builds Google Calendar payloads

* Sends each event to Google Calendar using:

  `service.events().insert(calendarId="primary", body=payload).execute()`

* Prints status and error messages

## Security & Best Practices

* Never commit `credentials.json` or `token.json` to version control
* Rotate or revoke OAuth tokens as needed
* Log sync actions for debugging and traceability