google-workspace-setup

name	google-workspace-setup
description	Properly set up Google Workspace OAuth2 authentication for Hermes agent, handling Python environment and module dependencies.
version	1.0.0

Google Workspace Setup Skill

This skill provides a reliable method to set up Google Workspace OAuth2 authentication for the Hermes agent, addressing common issues with Python module imports and environment configuration.

Problem

The standard Google Workspace setup script (setup.py) fails with ModuleNotFoundError: No module named 'hermes_constants' when run directly because:

1. The script depends on Hermes internal modules
2. It needs to be run from the Hermes agent directory with proper Python path
3. Virtual environment activation is required for dependencies

Solution

Always activate the Hermes virtual environment and run the setup script from the hermes-agent directory.

Prerequisites

• Google OAuth2 client secret JSON file (from Google Cloud Console)
• Hermes agent installed and accessible

Steps

Step 1: Prepare OAuth Credentials

1. Go to https://console.cloud.google.com/apis/credentials
2. Create/select a project
3. Enable required APIs: Gmail, Calendar, Drive, Sheets, Docs, People API
4. Create OAuth 2.0 Client ID (Desktop app type)
5. Download the JSON file

Step 2: Copy Credentials to Hermes Directory

# Copy your downloaded client secret to Hermes Google Workspace skill directory
cp /path/to/downloaded/client_secret_*.json ~/.hermes/skills/productivity/google-workspace/google_client_secret.json

Step 3: Run Setup with Proper Environment

# Change to Hermes agent directory and activate virtual environment
cd ~/.hermes/hermes-agent
source venv/bin/activate

# Run the setup script with your client secret
python ~/.hermes/skills/productivity/google-workspace/scripts/setup.py --client-secret ~/.hermes/skills/productivity/google-workspace/google_client_secret.json

# You should see: "OK: Client secret saved to /Users/yourname/.hermes/google_client_secret.json"

Step 4: Get Authorization URL

# Still in the same terminal session (venv activated, in hermes-agent directory)
python ~/.hermes/skills/productivity/google-workspace/scripts/setup.py --auth-url

# Copy the entire URL output and open it in your browser

Step 5: Complete Authorization

1. Open the URL from Step 4 in your browser
2. Sign in with your Google account
3. Grant the requested permissions
4. After redirection (may show an error page - this is normal), copy the ENTIRE URL from the browser's address bar

Step 6: Exchange Authorization Code

# Still in the same terminal session
python ~/.hermes/skills/productivity/google-workspace/scripts/setup.py --auth-code "PASTE_THE_ENTIRE_URL_FROM_STEP_5_HERE"

# You should see: "OK: Token saved to /Users/yourname/.hermes/google_token.json"

Step 7: Verify Authentication

# Still in the same terminal session
python ~/.hermes/skills/productivity/google-workspace/scripts/setup.py --check

# Should output: "AUTHENTICATED"

Verification

After successful setup, you can test Google Workspace access:

# Test Gmail access
python ~/.hermes/skills/productivity/google-workspace/scripts/google_api.py gmail search "is:unread" --max 5

# Test Calendar access
python ~/.hermes/skills/productivity/google-workspace/scripts/google_api.py calendar list

Notes

• Must maintain same terminal session: Steps 3-7 need to be run in the same terminal session where the venv is activated and you're in the hermes-agent directory
• Token storage: The OAuth token is saved automatically to ~/.hermes/google_token.json and refreshes automatically
• Re-authentication: To revoke and restart, use --revoke flag then repeat from Step 3
• Troubleshooting:
  • If you get ModuleNotFoundError again, you likely left the hermes-agent directory or deactivated the venv
  • If you get permission errors, ensure you enabled all required APIs in Google Cloud Console
  • For Advanced Protection accounts, your Workspace admin needs to allowlist the OAuth client ID

Integration with Market Alpha Scout

Once Google Workspace is authenticated, the market_alpha_scout skill can successfully:

1. Authenticate to stockbro.id via Google Workspace
2. Scrape Daily Hot Stocks and Broker Summary data
3. Combine with Google-based sentiment analysis for stock picks

Error Handling

Common errors and solutions:

• ModuleNotFoundError: No module named 'hermes_constants' → Not in hermes-agent directory or venv not activated
• FileNotFoundError for client secret → Check file path and permissions
• invalid_grant → Token expired, redo authorization flow
• 403: Insufficient Permission → Missing API scopes, redo OAuth flow with all required APIs enabled