Add MkDocs documentation

Covers: overview, setup, API reference, configuration, testing, deployment, and known quirks.
2026-04-09 20:24:49 +00:00
parent 17191fc489
commit 760b56bfd6
8 changed files with 691 additions and 0 deletions
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -0,0 +1,114 @@
+# Testing Locally
+
+## Running the Server
+
+```bash
+cd email-classifier
+uv sync
+uv run uvicorn app.main:app --host 0.0.0.0 --port 7999 --reload
+```
+
+The server starts on port **7999** by default. Access the API docs at:
+- Swagger UI: `http://localhost:7999/docs`
+- ReDoc: `http://localhost:7999/redoc`
+
+## Sending Test Requests
+
+### With `curl`
+
+**Simplified request:**
+
+```bash
+curl -X POST http://localhost:7999/classify \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email_data": {
+      "subject": "Printer issue in MB building",
+      "body": "Hi, the printer on floor 2 is not working. Can someone take a look?"
+    },
+    "id": "test-001",
+    "conversationId": "test-conv-001"
+  }'
+```
+
+**Full Outlook-shaped request:**
+
+```bash
+curl -X POST http://localhost:7999/classify \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "AAMkAD...",
+    "conversationId": "AAQkAD...",
+    "subject": "VPN is down",
+    "body": {
+      "contentType": "html",
+      "content": "<html><body>Users are reporting VPN connectivity issues.</body></html>"
+    },
+    "sender": {
+      "emailAddress": {
+        "name": "Jane Smith",
+        "address": "jane.smith@grandportage.com"
+      }
+    },
+    "from": {
+      "emailAddress": {
+        "name": "Jane Smith",
+        "address": "jane.smith@grandportage.com"
+      }
+    },
+    "toRecipients": [
+      {
+        "emailAddress": {
+          "name": "IT Helpdesk",
+          "address": "helpdesk@grandportage.com"
+        }
+      }
+    ],
+    "ccRecipients": [],
+    "receivedDateTime": "2026-04-09T10:00:00Z",
+    "sentDateTime": "2026-04-09T09:55:00Z",
+    "importance": "high"
+  }'
+```
+
+### With the Swagger UI
+
+Open `http://localhost:7999/docs`, click **POST /classify**, click **Try it out**, paste your JSON payload, and click **Execute**.
+
+## Running Tests
+
+This project does not currently include a test suite. To add tests, use `pytest`:
+
+```bash
+uv add --dev pytest pytest-asyncio httpx
+uv run pytest
+```
+
+## Verifying Deduplication
+
+The dedupe store is a SQLite database at `.data/email_classifier.db`. You can inspect it directly:
+
+```bash
+sqlite3 .data/email_classifier.db ".schema classification_dedupe"
+sqlite3 .data/email_classifier.db "SELECT * FROM classification_dedupe LIMIT 10;"
+```
+
+To reset deduplication state between tests:
+
+```bash
+rm .data/email_classifier.db
+```
+
+## Testing with Different LLM Providers
+
+Start the server with a specific provider:
+
+```bash
+LLM_PROVIDER=anthropic \
+LLM_BASE_URL=https://api.minimax.io/anthropic \
+LLM_API_KEY=your_key \
+LLM_MODEL=MiniMax-M2.7 \
+uv run uvicorn app.main:app --reload
+```
+
+Or override per-request by including `provider`, `base_url`, `model`, and `api_key` in the request body.