InboxAI

# 🎯 InboxAI AI-powered Gmail inbox organizer using LangGraph, LangChain, and Google's Gemini AI. Automatically classify, summarize, and manage your emails with intelligent workflows. ## 🌟 Features - **Intelligent Email Classification**: Automatically categorizes emails into: - 📰 **Informative** (newsletters, updates, notifications) - 💬 **Requires Reply** (emails needing your response) - 🗑️ **Ignored** (spam, promotions, unimportant messages) - **AI-Powered Summarization**: - Concise summaries of informative emails - Context extraction for emails requiring replies - Smart reply generation with multiple tone options - **LangGraph Workflow**: State-machine orchestrated email processing pipeline - **Model Context Protocol (MCP) Server**: Ready-to-use MCP server for AI assistant integration with Claude Desktop and other AI assistants - **Gmail API Integration**: Full read/write access to your Gmail account ## 🏗️ Architecture ``` 📧 InboxAI Workflow ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Fetch Emails │───▶│ Classify Emails │───▶│ Summarize │ │ │ │ │ │ Informative │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ │ Summarize │───▶│ Present to │ │ Requires Reply │ │ User │ └─────────────────┘ └─────────────────┘ ``` ### 🔧 Project Structure ``` InboxAI/ ├── src/ │ ├── main.py # CLI interface and main entry point │ ├── mcp_server.py # Model Context Protocol server │ ├── graph.py # LangGraph workflow definition │ └── tools/ │ ├── gmail.py # Gmail API client and Email class │ ├── summarise_email.py # Email summarization functions │ └── reply_email.py # Email reply generation and sending ├── tests/ │ └── test_graph.py # Comprehensive test suite ├── pyproject.toml # Project configuration and dependencies ├── requirements.txt # Legacy requirements file └── README.md # This file ``` ## 🚀 Quick Start ### 1. Prerequisites - Python 3.12+ - Gmail account with API access - Google Cloud Project with Gmail API enabled ### 2. Installation ```bash # Clone the repository git clone https://github.com/yourusername/InboxAI.git cd InboxAI # Install dependencies with uv (recommended) uv sync # Or install with pip pip install -e . ``` ### 3. Gmail API Setup 1. **Create a Google Cloud Project**: - Go to [Google Cloud Console](https://console.cloud.google.com/) - Create a new project or select existing one 2. **Enable Gmail API**: - Navigate to "APIs & Services" > "Library" - Search for "Gmail API" and enable it 3. **Create Credentials**: - Go to "APIs & Services" > "Credentials" - Click "Create Credentials" > "OAuth 2.0 Client IDs" - Choose "Desktop Application" - Download the JSON file as `credentials.json` 4. **Place Credentials**: ```bash # Place the downloaded file in the project root cp ~/Downloads/credentials.json ./credentials.json ``` ### 4. Environment Setup Create a `.env` file in the project root: ```env # Google AI API Key (for Gemini) GOOGLE_API_KEY=your_google_ai_api_key_here # Optional: Customize LLM model LLM_MODEL=google_genai:gemini-2.5-flash ``` ### 5. First Run ```bash # Run InboxAI uv run python src/main.py # Or specify time window uv run python src/main.py --time 7d # Interactive mode uv run python src/main.py --interactive ``` ## 📖 Usage ### Command Line Interface ```bash # Basic usage - process last 24 hours uv run python src/main.py # Specify time window uv run python src/main.py --time 12h # Last 12 hours uv run python src/main.py --time 7d # Last 7 days uv run python src/main.py --time 3d # Last 3 days # Show processing statistics uv run python src/main.py --stats --time 24h # Reply to an email uv run python src/main.py --reply email_id_123 --reply-text "Thanks for your message!" # Generate reply suggestions uv run python src/main.py --suggestions email_id_123 # Interactive mode uv run python src/main.py --interactive ``` ### Interactive Mode Commands ``` 📧 InboxAI> process 24h # Process emails from last 24 hours 📧 InboxAI> stats 7d # Show statistics for last 7 days 📧 InboxAI> reply 123 Thank you! # Reply to email with ID 123 📧 InboxAI> suggest 123 # Get reply suggestions for email 123 📧 InboxAI> quit # Exit interactive mode ``` ### Python API ```python from src.graph import process_inbox from src.tools.reply_email import reply_to_email_mcp from src.tools.summarise_email import summarise_emails_mcp # Process emails result = process_inbox("24h") print(result) # Summarize emails using MCP function summary = summarise_emails_mcp("24h") print(summary) # Reply to an email reply_result = reply_to_email_mcp( email_id="123", reply_text="Thank you for your email!", auto_generate=False ) # Auto-generate a reply auto_reply = reply_to_email_mcp( email_id="123", auto_generate=True, tone="professional" ) ``` ## 🔧 Configuration ### Environment Variables | Variable | Description | Default | | ---------------- | ---------------------------- | ------------------------------- | | `GOOGLE_API_KEY` | Google AI API key for Gemini | Required | | `LLM_MODEL` | Language model to use | `google_genai:gemini-2.5-flash` | ### Gmail API Scopes The application requires these Gmail API scopes: - `https://www.googleapis.com/auth/gmail.readonly` - Read emails - `https://www.googleapis.com/auth/gmail.send` - Send emails - `https://www.googleapis.com/auth/gmail.modify` - Modify emails ## 🧪 Testing Run the test suite: ```bash # Install test dependencies uv add --dev pytest pytest-mock # Run tests uv run pytest tests/ -v # Run with coverage uv run pytest tests/ --cov=src --cov-report=html ``` ### Test Structure - **Unit Tests**: Individual component testing - **Integration Tests**: Complete workflow testing - **Mock Tests**: Gmail API and LLM interaction testing - **Error Handling**: Exception and edge case testing ## 🔌 MCP Integration InboxAI provides a Model Context Protocol server for integration with AI assistants like Claude Desktop: ### Available Tools - `summarise_emails_mcp(time_window)` - Fetch and categorize emails with AI summaries - `reply_to_email_mcp(email_id, reply_text)` - Send intelligent replies - `get_email_suggestions(email_id, num_suggestions)` - Generate multiple reply options - `process_inbox_full(time_window)` - Run complete workflow ### Usage with Claude Desktop ```bash # Start MCP server uv run python src/mcp_server.py ``` See [MCP_GUIDE.md](./MCP_GUIDE.md) for detailed integration instructions. ## 🎨 Customization ### Adding New Email Categories 1. Update the `EmailClassification` model in `graph.py`: ```python category: Literal["informative", "requires_reply", "ignored", "urgent"] = Field(...) ``` 2. Modify classification logic in `classify_emails_node()` 3. Add corresponding summarization logic ### Custom LLM Models ```python # In graph.py, change the LLM initialization llm = init_chat_model("openai:gpt-4") # Use OpenAI llm = init_chat_model("anthropic:claude-3") # Use Anthropic ``` ## 🐛 Troubleshooting ### Common Issues 1. **"Import googleapiclient.discovery could not be resolved"** ```bash uv add google-api-python-client google-auth-oauthlib ``` 2. **Gmail API Authentication Failed** - Ensure `credentials.json` is in the correct location - Check that Gmail API is enabled in Google Cloud Console - Verify OAuth 2.0 client ID is configured for "Desktop Application" 3. **"No module named 'google.generativeai'"** ```bash uv add google-generativeai ``` 4. **Empty Email Results** - Check Gmail API quotas and limits - Verify time window format (e.g., "24h", "7d") - Ensure you have unread emails in the specified timeframe ### Debug Mode Enable detailed logging: ```bash export PYTHONPATH=$PYTHONPATH:./src uv run python src/main.py --time 1h --verbose ``` ## 🚧 Development ### Contributing 1. Fork the repository 2. Create a feature branch: `git checkout -b feature-name` 3. Make changes and add tests 4. Run tests: `uv run pytest tests/` 5. Submit a pull request ### Development Setup ```bash # Install development dependencies uv sync --dev # Install pre-commit hooks (optional) pre-commit install # Run linting uv run flake8 src/ tests/ uv run black src/ tests/ # Type checking uv run mypy src/ ``` ## 🏗️ Technical Architecture ### LangGraph State Machine The email processing workflow is implemented as a LangGraph state machine with the following nodes: - **Fetch Node**: Retrieves emails from Gmail API with time filtering - **Classify Node**: Uses Gemini AI to categorize emails into types - **Summarize Informative Node**: Generates concise summaries for informative emails - **Summarize Reply Node**: Extracts context and suggests replies for actionable emails - **Present Node**: Formats and presents results to the user ### AI Integration - **Classification**: Uses structured output with Pydantic models for reliable categorization - **Summarization**: Context-aware prompts optimized for different email types - **Reply Generation**: Multi-tone reply suggestions with professional/casual/friendly options ### Data Privacy - All email processing happens locally - Only email classification/summarization uses external AI API (Google Gemini) - No email content is stored permanently - OAuth credentials are securely managed ## 📄 License This project is licensed under the MIT License - see the LICENSE file for details. ## 🙏 Acknowledgments - **LangChain** & **LangGraph** for the orchestration framework - **Google Gemini** for AI capabilities - **Gmail API** for email access - **Python ecosystem** for excellent tooling ## 📞 Support - 📖 [Documentation](./README.md) - 🔧 [Setup Guide](./SETUP.md) - 🔌 [MCP Integration](./MCP_GUIDE.md) - 🐛 [Issue Tracker](https://github.com/yourusername/InboxAI/issues) --- **Built with ❤️ using LangGraph, LangChain, and Google AI** _Designed for developers who want to leverage AI for intelligent email management._