@weirdfingers/baseboards 0.5.2 → 0.6.0

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

@@ -1,19 +1,49 @@
 """Fal.ai image generators."""
 
+from .clarity_upscaler import FalClarityUpscalerGenerator
+from .crystal_upscaler import FalCrystalUpscalerGenerator
+from .fal_ideogram_character import FalIdeogramCharacterGenerator
+from .flux_2 import FalFlux2Generator
+from .flux_2_edit import FalFlux2EditGenerator
+from .flux_2_pro import FalFlux2ProGenerator
+from .flux_2_pro_edit import FalFlux2ProEditGenerator
 from .flux_pro_kontext import FalFluxProKontextGenerator
 from .flux_pro_ultra import FalFluxProUltraGenerator
+from .gemini_25_flash_image import FalGemini25FlashImageGenerator
+from .gpt_image_1_edit_image import FalGptImage1EditImageGenerator
+from .gpt_image_1_mini import FalGptImage1MiniGenerator
+from .ideogram_character_edit import FalIdeogramCharacterEditGenerator
+from .ideogram_v2 import FalIdeogramV2Generator
 from .imagen4_preview import FalImagen4PreviewGenerator
 from .imagen4_preview_fast import FalImagen4PreviewFastGenerator
 from .nano_banana import FalNanoBananaGenerator
 from .nano_banana_edit import FalNanoBananaEditGenerator
 from .nano_banana_pro import FalNanoBananaProGenerator
+from .nano_banana_pro_edit import FalNanoBananaProEditGenerator
+from .qwen_image import FalQwenImageGenerator
+from .qwen_image_edit import FalQwenImageEditGenerator
 
 __all__ = [
+    "FalClarityUpscalerGenerator",
+    "FalCrystalUpscalerGenerator",
+    "FalFlux2Generator",
+    "FalFlux2EditGenerator",
+    "FalFlux2ProGenerator",
+    "FalFlux2ProEditGenerator",
     "FalFluxProKontextGenerator",
     "FalFluxProUltraGenerator",
+    "FalGemini25FlashImageGenerator",
+    "FalGptImage1EditImageGenerator",
+    "FalGptImage1MiniGenerator",
+    "FalIdeogramCharacterGenerator",
+    "FalIdeogramCharacterEditGenerator",
+    "FalIdeogramV2Generator",
     "FalImagen4PreviewGenerator",
     "FalImagen4PreviewFastGenerator",
     "FalNanoBananaGenerator",
     "FalNanoBananaEditGenerator",
     "FalNanoBananaProGenerator",
+    "FalNanoBananaProEditGenerator",
+    "FalQwenImageEditGenerator",
+    "FalQwenImageGenerator",
 ]

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

