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
33.3 KB
Raw Blame
"""Pipeline runner: YAML-driven Director → Editor → Reviewer orchestration.

This module is the glue between the three agent modules shipped in
``src.agents.director``, ``src.agents.editor``, and ``src.agents.reviewer``.
It reads a YAML pipeline manifest (see ``pipelines/ugc-ad.yaml``),
executes each step in order, honors optional human-approval gates, and
runs a retry loop that feeds Reviewer feedback back to the Director when
the rendered cut falls below a configured score threshold.

The runner intentionally does **not** reimplement any tool logic — it
calls the public ``run_director`` / ``run_editor`` / ``run_reviewer``
synchronous wrappers and composes their results. The one exception is
retry feedback: ``run_director`` has no parameter for reviewer feedback,
so :func:`_run_director_with_feedback` builds a fresh Agent via
``build_director`` and sends an augmented user message that appends the
feedback history. That helper never modifies the Director module and
mirrors the event-draining loop used by ``run_director`` itself.

Failure semantics
-----------------

* A broken pipeline manifest (unknown agent, bad retry_if block, missing
  steps list) raises ``ValueError`` immediately.
* If the retry budget is exhausted and the final review still trips the
  ``retry_if`` predicate, the runner logs a WARNING and returns a
  :class:`PipelineResult` with the best-effort artifacts plus a non-empty
  ``warnings`` list. It does **not** raise — AC 8 treats this as a
  complete-with-low-score outcome, not a pipeline failure.
* If the user declines the human-approval gate the runner returns a
  :class:`PipelineResult` with ``edit_plan`` set, ``final_video_path``
  and ``review`` left as ``None``, and a warning recording the abort.
* Any exception raised by ``run_director`` / ``run_editor`` /
  ``run_reviewer`` (file-not-found, schema validation, tool failures)
  propagates — those are real bugs the caller should see, not soft
  retryable conditions.

Logging is plain ``print()`` to stdout to match the rest of the project
(see ``src/pipeline/preprocess.py``).
"""

from __future__ import annotations

import asyncio
import shutil
import sys
import time
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Literal

import yaml
from google.adk.runners import InMemoryRunner
from google.genai import errors as genai_errors
from google.genai import types as genai_types
from pydantic import BaseModel, Field, ValidationError

from src.agents.director import (
    _APP_NAME as _DIRECTOR_APP_NAME,
)
from src.agents.director import (
    _USER_ID as _DIRECTOR_USER_ID,
)
from src.agents.director import (
    build_director,
    run_director,
)
from src.agents.editor import run_editor
from src.agents.reviewer import run_reviewer
from src.agents.trim_refiner import refine_plan
from src.models.schemas import CreativeBrief, EditPlan, ReviewScore

# --------------------------------------------------------------------------- #
# Transient error retry
# --------------------------------------------------------------------------- #

_TRANSIENT_DELAYS = (30, 60, 120)  # seconds — exponential-ish backoff


def _with_transient_retry(fn, *args, **kwargs):
    """Call *fn* with retries on transient Gemini errors (502, 503, 429).

    Catches ``google.genai.errors.ServerError`` (5xx) and
    ``google.genai.errors.ClientError`` (429 rate-limit) and waits
    before retrying, up to ``len(_TRANSIENT_DELAYS)`` attempts.
    """
    for attempt, delay in enumerate(_TRANSIENT_DELAYS):
        try:
            return fn(*args, **kwargs)
        except (genai_errors.ServerError, genai_errors.ClientError) as exc:
            _log(
                f"[pipeline] transient error (attempt {attempt + 1}/"
                f"{len(_TRANSIENT_DELAYS) + 1}): {exc}"
            )
            _log(f"[pipeline] waiting {delay}s before retry …")
            time.sleep(delay)
    # Final attempt — let exceptions propagate
    return fn(*args, **kwargs)


# --------------------------------------------------------------------------- #
# Typed manifest models
# --------------------------------------------------------------------------- #


_ALLOWED_AGENTS: frozenset[str] = frozenset({"director", "editor", "reviewer", "trim_refiner"})
_ALLOWED_METRICS: frozenset[str] = frozenset(
    {"adherence", "pacing", "visual_quality", "watchability", "overall"}
)
_ALLOWED_OPERATORS: frozenset[str] = frozenset({"<", "<="})


