Add seedream tools

[ikohu-66]

Summary

Add Seedream V5 image generation tool with comprehensive test suite and UTF-8 encoding fix

This PR introduces the Seedream V5 image generation tool via fal.ai API, featuring:

• 🎨 Multi-language support (Chinese, Japanese, Korean, emoji, etc.) with proper UTF-8 encoding
• 🧪 Complete test coverage (unit tests + integration tests)
• ⚡ Optimized test code (38% reduction from 421 → 263 lines)
• 🔒 Robust error handling and input validation

Why: Seedream V5 excels at generating images with accurate text rendering, structured designs, and dense layouts — capabilities missing from existing image generation tools.

Changes

🆕 New Files

• tools/graphics/seedream_image.py (258 lines)

  • Seedream V5 image generation via fal.ai queue API
  • Support for 8 image sizes (square, square_hd, landscape_4_3, portrait_4_3, auto_1K, auto_2K, etc.)
  • JPEG/PNG output formats with configurable safety checker
  • Critical fix: Explicit UTF-8 encoding to support CJK characters, emoji, and Unicode prompts
  • Async polling status tracking (up to 300s timeout)
  • Cost estimation based on size and quantity
  • Input validation and friendly error messages

• tests/tools/test_seedream_image.py (442 lines)

  • Unit tests (262 lines): Fully mocked HTTP responses, <1s execution time

    • TestMultiOutputRegression: Ensures all requested images are returned (critical for billing accuracy)
    • TestCostEstimation: Parameterized tests for all 8 size/quantity combinations
    • TestAsyncPolling: IN_PROGRESS → COMPLETED state transitions
    • TestValidation: Empty prompt, missing API key scenarios
    • TestMetadata: Response data completeness validation

  • Integration tests (180 lines): Real API calls requiring FAL_KEY

    • TestSeedreamImageRealAPI: 8 real-world scenarios
      • Single/multi-image generation
      • Different size/format combinations
      • Cost estimation accuracy (±2% tolerance)
      • Error handling (invalid prompts, failed states)
      • Metadata completeness verification
      • Output format validation (JPEG header \xff\xd8, PNG header \x89PNG)
    • Auto-skips when FAL_KEY environment variable is not set

Testing

✅ Platform Tested

• ✅ macOS (Apple Silicon) - Python 3.10+
• ✅ Linux (Ubuntu 22.04) - Python 3.11
• ✅ Windows 11 (WSL2) - Python 3.10

✅ Edge Cases Tested

• Empty prompt string → Returns clear error message
• Missing FAL_KEY → Tool status = UNAVAILABLE
• Network timeout → Retry policy applied (max 2 retries)
• API rate limit → Caught as retryable error
• Invalid image size → Falls back to default auto_2K
• Very long prompt (>1000 chars) → Handled correctly by UTF-8 encoding

Checklist

• The change is focused on a single logical concern: Add Seedream V5 image generation tool with UTF-8 encoding support and comprehensive test suite
• I ran the relevant tests locally: