Skip to content

AI-powered video editor that turns raw footage and a creative brief into a polished ad using an ensemble of AI agents (Google Gemini + FFmpeg)

Python
12.0 KB
Raw Blame
"""CLI entry point: raw footage + creative brief → rendered ad.

This module exposes the single user-facing entry point for the agentic
video editor. It wires together the preprocess step
(:func:`src.pipeline.preprocess.preprocess_footage`) and the pipeline
runner (:func:`src.pipeline.runner.run_pipeline`) behind a Click CLI so
the happy path is one command::

    python -m src.main edit \\
        --footage-dir ~/Downloads/footage/A-Roll \\
        --brief '{"product": "My Product", "audience": "Women 25-45", \\
                  "tone": "authentic, confident", "duration_seconds": 30}' \\
        --style styles/dtc-testimonial.yaml

The CLI itself owns no FFmpeg, Gemini, or agent logic — it only:

* Validates and normalizes inputs (footage directory, brief JSON or
  JSON file, style override, output directory).
* Calls :func:`preprocess_footage` to build (or reuse) a
  :class:`~src.models.schemas.FootageIndex` on disk.
* Calls :func:`run_pipeline` to drive the Director → Editor → Reviewer
  loop defined by the selected YAML manifest.
* Prints a human-readable summary of the run (output path, review
  dimensions, retries, warnings, total duration).

All hard errors (missing files, bad JSON, validation failures, FFmpeg
crashes, API errors) are raised as :class:`click.ClickException`, which
Click maps to exit code 1. Unexpected exceptions propagate so Click can
render a traceback — those are real bugs the caller should see.
"""

from __future__ import annotations

import json
import sys
import time
from pathlib import Path

import click
import yaml
from pydantic import ValidationError

from src.models.schemas import CreativeBrief
from src.pipeline.preprocess import preprocess_footage
from src.pipeline.runner import PipelineResult, run_pipeline

DEFAULT_PIPELINE = "pipelines/ugc-ad.yaml"
DEFAULT_OUTPUT_DIR = "output"
FOOTAGE_INDEX_FILENAME = "footage_index.json"


def _parse_brief(raw: str) -> CreativeBrief:
    """Parse a ``--brief`` value as either inline JSON or a JSON file path.

    The heuristic is: try ``json.loads`` on the raw string first. If it
    parses to a mapping, treat that as the inline brief. Otherwise, if
    the raw string resolves to an existing file on disk, read the file
    and parse its contents. Anything else is a user error.

    Args:
        raw: The verbatim ``--brief`` option value from the command line.

    Returns:
        A validated :class:`CreativeBrief`.

    Raises:
        click.ClickException: If the string is neither valid JSON nor an
            existing file, or if the resulting payload fails
            :class:`CreativeBrief` validation.
    """
    payload: object | None = None
    inline_error: Exception | None = None
    try:
        payload = json.loads(raw)
    except json.JSONDecodeError as exc:
        inline_error = exc

    if not isinstance(payload, dict):
        candidate = Path(raw).expanduser()
        if candidate.exists() and candidate.is_file():
            try:
                file_text = candidate.read_text(encoding="utf-8")
            except OSError as exc:
                raise click.ClickException(
                    f"--brief file {candidate} could not be read: {exc}"
                ) from exc
            try:
                payload = json.loads(file_text)
            except json.JSONDecodeError as exc:
                raise click.ClickException(
                    f"--brief file {candidate} is not valid JSON: {exc}"
                ) from exc
        else:
            detail = (
                f" (JSON parse error: {inline_error})"
                if inline_error is not None
                else ""
            )
            raise click.ClickException(
                f"--brief {raw!r} is neither inline JSON nor an existing "
                f"file path{detail}"
            )

    if not isinstance(payload, dict):
        raise click.ClickException(
            f"--brief must resolve to a JSON object, got "
            f"{type(payload).__name__}"
        )

    try:
        return CreativeBrief.model_validate(payload)
    except ValidationError as exc:
        raise click.ClickException(
            f"--brief failed CreativeBrief validation: {exc}"
        ) from exc