class RetryIf(BaseModel):
    """Retry predicate for a pipeline step.

    Declares which :class:`ReviewScore` metric to inspect, the comparison
    operator, the threshold, the maximum number of retries allowed, and
    which upstream agent receives the Reviewer feedback on retry. Today
    only ``feedback_target: director`` is supported — the runner raises
    ``ValueError`` on any other value.
    """

    metric: Literal[
        "adherence", "pacing", "visual_quality", "watchability", "overall"
    ] = "overall"
    operator: Literal["<", "<="] = "<"
    threshold: float = 0.7
    max_retries: int = 2
    feedback_target: Literal["director"] = "director"


class PipelineStep(BaseModel):
    """One step in a pipeline manifest.

    Unknown keys are rejected at validation time. The :func:`_load_pipeline`
    helper preprocesses raw YAML with :func:`_strip_unknown_keys` so
    unexpected fields produce a stdout warning instead of a hard error.
    """

    agent: Literal["director", "editor", "reviewer", "trim_refiner"]
    gate: Literal["human_approval"] | None = None
    retry_if: RetryIf | None = None

    model_config = {"extra": "forbid"}


class PipelineManifest(BaseModel):
    """Typed view of a pipeline YAML manifest."""

    name: str = "unnamed-pipeline"
    description: str | None = None
    steps: list[PipelineStep] = Field(default_factory=list)

    model_config = {"extra": "forbid"}


# --------------------------------------------------------------------------- #
# Result type
# --------------------------------------------------------------------------- #


@dataclass
class PipelineResult:
    """Outcome of a full :func:`run_pipeline` invocation.

    Attributes:
        edit_plan: The last :class:`EditPlan` produced by the Director,
            or ``None`` if the pipeline aborted before the Director ran.
        final_video_path: Absolute path to the last rendered MP4 the
            Editor produced, or ``None`` if the pipeline aborted before
            the Editor ran (e.g. the human declined the approval gate).
        review: The last :class:`ReviewScore` produced by the Reviewer,
            or ``None`` if the pipeline aborted before the Reviewer ran.
        retries_used: How many retry iterations the Reviewer loop
            consumed. Zero if the first pass passed the retry predicate
            or the pipeline had no Reviewer step.
        warnings: Non-fatal notices the runner wants to surface (retry
            budget exhausted, human declined gate, unknown manifest
            keys, etc.). Empty on a clean happy path.
        feedback_history: All Reviewer feedback strings gathered across
            retry attempts, in chronological order. Useful for debugging
            retry regressions.
    """

    edit_plan: EditPlan | None = None
    final_video_path: str | None = None
    review: ReviewScore | None = None
    retries_used: int = 0
    warnings: list[str] = field(default_factory=list)
    feedback_history: list[str] = field(default_factory=list)


# --------------------------------------------------------------------------- #
# Logging helpers
# --------------------------------------------------------------------------- #


def _log(msg: str) -> None:
    """Write an informational line to stdout (flushed)."""
    print(msg, flush=True)


def _log_warning(msg: str) -> None:
    """Write a prefixed warning line to stdout."""
    print(f"[pipeline] WARNING: {msg}", flush=True)


def _log_step_start(agent: str, index: int) -> None:
    _log(f"[pipeline] step {index} — {agent} starting")


def _log_step_end(agent: str, duration: float, summary: str) -> None:
    _log(
        f"[pipeline] step — {agent} done in {duration:.2f}s — {summary}"
    )


# --------------------------------------------------------------------------- #
# Manifest loading
# --------------------------------------------------------------------------- #


_KNOWN_MANIFEST_KEYS: frozenset[str] = frozenset(
    {"name", "description", "steps"}
)
_KNOWN_STEP_KEYS: frozenset[str] = frozenset({"agent", "gate", "retry_if"})
_KNOWN_RETRY_KEYS: frozenset[str] = frozenset(
    {"metric", "operator", "threshold", "max_retries", "feedback_target"}
)


