@weirdfingers/baseboards 0.2.0

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

@@ -0,0 +1 @@
+"""Workers package: Dramatiq actors and execution utilities."""

package/templates/api/src/boards/workers/actors.py

@@ -0,0 +1,201 @@
+"""Dramatiq actors for generation processing."""
+
+from __future__ import annotations
+
+import traceback
+
+import dramatiq
+from dramatiq import actor
+from dramatiq.brokers.redis import RedisBroker
+from dramatiq.middleware import AsyncIO
+
+from ..config import Settings
+from ..database.connection import get_async_session
+from ..generators.registry import registry as generator_registry
+from ..jobs import repository as jobs_repo
+from ..logging import get_logger
+from ..progress.models import ProgressUpdate
+from ..progress.publisher import ProgressPublisher
+from ..storage.factory import create_storage_manager
+from .context import GeneratorExecutionContext
+from .middleware import GeneratorLoaderMiddleware
+
+logger = get_logger(__name__)
+
+
+settings = Settings()
+broker = RedisBroker(url=settings.redis_url)
+dramatiq.set_broker(broker)
+
+# Enable async actor support - Dramatiq will manage event loops per thread
+# This avoids the event loop conflicts from using asyncio.run()
+broker.add_middleware(AsyncIO())
+
+# Load generators when worker process starts via middleware
+# Middleware runs before_worker_boot hook once per worker process at startup
+broker.add_middleware(GeneratorLoaderMiddleware())
+
+
+@actor(queue_name="boards-jobs", max_retries=3, min_backoff=5000, max_backoff=30000)
+async def process_generation(generation_id: str) -> None:
+    """Entry actor: load job context and dispatch to the generator.
+
+    Retry policy:
+    - max_retries: 3 attempts
+    - min_backoff: 5 seconds
+    - max_backoff: 30 seconds
+
+    Note: This is an async actor. Dramatiq manages the event loop lifecycle properly,
+    avoiding the event loop conflicts that would occur with asyncio.run().
+
+    Process a generation job with comprehensive error handling.
+    """
+    logger.info("Starting generation processing", generation_id=generation_id)
+
+    publisher = ProgressPublisher(settings)
+
+    try:
+        # Initialize processing
+        await publisher.publish_progress(
+            generation_id,
+            ProgressUpdate(
+                job_id=generation_id,
+                status="processing",
+                progress=0.0,
+                phase="initializing",
+            ),
+        )
+
+        # Load generation from DB
+        async with get_async_session() as session:
+            gen = await jobs_repo.get_generation(session, generation_id)
+            # Access all attributes while session is active to avoid DetachedInstanceError
+            generator_name = gen.generator_name
+            input_params = gen.input_params
+            gen_id = gen.id
+            tenant_id = gen.tenant_id
+            board_id = gen.board_id
+
+        # Initialize storage manager
+        # This will use the default storage configuration from environment/config
+        storage_manager = create_storage_manager()
+
+        # Validate generator exists
+        generator = generator_registry.get(generator_name)
+        if generator is None:
+            error_msg = "Unknown generator"
+            logger.error(error_msg, generator_name=generator_name)
+            raise RuntimeError(f"Unknown generator: {generator_name}")
+
+        # Build and validate typed inputs
+        try:
+            input_schema = generator.get_input_schema()
+            typed_inputs = input_schema.model_validate(input_params)
+        except Exception as e:
+            error_msg = "Invalid input parameters"
+            logger.error(error_msg, generation_id=generation_id, error=str(e))
+            raise ValueError(f"Invalid input parameters: {e}") from e
+
+        # Build context and run generator
+        # TODO(generators): make a way for a generator to add additional generations
+        # based on eg outputs=4, or similar.
+        context = GeneratorExecutionContext(gen_id, publisher, storage_manager, tenant_id, board_id)
+
+        await publisher.publish_progress(
+            generation_id,
+            ProgressUpdate(
+                job_id=generation_id,
+                status="processing",
+                progress=0.05,
+                phase="processing",
+                message="Starting generation",
+            ),
+        )
+
+        # Execute generator
+        logger.info(
+            "Executing generator",
+            generator_name=generator_name,
+            generation_id=generation_id,
+        )
+        # TODO: Consider implementing credit refund logic on failure
+        # await refund_credits(gen.user_id, gen.estimated_cost)
+        output = await generator.generate(typed_inputs, context)
+        logger.info(
+            "Generator completed successfully",
+            generator_name=generator_name,
+            generation_id=generation_id,
+        )
+
+        # Find the artifact with matching generation_id
+        # Generators should return exactly one artifact with the matching generation_id
+        matching_artifacts = [art for art in output.outputs if art.generation_id == generation_id]
+
+        if len(matching_artifacts) == 0:
+            raise RuntimeError(
+                f"No artifact found with generation_id {generation_id} in generator output. "
+                f"Generator returned {len(output.outputs)} artifact(s) but none matched."
+            )
+
+        if len(matching_artifacts) > 1:
+            logger.warning(
+                "Generator returned multiple artifacts with same generation_id, using first one",
+                generation_id=generation_id,
+                artifact_count=len(matching_artifacts),
+            )
+
+        artifact = matching_artifacts[0]
+
+        # Extract storage URL and convert artifact to dict
+        storage_url = artifact.storage_url
+        output_metadata = artifact.model_dump()
+
+        # Finalize DB with storage URL and output metadata
+        async with get_async_session() as session:
+            await jobs_repo.finalize_success(
+                session,
+                generation_id,
+                storage_url=storage_url,
+                output_metadata=output_metadata,
+            )
+
+        logger.info("Job finalized successfully", generation_id=generation_id)
+
+        # Publish completion (DB already updated by finalize_success)
+        await publisher.publish_only(
+            generation_id,
+            ProgressUpdate(
+                job_id=generation_id,
+                status="completed",
+                progress=1.0,
+                phase="finalizing",
+                message="Completed",
+            ),
+        )
+
+    except Exception as e:
+        # Log the full traceback for debugging
+        logger.error(
+            "Job failed with error",
+            generation_id=generation_id,
+            error=str(e),
+            traceback=traceback.format_exc(),
+        )
+
+        # Publish failure status (this also persists to DB via ProgressPublisher)
+        try:
+            await publisher.publish_progress(
+                generation_id,
+                ProgressUpdate(
+                    job_id=generation_id,
+                    status="failed",
+                    progress=0.0,
+                    phase="finalizing",
+                    message=str(e),
+                ),
+            )
+        except Exception as pub_error:
+            logger.error("Failed to publish error status", error=str(pub_error))
+
+        # Re-raise for Dramatiq retry mechanism
+        # raise

