Feature/ENG-31: Google sheets connector by coutocass · Pull Request #1158 · airweave-ai/airweave

coutocass · 2025-12-09T01:13:06Z

Summary by cubic

Adds a Google Sheets connector (ENG-31) with OAuth and full/incremental sync via Drive Changes, plus docs and UI icons. Includes E2E tests and local worker QoL fixes for safer shutdowns.

New Features
- Google Sheets source: lists spreadsheets, fetches sheet metadata/values, and emits spreadsheet/sheet entities with headers and formatted cell data.
- Incremental sync via Drive Changes using start_page_token; full sync persists the next token.
- Config and schemas: GoogleSheetsConfig (include_trashed, include_shared, max_rows_per_sheet), cursor, and entities.
- OAuth for dev/prd/self-hosted; Composio maps to Google Docs scopes; connector uses read-only scopes; BYOC and Pipedream supported.
- Monke E2E: bongo to create/update/delete spreadsheets, LLM-generated rows with verification tokens, force_full_sync deletion checks, and orphaned test cleanup.
- Docs and UI: added connector docs page and nav entry, app icons, and README icon.
Bug Fixes
- Worker hot-reload: optional debugpy (AIRWEAVE_WORKER_DEBUG) and optional wait-for-client (AIRWEAVE_DEBUGPY_WAIT_FOR_CLIENT); fixed watch paths.
- Graceful shutdown even if the metrics server isn’t fully initialized.
- Monke: troubleshooting guide for entity ID collisions/deletion order and minor logging improvements.

^{Written for commit 19f76e2. Summary will update on new commits.}

- Make debugpy optional in worker hot-reload (set AIRWEAVE_WORKER_DEBUG=true to enable) - Make --wait-for-client optional (set AIRWEAVE_DEBUGPY_WAIT_FOR_CLIENT=true to enable) - Fix graceful shutdown when metrics server not fully initialized - Fix watch paths for hot-reload script - Add Monke troubleshooting guide for entity ID collisions and deletion order - Minor monke logging improvements

cubic-dev-ai

1 issue found across 19 files

Prompt for AI agents (all 1 issues)


Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="monke/bongos/google_sheets.py">

<violation number="1" location="monke/bongos/google_sheets.py:202">
P1: Passing `self._test_spreadsheets` directly causes list modification during iteration. Inside `delete_specific_entities`, items are removed from `_test_spreadsheets` while iterating over the same list, which can cause elements to be skipped. Pass a copy instead, similar to how `cleanup` does it.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

monke/bongos/google_sheets.py

marc-rutzou · 2025-12-09T15:35:29Z

backend/airweave/platform/auth_providers/composio.py

        "google_drive": "googledrive",
        "google_calendar": "googlecalendar",
        "google_docs": "googledocs",
+        "google_sheets": "googledocs",  # Reuse Google Docs OAuth (compatible scopes)


does this require users to create a "googledocs" Composio connection and use that to create a "google_sheets" Airweave conncection?

I'm using googledocs just temporarily, because I don't have access to composio.

marc-rutzou · 2025-12-09T15:37:34Z

backend/airweave/platform/configs/config.py

+class GoogleSheetsConfig(SourceConfig):
+    """Google Sheets configuration schema."""
+
+    include_trashed: bool = Field(


not sure if we should include this option. Normally we do not synced deleted data.

This follows the existing pattern for Google connectors - GoogleDocsConfig and GoogleSlidesConfig already have this same option on main. It defaults to False (trashed items excluded), so the default behavior matches our principle of not syncing deleted data. The opt-in exists for edge cases like compliance audits or data recovery scenarios.

marc-rutzou · 2025-12-09T15:39:38Z

we do have a xlsx converter. Did you consider processing the data as a file? or do you think this is a better way?

coutocass · 2025-12-09T21:43:57Z

we do have a xlsx converter. Did you consider processing the data as a file? or do you think this is a better way?

@marc-rutzou Good question! I considered the XLSX export approach but went with the Sheets API directly for a few reasons:

Incremental sync efficiency - The Drive Changes API tells us which sheets changed. With XLSX export, we'd need to re-download the entire file on any change.
No export overhead - Large spreadsheets can be slow/fail to export. The Sheets API lets us paginate and limit rows (max_rows_per_sheet) without downloading everything.
Live data - Sheets API returns formula results as users see them. XLSX export may not preserve all Google Sheets features correctly.
Metadata - We get owners, sharing status, and web links directly from Drive API.

coutocass · 2025-12-09T21:52:26Z

@marc-rutzou btw the test that is failing is unrelated to the changes here. It's likely a bug :/

marc-rutzou

once the composio name mapping is fixed, its good to go!

coutocass · 2025-12-11T18:33:17Z

@marc-rutzou could you please re-review? Composio is set

cubic-dev-ai

2 issues found across 11 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="backend/airweave/platform/sources/google_sheets.py">

<violation number="1" location="backend/airweave/platform/sources/google_sheets.py:279">
P1: Dead code: `_latest_new_start_page_token` is never assigned in this class</violation>
</file>

<file name="backend/airweave/platform/auth/yaml/dev.integrations.yaml">

<violation number="1" location="backend/airweave/platform/auth/yaml/dev.integrations.yaml:161">
P2: Using placeholder OAuth credentials will break Google Sheets authentication in the dev integration config.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

backend/airweave/platform/sources/google_sheets.py

backend/airweave/platform/auth/yaml/dev.integrations.yaml

felixschmetz · 2026-03-05T17:40:09Z

backend/airweave/platform/entities/__init__.py

+from .google_sheets import (
+    GoogleSheetsSheetEntity,
+    GoogleSheetsSpreadsheetEntity,
+)


We don't have a Deletion Entity, is that expected? _process_changes filters for removed == False but never yields a deletion entity for removed == True. So this will work for the monke since we set force_full_sync to true, but regular users will accumulate stale data over time.

felixschmetz · 2026-03-05T17:42:03Z

backend/airweave/platform/sources/google_sheets.py

+            spreadsheet_title = file_data.get("name", "Untitled Spreadsheet")
+
+            # Parse timestamps
+            created_time = self._parse_datetime(file_data.get("createdTime")) or datetime.utcnow()


We're in the process of bumping to Python 3.14. AFAIK datetime.utcnow() is deprecated for 3.12 and higher. Can you use datetime.now(timezone.utc) instead?

felixschmetz · 2026-03-05T18:04:47Z

Thanks!! I believe we should park this connector for now. We are unable to parse sheets in a meaningful way yet that

a) doesn't crash our infra with mem-usage
b) provides meaningful results during retrieval.

