Kathy - Personal Email Assistant

A web-based personal email assistant that reads emails from Gmail and Outlook via OAuth2, displays them in a unified inbox, and uses Claude AI to draft replies for user review before sending.

Features

• Unified Inbox - View emails from Gmail and Outlook in one place
• AI-Powered Replies - Claude drafts context-aware replies matching the email's tone
• Tone Control - Choose from professional, friendly, brief, or formal tones
• Custom Instructions - Guide the AI with specific instructions (e.g., "decline politely")
• Review Before Sending - Edit AI-generated drafts before sending
• OAuth2 Authentication - Secure Google and Microsoft OAuth2 integration
• Encrypted Token Storage - OAuth tokens encrypted at rest with Fernet

Tech Stack

Layer	Technology
Frontend	Next.js 14 (App Router, TypeScript, Tailwind CSS)
Backend	Python FastAPI
Database	SQLite (SQLAlchemy, swappable to PostgreSQL)
AI	Anthropic Claude API (Sonnet)
Auth	OAuth2 (Google, Microsoft), JWT session cookies

Project Structure

kathy/
├── frontend/                    # Next.js
│   ├── src/app/                 # Pages (inbox, email detail, settings)
│   ├── src/components/          # EmailList, EmailView, AIDraftPanel, etc.
│   ├── src/hooks/               # useAuth, useEmails
│   └── src/lib/                 # API client, types
│
└── backend/                     # FastAPI
    └── app/
        ├── main.py              # App entry, CORS, routers
        ├── config.py            # Pydantic Settings
        ├── models.py            # User, EmailAccount tables
        ├── auth/                # JWT, Google OAuth, Microsoft OAuth
        ├── routers/             # auth, emails, accounts, ai endpoints
        ├── services/            # Gmail, Outlook, Claude AI services
        └── utils/               # Encryption, email parsing

Getting Started

Prerequisites

• Python 3.11+
• Node.js 18+
• Google Cloud Console project with Gmail API enabled
• Anthropic API key

Setup

1. Clone the repo

   git clone https://github.com/quake0day/Kathy.git
   cd Kathy

2. Configure environment

   cp .env.example backend/.env
   # Edit backend/.env with your credentials

3. Start the backend

   cd backend
   pip install -r requirements.txt
   uvicorn app.main:app --reload --port 8000

4. Start the frontend

   cd frontend
   npm install
   npm run dev

5. Open http://localhost:3000 and connect your email account.

OAuth Setup

Google (Gmail)

1. Go to Google Cloud Console
2. Create a project and enable the Gmail API
3. Configure OAuth consent screen (External, add test users)
4. Create OAuth credentials (Web application)
5. Add redirect URI: http://localhost:8000/api/auth/google/callback

Microsoft (Outlook)

1. Go to Azure Portal → App registrations
2. Register a new application
3. Add redirect URI: http://localhost:8000/api/auth/microsoft/callback
4. Create a client secret

API Endpoints

Method	Path	Purpose
GET	/api/auth/google/login	Start Google OAuth
GET	/api/auth/microsoft/login	Start Microsoft OAuth
GET	/api/auth/me	Current user info
GET	/api/emails	Unified inbox (paginated)
GET	/api/emails/{account_id}/{message_id}	Email detail
POST	/api/emails/{account_id}/{message_id}/reply	Send reply
POST	/api/ai/draft-reply	Generate AI draft reply

License

MIT