clara.connections.google package

Submodules

clara.connections.google.calendar module

Google Calendar Connection Module for Clara Core.

This module provides the CalendarConnection class and helper functions to interact with the Google Calendar API for event retrieval, scheduling, updates, and deletion on behalf of the user.

clara.connections.google.calendar.list_events(calendar_id='primary', time_min=None, time_max=None, max_results=10, service=None)

Lists upcoming events from the specified Google Calendar.

Parameters:

• calendar_id (str) – Unique calendar identifier (default is ‘primary’).

• time_min (str | None) – Lower bound for an event’s end time (ISO-8601 string). Defaults to current UTC time if omitted.

• time_max (str | None) – Upper bound for an event’s start time (ISO-8601 string).

• max_results (int) – Maximum number of events to return. Defaults to 10.

• service (Any | None) – Optional pre-authenticated Google Calendar API client.

Returns:

List of calendar event dictionaries containing summary, start/end times, location, and event ID.

Return type:

List[Dict[str, Any]]

Example

>>> events = list_events(max_results=5)
>>> for ev in events:
...     print(ev['summary'], ev['start'])

clara.connections.google.calendar.create_event(summary, start_time, end_time, calendar_id='primary', description='', location='', attendees=None, service=None)

Creates a new calendar event on Google Calendar.

Parameters:

• summary (str) – Title/name of the calendar event.

• start_time (str) – Start date-time formatted in ISO 8601 string.

• end_time (str) – End date-time formatted in ISO 8601 string.

• calendar_id (str) – Target calendar ID. Defaults to ‘primary’.

• description (str) – Detailed event description or meeting agenda.

• location (str) – Event location, conference room, or video link.

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

• service (Any | None) – Optional pre-authenticated Google Calendar API client.

Returns:

Details of the created event including ID and link.

Return type:

Dict[str, Any]

Example

>>> event = create_event(
...     summary="Team Sync",
...     start_time="2026-09-25T14:00:00Z",
...     end_time="2026-09-25T15:00:00Z",
...     attendees=["colleague@example.com"]
... )

clara.connections.google.calendar.delete_event(event_id, calendar_id='primary', service=None)

Deletes an existing event from Google Calendar.

Parameters:

• event_id (str) – Unique event identifier to remove.

• calendar_id (str) – Calendar identifier. Defaults to ‘primary’.

• service (Any | None) – Optional pre-authenticated Google Calendar API client.

Returns:

Status dictionary indicating successful deletion.

Return type:

Dict[str, Any]

class clara.connections.google.calendar.CalendarConnection(config=None)

Bases: BaseConnection

Google Calendar connection adapter for Clara.

Enables agents and skills to query calendar schedules, create bookings, reschedule events, and coordinate meetings.

Parameters:

config (Dict[str, Any] | None)

name

Connection name identifier (‘calendar’).

Type:

str

connect(credentials=None, access_token=None, **kwargs)

Initializes and authenticates the Google Calendar API client.

Parameters:

• credentials (Credentials | None) – Optional OAuth2 Credentials instance.

• access_token (str | None) – Optional OAuth2 access token.

• **kwargs (Any) – Extra parameters passed to the internal service builder.

Returns:

The active Google Calendar Resource instance.

Return type:

Resource

disconnect()

Closes the connection session and cleans up resources.

Return type:

None

list_events(*args, **kwargs)

Queries upcoming events using the active connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

List[Dict[str, Any]]

create_event(*args, **kwargs)

Creates a calendar event using the active connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Dict[str, Any]

delete_event(*args, **kwargs)

Deletes a calendar event using the active connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Dict[str, Any]

clara.connections.google.drive module

Google Drive Connection Module for Clara Core.

This module provides the DriveConnection class and helper functions to interact with the Google Drive API for querying files, reading metadata, managing folder hierarchies, and searching user documents.

clara.connections.google.drive.list_files(query=None, page_size=10, order_by='modifiedTime desc', service=None)

Lists or queries files in Google Drive.

Parameters:

• query (str | None) – Optional Google Drive search query string (e.g. “name contains ‘Report’”).

• page_size (int) – Number of files to return (maximum 100). Defaults to 10.

• order_by (str) – Sorting field and direction. Defaults to ‘modifiedTime desc’.

• service (Any | None) – Optional pre-authenticated Google Drive API client resource.

Returns:

List of file records containing id, name, mimeType, modifiedTime, and webViewLink.

Return type:

List[Dict[str, Any]]

