AI Photo Review Guide

This guide explains how the AI photo review system works in chet-lemon and how to customize it for your needs.

Overview

The AI review system supports multiple AI providers - Anthropic Claude, OpenAI GPT-4, and Google Gemini - giving you flexibility in cost, quality, and availability. The review is automatically generated during the image processing workflow and displayed on each photo's post page.

Multi-Provider Support (NEW!)

Supported Providers

The system now supports three leading AI vision models:

Provider	Model	Strengths	Cost	Speed	Quality
Anthropic Claude	Sonnet 4.5	Best overall quality, nuanced feedback	$0.003/img	Fast	⭐⭐⭐⭐⭐
OpenAI GPT-4	GPT-4o	Detailed analysis, broad knowledge	$0.005/img	Medium	⭐⭐⭐⭐
Google Gemini	Gemini 1.5 Flash	Fast, cost-effective, free tier	$0.0001/img	Fastest	⭐⭐⭐⭐

Auto-Detection

The system automatically detects which API key is available and uses that provider:

1. Checks for ANTHROPIC_API_KEY first (highest priority)
2. Falls back to OPENAI_API_KEY
3. Falls back to GOOGLE_API_KEY (lowest priority)

You can override this by setting AI_PROVIDER to anthropic, openai, or google.

Which Provider Should You Choose?

Use Claude if:

• You want the best quality reviews
• Budget allows ~$0.30 per 100 photos
• Professional photography portfolio

Use GPT-4 if:

• You want very detailed analysis
• You already have OpenAI credits
• You want a different perspective from Claude

Use Gemini if:

• You're processing large volumes
• You're on a tight budget
• You want to use the free tier
• Speed is most important

How It Works

Workflow Integration

Photo Upload → HEIC Conversion → Image Optimization → AI Review → Post Generation → Commit

When you push photos to _originals/:

1. GitHub Actions triggers the workflow
2. Image Processing converts and optimizes the images
3. AI Review sends the image to Claude API for analysis
4. Post Generation includes the review in YAML front matter
5. Display shows the review on the photo post page

Review Process

The AI analyzes each photo considering:

• Composition: Rule of thirds, leading lines, framing, balance, negative space
• Lighting: Quality, direction, color temperature, mood, contrast
• Exposure: Brightness levels, dynamic range, histogram distribution
• Subject & Focus: Subject clarity, depth of field, focal point effectiveness
• Creativity: Originality, emotional resonance, storytelling elements
• Technical Execution: Sharpness, noise levels, color accuracy, post-processing

Review Output

Data Structure

The review is stored in Jekyll front matter as YAML:

ai_review:
  overall_grade: "A-"
  overall_score: 87
  ratings:
    composition: 9
    lighting: 8
    exposure: 9
    subject: 8
    creativity: 9
    technical: 9
  strengths:
    - "Excellent use of the rule of thirds with the subject positioned perfectly"
    - "Beautiful golden hour lighting creates warmth and depth"
    - "Strong leading lines draw the viewer's eye through the composition"
  improvements:
    - "Slight overexposure in the highlights could be reduced"
    - "Consider a lower perspective to emphasize the foreground"
  summary: "A well-composed landscape shot with excellent timing and lighting. The golden hour glow adds emotional warmth, and the composition guides the viewer's eye naturally through the scene."
  mood: "serene"
  style: "landscape"

Visual Display

The review is displayed with:

• Grade Badge: Large, prominent display of letter grade and numeric score
• Rating Bars: Visual progress bars for each of the 6 dimensions
• Strengths Section: Green-highlighted positive feedback
• Improvements Section: Orange-highlighted constructive suggestions
• Tags: Style and mood classification badges
• Summary: Professional critique paragraph

Setup Instructions

1. Get API Key(s)

Choose one or more providers:

Option A: Anthropic Claude (Recommended)

1. Visit console.anthropic.com
2. Sign up or log in
3. Navigate to API Keys section
4. Create a new API key
5. Copy the key (starts with sk-ant-api03-...)

Option B: OpenAI GPT-4

1. Visit platform.openai.com
2. Sign up or log in
3. Navigate to API Keys section
4. Create a new API key
5. Copy the key (starts with sk-...)

Option C: Google Gemini

1. Visit ai.google.dev
2. Click "Get API key in Google AI Studio"
3. Sign in with Google account
4. Create a new API key
5. Copy the key

