🎯 Ascent TechFest 2026 - AI Mail Automation System

An intelligent, production-ready email support automation system that uses AI and RAG (Retrieval-Augmented Generation) to handle support tickets for Ascent TechFest 2026.

📋 Features

✅ Automated Email Reading - Connects to Gmail API to read unread emails
✅ RAG Pipeline - Retrieves relevant FAQ answers using semantic search
✅ LLM Integration - Uses Groq's Llama 3.3 70B for intelligent responses
✅ Thread Tracking - Maintains conversation history with built-in escalation
✅ Smart Escalation - Automatically escalates uncertain queries to human team
✅ Duplicate Prevention - Prevents replying to the same email twice
✅ Database Persistence - SQLite database for tracking all interactions
✅ Comprehensive Logging - Detailed logs for debugging and monitoring
✅ Error Resilience - Automatic error recovery and email retry logic ✅ Thread-Safe Database - Concurrent request handling with proper transaction management ✅ Input Validation - Robust validation of Gmail API responses ✅ Rate Limiting - 60-second polling interval with exponential backoff ✅ Configuration Validation - Startup validation of required environment variables ✅ Production Security - .gitignore for sensitive files, .env.example template

🏗️ Architecture

┌─────────────────────────────┐
│   Gmail Inbox (UNREAD)      │
└────────────┬────────────────┘
             │
     ┌───────▼────────┐
     │ Email Reader   │  (Extracts thread ID, body, sender)
     └───────┬────────┘
             │
     ┌───────▼────────────────────┐
     │ Duplicate Check (Database) │
     └───────┬────────────────────┘
             │
     ┌──────▼──────────────────────┐
     │ RAG System                  │  (FAQ embedding + retrieval)
     │ • Load FAQ chunks           │
     │ • Create embeddings         │
     │ • Find top-3 similar chunks │
     └──────┬──────────────────────┘
            │
     ┌──────▼─────────────────┐
     │ LLM (Groq - Llama 3.3) │  (Generate answer from context)
     │ • Generate response    │
     │ • Safety validation    │
     │ • Confidence scoring   │
     └──────┬─────────────────┘
            │
     ┌──────▼────────────────────────┐
     │ Decision Engine                │
     │ • If confident → AUTO-REPLY    │
     │ • If uncertain → ESCALATE      │
     │ • If 2nd reply → ESCALATE      │
     └──────┬────────────────────────┘
            │
  ┌─────────┴──────────┬──────────────┐
  │                    │              │
  ▼                    ▼              ▼
AUTO-REPLY         ESCALATE      EMAIL SENT
(Gmail)            (Notify Team)  (Mark Read)
  │                 │              │
  └─────────────────┴──────────────┘
            │
      ┌─────▼──────┐
      │  Database  │  (Log transaction)
      │  (SQLite)  │
      └────────────┘

🚀 Quick Start

1. Installation

# Clone/navigate to project directory
cd "path/to/Ascent Mail Automation"

# Install dependencies
pip install -r requirements.txt

2. Setup Gmail API

1. Go to Google Cloud Console
2. Create a new project (or use existing)
3. Enable Gmail API
4. Create OAuth 2.0 credentials (Desktop application)
5. Download credentials as JSON
6. Save as credentials/credentials.json

3. Prepare FAQ Data

Create data/faq.txt with format:

Q: What time is the event?
A: Ascent TechFest 2026 will be held from 9 AM to 5 PM on March 15, 2026.

Q: Where is the venue?
A: The event will be held at the Main campus auditorium.

Q: Can I participate remotely?
A: No, this is an on-campus event only.

4. Configure Environment

Create .env file:

GROQ_API_KEY=gsk_your_api_key_here
[email protected]

Get your GROQ API key from groq.com

5. Run the System

# From project root
python -m app.main

# Or with virtual environment
.\venv\Scripts\activate
python -m app.main

📊 Database Schema

email_threads table

• thread_id - Gmail conversation thread ID
• email_id - Individual message ID
• sender_email - Sender's email address
• subject - Email subject
• status - pending|auto_replied|escalated|resolved
• reply_count - Number of replies in thread
• created_at - Timestamp
• updated_at - Last update timestamp

email_log table

• thread_id - Reference to thread
• email_id - Message ID
• query - Original user query
• context - Retrieved FAQ context
• ai_response - Generated AI answer
• confidence - YES|NO
• action_taken - auto_replied|escalated|error
• error - Error message (if any)
• processed_at - Processing timestamp

🔧 Configuration

Email Check Interval

Edit in app/main.py:

system.run_loop(check_interval=30)  # Check every 30 seconds