def _strip_unknown_keys(raw: dict[str, Any]) -> dict[str, Any]:
    """Strip unknown top-level/step/retry keys with stdout warnings.

    Returns a new dict containing only the keys Pydantic will accept.
    Each dropped key logs a warning so manifest authors see the typo
    without the pipeline crashing.
    """
    cleaned: dict[str, Any] = {}
    for key, value in raw.items():
        if key not in _KNOWN_MANIFEST_KEYS:
            _log_warning(
                f"pipeline manifest has unknown top-level key {key!r}; "
                "ignoring"
            )
            continue
        cleaned[key] = value

    steps_raw = cleaned.get("steps")
    if isinstance(steps_raw, list):
        cleaned_steps: list[dict[str, Any]] = []
        for step_index, step in enumerate(steps_raw):
            if not isinstance(step, dict):
                raise ValueError(
                    f"pipeline step at index {step_index} is not a mapping: "
                    f"{step!r}"
                )
            cleaned_step: dict[str, Any] = {}
            for sk, sv in step.items():
                if sk not in _KNOWN_STEP_KEYS:
                    _log_warning(
                        f"pipeline step {step_index} has unknown key "
                        f"{sk!r}; ignoring"
                    )
                    continue
                cleaned_step[sk] = sv
            retry_raw = cleaned_step.get("retry_if")
            if isinstance(retry_raw, dict):
                cleaned_retry: dict[str, Any] = {}
                for rk, rv in retry_raw.items():
                    if rk not in _KNOWN_RETRY_KEYS:
                        _log_warning(
                            f"pipeline step {step_index} retry_if has "
                            f"unknown key {rk!r}; ignoring"
                        )
                        continue
                    cleaned_retry[rk] = rv
                cleaned_step["retry_if"] = cleaned_retry
            cleaned_steps.append(cleaned_step)
        cleaned["steps"] = cleaned_steps

    return cleaned


def _load_pipeline(pipeline_path: str) -> PipelineManifest:
    """Load and validate a pipeline YAML manifest from disk.

    Args:
        pipeline_path: Filesystem path to a YAML manifest (relative or
            absolute — tildes are expanded).

    Returns:
        A validated :class:`PipelineManifest` with ``steps`` populated.

    Raises:
        FileNotFoundError: If the path does not exist.
        ValueError: If the YAML parses to a non-mapping, declares zero
            steps, or fails Pydantic validation (unknown step agent,
            bad retry operator, etc.).
    """
    path = Path(pipeline_path).expanduser()
    if not path.exists():
        raise FileNotFoundError(
            f"pipeline_path does not exist: {pipeline_path}"
        )

    text = path.read_text(encoding="utf-8")
    parsed = yaml.safe_load(text)
    if parsed is None:
        raise ValueError(
            f"pipeline manifest {pipeline_path!r} is empty"
        )
    if not isinstance(parsed, dict):
        raise ValueError(
            f"pipeline manifest {pipeline_path!r} must be a mapping, got "
            f"{type(parsed).__name__}"
        )

    cleaned = _strip_unknown_keys(parsed)

    try:
        manifest = PipelineManifest.model_validate(cleaned)
    except ValidationError as exc:
        raise ValueError(
            f"pipeline manifest {pipeline_path!r} failed validation: {exc}"
        ) from exc

    if not manifest.steps:
        raise ValueError(
            f"pipeline manifest {pipeline_path!r} declares zero steps"
        )

    for step in manifest.steps:
        if step.agent not in _ALLOWED_AGENTS:
            raise ValueError(
                f"pipeline manifest {pipeline_path!r} has unknown agent "
                f"{step.agent!r} (allowed: {sorted(_ALLOWED_AGENTS)})"
            )
        if step.retry_if is not None:
            if step.retry_if.metric not in _ALLOWED_METRICS:
                raise ValueError(
                    f"retry_if.metric {step.retry_if.metric!r} is not one "
                    f"of {sorted(_ALLOWED_METRICS)}"
                )
            if step.retry_if.operator not in _ALLOWED_OPERATORS:
                raise ValueError(
                    f"retry_if.operator {step.retry_if.operator!r} is not "
                    f"one of {sorted(_ALLOWED_OPERATORS)}"
                )
            if step.retry_if.max_retries < 0:
                raise ValueError(
                    "retry_if.max_retries must be >= 0, got "
                    f"{step.retry_if.max_retries}"
                )

    return manifest


# --------------------------------------------------------------------------- #
# Retry predicate
# --------------------------------------------------------------------------- #