Example

>>> files = list_files(query="mimeType = 'application/pdf'", page_size=5)
>>> for f in files:
...     print(f['name'], f['id'])

clara.connections.google.drive.get_file_metadata(file_id, service=None)

Retrieves metadata and properties for a specific Google Drive file.

Parameters:

• file_id (str) – Unique Google Drive file identifier.

• service (Any | None) – Optional pre-authenticated Google Drive API client resource.

Returns:

Dictionary containing detailed file metadata.

Return type:

Dict[str, Any]

clara.connections.google.drive.delete_file(file_id, service=None)

Permanently deletes a file from Google Drive.

Parameters:

• file_id (str) – Unique Google Drive file identifier.

• service (Any | None) – Optional pre-authenticated Google Drive API client resource.

Returns:

Deletion confirmation dictionary.

Return type:

Dict[str, Any]

class clara.connections.google.drive.DriveConnection(config=None)

Bases: BaseConnection

Google Drive connection adapter for Clara.

Enables agents and skills to search, inspect, upload, and organize documents stored in the user’s Google Drive.

Parameters:

config (Dict[str, Any] | None)

name

Connection name identifier (‘drive’).

Type:

str

connect(credentials=None, access_token=None, **kwargs)

Initializes and authenticates the Google Drive API client.

Parameters:

• credentials (Credentials | None) – Optional OAuth2 Credentials instance.

• access_token (str | None) – Optional OAuth2 access token string.

• **kwargs (Any) – Extra parameters passed to the internal service builder.

Returns:

The active Google Drive Resource client instance.

Return type:

Resource

disconnect()

Closes the connection session and cleans up resources.

Return type:

None

list_files(*args, **kwargs)

Queries files using the active connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

List[Dict[str, Any]]

get_file_metadata(*args, **kwargs)

Fetches file metadata using the active connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Dict[str, Any]

delete_file(*args, **kwargs)

Deletes a file using the active connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Dict[str, Any]

clara.connections.google.gmail module

Gmail Connection Module for Clara Core.

This module handles all Gmail CRUD operations performed by Clara AI assistant on behalf of the user. User consent and authorization tokens are received via the Clara mobile app (Android/iOS) or web/desktop OAuth flows.

clara.connections.google.gmail.send_email(to, cc=None, bcc=None, subject='', body='', attachments=None, is_html=False, service=None)

Send an email message via Gmail.

Parameters:

• to (str | List[str]) – Recipient email address or list of email addresses.

• cc (str | List[str] | None) – Optional CC email address or list.

• bcc (str | List[str] | None) – Optional BCC email address or list.

• subject (str) – Email subject line.

• body (str) – Email body text (plain text or HTML).

• attachments (str | List[str | Dict[str, Any]] | None) – Optional file path or list of file paths/attachment dicts.

• is_html (bool) – Set to True if body is HTML formatted.

• service (Any | None) – Optional pre-authenticated Gmail service instance.

Returns:

Dict containing send status, message ID, thread ID, and recipient.

Return type:

Dict[str, Any]

clara.connections.google.gmail.create_draft(to=None, cc=None, bcc=None, subject='', body='', attachments=None, is_html=False, service=None)

Create a new email draft in Gmail.

Parameters:

• to (str | List[str] | None) – Optional recipient email address or list.

• cc (str | List[str] | None) – Optional CC email address or list.

• bcc (str | List[str] | None) – Optional BCC email address or list.

• subject (str) – Email subject line.

• body (str) – Email body text.

• attachments (str | List[str | Dict[str, Any]] | None) – Optional attachment paths or dictionaries.

• is_html (bool) – True if body is HTML formatted.

• service (Any | None) – Optional pre-authenticated Gmail service instance.

Returns:

Dict containing draft creation status, draft ID, and message ID.

Return type:

Dict[str, Any]

clara.connections.google.gmail.update_draft(draft_id, new_content, new_recipients=None, subject=None, cc=None, bcc=None, attachments=None, is_html=False, service=None)

Update an existing email draft in Gmail.

Parameters:

• draft_id (str) – The ID of the draft to update.

• new_content (str) – The new body content for the draft.

• new_recipients (str | List[str] | None) – Optional updated recipient(s).

• subject (str | None) – Optional updated subject line.

• cc (str | List[str] | None) – Optional updated CC recipient(s).

• bcc (str | List[str] | None) – Optional updated BCC recipient(s).

• attachments (str | List[Any] | None) – Optional updated attachment(s).