LLM Parameters

Edit in app/llm.py:

response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    temperature=0.3,  # Lower = more consistent
    max_tokens=500    # Max response length
)

FAQ Retrieval

Edit in app/rag.py:

def retrieve(self, query, k=3):  # k = number of chunks to retrieve
    ...

📝 Logs

Logs are saved in logs/ directory:

• One file per run
• Rotates after 5MB
• Keeps last 5 backups

View logs:

tail -f logs/ascent_*.log

🚨 Escalation Triggers

Email is escalated when:

1. Low Confidence - AI is uncertain about the answer
2. User Replies Twice - Applicant replied to an automated response
3. Parsing Error - Email body couldn't be extracted
4. Processing Error - Any system error occurs

Escalated emails are:

• Logged in database with status='escalated'
• Notification sent to team
• Applicant receives professional response

🛡️ Safety Features

• Hallucination Prevention - Answers strictly grounded in FAQ context
• Uncertainty Detection - Identifies uncertain responses
• Duplicate Prevention - Checks database before processing
• Error Recovery - Auto-restart on failure with exponential backoff (up to 5 consecutive errors)
• Rate Limiting - 60-second polling interval to prevent API throttling
• Thread-Safe Database - Concurrent requests handled with locks and proper transactions
• Input Validation - All Gmail API responses validated before processing
• Retry Logic - Exponential backoff for failed API calls (3 retries)

🔐 Production-Ready Improvements

Security & Configuration

• ✅ .gitignore created to prevent accidental credential commits
• ✅ .env.example template for environment variable reference
• ✅ Configuration validation at startup (validate_config())
• ✅ All required files checked before system starts

Database Reliability

• ✅ Thread-safe database with locks (threading.Lock)
• ✅ Connection pooling with 10-second timeout
• ✅ Proper transaction management with rollback on errors
• ✅ Foreign key constraints for data integrity

API Resilience

• ✅ Input validation for all Gmail API responses
• ✅ Retry logic with exponential backoff for failed requests
• ✅ Graceful handling of malformed responses
• ✅ Comprehensive error logging for debugging

Rate Limiting & Performance

• ✅ Email check interval changed from 30 to 60 seconds
• ✅ Exponential backoff for consecutive errors (max 60 seconds)
• ✅ 1-second delay between email processing
• ✅ Prevention of Gmail API rate limit violations

📈 Monitoring

Check System Status

# View escalated tickets
sqlite3 data/emails.db "SELECT * FROM email_threads WHERE status='escalated';"

# View processing log
sqlite3 data/emails.db "SELECT thread_id, confidence, action_taken FROM email_log ORDER BY processed_at DESC LIMIT 10;"

# Statistics
sqlite3 data/emails.db "SELECT
    COUNT(*) as total,
    SUM(CASE WHEN status='auto_replied' THEN 1 ELSE 0 END) as auto_replied,
    SUM(CASE WHEN status='escalated' THEN 1 ELSE 0 END) as escalated
FROM email_threads;"

🐳 Deployment Options

Option 1: VPS (Recommended)

# On Linux VPS (Ubuntu 20.04+)
git clone <repo-url>
cd "Ascent Mail Automation"
pip install -r requirements.txt

# Create systemd service
sudo nano /etc/systemd/system/ascent-mail.service

Service file content:

[Unit]
Description=Ascent Mail Automation
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/Ascent\ Mail\ Automation
ExecStart=/usr/bin/python3 -m app.main
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Start service:

systemctl start ascent-mail
systemctl enable ascent-mail

Option 2: Docker

Create Dockerfile:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "-m", "app.main"]

Option 3: Cloud Functions (Serverless)

Use Gmail push notifications instead of polling.

🐛 Troubleshooting

"No module named 'app'"

# Run from project root
cd /path/to/project
python -m app.main

Gmail authentication fails

• Delete token.pickle
• Check credentials/credentials.json exists
• Verify Gmail API is enabled in Google Cloud Console

FAQ not loading

• Check data/faq.txt exists
• Verify format: Q: ... A: ...
• Check file encoding (UTF-8)

Database locked

# Remove lock
rm data/emails.db-wal
rm data/emails.db-shm

📚 API References

• Gmail API Docs
• Groq API Docs
• Sentence Transformers
• FAISS

📝 License & Credits

Built for Ascent TechFest 2026

🤝 Contributing

To add improvements:

1. Test locally
2. Update documentation
3. Submit changes

📞 Support

For issues or questions, create an issue in the repository.

---

Status: Production Ready ✅
Last Updated: 2nd March 2026
Version: 1.0.0