clawfort/openspec/changes/archive/2026-02-13-p09-image-choices/tasks.md

1. Configuration Setup

• 1.1 Add ROYALTY_IMAGE_PROVIDERS config variable to backend/config.py with default pixabay,unsplash,pexels,wikimedia,picsum
• 1.2 Add PIXABAY_API_KEY config variable to backend/config.py
• 1.3 Add UNSPLASH_ACCESS_KEY config variable to backend/config.py
• 1.4 Add PEXELS_API_KEY config variable to backend/config.py
• 1.5 Update .env.example with new provider API key placeholders

2. Query Refinement

• 2.1 Create extract_image_keywords(headline: str) -> str function in backend/news_service.py
• 2.2 Implement stop word removal (articles, prepositions, common verbs)
• 2.3 Implement keyword limit (max 5 significant words)
• 2.4 Handle edge cases: empty headline, only stop words, special characters

3. Provider Implementations

• 3.1 Create fetch_pixabay_image(query: str) -> tuple[str | None, str | None] function
• 3.2 Implement Pixabay API call with webformatURL extraction and "Photo by {user} on Pixabay" credit
• 3.3 Create fetch_unsplash_image(query: str) -> tuple[str | None, str | None] function
• 3.4 Implement Unsplash API call with urls.regular extraction and "Photo by {user.name} on Unsplash" credit
• 3.5 Create fetch_pexels_image(query: str) -> tuple[str | None, str | None] function
• 3.6 Implement Pexels API call with src.large extraction and "Photo by {photographer} on Pexels" credit

4. Provider Fallback Chain

• 4.1 Create provider registry mapping provider names to fetch functions
• 4.2 Parse ROYALTY_IMAGE_PROVIDERS into ordered list at startup
• 4.3 Implement get_enabled_providers() that filters by configured API keys
• 4.4 Modify fetch_royalty_free_image() to iterate provider chain with fallback

5. Integration

• 5.1 Wire refined query extraction into fetch_royalty_free_image() call
• 5.2 Preserve MCP endpoint as highest priority (existing behavior)
• 5.3 Preserve Wikimedia and Picsum as fallback providers in chain
• 5.4 Add error logging for each provider failure with provider name

6. Documentation

• 6.1 Update README environment variables table with new provider keys
• 6.2 Add provider configuration section to README explaining priority chain
• 6.3 Document attribution requirements for each provider

7. Verification

• 7.1 Test Pixabay provider with sample query (requires API key)
• 7.2 Test Unsplash provider with sample query (requires API key)
• 7.3 Test Pexels provider with sample query (requires API key)
• 7.4 Test fallback chain when primary provider fails
• 7.5 Test fallback to Picsum when no API keys configured
• 7.6 Verify attribution format matches provider requirements