@@ -0,0 +1,220 @@
+"""
+fal.ai clarity-upscaler image upscaling generator.
+
+Upscale images with high fidelity using fal.ai's clarity-upscaler model.
+Supports upscaling factors from 1x to 4x with configurable creativity and resemblance.
+"""
+
+import os
+
+from pydantic import BaseModel, Field
+
+from ....artifacts import ImageArtifact
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class ClarityUpscalerInput(BaseModel):
+    """Input schema for clarity upscaler.
+
+    Artifact fields (like image_url) are automatically detected via type
+    introspection and resolved from generation IDs to ImageArtifact objects.
+    """
+
+    image_url: ImageArtifact = Field(
+        description="The input image to upscale (from a previous generation)"
+    )
+    prompt: str = Field(
+        default="masterpiece, best quality, highres",
+        description="Descriptive text guiding the upscaling generation",
+    )
+    upscale_factor: float = Field(
+        default=2.0,
+        ge=1.0,
+        le=4.0,
+        description="Scaling multiplier for the upscaling (1-4x)",
+    )
+    negative_prompt: str = Field(
+        default="(worst quality, low quality, normal quality:2)",
+        description="Text describing unwanted details in the output",
+    )
+    creativity: float = Field(
+        default=0.35,
+        ge=0.0,
+        le=1.0,
+        description="Deviation from prompt strength (0-1)",
+    )
+    resemblance: float = Field(
+        default=0.6,
+        ge=0.0,
+        le=1.0,
+        description="The strength of the ControlNet for fidelity to original (0-1)",
+    )
+    guidance_scale: float = Field(
+        default=4.0,
+        ge=0.0,
+        le=20.0,
+        description="CFG scale for prompt adherence (0-20)",
+    )
+    num_inference_steps: int = Field(
+        default=18,
+        ge=4,
+        le=50,
+        description="Number of processing iterations (4-50)",
+    )
+    seed: int | None = Field(
+        default=None,
+        description="Random seed for reproducibility",
+    )
+    enable_safety_checker: bool = Field(
+        default=True,
+        description="Enable content filtering",
+    )
+
+
+class FalClarityUpscalerGenerator(BaseGenerator):
+    """Clarity upscaler generator using fal.ai."""
+
+    name = "fal-clarity-upscaler"
+    artifact_type = "image"
+    description = "Fal: Clarity upscaler - High fidelity image upscaling (1-4x)"
+
+    def get_input_schema(self) -> type[ClarityUpscalerInput]:
+        return ClarityUpscalerInput
+
+    async def generate(
+        self, inputs: ClarityUpscalerInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Upscale images using fal.ai clarity-upscaler 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 FalClarityUpscalerGenerator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Upload image artifact 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
+
+        # upload_artifacts_to_fal expects a list, so wrap the single image
+        image_urls = await upload_artifacts_to_fal([inputs.image_url], context)
+        image_url = image_urls[0]  # Extract the single URL
+
+        # Prepare arguments for fal.ai API
+        arguments = {
+            "image_url": image_url,
+            "prompt": inputs.prompt,
+            "upscale_factor": inputs.upscale_factor,
+            "negative_prompt": inputs.negative_prompt,
+            "creativity": inputs.creativity,
+            "resemblance": inputs.resemblance,
+            "guidance_scale": inputs.guidance_scale,
+            "num_inference_steps": inputs.num_inference_steps,
+            "enable_safety_checker": inputs.enable_safety_checker,
+        }
+
+        # Add seed if provided
+        if inputs.seed is not None:
+            arguments["seed"] = inputs.seed
+
+        # Submit async job and get handler
+        handler = await fal_client.submit_async(
+            "fal-ai/clarity-upscaler",
+            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 from result
+        # fal.ai returns: {
+        #   "image": {"url": "...", "width": ..., "height": ...},
+        #   "seed": 12345,
+        #   "timings": {...}
+        # }
+        image_data = result.get("image")
+
+        if not image_data:
+            raise ValueError("No image returned from fal.ai API")
+
+        image_url = image_data.get("url")
+        if not image_url:
+            raise ValueError("Image missing URL in fal.ai response")
+
+        # Extract dimensions if available
+        width = image_data.get("width")
+        height = image_data.get("height")
+
+        # If dimensions are not in the response, calculate from upscale factor
+        if width is None or height is None:
+            # Use original image dimensions multiplied by upscale factor
+            original_width = inputs.image_url.width
+            original_height = inputs.image_url.height
+            if original_width and original_height:
+                width = int(original_width * inputs.upscale_factor)
+                height = int(original_height * inputs.upscale_factor)
+            else:
+                # Fallback to reasonable defaults
+                width = 2048
+                height = 2048
+
+        # Store the upscaled image
+        artifact = await context.store_image_result(
+            storage_url=image_url,
+            format="png",  # Clarity upscaler outputs PNG
+            width=width,
+            height=height,
+            output_index=0,
+        )
+
+        return GeneratorResult(outputs=[artifact])
+
+    async def estimate_cost(self, inputs: ClarityUpscalerInput) -> float:
+        """Estimate cost for clarity upscaler generation.
+
+        Based on typical Fal image upscaling model pricing.
+        """
+        # Estimated cost per upscale operation
+        # Using a conservative estimate based on similar Fal upscaling models
+        return 0.05

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

@@ -0,0 +1,173 @@
+"""
+fal.ai Crystal Upscaler - Advanced image enhancement for facial details and portraits.
+
+Upscales images with specialized enhancement for facial details using Clarity AI's
+upscaling technology. Supports scale factors from 1x to 200x.
+
+Based on Fal AI's fal-ai/crystal-upscaler model.
+See: https://fal.ai/models/fal-ai/crystal-upscaler
+"""
+
+import os
+
+from pydantic import BaseModel, Field
+
+from ....artifacts import ImageArtifact
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class CrystalUpscalerInput(BaseModel):
+    """Input schema for crystal-upscaler.
+
+    Artifact fields (like image_url) are automatically detected via type
+    introspection and resolved from generation IDs to ImageArtifact objects.
+    """
+
+    image_url: ImageArtifact = Field(
+        description="Input image to upscale (from a previous generation)"
+    )
+    scale_factor: int = Field(
+        default=2,
+        ge=1,
+        le=200,
+        description="Scale factor for upscaling (1-200)",
+    )
+
+
+class FalCrystalUpscalerGenerator(BaseGenerator):
+    """Crystal Upscaler generator using fal.ai."""
+
+    name = "fal-crystal-upscaler"
+    artifact_type = "image"
+    description = "Fal: Crystal Upscaler - Advanced image enhancement for facial details"
+
+    def get_input_schema(self) -> type[CrystalUpscalerInput]:
+        return CrystalUpscalerInput
+
+    async def generate(
+        self, inputs: CrystalUpscalerInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Upscale image using fal.ai crystal-upscaler 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 FalCrystalUpscalerGenerator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Upload image artifact 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
+
+        # upload_artifacts_to_fal expects a list, returns a list
+        image_urls = await upload_artifacts_to_fal([inputs.image_url], context)
+        image_url = image_urls[0]
+
+        # Prepare arguments for fal.ai API
+        arguments = {
+            "image_url": image_url,
+            "scale_factor": inputs.scale_factor,
+        }
+
+        # Submit async job and get handler
+        handler = await fal_client.submit_async(
+            "fal-ai/crystal-upscaler",
+            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")
+            # Extract dimensions from response
+            width = image_data.get("width")
+            height = image_data.get("height")
+
+            if not image_url:
+                raise ValueError(f"Image {idx} missing URL in fal.ai response")
+
+            # Determine format from content_type or use png as default
+            content_type = image_data.get("content_type", "image/png")
+            format_map = {
+                "image/jpeg": "jpeg",
+                "image/jpg": "jpeg",
+                "image/png": "png",
+                "image/webp": "webp",
+            }
+            format = format_map.get(content_type, "png")
+
+            # Store with appropriate output_index
+            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: CrystalUpscalerInput) -> float:
+        """Estimate cost for crystal upscaler generation.
+
+        Using a conservative estimate for image upscaling operations.
+        Actual cost may vary based on image size and scale factor.
+        """
+        # Base cost per upscale operation
+        # Higher scale factors may cost more, but using fixed cost for now
+        base_cost = 0.05
+        return base_cost

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

@@ -0,0 +1,227 @@
+"""
+Ideogram V3 Character generator - Generate consistent character appearances.
+
+This generator creates images with consistent character appearances across multiple
+generations, maintaining facial features, proportions, and distinctive traits for
+cohesive storytelling and branding purposes.
+
+Based on Fal AI's fal-ai/ideogram/character model.
+See: https://fal.ai/models/fal-ai/ideogram/character
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from .....generators.artifacts import ImageArtifact
+from .....generators.base import (
+    BaseGenerator,
+    GeneratorExecutionContext,
+    GeneratorResult,
+)
+from .....progress.models import ProgressUpdate
+
+
+class IdeogramCharacterInput(BaseModel):
+    """Input schema for fal-ideogram-character.
+
+    Artifact fields are automatically detected via type introspection
+    and resolved from generation IDs to artifact objects.
+    """
+
+    prompt: str = Field(
+        description="The prompt to fill the masked part of the image. Describe the scene, "
+        "setting, and action for the character."
+    )
+    reference_image_urls: list[ImageArtifact] = Field(
+        description="A set of images to use as character references. Currently only 1 image "
+        "is supported, rest will be ignored. Maximum total size 10MB across all character "
+        "references. The images should be in JPEG, PNG or WebP format.",
+        min_length=1,
+    )
+    image_size: str | dict[str, int] = Field(
+        default="square_hd",
+        description="Size preset (square_hd, square, portrait_4_3, portrait_16_9, "
+        "landscape_4_3, landscape_16_9) or custom dimensions with width and height.",
+    )
+    style: Literal["AUTO", "REALISTIC", "FICTION"] = Field(
+        default="AUTO",
+        description="The style preset to use for generation.",
+    )
+    expand_prompt: bool = Field(
+        default=True,
+        description="Determine if MagicPrompt should be used in generating the request or not.",
+    )
+    rendering_speed: Literal["TURBO", "BALANCED", "QUALITY"] = Field(
+        default="BALANCED",
+        description="The speed/quality tradeoff for generation. TURBO is fastest but lower "
+        "quality, QUALITY is slowest but highest quality.",
+    )
+    num_images: int = Field(
+        default=1,
+        ge=1,
+        le=8,
+        description="Number of images to generate (1-8).",
+    )
+    negative_prompt: str | None = Field(
+        default=None,
+        description="Things to exclude from the generation.",
+    )
+    sync_mode: bool = Field(
+        default=False,
+        description="If true, returns data URI instead of URL.",
+    )
+    seed: int | None = Field(
+        default=None,
+        description="Random number generator seed for reproducible results.",
+    )
+    reference_mask_urls: list[ImageArtifact] | None = Field(
+        default=None,
+        description="Masking images to refine character editing. Maximum 10MB total size. "
+        "Currently only 1 mask is supported.",
+    )
+    image_urls: list[ImageArtifact] | None = Field(
+        default=None,
+        description="Style reference images. Maximum 10MB total size.",
+    )
+    style_codes: list[str] | None = Field(
+        default=None,
+        description="8-character hexadecimal style codes for custom styles.",
+    )
+    color_palette: dict[str, str | list[dict[str, int]]] | None = Field(
+        default=None,
+        description="Color palette preset (EMBER, FRESH, JUNGLE, MAGIC, MELON, MOSAIC, "
+        "PASTEL, ULTRAMARINE) or custom RGB members.",
+    )
+
+
+class FalIdeogramCharacterGenerator(BaseGenerator):
+    """Generator for consistent character appearance generation."""
+
+    name = "fal-ideogram-character"
+    description = (
+        "Generate consistent character appearances across multiple images. Maintains facial "
+        "features, proportions, and distinctive traits for cohesive storytelling and branding."
+    )
+    artifact_type = "image"
+
+    def get_input_schema(self) -> type[IdeogramCharacterInput]:
+        """Return the input schema for this generator."""
+        return IdeogramCharacterInput
+
+    async def generate(
+        self, inputs: IdeogramCharacterInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate images with consistent character appearance using fal.ai ideogram/character."""
+        # 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 FalIdeogramCharacterGenerator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Upload artifact inputs to Fal's storage
+        from ..utils import upload_artifacts_to_fal
+
+        reference_image_urls = await upload_artifacts_to_fal(inputs.reference_image_urls, context)
+
+        # Prepare arguments for fal.ai API
+        arguments: dict = {
+            "prompt": inputs.prompt,
+            "reference_image_urls": reference_image_urls,
+            "image_size": inputs.image_size,
+            "style": inputs.style,
+            "expand_prompt": inputs.expand_prompt,
+            "rendering_speed": inputs.rendering_speed,
+            "num_images": inputs.num_images,
+            "sync_mode": inputs.sync_mode,
+        }
+
+        # Add optional parameters if provided
+        if inputs.negative_prompt is not None:
+            arguments["negative_prompt"] = inputs.negative_prompt
+        if inputs.seed is not None:
+            arguments["seed"] = inputs.seed
+        if inputs.reference_mask_urls is not None:
+            arguments["reference_mask_urls"] = await upload_artifacts_to_fal(
+                inputs.reference_mask_urls, context
+            )
+        if inputs.image_urls is not None:
+            arguments["image_urls"] = await upload_artifacts_to_fal(inputs.image_urls, context)
+        if inputs.style_codes is not None:
+            arguments["style_codes"] = inputs.style_codes
+        if inputs.color_palette is not None:
+            arguments["color_palette"] = inputs.color_palette
+
+        # Submit async job
+        handler = await fal_client.submit_async(
+            "fal-ai/ideogram/character",
+            arguments=arguments,
+        )
+
+        # Store external job ID
+        await context.set_external_job_id(handler.request_id)
+
+        # Stream progress updates
+        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:
+                await context.publish_progress(
+                    ProgressUpdate(
+                        job_id="",  # Will be populated by context
+                        status="processing",
+                        progress=0.5,
+                        phase="processing",
+                    )
+                )
+
+        # Get final result
+        result = await handler.get()
+
+        # Extract outputs from result and store artifacts
+        artifacts = []
+        images = result.get("images", [])
+
+        for idx, image_data in enumerate(images):
+            # Determine image format from content_type or URL
+            content_type = image_data.get("content_type", "image/png")
+            image_format = content_type.split("/")[-1] if "/" in content_type else "png"
+
+            # Store image artifact
+            artifact = await context.store_image_result(
+                storage_url=image_data["url"],
+                format=image_format,
+                # Image dimensions are not provided in response, use defaults based on size
+                width=1024,  # Will be updated when image is downloaded
+                height=1024,
+                output_index=idx,
+            )
+            artifacts.append(artifact)
+
+        return GeneratorResult(outputs=artifacts)
+
+    async def estimate_cost(self, inputs: IdeogramCharacterInput) -> float:
+        """Estimate cost for this generation in USD.
+
+        Pricing based on rendering speed:
+        - TURBO: $0.10 per image
+        - BALANCED: $0.15 per image
+        - QUALITY: $0.20 per image
+        """
+        cost_per_image = {
+            "TURBO": 0.10,
+            "BALANCED": 0.15,
+            "QUALITY": 0.20,
+        }
+
+        base_cost = cost_per_image.get(inputs.rendering_speed, 0.15)
+        return base_cost * inputs.num_images