@weirdfingers/baseboards 0.2.1 → 0.4.0

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

@@ -0,0 +1,183 @@
+"""
+fal.ai nano-banana text-to-image generator.
+
+Fast image generation using fal.ai's nano-banana model with support for batch outputs.
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class NanoBananaInput(BaseModel):
+    """Input schema for nano-banana image generation."""
+
+    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 aspect ratio and resolution",
+    )
+    num_inference_steps: int = Field(
+        default=4,
+        ge=1,
+        le=50,
+        description="Number of inference steps (more steps = higher quality but slower)",
+    )
+    guidance_scale: float = Field(
+        default=3.5,
+        ge=1.0,
+        le=20.0,
+        description="Guidance scale for prompt adherence",
+    )
+    num_images: int = Field(
+        default=1,
+        ge=1,
+        le=10,
+        description="Number of images to generate in batch",
+    )
+    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 reproducibility (optional)",
+    )
+    sync_mode: bool = Field(
+        default=True,
+        description="Use synchronous mode (wait for completion)",
+    )
+    output_format: Literal["jpeg", "png"] = Field(
+        default="jpeg",
+        description="Output image format",
+    )
+
+
+class FalNanoBananaGenerator(BaseGenerator):
+    """nano-banana image generator using fal.ai."""
+
+    name = "fal-nano-banana"
+    artifact_type = "image"
+    description = "Fal: nano-banana - fast text-to-image generation with batch support"
+
+    def get_input_schema(self) -> type[NanoBananaInput]:
+        return NanoBananaInput
+
+    async def generate(
+        self, inputs: NanoBananaInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate images using fal.ai nano-banana 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 NanoBananaGenerator. "
+                "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,
+            "num_inference_steps": inputs.num_inference_steps,
+            "guidance_scale": inputs.guidance_scale,
+            "num_images": inputs.num_images,
+            "enable_safety_checker": inputs.enable_safety_checker,
+            "sync_mode": inputs.sync_mode,
+            "output_format": inputs.output_format,
+        }
+
+        # 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/nano-banana",
+            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")
+            height = image_data.get("height")
+
+            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: NanoBananaInput) -> float:
+        """Estimate cost for nano-banana generation.
+
+        nano-banana typically costs around $0.003 per image.
+        """
+        return 0.003 * inputs.num_images  # $0.003 per image, scaled by batch size

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

@@ -0,0 +1,212 @@
+"""
+fal.ai nano-banana image-to-image editing generator.
+
+Edit images using fal.ai's nano-banana/edit model (powered by Gemini).
+Supports editing multiple input images with a text prompt.
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....artifacts import ImageArtifact
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class NanoBananaEditInput(BaseModel):
+    """Input schema for nano-banana 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="The prompt for image editing")
+    image_sources: list[ImageArtifact] = Field(
+        description="List of input images for editing (from previous generations)",
+        min_length=1,
+    )
+    num_images: int = Field(
+        default=1,
+        ge=1,
+        le=10,
+        description="Number of images to generate",
+    )
+    output_format: Literal["jpeg", "png", "webp"] = Field(
+        default="jpeg",
+        description="Output image format",
+    )
+    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"
+        ),
+    )
+    limit_generations: bool = Field(
+        default=False,
+        description=(
+            "Experimental parameter to limit the number of generations from each "
+            "round of prompting to 1. Set to True to disregard any instructions in "
+            "the prompt regarding the number of images to generate"
+        ),
+    )
+    aspect_ratio: (
+        Literal[
+            "21:9",
+            "1:1",
+            "4:3",
+            "3:2",
+            "2:3",
+            "5:4",
+            "4:5",
+            "3:4",
+            "16:9",
+            "9:16",
+        ]
+        | None
+    ) = Field(
+        default=None,
+        description=(
+            "Aspect ratio for generated images. Default is None, which takes one "
+            "of the input images' aspect ratio"
+        ),
+    )
+
+
+class FalNanoBananaEditGenerator(BaseGenerator):
+    """nano-banana image editing generator using fal.ai."""
+
+    name = "fal-nano-banana-edit"
+    artifact_type = "image"
+    description = "Fal: nano-banana edit - AI-powered image editing with Gemini"
+
+    def get_input_schema(self) -> type[NanoBananaEditInput]:
+        return NanoBananaEditInput
+
+    async def generate(
+        self, inputs: NanoBananaEditInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Edit images using fal.ai nano-banana/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 FalNanoBananaEditGenerator. "
+                "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 = {
+            "prompt": inputs.prompt,
+            "image_urls": image_urls,
+            "num_images": inputs.num_images,
+            "output_format": inputs.output_format,
+            "sync_mode": inputs.sync_mode,
+            "limit_generations": inputs.limit_generations,
+        }
+
+        # Add aspect_ratio if provided
+        if inputs.aspect_ratio is not None:
+            arguments["aspect_ratio"] = inputs.aspect_ratio
+
+        # Submit async job and get handler
+        handler = await fal_client.submit_async(
+            "fal-ai/nano-banana/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 and description from result
+        # fal.ai returns: {
+        #   "images": [{"url": "...", ...}, ...],
+        #   "description": "Text description from Gemini"
+        # }
+        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
+            # Note: The Gemini description from the API response (result.get("description"))
+            # is not currently stored with the artifact. Consider extending ImageArtifact
+            # to support metadata in the future.
+            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: NanoBananaEditInput) -> float:
+        """Estimate cost for nano-banana edit generation.
+
+        nano-banana/edit uses Gemini for image editing, which has variable costs
+        depending on input complexity. Using a conservative estimate.
+        """
+        # Base cost per edit operation + per-image multiplier
+        per_image_cost = 0.039
+        return per_image_cost * inputs.num_images

package/templates/api/src/boards/generators/implementations/fal/utils.py

@@ -0,0 +1,61 @@
+"""
+Shared utilities for Fal.ai generators.
+
+Provides helper functions for common operations across Fal generators.
+"""
+
+import asyncio
+
+from ...artifacts import AudioArtifact, DigitalArtifact, ImageArtifact, VideoArtifact
+from ...base import GeneratorExecutionContext
+
+
+async def upload_artifacts_to_fal[T: DigitalArtifact](
+    artifacts: list[ImageArtifact] | list[VideoArtifact] | list[AudioArtifact] | list[T],
+    context: GeneratorExecutionContext,
+) -> list[str]:
+    """
+    Upload artifacts to Fal's temporary storage for use in API requests.
+
+    Fal API endpoints require publicly accessible URLs for file inputs. Since our
+    storage URLs might be local or private (localhost, private S3 buckets, etc.),
+    we need to:
+    1. Resolve each artifact to a local file path
+    2. Upload to Fal's public temporary storage
+    3. Get back publicly accessible URLs
+
+    Args:
+        artifacts: List of artifacts (image, video, or audio) to upload
+        context: Generator execution context for artifact resolution
+
+    Returns:
+        List of publicly accessible URLs from Fal storage
+
+    Raises:
+        ImportError: If fal_client is not installed
+        Any exceptions from file resolution or upload are propagated
+    """
+    # Import fal_client
+    try:
+        import fal_client
+    except ImportError as e:
+        raise ImportError(
+            "fal.ai SDK is required for Fal generators. "
+            "Install with: pip install weirdfingers-boards[generators-fal]"
+        ) from e
+
+    async def upload_single_artifact(artifact: DigitalArtifact) -> str:
+        """Upload a single artifact and return its public URL."""
+        # Resolve artifact to local file path (downloads if needed)
+        file_path_str = await context.resolve_artifact(artifact)
+
+        # Upload to Fal's temporary storage and get public URL
+        # fal_client.upload_file_async expects a file path
+        url = await fal_client.upload_file_async(file_path_str)  # type: ignore[arg-type]
+
+        return url
+
+    # Upload all artifacts in parallel for performance
+    urls = await asyncio.gather(*[upload_single_artifact(artifact) for artifact in artifacts])
+
+    return list(urls)

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

@@ -0,0 +1,13 @@
+"""Fal.ai video generators."""
+
+from .kling_video_v2_5_turbo_pro_text_to_video import (
+    FalKlingVideoV25TurboProTextToVideoGenerator,
+)
+from .sync_lipsync_v2 import FalSyncLipsyncV2Generator
+from .veo31_first_last_frame_to_video import FalVeo31FirstLastFrameToVideoGenerator
+
+__all__ = [
+    "FalKlingVideoV25TurboProTextToVideoGenerator",
+    "FalSyncLipsyncV2Generator",
+    "FalVeo31FirstLastFrameToVideoGenerator",
+]

package/templates/api/src/boards/generators/implementations/fal/video/kling_video_v2_5_turbo_pro_text_to_video.py

@@ -0,0 +1,168 @@
+"""
+Kling v2.5 Turbo Pro text-to-video generator.
+
+Top-tier text-to-video generation with unparalleled motion fluidity, cinematic visuals,
+and exceptional prompt precision using Kling's v2.5 Turbo Pro model.
+
+Based on Fal AI's fal-ai/kling-video/v2.5-turbo/pro/text-to-video model.
+See: https://fal.ai/models/fal-ai/kling-video/v2.5-turbo/pro/text-to-video
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class KlingVideoV25TurboProTextToVideoInput(BaseModel):
+    """Input schema for Kling v2.5 Turbo Pro text-to-video generation."""
+
+    prompt: str = Field(
+        description="Primary instruction for video generation",
+        max_length=2500,
+    )
+    duration: Literal["5", "10"] = Field(
+        default="5",
+        description="Video length in seconds",
+    )
+    aspect_ratio: Literal["16:9", "9:16", "1:1"] = Field(
+        default="16:9",
+        description="Frame dimensions",
+    )
+    negative_prompt: str = Field(
+        default="blur, distort, and low quality",
+        description="Elements to exclude from output",
+        max_length=2500,
+    )
+    cfg_scale: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description="Guidance strength controlling prompt adherence (0-1)",
+    )
+
+
+class FalKlingVideoV25TurboProTextToVideoGenerator(BaseGenerator):
+    """Generator for text-to-video using Kling v2.5 Turbo Pro."""
+
+    name = "fal-kling-video-v2-5-turbo-pro-text-to-video"
+    description = (
+        "Fal: Kling v2.5 Turbo Pro - top-tier text-to-video generation with cinematic visuals"
+    )
+    artifact_type = "video"
+
+    def get_input_schema(self) -> type[KlingVideoV25TurboProTextToVideoInput]:
+        """Return the input schema for this generator."""
+        return KlingVideoV25TurboProTextToVideoInput
+
+    async def generate(
+        self, inputs: KlingVideoV25TurboProTextToVideoInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate video using fal.ai Kling v2.5 Turbo Pro model."""
+        # 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 FalKlingVideoV25TurboProTextToVideoGenerator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Prepare arguments for fal.ai API
+        arguments = {
+            "prompt": inputs.prompt,
+            "duration": inputs.duration,
+            "aspect_ratio": inputs.aspect_ratio,
+            "negative_prompt": inputs.negative_prompt,
+            "cfg_scale": inputs.cfg_scale,
+        }
+
+        # Submit async job
+        handler = await fal_client.submit_async(
+            "fal-ai/kling-video/v2.5-turbo/pro/text-to-video",
+            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:
+                # 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 video from result
+        # fal.ai returns: {"video": {"url": "...", "content_type": "video/mp4", ...}}
+        video_data = result.get("video")
+        if not video_data:
+            raise ValueError("No video returned from fal.ai API")
+
+        video_url = video_data.get("url")
+        if not video_url:
+            raise ValueError("Video missing URL in fal.ai response")
+
+        # Determine video dimensions based on aspect ratio
+        # Using HD quality resolutions
+        aspect_ratio_dimensions = {
+            "16:9": (1920, 1080),
+            "9:16": (1080, 1920),
+            "1:1": (1080, 1080),
+        }
+        width, height = aspect_ratio_dimensions.get(inputs.aspect_ratio, (1920, 1080))
+
+        # Store video result
+        artifact = await context.store_video_result(
+            storage_url=video_url,
+            format="mp4",
+            width=width,
+            height=height,
+            duration=float(inputs.duration),  # Convert "5" or "10" to float
+            output_index=0,
+        )
+
+        return GeneratorResult(outputs=[artifact])
+
+    async def estimate_cost(self, inputs: KlingVideoV25TurboProTextToVideoInput) -> float:
+        """Estimate cost for Kling v2.5 Turbo Pro generation.
+
+        Pricing information not provided in official documentation.
+        Estimated at $0.15 per video based on typical video generation costs.
+        Cost may vary based on duration and quality settings.
+        """
+        # Approximate cost per video
+        # 10-second videos may cost more than 5-second videos
+        base_cost = 0.15
+        duration_multiplier = 2.0 if inputs.duration == "10" else 1.0
+        return base_cost * duration_multiplier