2. Configure GitHub Repository

1. Go to your repository on GitHub
2. Navigate to Settings > Secrets and variables > Actions
3. Click "New repository secret"
4. Add one or more of these secrets:
   • Name: ANTHROPIC_API_KEY | Value: Your Anthropic key
   • Name: OPENAI_API_KEY | Value: Your OpenAI key
   • Name: GOOGLE_API_KEY | Value: Your Google key

3. Provider Selection (Optional)

By default, the system auto-detects which provider to use based on available API keys (Claude > OpenAI > Gemini).

To force a specific provider:

• Name: AI_PROVIDER
• Value: anthropic, openai, or google

4. Enable/Disable Review

The AI review is enabled by default if any API key is present.

To disable it:

• Add repository secret:
  • Name: ENABLE_AI_REVIEW
  • Value: false

Customization

Changing the AI Model

Edit the MODELS object in scripts/review_photo.js:

const MODELS = {
  anthropic: 'claude-3-5-sonnet-20241022',
  openai: 'gpt-4o',
  google: 'gemini-1.5-flash'
};

Anthropic models:

• claude-3-5-sonnet-20241022 - Best balance (recommended)
• claude-3-opus-20240229 - Highest quality (slower, more expensive)
• claude-3-haiku-20240307 - Fastest and cheapest

OpenAI models:

• gpt-4o - Latest GPT-4 with vision (recommended)
• gpt-4-turbo - Previous generation
• gpt-4-vision-preview - Preview version

Google models:

• gemini-1.5-flash - Fast and efficient (recommended)
• gemini-1.5-pro - More capable, slower
• gemini-pro-vision - Previous generation

Customizing Review Criteria

Edit the REVIEW_PROMPT in scripts/review_photo.js to adjust:

• Which aspects to focus on
• The tone of feedback (strict vs. encouraging)
• Additional criteria (e.g., specific to wildlife, portraits, etc.)
• Output format

Example - Adding a "wildlife photography" focus:

const REVIEW_PROMPT = `You are an expert wildlife photography critic...

Additional considerations for wildlife photography:
- Animal behavior capture
- Eye sharpness and catchlights
- Natural habitat context
- Ethical shooting practices

...rest of prompt...`;

Adjusting Rating Display

Edit _layouts/post.html to customize:

Change color scheme:

.grade-badge {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  /* Change to any gradient or solid color */
}

Modify rating bar colors:

