viral_velocity/README.md

# Viral Velocity - AI-Powered Social Media Image Scorer

🚀 **Viral Velocity** is an AI-powered mobile application that helps users optimize their social media posts by providing intelligent image scoring and enhancement recommendations.

## 🎯 What We Built

We've created a **personalized 4-pillar scoring system** using **OpenAI GPT-4 Vision** that analyzes images for:

1. **Technical Quality** (25% weight) - Sharpness, resolution, noise, dynamic range, color fidelity
2. **Compositional Strength** (25% weight) - Rule of thirds, leading lines, balance, depth, subject isolation  
3. **Psychological Engagement** (30% weight) - Face detection, emotional resonance, color psychology, storytelling
4. **Trend & Zeitgeist** (20% weight) - **Personalized** aesthetic alignment based on user preferences

### 🌟 **Key Feature: Personalization**
The system now supports **user preferences** for personalized scoring:
- **Aesthetic:** Y2K, Maximalist, Minimalist, Vintage, etc.
- **Niche:** Fashion Influencer, Food Blogger, Business Professional, etc.
- **Target Audience:** Gen Z, Millennials, Professionals, etc.
- **Content Type:** Instagram Post, LinkedIn Post, TikTok, etc.
- **Brand Voice:** Playful, Professional, Casual, etc.

## 🛠️ Setup Instructions

### 1. Install Dependencies
```bash
pip install -r requirements.txt
```