def _metric_value(review: ReviewScore, metric: str) -> float:
    """Read the scalar score for a named metric off a ReviewScore."""
    return float(getattr(review, metric))


def _should_retry(review: ReviewScore | None, retry_if: RetryIf | None) -> bool:
    """Return True when the review trips the retry_if predicate.

    A ``None`` ``review`` or ``None`` ``retry_if`` both return False —
    without a score we cannot evaluate the predicate, and without a
    retry rule there is nothing to retry.
    """
    if review is None or retry_if is None:
        return False
    value = _metric_value(review, retry_if.metric)
    if retry_if.operator == "<":
        return value < retry_if.threshold
    if retry_if.operator == "<=":
        return value <= retry_if.threshold
    return False


# --------------------------------------------------------------------------- #
# Director retry helper (with reviewer feedback)
# --------------------------------------------------------------------------- #


def _run_director_with_feedback(
    brief: CreativeBrief,
    footage_index_path: str,
    feedback: str,
) -> EditPlan:
    """Re-run the Director with Reviewer feedback injected into the prompt.

    This helper mirrors the event-drain + structured-output-parse pattern
    in ``src.agents.director.run_director`` but appends a "Reviewer
    feedback from previous attempt" block to the user message so the
    Director sees the concrete issues it must address in the revised
    EditPlan. The Director's :func:`build_director` is imported and
    called directly — no module surgery on ``director.py``.

    Args:
        brief: The same :class:`CreativeBrief` that drove the first
            attempt. The brief is intentionally NOT mutated so downstream
            validation (e.g. :class:`EditPlan.brief` echo) keeps working.
        footage_index_path: Path to the serialized
            :class:`~src.models.schemas.FootageIndex`. Must exist on disk
            so the Director's ``search_moments`` tool calls can read it.
        feedback: One or more Reviewer feedback strings concatenated by
            the caller (newest at the end). Injected verbatim into the
            user message.

    Returns:
        A validated :class:`EditPlan` produced by the retry-aware run.

    Raises:
        FileNotFoundError: If ``footage_index_path`` does not exist.
        RuntimeError: If the agent stream completes without producing a
            final response payload.
        pydantic.ValidationError: If the model emits JSON that does not
            satisfy the :class:`EditPlan` schema.
    """
    if not Path(footage_index_path).exists():
        raise FileNotFoundError(
            f"footage_index_path does not exist: {footage_index_path}"
        )

    agent = build_director(brief)
    runner = InMemoryRunner(agent=agent, app_name=_DIRECTOR_APP_NAME)

    feedback_block = (
        "\n\n## Reviewer feedback from previous attempt "
        "(address these issues in the new plan)\n"
        f"{feedback.strip()}\n"
        "\nProduce a revised EditPlan that directly addresses the feedback "
        "above. Keep the same brief and footage index — only change shot "
        "selection, ordering, trims, or overlays as needed to fix the "
        "issues called out."
    )

    user_message = genai_types.Content(
        role="user",
        parts=[
            genai_types.Part(
                text=(
                    "Build a REVISED EditPlan for the following brief.\n\n"
                    f"Brief JSON: {brief.model_dump_json()}\n\n"
                    f"Footage index path (use this exact path in tool "
                    f"calls): {footage_index_path}\n\n"
                    "Produce the revised EditPlan now."
                    + feedback_block
                )
            )
        ],
    )

    async def _go() -> EditPlan:
        session = await runner.session_service.create_session(
            app_name=_DIRECTOR_APP_NAME,
            user_id=_DIRECTOR_USER_ID,
        )
        final_text: str | None = None
        async for event in runner.run_async(
            user_id=_DIRECTOR_USER_ID,
            session_id=session.id,
            new_message=user_message,
        ):
            if (
                event.is_final_response()
                and event.content
                and event.content.parts
            ):
                text = "".join(
                    part.text
                    for part in event.content.parts
                    if getattr(part, "text", None)
                    and not getattr(part, "thought", False)
                )
                if text.strip():
                    final_text = text
        if not final_text:
            raise RuntimeError(
                "Director retry returned no final response text. Check "
                "that the FootageIndex still contains shots and that the "
                "model returned a non-empty structured response."
            )
        return EditPlan.model_validate_json(final_text)

    last_exc: Exception | None = None
    for attempt in range(3):
        try:
            return asyncio.run(_go())
        except RuntimeError as exc:
            if "no final response text" not in str(exc):
                raise
            last_exc = exc
            _log(
                f"[pipeline] director retry attempt {attempt + 1}/3 "
                "produced no final text; retrying"
            )
    raise last_exc  # type: ignore[misc]


