760b56bfd6
Covers: overview, setup, API reference, configuration, testing, deployment, and known quirks.
2.7 KiB
Known Quirks
MiniMax Base URL
MiniMax uses an Anthropic-compatible API endpoint that is different from the standard OpenAI-compatible path. Using the wrong URL will result in silent failures or 404 errors.
Correct MiniMax configuration:
export LLM_PROVIDER=anthropic
export LLM_BASE_URL=https://api.minimax.io/anthropic
export LLM_MODEL=MiniMax-M2.7
Incorrect (common mistake):
# Wrong — this is the OpenAI-compatible path, not the Anthropic path
export LLM_BASE_URL=https://api.minimax.io/v1
MiniMax's Anthropic-compatible endpoint is at /anthropic, not /v1. Always verify the correct endpoint in your provider's documentation.
Per-Request api_key Exclusion
The api_key field in a request body is excluded from all logging and dedupe storage (exclude=True in the Pydantic model). However, it is still transmitted to the LLM adapter in plaintext during the request. Do not send untrusted request bodies to untrusted networks.
SQLite Dedupe Database Path
The dedupe database path is relative to the working directory where the process starts, not relative to the application code. If you run the service from different directories, you may end up with multiple databases.
Always set EMAIL_CLASSIFIER_DB_PATH to an absolute path when running in production:
export EMAIL_CLASSIFIER_DB_PATH=/data/email_classifier.db
Classification Retries
The classifier retries when needs_action=true but task_description is missing (an invalid state). This means a flaky LLM that sometimes omits task_description will be called multiple times. If this causes issues (e.g., rate limiting), set LLM_MAX_RETRIES=1.
HTML Body Processing
The service strips disclaimers and cleans HTML from email bodies before sending to the LLM. This is aggressive and may also remove some legitimate HTML content in some email clients. There is currently no way to disable this cleaning step.
No Authentication
The service has no built-in authentication. It is designed to run behind a reverse proxy (nginx, Caddy, etc.) that handles auth. Do not expose port 7999 directly to the internet.
Dedupe Fingerprinting Limitations
The fingerprint-based dedupe fallback is heuristic, not exact. It uses a normalized subject + body preview + first 2000 characters of the cleaned body. Minor edits to an email (rewording, adding a signature line) can produce a different fingerprint and cause the email to be treated as new rather than duplicate. Conversely, very similar emails from different senders may collide.
For strict deduplication, rely on message_id (exact Outlook message ID match) or conversation_id (thread grouping) rather than fingerprint.