Add Gemini 3 Pro Image Preview model support (v0.2.10)

[Kamilbenkirane]

Overview

This PR adds support for Gemini 3 Pro Image Preview model for image generation and bumps versions to trigger publishing.

Changes

• ✅ Added gemini-3-pro-image-preview model with aspect_ratio and quality parameters
• ✅ Support for high-resolution outputs (1K, 2K, 4K) via unified quality parameter
• ✅ Added reasoning_tokens field to ImageGenerationUsage for thoughts/reasoning token counts
• ✅ Updated GeminiImageAPIAdapter to parse thoughtsTokenCount from API response

Version Bumps

• celeste-image-generation: 0.2.8 → 0.2.9
• celeste-ai: 0.2.9 → 0.2.10
• Updated dependency references in main pyproject.toml

Model Details

• Model ID: gemini-3-pro-image-preview
• Display Name: Gemini 3 Pro Image (Preview)
• Aspect Ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
• Quality Options: 1K, 2K, 4K

Publishing

This PR includes version bumps that will trigger publishing when merged and tagged.

[claude]

Code Review: Add Gemini 3 Pro Image Preview model support (v0.2.10)

Summary

This PR adds support for the Gemini 3 Pro Image Preview model with enhanced quality options (1K, 2K, 4K) and introduces reasoning token tracking. The implementation follows existing patterns and is well-structured.

✅ Strengths

Code Quality

• Consistent with existing patterns: The new model definition follows the same structure as other Gemini models (packages/image-generation/src/celeste_image_generation/providers/google/models.py:81-101)
• Clean separation of concerns: API adapter pattern is properly utilized
• Type safety: All changes maintain type annotations

Implementation

• Reasoning tokens support: Adding reasoning_tokens field to ImageGenerationUsage aligns with text generation's usage tracking (packages/text-generation/src/celeste_text_generation/io.py:32)
• Proper usage parsing: The thoughtsTokenCount extraction in GeminiImageAPIAdapter.parse_usage() matches the text generation implementation pattern (packages/image-generation/src/celeste_image_generation/providers/google/gemini_api.py:73)

🔍 Areas for Consideration

1. Missing Test Coverage ⚠️

The PR adds new functionality but doesn't include tests:

Recommendation: Add tests for:

• The new gemini-3-pro-image-preview model definition
• The reasoning_tokens field in usage parsing
• Quality parameter validation for 4K option (new capability)

Example test location: packages/image-generation/tests/unit_tests/providers/google/test_gemini_api.py

def test_parse_usage_with_reasoning_tokens():
    """Test that thoughtsTokenCount is correctly parsed as reasoning_tokens."""
    adapter = GeminiImageAPIAdapter()
    response_data = {
        "usageMetadata": {
            "promptTokenCount": 10,
            "candidatesTokenCount": 20,
            "totalTokenCount": 30,
            "thoughtsTokenCount": 5,  # New field
        },
        "candidates": [{}],
    }
    
    usage = adapter.parse_usage(response_data)
    
    assert usage.reasoning_tokens == 5
    assert usage.input_tokens == 10

2. Documentation Gaps 📝

Issue: No inline documentation explaining what reasoning_tokens represents

Recommendation: Add a docstring to the reasoning_tokens field in ImageGenerationUsage

3. Version Bump Strategy 📦

Observation: The PR bumps versions to trigger publishing

Question: Is there a changelog or release notes file that should be updated? Consider documenting:

• New model support
• New reasoning_tokens field in API
• Breaking changes (if any)

4. Minor: Aspect Ratio Options Consistency 🎨

Observation: The new model has 10 aspect ratio options (including 21:9, 4:5, 5:4) vs. gemini-2.5-flash-image's identical list

Note: This is fine if accurate to the API, but worth double-checking Google's documentation to ensure:

• 4K quality is available for all aspect ratios
• The aspect ratio list matches the official API spec

🔒 Security

✅ No security concerns identified:

• No user input processing changes
• No authentication/authorization changes
• API key handling unchanged

⚡ Performance

✅ No performance concerns:

• Minimal code additions
• No algorithmic changes
• Model lookup uses existing O(1) set operations (packages/image-generation/src/celeste_image_generation/providers/google/client.py:126-127)

🐛 Potential Issues

No bugs identified, but consider:

1. Graceful degradation: If Google's API doesn't return thoughtsTokenCount, the code handles it correctly (returns None)
2. API compatibility: Ensure the Gemini 3 Pro Image Preview model is available in the API region/endpoint being used

📋 Checklist for Merge

• Add unit tests for reasoning_tokens parsing
• Add integration test or update existing test to include gemini-3-pro-image-preview
• Document reasoning_tokens field purpose
• Verify 4K quality support with Google's API documentation
• Update changelog/release notes (if applicable)

Final Verdict

Approve with minor suggestions. The code is well-structured and follows existing patterns. The main gap is test coverage for the new functionality. Once tests are added, this is ready to merge.

Great work maintaining consistency with the existing codebase architecture! 🚀

---

Generated with Claude Code