# --------------------------------------------------------------------------- #
# Human approval gate
# --------------------------------------------------------------------------- #


def _summarize_edit_plan(plan: EditPlan) -> str:
    """Render a short, human-readable summary of an EditPlan for stdout."""
    lines = [
        "--- EditPlan ---",
        f"product: {plan.brief.product}",
        f"audience: {plan.brief.audience}",
        f"tone: {plan.brief.tone}",
        f"target duration: {plan.brief.duration_seconds}s",
        f"total duration: {plan.total_duration:.2f}s",
        f"entries ({len(plan.entries)}):",
    ]
    for entry in sorted(plan.entries, key=lambda e: e.position):
        duration = entry.end_trim - entry.start_trim
        overlay = f" overlay={entry.text_overlay!r}" if entry.text_overlay else ""
        lines.append(
            f"  [{entry.position}] {entry.shot_id} "
            f"trim=({entry.start_trim:.2f}, {entry.end_trim:.2f}) "
            f"dur={duration:.2f}s{overlay}"
        )
    lines.append("--- end EditPlan ---")
    return "\n".join(lines)


def _prompt_human_approval(plan: EditPlan) -> bool:
    """Print the edit plan and block until the user types y/n on stdin.

    Returns ``True`` when the user approves (``y``/``yes``, case
    insensitive), ``False`` when they decline (``n``/``no``). Any other
    input re-prompts up to three times before defaulting to declined.
    """
    _log(_summarize_edit_plan(plan))
    for _ in range(3):
        try:
            answer = input(
                "[pipeline] approve this EditPlan and proceed to Editor? "
                "[y/n]: "
            ).strip().lower()
        except EOFError:
            _log_warning(
                "human_approval gate got EOF on stdin; declining by default"
            )
            return False
        if answer in {"y", "yes"}:
            return True
        if answer in {"n", "no"}:
            return False
        _log_warning(f"unrecognized answer {answer!r}; expected y/n")
    _log_warning("no valid answer after 3 prompts; declining by default")
    return False


# --------------------------------------------------------------------------- #
# Step summaries
# --------------------------------------------------------------------------- #


def _summarize_director(plan: EditPlan | None) -> str:
    if plan is None:
        return "no plan produced"
    return (
        f"plan with {len(plan.entries)} entries, "
        f"total_duration={plan.total_duration:.2f}s"
    )


def _summarize_editor(video_path: str | None) -> str:
    if not video_path:
        return "no video produced"
    return f"rendered {video_path}"


def _summarize_reviewer(review: ReviewScore | None) -> str:
    if review is None:
        return "no review produced"
    return (
        f"overall={review.overall:.2f} "
        f"adherence={review.adherence:.2f} "
        f"pacing={review.pacing:.2f} "
        f"visual_quality={review.visual_quality:.2f} "
        f"watchability={review.watchability:.2f}"
    )


# --------------------------------------------------------------------------- #
# Versioned video saves
# --------------------------------------------------------------------------- #


def _save_version(video_path: str | None, iteration: int) -> None:
    """Copy a rendered video to a versioned file so retries don't overwrite it.

    Creates ``output/final/{slug}_v0.mp4``, ``_v1.mp4``, etc. alongside
    the main render. This lets users compare each iteration and see if
    the reviewer feedback loop is improving or degrading quality.
    """
    if not video_path:
        return
    src = Path(video_path)
    if not src.exists():
        return
    versioned = src.with_stem(f"{src.stem}_v{iteration}")
    shutil.copy2(str(src), str(versioned))
    _log(f"[pipeline] saved version: {versioned.name}")


# --------------------------------------------------------------------------- #
# Main entrypoint
# --------------------------------------------------------------------------- #