Let's revisit once our platform is ready.

coutocass added 2 commits December 8, 2025 17:56

feat: new connector for google sheets

dec9f8d

coutocass temporarily deployed to dev December 9, 2025 01:13 — with GitHub Actions Inactive

coutocass self-assigned this Dec 9, 2025

coutocass temporarily deployed to dev December 9, 2025 01:15 — with GitHub Actions Inactive

cubic-dev-ai bot reviewed Dec 9, 2025

View reviewed changes

monke/bongos/google_sheets.py Outdated Show resolved Hide resolved

fix: addressing cubic comment

4a9dea2

coutocass temporarily deployed to dev December 9, 2025 14:53 — with GitHub Actions Inactive

coutocass temporarily deployed to dev December 9, 2025 14:56 — with GitHub Actions Inactive

coutocass had a problem deploying to dev December 9, 2025 14:56 — with GitHub Actions Failure

marc-rutzou reviewed Dec 9, 2025

View reviewed changes

marc-rutzou requested changes Dec 10, 2025

View reviewed changes

coutocass requested a review from marc-rutzou December 11, 2025 18:32

orhanrauf force-pushed the main branch from 3d86f30 to d2eef62 Compare January 14, 2026 12:18

viralpraxis temporarily deployed to dev March 5, 2026 13:21 — with GitHub Actions Inactive

viralpraxis temporarily deployed to dev March 5, 2026 13:24 — with GitHub Actions Inactive

viralpraxis had a problem deploying to dev March 5, 2026 14:20 — with GitHub Actions Failure

viralpraxis temporarily deployed to dev March 5, 2026 14:21 — with GitHub Actions Inactive

viralpraxis had a problem deploying to dev March 5, 2026 14:21 — with GitHub Actions Failure

viralpraxis temporarily deployed to dev March 5, 2026 14:21 — with GitHub Actions Inactive

viralpraxis temporarily deployed to dev March 5, 2026 14:22 — with GitHub Actions Inactive

cubic-dev-ai bot reviewed Mar 5, 2026

View reviewed changes

backend/airweave/platform/sources/google_sheets.py Outdated Show resolved Hide resolved

backend/airweave/platform/auth/yaml/dev.integrations.yaml Show resolved Hide resolved

viralpraxis requested a review from orhanrauf March 5, 2026 14:40

Actualize implementation

19f76e2

viralpraxis force-pushed the feture/eng-31-google-sheets branch from 4640847 to 19f76e2 Compare March 5, 2026 14:43

viralpraxis had a problem deploying to dev March 5, 2026 14:43 — with GitHub Actions Failure

viralpraxis temporarily deployed to dev March 5, 2026 14:44 — with GitHub Actions Inactive

viralpraxis had a problem deploying to dev March 5, 2026 14:44 — with GitHub Actions Failure

viralpraxis temporarily deployed to dev March 5, 2026 14:44 — with GitHub Actions Inactive

viralpraxis had a problem deploying to dev March 5, 2026 14:45 — with GitHub Actions Failure

viralpraxis temporarily deployed to dev March 5, 2026 14:45 — with GitHub Actions Inactive

felixschmetz reviewed Mar 5, 2026

View reviewed changes

Conversation

coutocass commented Dec 9, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by cubic

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marc-rutzou Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

coutocass Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marc-rutzou Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

coutocass Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

marc-rutzou commented Dec 9, 2025

Uh oh!

coutocass commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coutocass commented Dec 9, 2025

Uh oh!

marc-rutzou left a comment

Choose a reason for hiding this comment

Uh oh!

coutocass commented Dec 11, 2025

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

felixschmetz Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

felixschmetz Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

felixschmetz commented Mar 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

coutocass commented Dec 9, 2025 •

edited by cubic-dev-ai bot

Loading

coutocass Dec 9, 2025 •

edited

Loading

coutocass commented Dec 9, 2025 •

edited

Loading