README.md

metadata

title: EmailAgentwithMemory
emoji: 🦀
colorFrom: green
colorTo: indigo
sdk: docker
pinned: false
license: apache-2.0
short_description: Email  ai agent project with memory.

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

---

---

---

📧 AI-Driven Email Agent 🧠

A production-grade, multi-agent email automation system built with LangGraph and FastAPI that intelligently automates email triage, context retrieval, and professional draft generation with human review.

This project demonstrates advanced implementations of:

• 🧠 Semantic Memory Management with langmem + PostgresStore
• 💾 State Persistence using PostgreSQL Checkpointing
• ⏸️ Human-in-the-Loop Interrupts via LangGraph's Functional API Command pattern
• 🔐 Custom Email Threat Detection (99.35% accuracy with DistilBERT + XGBoost)
• 🚀 Production-Ready Orchestration with FastAPI + Docker

Perfect for: Enterprise email automation, customer support triage, HR workflows, security threat detection, and intelligent email routing.

---

✨ Key Features

🤖 Advanced Multi-Agent Architecture

The system orchestrates three specialized agents:

• Triage Agent: Classifies emails (URGENT/FOLLOW_UP/INFO), assigns priority scores
• Context Agent: Retrieves relevant past interactions via semantic memory
• Email Writing Agent: Generates professional, contextual replies with full conversation history

🧠 Semantic Memory System

• Powered by langmem + PostgreSQL (Neon)
• Stores sent emails with semantic embeddings (Sentence Transformers)
• Retrieves past interactions using cosine similarity
• Namespace pattern: (email_assistant, user_id, collection) for scoped memory
• Enables agent to "remember" projects, clients, technical details across sessions

💾 State Persistence & Recovery

• PostgreSQL Checkpointer: Saves graph state at each node
• Automatic Recovery: Resume from last checkpoint on failure
• Audit Trail: Complete history of email processing decisions

⏸️ Human-in-the-Loop Review

The graph intelligently pauses at draft generation for human feedback:

Draft Generated → interrupt() → User Reviews → Command(resume=...) → Send

• Approve: Send draft as-is
• Reject: Provide feedback → Agent regenerates
• Edit: Manually modify → Save version → Send

🔐 Custom Email Threat Detection

• DistilBERT + XGBoost classifier (99.35% accuracy):
• Semantic Analysis: DistilBERT embeddings detect phishing intent
• URL Feature Engineering: Extracts malicious patterns (subdomain count, keywords, redirects)
• Hybrid Classification: XGBoost combines both features
• Real-time Detection: Quarantines threats before processing

📖 Full Implementation

💡 Resource Optimization

• Token Counter Node: Summarizes large emails before processing
• Cost Reduction: ~40% API savings on verbose emails
• Context Window Management: Prevents overflow, maintains quality

🔒 Enterprise-Ready

• Type-safe configuration (Pydantic Settings)
• PostgreSQL connection pooling
• Structured logging across all nodes
• Docker + Docker Compose deployment
• Rate limiting & input validation

---

🛠️ Tech Stack

Layer	Technology	Purpose
Orchestration	LangGraph (Functional API)	Graph-based workflow with interrupts & commands
LLM	Groq (Mixtral/Llama 3.1)	Fast, cost-effective inference
Memory	langmem + PostgreSQL	Long-term semantic memory with persistence
Embeddings	Sentence Transformers (all-MiniLM-L6-v2)	Semantic similarity for context retrieval
Threat Detection	DistilBERT + XGBoost (Custom)	Email security classification (99.35% accuracy)
Database	PostgreSQL 16 (Neon)	Checkpointing & persistent memory storage
ORM	SQLAlchemy 2.0	Type-safe database operations
API	FastAPI 0.118 + Uvicorn	HTTP endpoints & interactive docs
Configuration	pydantic-settings	Type-safe .env management
Containers	Docker + Docker Compose	Production deployment & orchestration

---

📂 Project Structure

