@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/gemini-imagegen/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: gemini-imagegen
+description: "This skill should be used when generating or editing images via the Gemini API: text-to-image, edits, multi-turn refinement, style transfer, mockups."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Gemini Image Generation (Nano Banana Pro)
+
+Generate and edit images using Google's Gemini API. The environment variable `GEMINI_API_KEY` must be set.
+
+## Phase 0: Pre-Flight Checks
+
+Before generating images, verify both environment and quota:
+
+1. **Environment:** Confirm `GEMINI_API_KEY` is set (the scripts check this)
+2. **Python dependencies:** Install in a venv (`python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt`) -- bare `pip install` is blocked by PEP 668 on modern Linux; versions are pinned to exact releases for supply chain security
+3. **Image generation quota:** Free-tier API keys authenticate successfully but may have zero quota for image generation. The pre-flight MUST exercise the SAME model Phase 1 will use (`gemini-3-pro-image-preview`) — testing a different model produces stale signals. On free-tier keys as of 2026-04-21, BOTH `gemini-3-pro-image` and `gemini-2.5-flash-image` return `429 RESOURCE_EXHAUSTED` with `limit: 0`; Imagen models return `404 NOT_FOUND`. Run a minimal test request before building the full pipeline:
+
+```bash
+python3 -c "
+import os
+from google import genai
+from google.genai import types
+client = genai.Client(api_key=os.environ['GEMINI_API_KEY'])
+try:
+    r = client.models.generate_content(
+        model='gemini-3-pro-image-preview',
+        contents=['Generate a 1x1 pixel red square'],
+        config=types.GenerateContentConfig(
+            response_modalities=['TEXT', 'IMAGE'],
+            image_config=types.ImageConfig(aspect_ratio='1:1', image_size='1K'),
+        ),
+    )
+    # Verify we actually got image bytes, not just a successful call
+    has_image = any(p.inline_data for p in r.parts)
+    print('[ok] Image generation quota available' if has_image else '[FAIL] No image bytes in response')
+except Exception as e:
+    print(f'[FAIL] Image generation quota: {type(e).__name__}: {str(e)[:200]}')
+"
+```
+
+If quota is unavailable (`429 RESOURCE_EXHAUSTED`, `limit: 0`), fall back to Pillow-only generation (solid/gradient backgrounds with text overlay, or geometric compositions without text). Print a loud banner so the operator knows the session is running on fallback, not real Gemini output — silent fallback on OG/hero work can ship before a regeneration is scheduled. See `knowledge-base/project/learnings/2026-04-21-fact-checker-file-scope-plus-eleventy-footnote-gap.md` §5.
+
+## Default Model
+
+| Model | Resolution | Best For |
+|-------|------------|----------|
+| `gemini-3-pro-image-preview` | 1K-4K | All image generation (default) |
+
+**Note:** Always use this Pro model. Only use a different model if explicitly requested.
+
+## Quick Reference
+
+### Default Settings
+
+- **Model:** `gemini-3-pro-image-preview`
+- **Resolution:** 1K (default, options: 1K, 2K, 4K)
+- **Aspect Ratio:** 1:1 (default)
+
+### Available Aspect Ratios
+
+`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
+
+### Available Resolutions
+
+`1K` (default), `2K`, `4K`
+
+## Core API Pattern
+
+```python
+import os
+from google import genai
+from google.genai import types
+
+client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
+
+# Basic generation (1K, 1:1 - defaults)
+response = client.models.generate_content(
+    model="gemini-3-pro-image-preview",
+    contents=["Your prompt here"],
+    config=types.GenerateContentConfig(
+        response_modalities=['TEXT', 'IMAGE'],
+    ),
+)
+
+for part in response.parts:
+    if part.text:
+        print(part.text)
+    elif part.inline_data:
+        image = part.as_image()
+        image.save("output.png")
+```
+
+## Custom Resolution & Aspect Ratio
+
+```python
+from google.genai import types
+
+response = client.models.generate_content(
+    model="gemini-3-pro-image-preview",
+    contents=[prompt],
+    config=types.GenerateContentConfig(
+        response_modalities=['TEXT', 'IMAGE'],
+        image_config=types.ImageConfig(
+            aspect_ratio="16:9",  # Wide format
+            image_size="2K"       # Higher resolution
+        ),
+    )
+)
+```
+
+### Resolution Examples
+
+```python
+# 1K (default) - Fast, good for previews
+image_config=types.ImageConfig(image_size="1K")
+
+# 2K - Balanced quality/speed
+image_config=types.ImageConfig(image_size="2K")
+
+# 4K - Maximum quality, slower
+image_config=types.ImageConfig(image_size="4K")
+```
+
+### Aspect Ratio Examples
+
+```python
+# Square (default)
+image_config=types.ImageConfig(aspect_ratio="1:1")
+
+# Landscape wide
+image_config=types.ImageConfig(aspect_ratio="16:9")
+
+# Ultra-wide panoramic
+image_config=types.ImageConfig(aspect_ratio="21:9")
+
+# Portrait
+image_config=types.ImageConfig(aspect_ratio="9:16")
+
+# Photo standard
+image_config=types.ImageConfig(aspect_ratio="4:3")
+```
+
+## Editing Images
+
+Pass existing images with text prompts:
+
+```python
+from PIL import Image
+
+img = Image.open("input.png")
+response = client.models.generate_content(
+    model="gemini-3-pro-image-preview",
+    contents=["Add a sunset to this scene", img],
+    config=types.GenerateContentConfig(
+        response_modalities=['TEXT', 'IMAGE'],
+    ),
+)
+```
+
+## Multi-Turn Refinement
+
+Use chat for iterative editing:
+
+```python
+from google.genai import types
+
+chat = client.chats.create(
+    model="gemini-3-pro-image-preview",
+    config=types.GenerateContentConfig(response_modalities=['TEXT', 'IMAGE'])
+)
+
+response = chat.send_message("Create a logo for 'Acme Corp'")
+# Save first image...
+
+response = chat.send_message("Make the text bolder and add a blue gradient")
+# Save refined image...
+```
+
+## Prompting Best Practices
+
+### Photorealistic Scenes
+
+Include camera details: lens type, lighting, angle, mood.
+> "A photorealistic close-up portrait, 85mm lens, soft golden hour light, shallow depth of field"
+
+### Stylized Art
+
+Specify style explicitly:
+> "A kawaii-style sticker of a happy red panda, bold outlines, cel-shading, white background"
+
+### Text in Images
+
+Be explicit about font style and placement:
+> "Create a logo with text 'Daily Grind' in clean sans-serif, black and white, coffee bean motif"
+
+### Product Mockups
+
+Describe lighting setup and surface:
+> "Studio-lit product photo on polished concrete, three-point softbox setup, 45-degree angle"
+
+## Advanced Features
+
+### Google Search Grounding
+
+Generate images based on real-time data:
+
+```python
+response = client.models.generate_content(
+    model="gemini-3-pro-image-preview",
+    contents=["Visualize today's weather in Tokyo as an infographic"],
+    config=types.GenerateContentConfig(
+        response_modalities=['TEXT', 'IMAGE'],
+        tools=[{"google_search": {}}]
+    )
+)
+```
+
+### Multiple Reference Images (Up to 14)
+
+Combine elements from multiple sources:
+
+```python
+response = client.models.generate_content(
+    model="gemini-3-pro-image-preview",
+    contents=[
+        "Create a group photo of these people in an office",
+        Image.open("person1.png"),
+        Image.open("person2.png"),
+        Image.open("person3.png"),
+    ],
+    config=types.GenerateContentConfig(
+        response_modalities=['TEXT', 'IMAGE'],
+    ),
+)
+```
+
+## Important: File Format & Media Type
+
+**CRITICAL:** The Gemini API returns images in JPEG format by default. When saving, always use `.jpg` extension to avoid media type mismatches.
+
+```python
+# CORRECT - Use .jpg extension (Gemini returns JPEG)
+image.save("output.jpg")
+
+# WRONG - Will cause "Image does not match media type" errors
+image.save("output.png")  # Creates JPEG with PNG extension!
+```
+
+### Converting to PNG (if needed)
+
+If you specifically need PNG format:
+
+```python
+from PIL import Image
+
+# Generate with Gemini
+for part in response.parts:
+    if part.inline_data:
+        img = part.as_image()
+        # Convert to PNG by saving with explicit format
+        img.save("output.png", format="PNG")
+```
+
+### Verifying Image Format
+
+Check actual format vs extension with the `file` command:
+
+```bash
+file image.png
+# If output shows "JPEG image data" - rename to .jpg!
+```
+
+## Notes
+
+- All generated images include SynthID watermarks
+- Gemini returns **JPEG format by default** - always use `.jpg` extension
+- Image-only mode (`responseModalities: ["IMAGE"]`) won't work with Google Search grounding
+- For editing, describe changes conversationally—the model understands semantic masking
+- Default to 1K resolution for speed; use 2K/4K when quality is critical

package/skills/gemini-imagegen/requirements.txt

@@ -0,0 +1,5 @@
+# Pinned to exact versions for supply chain security (#1174).
+# Full hash verification (--require-hashes) requires pip-compile for
+# transitive dependencies -- tracked as future enhancement.
+google-genai==1.66.0
+Pillow==12.3.0

package/skills/gemini-imagegen/scripts/_error_handling.py

@@ -0,0 +1,146 @@
+"""Shared error handling for Gemini image generation scripts.
+
+Error messages include raw API responses intentionally for CLI debugging.
+Sanitize before surfacing in user-facing web contexts.
+"""
+
+from typing import NoReturn
+
+from google.genai import errors
+
+
+class QuotaExhaustedError(RuntimeError):
+    """API key has zero or exceeded image generation quota."""
+
+    pass
+
+
+class PermissionDeniedError(RuntimeError):
+    """API key lacks image generation access."""
+
+    pass
+
+
+class SafetyFilterError(RuntimeError):
+    """Image was blocked by content policy."""
+
+    pass
+
+
+class NoImageError(RuntimeError):
+    """Model returned no image in response."""
+
+    pass
+
+
+_SAFETY_KEYWORDS = ("blocked", "safety", "policy", "prohibited", "harmful")
+
+
+def handle_api_error(e: errors.APIError) -> NoReturn:
+    """Raise a descriptive error based on API error code.
+
+    Converts google.genai SDK exceptions into specific error types.
+    """
+    if isinstance(e, errors.ClientError):
+        if e.code == 429:
+            raise QuotaExhaustedError(
+                "QUOTA EXHAUSTED: Image generation quota is zero or exceeded. "
+                "Free-tier keys may not include image generation.\n"
+                f"API error: {e.message}"
+            ) from e
+        elif e.code == 403:
+            raise PermissionDeniedError(
+                "PERMISSION DENIED: API key lacks image generation access. "
+                "Check your Gemini API tier.\n"
+                f"API error: {e.message}"
+            ) from e
+        else:
+            raise RuntimeError(
+                f"API CLIENT ERROR ({e.code}): {e.message}"
+            ) from e
+    elif isinstance(e, errors.ServerError):
+        raise RuntimeError(
+            f"API SERVER ERROR ({e.code}): {e.message}"
+        ) from e
+    # Forward-compatibility guard for future APIError subclasses
+    raise RuntimeError(f"API ERROR: {e.message}") from e
+
+
+def parse_image_response(response) -> tuple[object | None, str | None]:
+    """Parse a Gemini response for image and text parts.
+
+    Does NOT access response.candidates[N].finish_reason to avoid
+    SDK hang bug (issue #2024).
+
+    Args:
+        response: The GenerateContentResponse or SendMessageResponse.
+
+    Returns:
+        Tuple of (PIL Image or None, text_response or None).
+
+    Raises:
+        NoImageError: If response contains no image parts.
+        SafetyFilterError: If image was blocked by content policy.
+    """
+    if not response.parts:
+        raise NoImageError(
+            "NO IMAGE IN RESPONSE: Model returned empty response. "
+            "Try a different model or prompt."
+        )
+
+    text_response = None
+    image_result = None
+
+    for part in response.parts:
+        if part.text is not None:
+            text_response = part.text
+        elif part.inline_data is not None:
+            image_result = part.as_image()
+
+    if image_result is None:
+        response_text = text_response or ""
+        if any(kw in response_text.lower() for kw in _SAFETY_KEYWORDS):
+            raise SafetyFilterError(
+                "SAFETY FILTER: Image was blocked by content policy. "
+                "Rephrase the prompt."
+            )
+        raise NoImageError(
+            "NO IMAGE IN RESPONSE: Model returned text only. "
+            "Try a different model or prompt."
+        )
+
+    return image_result, text_response
+
+
+def check_quota(client, model: str = "gemini-2.5-flash-image") -> None:
+    """Verify image generation quota with a minimal test request.
+
+    Sends a trivial prompt and checks if the API returns an image.
+    Prints status and raises on failure.
+
+    Args:
+        client: An initialized genai.Client instance.
+        model: The model to test against.
+    """
+    from google.genai import types
+
+    try:
+        response = client.models.generate_content(
+            model=model,
+            contents=["Generate a 1x1 pixel red square"],
+            config=types.GenerateContentConfig(
+                response_modalities=["TEXT", "IMAGE"]
+            ),
+        )
+    except errors.APIError as e:
+        handle_api_error(e)
+
+    has_image = response.parts and any(
+        p.inline_data is not None for p in response.parts
+    )
+    if has_image:
+        print(f"[ok] Image generation quota available (model: {model})")
+    else:
+        raise NoImageError(
+            f"[FAIL] No image in response -- quota may be unavailable (model: {model})"
+        )

package/skills/gemini-imagegen/scripts/compose_images.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""
+Compose multiple images into a new image using Gemini API.
+
+Usage:
+    python compose_images.py "instruction" output.png image1.png [image2.png ...]
+
+Examples:
+    python compose_images.py "Create a group photo of these people" group.png person1.png person2.png
+    python compose_images.py "Put the cat from the first image on the couch from the second" result.png cat.png couch.png
+    python compose_images.py "Apply the art style from the first image to the scene in the second" styled.png style.png photo.png
+
+Note: Supports up to 14 reference images (Gemini 3 Pro only).
+
+Environment:
+    GEMINI_API_KEY - Required API key
+"""
+
+import argparse
+import os
+import sys
+
+from PIL import Image
+from google import genai
+from google.genai import errors, types
+
+from _error_handling import handle_api_error, parse_image_response
+
+
+def compose_images(
+    instruction: str,
+    output_path: str,
+    image_paths: list[str],
+    model: str = "gemini-3-pro-image-preview",
+    aspect_ratio: str | None = None,
+    image_size: str | None = None,
+) -> str | None:
+    """Compose multiple images based on instructions.
+    
+    Args:
+        instruction: Text description of how to combine images
+        output_path: Path to save the result
+        image_paths: List of input image paths (up to 14)
+        model: Gemini model to use (pro recommended)
+        aspect_ratio: Output aspect ratio
+        image_size: Output resolution
+    
+    Returns:
+        Any text response from the model, or None
+    """
+    api_key = os.environ.get("GEMINI_API_KEY")
+    if not api_key:
+        raise EnvironmentError("GEMINI_API_KEY environment variable not set")
+    
+    if len(image_paths) > 14:
+        raise ValueError("Maximum 14 reference images supported")
+    
+    if len(image_paths) < 1:
+        raise ValueError("At least one image is required")
+    
+    # Verify all images exist
+    for path in image_paths:
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"Image not found: {path}")
+    
+    client = genai.Client(api_key=api_key)
+    
+    # Load images
+    images = [Image.open(path) for path in image_paths]
+    
+    # Build contents: instruction first, then images
+    contents = [instruction] + images
+    
+    # Build config
+    config_kwargs = {"response_modalities": ["TEXT", "IMAGE"]}
+    
+    image_config_kwargs = {}
+    if aspect_ratio:
+        image_config_kwargs["aspect_ratio"] = aspect_ratio
+    if image_size:
+        image_config_kwargs["image_size"] = image_size
+    
+    if image_config_kwargs:
+        config_kwargs["image_config"] = types.ImageConfig(**image_config_kwargs)
+    
+    config = types.GenerateContentConfig(**config_kwargs)
+    
+    try:
+        response = client.models.generate_content(
+            model=model,
+            contents=contents,
+            config=config,
+        )
+    except errors.APIError as e:
+        handle_api_error(e)
+
+    image, text_response = parse_image_response(response)
+    image.save(output_path)
+    return text_response
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Compose multiple images using Gemini API",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__
+    )
+    parser.add_argument("instruction", help="Composition instruction")
+    parser.add_argument("output", help="Output file path")
+    parser.add_argument("images", nargs="+", help="Input images (up to 14)")
+    parser.add_argument(
+        "--model", "-m",
+        default="gemini-3-pro-image-preview",
+        choices=["gemini-2.5-flash-image", "gemini-3-pro-image-preview"],
+        help="Model to use (pro recommended for composition)"
+    )
+    parser.add_argument(
+        "--aspect", "-a",
+        choices=["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"],
+        help="Output aspect ratio"
+    )
+    parser.add_argument(
+        "--size", "-s",
+        choices=["1K", "2K", "4K"],
+        help="Output resolution"
+    )
+    
+    args = parser.parse_args()
+    
+    try:
+        text = compose_images(
+            instruction=args.instruction,
+            output_path=args.output,
+            image_paths=args.images,
+            model=args.model,
+            aspect_ratio=args.aspect,
+            image_size=args.size,
+        )
+        
+        print(f"Composed image saved to: {args.output}")
+        if text:
+            print(f"Model response: {text}")
+            
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()