@weirdfingers/baseboards 0.2.0

package/templates/api/docs/GENERATORS_API.md

@@ -0,0 +1,502 @@
+# Generators API Reference
+
+This document provides detailed API reference for the Boards generators system.
+
+## Core Classes
+
+### BaseGenerator
+
+Abstract base class for all generators.
+
+```python
+from boards.generators.base import BaseGenerator
+
+class MyGenerator(BaseGenerator):
+    name: str                    # Unique identifier for the generator
+    artifact_type: str          # Type of artifact produced ('image', 'video', 'audio', 'text', 'lora')  
+    description: str            # Human-readable description
+    
+    def get_input_schema(self) -> Type[BaseModel]:
+        """Return Pydantic model class for input validation."""
+        pass
+    
+    async def generate(self, inputs: BaseModel) -> BaseModel:
+        """Execute generation and return results."""
+        pass
+    
+    async def estimate_cost(self, inputs: BaseModel) -> float:
+        """Estimate cost in USD for this generation."""
+        pass
+    
+    def get_output_schema(self) -> Type[BaseModel]:
+        """Return Pydantic model class for output (optional override)."""
+        pass
+```
+
+#### Required Attributes
+
+- **`name`**: Unique string identifier (e.g., `"flux-pro"`, `"whisper"`)
+- **`artifact_type`**: One of `"image"`, `"video"`, `"audio"`, `"text"`, `"lora"`
+- **`description`**: Brief description of what the generator does
+
+#### Required Methods
+
+- **`get_input_schema()`**: Return the Pydantic model class that defines valid inputs
+- **`generate(inputs)`**: Core generation logic that produces artifacts
+- **`estimate_cost(inputs)`**: Return estimated cost in USD as a float
+
+## Artifact Types
+
+### ImageArtifact
+
+Represents generated or input images.
+
+```python
+from boards.generators.artifacts import ImageArtifact
+
+artifact = ImageArtifact(
+    generation_id="gen_123",        # ID of generation that created this
+    storage_url="https://...",      # URL where image is stored  
+    width=1024,                     # Image width in pixels
+    height=1024,                    # Image height in pixels
+    format="png"                    # Image format (png, jpg, webp, etc.)
+)
+```
+
+### VideoArtifact
+
+Represents generated or input videos.
+
+```python
+from boards.generators.artifacts import VideoArtifact
+
+artifact = VideoArtifact(
+    generation_id="gen_456",        # Required: generation ID
+    storage_url="https://...",      # Required: storage location
+    width=1920,                     # Required: video width
+    height=1080,                    # Required: video height  
+    format="mp4",                   # Required: video format
+    duration=60.5,                  # Optional: duration in seconds
+    fps=30.0                        # Optional: frames per second
+)
+```
+
+### AudioArtifact
+
+Represents generated or input audio.
+
+```python
+from boards.generators.artifacts import AudioArtifact
+
+artifact = AudioArtifact(
+    generation_id="gen_789",        # Required: generation ID
+    storage_url="https://...",      # Required: storage location
+    format="mp3",                   # Required: audio format
+    duration=120.0,                 # Optional: duration in seconds
+    sample_rate=44100,              # Optional: sample rate in Hz
+    channels=2                      # Optional: number of channels
+)
+```
+
+### TextArtifact
+
+Represents generated or input text.
+
+```python
+from boards.generators.artifacts import TextArtifact
+
+artifact = TextArtifact(
+    generation_id="gen_text",       # Required: generation ID
+    content="Generated text...",    # Required: the actual text content
+    format="plain"                  # Optional: format (plain, markdown, html)
+)
+```
+
+### LoRArtifact
+
+Represents LoRA (Low-Rank Adaptation) models.
+
+```python
+from boards.generators.artifacts import LoRArtifact
+
+artifact = LoRArtifact(
+    generation_id="gen_lora",       # Required: generation ID
+    storage_url="https://...",      # Required: storage location
+    base_model="sd-v1.5",          # Required: base model name
+    format="safetensors",           # Required: file format
+    trigger_words=["style1", "tag"] # Optional: trigger words list
+)
+```
+
+## Generator Registry
+
+### Global Registry
+
+The system provides a global registry for managing generators:
+
+```python
+from boards.generators.registry import registry
+
+# Register a generator
+generator_instance = MyGenerator()
+registry.register(generator_instance)
+
+# Get a generator by name
+generator = registry.get("my-generator")
+
+# List all generators
+all_generators = registry.list_all()
+
+# List generators by artifact type
+image_generators = registry.list_by_artifact_type("image")
+
+# Check if generator exists
+if "my-generator" in registry:
+    print("Generator is registered")
+
+# Get count of registered generators
+count = len(registry)
+```
+
+### GeneratorRegistry Methods
+
+```python
+class GeneratorRegistry:
+    def register(self, generator: BaseGenerator) -> None:
+        """Register a generator instance."""
+    
+    def get(self, name: str) -> Optional[BaseGenerator]:
+        """Get generator by name, returns None if not found."""
+    
+    def list_all(self) -> List[BaseGenerator]:
+        """Return all registered generators."""
+    
+    def list_by_artifact_type(self, artifact_type: str) -> List[BaseGenerator]:
+        """Return generators that produce the specified artifact type."""
+    
+    def list_names(self) -> List[str]:
+        """Return list of all registered generator names."""
+    
+    def unregister(self, name: str) -> bool:
+        """Remove generator by name. Returns True if found and removed."""
+    
+    def clear(self) -> None:
+        """Remove all registered generators."""
+    
+    def __contains__(self, name: str) -> bool:
+        """Check if generator with name is registered."""
+    
+    def __len__(self) -> int:
+        """Return number of registered generators."""
+```
+
+## Artifact Resolution
+
+### resolve_artifact()
+
+Converts artifact references to local file paths for use with provider SDKs:
+
+```python
+from boards.generators.resolution import resolve_artifact
+
+async def generate(self, inputs):
+    # Resolve artifacts to local file paths
+    audio_path = await resolve_artifact(inputs.audio_source)
+    video_path = await resolve_artifact(inputs.video_source)
+    
+    # Now you can pass file paths to any provider SDK
+    result = await provider.process(audio=audio_path, video=video_path)
+```
+
+**Supported artifacts**: `AudioArtifact`, `VideoArtifact`, `ImageArtifact`, `LoRArtifact`
+
+**Not supported**: `TextArtifact` (use `.content` property directly)
+
+### Store Result Functions
+
+Create artifact instances from generated content:
+
+```python
+from boards.generators.resolution import (
+    store_image_result,
+    store_video_result, 
+    store_audio_result
+)
+
+# Store generated image
+image_artifact = await store_image_result(
+    storage_url="https://storage.com/image.png",
+    format="png",
+    generation_id="gen_123",
+    width=1024,
+    height=1024
+)
+
+# Store generated video  
+video_artifact = await store_video_result(
+    storage_url="https://storage.com/video.mp4",
+    format="mp4", 
+    generation_id="gen_456",
+    width=1920,
+    height=1080,
+    duration=60.0,      # Optional
+    fps=30.0           # Optional  
+)
+
+# Store generated audio
+audio_artifact = await store_audio_result(
+    storage_url="https://storage.com/audio.mp3",
+    format="mp3",
+    generation_id="gen_789", 
+    duration=120.0,     # Optional
+    sample_rate=44100,  # Optional
+    channels=2          # Optional
+)
+```
+
+## Pydantic Integration
+
+### Input Schema Patterns
+
+#### Basic Inputs
+
+```python
+from pydantic import BaseModel, Field
+
+class BasicInput(BaseModel):
+    prompt: str = Field(description="Text prompt")
+    strength: float = Field(default=0.75, ge=0.0, le=1.0, description="Generation strength")
+    seed: Optional[int] = Field(None, description="Random seed")
+```
+
+#### Artifact Inputs
+
+```python
+class ArtifactInput(BaseModel):
+    image_source: ImageArtifact = Field(description="Input image")
+    audio_source: AudioArtifact = Field(description="Input audio")
+    reference_text: TextArtifact = Field(description="Reference text")
+```
+
+#### Validation and Constraints
+
+```python
+from pydantic import field_validator
+
+class ValidatedInput(BaseModel):
+    prompt: str = Field(min_length=1, max_length=500)
+    quality: str = Field(pattern="^(low|medium|high)$")
+    dimensions: str = Field(pattern="^\\d+x\\d+$")
+    
+    @field_validator('prompt')
+    @classmethod
+    def validate_prompt(cls, v):
+        if 'forbidden' in v.lower():
+            raise ValueError('Prompt contains forbidden content')
+        return v.strip()
+```
+
+#### Conditional Fields
+
+```python
+class ConditionalInput(BaseModel):
+    mode: str = Field(pattern="^(text|image)$")
+    text_prompt: Optional[str] = Field(None)
+    image_prompt: Optional[ImageArtifact] = Field(None)
+    
+    @model_validator(mode='after')
+    def validate_conditional_fields(self):
+        if self.mode == 'text' and not self.text_prompt:
+            raise ValueError('text_prompt required when mode=text')
+        elif self.mode == 'image' and not self.image_prompt:
+            raise ValueError('image_prompt required when mode=image')
+        return self
+```
+
+### Output Schema Patterns
+
+#### Simple Outputs
+
+```python
+class SimpleOutput(BaseModel):
+    result: ImageArtifact
+    metadata: dict = Field(default_factory=dict)
+```
+
+#### Multiple Artifacts
+
+```python  
+class MultiOutput(BaseModel):
+    images: List[ImageArtifact] = Field(description="Generated images")
+    preview: ImageArtifact = Field(description="Low-res preview")
+    generation_time: float = Field(description="Time taken in seconds")
+```
+
+## JSON Schema Generation
+
+Pydantic models automatically generate JSON schemas for frontend integration:
+
+```python
+# Get JSON schema for frontend type generation
+schema = MyInputClass.model_json_schema()
+
+# Example output:
+{
+    "type": "object",
+    "properties": {
+        "prompt": {
+            "type": "string", 
+            "description": "Text prompt",
+            "minLength": 1,
+            "maxLength": 500
+        },
+        "strength": {
+            "type": "number",
+            "minimum": 0.0,
+            "maximum": 1.0,
+            "default": 0.75,
+            "description": "Generation strength"
+        }
+    },
+    "required": ["prompt"]
+}
+```
+
+## Error Handling
+
+### Common Error Patterns
+
+```python
+async def generate(self, inputs):
+    # Check environment variables
+    api_key = os.getenv("PROVIDER_API_KEY")
+    if not api_key:
+        raise ValueError(
+            "PROVIDER_API_KEY environment variable required. "
+            "Get your key from https://provider.com/keys"
+        )
+    
+    # Provider-specific error handling
+    try:
+        result = await provider.generate(inputs)
+    except provider.AuthenticationError:
+        raise ValueError("Invalid API key - check PROVIDER_API_KEY")
+    except provider.RateLimitError as e:
+        raise ValueError(f"Rate limited - retry after {e.retry_after} seconds")
+    except provider.ValidationError as e:
+        raise ValueError(f"Invalid input: {e.message}")
+    except Exception as e:
+        raise RuntimeError(f"Generation failed: {str(e)}")
+```
+
+### Best Practices
+
+1. **Specific Error Messages**: Provide actionable error messages
+2. **Environment Variable Checks**: Validate required configuration early
+3. **Provider Error Translation**: Convert provider errors to user-friendly messages
+4. **Resource Cleanup**: Clean up temporary files in finally blocks
+
+## Testing
+
+### Generator Testing Pattern
+
+```python
+import pytest
+from unittest.mock import patch, AsyncMock
+
+class TestMyGenerator:
+    def setup_method(self):
+        self.generator = MyGenerator()
+    
+    def test_metadata(self):
+        assert self.generator.name == "my-generator"
+        assert self.generator.artifact_type == "image"
+    
+    def test_input_schema(self):
+        schema_class = self.generator.get_input_schema()
+        assert schema_class == MyInputClass
+        
+        # Test schema validation
+        valid_input = schema_class(prompt="test")
+        assert valid_input.prompt == "test"
+    
+    @pytest.mark.asyncio
+    async def test_generate_success(self):
+        inputs = MyInputClass(prompt="test prompt")
+        
+        with patch.dict(os.environ, {"API_KEY": "fake-key"}):
+            with patch('provider.generate') as mock_generate:
+                mock_generate.return_value = "fake_result_url"
+                
+                result = await self.generator.generate(inputs)
+                
+                assert isinstance(result, MyOutputClass)
+                mock_generate.assert_called_once()
+    
+    @pytest.mark.asyncio 
+    async def test_generate_missing_api_key(self):
+        inputs = MyInputClass(prompt="test")
+        
+        with patch.dict(os.environ, {}, clear=True):
+            with pytest.raises(ValueError, match="API_KEY.*required"):
+                await self.generator.generate(inputs)
+    
+    @pytest.mark.asyncio
+    async def test_estimate_cost(self):
+        inputs = MyInputClass(prompt="short")
+        cost = await self.generator.estimate_cost(inputs)
+        
+        assert isinstance(cost, float)
+        assert cost > 0
+```
+
+## Integration Points
+
+### Storage System Integration
+
+Generators integrate with the Boards storage system through the resolution utilities:
+
+```python
+# The store_*_result functions will be implemented to:
+# 1. Upload content to configured storage backend (S3, local, etc.)  
+# 2. Return artifact with proper storage_url
+# 3. Handle metadata and thumbnails
+```
+
+### Database Integration
+
+Generated artifacts are automatically stored in the database with:
+
+- Generation metadata (model, parameters, cost)
+- Artifact metadata (dimensions, duration, format)
+- Relationships to boards and users
+- Audit trail information
+
+### GraphQL API Integration
+
+Registered generators are automatically exposed via GraphQL:
+
+```graphql
+query GetGenerators($artifactType: String) {
+  generators(artifactType: $artifactType) {
+    name
+    artifactType
+    description
+    inputSchema  # JSON schema for frontend
+  }
+}
+
+mutation RunGeneration($generatorName: String!, $inputs: JSON!) {
+  runGeneration(generatorName: $generatorName, inputs: $inputs) {
+    id
+    status
+    result {
+      ... on ImageArtifact {
+        storageUrl
+        width
+        height
+      }
+    }
+  }
+}
+```