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
15.7 KB
Raw Blame
"""Reviewer agent: watches the rendered cut and grades it against the brief.

The Reviewer is a Google ADK :class:`~google.adk.agents.Agent` named
``reviewer``, wired to ``gemini-3.1-pro`` with a single tool:

* :func:`src.tools.analyze.review_output` — sends the rendered video to
  Gemini native-video and returns a structured
  :class:`~src.models.schemas.ReviewScore`.

Unlike the Director (which plans) and the Editor (which executes), the
Reviewer only judges. It takes a rendered ad (MP4/MOV/etc.) and the
original :class:`~src.models.schemas.CreativeBrief`, asks Gemini to score
the cut across four qualitative dimensions plus a holistic ``overall``,
and returns actionable feedback the upstream loop can use to re-edit.

Scoring contract
----------------

Every dimension is a float in ``[0.0, 1.0]``:

* ``adherence`` — how well the finished cut honors ``brief.product`` /
  ``brief.audience`` / ``brief.tone``.
* ``pacing`` — energy arc, hook strength, and cut rhythm.
* ``visual_quality`` — composition, framing, color, clarity.
* ``watchability`` — would a real viewer keep watching to the end.
* ``overall`` — holistic judgment, NOT a plain mean. One broken dimension
  can drag the whole score down when it deserves to.

The ``feedback`` field is free text. If ``overall < 0.7`` it MUST include
specific, actionable suggestions that reference beats, clip numbers, or
timestamps (e.g. "hook at 0:00–0:03 is weak — replace clip 1 with the
product close-up"). Vague feedback like "could be better" is not allowed.

The agent's ``output_schema`` is :class:`~src.models.schemas.ReviewScore`
so the final response is forced to validate against the Pydantic
contract. Google ADK's ``_OutputSchemaRequestProcessor`` bridges
``tools + output_schema`` for Gemini models, so a single
:class:`~google.adk.agents.Agent` can both call ``review_output`` and
emit a strict structured response (no SequentialAgent split required).

Surfaces
--------

* Module-level :data:`reviewer` — a constructed Agent instance with the
  base instruction (no brief baked in). Useful for ADK auto-discovery
  (``adk web``, ``adk eval``) and module-level introspection.
* :func:`build_reviewer` — factory that takes a
  :class:`~src.models.schemas.CreativeBrief` and returns a fresh Agent
  whose instruction has the brief details baked into the runtime prompt.
  Use this for real runs.
* :func:`build_runtime_instruction` — pure helper that returns the
  runtime instruction string for a given brief (exposed so callers can
  preview what the agent will see before running it).
* :func:`run_reviewer` — synchronous end-to-end runner that wires up an
  ``InMemoryRunner``, sends the brief + rendered video path as the user
  message, and returns a validated
  :class:`~src.models.schemas.ReviewScore`.

Importing this module instantiates the module-level ``reviewer`` Agent
(no Gemini API calls). Tool invocations and the Gemini round-trip only
happen inside :func:`run_reviewer`.
"""

from __future__ import annotations

import asyncio
from pathlib import Path

from google.adk.agents import Agent
from google.adk.runners import InMemoryRunner
from google.genai import types as genai_types

from src.models.schemas import CreativeBrief, ReviewScore
from src.tools.analyze import _ALLOWED_REVIEW_VIDEO_PATH, review_output

# --------------------------------------------------------------------------- #
# Constants
# --------------------------------------------------------------------------- #

_MODEL_ID = "gemini-3.1-pro-preview"
_AGENT_NAME = "reviewer"
_APP_NAME = "agentic-video-editor"
_USER_ID = "reviewer-user"

_AGENT_DESCRIPTION = (
    "Creative reviewer that watches a rendered ad and scores it against "
    "the brief, returning actionable feedback."
)

