planning.py

"""
Planning utilities for the agentic WAN‑VACE video generator.

This module defines a simple planner that takes a high‑level concept or topic and
returns a refined text prompt and a recommended negative prompt.  The planner
adds cinematic and visual descriptors to the concept to encourage more
engaging video outputs and recommends a default negative prompt to avoid
common artifacts and low‑quality renderings.

The planner can be replaced or extended with more sophisticated logic or local
LLMs if desired.
"""

from dataclasses import dataclass
from typing import Tuple


@dataclass
class Plan:
    """A dataclass representing a planned prompt and negative prompt."""
    prompt: str
    negative_prompt: str


def plan_from_topic(topic: str) -> Plan:
    """
    Generate a refined prompt and a recommended negative prompt from a high‑level topic.

    The refined prompt enriches the user's concept with cinematic descriptors and
    details that tend to produce appealing vertical videos.  The negative prompt
    includes terms that discourage common undesirable artifacts.

    Parameters
    ----------
    topic: str
        A short description of what the user wants in the video.

    Returns
    -------
    Plan
        An object containing a refined prompt and a negative prompt.
    """
    # Base descriptors to enrich the concept. These tokens help guide the model
    # towards vibrant, cinematic compositions. You can customise these tokens
    # depending on your aesthetic preferences.
    base_descriptors = (
        "cinematic, dynamic motion, rich details, warm lighting, volumetric lighting, "
        "bokeh, warm sun rim light, tracking shot, shallow depth of field, vertical 9:16"
    )
    # Compose the refined prompt
    refined_prompt = f"{topic}, {base_descriptors}"

    # Recommended negative prompt to avoid low‑quality outputs.  Users can
    # override this by supplying their own negative prompt.
    recommended_negative = (
        "blurry, lowres, artifacts, distorted anatomy, dull colors, washed out, "
        "overexposed, underexposed, jitter, bad compression"
    )

    return Plan(prompt=refined_prompt, negative_prompt=recommended_negative)