feat: Implement AI classification and Web UI, refactor to IMAP

2025-12-29 15:50:35 +09:00
commit d3c9cd2c7f
13 changed files with 928 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,142 @@
+# AI-Powered Mail Automation Engine
+
+This project provides a framework for automatically processing emails from an IMAP server based on a user-defined set of rules. It can categorize, archive, or delete emails, serving as a powerful personal email assistant.
+
+## Core Concepts
+
+The engine works by connecting to an IMAP mail server, fetching unread emails, and processing them according to rules you define in a JSON file. This allows for a highly customizable workflow to manage your inbox.
+
+### AI-Powered Classification
+The standout feature is the ability to use Google's Gemini large language model to classify emails based on their content. You define a list of categories, and the AI will determine the most appropriate one for each email. This allows for much more intelligent and nuanced routing than simple keyword matching.
+
+### Key Components
+- `main.py`: The main entry point that runs the FastAPI web server and provides the API.
+- `processing_logic.py`: The core module that handles the email processing workflow, including the rule engine.
+- `ai_classifier.py`: The module that communicates with the Gemini API to classify emails.
+- `imap_client.py`: A class that handles all communication with the IMAP server.
+- `config.json`: Stores your sensitive connection details and API keys.
+- `rules.json`: **This is where you define your workflow.** You create rules that match email properties (like sender or subject) or AI classification results, and link them to specific actions.
+- `web/`: Contains the HTML, CSS, and JavaScript files for the web UI.
+
+## The 4-Step Workflow
+
+Based on the rules you set, the script can perform one of the following actions for each email:
+1.  **DEVONthink (Archive):** Downloads the email as a `.eml` file and saves it to a specified folder. This folder can be indexed by DEVONthink for automatic import.
+2.  **CATEGORIZE:** Moves the email to a specific mailbox on the server.
+3.  **REVIEW:** Moves the email to a "Review" mailbox if it doesn't match any other rule, allowing you to handle it manually.
+4.  **TRASH:** Moves the email to the Trash.
+
+## Setup and Usage (Local Development)
+
+### 1. Configure Credentials (`config.json`)
+
+Update `config.json` with your mail server details and your Gemini API key.
+
+```json
+{
+  "username": "your_email_username",
+  "password": "your_email_password",
+  "imap": {
+    "server": "mail.hyungi.net",
+    "port": 993
+  },
+  "gemini_api_key": "YOUR_GEMINI_API_KEY"
+}
+```
+- You can get a Gemini API key from Google AI Studio.
+
+### 2. Define Your Workflow (`rules.json`)
+
+This is the most important step. Open `rules.json` and define your email processing logic.
+
+To use the AI, first define your categories in the `ai_categories` list. Then, create rules that use the `ai_classification_is` condition.
+
+```json
+{
+  "ai_categories": ["청구서", "프로젝트 업데이트", "광고", "개인 용무", "기타"],
+  "rules": [
+    {
+      "rule_name": "AI 분류: 청구서는 DEVONthink로",
+      "conditions": {
+        "ai_classification_is": "청구서"
+      },
+      "action": {
+        "type": "DEVONTHINK",
+        "parameters": {
+          "devonthink_inbox_path": "/path/on/nas/for/devonthink"
+        }
+      }
+    },
+    {
+      "rule_name": "키워드: 중요한 프로젝트",
+      "conditions": {
+        "subject_contains": "[Urgent Project]"
+      },
+      "action": {
+        "type": "CATEGORIZE",
+        "parameters": {
+          "move_to_mailbox": "INBOX/Urgent"
+        }
+      }
+    }
+  ],
+  "default_action": {
+    "type": "REVIEW",
+    "parameters": {
+      "move_to_mailbox": "INBOX/Review"
+    }
+  }
+}
+```
+- **`ai_categories`**: A list of categories you want the AI to use.
+- **`conditions`**: Can be `subject_contains`, `from_contains`, or `ai_classification_is`.
+- **`action`**: The action to perform (`DEVONTHINK`, `CATEGORIZE`, `TRASH`, `REVIEW`).
+
+### 3. Installation
+
+This project uses a virtual environment to manage dependencies.
+
+**Create the environment (only once):**
+```bash
+python3 -m venv venv
+```
+
+**Activate the environment and install packages:**
+(Activate the environment every time you open a new terminal)
+```bash
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+### 4. Running the Web Server
+
+With the virtual environment activated, run the FastAPI server:
+
+```bash
+uvicorn main:app --host 0.0.0.0 --port 8000 --reload
+```
+- The `--reload` flag automatically restarts the server when you make code changes.
+- Access the web UI by opening `http://localhost:8000` in your browser.
+
+## Docker
+
+You can also build and run this application as a Docker container.
+
+### 1. Build the Image
+```bash
+docker build -t mail-manager .
+```
+
+### 2. Run the Container
+```bash
+# Make sure your config.json and rules.json are correctly filled out
+docker run --rm -p 8000:8000 -v $(pwd)/config.json:/app/config.json -v $(pwd)/rules.json:/app/rules.json mail-manager
+```
+- `-p 8000:8000`: This maps port 8000 on your local machine to port 8000 in the container, making the web UI accessible at `http://localhost:8000`.
+- `-v`: Using volumes mounts your local configuration files into the container, making it easy to manage them without rebuilding the image.
+
+## Roadmap
+
+- **Advanced Rule Conditions:** Add more complex conditions to the rule engine (e.g., regex matching, checking for attachments).
+- **Improved Web UI:** Enhance the web interface for a more user-friendly rule editing experience (e.g., with forms instead of raw JSON).
+- **Scheduler:** Implement a scheduler within the application to run the email processing task automatically at regular intervals.