@weirdfingers/baseboards 0.5.2 → 0.6.0

package/templates/api/src/boards/generators/implementations/fal/image/flux_2_pro_edit.py

@@ -0,0 +1,221 @@
+"""
+fal.ai FLUX 2 Pro Edit generator.
+
+Production-grade multi-reference image editing that combines up to 9 reference
+images through a streamlined pipeline for professional image manipulation.
+Supports natural language precision, explicit image indexing with @ symbol,
+and zero-configuration workflow.
+
+Based on Fal AI's fal-ai/flux-2-pro/edit model.
+See: https://fal.ai/models/fal-ai/flux-2-pro/edit
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....artifacts import ImageArtifact
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+# Image size presets supported by the API
+ImageSizePreset = Literal[
+    "auto",
+    "square_hd",
+    "square",
+    "portrait_4_3",
+    "portrait_16_9",
+    "landscape_4_3",
+    "landscape_16_9",
+]
+
+
+class Flux2ProEditInput(BaseModel):
+    """Input schema for FLUX 2 Pro Edit.
+
+    Artifact fields (like image_sources) are automatically detected via type
+    introspection and resolved from generation IDs to ImageArtifact objects.
+    """
+
+    prompt: str = Field(
+        description="The prompt to edit the images. Use @ symbol to reference "
+        "specific input images by index (e.g., '@1' for first image)."
+    )
+    image_sources: list[ImageArtifact] = Field(
+        description="List of input images for editing (up to 9 images, 9 MP total)",
+        min_length=1,
+        max_length=9,
+    )
+    image_size: ImageSizePreset | None = Field(
+        default="auto",
+        description="The size of the generated image. If 'auto', the size will be "
+        "determined by the model based on input images.",
+    )
+    output_format: Literal["jpeg", "png"] = Field(
+        default="jpeg",
+        description="The format of the generated image.",
+    )
+    sync_mode: bool = Field(
+        default=False,
+        description=(
+            "If True, the media will be returned as a data URI and the output "
+            "data won't be available in the request history."
+        ),
+    )
+    safety_tolerance: Literal[1, 2, 3, 4, 5] = Field(
+        default=2,
+        description=(
+            "The safety tolerance level for the generated image. "
+            "1 is most strict, 5 is most permissive."
+        ),
+    )
+    enable_safety_checker: bool = Field(
+        default=True,
+        description="Whether to enable the safety checker.",
+    )
+    seed: int | None = Field(
+        default=None,
+        description="The seed to use for the generation. Leave empty for random.",
+    )
+
+
+class FalFlux2ProEditGenerator(BaseGenerator):
+    """FLUX 2 Pro Edit image generator using fal.ai.
+
+    Production-grade multi-reference editing that combines up to 9 reference
+    images through a streamlined pipeline. Supports natural language precision
+    for describing complex edits without masks.
+    """
+
+    name = "fal-flux-2-pro-edit"
+    artifact_type = "image"
+    description = "Fal: FLUX 2 Pro Edit - Production-grade multi-reference image editing"
+
+    def get_input_schema(self) -> type[Flux2ProEditInput]:
+        return Flux2ProEditInput
+
+    async def generate(
+        self, inputs: Flux2ProEditInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Edit images using fal.ai FLUX 2 Pro Edit model."""
+        # Check for API key (fal-client uses FAL_KEY environment variable)
+        if not os.getenv("FAL_KEY"):
+            raise ValueError("API configuration invalid. Missing FAL_KEY environment variable")
+
+        # Import fal_client
+        try:
+            import fal_client
+        except ImportError as e:
+            raise ImportError(
+                "fal.ai SDK is required for FalFlux2ProEditGenerator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Upload image artifacts to Fal's public storage
+        # Fal API requires publicly accessible URLs, but our storage_url might be:
+        # - Localhost URLs (not publicly accessible)
+        # - Private S3 buckets (not publicly accessible)
+        # So we upload to Fal's temporary storage first
+        from ..utils import upload_artifacts_to_fal
+
+        image_urls = await upload_artifacts_to_fal(inputs.image_sources, context)
+
+        # Prepare arguments for fal.ai API
+        arguments: dict = {
+            "prompt": inputs.prompt,
+            "image_urls": image_urls,
+            "output_format": inputs.output_format,
+            "sync_mode": inputs.sync_mode,
+            "safety_tolerance": inputs.safety_tolerance,
+            "enable_safety_checker": inputs.enable_safety_checker,
+        }
+
+        # Add optional parameters
+        if inputs.image_size is not None:
+            arguments["image_size"] = inputs.image_size
+        if inputs.seed is not None:
+            arguments["seed"] = inputs.seed
+
+        # Submit async job and get handler
+        handler = await fal_client.submit_async(
+            "fal-ai/flux-2-pro/edit",
+            arguments=arguments,
+        )
+
+        # Store the external job ID for tracking
+        await context.set_external_job_id(handler.request_id)
+
+        # Stream progress updates (sample every 3rd event to avoid spam)
+        from .....progress.models import ProgressUpdate
+
+        event_count = 0
+        async for event in handler.iter_events(with_logs=True):
+            event_count += 1
+
+            # Process every 3rd event to provide feedback without overwhelming
+            if event_count % 3 == 0:
+                # Extract logs if available
+                logs = getattr(event, "logs", None)
+                if logs:
+                    # Join log entries into a single message
+                    if isinstance(logs, list):
+                        message = " | ".join(str(log) for log in logs if log)
+                    else:
+                        message = str(logs)
+
+                    if message:
+                        await context.publish_progress(
+                            ProgressUpdate(
+                                job_id=handler.request_id,
+                                status="processing",
+                                progress=50.0,  # Approximate mid-point progress
+                                phase="processing",
+                                message=message,
+                            )
+                        )
+
+        # Get final result
+        result = await handler.get()
+
+        # Extract image URLs from result
+        # fal.ai returns: {
+        #   "images": [{"url": "...", "width": ..., "height": ..., ...}, ...],
+        #   "seed": ...
+        # }
+        images = result.get("images", [])
+
+        if not images:
+            raise ValueError("No images returned from fal.ai API")
+
+        # Store each image using output_index
+        artifacts = []
+        for idx, image_data in enumerate(images):
+            image_url = image_data.get("url")
+            # Extract dimensions if available, otherwise use sensible defaults
+            width = image_data.get("width", 1024)
+            height = image_data.get("height", 1024)
+
+            if not image_url:
+                raise ValueError(f"Image {idx} missing URL in fal.ai response")
+
+            # Store with appropriate output_index
+            artifact = await context.store_image_result(
+                storage_url=image_url,
+                format=inputs.output_format,
+                width=width,
+                height=height,
+                output_index=idx,
+            )
+            artifacts.append(artifact)
+
+        return GeneratorResult(outputs=artifacts)
+
+    async def estimate_cost(self, inputs: Flux2ProEditInput) -> float:
+        """Estimate cost for FLUX 2 Pro Edit generation.
+
+        Pricing: $0.03 for first megapixel, $0.015 for additional megapixels.
+        Using base cost of $0.03 as default (1 MP output).
+        """
+        # Base cost per generation (1 megapixel default)
+        base_cost = 0.03
+        return base_cost

package/templates/api/src/boards/generators/implementations/fal/image/gemini_25_flash_image.py

@@ -0,0 +1,177 @@
+"""
+Google Gemini 2.5 Flash Image text-to-image generator.
+
+Google's state-of-the-art image generation and editing model available through fal.ai.
+Supports multiple aspect ratios and output formats with batch generation up to 4 images.
+
+Based on Fal AI's fal-ai/gemini-25-flash-image model.
+See: https://fal.ai/models/fal-ai/gemini-25-flash-image
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class Gemini25FlashImageInput(BaseModel):
+    """Input schema for Gemini 2.5 Flash Image generation."""
+
+    prompt: str = Field(
+        description="Text prompt for image generation",
+        min_length=3,
+        max_length=5000,
+    )
+    num_images: int = Field(
+        default=1,
+        ge=1,
+        le=4,
+        description="Number of images to generate (max 4)",
+    )
+    aspect_ratio: Literal[
+        "21:9",
+        "16:9",
+        "3:2",
+        "4:3",
+        "5:4",
+        "1:1",
+        "4:5",
+        "3:4",
+        "2:3",
+        "9:16",
+    ] = Field(
+        default="1:1",
+        description="Image aspect ratio",
+    )
+    output_format: Literal["jpeg", "png", "webp"] = Field(
+        default="png",
+        description="Output image format",
+    )
+    sync_mode: bool = Field(
+        default=False,
+        description="Return media as data URI without request history storage",
+    )
+    limit_generations: bool = Field(
+        default=False,
+        description="Restrict to single generation per round (experimental)",
+    )
+
+
+class FalGemini25FlashImageGenerator(BaseGenerator):
+    """Google Gemini 2.5 Flash Image generator using fal.ai."""
+
+    name = "fal-gemini-25-flash-image"
+    artifact_type = "image"
+    description = "Fal: Gemini 2.5 Flash Image - Google's state-of-the-art text-to-image generation"
+
+    def get_input_schema(self) -> type[Gemini25FlashImageInput]:
+        return Gemini25FlashImageInput
+
+    async def generate(
+        self, inputs: Gemini25FlashImageInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate images using Google Gemini 2.5 Flash Image via fal.ai."""
+        # Check for API key (fal-client uses FAL_KEY environment variable)
+        if not os.getenv("FAL_KEY"):
+            raise ValueError("API configuration invalid. Missing FAL_KEY environment variable")
+
+        # Import fal_client
+        try:
+            import fal_client
+        except ImportError as e:
+            raise ImportError(
+                "fal.ai SDK is required for FalGemini25FlashImageGenerator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Prepare arguments for fal.ai API
+        arguments = {
+            "prompt": inputs.prompt,
+            "num_images": inputs.num_images,
+            "aspect_ratio": inputs.aspect_ratio,
+            "output_format": inputs.output_format,
+            "sync_mode": inputs.sync_mode,
+            "limit_generations": inputs.limit_generations,
+        }
+
+        # Submit async job and get handler
+        handler = await fal_client.submit_async(
+            "fal-ai/gemini-25-flash-image",
+            arguments=arguments,
+        )
+
+        # Store the external job ID for tracking
+        await context.set_external_job_id(handler.request_id)
+
+        # Stream progress updates (sample every 3rd event to avoid spam)
+        from .....progress.models import ProgressUpdate
+
+        event_count = 0
+        async for event in handler.iter_events(with_logs=True):
+            event_count += 1
+
+            # Process every 3rd event to provide feedback without overwhelming
+            if event_count % 3 == 0:
+                # Extract logs if available
+                logs = getattr(event, "logs", None)
+                if logs:
+                    # Join log entries into a single message
+                    if isinstance(logs, list):
+                        message = " | ".join(str(log) for log in logs if log)
+                    else:
+                        message = str(logs)
+
+                    if message:
+                        await context.publish_progress(
+                            ProgressUpdate(
+                                job_id=handler.request_id,
+                                status="processing",
+                                progress=50.0,  # Approximate mid-point progress
+                                phase="processing",
+                                message=message,
+                            )
+                        )
+
+        # Get final result
+        result = await handler.get()
+
+        # Extract image URLs from result
+        # fal.ai returns: {"images": [{"url": "...", "width": ..., "height": ..., ...}, ...]}
+        images = result.get("images", [])
+        if not images:
+            raise ValueError("No images returned from fal.ai API")
+
+        # Store each image using output_index
+        artifacts = []
+        for idx, image_data in enumerate(images):
+            image_url = image_data.get("url")
+            # Use 'or' to handle explicit None values from API
+            width = image_data.get("width") or 1024
+            height = image_data.get("height") or 1024
+
+            if not image_url:
+                raise ValueError(f"Image {idx} missing URL in fal.ai response")
+
+            # Store with appropriate output_index
+            artifact = await context.store_image_result(
+                storage_url=image_url,
+                format=inputs.output_format,
+                width=width,
+                height=height,
+                output_index=idx,
+            )
+            artifacts.append(artifact)
+
+        return GeneratorResult(outputs=artifacts)
+
+    async def estimate_cost(self, inputs: Gemini25FlashImageInput) -> float:
+        """Estimate cost for Gemini 2.5 Flash Image generation.
+
+        TODO: Pricing information not available in fal.ai documentation.
+        This is a placeholder estimate that should be updated when pricing is known.
+        """
+        # Placeholder cost estimate per image (to be updated with actual pricing)
+        cost_per_image = 0.00  # Unknown pricing
+        return cost_per_image * inputs.num_images

package/templates/api/src/boards/generators/implementations/fal/image/gpt_image_1_edit_image.py

@@ -0,0 +1,182 @@
+"""
+fal.ai GPT-Image-1 image editing generator.
+
+Edit images using OpenAI's GPT-Image-1 model via fal.ai.
+Based on Fal AI's fal-ai/gpt-image-1/edit-image model.
+See: https://fal.ai/models/fal-ai/gpt-image-1/edit-image
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....artifacts import ImageArtifact
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class GptImage1EditImageInput(BaseModel):
+    """Input schema for GPT-Image-1 image editing.
+
+    Artifact fields are automatically detected via type introspection
+    and resolved from generation IDs to artifact objects.
+    """
+
+    prompt: str = Field(
+        description="Edit instruction for transforming the input images",
+        min_length=1,
+        max_length=32000,
+    )
+    image_urls: list[ImageArtifact] = Field(
+        description="URLs of images to use as reference for editing",
+        min_length=1,
+    )
+    num_images: int = Field(
+        default=1,
+        ge=1,
+        le=4,
+        description="Number of edited images to generate (1-4)",
+    )
+    image_size: Literal["auto", "1024x1024", "1536x1024", "1024x1536"] = Field(
+        default="auto",
+        description="Size of the output images",
+    )
+    input_fidelity: Literal["low", "high"] = Field(
+        default="low",
+        description="How closely to follow the input image",
+    )
+    quality: Literal["auto", "low", "medium", "high"] = Field(
+        default="auto",
+        description="Quality level of the output images",
+    )
+
+
+class FalGptImage1EditImageGenerator(BaseGenerator):
+    """Generator for OpenAI's GPT-Image-1 image editing via fal.ai."""
+
+    name = "fal-gpt-image-1-edit-image"
+    description = "Fal: GPT-Image-1 Edit - OpenAI's image editing model"
+    artifact_type = "image"
+
+    def get_input_schema(self) -> type[GptImage1EditImageInput]:
+        """Return the input schema for this generator."""
+        return GptImage1EditImageInput
+
+    async def generate(
+        self, inputs: GptImage1EditImageInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate edited images using fal.ai GPT-Image-1."""
+        # Check for API key
+        if not os.getenv("FAL_KEY"):
+            raise ValueError("API configuration invalid. Missing FAL_KEY environment variable")
+
+        # Import fal_client
+        try:
+            import fal_client
+        except ImportError as e:
+            raise ImportError(
+                "fal.ai SDK is required for FalGptImage1EditImageGenerator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Upload image artifacts to Fal's public storage
+        # Fal API requires publicly accessible URLs
+        from ..utils import upload_artifacts_to_fal
+
+        image_urls = await upload_artifacts_to_fal(inputs.image_urls, context)
+
+        # Prepare arguments for fal.ai API
+        arguments = {
+            "prompt": inputs.prompt,
+            "image_urls": image_urls,
+            "num_images": inputs.num_images,
+            "image_size": inputs.image_size,
+            "input_fidelity": inputs.input_fidelity,
+            "quality": inputs.quality,
+        }
+
+        # Submit async job
+        handler = await fal_client.submit_async(
+            "fal-ai/gpt-image-1/edit-image",
+            arguments=arguments,
+        )
+
+        # Store external job ID
+        await context.set_external_job_id(handler.request_id)
+
+        # Stream progress updates
+        from .....progress.models import ProgressUpdate
+
+        event_count = 0
+        async for event in handler.iter_events(with_logs=True):
+            event_count += 1
+            # Sample every 3rd event to avoid spam
+            if event_count % 3 == 0:
+                logs = getattr(event, "logs", None)
+                if logs:
+                    # Join log entries into a single message
+                    if isinstance(logs, list):
+                        message = " | ".join(str(log) for log in logs if log)
+                    else:
+                        message = str(logs)
+
+                    if message:
+                        await context.publish_progress(
+                            ProgressUpdate(
+                                job_id=handler.request_id,
+                                status="processing",
+                                progress=50.0,
+                                phase="processing",
+                                message=message,
+                            )
+                        )
+
+        # Get final result
+        result = await handler.get()
+
+        # Extract images from result
+        # Response structure: {"images": [{"url": "...", "width": 1024, "height": 1024, ...}, ...]}
+        images = result.get("images", [])
+
+        if not images:
+            raise ValueError("No images returned from fal.ai API")
+
+        # Store each image using output_index
+        artifacts = []
+        for idx, image_data in enumerate(images):
+            image_url = image_data.get("url")
+            width = image_data.get("width", 1024)
+            height = image_data.get("height", 1024)
+
+            if not image_url:
+                raise ValueError(f"Image {idx} missing URL in fal.ai response")
+
+            # Determine format from image_size or content_type
+            format = "png"  # GPT-Image-1 typically returns PNG
+            if "content_type" in image_data:
+                content_type = image_data["content_type"]
+                if "jpeg" in content_type:
+                    format = "jpeg"
+                elif "webp" in content_type:
+                    format = "webp"
+
+            artifact = await context.store_image_result(
+                storage_url=image_url,
+                format=format,
+                width=width,
+                height=height,
+                output_index=idx,
+            )
+            artifacts.append(artifact)
+
+        return GeneratorResult(outputs=artifacts)
+
+    async def estimate_cost(self, inputs: GptImage1EditImageInput) -> float:
+        """Estimate cost for GPT-Image-1 edit generation.
+
+        Note: Pricing information not available in documentation.
+        Using estimated cost based on similar OpenAI image models.
+        """
+        # Estimated cost per image (similar to other image editing models)
+        per_image_cost = 0.04
+        return per_image_cost * inputs.num_images