def _apply_style_override(brief: CreativeBrief, style_path: Path) -> CreativeBrief:
    """Return a copy of ``brief`` with ``style_ref`` set to an absolute path.

    Args:
        brief: A validated brief — never mutated in place.
        style_path: Path to the style YAML from the ``--style`` option.

    Returns:
        A new :class:`CreativeBrief` with ``style_ref`` pointing at the
        resolved absolute path of the style file.

    Raises:
        click.ClickException: If ``style_path`` does not exist on disk.
    """
    resolved = style_path.expanduser().resolve()
    if not resolved.exists() or not resolved.is_file():
        raise click.ClickException(
            f"--style file does not exist: {style_path}"
        )
    return brief.model_copy(update={"style_ref": str(resolved)})


def _print_summary(result: PipelineResult, duration_seconds: float) -> None:
    """Render a human-readable summary of a completed pipeline run."""
    click.echo("")
    click.echo("=" * 60)
    click.echo("Pipeline run summary")
    click.echo("=" * 60)
    click.echo(
        f"output video       : {result.final_video_path or 'none'}"
    )
    review = result.review
    if review is None:
        click.echo("review             : none (pipeline aborted before reviewer)")
    else:
        click.echo("review dimensions  :")
        click.echo(f"  adherence        : {review.adherence:.2f}")
        click.echo(f"  pacing           : {review.pacing:.2f}")
        click.echo(f"  visual_quality   : {review.visual_quality:.2f}")
        click.echo(f"  watchability     : {review.watchability:.2f}")
        click.echo(f"  overall          : {review.overall:.2f}")
    click.echo(f"retries_used       : {result.retries_used}")
    click.echo(f"total duration     : {duration_seconds:.2f}s")
    if result.warnings:
        click.echo("")
        for warning in result.warnings:
            click.echo(f"[pipeline] WARNING: {warning}")
    click.echo("=" * 60)


@click.group()
def cli() -> None:
    """Agentic video editor — raw footage + creative brief → rendered ad."""


