@weirdfingers/baseboards 0.2.1 → 0.3.0

package/templates/api/pyproject.toml

@@ -36,7 +36,6 @@ classifiers = [
 ]
 dependencies = [
     "sqlalchemy>=2.0.0",
-    "supabase>=2.0.0",
     "pydantic>=2.0.0",
     "pydantic-settings>=2.0.0",
     "httpx>=0.24.0",
@@ -60,6 +59,52 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+# Generator providers (per-provider)
+generators-replicate = ["replicate>=1.0.4"]
+generators-openai = ["openai>=1.60.1"]
+generators-fal = ["fal-client>=0.5.0"]
+generators-anthropic = ["anthropic>=0.25.0"]
+generators-together = ["together>=1.0.0"]
+
+# Convenience: all generators
+generators-all = [
+    "replicate>=1.0.4",
+    "openai>=1.60.1",
+    "fal-client>=0.5.0",
+    "anthropic>=0.25.0",
+    "together>=1.0.0",
+]
+
+# Storage providers (per-provider)
+storage-supabase = ["supabase>=2.0.0"]
+storage-s3 = ["boto3>=1.34.0", "aioboto3>=12.0.0"]
+storage-gcs = ["google-cloud-storage>=2.10.0"]
+
+# Convenience: all storage backends
+storage-all = [
+    "supabase>=2.0.0",
+    "boto3>=1.34.0",
+    "aioboto3>=12.0.0",
+    "google-cloud-storage>=2.10.0",
+]
+
+# Auth providers (only Supabase needs extra deps beyond core httpx/pyjwt)
+auth-supabase = ["supabase>=2.0.0"]
+
+# Convenience: everything
+all = [
+    "replicate>=1.0.4",
+    "openai>=1.60.1",
+    "fal-client>=0.5.0",
+    "anthropic>=0.25.0",
+    "together>=1.0.0",
+    "supabase>=2.0.0",
+    "boto3>=1.34.0",
+    "aioboto3>=12.0.0",
+    "google-cloud-storage>=2.10.0",
+]
+
+# Development dependencies
 dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
@@ -74,21 +119,15 @@ dev = [
     "anthropic>=0.25.0",
     "replicate>=1.0.4",
     "together>=1.0.0",
+    "fal-client>=0.5.0",
     # Include all storage deps for typecheck
+    "supabase>=2.0.0",
     "boto3>=1.34.0",
     "aioboto3>=12.0.0",
     "google-cloud-storage>=2.10.0",
     # Type stubs
     "types-redis>=4.6.0",
 ]
-providers = [
-    "openai>=1.60.1",
-    "anthropic>=0.25.0",
-    "replicate>=1.0.4",
-    "together>=1.0.0",
-]
-storage-s3 = ["boto3>=1.34.0", "aioboto3>=12.0.0"]
-storage-gcs = ["google-cloud-storage>=2.10.0"]
 
 [project.urls]
 Homepage = "https://github.com/weirdfingers/boards"
@@ -156,6 +195,7 @@ dev-dependencies = [
     "anthropic>=0.25.0",
     "replicate>=1.0.4",
     "together>=1.0.0",
+    "fal-client>=0.5.0",
     # Include all storage deps for typecheck
     "boto3>=1.34.0",
     "aioboto3>=12.0.0",

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

@@ -3,7 +3,7 @@ Boards Backend SDK
 Open-source creative toolkit for AI-generated content
 """
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 
 from .config import settings
 

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

@@ -12,13 +12,13 @@ Key components:
 
 Example usage:
     from boards.generators import registry
-    from boards.generators.implementations.image.flux_pro import FluxProGenerator
+    from boards.generators.implementations.replicate.image.flux_pro import ReplicateFluxProGenerator
 
     # Get available generators
     image_generators = registry.list_by_artifact_type("image")
 
     # Use a specific generator
-    flux = registry.get("flux-pro")
+    flux = registry.get("replicate-flux-pro")
     result = await flux.generate(inputs)
 """
 

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

@@ -0,0 +1,380 @@
+"""
+Utilities for resolving generation IDs to artifact objects.
+
+This module provides utilities for converting generation ID strings (UUIDs)
+into typed artifact objects (ImageArtifact, AudioArtifact, etc.) with proper
+validation of ownership and completion status.
+
+The main approach is to automatically detect artifact fields via type introspection
+and resolve them BEFORE Pydantic validation.
+"""
+
+from typing import Any, TypeVar, get_args, get_origin
+from uuid import UUID
+
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..dbmodels import Generations
+from ..jobs import repository as jobs_repo
+from ..logging import get_logger
+from .artifacts import AudioArtifact, ImageArtifact, TextArtifact, VideoArtifact
+
+logger = get_logger(__name__)
+
+# Type variable for artifact types
+TArtifact = TypeVar("TArtifact", ImageArtifact, VideoArtifact, AudioArtifact, TextArtifact)
+
+# Set of all artifact types for quick checking
+ARTIFACT_TYPES = {ImageArtifact, VideoArtifact, AudioArtifact, TextArtifact}
+
+
+def _extract_artifact_type(annotation: Any) -> type[TArtifact] | None:
+    """Extract artifact type from a field annotation.
+
+    Handles both single artifacts (ImageArtifact) and lists (list[ImageArtifact]).
+
+    Args:
+        annotation: The type annotation from a Pydantic field
+
+    Returns:
+        The artifact class if this is an artifact field, None otherwise
+
+    Examples:
+        _extract_artifact_type(ImageArtifact) -> ImageArtifact
+        _extract_artifact_type(list[ImageArtifact]) -> ImageArtifact
+        _extract_artifact_type(str) -> None
+    """
+    # Direct artifact type (e.g., ImageArtifact)
+    if annotation in ARTIFACT_TYPES:
+        return annotation  # type: ignore[return-value]
+
+    # List of artifacts (e.g., list[ImageArtifact])
+    origin = get_origin(annotation)
+    if origin is list:
+        args = get_args(annotation)
+        if args and args[0] in ARTIFACT_TYPES:
+            return args[0]  # type: ignore[return-value]
+
+    return None
+
+
+def extract_artifact_fields(schema: type[BaseModel]) -> dict[str, tuple[type[TArtifact], bool]]:
+    """Automatically extract artifact fields from a Pydantic schema.
+
+    Inspects the schema's field annotations and returns a mapping of field names
+    to their artifact types and whether they expect a list.
+
+    Args:
+        schema: Pydantic model class to inspect
+
+    Returns:
+        Dictionary mapping field names to (artifact_type, is_list) tuples
+
+    Example:
+        class MyInput(BaseModel):
+            prompt: str
+            image_source: ImageArtifact
+            video_sources: list[VideoArtifact]
+
+        extract_artifact_fields(MyInput)
+        # Returns: {"image_source": (ImageArtifact, False), "video_sources": (VideoArtifact, True)}
+    """
+    artifact_fields: dict[str, tuple[type[TArtifact], bool]] = {}
+
+    for field_name, field_info in schema.model_fields.items():
+        artifact_type = _extract_artifact_type(field_info.annotation)
+        if artifact_type is not None:
+            # Check if the field is a list type
+            origin = get_origin(field_info.annotation)
+            is_list = origin is list
+            artifact_fields[field_name] = (artifact_type, is_list)
+
+    return artifact_fields
+
+
+def _get_artifact_type_name[T: (ImageArtifact, VideoArtifact, AudioArtifact, TextArtifact)](
+    artifact_class: type[T],
+) -> str:
+    """Get the database artifact_type string for an artifact class."""
+    type_map = {
+        ImageArtifact: "image",
+        VideoArtifact: "video",
+        AudioArtifact: "audio",
+        TextArtifact: "text",
+    }
+    artifact_type = type_map.get(artifact_class)
+    if artifact_type is None:
+        raise ValueError(f"Unsupported artifact class: {artifact_class}")
+    return artifact_type
+
+
+def _generation_to_artifact[T: (ImageArtifact, VideoArtifact, AudioArtifact, TextArtifact)](
+    generation: Generations, artifact_class: type[T]
+) -> T:
+    """Convert a Generations database record to an artifact object.
+
+    Args:
+        generation: Database generation record
+        artifact_class: Target artifact class (ImageArtifact, VideoArtifact, etc.)
+
+    Returns:
+        Artifact object populated from the generation record
+
+    Raises:
+        ValueError: If generation is missing required fields or data
+    """
+    if not generation.storage_url:
+        raise ValueError(
+            f"Generation {generation.id} has no storage_url - generation may not be completed"
+        )
+
+    # Get output metadata
+    metadata = generation.output_metadata or {}
+
+    # Build artifact based on type
+    if artifact_class == ImageArtifact:
+        width = metadata.get("width")
+        height = metadata.get("height")
+        if width is None or height is None:
+            raise ValueError(
+                f"Generation {generation.id} missing image dimensions in output_metadata"
+            )
+        return ImageArtifact(
+            generation_id=str(generation.id),
+            storage_url=generation.storage_url,
+            format=metadata.get("format", "png"),
+            width=width,
+            height=height,
+        )  # type: ignore[return-value]
+
+    elif artifact_class == VideoArtifact:
+        width = metadata.get("width")
+        height = metadata.get("height")
+        if width is None or height is None:
+            raise ValueError(
+                f"Generation {generation.id} missing video dimensions in output_metadata"
+            )
+        return VideoArtifact(
+            generation_id=str(generation.id),
+            storage_url=generation.storage_url,
+            format=metadata.get("format", "mp4"),
+            width=width,
+            height=height,
+            duration=metadata.get("duration"),
+            fps=metadata.get("fps"),
+        )  # type: ignore[return-value]
+
+    elif artifact_class == AudioArtifact:
+        return AudioArtifact(
+            generation_id=str(generation.id),
+            storage_url=generation.storage_url,
+            format=metadata.get("format", "mp3"),
+            duration=metadata.get("duration"),
+            sample_rate=metadata.get("sample_rate"),
+            channels=metadata.get("channels"),
+        )  # type: ignore[return-value]
+
+    elif artifact_class == TextArtifact:
+        content = metadata.get("content")
+        if content is None:
+            raise ValueError(f"Generation {generation.id} missing text content in output_metadata")
+        return TextArtifact(
+            generation_id=str(generation.id),
+            storage_url=generation.storage_url,
+            format=metadata.get("format", "plain"),
+            content=content,
+        )  # type: ignore[return-value]
+
+    else:
+        raise ValueError(f"Unsupported artifact class: {artifact_class}")
+
+
+async def resolve_generation_ids_to_artifacts[
+    T: (ImageArtifact, VideoArtifact, AudioArtifact, TextArtifact)
+](
+    generation_ids: list[str | UUID],
+    artifact_class: type[T],
+    session: AsyncSession,
+    tenant_id: UUID,
+) -> list[T]:
+    """Convert a list of generation IDs to typed artifact objects.
+
+    This function:
+    1. Queries the database for each generation ID
+    2. Validates the generation is completed
+    3. Validates the artifact type matches
+    4. Validates the user has access (tenant_id matches)
+    5. Converts to the appropriate artifact object
+
+    Args:
+        generation_ids: List of generation IDs (as strings or UUIDs)
+        artifact_class: Target artifact class (ImageArtifact, VideoArtifact, etc.)
+        session: Database session for queries
+        tenant_id: Tenant ID for access validation
+
+    Returns:
+        List of artifact objects
+
+    Raises:
+        ValueError: If any generation is not found, not completed, wrong type, or access denied
+    """
+    expected_artifact_type = _get_artifact_type_name(artifact_class)
+    artifacts: list[T] = []
+
+    for gen_id in generation_ids:
+        # Query generation from database
+        try:
+            generation = await jobs_repo.get_generation(session, gen_id)
+        except Exception as e:
+            raise ValueError(f"Generation {gen_id} not found") from e
+
+        # Validate tenant access
+        if generation.tenant_id != tenant_id:
+            raise ValueError(f"Access denied to generation {gen_id} - tenant mismatch")
+
+        # Validate completion status
+        if generation.status != "completed":
+            raise ValueError(f"Generation {gen_id} is not completed (status: {generation.status})")
+
+        # Validate artifact type
+        if generation.artifact_type != expected_artifact_type:
+            raise ValueError(
+                f"Generation {gen_id} has wrong artifact type: "
+                f"expected {expected_artifact_type}, got {generation.artifact_type}"
+            )
+
+        # Convert to artifact object
+        try:
+            artifact = _generation_to_artifact(generation, artifact_class)
+            artifacts.append(artifact)
+        except ValueError as e:
+            raise ValueError(f"Failed to convert generation {gen_id} to artifact: {e}") from e
+
+    return artifacts
+
+
+async def resolve_input_artifacts(
+    input_params: dict[str, Any],
+    schema: type[BaseModel],
+    session: AsyncSession,
+    tenant_id: UUID,
+) -> dict[str, Any]:
+    """Resolve generation IDs to artifact objects in input parameters.
+
+    This function automatically detects artifact fields from the Pydantic schema
+    via type introspection, then resolves generation ID strings to typed artifact
+    objects before Pydantic validation.
+
+    The function respects the field's type annotation:
+    - If field is `ImageArtifact`, input can be a single ID string → returns single artifact
+    - If field is `list[ImageArtifact]`, input can be a list of IDs → returns list of artifacts
+      (always a list, even if only one ID is provided)
+
+    Usage in generator input schema (no special declarations needed!):
+        class MyGeneratorInput(BaseModel):
+            prompt: str = Field(...)
+            image_source: ImageArtifact = Field(...)  # Automatically detected
+            video_sources: list[VideoArtifact] = Field(...)  # Also detected
+
+    Usage in actors.py:
+        # Artifacts are automatically detected and resolved
+        resolved_params = await resolve_input_artifacts(
+            input_params,
+            MyGeneratorInput,  # Just pass the schema class
+            session,
+            tenant_id,
+        )
+        # Now validate with resolved artifacts
+        typed_inputs = MyGeneratorInput.model_validate(resolved_params)
+
+    Args:
+        input_params: Raw input parameters dictionary (may contain generation IDs)
+        schema: Pydantic model class to inspect for artifact fields
+        session: Database session for queries
+        tenant_id: Tenant ID for access validation
+
+    Returns:
+        Updated input_params dictionary with generation IDs resolved to artifacts
+
+    Raises:
+        ValueError: If any generation ID cannot be resolved or validated
+    """
+    # Automatically extract artifact fields from schema
+    artifact_field_map = extract_artifact_fields(schema)
+
+    # If no artifact fields, just return original params
+    if not artifact_field_map:
+        return input_params
+
+    # Create a new dict with resolved artifacts
+    # Use dict constructor to avoid shallow copy issues
+    resolved_params = dict(input_params)
+
+    for field_name, (artifact_class, expects_list) in artifact_field_map.items():
+        field_value = resolved_params.get(field_name)
+
+        # Skip if field is not present
+        if field_value is None:
+            continue
+
+        # Skip if already artifacts (already resolved)
+        if isinstance(field_value, list) and all(
+            isinstance(item, artifact_class) for item in field_value
+        ):
+            continue
+
+        # Also check for single artifact (only if field expects a single artifact)
+        if not expects_list and isinstance(field_value, artifact_class):
+            continue
+
+        # Convert field value to list of UUIDs
+        generation_ids: list[str | UUID]
+        if isinstance(field_value, str):
+            # Single generation ID - convert to list for processing
+            generation_ids = [field_value]
+        elif isinstance(field_value, list):
+            # List of generation IDs - ensure all are strings
+            # Convert each item to str to ensure type consistency
+            generation_ids = [str(item) for item in field_value]
+        else:
+            raise ValueError(
+                f"Field '{field_name}' must be a generation ID (UUID string) "
+                f"or list of generation IDs, got: {type(field_value)}"
+            )
+
+        # Resolve to artifacts
+        try:
+            artifacts = await resolve_generation_ids_to_artifacts(
+                generation_ids, artifact_class, session, tenant_id
+            )
+        except ValueError as e:
+            raise ValueError(f"Failed to resolve field '{field_name}': {e}") from e
+
+        # Update params with resolved artifacts
+        # If field expects a single artifact (not a list), unwrap the first artifact
+        # Otherwise, keep as a list (even if there's only one artifact)
+        if expects_list:
+            resolved_value = artifacts
+        else:
+            # Field expects a single artifact, so unwrap
+            if len(artifacts) != 1:
+                raise ValueError(
+                    f"Field '{field_name}' expects a single artifact, "
+                    f"but got {len(artifacts)} generation IDs"
+                )
+            resolved_value = artifacts[0]
+
+        # Debug logging
+        logger.debug(
+            "Resolved artifact field",
+            field_name=field_name,
+            expects_list=expects_list,
+            artifacts_type=type(artifacts),
+            artifacts_len=len(artifacts),
+            resolved_value_type=type(resolved_value),
+        )
+
+        resolved_params[field_name] = resolved_value
+
+    return resolved_params

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

@@ -96,6 +96,7 @@ class GeneratorExecutionContext(Protocol):
         format: str,
         width: int,
         height: int,
+        output_index: int = 0,
     ) -> ImageArtifact:
         """Store an image result to permanent storage."""
         ...
@@ -108,6 +109,7 @@ class GeneratorExecutionContext(Protocol):
         height: int,
         duration: float | None = None,
         fps: float | None = None,
+        output_index: int = 0,
     ) -> VideoArtifact:
         """Store a video result to permanent storage."""
         ...
