tools.google_oauth_tools module

Google API tools using per-user OAuth tokens.

Provides Google Drive, Gmail, and Calendar operations via Google’s REST APIs. Requires the user to have connected their Google account via the OAuth flow. Distinct from gcp_tools.py which uses service accounts.

async tools.google_oauth_tools.google_drive_list(query='', folder_id='', limit=20, page_token='', ctx=None)[source]

List files in the user’s Google Drive, with optional search and folder filtering.

Backs the google_drive_list LLM tool. Builds a Drive files.list query that always excludes trashed files, optionally restricts to a folder or a raw Drive query, then returns a compact JSON summary of the matching files.

Resolves the user’s token via _get_token() (returning the connect prompt string if the account is not linked), then calls _google_request() against the Drive files endpoint, requesting only id/name/mimeType/size/modifiedTime/webViewLink/parents fields. Any API error dict is serialized straight through. This is a registered tool handler (see the module-level TOOLS list) and is invoked by name through the tools registry in tools/__init__.py rather than called directly anywhere in the codebase.

Parameters:

  • query (str) – Optional Drive search expression (e.g. "name contains 'report'"); empty for no text filter.

  • folder_id (str) – Optional folder ID to scope results to that folder’s direct children.

  • limit (int) – Maximum number of files to return; capped at 100.

  • page_token (str) – Optional pagination token from a previous call.

  • ctx (ToolContext | None) – Tool context supplying Redis and the user’s identity for token resolution.

Returns:

JSON string {"count", "files": [...]} (each file carrying id/name/mimeType/size/modifiedTime/url), optionally with next_page_token; or a JSON error dict; or the OAuth connect prompt text when the account is not connected.

Return type:

str

async tools.google_oauth_tools.google_drive_read(file_id, ctx=None)[source]

Read a Google Drive file’s metadata and content as text.

Backs the google_drive_read LLM tool. Fetches the file’s metadata, then retrieves its content — exporting native Google Docs/Sheets/Slides to text or CSV, and downloading other files via alt=media — and returns both, with the content truncated to 16000 characters.

Resolves the token through _get_token() and makes two or three _google_request() calls: one for metadata, then either a Drive export (for Google-native MIME types mapped to text/plain or text/csv) or a raw media download. Errors from either request are returned as JSON unchanged. This is a registered tool handler in the module TOOLS list, dispatched by name through the tools registry in tools/__init__.py; no direct internal callers exist.

Parameters:

  • file_id (str) – The Google Drive file ID to read.

  • ctx (ToolContext | None) – Tool context supplying Redis and the user’s identity for token resolution.

Returns:

JSON string {"metadata": {...}, "content": "..."} with the content truncated to 16000 chars; or a JSON error dict; or the OAuth connect prompt text when the account is not connected.

Return type:

str

async tools.google_oauth_tools.google_drive_upload(name, content, mime_type='text/plain', folder_id='', ctx=None)[source]

Create a new file in the user’s Google Drive from text content.

Backs the google_drive_upload LLM tool. Performs a Drive multipart upload, sending file metadata (name, MIME type, optional parent folder) and the body in a single multipart/related request.

Resolves the token via _get_token(), hand-assembles the multipart body with a fixed boundary, and calls _google_request() against the Drive multipart upload endpoint with a multipart Content-Type header. An API error dict is serialized straight through. This is a registered tool handler in the module TOOLS list, invoked by name through the tools registry in tools/__init__.py; it has no direct internal callers.

Parameters:

  • name (str) – The name to give the new Drive file.

  • content (str) – The text content of the file body.

  • mime_type (str) – MIME type for the file; defaults to "text/plain".

  • folder_id (str) – Optional parent folder ID; when set the file is created inside that folder.

  • ctx (ToolContext | None) – Tool context supplying Redis and the user’s identity for token resolution.

Returns:

JSON string with the new file’s id/name/mimeType and "status": "uploaded"; or a JSON error dict; or the OAuth connect prompt text when the account is not connected.

Return type:

str

async tools.google_oauth_tools.google_gmail_list(query='', label='INBOX', limit=15, page_token='', ctx=None)[source]

List messages from the user’s Gmail with header summaries.

Backs the google_gmail_list LLM tool. Queries the Gmail messages.list endpoint with an optional search query and label filter, then fetches metadata headers (From/To/Subject/Date) for each returned message so the result is human-readable.

Resolves the token via _get_token(), then makes one _google_request() to list message stubs followed by one additional _google_request() per message (up to limit) to fetch metadata headers and the snippet. Any list-level error dict is serialized straight through; per-message errors are skipped. This is a registered tool handler in the module TOOLS list, dispatched by name through the tools registry in tools/__init__.py; no direct internal callers exist.

Parameters:

  • query (str) – Optional Gmail search query (same syntax as the Gmail search bar).

  • label (str) – Label ID to filter by; defaults to "INBOX".

  • limit (int) – Maximum number of messages to return; the list call caps maxResults at 100 and the per-message fetch loop honors limit.

  • page_token (str) – Optional pagination token from a previous call.

  • ctx (ToolContext | None) – Tool context supplying Redis and the user’s identity for token resolution.

