@weirdfingers/baseboards 0.2.1 → 0.4.0

package/templates/api/src/boards/generators/implementations/fal/audio/minimax_music_v2.py

@@ -0,0 +1,173 @@
+"""
+fal.ai minimax-music/v2 text-to-music generator.
+
+Generate music from text prompts using the MiniMax Music 2.0 model, which leverages
+advanced AI techniques to create high-quality, diverse musical compositions.
+
+Based on Fal AI's fal-ai/minimax-music/v2 model.
+See: https://fal.ai/models/fal-ai/minimax-music/v2
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class AudioSetting(BaseModel):
+    """Audio output settings for minimax-music/v2."""
+
+    format: Literal["mp3", "pcm", "flac"] = Field(
+        default="mp3",
+        description="Audio output format",
+    )
+    sample_rate: Literal[8000, 16000, 22050, 24000, 32000, 44100] = Field(
+        default=44100,
+        description="Audio sample rate in Hz",
+    )
+    bitrate: Literal[32000, 64000, 128000, 256000] = Field(
+        default=256000,
+        description="Audio bitrate in bits per second",
+    )
+
+
+class MinimaxMusicV2Input(BaseModel):
+    """Input schema for minimax-music/v2 music generation."""
+
+    prompt: str = Field(
+        description="A description of the music, specifying style, mood, and scenario",
+        min_length=10,
+        max_length=300,
+    )
+    lyrics_prompt: str = Field(
+        description=(
+            "Lyrics of the song. Use \\n to separate lines. "
+            "Structure tags like [Intro], [Verse], [Chorus] supported"
+        ),
+        min_length=10,
+        max_length=3000,
+    )
+    audio_setting: AudioSetting | None = Field(
+        default=None,
+        description="Audio output settings (format, sample rate, bitrate)",
+    )
+
+
+class FalMinimaxMusicV2Generator(BaseGenerator):
+    """minimax-music/v2 music generator using fal.ai."""
+
+    name = "fal-minimax-music-v2"
+    artifact_type = "audio"
+    description = "Fal: MiniMax Music 2.0 - generate music from text prompts and lyrics"
+
+    def get_input_schema(self) -> type[MinimaxMusicV2Input]:
+        return MinimaxMusicV2Input
+
+    async def generate(
+        self, inputs: MinimaxMusicV2Input, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate music using fal.ai minimax-music/v2 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 FalMinimaxMusicV2Generator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Prepare arguments for fal.ai API
+        from typing import Any
+
+        arguments: dict[str, Any] = {
+            "prompt": inputs.prompt,
+            "lyrics_prompt": inputs.lyrics_prompt,
+        }
+
+        # Add audio settings if provided
+        if inputs.audio_setting is not None:
+            arguments["audio_setting"] = {
+                "format": inputs.audio_setting.format,
+                "sample_rate": inputs.audio_setting.sample_rate,
+                "bitrate": inputs.audio_setting.bitrate,
+            }
+
+        # Submit async job and get handler
+        handler = await fal_client.submit_async(
+            "fal-ai/minimax-music/v2",
+            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 audio from result
+        # fal.ai returns: {"audio": {"url": "...", "content_type": "...", "file_size": ...}}
+        audio_data = result.get("audio")
+        if not audio_data:
+            raise ValueError("No audio returned from fal.ai API")
+
+        audio_url = audio_data.get("url")
+        if not audio_url:
+            raise ValueError("Audio missing URL in fal.ai response")
+
+        # Determine format from audio_setting or content_type
+        audio_format = (
+            inputs.audio_setting.format if inputs.audio_setting else "mp3"  # Default format
+        )
+
+        # Store audio result
+        artifact = await context.store_audio_result(
+            storage_url=audio_url,
+            format=audio_format,
+            sample_rate=inputs.audio_setting.sample_rate if inputs.audio_setting else 44100,
+            output_index=0,
+        )
+
+        return GeneratorResult(outputs=[artifact])
+
+    async def estimate_cost(self, inputs: MinimaxMusicV2Input) -> float:
+        """Estimate cost for minimax-music/v2 generation.
+
+        Estimated at approximately $0.08 per music generation based on typical
+        music generation pricing. Actual cost may vary.
+        """
+        return 0.08  # $0.08 per music generation

package/templates/api/src/boards/generators/implementations/fal/audio/minimax_speech_2_6_turbo.py

@@ -0,0 +1,221 @@
+"""
+fal.ai MiniMax Speech 2.6 Turbo text-to-speech generator.
+
+Generate speech from text prompts using the MiniMax Speech-2.6 HD model,
+which leverages advanced AI techniques to create high-quality text-to-speech.
+
+Based on Fal AI's fal-ai/minimax/speech-2.6-turbo model.
+See: https://fal.ai/models/fal-ai/minimax/speech-2.6-turbo
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class VoiceSetting(BaseModel):
+    """Voice configuration settings."""
+
+    voice_id: str = Field(
+        default="Wise_Woman",
+        description="Speaker identifier for the voice",
+    )
+    speed: float = Field(
+        default=1.0,
+        description="Playback speed multiplier",
+    )
+    pitch: float = Field(
+        default=0.0,
+        description="Pitch adjustment",
+    )
+    vol: float = Field(
+        default=1.0,
+        description="Volume level",
+    )
+    english_normalization: bool = Field(
+        default=False,
+        description="Enable English text normalization",
+    )
+
+
+class LoudnessNormalizationSetting(BaseModel):
+    """Audio loudness normalization controls."""
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable loudness normalization",
+    )
+    target_loudness: float = Field(
+        default=-18.0,
+        ge=-70.0,
+        le=-10.0,
+        description="Target loudness in LUFS",
+    )
+    target_range: float = Field(
+        default=8.0,
+        ge=0.0,
+        le=20.0,
+        description="Target range in LU",
+    )
+    target_peak: float = Field(
+        default=-0.5,
+        ge=-3.0,
+        le=0.0,
+        description="Target peak level in dBTP",
+    )
+
+
+class MinimaxSpeech26TurboInput(BaseModel):
+    """Input schema for MiniMax Speech 2.6 Turbo generation."""
+
+    prompt: str = Field(
+        description=(
+            "Text to convert to speech " "(supports pause markers <#x#> with 0.01-99.99 seconds)"
+        ),
+        min_length=1,
+        max_length=10000,
+    )
+    voice_setting: VoiceSetting = Field(
+        default_factory=VoiceSetting,
+        description="Voice configuration including voice_id, speed, pitch, volume",
+    )
+    language_boost: str = Field(
+        default="auto",
+        description=(
+            "Enhance recognition of specified languages and dialects "
+            "(auto or specific language code)"
+        ),
+    )
+    output_format: Literal["url", "hex"] = Field(
+        default="url",
+        description="Output format: 'url' for audio file URL or 'hex' for hex-encoded data",
+    )
+    normalization_setting: LoudnessNormalizationSetting = Field(
+        default_factory=LoudnessNormalizationSetting,
+        description="Audio loudness normalization controls",
+    )
+
+
+class FalMinimaxSpeech26TurboGenerator(BaseGenerator):
+    """MiniMax Speech 2.6 Turbo text-to-speech generator using fal.ai."""
+
+    name = "fal-minimax-speech-2-6-turbo"
+    artifact_type = "audio"
+    description = (
+        "Fal: MiniMax Speech 2.6 Turbo - "
+        "High-quality text-to-speech with customizable voices and 35+ languages"
+    )
+
+    def get_input_schema(self) -> type[MinimaxSpeech26TurboInput]:
+        return MinimaxSpeech26TurboInput
+
+    async def generate(
+        self, inputs: MinimaxSpeech26TurboInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate audio using fal.ai MiniMax Speech 2.6 Turbo 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 FalMinimaxSpeech26TurboGenerator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Prepare arguments for fal.ai API
+        arguments = {
+            "prompt": inputs.prompt,
+            "voice_setting": {
+                "voice_id": inputs.voice_setting.voice_id,
+                "speed": inputs.voice_setting.speed,
+                "pitch": inputs.voice_setting.pitch,
+                "vol": inputs.voice_setting.vol,
+                "english_normalization": inputs.voice_setting.english_normalization,
+            },
+            "language_boost": inputs.language_boost,
+            "output_format": inputs.output_format,
+            "normalization_setting": {
+                "enabled": inputs.normalization_setting.enabled,
+                "target_loudness": inputs.normalization_setting.target_loudness,
+                "target_range": inputs.normalization_setting.target_range,
+                "target_peak": inputs.normalization_setting.target_peak,
+            },
+        }
+
+        # Submit async job and get handler
+        handler = await fal_client.submit_async(
+            "fal-ai/minimax/speech-2.6-turbo",
+            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 audio URL from result
+        # fal.ai returns: {"audio": {"url": "..."}}
+        audio_data = result.get("audio")
+        if audio_data is None:
+            raise ValueError("No audio data returned from fal.ai API")
+
+        audio_url = audio_data.get("url")
+        if not audio_url:
+            raise ValueError("Audio URL missing in fal.ai response")
+
+        # Store audio result
+        artifact = await context.store_audio_result(
+            storage_url=audio_url,
+            format="mp3",  # MiniMax Speech returns MP3 format
+            output_index=0,
+        )
+
+        return GeneratorResult(outputs=[artifact])
+
+    async def estimate_cost(self, inputs: MinimaxSpeech26TurboInput) -> float:
+        """Estimate cost for MiniMax Speech 2.6 Turbo generation.
+
+        MiniMax Speech 2.6 Turbo costs $0.06 per 1000 characters.
+        """
+        # Calculate character count
+        char_count = len(inputs.prompt)
+
+        # Cost is $0.06 per 1000 characters
+        return (char_count / 1000.0) * 0.06

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

@@ -0,0 +1,17 @@
+"""Fal.ai image generators."""
+
+from .flux_pro_kontext import FalFluxProKontextGenerator
+from .flux_pro_ultra import FalFluxProUltraGenerator
+from .imagen4_preview import FalImagen4PreviewGenerator
+from .imagen4_preview_fast import FalImagen4PreviewFastGenerator
+from .nano_banana import FalNanoBananaGenerator
+from .nano_banana_edit import FalNanoBananaEditGenerator
+
+__all__ = [
+    "FalFluxProKontextGenerator",
+    "FalFluxProUltraGenerator",
+    "FalImagen4PreviewGenerator",
+    "FalImagen4PreviewFastGenerator",
+    "FalNanoBananaGenerator",
+    "FalNanoBananaEditGenerator",
+]

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

@@ -0,0 +1,216 @@
+"""
+fal.ai FLUX.1 [pro] Kontext image-to-image generator.
+
+Handles both text and reference images as inputs, enabling targeted local edits
+and complex transformations of entire scenes using fal.ai's flux-pro/kontext model.
+"""
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ....artifacts import ImageArtifact
+from ....base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class FluxProKontextInput(BaseModel):
+    """Input schema for FLUX.1 [pro] Kontext image generation.
+
+    Artifact fields (like image_url) are automatically detected via type
+    introspection and resolved from generation IDs to ImageArtifact objects.
+    """
+
+    prompt: str = Field(
+        description="Text prompt for image editing (e.g., 'Put a donut next to the flour')"
+    )
+    image_url: ImageArtifact = Field(
+        description="Reference image for transformation (from previous generation)",
+    )
+    aspect_ratio: (
+        Literal[
+            "21:9",
+            "16:9",
+            "4:3",
+            "3:2",
+            "1:1",
+            "2:3",
+            "3:4",
+            "9:16",
+            "9:21",
+        ]
+        | None
+    ) = Field(
+        default=None,
+        description="Image aspect ratio (optional)",
+    )
+    num_images: int = Field(
+        default=1,
+        ge=1,
+        le=4,
+        description="Number of images to generate (1-4)",
+    )
+    output_format: Literal["jpeg", "png"] = 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"
+        ),
+    )
+    safety_tolerance: str = Field(
+        default="2",
+        description="Safety tolerance level (1-6 scale, higher is more permissive)",
+    )
+    guidance_scale: float = Field(
+        default=3.5,
+        ge=1.0,
+        le=20.0,
+        description="Guidance scale for image generation (1-20)",
+    )
+    seed: int | None = Field(
+        default=None,
+        description="Random seed for reproducible outputs (optional)",
+    )
+    enhance_prompt: bool = Field(
+        default=False,
+        description="Automatically enhance the prompt for better quality",
+    )
+
+
+class FalFluxProKontextGenerator(BaseGenerator):
+    """FLUX.1 [pro] Kontext image-to-image generator using fal.ai."""
+
+    name = "fal-flux-pro-kontext"
+    artifact_type = "image"
+    description = (
+        "Fal: FLUX.1 [pro] Kontext - Image-to-image editing with text and reference images"
+    )
+
+    def get_input_schema(self) -> type[FluxProKontextInput]:
+        return FluxProKontextInput
+
+    async def generate(
+        self, inputs: FluxProKontextInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate images using fal.ai flux-pro/kontext 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 FalFluxProKontextGenerator. "
+                "Install with: pip install weirdfingers-boards[generators-fal]"
+            ) from e
+
+        # Upload image artifact 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_url], context)
+        image_url = image_urls[0]  # Extract single URL from list
+
+        # Prepare arguments for fal.ai API
+        arguments = {
+            "prompt": inputs.prompt,
+            "image_url": image_url,
+            "num_images": inputs.num_images,
+            "output_format": inputs.output_format,
+            "sync_mode": inputs.sync_mode,
+            "safety_tolerance": inputs.safety_tolerance,
+            "guidance_scale": inputs.guidance_scale,
+            "enhance_prompt": inputs.enhance_prompt,
+        }
+
+        # Add optional fields if provided
+        if inputs.aspect_ratio is not None:
+            arguments["aspect_ratio"] = inputs.aspect_ratio
+
+        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-pro/kontext",
+            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: FluxProKontextInput) -> float:
+        """Estimate cost for FLUX.1 [pro] Kontext generation.
+
+        FLUX.1 [pro] Kontext is a premium image-to-image model. Estimated cost
+        is approximately $0.055 per image based on similar Flux Pro models.
+        """
+        # Cost per image * number of images
+        cost_per_image = 0.055
+        return cost_per_image * inputs.num_images