@@ -119,6 +121,7 @@ class GeneratorExecutionContext(Protocol):
         duration: float | None = None,
         sample_rate: int | None = None,
         channels: int | None = None,
+        output_index: int = 0,
     ) -> AudioArtifact:
         """Store an audio result to permanent storage."""
         ...
@@ -127,6 +130,7 @@ class GeneratorExecutionContext(Protocol):
         self,
         content: str,
         format: str,
+        output_index: int = 0,
     ) -> TextArtifact:
         """Store a text result to permanent storage."""
         ...

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

@@ -4,9 +4,11 @@ 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.
 
+Generators are organized by provider (Replicate, Fal, OpenAI, etc.).
+
 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
+# Import all provider modules to make them available
+from . import fal, openai, replicate

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

@@ -0,0 +1,25 @@
+"""Fal.ai provider generators."""
+
+from . import audio, image, video
+from .image import (
+    FalFluxProUltraGenerator,
+    FalNanoBananaEditGenerator,
+    FalNanoBananaGenerator,
+)
+from .video import (
+    FalKlingVideoV25TurboProTextToVideoGenerator,
+    FalSyncLipsyncV2Generator,
+    FalVeo31FirstLastFrameToVideoGenerator,
+)
+
+# Maintain alphabetical order
+__all__ = [
+    # Image generators
+    "FalFluxProUltraGenerator",
+    "FalNanoBananaEditGenerator",
+    "FalNanoBananaGenerator",
+    # Video generators
+    "FalKlingVideoV25TurboProTextToVideoGenerator",
+    "FalSyncLipsyncV2Generator",
+    "FalVeo31FirstLastFrameToVideoGenerator",
+]

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

@@ -0,0 +1,4 @@
+from .minimax_music_v2 import FalMinimaxMusicV2Generator
+from .minimax_speech_2_6_turbo import FalMinimaxSpeech26TurboGenerator
+
+__all__ = ["FalMinimaxSpeech26TurboGenerator", "FalMinimaxMusicV2Generator"]