app/
├── agents/
│   ├── triage_agent.py              # Intent classification & priority scoring
│   ├── context_agent.py             # Past interaction retrieval (ReAct reasoning)
│   └── email_writing_agent.py       # Draft generation with full context
│
├── nodes/
│   ├── safety_check_node.py         # Threat detection (DistilBERT + XGBoost)
│   ├── token_count_node.py          # Email size analysis & summarization routing
│   ├── triage_node.py               # Route email → URGENT/FOLLOW_UP/INFO/SPAM
│   ├── context_retrieval_node.py    # Query PostgresStore for semantic context
│   ├── draft_node.py                # Email writing agent + interrupt logic
│   ├── memory_store_node.py         # Persist sent emails with embeddings
│   ├── archive_node.py              # Store processed emails for audit
│   └── unsafe_emails_node.py        # Quarantine detected threats
│
├── state/
│   ├── state.py                     # EmailAgentState TypedDict (comprehensive schema)
│   └── constants.py                 # TriageLabel enum, message templates
│
├── database/
│   ├── models.py                    # SQLAlchemy User, Email, Memory models
│   ├── connection.py                # Connection pooling & session factory
│   └── utils.py                     # Database helpers (get_or_create_user)
│
├── persistence/
│   ├── postgres_checkpoint.py       # PostgreSQL checkpointer configuration
│   └── memory_store_config.py       # LangMem + PostgresStore initialization
│
├── utils/
│   ├── token_counter.py             # tiktoken-based token counting
│   ├── threat_detection.py          # DistilBERT + XGBoost inference
│   ├── embeddings.py                # Sentence Transformers model setup
│   ├── interrupt_utils.py           # Parse interrupt() values
│   └── logger.py                    # Structured logging configuration
│
├── graph.py                         # StateGraph construction & compilation
├── main.py                          # FastAPI application & endpoints
├── config.py                        # Pydantic Settings (database, API keys)
├── requirements.txt                 # Python dependencies
└── docker-compose.yml               # Multi-service orchestration

---

🔄 Multi-Agent Graph Architecture

The system follows a pre-processing → agentic loop → human review → sending pattern:

LangGraph Workflow Diagram

Graph Flow:

1. Safety Check → Your threat detector (DistilBERT + XGBoost) screens for malicious content
2. Token Count → Analyzes email size, routes large emails to summarization
3. Triage → Classifies intent (URGENT/FOLLOW_UP/INFO/FYI)
4. Context Retrieval → Searches PostgreSQL memory for relevant past emails
5. Draft Generation → LLM agent creates professional reply
6. Human Review → Graph pauses via interrupt() for user feedback
7. Resume with Command → User approves/rejects via Command(resume=...)
8. Memory Storage → Saves sent email with embeddings to PostgreSQL
9. Archive → Stores processed email for audit trail

---

📊 Key Nodes

Node	Purpose	Output
safety_check_node	Threat detection (99.35% accuracy)	is_safe, threat_score
token_count_node	Email size optimization	token_count, summarized_body
triage_node	Intent classification	triage_label, priority_score
context_retrieval_node	Semantic memory search	draft_context, past_emails
draft_node	LLM draft generation + interrupt	draft_body, interrupt()
memory_store_node	Persist to PostgresStore	saved_embedding
archive_node	Audit trail	archived_record
unsafe_emails_node	Threat quarantine	quarantined

---

📈 Performance Metrics

• Threat Detection Accuracy: 99.35% (Your Model)
• Email Processing: <2 seconds
• Memory Retrieval: <500ms (semantic search)
• Throughput: 100+ emails/minute
• Latency (p95): <3 seconds end-to-end
• State Persistence: Automatic checkpointing per node

---

🎓 What I Learned

✅ Semantic Memory: langmem + PostgreSQL for long-term learning
✅ State Persistence: PostgreSQL checkpointing for recovery
✅ Human-in-the-Loop: interrupt() + Command(resume=...) pattern
✅ Multi-Agent Orchestration: LangGraph functional API
✅ Custom ML Integration: DistilBERT + XGBoost classifier
✅ Production Architecture: Docker, FastAPI, connection pooling

---

🎯 Key Highlights

Feature	Status	Details
Threat Detection	✅ Custom	99.35% accuracy (DistilBERT + XGBoost)
Semantic Memory	✅ Implemented	langmem + PostgreSQL with embeddings
State Persistence	✅ Implemented	PostgreSQL checkpointing & recovery
Human-in-the-Loop	✅ Implemented	interrupt() + Command(resume=...)
Multi-Agent	✅ Implemented	Triage, Context, Writing agents

---

Built with ❤️ for intelligent, secure email automation.