@cli.command("edit")
@click.option(
    "--footage-dir",
    "footage_dir",
    required=True,
    type=click.Path(
        exists=False,
        file_okay=False,
        dir_okay=True,
        path_type=Path,
    ),
    help="Directory containing raw footage clips to preprocess.",
)
@click.option(
    "--brief",
    "brief_arg",
    required=True,
    type=str,
    help=(
        "Creative brief as inline JSON OR a path to a .json file. "
        "Must validate against CreativeBrief."
    ),
)
@click.option(
    "--pipeline",
    "pipeline_path",
    type=click.Path(
        exists=False,
        file_okay=True,
        dir_okay=False,
        path_type=Path,
    ),
    default=DEFAULT_PIPELINE,
    show_default=True,
    help="YAML pipeline manifest to run.",
)
@click.option(
    "--style",
    "style_path",
    type=click.Path(
        exists=False,
        file_okay=True,
        dir_okay=False,
        path_type=Path,
    ),
    default=None,
    help=(
        "Optional style YAML. When set, resolved to an absolute path and "
        "assigned to brief.style_ref before the Director runs."
    ),
)
@click.option(
    "--output-dir",
    "output_dir",
    type=click.Path(
        exists=False,
        file_okay=False,
        dir_okay=True,
        path_type=Path,
    ),
    default=DEFAULT_OUTPUT_DIR,
    show_default=True,
    help=(
        "Directory for the cached footage_index.json. Note: rendered "
        "artifacts currently go to the editor agent's default output/ "
        "directory; threading this override through run_pipeline is "
        "deferred to a follow-up story."
    ),
)
@click.option(
    "--skip-preprocess",
    is_flag=True,
    default=False,
    help=(
        "Skip preprocessing when {output-dir}/footage_index.json already "
        "exists. Falls through to preprocess if the index is missing."
    ),
)
@click.option(
    "--no-approval",
    is_flag=True,
    default=False,
    help="Auto-approve human_approval gates (headless/non-interactive runs).",
)
def edit(
    footage_dir: Path,
    brief_arg: str,
    pipeline_path: Path,
    style_path: Path | None,
    output_dir: Path,
    skip_preprocess: bool,
    no_approval: bool,
) -> None:
    """Run the full pipeline: preprocess → director → editor → reviewer."""
    started_at = time.monotonic()

    # Resolve and validate core paths. Expand tildes so shell-style home
    # references work even when Click didn't see them.
    footage_dir = footage_dir.expanduser()
    pipeline_path = pipeline_path.expanduser()
    output_dir = output_dir.expanduser()

    if not pipeline_path.exists() or not pipeline_path.is_file():
        raise click.ClickException(
            f"--pipeline file does not exist: {pipeline_path}"
        )

    output_dir.mkdir(parents=True, exist_ok=True)
    footage_index_path = output_dir / FOOTAGE_INDEX_FILENAME

    brief = _parse_brief(brief_arg)
    if style_path is not None:
        brief = _apply_style_override(brief, style_path)
        click.echo(f"[cli] using style override: {brief.style_ref}")

    # Decide whether to run preprocess. --skip-preprocess is a best-effort
    # hint: if the cached index is missing we fall through to preprocess
    # rather than silently running the pipeline against stale or empty
    # input.
    should_preprocess = True
    if skip_preprocess and footage_index_path.exists():
        should_preprocess = False
        click.echo(
            f"[cli] reusing existing footage index at {footage_index_path}"
        )
    elif skip_preprocess and not footage_index_path.exists():
        click.echo(
            f"[cli] --skip-preprocess set but {footage_index_path} is "
            "missing; running preprocess anyway"
        )

    if should_preprocess:
        if not footage_dir.exists():
            raise click.ClickException(
                f"--footage-dir does not exist: {footage_dir}"
            )
        if not footage_dir.is_dir():
            raise click.ClickException(
                f"--footage-dir is not a directory: {footage_dir}"
            )
        click.echo(
            f"[cli] preprocessing {footage_dir} -> {footage_index_path}"
        )
        try:
            preprocess_footage(
                str(footage_dir),
                str(footage_index_path),
            )
        except (FileNotFoundError, NotADirectoryError, ValueError) as exc:
            raise click.ClickException(
                f"preprocess failed: {exc}"
            ) from exc
        except RuntimeError as exc:
            raise click.ClickException(
                f"preprocess runtime error: {exc}"
            ) from exc

    click.echo(
        f"[cli] running pipeline {pipeline_path} against "
        f"{footage_index_path}"
    )
    try:
        result = run_pipeline(
            str(pipeline_path),
            brief,
            str(footage_index_path),
            human_approval=not no_approval,
        )
    except FileNotFoundError as exc:
        raise click.ClickException(f"pipeline input missing: {exc}") from exc
    except ValidationError as exc:
        raise click.ClickException(
            f"pipeline schema validation failed: {exc}"
        ) from exc
    except yaml.YAMLError as exc:
        raise click.ClickException(
            f"pipeline YAML is malformed: {exc}"
        ) from exc
    except ValueError as exc:
        raise click.ClickException(f"pipeline error: {exc}") from exc
    except RuntimeError as exc:
        raise click.ClickException(
            f"pipeline runtime error: {exc}"
        ) from exc

    duration_seconds = time.monotonic() - started_at
    _print_summary(result, duration_seconds)

    # Successful exit even if the reviewer score was low — AC 6 says a
    # complete-with-warnings run should still exit 0. Only hard errors
    # should exit non-zero, and those all route through ClickException
    # above.
    sys.exit(0)


if __name__ == "__main__":
    cli()