notid/email-organizer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Makes ai rule generation content work good.

Browse Source
This commit is contained in:
Bryce
2025-08-10 21:21:02 -07:00
parent 47a63d2eab
commit 0dac428217
12 changed files with 2129 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

353
docs/implementation/ai-configuration-guide.md Normal file
View File

@@ -0,0 +1,353 @@
# 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.

246
docs/implementation/ai-generated-rules-implementation.md Normal file
View File

@@ -0,0 +1,246 @@
# AI-Generated Rules Implementation Documentation
## Overview
This document provides a comprehensive overview of the AI-generated rules feature implementation in the Email Organizer application. The feature enables users to automatically generate email organization rules using artificial intelligence, significantly reducing the manual effort required for rule creation.
## Architecture
### System Components
#### 1. AI Service Layer (`app/ai_service.py`)
- **Purpose**: Central hub for all AI operations
- **Key Features**:
- OpenAI-compatible API integration
- Prompt engineering for rule generation
- Rule quality assessment algorithms
- Error handling and fallback mechanisms
- Caching integration
#### 2. Database Schema (`app/models.py`)
- **New Model**: `AIRuleCache`
- Stores AI-generated rules for performance optimization
- Implements TTL-based expiration
- User-specific caching with unique keys
- Metadata storage for quality scores and generation info
#### 3. API Endpoints (`app/routes/folders.py`)
- **POST `/api/folders/generate-rule`**: Generate single or multiple AI rules
- **POST `/api/folders/assess-rule`**: Assess rule quality
- **Features**:
- Caching integration
- Fallback rule generation
- HTML response format for seamless UI integration
#### 4. UI Components
- **Modal Updates**: Enhanced folder creation modal with AI controls
- **Result Display**: Dynamic rule display with quality indicators
- **User Interactions**: Copy, use, and regenerate functionality
## Implementation Details
### AI Service Integration
#### Configuration
The AI service is configured through environment variables:
```bash
AI_SERVICE_URL=https://api.openai.com/v1
AI_SERVICE_API_KEY=your-api-key
AI_MODEL=gpt-3.5-turbo
AI_TIMEOUT=30
AI_MAX_RETRIES=3
AI_CACHE_TTL=3600
```
#### Rule Generation
The service supports two modes:
1. **Single Rule Generation**: Creates one optimized rule based on folder context
2. **Multiple Rule Options**: Generates 5 different rule variations for user selection
#### Quality Assessment
Rules are evaluated on:
- Specificity (20 points)
- Action-orientation (15 points)
- Length optimization (20 points)
- Folder relevance (15 points)
- Grammar and structure (10 points)
- Pattern matching (10 points)
### Caching Strategy
#### Cache Key Generation
```python
cache_key = hashlib.md5(f"{folder_name}:{folder_type}:{rule_type}").hexdigest()
```
#### Cache Management
- TTL-based expiration (default: 1 hour)
- Automatic cleanup of expired entries
- User-specific isolation
- Performance optimization for repeated requests
### Error Handling
#### Fallback Mechanisms
1. **Primary Fallback**: Default rule templates based on folder type
2. **Secondary Fallback**: Cached responses when available
3. **Graceful Degradation**: Manual entry option always available
#### Error Categories
- Network errors (connection timeouts, DNS failures)
- Authentication errors (invalid API keys, rate limits)
- Service errors (AI service unavailability, timeouts)
## User Interface
### Modal Enhancements
The folder creation modal now includes:
- **AI Generation Buttons**: Single rule and multiple options
- **Loading States**: Visual feedback during AI processing
- **Result Display**: Dynamic content with quality indicators
- **Interactive Elements**: Copy, use, and regenerate functionality
### Accessibility Features
- **ARIA Labels**: Proper labeling for screen readers
- **Keyboard Navigation**: Full keyboard support
- **Screen Reader Announcements**: Status updates for actions
- **Color Contrast**: WCAG-compliant design
### Quality Indicators
- **Visual Badges**: Color-coded quality scores (green/yellow/red)
- **Percentage Display**: 0-100% quality score
- **Feedback Text**: Explanations of quality assessment
- **Grade System**: Excellent/Good/Fair/Poor ratings
## Testing Strategy
### Unit Tests (`tests/unit/test_ai_service.py`)
- AI service functionality testing
- Rule quality assessment validation
- Prompt generation testing
- Error handling verification
### Integration Tests (`tests/integration/test_ai_rule_endpoints.py`)
- API endpoint testing
- Database integration
- Caching functionality
- Authentication and authorization
### Functional Tests (`tests/functional/test_ai_rule_user_flow.py`)
- Complete user journey testing
- Modal interaction testing
- Error scenario testing
- Accessibility compliance verification
## Performance Considerations
### Optimization Strategies
1. **Caching**: Reduces API calls for repeated requests
2. **Connection Pooling**: Efficient HTTP connection management
3. **Rate Limiting**: Prevents API abuse and service overload
4. **Timeout Management**: Configurable timeouts for reliability
### Response Time Targets
- Single rule generation: < 3 seconds
- Multiple rule generation: < 5 seconds
- Cache retrieval: < 0.5 seconds
- Quality assessment: < 1 second
## Security Considerations
### Data Protection
- Input sanitization for all user inputs
- Output validation for AI responses
- Secure API key storage
- No sensitive data logging
### Access Control
- User-specific rule generation
- Authentication required for all endpoints
- Rate limiting per user
- Audit logging for access attempts
## Deployment Considerations
### Environment Setup
1. **AI Service Configuration**: Set up API credentials and endpoints
2. **Database Migration**: Run migrations for new cache table
3. **Feature Flags**: Enable gradual rollout if needed
4. **Monitoring**: Set up performance and error monitoring
### Production Deployment
1. **Security Hardening**: Configure API key management
2. **Performance Tuning**: Optimize caching and connection settings
3. **Load Testing**: Validate under expected load conditions
4. **Backup Strategy**: Ensure data backup and recovery procedures
## Monitoring and Observability
### Metrics to Track
- AI service request success rate
- Response time percentiles
- Cache hit rates
- User adoption rates
- Error rates by category
### Alerting
- Critical: AI service unavailability
- Warning: High error rates, performance degradation
- Info: Usage patterns, feature adoption
## Future Enhancements
### Phase 1 (Current Implementation)
- ✅ Basic AI rule generation
- ✅ Single and multiple rule options
- ✅ Quality assessment system
- ✅ Comprehensive error handling
### Phase 2 (Planned)
- Advanced prompt engineering techniques
- User preference learning
- Rule optimization and refinement
- Integration with existing rule engine
### Phase 3 (Future Vision)
- Multi-language support
- Advanced AI model integration
- Rule sharing and collaboration
- Analytics dashboard
## Troubleshooting
### Common Issues
#### AI Service Unavailable
- **Symptoms**: Rule generation fails consistently
- **Solution**: Verify API credentials and network connectivity
- **Fallback**: System automatically uses default rules
#### Cache Issues
- **Symptoms**: Rules not updating or showing stale data
- **Solution**: Clear cache or wait for expiration
- **Monitoring**: Check cache hit rates and expiration times
#### Performance Issues
- **Symptoms**: Slow response times
- **Solution**: Check AI service status and network latency
- **Optimization**: Review caching strategy and connection settings
### Debug Commands
```bash
# Check AI service connectivity
curl -H "Authorization: Bearer $AI_API_KEY" $AI_SERVICE_URL/models
# Monitor cache performance
SELECT COUNT(*) FROM ai_rule_cache WHERE is_active = true AND expires_at > NOW();
# Check error rates
SELECT COUNT(*) FROM ai_rule_cache WHERE rule_metadata->>'error' IS NOT NULL;
```
## Conclusion
The AI-generated rules implementation provides a robust, user-friendly feature that significantly enhances the Email Organizer application's value proposition. By following the structured approach outlined in this documentation, the development team can ensure reliable operation, maintainable code, and excellent user experience.
The feature successfully addresses all user stories from the requirements document while maintaining system reliability, performance, and security standards. The comprehensive testing strategy ensures high-quality code and smooth user interactions.