@weirdfingers/baseboards 0.5.3 → 0.6.1

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

@@ -0,0 +1,203 @@
+"""
+fal.ai FLUX.2 [dev] text-to-image generator.
+
+High-quality image generation using fal.ai's FLUX.2 [dev] model from Black Forest Labs.
+Features enhanced realism, crisper text generation, and configurable acceleration.
+
+See: https://fal.ai/models/fal-ai/flux-2
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class Flux2Input(BaseModel):
+    """Input schema for FLUX.2 [dev] image generation."""
+
+    prompt: str = Field(description="The text prompt for image generation")
+    num_images: int = Field(
+        default=1,
+        ge=1,
+        le=4,
+        description="Number of images to generate in batch (max 4)",
+    )
+    image_size: Literal[
+        "square_hd",
+        "square",
+        "portrait_4_3",
+        "portrait_16_9",
+        "landscape_4_3",
+        "landscape_16_9",
+    ] = Field(
+        default="landscape_4_3",
+        description="Predefined image size/aspect ratio",
+    )
+    acceleration: Literal["none", "regular", "high"] = Field(
+        default="regular",
+        description="Processing speed level (none = highest quality, high = fastest)",
+    )
+    output_format: Literal["jpeg", "png", "webp"] = Field(
+        default="png",
+        description="Output image format",
+    )
+    enable_prompt_expansion: bool = Field(
+        default=False,
+        description="Enhance prompt automatically for better results",
+    )
+    enable_safety_checker: bool = Field(
+        default=True,
+        description="Enable safety checker to filter NSFW content",
+    )
+    guidance_scale: float = Field(
+        default=2.5,
+        ge=0.0,
+        le=20.0,
+        description="Adherence strength to input prompt (0-20)",
+    )
+    num_inference_steps: int = Field(
+        default=28,
+        ge=4,
+        le=50,
+        description="Number of inference steps (4-50, higher = better quality but slower)",
+    )
+    seed: int | None = Field(
+        default=None,
+        description="Random seed for reproducibility (optional)",
+    )
+    sync_mode: bool = Field(
+        default=True,
+        description="Use synchronous mode (wait for completion)",
+    )
+
+
+class FalFlux2Generator(BaseGenerator):
+    """FLUX.2 [dev] image generator using fal.ai."""
+
+    name = "fal-flux-2"
+    artifact_type = "image"
+    description = (
+        "Fal: FLUX.2 [dev] - enhanced realism, crisper text generation, "
+        "and native editing capabilities from Black Forest Labs"
+    )
+
+    def get_input_schema(self) -> type[Flux2Input]:
+        return Flux2Input
+
+    async def generate(
+        self, inputs: Flux2Input, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate images using fal.ai FLUX.2 [dev] 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 FalFlux2Generator. "
+                "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,
+            "image_size": inputs.image_size,
+            "acceleration": inputs.acceleration,
+            "output_format": inputs.output_format,
+            "enable_prompt_expansion": inputs.enable_prompt_expansion,
+            "enable_safety_checker": inputs.enable_safety_checker,
+            "guidance_scale": inputs.guidance_scale,
+            "num_inference_steps": inputs.num_inference_steps,
+            "sync_mode": inputs.sync_mode,
+        }
+
+        # 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/flux-2",
+            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")
+            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: Flux2Input) -> float:
+        """Estimate cost for FLUX.2 [dev] generation.
+
+        FLUX.2 [dev] pricing is approximately $0.055 per image based on
+        typical FLUX model pricing. Cost varies slightly based on
+        acceleration level and inference steps.
+        """
+        # Approximate cost per image
+        cost_per_image = 0.055
+        return cost_per_image * inputs.num_images

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

@@ -0,0 +1,230 @@
+"""
+fal.ai FLUX.2 [dev] Edit image-to-image editing generator.
+
+Edit images using fal.ai's flux-2/edit model, enabling precise modifications
+using natural language descriptions and hex color control.
+Based on Black Forest Labs' FLUX.2 [dev] model.
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....artifacts import ImageArtifact
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class Flux2EditImageSize(BaseModel):
+    """Custom image size configuration."""
+
+    width: int = Field(ge=512, le=2048, description="Image width (512-2048)")
+    height: int = Field(ge=512, le=2048, description="Image height (512-2048)")
+
+
+class Flux2EditInput(BaseModel):
+    """Input schema for FLUX.2 [dev] Edit image editing.
+
+    Artifact fields (like image_sources) are automatically detected via type
+    introspection and resolved from generation IDs to ImageArtifact objects.
+    """
+
+    prompt: str = Field(
+        description="Editing instruction (e.g., 'Change his clothes to casual suit and tie')"
+    )
+    image_sources: list[ImageArtifact] = Field(
+        description="List of input images for editing (max 3 images)",
+        min_length=1,
+        max_length=3,
+    )
+    num_images: int = Field(
+        default=1,
+        ge=1,
+        le=4,
+        description="Number of output images to generate (1-4)",
+    )
+    image_size: (
+        Literal["square_hd", "portrait_4_3", "landscape_16_9"] | Flux2EditImageSize | None
+    ) = Field(
+        default=None,
+        description=(
+            "Output image size - predefined (square_hd, portrait_4_3, landscape_16_9) "
+            "or custom dimensions"
+        ),
+    )
+    acceleration: Literal["none", "regular", "high"] = Field(
+        default="regular",
+        description="Acceleration mode for generation speed/quality tradeoff",
+    )
+    num_inference_steps: int = Field(
+        default=28,
+        ge=4,
+        le=50,
+        description="Number of inference steps (4-50, higher = better quality but slower)",
+    )
+    output_format: Literal["jpeg", "png", "webp"] = Field(
+        default="png",
+        description="Output image format",
+    )
+    guidance_scale: float = Field(
+        default=2.5,
+        ge=0.0,
+        le=20.0,
+        description="Guidance scale for generation (0-20)",
+    )
+    seed: int | None = Field(
+        default=None,
+        description="Random seed for reproducible outputs",
+    )
+    enable_prompt_expansion: bool = Field(
+        default=False,
+        description="Enable automatic prompt expansion for better results",
+    )
+    enable_safety_checker: bool = Field(
+        default=True,
+        description="Enable safety checker to filter NSFW content",
+    )
+    sync_mode: bool = Field(
+        default=False,
+        description="If True, return data URI instead of URL (output won't be in request history)",
+    )
+
+
+class FalFlux2EditGenerator(BaseGenerator):
+    """FLUX.2 [dev] Edit image-to-image generator using fal.ai."""
+
+    name = "fal-flux-2-edit"
+    artifact_type = "image"
+    description = "Fal: FLUX.2 [dev] Edit - Precise image editing with natural language"
+
+    def get_input_schema(self) -> type[Flux2EditInput]:
+        return Flux2EditInput
+
+    async def generate(
+        self, inputs: Flux2EditInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Edit images using fal.ai flux-2/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 FalFlux2EditGenerator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Upload image artifacts to Fal's public storage
+        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[str, object] = {
+            "prompt": inputs.prompt,
+            "image_urls": image_urls,
+            "num_images": inputs.num_images,
+            "acceleration": inputs.acceleration,
+            "num_inference_steps": inputs.num_inference_steps,
+            "output_format": inputs.output_format,
+            "guidance_scale": inputs.guidance_scale,
+            "enable_prompt_expansion": inputs.enable_prompt_expansion,
+            "enable_safety_checker": inputs.enable_safety_checker,
+            "sync_mode": inputs.sync_mode,
+        }
+
+        # Add optional fields if provided
+        if inputs.image_size is not None:
+            if isinstance(inputs.image_size, str):
+                arguments["image_size"] = inputs.image_size
+            else:
+                # Custom size object
+                arguments["image_size"] = {
+                    "width": inputs.image_size.width,
+                    "height": inputs.image_size.height,
+                }
+
+        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/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": ...}, ...]}
+        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_result = image_data.get("url")
+            width = image_data.get("width", 1024)
+            height = image_data.get("height", 1024)
+
+            if not image_url_result:
+                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_result,
+                format=inputs.output_format,
+                width=width,
+                height=height,
+                output_index=idx,
+            )
+            artifacts.append(artifact)
+
+        return GeneratorResult(outputs=artifacts)
+
+    async def estimate_cost(self, inputs: Flux2EditInput) -> float:
+        """Estimate cost for FLUX.2 Edit generation.
+
+        FLUX.2 [dev] Edit is a premium image editing model. Estimated cost
+        is approximately $0.06 per image based on similar Flux models.
+        """
+        # Cost per image * number of images
+        cost_per_image = 0.06
+        return cost_per_image * inputs.num_images

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

