langgraph-email-automation

Implements a LangGraph StateGraph-based workflow that routes incoming emails through specialized AI agents for intelligent classification into product_inquiry, complaint, feedback, or unrelated categories. Uses conditional routing nodes that branch the workflow based on categorization results, enabling different processing paths for each email type. The categorization agent leverages LangChain with Groq/Google APIs to analyze email content and metadata, with routing decisions persisted in a custom GraphState object that maintains context across workflow steps.

Generates customer support responses by combining retrieval-augmented generation (RAG) with ChromaDB vector store and Google Embeddings. For product_inquiry emails, the system retrieves relevant product documentation from the vector store using semantic similarity search, then passes retrieved context to a writing agent that generates contextually appropriate responses. Uses a two-stage pipeline: (1) embedding-based retrieval of top-k relevant documents from ChromaDB, (2) LLM-based response generation conditioned on retrieved context. The vector store is pre-populated via create_index.py which chunks and embeds product documentation.

Provides a standalone execution mode (main.py) that runs the email processing workflow as a continuous background process without requiring API deployment. The standalone mode fetches emails from Gmail in a loop (configurable polling interval), processes each email through the workflow, and sends responses. Useful for development, testing, and simple deployments where API infrastructure is not needed. Includes console logging for monitoring and debugging. Can be run as a systemd service or Docker container for production use.

Implements a quality assurance node that validates generated responses before sending using a specialized proofreading agent. The QA agent checks for grammatical errors, tone consistency, factual accuracy (by comparing against retrieved context), and compliance with support guidelines. Uses LangChain agents with Groq/Google APIs to perform multi-dimensional quality checks, returning a quality score and list of issues. If quality score falls below a threshold, the response is flagged for human review rather than auto-sent. The QA node is integrated into the workflow graph as a post-generation step before email sending.

Implements a polling-based email monitoring system that continuously fetches new emails from Gmail inbox using the Gmail API with authenticated access. The monitoring node runs in a loop (configurable polling interval) and retrieves unread emails, parses email metadata (sender, subject, timestamp, body), and feeds them into the processing workflow. Uses Gmail API's label-based filtering to identify new emails and marks processed emails as read to avoid reprocessing. The polling mechanism is integrated into the main.py entry point for standalone deployment or exposed as an API endpoint in deploy_api.py for service-based deployment.

Implements the core workflow orchestration using LangGraph's StateGraph primitive, which manages the entire email processing pipeline as a directed acyclic graph (DAG) of nodes and edges. Each node represents a processing step (categorization, retrieval, generation, QA, sending), and edges define the control flow between nodes. The custom GraphState object maintains workflow state across all steps, including email content, categorization results, retrieved context, generated response, and QA decisions. Conditional edges enable branching logic (e.g., route to different nodes based on email category). The StateGraph is compiled into an executable workflow that can be invoked synchronously or asynchronously.

Provides a unified interface for invoking multiple LLM providers (Groq and Google AI) through LangChain's abstraction layer, enabling agent implementations to be agnostic to the underlying LLM provider. The system uses LangChain's ChatGroq and ChatGoogle integrations to instantiate LLM instances, which are then passed to agent definitions. Agents can be configured to use different providers for different tasks (e.g., Groq for fast categorization, Google for higher-quality response generation). The provider selection is configurable via environment variables, allowing deployment-time switching without code changes.

Implements a document indexing pipeline (create_index.py) that chunks product documentation, generates embeddings using Google Embeddings API, and stores them in ChromaDB vector store for later semantic retrieval. The indexing process: (1) reads product documentation files, (2) chunks documents into overlapping segments (configurable chunk size/overlap), (3) generates embeddings for each chunk using Google Embeddings, (4) stores chunks and embeddings in ChromaDB with metadata. During response generation, the RAG pipeline queries ChromaDB using semantic similarity search to retrieve top-k relevant chunks, which are then passed to the writing agent. ChromaDB provides in-memory or persistent storage options.

Provides a production-ready REST API deployment option (deploy_api.py) that wraps the LangGraph workflow in FastAPI endpoints using LangServe. The API exposes the email processing workflow as HTTP endpoints (e.g., POST /process-email) that accept email objects and return processed results. LangServe handles request/response serialization, async execution, and OpenAPI documentation generation. The API can be deployed as a standalone service or integrated into larger support infrastructure. Supports both synchronous and asynchronous invocation patterns.

Implements specialized AI agents for different tasks (categorization, writing, proofreading) using carefully crafted system prompts that define agent behavior, constraints, and output format. Each agent is instantiated with a specific prompt template (defined in src/prompts.py) that guides the LLM to perform its designated task. Prompts include task description, input/output format specifications, examples, and constraints (e.g., 'keep response under 200 words'). Agents are composed using LangChain's agent framework, which handles tool calling, reasoning, and output parsing. Prompts can be updated without code changes by modifying the prompt templates.

Implements email sending functionality that uses the Gmail API to compose and send generated responses back to customers. The sending node constructs a properly formatted email message (with headers, body, optional attachments) and invokes the Gmail API's send endpoint. Includes error handling for common failures (invalid recipient, quota exceeded, authentication errors) and logging for audit trails. Supports both plain text and HTML-formatted responses. Integrates with the workflow state to track which emails have been sent and prevent duplicate sends.