### 2. Get OpenAI API Key
1. Go to [OpenAI Platform](https://platform.openai.com/api-keys)
2. Create a new API key
3. Copy the key

### 3. Set Up Environment
Create a `.env` file in the project root:
```bash
OPENAI_API_KEY=your_actual_api_key_here
```

## 🚀 How to Use

### Option 1: Run the API Server
```bash
python api.py
```
The API will be available at `http://localhost:5300`

**Logs will be saved to:**
- `viral_velocity.log` - Main scorer logs

**Available Endpoints:**
- `GET /` - API info
- `POST /score-image` - Score an image with base64 data and optional user preferences
- `GET /health` - Health check
- `GET /scoring-weights` - View current scoring weights
- `GET /available-preferences` - Get all available preference options

### Option 2: Test with Sample Image
1. Place a test image named `test_image.jpg` in the project directory
2. Run the test script:
```bash
python test_scorer.py
```

### Option 3: Test Personalized Scoring
```bash
python test_personalized.py
```
This will test the system with different user preferences and show how personalization affects scores.

### Option 4: Use the Web Frontend
```bash
# Start the API server (serves both API and frontend)
python api.py
```
Then open http://localhost:5300 in your browser for a beautiful web interface!

### Option 5: View Logs in Real-Time
```bash
python view_logs.py
```
This will show you detailed logs of what's happening during the scoring process.

### Option 6: Use the API
```python
import requests
import base64

# Encode image to base64
with open("image.jpg", "rb") as image_file:
    encoded_image = base64.b64encode(image_file.read()).decode()

# Prepare request
request_data = {
    "image": encoded_image,
    "user_preferences": {
        "aesthetic": "Y2K",
        "niche": "Fashion Influencer", 
        "target_audience": "Gen Z",
        "content_type": "Instagram Post",
        "brand_voice": "Playful and Trendy"
    }
}

# Send request
response = requests.post("http://localhost:5300/score-image", json=request_data)
result = response.json()

# Get the final score
print(f"Viral Score: {result['final_score']}/100")

# Get detailed breakdown
print(f"Technical Quality: {result['technical_quality']['score']}/100")
print(f"Compositional Strength: {result['compositional_strength']['score']}/100")
print(f"Psychological Engagement: {result['psychological_engagement']['score']}/100")
print(f"Trend & Zeitgeist: {result['trend_zeitgeist']['score']}/100")
```

### Option 7: Use in Your Code (Direct)
```python
from viral_velocity_scorer import ViralVelocityScorer

# Initialize scorer
scorer = ViralVelocityScorer()

# Analyze an image with personalized preferences
user_preferences = {
    "aesthetic": "Y2K",
    "niche": "Fashion Influencer", 
    "target_audience": "Gen Z",
    "content_type": "Instagram Post",
    "brand_voice": "Playful and Trendy"
}

# Analyze an image
result = scorer.analyze_image_efficient("path/to/your/image.jpg", user_preferences)

# Get the final score
print(f"Viral Score: {result['final_score']}/100")

# Get detailed breakdown
print(f"Technical Quality: {result['technical_quality']['score']}/100")
print(f"Compositional Strength: {result['compositional_strength']['score']}/100")
print(f"Psychological Engagement: {result['psychological_engagement']['score']}/100")
print(f"Trend & Zeitgeist: {result['trend_zeitgeist']['score']}/100")

# Check if preferences were used
print(f"Preferences used: {result['user_preferences_used']}")
```

## 📊 Sample Output

### Generic Scoring (No Preferences)
```json
{
  "final_score": 78.5,
  "technical_quality": {
    "score": 85,
    "weight": 0.25,
    "details": "Image shows good sharpness and color balance..."
  },
  "compositional_strength": {
    "score": 72,
    "weight": 0.25,
    "details": "Subject is well-positioned but could benefit from..."
  },
  "psychological_engagement": {
    "score": 82,
    "weight": 0.30,
    "details": "Strong emotional appeal with engaging facial expressions..."
  },
  "trend_zeitgeist": {
    "score": 75,
    "weight": 0.20,
    "details": "Aligns well with current minimalist aesthetic trends..."
  },
  "recommendations": [
    "Try adjusting the composition to follow the rule of thirds more closely",
    "Consider enhancing the lighting to create more dramatic shadows",
    "The color palette could be more vibrant to increase engagement"
  ],
  "user_preferences_used": null
}
```

### Personalized Scoring (Y2K Fashion Influencer)
```json
{
  "final_score": 85.2,
  "technical_quality": {
    "score": 85,
    "weight": 0.25,
    "details": "Image shows good sharpness and color balance..."
  },
  "compositional_strength": {
    "score": 72,
    "weight": 0.25,
    "details": "Subject is well-positioned but could benefit from..."
  },
  "psychological_engagement": {
    "score": 82,
    "weight": 0.30,
    "details": "Strong emotional appeal with engaging facial expressions..."
  },
  "trend_zeitgeist": {
    "score": 95,
    "weight": 0.20,
    "details": "Perfectly aligns with Y2K aesthetic for fashion content targeting Gen Z..."
  },
  "recommendations": [
    "The Y2K aesthetic is spot-on for your target audience",
    "Consider adding more vibrant, retro color filters to enhance the Y2K vibe",
    "The fashion elements align perfectly with Gen Z preferences"
  ],
  "user_preferences_used": {
    "aesthetic": "Y2K",
    "niche": "Fashion Influencer",
    "target_audience": "Gen Z",
    "content_type": "Instagram Post",
    "brand_voice": "Playful and Trendy"
  }
}
```

## 🎨 How the Scoring Works

### Technical Quality Score (25%)
- **Sharpness & Focus** (0-25 points): Image clarity and focus quality
- **Resolution & Clarity** (0-25 points): Image resolution and overall clarity
- **Image Noise** (0-20 points): Presence of noise and artifacts
- **Dynamic Range** (0-15 points): Balance of highlights and shadows
- **Color Fidelity** (0-15 points): Natural and well-balanced colors

### Compositional Strength Score (25%)
- **Rule of Thirds** (0-25 points): Subject positioning according to compositional rules
- **Leading Lines** (0-20 points): Lines that guide the eye toward the subject
- **Balance & Symmetry** (0-20 points): Visual balance and symmetry
- **Depth & Framing** (0-20 points): Layering and framing effectiveness
- **Subject Isolation** (0-15 points): How well the subject stands out

### Psychological Engagement Score (30%)
- **Presence of Faces** (0-30 points): Face detection and engagement
- **Emotional Resonance** (0-25 points): Emotional impact and appeal
- **Color Psychology** (0-25 points): Psychological impact of colors
- **Storytelling** (0-20 points): Narrative elements and story potential

### Trend & Zeitgeist Score (20%)
- **Aesthetic Alignment** (0-60 points): Alignment with current visual trends
- **Authenticity Index** (0-40 points): Genuine and authentic feel

## 🔧 Customization

You can modify the scoring weights in `viral_velocity_scorer.py`:

```python
self.weights = {
    'technical_quality': 0.25,      # Change these values
    'compositional_strength': 0.25, # to adjust scoring
    'psychological_engagement': 0.30, # priorities
    'trend_zeitgeist': 0.20
}
```

## 📱 Next Steps for Mobile Integration

1. **API Integration**: The mobile app can call the `/score-image` endpoint
2. **Image Enhancement**: Add Gemini's image generation capabilities
3. **User Management**: Add user authentication and usage tracking
4. **Analytics**: Track scoring patterns and user engagement

## 🚨 Important Notes

- **Privacy**: Images are processed temporarily and not stored 
- **API Limits**: Be mindful of OpenAI API usage limits and costs
- **Accuracy**: Scores are AI-generated and should be used as guidance, not absolute truth
- **Mobile Optimization**: Consider image compression for faster mobile processing
- **Performance**: Uses efficient analysis (3 API calls instead of 8) to reduce costs
- **JSON Parsing**: Automatically handles OpenAI's markdown-formatted JSON responses

## 🤝 Contributing

This is a data science-focused implementation. The scoring algorithms and AI integration are the core components. Frontend/backend development for the mobile app will be handled separately.

---

**Built with ❤️ using OpenAI GPT-4 Vision for intelligent social media optimization**