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
8.1 KB
Raw Blame
"""POST /api/jobs/{id}/re-render and /review-only (US-010).

This module wires two "partial-pipeline" endpoints on top of the
sequential :class:`~src.web.jobs.JobRegistry` worker used by the rest
of AVE Studio:

* ``POST /api/jobs/{job_id}/re-render`` takes a user-edited
  :class:`EditPlan`, validates it against the parent job's
  :class:`FootageIndex` using the same helpers the PUT route uses
  (``_load_footage_index_or_422`` + ``_validate_edit_plan_against_index``
  from :mod:`src.web.routes.jobs`), and enqueues an ``"editor-only"``
  child job. The worker path calls :func:`run_editor` directly --
  no Director, no Reviewer -- so B-Roll compositing and trim logic go
  through the same renderer the full pipeline uses without any branching.
  The parent job's ``result`` is **not** mutated, so previous renders
  stay addressable by job id and the frontend can maintain a version
  history for the chat session.
* ``POST /api/jobs/{job_id}/review-only`` enqueues a ``"reviewer-only"``
  child job that calls :func:`run_reviewer` against the parent's latest
  rendered MP4. Useful after a manual plan edit + re-render where the
  user wants a fresh quality score without triggering another full
  Director retry loop.

Both endpoints mirror the contract of
:mod:`src.web.routes.feedback`: ``202 Accepted`` on success with
``{"job_id", "status", "parent_job_id"}``, ``404`` for unknown parents,
``409`` when the parent is not yet completed / missing the context the
re-run needs, and ``422`` when the submitted :class:`EditPlan` fails
pydantic coercion or semantic validation against the footage index.

All registry mutation routes through
:meth:`JobRegistry.submit_editor_rerun` and
:meth:`JobRegistry.submit_reviewer_only`, which each raise
``ValueError`` on invalid parents; this module converts those to
``409`` HTTP responses.
"""

from __future__ import annotations

from typing import Any

from fastapi import APIRouter, HTTPException, Request
from pydantic import BaseModel, Field, ValidationError

from src.models.schemas import EditPlan
from src.web.routes.jobs import (
    _load_footage_index_or_422,
    _validate_edit_plan_against_index,
    get_registry,
)

router = APIRouter(prefix="/api/jobs", tags=["render"])


class ReRenderResponse(BaseModel):
    """Response body for ``POST /api/jobs/{id}/re-render``.

    Mirrors :class:`~src.web.routes.feedback.FeedbackResponse` so the
    frontend can handle both feedback-rerun and editor-only re-render
    responses with a single parser.
    """

    job_id: str = Field(
        ..., description="UUID of the new editor-only re-render job."
    )
    status: str = Field(
        ..., description="Initial status, always ``pending``."
    )
    parent_job_id: str = Field(
        ...,
        description="UUID of the parent job whose plan this re-render revises.",
    )