package/templates/api/src/boards/workers/cli.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""
+CLI entry point for Boards background workers.
+
+For auto-reload during development, use a file watcher like entr or nodemon:
+
+    # Using entr (recommended):
+    make dev-worker-watch
+
+    # Or manually with entr:
+    find packages/backend/src -name '*.py' | entr -r uv run boards-worker
+
+    # Using nodemon:
+    nodemon --watch packages/backend/src --exec "uv run boards-worker"
+"""
+
+import sys
+
+import click
+
+from boards import __version__
+from boards.logging import configure_logging, get_logger
+
+logger = get_logger(__name__)
+
+
+def start_worker(
+    processes: int,
+    threads: int,
+    queue_list: list[str],
+    log_level: str,
+) -> None:
+    """Start the Dramatiq worker process."""
+    # Configure logging
+    configure_logging(debug=(log_level == "debug"))
+
+    try:
+        # Import workers to register them (if they exist)
+        try:
+            from boards.workers import actors  # noqa: F401
+        except ImportError:
+            logger.warning("No worker actors found - continuing with empty worker")
+
+        # Start the worker
+        from dramatiq.cli import main as dramatiq_main
+
+        # Build dramatiq CLI args
+        args = [
+            "dramatiq",
+            "boards.workers.actors",
+            f"--processes={processes}",
+            f"--threads={threads}",
+        ]
+
+        for queue in queue_list:
+            args.extend(["--queues", queue])
+
+        # Override sys.argv for dramatiq CLI
+        original_argv = sys.argv
+        sys.argv = args
+
+        dramatiq_main()
+
+    except KeyboardInterrupt:
+        logger.info("Worker shutdown requested by user")
+    except Exception as e:
+        logger.error("Worker startup failed", error=str(e))
+        sys.exit(1)
+    finally:
+        # Restore original argv
+        sys.argv = original_argv
+
+
+@click.command()
+@click.option(
+    "--processes",
+    default=1,
+    type=int,
+    help="Number of worker processes (default: 1)",
+)
+@click.option(
+    "--threads",
+    default=1,
+    type=int,
+    help="Number of worker threads per process (default: 1)",
+)
+@click.option(
+    "--queues",
+    default="boards-jobs",
+    help="Comma-separated list of queues to process (default: boards-jobs)",
+)
+@click.option(
+    "--log-level",
+    default="info",
+    type=click.Choice(["debug", "info", "warning", "error"]),
+    help="Log level (default: info)",
+)
+@click.version_option(version=__version__, prog_name="boards-worker")
+def main(
+    processes: int,
+    threads: int,
+    queues: str,
+    log_level: str,
+) -> None:
+    """Start Boards background workers."""
+
+    # Configure logging
+    configure_logging(debug=(log_level == "debug"))
+
+    queue_list = [q.strip() for q in queues.split(",")]
+
+    logger.info(
+        "Starting Boards workers",
+        processes=processes,
+        threads=threads,
+        queues=queue_list,
+        log_level=log_level,
+    )
+
+    start_worker(processes, threads, queue_list, log_level)
+
+
+# meaningless
+if __name__ == "__main__":
+    main()

package/templates/api/src/boards/workers/context.py

@@ -0,0 +1,188 @@
+"""Execution context passed to generators for storage/DB/progress access."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from ..database.connection import get_async_session
+from ..generators import resolution
+from ..generators.artifacts import AudioArtifact, ImageArtifact, TextArtifact, VideoArtifact
+from ..jobs import repository as jobs_repo
+from ..logging import get_logger
+from ..progress.models import ProgressUpdate
+from ..progress.publisher import ProgressPublisher
+from ..storage.base import StorageManager
+
+logger = get_logger(__name__)
+
+
+class GeneratorExecutionContext:
+    def __init__(
+        self,
+        generation_id: UUID,
+        publisher: ProgressPublisher,
+        storage_manager: StorageManager,
+        tenant_id: UUID,
+        board_id: UUID,
+    ) -> None:
+        self.generation_id = str(generation_id)
+        self.publisher = publisher
+        self.storage_manager = storage_manager
+        self.tenant_id = str(tenant_id)
+        self.board_id = str(board_id)
+        logger.info(
+            "Created execution context",
+            generation_id=str(generation_id),
+            tenant_id=str(tenant_id),
+            board_id=str(board_id),
+        )
+
+    async def resolve_artifact(self, artifact) -> str:
+        """Resolve an artifact to a file path."""
+        logger.debug("Resolving artifact", generation_id=self.generation_id)
+        try:
+            result = await resolution.resolve_artifact(artifact)
+            logger.debug("Artifact resolved successfully", result=result)
+            return result
+        except Exception as e:
+            logger.error("Failed to resolve artifact", error=str(e))
+            raise
+
+    async def store_image_result(
+        self,
+        storage_url: str,
+        format: str,
+        width: int,
+        height: int,
+    ) -> ImageArtifact:
+        """Store image generation result."""
+        logger.debug("Storing image result", generation_id=self.generation_id)
+        try:
+            result = await resolution.store_image_result(
+                storage_manager=self.storage_manager,
+                generation_id=self.generation_id,
+                tenant_id=self.tenant_id,
+                board_id=self.board_id,
+                storage_url=storage_url,
+                format=format,
+                width=width,
+                height=height,
+            )
+            logger.info("Image result stored", generation_id=self.generation_id)
+            return result
+        except Exception as e:
+            logger.error("Failed to store image result", error=str(e))
+            raise
+
+    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 video generation result."""
+        logger.debug("Storing video result", generation_id=self.generation_id)
+        try:
+            result = await resolution.store_video_result(
+                storage_manager=self.storage_manager,
+                generation_id=self.generation_id,
+                tenant_id=self.tenant_id,
+                board_id=self.board_id,
+                storage_url=storage_url,
+                format=format,
+                width=width,
+                height=height,
+                duration=duration,
+                fps=fps,
+            )
+            logger.info("Video result stored", generation_id=self.generation_id)
+            return result
+        except Exception as e:
+            logger.error("Failed to store video result", error=str(e))
+            raise
+
+    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 audio generation result."""
+        logger.debug("Storing audio result", generation_id=self.generation_id)
+        try:
+            result = await resolution.store_audio_result(
+                storage_manager=self.storage_manager,
+                generation_id=self.generation_id,
+                tenant_id=self.tenant_id,
+                board_id=self.board_id,
+                storage_url=storage_url,
+                format=format,
+                duration=duration,
+                sample_rate=sample_rate,
+                channels=channels,
+            )
+            logger.info("Audio result stored", generation_id=self.generation_id)
+            return result
+        except Exception as e:
+            logger.error("Failed to store audio result", error=str(e))
+            raise
+
+    async def store_text_result(
+        self,
+        content: str,
+        format: str,
+    ) -> TextArtifact:
+        """Store text generation result."""
+        logger.debug("Storing text result", generation_id=self.generation_id)
+        try:
+            result = await resolution.store_text_result(
+                storage_manager=self.storage_manager,
+                generation_id=self.generation_id,
+                tenant_id=self.tenant_id,
+                board_id=self.board_id,
+                content=content,
+                format=format,
+            )
+            logger.info("Text result stored", generation_id=self.generation_id)
+            return result
+        except Exception as e:
+            logger.error("Failed to store text result", error=str(e))
+            raise
+
+    async def publish_progress(self, update: ProgressUpdate) -> None:
+        """Publish progress update for the generation."""
+        logger.debug(
+            "Publishing progress",
+            generation_id=self.generation_id,
+            status=update.status,
+            progress=update.progress,
+        )
+        try:
+            await self.publisher.publish_progress(self.generation_id, update)
+        except Exception as e:
+            logger.error(
+                "Failed to publish progress update - "
+                "generation will continue but progress may not be visible",
+                generation_id=self.generation_id,
+                status=update.status,
+                progress=update.progress,
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+            # Don't raise here - progress updates are non-critical
+            # The generation should continue even if progress updates fail
+
+    async def set_external_job_id(self, external_id: str) -> None:
+        """Set the external job ID from the provider."""
+        logger.info(
+            "Setting external job ID",
+            external_job_id=external_id,
+            generation_id=self.generation_id,
+        )
+        async with get_async_session() as session:
+            await jobs_repo.set_external_job_id(session, self.generation_id, external_id)

package/templates/api/src/boards/workers/middleware.py

@@ -0,0 +1,58 @@
+"""Dramatiq middleware for worker process initialization.
+
+This module provides custom middleware for managing worker lifecycle,
+particularly for loading generators during worker startup.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from dramatiq.middleware import Middleware
+
+from ..config import initialize_generator_api_keys
+from ..generators.loader import load_generators_from_config
+from ..generators.registry import registry as generator_registry
+from ..logging import get_logger
+
+if TYPE_CHECKING:
+    from dramatiq import Broker, Worker
+
+logger = get_logger(__name__)
+
+
+class GeneratorLoaderMiddleware(Middleware):
+    """Middleware to load generators when worker process starts.
+
+    This ensures that generators are registered in each worker process's
+    registry before any jobs are processed. Since Dramatiq uses multiprocessing,
+    each worker process gets its own copy of the registry, so initialization
+    must happen in each process.
+
+    The before_worker_boot hook runs once per worker process at startup,
+    before any actors are executed. Worker processes are long-running and
+    reused across many jobs, so this initialization overhead happens only
+    once per worker lifetime.
+    """
+
+    def before_worker_boot(self, broker: Broker, worker: Worker) -> None:
+        """Load generators when worker process starts.
+
+        Args:
+            broker: The Dramatiq broker instance
+            worker: The worker process instance
+        """
+        logger.info("Loading generators in worker process", worker_id=id(worker))
+
+        # Initialize generator API keys before loading generators
+        initialize_generator_api_keys()
+        logger.info("Generator API keys initialized in worker process")
+
+        load_generators_from_config()
+
+        logger.info(
+            "Generators loaded in worker process",
+            worker_id=id(worker),
+            generator_count=len(generator_registry.list_names()),
+            generators=generator_registry.list_names(),
+        )

package/templates/compose.dev.yaml

@@ -0,0 +1,39 @@
+# Development overrides for Docker Compose
+# Enables hot reload by mounting source code
+
+services:
+  api:
+    volumes:
+      - ./api:/app
+      - ./data/storage:/app/data/storage
+    environment:
+      - PYTHONUNBUFFERED=1
+    command:
+      [
+        "uvicorn",
+        "boards.api.app:app",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "8800",
+        "--reload",
+        "--log-level",
+        "debug",
+      ]
+
+  worker:
+    volumes:
+      - ./api:/app
+      - ./data/storage:/app/data/storage
+    environment:
+      - PYTHONUNBUFFERED=1
+
+  web:
+    command: sh -c "pnpm install && pnpm dev"
+    volumes:
+      - ./web:/app
+      - /app/node_modules
+      - /app/.next
+    environment:
+      - NODE_ENV=development
+      - INTERNAL_API_URL=http://api:8800