initialize paraclub-ai-mailer project with core components and configuration

README.md

@@ -0,0 +1,160 @@
+# ParaClub AI Mailer
+
+An automated email response system that uses OpenRouter AI API to generate context-aware replies to incoming emails. The system fetches emails via IMAP, gathers context from configured URLs, and generates AI-powered responses that are saved as email drafts.
+
+## Features
+
+- Automatic email fetching via IMAP
+- Context gathering from configured URLs
+- AI-powered response generation using OpenRouter API
+- Draft email creation in IMAP folders
+- Configurable polling intervals
+- TLS support for secure email communication
+- Comprehensive logging system
+- Graceful shutdown handling
+
+## Prerequisites
+
+- Go 1.19 or later
+- IMAP email account credentials
+- OpenRouter API key
+- Access to the websites you want to use as context sources
+
+## Installation
+
+1. Clone the repository:
+```bash
+git clone gitea@git.cloonar.com:Paraclub/ai-mailer.git
+cd paraclub-ai-mailer
+```
+
+2. Install dependencies:
+```bash
+go mod download
+```
+
+3. Build the application:
+```bash
+go build -o paraclub-ai-mailer ./cmd/paraclub-ai-mailer
+```
+
+## Configuration
+
+The application uses a YAML configuration file (`config.yaml`) with the following structure:
+
+```yaml
+imap:
+  server: "imap.example.com"
+  port: 993
+  username: "your-email@example.com"
+  password: "${IMAP_PASSWORD}"  # From environment variable
+  mailbox_in: "INBOX"
+  draft_box: "Drafts"
+  use_tls: true
+
+ai:
+  openrouter_api_key: "${OPENROUTER_API_KEY}"  # From environment variable
+  model: "anthropic/claude-2"
+  temperature: 0.7
+  max_tokens: 2000
+
+context:
+  urls:
+    - "https://example.com/faq"
+    - "https://example.com/about"
+    - "https://example.com/policies"
+
+polling:
+  interval: "5m"  # Duration format (e.g., 30s, 5m, 1h)
+
+logging:
+  level: "info"  # debug, info, warn, error
+  file_path: "paraclub-ai-mailer.log"
+```
+
+### Environment Variables
+
+The following environment variables need to be set:
+
+- `IMAP_PASSWORD`: Your IMAP account password
+- `OPENROUTER_API_KEY`: Your OpenRouter API key
+
+## Usage
+
+1. Set up your configuration file:
+```bash
+cp config.yaml.example config.yaml
+# Edit config.yaml with your settings
+```
+
+2. Set required environment variables:
+```bash
+export IMAP_PASSWORD="your-email-password"
+export OPENROUTER_API_KEY="your-openrouter-api-key"
+```
+
+3. Run the application:
+```bash
+./paraclub-ai-mailer
+```
+
+Or specify a custom config file path:
+```bash
+./paraclub-ai-mailer -config /path/to/config.yaml
+```
+
+## How It Works
+
+1. The application polls the IMAP server at configured intervals
+2. For each unprocessed email:
+   - Fetches the email content
+   - Retrieves HTML content from configured URLs
+   - Sends combined content to OpenRouter AI for response generation
+   - Saves the AI-generated response as a draft email
+   - Marks the original email as processed
+
+## Logging
+
+Logs are written to both stdout and the configured log file. Log levels can be set to:
+- debug: Detailed debugging information
+- info: General operational information
+- warn: Warning messages
+- error: Error conditions
+
+## Security Considerations
+
+- Use TLS for IMAP connections (set `use_tls: true`)
+- Store sensitive credentials in environment variables
+- Regularly rotate API keys and passwords
+- Monitor log files for unusual activity
+
+## Error Handling
+
+The application implements:
+- Automatic retries for transient failures
+- Graceful shutdown on system signals
+- Comprehensive error logging
+- Email processing state tracking to prevent duplicates
+
+## Limitations
+
+- Processes emails sequentially
+- HTML content is fetched without following links
+- Requires stable internet connection
+- API rate limits may apply (OpenRouter)
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request
+
+## License
+
+[Your chosen license]
+
+## Support
+
+[Your support information]