Returns:

JSON string {"count", "messages": [...]} (each message carrying id/threadId/from/to/subject/date/snippet/labels), optionally with next_page_token; or a JSON error dict; or the OAuth connect prompt text when the account is not connected.

Return type:

str

async tools.google_oauth_tools.google_gmail_read(message_id, ctx=None)[source]

Read a single Gmail message’s headers and decoded plain-text body.

Backs the google_gmail_read LLM tool. Fetches the full message, flattens its headers, and walks the MIME payload to extract a readable plain-text body, returning everything as JSON with the body truncated to 16000 characters.

Resolves the token via _get_token() and makes a single _google_request() for the full message; the nested _extract_body() helper recursively base64url-decodes the message parts. An API error dict is serialized straight through. This is a registered tool handler in the module TOOLS list, dispatched by name through the tools registry in tools/__init__.py; no direct internal callers exist.

Parameters:

  • message_id (str) – The Gmail message ID to read.

  • ctx (ToolContext | None) – Tool context supplying Redis and the user’s identity for token resolution.

Returns:

JSON string with id/threadId/from/to/subject/date, the decoded body (truncated to 16000 chars) and labels; or a JSON error dict; or the OAuth connect prompt text when the account is not connected.

Return type:

str

async tools.google_oauth_tools.google_gmail_send(to, subject, body, ctx=None)[source]

Send a plain-text email from the user’s Gmail account.

Backs the google_gmail_send LLM tool. Constructs a MIME text message with the given recipient, subject and body, base64url-encodes it, and posts it to Gmail’s messages.send endpoint.

Resolves the token via _get_token(), builds a email.mime.text.MIMEText message, then calls _google_request() with the encoded raw payload. An API error dict is serialized straight through. This is a registered tool handler in the module TOOLS list, dispatched by name through the tools registry in tools/__init__.py; no direct internal callers exist.

Parameters:

  • to (str) – Recipient email address.

  • subject (str) – Email subject line.

  • body (str) – Plain-text email body.

  • ctx (ToolContext | None) – Tool context supplying Redis and the user’s identity for token resolution.

Returns:

JSON string {"status": "sent", "id", "threadId"}; or a JSON error dict; or the OAuth connect prompt text when the account is not connected.

Return type:

str

async tools.google_oauth_tools.google_calendar_list_events(time_min='', time_max='', calendar_id='primary', limit=20, query='', ctx=None)[source]

List events from one of the user’s Google Calendars.

Backs the google_calendar_list_events LLM tool. Queries the Calendar events.list endpoint with single-event expansion and start-time ordering, optionally bounded by a time range and a free-text query, then returns a compact JSON summary of the matching events.

Resolves the token via _get_token() and makes a single _google_request() against the calendar’s events endpoint. Event descriptions are truncated to 500 chars and attendee lists capped at 10 emails. An API error dict is serialized straight through. This is a registered tool handler in the module TOOLS list, dispatched by name through the tools registry in tools/__init__.py; no direct internal callers exist.

Parameters:

  • time_min (str) – Optional ISO 8601 lower bound on event start times.

  • time_max (str) – Optional ISO 8601 upper bound on event start times.

  • calendar_id (str) – Calendar to query; defaults to "primary".

  • limit (int) – Maximum number of events to return; capped at 250.

  • query (str) – Optional free-text search over event fields.

  • ctx (ToolContext | None) – Tool context supplying Redis and the user’s identity for token resolution.

Returns:

JSON string {"count", "events": [...]} (each event carrying id/summary/description/start/end/location/status/url/attendees); or a JSON error dict; or the OAuth connect prompt text when the account is not connected.

Return type:

str

async tools.google_oauth_tools.google_calendar_create_event(summary, start_time, end_time, description='', location='', calendar_id='primary', attendees=None, ctx=None)[source]

Create a new event on one of the user’s Google Calendars.

Backs the google_calendar_create_event LLM tool. Assembles an event body from the summary, start/end times and optional description/location/attendees, then posts it to the Calendar events.insert endpoint.

Resolves the token via _get_token() and makes a single _google_request() POST to the calendar’s events endpoint. Attendee emails are wrapped into {"email": ...} objects. An API error dict is serialized straight through. This is a registered tool handler in the module TOOLS list, dispatched by name through the tools registry in tools/__init__.py; no direct internal callers exist.

Parameters:

  • summary (str) – Event title.

  • start_time (str) – ISO 8601 start time (with timezone offset).

  • end_time (str) – ISO 8601 end time (with timezone offset).

  • description (str) – Optional event description.

  • location (str) – Optional event location.

  • calendar_id (str) – Calendar to create the event on; defaults to "primary".

  • attendees (list[str] | None) – Optional list of attendee email addresses to invite.

  • ctx (ToolContext | None) – Tool context supplying Redis and the user’s identity for token resolution.

Returns:

JSON string {"status": "created", "id", "summary", "url", "start", "end"}; or a JSON error dict; or the OAuth connect prompt text when the account is not connected.

Return type:

str