A real-time Agentic AI system that connects to your Gmail account, monitors your inbox, and allows you to ask natural language questions about your emails using RAG (Retrieval-Augmented Generation).
Built with the OpenAI Agents SDK and powered by OpenRouter for LLM access.
- 📬 Real-time Email Monitoring: Automatically checks Gmail inbox every 60 seconds for new emails
- 🔍 Semantic Search: Find emails by meaning, not just keywords
- 🤖 AI-Powered Answers: Ask questions in natural language and get intelligent responses
- 🗄️ Vector Database: Stores email embeddings in Pinecone for fast retrieval
- 🧠 Multi-Agent Architecture: Specialized agents for ingestion, embedding, and queries
- ⚡ Async-First Design: Built for performance with async/await patterns
┌─────────────────────────────────────────────────────────────────┐
│ Email RAG Assistant │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │
│ │ Gmail Ingestion │───▶│ Embedding Agent │───▶│ Pinecone │ │
│ │ Agent │ │ │ │ Vector DB │ │
│ └─────────────────┘ └─────────────────┘ └──────────────┘ │
│ │ │ │
│ │ ┌─────────────────┐ │ │
│ │ │ RAG Query │◀──────────┘ │
│ │ │ Agent │ │
│ │ └─────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ Main Orchestrator ││
│ │ (Scheduler + Interactive CLI) ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────┘
| Agent | Responsibility |
|---|---|
| Gmail Ingestion Agent | Monitors inbox, fetches new/unread emails, passes to pipeline |
| Embedding Agent | Cleans text, generates embeddings, stores in Pinecone |
| RAG Query Agent | Accepts questions, searches embeddings, generates answers |
email-rag-assistant/
│
├── agents/
│ ├── __init__.py
│ ├── gmail_ingestion_agent.py # Gmail monitoring agent
│ ├── embedding_agent.py # Embedding generation agent
│ └── rag_query_agent.py # RAG query agent
│
├── services/
│ ├── __init__.py
│ ├── gmail_service.py # Gmail API integration
│ └── pinecone_service.py # Pinecone vector DB operations
│
├── utils/
│ ├── __init__.py
│ ├── email_parser.py # Email text cleaning/parsing
│ └── scheduler.py # Periodic task scheduler
│
├── config.py # Configuration & model setup
├── main.py # Main entry point
├── requirements.txt # Python dependencies
├── .env.example # Environment variables template
└── README.md # This file
| Component | Technology |
|---|---|
| Framework | OpenAI Agents SDK |
| LLM Access | OpenRouter (xiaomi/mimo-v2-flash:free) |
| Gmail API (OAuth 2.0) | |
| Vector DB | Pinecone |
| Embeddings | sentence-transformers (all-MiniLM-L6-v2) |
| Language | Python 3.12+ |
- Python 3.12 or higher
- Gmail account with API access enabled
- OpenRouter API key
- Pinecone API key
# Clone the repository
git clone https://github.com/yourusername/email-rag-assistant.git
cd email-rag-assistant
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt# Copy the example environment file
cp .env.example .env
# Edit .env with your API keysRequired environment variables:
OPENROUTER_API_KEY: Your OpenRouter API keyPINECONE_API_KEY: Your Pinecone API key
- Go to Google Cloud Console
- Create a new project or select existing
- Enable the Gmail API
- Create OAuth 2.0 credentials (Desktop application)
- Download the credentials JSON file
- Save it as
credentials.jsonin the project root
# Interactive mode (default)
python main.py
# Run ingestion once
python main.py --ingest
# Run as background daemon
python main.py --daemon============================================================
📧 Email RAG Assistant - Interactive Mode
============================================================
Commands:
Type your question to search emails
'ingest' - Run email ingestion
'stats' - Show system statistics
'help' - Show this help
'quit' - Exit the program
------------------------------------------------------------
You: What emails did I receive about the project deadline?
Searching emails...
### Example Questions
- `What emails did I receive from John last week?`
- `Find emails about the budget report`
- `What meetings do I have scheduled?`
- `Show me emails with attachments about the contract`
- `What did Sarah say about the project?`
## ?? Configuration
### Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `OPENROUTER_API_KEY` | OpenRouter API key | Yes |
| `PINECONE_API_KEY` | Pinecone API key | Yes |
| `PINECONE_INDEX_NAME` | Name of Pinecone index | No (default: email-rag-index) |
| `GMAIL_CREDENTIALS_PATH` | Path to Gmail credentials | No (default: credentials.json) |
| `EMBEDDING_MODEL` | Sentence transformer model | No (default: all-MiniLM-L6-v2) |
| `INGESTION_INTERVAL_SECONDS` | Seconds between email checks | No (default: 60) |
### Example Questions
- What emails did I receive from John last week?
- Find emails about the budget report
- What meetings do I have scheduled?
- Show me emails with attachments about the contract
- What did Sarah say about the project?
## License
MIT License - feel free to use this project for learning and building.