@router.post(
    "/{job_id}/re-render",
    status_code=202,
    response_model=ReRenderResponse,
)
async def post_re_render(
    job_id: str,
    payload: dict[str, Any],
    request: Request,
) -> ReRenderResponse:
    """Validate a modified :class:`EditPlan` and enqueue an editor-only job.

    The body is the same serialized :class:`EditPlan` shape the GET
    endpoint returns -- the frontend can submit the output of its local
    edit state directly without any transformation. Validation happens
    in the same three layers the PUT route uses:

    1. Pydantic coercion via :meth:`EditPlan.model_validate`. Bad
       types / missing required fields surface as a ``422`` with the
       same error-list shape FastAPI uses for automatic body
       validation.
    2. :func:`_load_footage_index_or_422` loads the parent job's
       :class:`FootageIndex` from disk. A missing / unreadable /
       malformed index is surfaced as ``422`` with a server-side
       ``job.footage_index_path`` error so the user sees "the job's
       footage is gone" instead of a client-side validation error.
    3. :func:`_validate_edit_plan_against_index` walks every entry to
       check shot_id resolution, trim bounds, and the contiguous
       position sequence. Per-field errors are returned in the same
       shape as layer 1.

    Only if all three pass do we call
    :meth:`JobRegistry.submit_editor_rerun` to enqueue the job. The
    parent job's ``result`` is never mutated by this route -- the
    previous render stays available under its original id so the
    frontend can build a render-version list.

    Returns ``202`` with ``{"job_id", "status", "parent_job_id"}`` so
    the client can subscribe to ``/ws/jobs/{new_id}`` and stream
    progress through the same plumbing used for full-pipeline and
    feedback-rerun jobs.
    """
    registry = get_registry(request)
    parent = registry.get(job_id)
    if parent is None:
        raise HTTPException(
            status_code=404,
            detail=f"job {job_id!r} not found",
        )
    if parent.result is None:
        raise HTTPException(
            status_code=409,
            detail=(
                f"job {job_id!r} has no result yet "
                f"(status={parent.status!r}); cannot re-render"
            ),
        )

    # Layer 1: pydantic coercion. Surfaces as 422 with the same error
    # shape FastAPI uses for automatic request validation so the
    # frontend can render field-level messages uniformly.
    try:
        plan = EditPlan.model_validate(payload)
    except ValidationError as exc:
        raise HTTPException(
            status_code=422,
            detail=exc.errors(),
        ) from exc

    # Layers 2 + 3: footage-aware semantic validation. Reuses the PUT
    # helpers (imported from src.web.routes.jobs) so backend validation
    # stays consistent with the PUT path even if the client skipped the
    # save step and went straight to re-render.
    index = _load_footage_index_or_422(parent.footage_index_path)
    errors = _validate_edit_plan_against_index(plan, index)
    if errors:
        raise HTTPException(status_code=422, detail=errors)

    try:
        child = registry.submit_editor_rerun(parent, plan)
    except ValueError as exc:
        raise HTTPException(status_code=409, detail=str(exc)) from exc

    return ReRenderResponse(
        job_id=child.id,
        status=child.status,
        parent_job_id=parent.id,
    )


class ReviewOnlyResponse(BaseModel):
    """Response body for ``POST /api/jobs/{id}/review-only``.

    Identical envelope shape to :class:`ReRenderResponse` so the
    frontend's "new job spawned" handler can process both.
    """

    job_id: str = Field(
        ..., description="UUID of the new reviewer-only scoring job."
    )
    status: str = Field(
        ..., description="Initial status, always ``pending``."
    )
    parent_job_id: str = Field(
        ...,
        description="UUID of the parent job whose MP4 this job scores.",
    )


@router.post(
    "/{job_id}/review-only",
    status_code=202,
    response_model=ReviewOnlyResponse,
)
async def post_review_only(
    job_id: str,
    request: Request,
) -> ReviewOnlyResponse:
    """Enqueue a reviewer-only scoring pass on the parent's latest MP4.

    No request body: all the context the Reviewer needs
    (:class:`CreativeBrief` + path to the rendered video) lives on
    the parent :class:`Job`. The registry method
    :meth:`JobRegistry.submit_reviewer_only` verifies the parent is
    ``"completed"``, has a ``final_video_path`` in its result, and
    that the referenced MP4 actually exists on disk -- any missing
    precondition surfaces as a ``409 Conflict`` so the client gets a
    descriptive error instead of a 500 when the worker inevitably
    fails.

    Returns ``202`` with ``{"job_id", "status", "parent_job_id"}`` so
    the frontend can subscribe to ``/ws/jobs/{new_id}`` and watch the
    scoring run stream.
    """
    registry = get_registry(request)
    parent = registry.get(job_id)
    if parent is None:
        raise HTTPException(
            status_code=404,
            detail=f"job {job_id!r} not found",
        )
    try:
        child = registry.submit_reviewer_only(parent)
    except ValueError as exc:
        raise HTTPException(status_code=409, detail=str(exc)) from exc

    return ReviewOnlyResponse(
        job_id=child.id,
        status=child.status,
        parent_job_id=parent.id,
    )