painting_plan.py

"""Painting plan type definitions for VLM-driven artwork planning."""

from typing import TypedDict


class PlanLayer(TypedDict):
    """
    Represents a single layer in a painting plan.

    Each layer defines a stage of the painting process with specific
    instructions for stroke types, colours, and techniques.

    Attributes:
        layer_number (int): Sequential layer number (1-based)
        name (str): Short descriptive name for this layer (e.g. "Background wash")
        description (str): Detailed description of what this layer should achieve
        colour_palette (list[str]): Hex colour codes to use in this layer
        stroke_types (list[str]): Stroke types to use (e.g. line, arc, splatter)
        techniques (str): Painting techniques to apply in this layer
        shapes (str): Description of shapes and forms to create
        highlights (str): Key visual highlights or focal points for this layer
    """

    layer_number: int
    name: str
    description: str
    colour_palette: list[str]
    stroke_types: list[str]
    techniques: str
    shapes: str
    highlights: str


class PaintingPlan(TypedDict):
    """
    Represents a complete painting plan generated by the planner VLM.

    The painting plan breaks down artwork creation into ordered layers,
    each with specific instructions for the stroke VLM to follow.

    Attributes:
        artist_name (str): Target artist whose style to emulate
        subject (str): Brief subject description
        expanded_subject (str | None): Detailed description of the final image
        total_layers (int): Total number of layers in the plan
        layers (list[PlanLayer]): Ordered list of layer definitions
        overall_notes (str): General notes about the painting approach
    """

    artist_name: str
    subject: str
    expanded_subject: str | None
    total_layers: int
    layers: list[PlanLayer]
    overall_notes: str