353 lines
8.7 KiB
Markdown
353 lines
8.7 KiB
Markdown
# AI-Generated Rules Configuration Guide
|
|
|
|
This guide provides step-by-step instructions for configuring and deploying the AI-generated rules feature in the Email Organizer application.
|
|
|
|
## Prerequisites
|
|
|
|
### System Requirements
|
|
- Python 3.8+
|
|
- Flask application with existing user authentication
|
|
- PostgreSQL database (SQLite for development)
|
|
- Internet connectivity for AI service access
|
|
|
|
### AI Service Requirements
|
|
- OpenAI-compatible API endpoint
|
|
- Valid API key with sufficient quota
|
|
- Model access (GPT-3.5-turbo recommended)
|
|
|
|
## Configuration Steps
|
|
|
|
### 1. Environment Variables
|
|
|
|
Add the following environment variables to your `.env` file:
|
|
|
|
```bash
|
|
# AI Service Configuration
|
|
AI_SERVICE_URL=https://api.openai.com/v1
|
|
AI_SERVICE_API_KEY=your-openai-api-key-here
|
|
AI_MODEL=gpt-3.5-turbo
|
|
AI_TIMEOUT=30
|
|
AI_MAX_RETRIES=3
|
|
AI_CACHE_TTL=3600
|
|
|
|
# Feature Configuration
|
|
AI_FEATURE_ENABLED=true
|
|
AI_CACHE_ENABLED=true
|
|
AI_FALLBACK_ENABLED=true
|
|
```
|
|
|
|
### 2. Database Migration
|
|
|
|
Create and run the database migration for the AI rule cache table:
|
|
|
|
```bash
|
|
# Generate migration
|
|
flask db migrate -m "Add AI rule cache table"
|
|
|
|
# Apply migration
|
|
flask db upgrade
|
|
```
|
|
|
|
### 3. Application Configuration
|
|
|
|
Update your `config.py` file to include AI service configuration:
|
|
|
|
```python
|
|
class Config:
|
|
# Existing configuration...
|
|
|
|
# AI Service Configuration
|
|
AI_SERVICE_URL = os.environ.get('AI_SERVICE_URL')
|
|
AI_SERVICE_API_KEY = os.environ.get('AI_SERVICE_API_KEY')
|
|
AI_MODEL = os.environ.get('AI_MODEL', 'gpt-3.5-turbo')
|
|
AI_TIMEOUT = int(os.environ.get('AI_TIMEOUT', 30))
|
|
AI_MAX_RETRIES = int(os.environ.get('AI_MAX_RETRIES', 3))
|
|
AI_CACHE_TTL = int(os.environ.get('AI_CACHE_TTL', 3600))
|
|
|
|
# Feature Flags
|
|
AI_FEATURE_ENABLED = os.environ.get('AI_FEATURE_ENABLED', 'true').lower() == 'true'
|
|
AI_CACHE_ENABLED = os.environ.get('AI_CACHE_ENABLED', 'true').lower() == 'true'
|
|
AI_FALLBACK_ENABLED = os.environ.get('AI_FALLBACK_ENABLED', 'true').lower() == 'true'
|
|
```
|
|
|
|
### 4. Service Integration
|
|
|
|
The AI service is automatically integrated into the existing folder creation workflow. No additional configuration is required for the basic functionality.
|
|
|
|
## Testing the Configuration
|
|
|
|
### 1. Unit Testing
|
|
|
|
Run the AI service unit tests:
|
|
|
|
```bash
|
|
python -m pytest tests/unit/test_ai_service.py -v
|
|
```
|
|
|
|
### 2. Integration Testing
|
|
|
|
Test the API endpoints:
|
|
|
|
```bash
|
|
python -m pytest tests/integration/test_ai_rule_endpoints.py -v
|
|
```
|
|
|
|
### 3. Functional Testing
|
|
|
|
Test the complete user flow:
|
|
|
|
```bash
|
|
python -m pytest tests/functional/test_ai_rule_user_flow.py -v
|
|
```
|
|
|
|
### 4. Manual Testing
|
|
|
|
1. Start the application:
|
|
```bash
|
|
flask run --port=5000
|
|
```
|
|
|
|
2. Open your browser and navigate to the application
|
|
3. Click "Add New Folder"
|
|
4. Test the AI rule generation buttons:
|
|
- "Generate Rule" - creates a single rule
|
|
- "Multiple Options" - creates multiple rule choices
|
|
5. Verify that rules appear with quality scores
|
|
6. Test the "Use This Rule" and "Copy" functionality
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### 1. AI Service Connection Errors
|
|
|
|
**Symptoms**: Rule generation fails with "No response from AI service"
|
|
|
|
**Solutions**:
|
|
- Verify API key is valid and has sufficient quota
|
|
- Check network connectivity to AI service endpoint
|
|
- Confirm AI service URL is correct
|
|
- Check service status: [OpenAI Status](https://status.openai.com/)
|
|
|
|
**Debug Commands**:
|
|
```bash
|
|
# Test API connectivity
|
|
curl -H "Authorization: Bearer $AI_SERVICE_API_KEY" $AI_SERVICE_URL/models
|
|
|
|
# Check API key format
|
|
echo $AI_SERVICE_API_KEY | wc -c # Should be 51 characters for OpenAI
|
|
```
|
|
|
|
#### 2. Rate Limiting Issues
|
|
|
|
**Symptoms**: "Rate limit exceeded" errors
|
|
|
|
**Solutions**:
|
|
- Monitor API usage and quotas
|
|
- Implement request throttling if needed
|
|
- Consider upgrading to a higher-tier API plan
|
|
- Enable caching to reduce API calls
|
|
|
|
**Monitoring**:
|
|
```sql
|
|
-- Check cache hit rate
|
|
SELECT
|
|
COUNT(*) as total_requests,
|
|
COUNT(CASE WHEN cache_key IS NOT NULL THEN 1 END) as cached_requests,
|
|
ROUND(COUNT(CASE WHEN cache_key IS NOT NULL THEN 1 END) * 100.0 / COUNT(*), 2) as cache_hit_rate
|
|
FROM ai_rule_cache
|
|
WHERE created_at > NOW() - INTERVAL '1 day';
|
|
```
|
|
|
|
#### 3. Database Issues
|
|
|
|
**Symptoms**: Cache not working or database errors
|
|
|
|
**Solutions**:
|
|
- Verify database permissions
|
|
- Check table creation
|
|
- Monitor cache expiration
|
|
- Clear cache if needed
|
|
|
|
**Debug Commands**:
|
|
```sql
|
|
-- Check cache table status
|
|
SELECT COUNT(*) as total_cache_entries,
|
|
COUNT(CASE WHEN expires_at > NOW() THEN 1 END) as active_cache_entries,
|
|
COUNT(CASE WHEN expires_at <= NOW() THEN 1 END) as expired_cache_entries
|
|
FROM ai_rule_cache;
|
|
|
|
-- Clear expired cache entries
|
|
DELETE FROM ai_rule_cache WHERE expires_at <= NOW();
|
|
```
|
|
|
|
#### 4. UI Issues
|
|
|
|
**Symptoms**: AI controls not appearing or not working
|
|
|
|
**Solutions**:
|
|
- Verify feature flag is enabled
|
|
- Check template rendering
|
|
- Test JavaScript functionality
|
|
- Verify HTMX configuration
|
|
|
|
**Debug Steps**:
|
|
1. Open browser developer tools
|
|
2. Check for JavaScript errors in console
|
|
3. Verify HTMX requests are being made
|
|
4. Check network responses for AI endpoints
|
|
|
|
### Performance Optimization
|
|
|
|
#### 1. Caching Optimization
|
|
|
|
```sql
|
|
-- Create indexes for better cache performance
|
|
CREATE INDEX idx_ai_rule_cache_user_folder ON ai_rule_cache(user_id, folder_name, folder_type);
|
|
CREATE INDEX idx_ai_rule_cache_expires ON ai_rule_cache(expires_at);
|
|
CREATE INDEX idx_ai_rule_cache_key ON ai_rule_cache(cache_key);
|
|
```
|
|
|
|
#### 2. Connection Pooling
|
|
|
|
Configure connection pooling in your database settings for better performance under load.
|
|
|
|
#### 3. Rate Limiting
|
|
|
|
Implement rate limiting to prevent abuse:
|
|
|
|
```python
|
|
# Add to your Flask app configuration
|
|
RATELIMIT_STORAGE_URL = 'memory://'
|
|
RATELIMIT_DEFAULT = "100 per hour"
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
### 1. API Key Security
|
|
|
|
- Store API keys securely using environment variables
|
|
- Rotate API keys regularly
|
|
- Monitor API usage for suspicious activity
|
|
- Use least privilege principle for API access
|
|
|
|
### 2. Input Validation
|
|
|
|
The system includes comprehensive input validation:
|
|
- Folder name validation (length, characters)
|
|
- Rule text validation (format, length)
|
|
- Folder type validation (enum values)
|
|
|
|
### 3. Output Sanitization
|
|
|
|
AI responses are sanitized before storage:
|
|
- HTML tag removal
|
|
- Script injection prevention
|
|
- Content length validation
|
|
|
|
## Monitoring and Maintenance
|
|
|
|
### 1. Health Checks
|
|
|
|
Set up regular health checks:
|
|
```bash
|
|
# Monitor AI service availability
|
|
curl -f $AI_SERVICE_URL/models || echo "AI service unavailable"
|
|
|
|
# Monitor database connectivity
|
|
psql $DATABASE_URL -c "SELECT 1;" || echo "Database unavailable"
|
|
```
|
|
|
|
### 2. Log Monitoring
|
|
|
|
Monitor logs for errors and performance issues:
|
|
```bash
|
|
# Check for AI service errors
|
|
tail -f app.log | grep "AI service"
|
|
|
|
# Monitor performance
|
|
tail -f app.log | grep "generate-rule"
|
|
```
|
|
|
|
### 3. Regular Maintenance
|
|
|
|
- Clean up expired cache entries weekly
|
|
- Monitor API usage and quotas
|
|
- Review error logs regularly
|
|
- Update AI models as new versions become available
|
|
|
|
## Backup and Recovery
|
|
|
|
### 1. Database Backup
|
|
|
|
Include the AI rule cache table in your regular backup strategy:
|
|
```bash
|
|
# Backup command example
|
|
pg_dump $DATABASE_URL > backup_$(date +%Y%m%d).sql
|
|
```
|
|
|
|
### 2. Configuration Backup
|
|
|
|
Backup your environment configuration:
|
|
```bash
|
|
# Copy environment variables
|
|
cp .env .env.backup
|
|
```
|
|
|
|
### 3. Recovery Procedures
|
|
|
|
**Cache Recovery**:
|
|
```sql
|
|
-- Restore from backup if needed
|
|
-- Recreate cache entries from usage patterns
|
|
```
|
|
|
|
**Service Recovery**:
|
|
1. Verify AI service status
|
|
2. Check API credentials
|
|
3. Test rule generation
|
|
4. Monitor for errors
|
|
|
|
## Scaling Considerations
|
|
|
|
### 1. Horizontal Scaling
|
|
|
|
- Use a distributed cache for multi-instance deployments
|
|
- Implement session affinity if needed
|
|
- Consider read replicas for database scaling
|
|
|
|
### 2. Vertical Scaling
|
|
|
|
- Increase memory for caching
|
|
- Optimize database connections
|
|
- Monitor CPU usage for AI processing
|
|
|
|
### 3. Load Testing
|
|
|
|
Test with simulated load:
|
|
```bash
|
|
# Example load testing command
|
|
locust -f locustfile.py --users 50 --spawn-rate 5 --run-time 5m
|
|
```
|
|
|
|
## Support and Resources
|
|
|
|
### Documentation
|
|
- [Implementation Guide](ai-generated-rules-implementation.md)
|
|
- [User Stories](../../user-stories/ai-generated-rules.md)
|
|
- [Design Documentation](../../design/ai-comprehensive-summary.md)
|
|
|
|
### Community Support
|
|
- GitHub Issues: Report bugs and request features
|
|
- Documentation: Contribute improvements
|
|
- Discussions: Share best practices
|
|
|
|
### Professional Support
|
|
For enterprise deployments, consider:
|
|
- AI service provider support
|
|
- Database administration support
|
|
- Security consulting
|
|
|
|
---
|
|
|
|
This configuration guide provides everything needed to successfully deploy and maintain the AI-generated rules feature. For additional questions or issues, please refer to the troubleshooting section or contact the development team. |