Implement Python email agent with multi-model AI support

Adds a complete email-based registration agent for Spielgruppe Pumuckl based on the OpenSpec define-project-scope specifications. Architecture - Channel-agnostic EmailAgent core — no email-specific code in business logic - Pluggable AI provider layer: Anthropic (Claude) and OpenAI (GPT) supported via a shared LLMProvider interface; switch with AI_PROVIDER env var - IMAP polling for inbound emails with thread-tracking via email headers (Message-ID / In-Reply-To / References) - SMTP for outbound replies and admin notifications - File-based JSON storage for conversation state and completed registrations - Admin-editable knowledge-base loaded from markdown files at startup Key files src/config.py — env-var configuration src/providers/base.py — abstract LLMProvider src/providers/anthropic_provider.py — Claude backend src/providers/openai_provider.py — OpenAI backend src/agent/core.py — EmailAgent orchestrator src/agent/prompts.py — system prompt builder (KB + registration state) src/models/registration.py — RegistrationData matching the JSON schema src/models/conversation.py — ConversationState persisted per thread src/channels/email_channel.py — IMAP/SMTP I/O + quoted-text stripping src/storage/json_store.py — conversation & registration persistence src/notifications/notifier.py — admin notification routing by playgroup type main.py — polling entry point requirements.txt — anthropic, openai, python-dotenv, jsonschema .env.example — configuration template https://claude.ai/code/session_01HaUFs7SaLD5SoiuGCY27Tw
2026-02-20 20:17:00 +00:00
parent 4d44d4ee58
commit b82ff27efd
24 changed files with 1728 additions and 0 deletions
@@ -0,0 +1,59 @@
+# ---------------------------------------------------------------
+# Meister-Eder Email Agent — Configuration Template
+# ---------------------------------------------------------------
+# Copy this file to .env and fill in your values.
+# The .env file must NOT be committed to version control.
+# ---------------------------------------------------------------
+
+# ---------------------------------------------------------------
+# AI Provider
+# ---------------------------------------------------------------
+# Choose "anthropic" (Claude) or "openai" (GPT).
+AI_PROVIDER=anthropic
+
+# Optional: override the default model for the chosen provider.
+# Anthropic default: claude-opus-4-6
+# OpenAI default:    gpt-4o
+# AI_MODEL=
+
+# ---------------------------------------------------------------
+# API Keys — set the one matching your AI_PROVIDER
+# ---------------------------------------------------------------
+ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+
+# ---------------------------------------------------------------
+# Email — IMAP (receiving parent messages)
+# ---------------------------------------------------------------
+IMAP_HOST=imap.example.com
+IMAP_PORT=993
+IMAP_USERNAME=anmeldung@example.com
+IMAP_PASSWORD=your-imap-password
+IMAP_USE_SSL=true
+
+# ---------------------------------------------------------------
+# Email — SMTP (sending replies and notifications)
+# ---------------------------------------------------------------
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USE_TLS=true
+
+# ---------------------------------------------------------------
+# Registration email address (displayed as sender to parents)
+# ---------------------------------------------------------------
+REGISTRATION_EMAIL=anmeldung@example.com
+
+# ---------------------------------------------------------------
+# Storage
+# ---------------------------------------------------------------
+# Directory for conversation state and completed registrations.
+DATA_DIR=data
+
+# Path to the knowledge-base markdown files (admin-editable).
+KNOWLEDGE_BASE_DIR=openspec/changes/define-project-scope/content/knowledge-base
+
+# ---------------------------------------------------------------
+# Polling
+# ---------------------------------------------------------------
+# How often (in seconds) to check the inbox for new messages.
+POLL_INTERVAL=60