OpenPoke Documentation

The project is split into two main directories:

• server/: Contains the FastAPI application, agent logic, and backend services.
• web/: Contains the Next.js web application.
• server/data/: A directory used for runtime data (this is ignored by git and is not part of the source code).

OpenPoke requires two primary API integrations to function. These must be configured in the .env file located in the root directory.

The OpenPoke server manages two primary background services that are tied to the FastAPI application lifecycle via startup and shutdown events:

1. Trigger Scheduler: Managed via get_trigger_scheduler().
2. Important Email Watcher: Managed via get_important_email_watcher().

When the application starts, these services are initialized using their .start() methods. When the application shuts down, they are stopped using their .stop() methods to ensure a graceful exit.

To optimize performance, the Gmail service implements a thread-safe in-memory cache for user profiles.

1. Fetching: When fetch_status is called, the system first checks _get_cached_profile. If a profile is not found in the cache, it calls _fetch_profile_from_composio using the GMAIL_GET_PROFILE tool.
2. Caching: Once a profile is successfully fetched from Composio, it is stored via _cache_profile with a timestamp (cached_at).
3. Invalidation: Profiles are cleared from the cache in two scenarios:
   • When _clear_cached_profile(user_id) is called for a specific user.
   • When disconnect_account is called, which clears all profiles for the affected user IDs.
   • When a new connection is initiated for a user, the existing cache for that user is cleared.

To start the Gmail OAuth connection process, use initiate_connect. This function requires a GmailConnectPayload containing the user_id and an auth_config_id. If auth_config_id is not provided in the payload, it will attempt to use the composio_gmail_auth_config_id from the application settings.

It returns a JSONResponse containing a redirect_url for the user to complete authentication, a connection_request_id, and the user_id.

# Example usage (conceptual)
from server.services.gmail.client import initiate_connect
from server.models import GmailConnectPayload

payload = GmailConnectPayload(
    user_id="user_123",
    auth_config_id="your_composio_auth_config_id"
)
response = initiate_connect(payload, settings)
# response contains {'ok': True, 'redirect_url': '...', 'connection_request_id': '...', 'user_id': 'user_123'}

The register_exception_handlers function configures a FastAPI application to return consistent JSON error responses for common error types. It handles:

• RequestValidationError: Returns a 422 Unprocessable Entity status with a JSON body containing {"ok": false, "error": "Invalid request", "detail": <errors>}.
• HTTPException: Returns the specified status code with a JSON body {"ok": false, "error": <detail>}. If the detail is not a string, it is JSON-serialized.
• Exception (Unhandled): Returns a 500 Internal Server Error status with a JSON body {"ok": false, "error": "Internal server error"}.

This ensures that all API errors follow a predictable schema for clients.

from server.app import register_exception_handlers
from fastapi import FastAPI

app = FastAPI()
register_exception_handlers(app)

Use disconnect_account to remove a Gmail connection. It accepts a GmailDisconnectPayload.

If a connection_id is provided, it attempts to delete that specific connection. If only a user_id is provided, it lists all Gmail connections for that user and attempts to delete them all. The function also clears any cached profiles associated with the affected user IDs.

Returns a JSONResponse containing:

• ok: boolean
• disconnected: boolean (true if connections were removed)
• removed_connection_ids: list of IDs that were successfully deleted
• warnings: (optional) list of error messages encountered during the process.

# Example usage (conceptual)
from server.services.gmail.client import disconnect_account
from server.models import GmailDisconnectPayload

payload = GmailDisconnectPayload(user_id="user_123")
response = disconnect_account(payload)

The execute_gmail_tool function allows you to run specific Gmail operations (tools) through the Composio SDK.

Parameters:

• tool_name (str): The name of the Gmail tool to execute (e.g., GMAIL_GET_PROFILE).
• composio_user_id (str): The ID of the user in Composio.
• arguments (dict, optional): A dictionary of arguments for the tool. Note that user_id is automatically defaulted to "me" if not provided in the arguments.

Returns:

• A dictionary containing the normalized tool response.

Errors:

• Raises a RuntimeError if the tool invocation fails.

# Example usage (conceptual)
from server.services.gmail.client import execute_gmail_tool

result = execute_gmail_tool(
    tool_name="GMAIL_GET_PROFILE",
    composio_user_id="user_123",
    arguments={"user_id": "me"}
)

The default base URL used for all OpenRouter API requests is https://openrouter.ai/api/v1.

OpenRouterBaseURL = "https://openrouter.ai/api/v1"