def run_pipeline(
    pipeline_path: str,
    brief: CreativeBrief,
    footage_index_path: str,
    *,
    human_approval: bool = True,
) -> PipelineResult:
    """Execute a YAML-defined agent pipeline end to end.

    Reads the manifest at ``pipeline_path``, validates it against the
    :class:`PipelineManifest` schema, and walks the declared steps in
    order. Each step resolves to one of three agents:

    * ``director`` — calls :func:`src.agents.director.run_director` on
      the initial attempt and :func:`_run_director_with_feedback` on
      retries. Honors an optional ``gate: human_approval`` that blocks
      on stdin before proceeding. If the user declines, the pipeline
      returns early with a warning and no final video. When
      ``human_approval=False`` every ``gate: human_approval`` is
      auto-approved and no stdin read happens — use this for tests and
      non-interactive runs.
    * ``editor`` — calls :func:`src.agents.editor.run_editor` against
      the current :class:`EditPlan` and records the rendered MP4 path.
    * ``reviewer`` — calls :func:`src.agents.reviewer.run_reviewer`
      against the current video. If ``retry_if`` is declared and the
      score trips the predicate, the runner feeds the Reviewer feedback
      back into the Director (via :func:`_run_director_with_feedback`),
      re-runs the Editor, and re-reviews, up to ``max_retries`` times.
      After the retry budget is exhausted, a low score is logged as a
      warning rather than raising.

    Each step prints a start line, a duration, and a short summary of
    its output to stdout. The return value is a :class:`PipelineResult`
    that carries the final plan, video path, review, retry count,
    warnings, and full feedback history so callers can inspect the run.

    Args:
        pipeline_path: Path to a YAML pipeline manifest (see
            ``pipelines/ugc-ad.yaml`` for the canonical example).
        brief: The :class:`CreativeBrief` driving this run. Passed
            unchanged to the Director and Reviewer — the Editor reads
            brief context off the plan itself.
        footage_index_path: Path to the JSON-serialized
            :class:`~src.models.schemas.FootageIndex` produced by
            :mod:`src.pipeline.preprocess`. Must exist on disk.
        human_approval: When ``True`` (default), any step with
            ``gate: human_approval`` prints a human-readable plan
            summary and blocks on stdin for a ``y/n`` confirmation
            before the Editor runs. When ``False``, the gate is
            auto-approved, the summary is still printed, and stdin is
            not touched — intended for non-interactive test runs and
            automation. Keyword-only so callers cannot accidentally
            bypass the gate by passing positional arguments.

    Returns:
        A :class:`PipelineResult` describing what the pipeline produced
        and any warnings it raised. AC 8: a retry-budget exhaustion is
        reflected in ``warnings`` and does NOT raise.

    Raises:
        FileNotFoundError: If ``pipeline_path`` or
            ``footage_index_path`` does not exist.
        ValueError: If the manifest fails validation or an editor step
            is reached before a plan exists / a reviewer step is
            reached before a video exists.
        RuntimeError: Propagated from any underlying agent runner
            (e.g. the Editor reporting a tool failure).
    """
    if not Path(footage_index_path).exists():
        raise FileNotFoundError(
            f"footage_index_path does not exist: {footage_index_path}"
        )

    manifest = _load_pipeline(pipeline_path)
    _log(
        f"[pipeline] loaded manifest {manifest.name!r} with "
        f"{len(manifest.steps)} step(s) from {pipeline_path}"
    )

    result = PipelineResult()

    for step_index, step in enumerate(manifest.steps):
        _log_step_start(step.agent, step_index)
        t0 = time.monotonic()

        if step.agent == "director":
            # Only run the Director on the first director step; downstream
            # retries are driven from inside the reviewer branch via
            # _run_director_with_feedback so we do not re-plan twice in
            # the same pass.
            if result.edit_plan is None:
                result.edit_plan = _with_transient_retry(
                    run_director, brief, footage_index_path
                )
            if step.gate == "human_approval":
                if human_approval:
                    approved = _prompt_human_approval(result.edit_plan)
                else:
                    # Non-interactive bypass: still print the plan summary
                    # so the run log captures what the Editor will execute,
                    # but skip the stdin read entirely. Tests and batch
                    # pipelines pass human_approval=False to get here.
                    _log(_summarize_edit_plan(result.edit_plan))
                    _log(
                        "[pipeline] human_approval gate auto-approved "
                        "(human_approval=False kwarg)"
                    )
                    approved = True
                if not approved:
                    warning = (
                        "human_approval gate declined; aborting pipeline "
                        "before editor"
                    )
                    _log_warning(warning)
                    result.warnings.append(warning)
                    _log_step_end(
                        step.agent,
                        time.monotonic() - t0,
                        _summarize_director(result.edit_plan),
                    )
                    return result
            _log_step_end(
                step.agent,
                time.monotonic() - t0,
                _summarize_director(result.edit_plan),
            )
            continue

        if step.agent == "trim_refiner":
            if result.edit_plan is None:
                raise ValueError(
                    "pipeline step 'trim_refiner' reached before any "
                    "director step produced an EditPlan"
                )
            result.edit_plan = _with_transient_retry(
                refine_plan, result.edit_plan, footage_index_path
            )
            _log_step_end(
                step.agent,
                time.monotonic() - t0,
                f"refined {len(result.edit_plan.entries)} entries, "
                f"total_duration={result.edit_plan.total_duration:.2f}s",
            )
            continue

        if step.agent == "editor":
            if result.edit_plan is None:
                raise ValueError(
                    "pipeline step 'editor' reached before any director "
                    "step produced an EditPlan"
                )
            result.final_video_path = _with_transient_retry(
                run_editor, result.edit_plan, footage_index_path
            )
            # Save versioned copy so retries don't overwrite the original
            _save_version(result.final_video_path, 0)
            _log_step_end(
                step.agent,
                time.monotonic() - t0,
                _summarize_editor(result.final_video_path),
            )
            continue

        if step.agent == "reviewer":
            if result.final_video_path is None:
                raise ValueError(
                    "pipeline step 'reviewer' reached before any editor "
                    "step produced a rendered video"
                )
            result.review = _with_transient_retry(
                run_reviewer, brief, result.final_video_path
            )
            _log(
                f"[pipeline] initial reviewer score: "
                f"{_summarize_reviewer(result.review)}"
            )

            retry_if = step.retry_if
            while (
                _should_retry(result.review, retry_if)
                and retry_if is not None
                and result.retries_used < retry_if.max_retries
            ):
                result.retries_used += 1
                assert result.review is not None  # for type-checkers
                result.feedback_history.append(result.review.feedback)
                metric_value = _metric_value(result.review, retry_if.metric)
                _log_warning(
                    f"reviewer {retry_if.metric}={metric_value:.2f} "
                    f"{retry_if.operator} {retry_if.threshold} — retry "
                    f"{result.retries_used}/{retry_if.max_retries}"
                )
                combined_feedback = "\n\n".join(result.feedback_history)
                revised_plan = _with_transient_retry(
                    _run_director_with_feedback,
                    brief,
                    footage_index_path,
                    feedback=combined_feedback,
                )
                _log(_summarize_edit_plan(revised_plan))
                result.edit_plan = _with_transient_retry(
                    refine_plan, revised_plan, footage_index_path
                )
                result.final_video_path = _with_transient_retry(
                    run_editor, result.edit_plan, footage_index_path
                )
                # Save versioned copy of retry render
                _save_version(result.final_video_path, result.retries_used)
                result.review = _with_transient_retry(
                    run_reviewer, brief, result.final_video_path
                )
                _log(
                    f"[pipeline] retry {result.retries_used} reviewer "
                    f"score: {_summarize_reviewer(result.review)}"
                )

            if _should_retry(result.review, retry_if) and retry_if is not None:
                assert result.review is not None
                final_metric = _metric_value(result.review, retry_if.metric)
                warning = (
                    f"retry budget exhausted after "
                    f"{result.retries_used}/{retry_if.max_retries} "
                    f"attempts; final {retry_if.metric}={final_metric:.2f} "
                    f"still {retry_if.operator} {retry_if.threshold}"
                )
                _log_warning(warning)
                result.warnings.append(warning)

            _log_step_end(
                step.agent,
                time.monotonic() - t0,
                _summarize_reviewer(result.review),
            )
            continue

        # Unreachable because the manifest loader rejects unknown agents,
        # but kept as a defensive final branch.
        raise ValueError(f"Unknown pipeline step agent: {step.agent!r}")

    _log(
        f"[pipeline] pipeline {manifest.name!r} complete — "
        f"retries_used={result.retries_used} warnings={len(result.warnings)}"
    )
    if result.warnings:
        for w in result.warnings:
            print(f"[pipeline] WARNING (final): {w}", flush=True, file=sys.stdout)

    return result