REVIEWER_INSTRUCTION = """\
You are the Reviewer agent for an AI video editor. Your job is to watch a
rendered ad and grade it honestly against the creative brief that
produced it. You are the critic — you do not plan edits, you do not
render, you judge the finished cut and tell the upstream loop what to
fix.

## Your Mission
Given a creative brief and a rendered video path in the user message,
call the review_output tool with that exact video path and the brief,
then return a single ReviewScore that validates against the Pydantic
schema.

## Scoring Contract
Every score is a float in [0.0, 1.0]. Do not clamp to round numbers —
use the full range.

- adherence: how well the finished cut honors brief.product,
  brief.audience, and brief.tone. Is the right product on screen? Does
  the tone match the stated audience?
- pacing: energy arc, hook strength, and cut rhythm. A great cut opens
  strong and varies energy; a bad cut drags or feels choppy.
- visual_quality: composition, framing, color, and clarity. Does the
  footage look like a finished ad, not rushed filler?
- watchability: would a real viewer keep watching to the end. This is
  the single most important retention signal.
- overall: holistic judgment. NOT a plain mean of the four dimensions
  above. One broken dimension (especially a weak hook) can and should
  drag the whole score down.

## Feedback Contract
The feedback field must be concrete, actionable text that identifies
what works and what should change.

If overall >= 0.7, feedback can summarize strengths plus any minor
polish notes.

If overall < 0.7, feedback MUST include specific actionable
suggestions that reference beats, clip numbers, or timestamps. Examples
of good feedback:

- "hook at 0:00–0:03 is weak — replace clip 1 with the product close-up
  from the tool output"
- "clip 3 drags, shorten by ~1.5s or swap for a higher-energy reaction
  shot"
- "tone is too formal for the stated audience — re-cut with the casual
  reaction shots instead of the voiceover takes"

Vague feedback like "could be better", "try harder", or "needs more
energy" is NOT allowed when overall < 0.7.

## Available Tools
- review_output(video_path, brief) — sends the rendered video to Gemini
  3.1 Pro and returns a ReviewScore. Use this tool exactly once with the
  video path and the brief JSON you were given. Do not paraphrase or
  truncate the brief before passing it to the tool.

## Workflow
1. Read the brief JSON and the rendered video_path from the user
   message.
2. Call review_output(video_path, brief) exactly once with the values
   you were given. Pass the brief JSON verbatim.
3. Take the tool's ReviewScore and return it as your final structured
   output. If the tool's feedback is already specific and the overall
   score honors the rubric above, you may return the tool's output
   unchanged. If the feedback is vague or fails the < 0.7 actionable
   rule, rewrite feedback to be specific before returning — do NOT
   invent new scores.

## Hard Constraints
- Every score must be a float in [0.0, 1.0].
- If overall < 0.7, feedback must contain specific actionable
  suggestions referencing beats, clips, or timestamps.
- The output must validate against the ReviewScore Pydantic schema.
- Return ONLY the JSON object — no preamble, no commentary, no
  markdown fences.
"""


# --------------------------------------------------------------------------- #
# Instruction builder
# --------------------------------------------------------------------------- #


def build_runtime_instruction(brief: CreativeBrief) -> str:
    """Return the full runtime instruction for a brief-aware Reviewer.

    Combines the static :data:`REVIEWER_INSTRUCTION` with a brief header
    (product, audience, tone, target duration, style_ref) so the Reviewer
    has the grading rubric context inline. Unlike the Director, the
    Reviewer does not load style skills — style-skill YAML is a planning
    concern, and the Reviewer grades whatever was actually rendered.

    This helper is exposed so callers (tests, debug tools) can preview
    exactly what the Reviewer will see without spinning up an Agent.

    Args:
        brief: The :class:`CreativeBrief` to bake into the instruction.

    Returns:
        A multi-line instruction string ready to pass as
        ``Agent.instruction``.
    """
    header = (
        "## Brief Context (grade the rendered cut against these fields)\n"
        f"- product: {brief.product}\n"
        f"- audience: {brief.audience}\n"
        f"- tone: {brief.tone}\n"
        f"- target duration (seconds): {brief.duration_seconds}\n"
        f"- style_ref: {brief.style_ref or '(none)'}\n"
    )

    return "\n".join([REVIEWER_INSTRUCTION.rstrip(), "", header]) + "\n"


# --------------------------------------------------------------------------- #
# Agent factory
# --------------------------------------------------------------------------- #


def build_reviewer(brief: CreativeBrief) -> Agent:
    """Construct a brief-aware Reviewer ADK Agent without running it.

    Each call returns a fresh :class:`google.adk.agents.Agent` whose
    instruction has the brief details baked into the runtime prompt. The
    agent is wired with a single tool — :func:`review_output` — and
    ``output_schema=ReviewScore`` so the final response validates
    against the Pydantic contract.

    Use this factory whenever you have a concrete brief in hand. The
    module-level :data:`reviewer` instance is reserved for ADK
    auto-discovery and tests that do not need brief-specific context.

    Args:
        brief: The creative brief whose product/audience/tone/duration
            and optional ``style_ref`` shape the agent's instruction.

    Returns:
        A configured :class:`Agent` named ``reviewer`` with model
        ``gemini-3.1-pro``, the ``review_output`` tool attached, and
        ``output_schema=ReviewScore``.
    """
    instruction = build_runtime_instruction(brief)
    return Agent(
        name=_AGENT_NAME,
        model=_MODEL_ID,
        description=_AGENT_DESCRIPTION,
        instruction=instruction,
        tools=[review_output],
        output_schema=ReviewScore,
    )


# --------------------------------------------------------------------------- #
# Module-level default instance
# --------------------------------------------------------------------------- #

