How parthshr370/email-ai-agent works
Project Type and Purpose
• This is a backend-only, AI-driven email automation pipeline written in Python.
• Purpose: fetch emails (live or simulated), classify and summarize them via LLMs, draft replies, allow human review, and send responses via SMTP.
• It leverages a state-graph workflow (LangGraph) to orchestrate agents at each processing step.
File Structure
• Top-level scripts:
• main.py: entry point
• email.sh: auxiliary shell script
• test_email.py: unit tests
• Configuration:
• config.py: loads environment variables (.env)
• Core modules (core/):
• email_imap.py: IMAP connector for live fetching
• email_ingestion.py: JSON-based simulation loader
• email_sender.py: SMTP integration
• state.py: EmailState data model
• supervisor.py: orchestrates the state graph workflow
• Agents (agents/):
• filtering_agent.py
• summarization_agent.py
• response_agent.py
• human_review_agent.py
• Utilities (utils/):
• formatter.py: email formatting helpers
• logger.py: centralized logging setup
Extract Architectural Insights from README
• Workflow steps: Ingestion → Filtering → Summarization → Response Generation → (Optional) Human Review → Sending/Drafting.
• Integrations: Deepseek API for LLM calls, IMAP server for fetching, SMTP server for sending.
• State Graph: conditional transitions based on classification results.
Main Components
a. Ingestion Layer
• IMAP Connector (core/email_imap)
• JSON Loader (core/email_ingestion)
b. Controller / Orchestrator
• State-Graph Supervisor (core/supervisor)
• EmailState Model (core/state)
c. Agent Layer
• Filtering Agent (classifies emails)
• Summarization Agent
• Response Agent (drafts replies)
• Human Review Agent (prompts for manual edits)
d. Delivery Layer
• SMTP Sender (core/email_sender)
• Draft Handler (writes drafts to file or Gmail)
e. External Services
• Deepseek API (LLM calls)
• IMAP Server
• SMTP Server
Relationships and Data Flow
• Conditional branch: If “needs review” → Human Review Agent → Supervisor
• External calls from each agent/component to Deepseek API.
Architectural Patterns and Design Principles
• Pipeline / Chain of Responsibility: each agent handles one responsibility.
• State Machine / Workflow: LangGraph manages step transitions.
• Modular Separation: core vs agents vs utils.
• Dependency Injection via config.py for credentials and API keys.
• Testability: clear boundaries enable unit tests (test_email.py).
Technologies and Frameworks
• Python 3.8+
• Deepseek API (LLM backend)
• LangGraph (state graph orchestrator)
• IMAP & SMTP protocols
• Logging with utils/logger.py
• Formatting utilities in utils/formatter.py