@weirdfingers/baseboards 0.2.0

package/templates/api/src/boards/generators/base.py

@@ -0,0 +1,140 @@
+"""
+Base generator classes and interfaces for the Boards generators system.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from ..progress.models import ProgressUpdate
+from .artifacts import (
+    AudioArtifact,
+    DigitalArtifact,
+    ImageArtifact,
+    TextArtifact,
+    VideoArtifact,
+)
+
+
+class GeneratorResult(BaseModel):
+    """All generators return a list of urls to the artifacts they produce."""
+
+    outputs: list[DigitalArtifact]
+
+
+class BaseGenerator(ABC):
+    """
+    Abstract base class for all generators in the Boards system.
+
+    Generators define input/output schemas using Pydantic models and implement
+    the generation logic using provider SDKs directly.
+    """
+
+    # Class attributes that subclasses must define
+    name: str
+    artifact_type: str  # 'image', 'video', 'audio', 'text', 'lora'
+    description: str
+
+    @abstractmethod
+    def get_input_schema(self) -> type[BaseModel]:
+        """
+        Return the Pydantic model class that defines the input schema for this generator.
+
+        Returns:
+            Type[BaseModel]: Pydantic model class for input validation
+        """
+        pass
+
+    @abstractmethod
+    async def generate(
+        self, inputs: BaseModel, context: "GeneratorExecutionContext"
+    ) -> GeneratorResult:
+        """
+        Execute the generation process using the provided inputs.
+
+        Args:
+            inputs: Validated input data matching the input schema
+
+        Returns:
+            BaseModel: Generated output matching the output schema
+        """
+        pass
+
+    @abstractmethod
+    async def estimate_cost(self, inputs: BaseModel) -> float:
+        """
+        Estimate the cost of running this generation in USD.
+
+        Args:
+            inputs: Input data for cost estimation
+
+        Returns:
+            float: Estimated cost in USD
+        """
+        pass
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}(name='{self.name}', type='{self.artifact_type}')>"
+
+
+@runtime_checkable
+class GeneratorExecutionContext(Protocol):
+    """Typed protocol for the execution context passed to generators.
+
+    This protocol defines the interface that generators can use to interact
+    with storage, database, and progress tracking systems.
+    """
+
+    async def resolve_artifact(self, artifact: DigitalArtifact) -> str:
+        """Resolve an artifact to a local file path for use with provider SDKs."""
+        ...
+
+    async def store_image_result(
+        self,
+        storage_url: str,
+        format: str,
+        width: int,
+        height: int,
+    ) -> ImageArtifact:
+        """Store an image result to permanent storage."""
+        ...
+
+    async def store_video_result(
+        self,
+        storage_url: str,
+        format: str,
+        width: int,
+        height: int,
+        duration: float | None = None,
+        fps: float | None = None,
+    ) -> VideoArtifact:
+        """Store a video result to permanent storage."""
+        ...
+
+    async def store_audio_result(
+        self,
+        storage_url: str,
+        format: str,
+        duration: float | None = None,
+        sample_rate: int | None = None,
+        channels: int | None = None,
+    ) -> AudioArtifact:
+        """Store an audio result to permanent storage."""
+        ...
+
+    async def store_text_result(
+        self,
+        content: str,
+        format: str,
+    ) -> TextArtifact:
+        """Store a text result to permanent storage."""
+        ...
+
+    async def publish_progress(self, update: ProgressUpdate) -> None:
+        """Publish a progress update for this generation."""
+        ...
+
+    async def set_external_job_id(self, external_id: str) -> None:
+        """Set the external job ID from the provider (e.g., Replicate prediction ID)."""
+        ...

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

@@ -0,0 +1,12 @@
+"""
+Built-in generator implementations for the Boards system.
+
+This package contains example generators that demonstrate how to integrate
+various AI services using their native SDKs.
+
+Import this module to automatically register all built-in generators:
+    import boards.generators.implementations
+"""
+
+# Import all generator modules to trigger registration
+from . import audio, image, video

package/templates/api/src/boards/generators/implementations/audio/__init__.py

@@ -0,0 +1,3 @@
+"""Audio generation implementations."""
+
+from . import whisper

package/templates/api/src/boards/generators/implementations/audio/whisper.py

@@ -0,0 +1,66 @@
+"""
+Whisper audio transcription using OpenAI API.
+
+Demonstrates audio processing generator that outputs text.
+"""
+
+from pydantic import BaseModel, Field
+
+from ...artifacts import AudioArtifact
+from ...base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class WhisperInput(BaseModel):
+    """Input schema for Whisper transcription."""
+
+    audio_source: AudioArtifact = Field(description="Audio file to transcribe")
+    language: str = Field(default="en", description="Language code (e.g., 'en', 'es', 'fr')")
+    prompt: str = Field(default="", description="Optional prompt to guide transcription")
+
+
+class WhisperGenerator(BaseGenerator):
+    """Whisper speech-to-text transcription using OpenAI API."""
+
+    name = "whisper"
+    artifact_type = "text"
+    description = "OpenAI Whisper - speech-to-text transcription"
+
+    def get_input_schema(self) -> type[WhisperInput]:
+        return WhisperInput
+
+    async def generate(
+        self, inputs: WhisperInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Transcribe audio using OpenAI Whisper."""
+        try:
+            from openai import AsyncOpenAI
+        except ImportError as e:
+            raise ValueError("Required dependencies not available") from e
+
+        client = AsyncOpenAI()
+
+        # Resolve audio artifact to file path via context
+        audio_file_path = await context.resolve_artifact(inputs.audio_source)
+
+        # Use OpenAI SDK for transcription
+        with open(audio_file_path, "rb") as audio_file:
+            transcript = await client.audio.transcriptions.create(
+                model="whisper-1",
+                file=audio_file,
+                language=inputs.language,
+                prompt=inputs.prompt,
+            )
+
+        # Create text artifact
+        text_artifact = await context.store_text_result(
+            content=transcript.text,
+            format="plain",
+        )
+
+        return GeneratorResult(outputs=[text_artifact])
+
+    async def estimate_cost(self, inputs: WhisperInput) -> float:
+        """Estimate cost for Whisper transcription."""
+        # Whisper pricing is $0.006 per minute
+        duration_minutes = (inputs.audio_source.duration or 60) / 60
+        return duration_minutes * 0.006

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