• is_html (bool) – True if new_content is HTML formatted.

• service (Any | None) – Optional pre-authenticated Gmail service instance.

Returns:

Dict containing draft update status and draft ID.

Return type:

Dict[str, Any]

clara.connections.google.gmail.search_emails(query='', folder=None, date_range=None, limit=10, service=None)

Search for emails in Gmail matching query parameters.

Parameters:

• query (str) – Search keywords or query string.

• folder (str | None) – Optional folder/label (e.g., ‘inbox’, ‘sent’, ‘unread’).

• date_range (datetime | str | tuple | None) – Optional date filter.

• limit (int) – Maximum number of results to return (default: 10).

• service (Any | None) – Optional pre-authenticated Gmail service instance.

Returns:

List of matching email summaries.

Return type:

List[Dict[str, Any]]

clara.connections.google.gmail.get_email_content(message_id, format='full', service=None)

Retrieve full content and metadata for a specific email message.

Parameters:

• message_id (str) – The unique Gmail message ID.

• format (str) – Format of returned message (‘full’, ‘raw’, ‘metadata’).

• service (Any | None) – Optional pre-authenticated Gmail service instance.

Returns:

Dict containing parsed subject, sender, recipients, date, and body.

Return type:

Dict[str, Any]

clara.connections.google.gmail.summarize_thread(message_ids, service=None)

Retrieve and format all messages in a thread for summarization.

Parameters:

• message_ids (str | List[str]) – A thread ID string or a list of message ID strings.

• service (Any | None) – Optional pre-authenticated Gmail service instance.

Returns:

Dict containing thread subject, participant list, and history.

Return type:

Dict[str, Any]

clara.connections.google.gmail.move_email(message_id, target_folder, service=None)

Move an email to a specific folder or label.

Parameters:

• message_id (str) – The unique Gmail message ID.

• target_folder (str) – The target folder or label name.

• service (Any | None) – Optional pre-authenticated Gmail service instance.

Returns:

Dict containing operation status, message ID, and target folder.

Return type:

Dict[str, Any]

clara.connections.google.gmail.delete_email(message_id, parmanent=False, permanent=None, service=None)

Delete an email from Gmail. Supports moving to Trash and permanent deletion.

Parameters:

• message_id (str) – The unique Gmail message ID.

• parmanent (bool) – Backward compatibility flag for permanent deletion.

• permanent (bool | None) – True for permanent deletion, False to move to Trash.

• service (Any | None) – Optional pre-authenticated Gmail service instance.

Returns:

Dict containing operation status and message ID.

Return type:

Dict[str, Any]

class clara.connections.google.gmail.GmailConnection(config=None)

Bases: BaseConnection

Clara connection adapter implementation for Google Gmail service.

Enables agents and workflows to search, read, draft, send, archive, and delete emails via the Gmail v1 REST API.

Parameters:

config (Dict[str, Any] | None)

name

Unique connection identifier (‘gmail’).

Type:

str

connect(credentials=None, access_token=None, **kwargs)

Authenticates and initializes the Gmail API client service.

Parameters:

• credentials (Credentials | None) – Optional Google OAuth2 Credentials object.

• access_token (str | None) – Optional OAuth2 access token.

• **kwargs (Any) – Extra parameters passed to the service builder.

Returns:

Authenticated Gmail API client resource.

Return type:

Resource

disconnect()

Disconnects and releases the active Gmail service client.

Return type:

None

send_email(*args, **kwargs)

Sends an email using the active Gmail service connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Dict[str, Any]

create_draft(*args, **kwargs)

Creates a draft using the active Gmail service connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Dict[str, Any]

update_draft(*args, **kwargs)

Updates a draft using the active Gmail service connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Dict[str, Any]

search_emails(*args, **kwargs)

Searches messages using the active Gmail service connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

List[Dict[str, Any]]

get_email_content(*args, **kwargs)

Retrieves email content using the active Gmail service connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Dict[str, Any]

summarize_thread(*args, **kwargs)

Summarizes a message thread using the active Gmail service connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Dict[str, Any]

move_email(*args, **kwargs)

Moves an email using the active Gmail service connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Dict[str, Any]

delete_email(*args, **kwargs)

Trashes or permanently deletes an email using the active connection.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Dict[str, Any]

Module contents

Google Workspace connection adapters for Clara Core.

This package provides service adapters for Google Workspace APIs including: - GmailConnection - CalendarConnection - DriveConnection