clawfort/openspec/specs/image-provider-fallback-chain/spec.md

Purpose

Canonical specification for image-provider-fallback-chain requirements synced from OpenSpec change deltas.

Requirements

Requirement: Configurable provider priority

The system SHALL support configuring image provider order via ROYALTY_IMAGE_PROVIDERS environment variable.

Scenario: Custom provider order

• WHEN ROYALTY_IMAGE_PROVIDERS=unsplash,pexels,pixabay,wikimedia,picsum
• THEN system tries providers in order: Unsplash → Pexels → Pixabay → Wikimedia → Picsum

Scenario: Default provider order

• WHEN ROYALTY_IMAGE_PROVIDERS is not set or empty
• THEN system uses default order: pixabay,unsplash,pexels,wikimedia,picsum

Scenario: Single provider configured

• WHEN ROYALTY_IMAGE_PROVIDERS=pexels
• THEN system only tries Pexels provider
• AND returns (None, None) if Pexels fails or is not configured

Requirement: Sequential fallback execution

The system SHALL try providers sequentially until one returns a valid image.

Scenario: First provider succeeds

• WHEN provider chain is pixabay,unsplash,pexels AND Pixabay returns valid image
• THEN system returns Pixabay image immediately
• AND does NOT call Unsplash or Pexels APIs

Scenario: First provider fails, second succeeds

• WHEN provider chain is pixabay,unsplash,pexels AND Pixabay returns no results AND Unsplash returns valid image
• THEN system returns Unsplash image
• AND does NOT call Pexels API

Scenario: All providers fail

• WHEN all configured providers return (None, None)
• THEN system returns (None, None) as final result
• AND caller handles fallback to article image or placeholder

Requirement: MCP endpoint override

The existing ROYALTY_IMAGE_MCP_ENDPOINT SHALL take priority over the provider chain when configured.

Scenario: MCP endpoint configured

• WHEN ROYALTY_IMAGE_MCP_ENDPOINT is set to valid URL
• THEN system tries MCP endpoint first before provider chain
• AND falls back to provider chain only if MCP endpoint fails

Scenario: MCP endpoint not configured

• WHEN ROYALTY_IMAGE_MCP_ENDPOINT is empty or unset
• THEN system skips MCP endpoint and proceeds directly to provider chain

Requirement: Provider skip on missing credentials

Providers without required API keys SHALL be skipped silently.

Scenario: Skip unconfigured provider

• WHEN provider chain includes pixabay AND PIXABAY_API_KEY is not set
• THEN Pixabay is skipped without error
• AND chain continues to next provider

Scenario: All providers skipped

• WHEN no providers in chain have valid API keys configured
• THEN system falls back to Wikimedia (no key required) or Picsum (always available)