@@ -0,0 +1,3 @@
+"""Image generation implementations."""
+
+from . import dalle3, flux_pro

package/templates/api/src/boards/generators/implementations/image/dalle3.py

@@ -0,0 +1,93 @@
+"""
+DALL-E 3 generator using OpenAI API.
+
+Demonstrates integration with OpenAI's SDK for image generation.
+"""
+
+import os
+
+from pydantic import BaseModel, Field
+
+from ...base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class DallE3Input(BaseModel):
+    """Input schema for DALL-E 3 image generation."""
+
+    prompt: str = Field(description="Text prompt for image generation")
+    size: str = Field(
+        default="1024x1024",
+        description="Image size",
+        pattern="^(1024x1024|1024x1792|1792x1024)$",
+    )
+    quality: str = Field(default="standard", description="Image quality", pattern="^(standard|hd)$")
+    style: str = Field(default="vivid", description="Image style", pattern="^(vivid|natural)$")
+
+
+class DallE3Generator(BaseGenerator):
+    """DALL-E 3 image generator using OpenAI API."""
+
+    name = "dall-e-3"
+    artifact_type = "image"
+    description = "OpenAI's DALL-E 3 - advanced text-to-image generation"
+
+    def get_input_schema(self) -> type[DallE3Input]:
+        return DallE3Input
+
+    async def generate(
+        self, inputs: DallE3Input, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate image using OpenAI DALL-E 3."""
+        # Check for API key
+        if not os.getenv("OPENAI_API_KEY"):
+            raise ValueError("API configuration invalid")
+
+        # Import SDK directly
+        try:
+            from openai import AsyncOpenAI
+        except ImportError as e:
+            raise ValueError("Required dependencies not available") from e
+
+        client = AsyncOpenAI()
+
+        # Use OpenAI SDK directly
+        response = await client.images.generate(
+            model="dall-e-3",
+            prompt=inputs.prompt,
+            size=inputs.size,  # pyright: ignore[reportArgumentType]
+            quality=inputs.quality,  # pyright: ignore[reportArgumentType]
+            style=inputs.style,  # pyright: ignore[reportArgumentType]
+            n=1,
+        )
+
+        # Get the generated image URL
+        if not response.data or not response.data[0].url:
+            raise ValueError("No image generated")
+        image_url = response.data[0].url
+
+        # Parse dimensions from size
+        width, height = map(int, inputs.size.split("x"))
+
+        # Store via context (downloads from OpenAI and uploads to our storage)
+        image_artifact = await context.store_image_result(
+            storage_url=image_url,
+            format="png",  # DALL-E 3 outputs PNG
+            width=width,
+            height=height,
+        )
+
+        return GeneratorResult(outputs=[image_artifact])
+
+    async def estimate_cost(self, inputs: DallE3Input) -> float:
+        """Estimate cost for DALL-E 3 generation."""
+        # DALL-E 3 pricing varies by quality and size
+        if inputs.quality == "hd":
+            if inputs.size in ["1024x1792", "1792x1024"]:
+                return 0.080  # HD, non-square
+            else:
+                return 0.080  # HD, square
+        else:  # standard quality
+            if inputs.size in ["1024x1792", "1792x1024"]:
+                return 0.040  # Standard, non-square
+            else:
+                return 0.040  # Standard, square

package/templates/api/src/boards/generators/implementations/image/flux_pro.py

@@ -0,0 +1,85 @@
+"""
+FLUX.1.1 Pro generator using Replicate API.
+
+This demonstrates the simple pattern for creating generators:
+1. Define Pydantic input/output models
+2. Implement generation logic using provider SDK directly
+3. Register with the global registry
+"""
+
+import os
+from collections.abc import AsyncIterator
+
+from pydantic import BaseModel, Field
+
+from ...base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class FluxProInput(BaseModel):
+    """Input schema for FLUX.1.1 Pro image generation."""
+
+    prompt: str = Field(description="Text prompt for image generation")
+    aspect_ratio: str = Field(
+        default="1:1",
+        description="Image aspect ratio",
+        pattern="^(1:1|16:9|21:9|2:3|3:2|4:5|5:4|9:16|9:21)$",
+    )
+    safety_tolerance: int = Field(default=2, ge=1, le=5, description="Safety tolerance level (1-5)")
+
+
+class FluxProGenerator(BaseGenerator):
+    """FLUX.1.1 Pro image generator using Replicate."""
+
+    name = "flux-pro"
+    artifact_type = "image"
+    description = "FLUX.1.1 [pro] by Black Forest Labs - high-quality image generation"
+
+    def get_input_schema(self) -> type[FluxProInput]:
+        return FluxProInput
+
+    async def generate(
+        self, inputs: FluxProInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate image using Replicate FLUX.1.1 Pro model."""
+        # Check for API key
+        if not os.getenv("REPLICATE_API_TOKEN"):
+            raise ValueError("API configuration invalid. Missing REPLICATE_API_TOKEN")
+
+        # Import SDK directly
+        try:
+            import replicate
+            from replicate.helpers import FileOutput
+        except ImportError as e:
+            raise ValueError("Required dependencies not available") from e
+
+        # Use Replicate SDK directly
+        prediction: FileOutput | AsyncIterator[FileOutput] = await replicate.async_run(
+            "black-forest-labs/flux-1.1-pro",
+            input={
+                "prompt": inputs.prompt,
+                "aspect_ratio": inputs.aspect_ratio,
+                "safety_tolerance": inputs.safety_tolerance,
+            },
+        )
+
+        # If prediction is an async iterator, get the first item; else, use as is.
+        if isinstance(prediction, AsyncIterator):
+            file_output = await anext(prediction)
+        else:
+            file_output = prediction
+
+        output_url = file_output.url
+
+        image_artifact = await context.store_image_result(
+            storage_url=output_url,
+            format="png",
+            width=1024,
+            height=1024,
+        )
+
+        return GeneratorResult(outputs=[image_artifact])
+
+    async def estimate_cost(self, inputs: FluxProInput) -> float:
+        """Estimate cost for FLUX.1.1 Pro generation."""
+        # FLUX.1.1 Pro typically costs around $0.055 per generation
+        return 0.055

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

@@ -0,0 +1,3 @@
+"""Video generation implementations."""
+
+from . import lipsync

package/templates/api/src/boards/generators/implementations/video/lipsync.py

@@ -0,0 +1,70 @@
+"""
+Lipsync generator using Replicate API.
+
+This demonstrates how generators can use multiple artifact inputs
+with automatic artifact resolution.
+"""
+
+from pydantic import BaseModel, Field
+
+from ...artifacts import AudioArtifact, VideoArtifact
+from ...base import BaseGenerator, GeneratorExecutionContext, GeneratorResult
+
+
+class LipsyncInput(BaseModel):
+    """Input schema for lipsync generation."""
+
+    audio_source: AudioArtifact = Field(description="Audio track for lip sync")
+    video_source: VideoArtifact = Field(description="Video to sync lips in")
+    prompt: str | None = Field(None, description="Optional prompt for generation")
+
+
+class LipsyncGenerator(BaseGenerator):
+    """Lipsync generator that syncs lips in video to audio."""
+
+    name = "lipsync"
+    artifact_type = "video"
+    description = "Sync lips in video to match audio track"
+
+    def get_input_schema(self) -> type[LipsyncInput]:
+        return LipsyncInput
+
+    async def generate(
+        self, inputs: LipsyncInput, context: GeneratorExecutionContext
+    ) -> GeneratorResult:
+        """Generate lip-synced video."""
+        # Import SDK directly
+        try:
+            import replicate  # type: ignore
+        except ImportError as e:
+            raise ValueError("Required dependencies not available") from e
+
+        # Resolve artifacts via context
+        audio_file = await context.resolve_artifact(inputs.audio_source)
+        video_file = await context.resolve_artifact(inputs.video_source)
+
+        # Use Replicate SDK directly with proper file handling
+        with open(audio_file, "rb") as audio_f, open(video_file, "rb") as video_f:
+            result = await replicate.async_run(
+                "cjwbw/wav2lip",
+                input={
+                    "audio": audio_f,
+                    "video": video_f,
+                },
+            )
+
+        # Store output and create artifact via context
+        video_artifact = await context.store_video_result(
+            storage_url=str(result),
+            format="mp4",
+            width=inputs.video_source.width,
+            height=inputs.video_source.height,
+            duration=inputs.audio_source.duration,
+        )
+
+        return GeneratorResult(outputs=[video_artifact])
+
+    async def estimate_cost(self, inputs: LipsyncInput) -> float:
+        """Estimate cost for lipsync generation."""
+        # Wav2Lip is typically free on Replicate, but let's add a small cost
+        return 0.01