.rating-fill {
  background: linear-gradient(90deg, #4CAF50 0%, #8BC34A 100%);
  /* Green gradient - change to your preference */
}

Adjust layout:

.ratings-grid {
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  /* Change column count or minimum width */
}

Adding Additional Metrics

You can extend the review to include more data:

1. Edit scripts/review_photo.js - Add new fields to the JSON response format
2. Edit _layouts/post.html - Display the new data

Example - Adding a "market value" estimate:

In review_photo.js:

{
  ...existing fields...,
  "market_value": "Estimate if this would sell stock photography (yes/no/maybe)",
  "suggested_price": "Estimated stock photo price range ($-$$$)"
}

In post.html:

{% raw %}{% if page.ai_review.market_value %}
  <div class="market-info">
    <strong>Stock Photography Potential:</strong> {{ page.ai_review.market_value }}
    <br>
    <strong>Suggested Price:</strong> {{ page.ai_review.suggested_price }}
  </div>
{% endif %}{% endraw %}

Cost Management

Pricing Breakdown

Claude Sonnet 4.5 (as of 2025):

• Input: ~$3 per million tokens
• Output: ~$15 per million tokens

Per Image Cost:

• Image input: 200 tokens ($0.0006)
• Prompt: 300 tokens ($0.0009)
• Response: 400 tokens ($0.0060)
• Total: ~$0.003 per image

Batch Processing Costs

Photos	Estimated Cost
10	$0.03
50	$0.15
100	$0.30
500	$1.50
1,000	$3.00

Cost Reduction Strategies

1. Use Haiku model - 5x cheaper, faster, but less detailed reviews

   const MODEL = 'claude-3-haiku-20240307';
   

2. Disable for bulk uploads - Set ENABLE_AI_REVIEW=false for large batches

3. Selective review - Manually review only your best shots:

   # Upload without review
   ENABLE_AI_REVIEW=false git commit -m "Bulk upload"
   
   # Later, manually review specific images
   ANTHROPIC_API_KEY=your-key node scripts/review_photo.js _originals/photo.jpg --yaml
   

4. Reduce response length - Modify MAX_TOKENS to limit review length

Local Testing

Test the review system locally before pushing:

# Set API key
export ANTHROPIC_API_KEY='your-key-here'

# Review a single photo
node scripts/review_photo.js path/to/photo.jpg

# Get YAML output (for Jekyll front matter)
node scripts/review_photo.js path/to/photo.jpg --yaml

# Process all photos with reviews
./scripts/process_images.sh

Troubleshooting

Issue: "Error: ANTHROPIC_API_KEY environment variable not set"

Solution: Ensure the secret is added to GitHub repository or set locally:

export ANTHROPIC_API_KEY='your-key'

Issue: API rate limits exceeded

Solution:

• Anthropic has generous rate limits (default: 50 requests/minute)
• For bulk processing, add delays between reviews
• Contact Anthropic support for higher limits if needed

Issue: Review not appearing on post page

Possible causes:

1. API key not set - Check GitHub Secrets
2. Script failed silently - Check GitHub Actions logs
3. YAML parsing error - Validate generated post front matter
4. Template issue - Verify {% raw %}{% if page.ai_review %}{% endraw %} in post.html

Debug:

# Check generated post file
cat _posts/YYYY-MM-DD-filename.md

# Should contain ai_review: section with all data

Issue: "Could not parse JSON from AI response"

Solution:

• Model might return non-JSON text
• Check scripts/review_photo.js error logs
• Verify Claude is returning expected format
• Try with a simpler test image first

Issue: Different reviews for same photo

This is normal! AI models have some variability. If you need consistent reviews:

• Cache review results and don't regenerate
• Use temperature=0 in API call (add to scripts/review_photo.js)

Advanced Features

Multi-Language Support

Modify the prompt to request reviews in different languages:

const REVIEW_PROMPT = `You are an expert photography critic. Provide your review in Spanish.

Analiza esta fotografía y proporciona una crítica detallada...`;

Custom Grading Scales

Change from letter grades to stars, numbers, or custom scales:

// In review_photo.js
{
  "overall_grade": "4.5/5 stars",  // Instead of "A-"
  "overall_score": 90
}

Integration with Other Services

The review data can be exported to:

• Google Sheets - Track photo performance over time
• Portfolio sites - Display reviews on external websites
• Social media - Auto-generate captions with review highlights
• Photo management apps - Sync reviews to Lightroom/Capture One

Example Reviews

Landscape Photo

Grade: A-
Score: 87/100

Composition: 9/10 | Lighting: 8/10 | Exposure: 9/10
Subject: 8/10 | Creativity: 9/10 | Technical: 9/10

Strengths:
• Excellent use of the rule of thirds with perfectly positioned horizon
• Beautiful golden hour lighting creates warmth and depth
• Strong leading lines from the path draw viewer's eye through scene

Improvements:
• Slight overexposure in sky highlights could be reduced
• Consider deeper depth of field for sharper foreground details

Style: landscape | Mood: serene

Portrait Photo

Grade: B+
Score: 78/100

Composition: 7/10 | Lighting: 9/10 | Exposure: 8/10
Subject: 8/10 | Creativity: 7/10 | Technical: 7/10

Strengths:
• Soft natural window light beautifully sculpts the subject's features
• Excellent eye contact and genuine expression creates connection
• Clean background keeps focus on subject

Improvements:
• Composition could benefit from more negative space on left
• Slight chromatic aberration visible in high-contrast edges
• Consider subtle fill light to brighten shadows under chin

Style: portrait | Mood: contemplative

Privacy & Data

• Images are sent to Anthropic's API for analysis
• Anthropic does not train on your images (as of 2025 policy)
• Reviews are stored in your GitHub repository
• No third-party services besides Anthropic are used
• All processing happens in GitHub Actions (serverless)

For maximum privacy:

• Self-host the review system
• Use local AI models (requires significant setup)
• Disable AI review and manually write critiques

Support

For issues specific to:

• AI review feature: Open issue on this repository
• Anthropic API: Contact Anthropic support
• GitHub Actions: Check GitHub Actions documentation

---

Happy shooting and happy reviewing! 📸🤖