How tonykipkemboi/crewai-gmail-automation works
Project Type and Purpose
• This is an open-source Python CLI tool (not a web or mobile app) named “Gmail Automation with CrewAI.”
• Purpose: Automate Gmail inbox management—categorization, labeling, priority assignment, automated replies, cleanup—and send Slack notifications for high-priority emails, leveraging LLM agents via external APIs.
File Structure
• Top-level files and directories:
• .env_example, pyproject.toml: configuration and packaging
• src/gmail_crew_ai/ – core Python package
• src/gmail_crew_ai/config/ – YAML configurations for agents and tasks
• src/gmail_crew_ai/crew.py – orchestrator class
• src/gmail_crew_ai/main.py – CLI entry point
• src/gmail_crew_ai/models.py – data models (email metadata, tasks)
• src/gmail_crew_ai/tools/ – helpers (‘gmail_tools.py’, ‘slack_tool.py’, ‘date_tools.py’)
• assets/, knowledge/ – static assets & user preference data
• Key patterns:
• Modular design: orchestration, configuration, tooling, models separated by directory
• External integrations: IMAP server (Gmail), LLM provider (OpenAI/Gemini/Ollama), Slack Webhook
Extract Insights from the README
• Technical stack: Python 3, IMAP, SSL, LLM API calls, Slack incoming webhooks
• Workflow steps: fetch unread emails → categorize/assign priority → apply Gmail labels/stars → draft AI-generated replies → send Slack alerts → cleanup & trash management
• Configurable via .env (credentials) and agents.yaml/tasks.yaml
a. Main Components
1. CLI Launcher (main.py)
2. Orchestrator (Crew class in crew.py)
3. Configuration Store (agents.yaml, tasks.yaml, .env)
4. IMAP Client Module (gmail_tools.py)
5. LLM Agent Module (models.py + external API client)
6. Slack Notifier Module (slack_tool.py)
7. Date/Time Helpers (date_tools.py)
8. Knowledge Base (knowledge/user_preference.txt)
9. External Services:
• Gmail IMAP Server
• OpenAI/Gemini/Ollama API
• Slack Incoming Webhook
b. Relationships and Data Flow
• User runs crewai run → CLI Launcher
• CLI passes input (num of emails) to Orchestrator
• Orchestrator reads .env and YAML configs
• Orchestrator calls IMAP Client to fetch unread emails
• Emails → Data Models → passed to LLM Agent for categorization and response generation
• LLM Agent calls external LLM API
• Categorized emails → IMAP Client applies labels, stars, moves/trashes messages
• For high-priority: Orchestrator → Slack Notifier → Slack Webhook
• Cleanup logic uses Date Helpers + Gmail tools
• Knowledge Base consulted for user preferences or persistent rules
c. Architectural Patterns and Principles
• Separation of Concerns: distinct modules for config, orchestration, tooling, models
• Dependency Injection: pass config and clients into the Crew orchestrator
• Extensibility: agents/tasks YAML files allow adding new behaviors without code changes
• Fail-safe cleanup: ensures IMAP connections close properly
d. Key Technologies
• Python 3, imaplib (or a similar IMAP wrapper)
• YAML for configuration
• OpenAI/Gemini/Ollama LLM API
• Slack Incoming Webhooks
• .env for secrets management
Detail
• Even small helpers (date_tools) as they play a role in cleanup rules.
• Lifecycle of a single email and how it traverses through modules.
• Configuration flow: .env → environment variables → modules reading credentials, and YAML → modules loading behavior rules.