clara.connections package

Subpackages

• clara.connections.google package
  • Submodules
  • clara.connections.google.calendar module
    • list_events()
    • create_event()
    • delete_event()
    • CalendarConnection
      • CalendarConnection.name
      • CalendarConnection.connect()
      • CalendarConnection.disconnect()
      • CalendarConnection.list_events()
      • CalendarConnection.create_event()
      • CalendarConnection.delete_event()
  • clara.connections.google.drive module
    • list_files()
    • get_file_metadata()
    • delete_file()
    • DriveConnection
      • DriveConnection.name
      • DriveConnection.connect()
      • DriveConnection.disconnect()
      • DriveConnection.list_files()
      • DriveConnection.get_file_metadata()
      • DriveConnection.delete_file()
  • clara.connections.google.gmail module
    • send_email()
    • create_draft()
    • update_draft()
    • search_emails()
    • get_email_content()
    • summarize_thread()
    • move_email()
    • delete_email()
    • GmailConnection
      • GmailConnection.name
      • GmailConnection.connect()
      • GmailConnection.disconnect()
      • GmailConnection.send_email()
      • GmailConnection.create_draft()
      • GmailConnection.update_draft()
      • GmailConnection.search_emails()
      • GmailConnection.get_email_content()
      • GmailConnection.summarize_thread()
      • GmailConnection.move_email()
      • GmailConnection.delete_email()
  • Module contents

Submodules

clara.connections.base module

Base connection interfaces and abstractions for Clara service integrations.

This module defines BaseConnection, the foundational abstract class that all third-party service adapters (such as Google Workspace, GitHub, Slack, Notion, etc.) must inherit from and implement.

class clara.connections.base.BaseConnection(name, config=None)

Bases: ABC

Abstract base class for all third-party service connections in Clara.

Subclasses must implement authentication lifecycle methods, session management, and service client discovery for external APIs.

Parameters:

• name (str)

• config (Dict[str, Any] | None)

name

Unique identifier for the service connection (e.g., ‘gmail’, ‘calendar’).

Type:

str

config

Configuration dictionary containing service parameters, endpoints, scopes, or credentials.

Type:

Dict[str, Any]

abstractmethod connect(credentials=None, **kwargs)

Authenticates and initializes the underlying service client.

Parameters:

• credentials (Optional[Any]) – Optional credentials, OAuth tokens, or API keys.

• **kwargs (Any) – Additional service-specific initialization options.

Returns:

The authenticated service client instance (e.g. Google API Resource).

Return type:

Any

Raises:

ConnectionError – If authentication or connection initialization fails.

abstractmethod disconnect()

Disconnects active session and releases held network resources.

Return type:

None

property is_connected: bool

Indicates whether the connection is currently established and active.

Returns:

True if connected and ready for requests; otherwise False.

Return type:

bool

property service: Any | None

Provides direct access to the underlying authenticated API client.

Returns:

The active service client instance, or None if not connected.

Return type:

Optional[Any]

clara.connections.registry module

Connection Registry for Clara Service Integrations.

This module provides the ConnectionRegistry singleton and class to register, instantiate, and look up external service adapters dynamically at runtime.

class clara.connections.registry.ConnectionRegistry

Bases: object

Manages active third-party API service integrations and adapters.

Maintains a catalog of registered connection classes and singleton active instances for reuse across Clara skills and agent workflows.

_connections

Mapping of lowercased connection identifiers to their connection classes.

Type:

Dict[str, Type[BaseConnection]]

_active_instances

Mapping of identifiers to live, instantiated connection objects.

Type:

Dict[str, BaseConnection]

Example

>>> registry = ConnectionRegistry()
>>> registry.register("gmail", GmailConnection)
>>> gmail_client = registry.get_instance("gmail")

register(name, connection_cls)

Registers a connection class under a unique identifier.

Parameters:

• name (str) – Identifier for the connection (e.g., ‘gmail’, ‘calendar’, ‘drive’).

• connection_cls (Type[BaseConnection]) – The class object inheriting from BaseConnection.

Return type:

None

Example

>>> registry.register("gmail", GmailConnection)

get(name)

Retrieves a registered connection class by its identifier.

Parameters:

name (str) – Identifier for the connection.

Returns:

The connection class if registered; otherwise None.

Return type:

Optional[Type[BaseConnection]]

get_instance(name, **kwargs)

Gets an existing instance or instantiates and caches a connection.

Parameters:

• name (str) – Identifier for the connection.

• **kwargs (Any) – Keyword arguments passed to constructor.

Returns:

Active connection instance, or None if not registered.

Return type:

Optional[BaseConnection]

list_connections()

Returns a snapshot of all registered connection classes.

Returns:

Dictionary of names mapped to classes.

Return type:

Dict[str, Type[BaseConnection]]

clara.connections.registry.registry: ConnectionRegistry = <clara.connections.registry.ConnectionRegistry object>

Global default connection registry instance.

Module contents

Service connection adapters and registry for Clara Core.

This package manages integrations with external services such as Google Workspace (Gmail, Calendar, Drive) and other third-party API providers.