@@ -0,0 +1,204 @@
+"""
+fal.ai FLUX.2 [pro] text-to-image generator.
+
+Production-optimized generation with professional quality out of the box.
+Studio-grade images through a streamlined pipeline that prioritizes consistency
+and speed over parameter tuning.
+
+Based on Fal AI's fal-ai/flux-2-pro model.
+See: https://fal.ai/models/fal-ai/flux-2-pro
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class Flux2ProInput(BaseModel):
+    """Input schema for FLUX.2 [pro] image generation.
+
+    Note: FLUX.2 [pro] is designed for zero-configuration quality with
+    no inference steps or guidance parameters to adjust.
+    """
+
+    prompt: str = Field(description="Text prompt for image generation")
+    image_size: Literal[
+        "square_hd",
+        "square",
+        "portrait_4_3",
+        "portrait_16_9",
+        "landscape_4_3",
+        "landscape_16_9",
+    ] = Field(
+        default="landscape_4_3",
+        description="Image size preset. Available presets: square_hd, square, "
+        "portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9",
+    )
+    output_format: Literal["jpeg", "png"] = Field(
+        default="jpeg",
+        description="Output image format. JPEG for optimized file sizes, PNG for lossless quality",
+    )
+    safety_tolerance: Literal["1", "2", "3", "4", "5"] = Field(
+        default="2",
+        description="Safety tolerance level (1 = most strict, 5 = most permissive)",
+    )
+    enable_safety_checker: bool = Field(
+        default=True,
+        description="Enable safety checker to filter unsafe content",
+    )
+    seed: int | None = Field(
+        default=None,
+        description="Random seed for reproducible generation (optional)",
+    )
+    sync_mode: bool = Field(
+        default=True,
+        description="Use synchronous mode (wait for completion)",
+    )
+
+
+# Approximate megapixels for each preset
+_SIZE_MEGAPIXELS = {
+    "square_hd": 1.5,  # ~1408x1408 (typical HD square)
+    "square": 1.0,  # ~1024x1024
+    "portrait_4_3": 1.0,  # ~768x1024
+    "portrait_16_9": 1.0,  # ~576x1024
+    "landscape_4_3": 1.0,  # ~1024x768
+    "landscape_16_9": 1.0,  # ~1024x576
+}
+
+
+class FalFlux2ProGenerator(BaseGenerator):
+    """FLUX.2 [pro] image generator using fal.ai.
+
+    Production-optimized generation with professional quality out of the box.
+    Zero-configuration quality with no inference steps or guidance parameters
+    to adjust. Predictable results across batch generations.
+    """
+
+    name = "fal-flux-2-pro"
+    artifact_type = "image"
+    description = "Fal: FLUX.2 [pro] - production-optimized text-to-image with studio-grade quality"
+
+    def get_input_schema(self) -> type[Flux2ProInput]:
+        return Flux2ProInput
+
+    async def generate(
+        self, inputs: Flux2ProInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate image using fal.ai FLUX.2 [pro] 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 FalFlux2ProGenerator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Prepare arguments for fal.ai API
+        arguments = {
+            "prompt": inputs.prompt,
+            "image_size": inputs.image_size,
+            "output_format": inputs.output_format,
+            "safety_tolerance": inputs.safety_tolerance,
+            "enable_safety_checker": inputs.enable_safety_checker,
+            "sync_mode": inputs.sync_mode,
+        }
+
+        # 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/flux-2-pro",
+            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")
+            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: Flux2ProInput) -> float:
+        """Estimate cost for FLUX.2 [pro] generation.
+
+        FLUX.2 [pro] billing is based on megapixels (rounded up):
+        - $0.03 for the first megapixel
+        - $0.015 per additional megapixel
+
+        For preset sizes, we estimate based on typical dimensions.
+        """
+        megapixels = _SIZE_MEGAPIXELS.get(inputs.image_size, 1.0)
+
+        # First megapixel is $0.03, each additional is $0.015
+        if megapixels <= 1:
+            return 0.03
+        else:
+            additional_megapixels = megapixels - 1
+            return 0.03 + (additional_megapixels * 0.015)