473 lines
12 KiB
Markdown
473 lines
12 KiB
Markdown
# LinkedIn Content Generation Service
|
|
|
|
A comprehensive FastAPI-based service for generating professional LinkedIn content using AI. This service has been migrated from the legacy Streamlit implementation to provide robust API endpoints for LinkedIn content creation.
|
|
|
|
## Overview
|
|
|
|
The LinkedIn Content Generation Service provides AI-powered tools for creating various types of LinkedIn content:
|
|
|
|
- **Posts**: Short-form professional posts with research-backed content
|
|
- **Articles**: Long-form articles with SEO optimization
|
|
- **Carousels**: Multi-slide visual content
|
|
- **Video Scripts**: Structured scripts for LinkedIn videos
|
|
- **Comment Responses**: Professional responses to LinkedIn comments
|
|
|
|
## Features
|
|
|
|
### 🚀 Core Capabilities
|
|
|
|
- **Multi-format Content Generation**: Posts, articles, carousels, video scripts, and comment responses
|
|
- **Research Integration**: Automated research using multiple search engines (Metaphor, Google, Tavily)
|
|
- **AI-Powered Optimization**: Industry-specific content optimization using Gemini AI
|
|
- **SEO Enhancement**: Built-in SEO optimization for LinkedIn articles
|
|
- **Engagement Prediction**: AI-based engagement metrics prediction
|
|
- **Professional Tone Control**: Multiple tone options (professional, conversational, authoritative, etc.)
|
|
|
|
### 🛠 Technical Features
|
|
|
|
- **FastAPI Integration**: RESTful API with automatic documentation
|
|
- **Comprehensive Error Handling**: Robust exception handling and logging
|
|
- **Database Monitoring**: Request logging and performance monitoring
|
|
- **Async/Await Support**: Non-blocking operations for better performance
|
|
- **Pydantic Validation**: Strong request/response validation
|
|
- **Structured JSON Responses**: Consistent API response format
|
|
|
|
## API Endpoints
|
|
|
|
### Base URL
|
|
```
|
|
/api/linkedin
|
|
```
|
|
|
|
### Available Endpoints
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/health` | GET | Health check for service status |
|
|
| `/generate-post` | POST | Generate LinkedIn posts |
|
|
| `/generate-article` | POST | Generate LinkedIn articles |
|
|
| `/generate-carousel` | POST | Generate LinkedIn carousels |
|
|
| `/generate-video-script` | POST | Generate video scripts |
|
|
| `/generate-comment-response` | POST | Generate comment responses |
|
|
| `/content-types` | GET | Get available content types |
|
|
| `/usage-stats` | GET | Get usage statistics |
|
|
|
|
## Quick Start
|
|
|
|
### 1. Prerequisites
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Set environment variables
|
|
export GEMINI_API_KEY="your_gemini_api_key"
|
|
export DATABASE_URL="sqlite:///./alwrity.db"
|
|
```
|
|
|
|
### 2. Start the Service
|
|
|
|
```bash
|
|
# Start FastAPI server
|
|
uvicorn app:app --host 0.0.0.0 --port 8000 --reload
|
|
```
|
|
|
|
### 3. Access Documentation
|
|
|
|
- **Interactive API Docs**: http://localhost:8000/docs
|
|
- **Alternative Docs**: http://localhost:8000/redoc
|
|
|
|
## Usage Examples
|
|
|
|
### Generate a LinkedIn Post
|
|
|
|
```python
|
|
import requests
|
|
|
|
# Request payload
|
|
payload = {
|
|
"topic": "Artificial Intelligence in Healthcare",
|
|
"industry": "Healthcare",
|
|
"post_type": "thought_leadership",
|
|
"tone": "professional",
|
|
"target_audience": "Healthcare executives",
|
|
"key_points": ["AI diagnostics", "Patient outcomes", "Cost reduction"],
|
|
"include_hashtags": True,
|
|
"include_call_to_action": True,
|
|
"research_enabled": True,
|
|
"max_length": 2000
|
|
}
|
|
|
|
# Make request
|
|
response = requests.post(
|
|
"http://localhost:8000/api/linkedin/generate-post",
|
|
json=payload
|
|
)
|
|
|
|
# Process response
|
|
if response.status_code == 200:
|
|
data = response.json()
|
|
print(f"Generated post: {data['data']['content']}")
|
|
print(f"Hashtags: {[h['hashtag'] for h in data['data']['hashtags']]}")
|
|
else:
|
|
print(f"Error: {response.status_code}")
|
|
```
|
|
|
|
### Generate a LinkedIn Article
|
|
|
|
```python
|
|
payload = {
|
|
"topic": "Digital Transformation in Manufacturing",
|
|
"industry": "Manufacturing",
|
|
"tone": "professional",
|
|
"target_audience": "Manufacturing leaders",
|
|
"key_sections": ["Current challenges", "Technology solutions", "Implementation strategies"],
|
|
"include_images": True,
|
|
"seo_optimization": True,
|
|
"research_enabled": True,
|
|
"word_count": 1500
|
|
}
|
|
|
|
response = requests.post(
|
|
"http://localhost:8000/api/linkedin/generate-article",
|
|
json=payload
|
|
)
|
|
```
|
|
|
|
### Generate a LinkedIn Carousel
|
|
|
|
```python
|
|
payload = {
|
|
"topic": "5 Ways to Improve Team Productivity",
|
|
"industry": "Business Management",
|
|
"slide_count": 8,
|
|
"tone": "professional",
|
|
"target_audience": "Team leaders and managers",
|
|
"key_takeaways": ["Clear communication", "Goal setting", "Tool optimization"],
|
|
"include_cover_slide": True,
|
|
"include_cta_slide": True,
|
|
"visual_style": "modern"
|
|
}
|
|
|
|
response = requests.post(
|
|
"http://localhost:8000/api/linkedin/generate-carousel",
|
|
json=payload
|
|
)
|
|
```
|
|
|
|
## Request/Response Models
|
|
|
|
### LinkedIn Post Request
|
|
|
|
```json
|
|
{
|
|
"topic": "string",
|
|
"industry": "string",
|
|
"post_type": "professional|thought_leadership|industry_news|personal_story|company_update|poll",
|
|
"tone": "professional|conversational|authoritative|inspirational|educational|friendly",
|
|
"target_audience": "string (optional)",
|
|
"key_points": ["string"] (optional),
|
|
"include_hashtags": true,
|
|
"include_call_to_action": true,
|
|
"research_enabled": true,
|
|
"search_engine": "metaphor|google|tavily",
|
|
"max_length": 3000
|
|
}
|
|
```
|
|
|
|
### LinkedIn Post Response
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"content": "Generated post content...",
|
|
"character_count": 1250,
|
|
"hashtags": [
|
|
{
|
|
"hashtag": "#AIinHealthcare",
|
|
"category": "industry",
|
|
"popularity_score": 0.9
|
|
}
|
|
],
|
|
"call_to_action": "What's your experience with AI in healthcare?",
|
|
"engagement_prediction": {
|
|
"estimated_likes": 120,
|
|
"estimated_comments": 15,
|
|
"estimated_shares": 8
|
|
}
|
|
},
|
|
"research_sources": [
|
|
{
|
|
"title": "AI in Healthcare: Current Trends",
|
|
"url": "https://example.com/ai-healthcare",
|
|
"content": "Summary of AI healthcare trends...",
|
|
"relevance_score": 0.95
|
|
}
|
|
],
|
|
"generation_metadata": {
|
|
"generation_time": 3.2,
|
|
"timestamp": "2025-01-27T10:00:00Z",
|
|
"model_used": "gemini-2.0-flash-001"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Description | Required | Default |
|
|
|----------|-------------|----------|---------|
|
|
| `GEMINI_API_KEY` | Google Gemini API key | Yes | - |
|
|
| `DATABASE_URL` | Database connection string | No | `sqlite:///./alwrity.db` |
|
|
| `LOG_LEVEL` | Logging level | No | `INFO` |
|
|
|
|
### Content Generation Settings
|
|
|
|
The service supports various customization options:
|
|
|
|
#### Post Types
|
|
- `professional`: Standard professional posts
|
|
- `thought_leadership`: Industry insights and expertise
|
|
- `industry_news`: News and updates
|
|
- `personal_story`: Personal experiences and stories
|
|
- `company_update`: Company news and announcements
|
|
- `poll`: Interactive polls
|
|
|
|
#### Tone Options
|
|
- `professional`: Formal business tone
|
|
- `conversational`: Casual but professional
|
|
- `authoritative`: Expert and confident
|
|
- `inspirational`: Motivational and uplifting
|
|
- `educational`: Informative and teaching
|
|
- `friendly`: Warm and approachable
|
|
|
|
#### Search Engines
|
|
- `metaphor`: Metaphor AI search (recommended)
|
|
- `google`: Google Search API
|
|
- `tavily`: Tavily AI search
|
|
|
|
## Architecture
|
|
|
|
### Service Structure
|
|
|
|
```
|
|
backend/
|
|
├── models/
|
|
│ └── linkedin_models.py # Pydantic models for requests/responses
|
|
├── services/
|
|
│ └── linkedin_service.py # Core business logic
|
|
├── routers/
|
|
│ └── linkedin.py # FastAPI route handlers
|
|
├── middleware/
|
|
│ └── monitoring_middleware.py # Request monitoring
|
|
└── docs/
|
|
└── LINKEDIN_CONTENT_GENERATION.md
|
|
```
|
|
|
|
### Key Components
|
|
|
|
#### LinkedInContentService
|
|
The core service class that handles all content generation logic:
|
|
|
|
- **Content Generation**: AI-powered content creation
|
|
- **Research Integration**: Multi-source research capabilities
|
|
- **Error Handling**: Comprehensive exception management
|
|
- **Logging**: Detailed operation logging
|
|
|
|
#### Request Models
|
|
Pydantic models for strong typing and validation:
|
|
|
|
- `LinkedInPostRequest`
|
|
- `LinkedInArticleRequest`
|
|
- `LinkedInCarouselRequest`
|
|
- `LinkedInVideoScriptRequest`
|
|
- `LinkedInCommentResponseRequest`
|
|
|
|
#### Response Models
|
|
Structured response models with metadata:
|
|
|
|
- `LinkedInPostResponse`
|
|
- `LinkedInArticleResponse`
|
|
- `LinkedInCarouselResponse`
|
|
- `LinkedInVideoScriptResponse`
|
|
- `LinkedInCommentResponseResult`
|
|
|
|
## Performance Considerations
|
|
|
|
### Response Times
|
|
- **Posts**: 3-8 seconds (with research)
|
|
- **Articles**: 15-45 seconds (depending on length)
|
|
- **Carousels**: 5-15 seconds
|
|
- **Video Scripts**: 3-10 seconds
|
|
- **Comment Responses**: 1-3 seconds
|
|
|
|
### Rate Limiting
|
|
The service respects API rate limits:
|
|
- Gemini API: Built-in retry logic with exponential backoff
|
|
- Research APIs: Configurable rate limiting
|
|
|
|
### Caching
|
|
- Research results caching (planned)
|
|
- Response caching for similar requests (planned)
|
|
|
|
## Error Handling
|
|
|
|
### Common Error Scenarios
|
|
|
|
#### 422 Validation Error
|
|
```json
|
|
{
|
|
"detail": [
|
|
{
|
|
"loc": ["body", "topic"],
|
|
"msg": "ensure this value has at least 3 characters",
|
|
"type": "value_error.any_str.min_length"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### 500 Internal Server Error
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Content generation failed: API key not configured",
|
|
"generation_metadata": {
|
|
"service_version": "1.0.0",
|
|
"timestamp": "2025-01-27T10:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Error Recovery
|
|
- Automatic retry logic for transient failures
|
|
- Graceful fallback for content generation
|
|
- Detailed error logging for debugging
|
|
|
|
## Monitoring and Logging
|
|
|
|
### Request Monitoring
|
|
All API requests are logged with:
|
|
- Request path and method
|
|
- Response time and status code
|
|
- User information (if available)
|
|
- Request/response sizes
|
|
|
|
### Performance Metrics
|
|
- Generation time tracking
|
|
- Success/failure rates
|
|
- Popular content types
|
|
- Error frequency analysis
|
|
|
|
### Health Checks
|
|
```bash
|
|
curl http://localhost:8000/api/linkedin/health
|
|
```
|
|
|
|
## Migration from Streamlit
|
|
|
|
### Key Changes
|
|
|
|
1. **Architecture**: Streamlit UI → FastAPI REST API
|
|
2. **Dependencies**: Integrated with existing backend services
|
|
3. **Error Handling**: Enhanced exception handling and logging
|
|
4. **Monitoring**: Database-backed request monitoring
|
|
5. **Validation**: Strong request/response validation
|
|
6. **Documentation**: Automatic API documentation
|
|
|
|
### Compatibility
|
|
- All original functionality preserved
|
|
- Enhanced features and capabilities
|
|
- Better integration with existing systems
|
|
- Improved performance and scalability
|
|
|
|
## Testing
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Structure validation
|
|
python3 validate_linkedin_structure.py
|
|
|
|
# Full functionality tests (requires dependencies)
|
|
python3 test_linkedin_endpoints.py
|
|
```
|
|
|
|
### Test Coverage
|
|
- ✅ Post generation
|
|
- ✅ Article generation
|
|
- ✅ Carousel generation
|
|
- ✅ Video script generation
|
|
- ✅ Comment response generation
|
|
- ✅ Error handling
|
|
- ✅ Structure validation
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### 1. Import Errors
|
|
```bash
|
|
ModuleNotFoundError: No module named 'pydantic'
|
|
```
|
|
**Solution**: Install dependencies
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
#### 2. API Key Issues
|
|
```bash
|
|
Error: GEMINI_API_KEY environment variable is not set
|
|
```
|
|
**Solution**: Set the environment variable
|
|
```bash
|
|
export GEMINI_API_KEY="your_api_key_here"
|
|
```
|
|
|
|
#### 3. Database Connection Issues
|
|
```bash
|
|
Error creating database session
|
|
```
|
|
**Solution**: Check database configuration and permissions
|
|
|
|
#### 4. Generation Timeouts
|
|
**Solution**: Increase timeout settings or reduce content complexity
|
|
|
|
### Debug Mode
|
|
Enable debug logging:
|
|
```bash
|
|
export LOG_LEVEL=DEBUG
|
|
```
|
|
|
|
## Future Enhancements
|
|
|
|
### Planned Features
|
|
- [ ] Real search engine integration (Metaphor, Google, Tavily)
|
|
- [ ] Content scheduling and calendar integration
|
|
- [ ] A/B testing capabilities
|
|
- [ ] Advanced analytics and reporting
|
|
- [ ] Multi-language support
|
|
- [ ] Custom templates and brand voice
|
|
- [ ] LinkedIn API integration for direct posting
|
|
- [ ] Content performance tracking
|
|
|
|
### Performance Improvements
|
|
- [ ] Response caching
|
|
- [ ] Parallel processing for multiple requests
|
|
- [ ] Background job processing
|
|
- [ ] CDN integration for static assets
|
|
|
|
## Support
|
|
|
|
For issues and questions:
|
|
|
|
1. Check the [troubleshooting section](#troubleshooting)
|
|
2. Review the API documentation at `/docs`
|
|
3. Check the logs for detailed error information
|
|
4. Validate your request format against the examples
|
|
|
|
## License
|
|
|
|
This LinkedIn Content Generation Service is part of the ALwrity platform and follows the same licensing terms. |