#: Default Reviewer agent without any brief baked in. Useful for ADK
#: discovery (``adk web``, ``adk eval``), tests, and module-level
#: introspection. For real runs prefer :func:`build_reviewer` so the
#: brief details land inside the instruction.
reviewer: Agent = Agent(
    name=_AGENT_NAME,
    model=_MODEL_ID,
    description=_AGENT_DESCRIPTION,
    instruction=REVIEWER_INSTRUCTION,
    tools=[review_output],
    output_schema=ReviewScore,
)


# --------------------------------------------------------------------------- #
# Synchronous end-to-end runner
# --------------------------------------------------------------------------- #


def run_reviewer(
    brief: CreativeBrief,
    video_path: str,
) -> ReviewScore:
    """Run the Reviewer agent end-to-end and return a validated ReviewScore.

    Builds a fresh brief-aware :class:`Agent` via :func:`build_reviewer`,
    creates a single-turn in-memory session, sends one user message
    containing the brief and the rendered video path, drains the event
    stream, and parses the reviewer's final structured-output payload as
    a :class:`ReviewScore`.

    The agent's ``output_schema`` forces structured JSON output so the
    final message body is validated by Pydantic via
    :meth:`ReviewScore.model_validate_json`.

    Args:
        brief: The :class:`CreativeBrief` that drove this edit. Used to
            anchor grading — the Reviewer scores the cut relative to the
            brief's product, audience, tone, and target duration.
        video_path: Path to the rendered ad video produced by the
            Editor agent (US-006). Must exist on disk so the Reviewer's
            ``review_output`` tool call can read it.

    Returns:
        A validated :class:`ReviewScore` with five float dimensions in
        ``[0.0, 1.0]`` and a non-empty ``feedback`` string.

    Raises:
        FileNotFoundError: If ``video_path`` does not exist.
        RuntimeError: If the agent stream completes without producing a
            final response payload, or if the parsed
            :class:`ReviewScore` has empty ``feedback`` (the grading
            contract requires non-empty feedback on every response).
        pydantic.ValidationError: If the model emits JSON that does not
            satisfy the :class:`ReviewScore` schema.
    """
    if not Path(video_path).exists():
        raise FileNotFoundError(
            f"video_path does not exist: {video_path}"
        )

    # Defense-in-depth against prompt-injection path exfiltration: bind the
    # pre-approved, resolved video path in a ContextVar so ``review_output``
    # can reject any path the model fabricates. The FileNotFoundError guard
    # above remains — this binding is additive and tightens the tool's trust
    # boundary so the Reviewer can only read the cut we explicitly approved.
    canonical_video_path = str(Path(video_path).resolve())

    agent = build_reviewer(brief)
    runner = InMemoryRunner(agent=agent, app_name=_APP_NAME)

    user_message = genai_types.Content(
        role="user",
        parts=[
            genai_types.Part(
                text=(
                    "Watch the rendered ad at this path and score it "
                    "against the brief.\n\n"
                    f"Brief JSON: {brief.model_dump_json()}\n\n"
                    f"Rendered video path (use this exact path in the "
                    f"review_output tool call): {video_path}\n\n"
                    "Produce the ReviewScore now."
                )
            )
        ],
    )

    async def _go() -> ReviewScore:
        session = await runner.session_service.create_session(
            app_name=_APP_NAME,
            user_id=_USER_ID,
        )
        final_text: str | None = None
        async for event in runner.run_async(
            user_id=_USER_ID,
            session_id=session.id,
            new_message=user_message,
        ):
            if (
                event.is_final_response()
                and event.content
                and event.content.parts
            ):
                # Concatenate any non-thought text parts so we capture the
                # model's full structured response even if it is split.
                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(
                "Reviewer agent returned no final response text. Check "
                "that the rendered video exists and that the model "
                "returned a non-empty structured response."
            )
        score = ReviewScore.model_validate_json(final_text)
        # Defensive safety net: the prompt instructs the model to always
        # return concrete feedback (and mandatory actionable suggestions
        # when overall < 0.7). The ReviewScore schema only types feedback
        # as ``str`` so an empty string would otherwise slip through.
        # Reject empty/whitespace feedback here — an upstream loop cannot
        # act on it and the failure mode would be silent otherwise.
        if not score.feedback.strip():
            raise RuntimeError(
                "Reviewer agent returned a ReviewScore with empty "
                "feedback. The grading contract requires non-empty "
                "feedback on every response (and specific actionable "
                f"suggestions when overall < 0.7; got overall={score.overall})."
            )
        return score

    _token = _ALLOWED_REVIEW_VIDEO_PATH.set(canonical_video_path)
    try:
        return asyncio.run(_go())
    finally:
        _ALLOWED_REVIEW_VIDEO_PATH.reset(_token)