Video-Coder demo

README.md

@@ -1,13 +1,31 @@
 ---
-title: Video Coder
-emoji: 🐢
-colorFrom: indigo
-colorTo: purple
+title: Video-Coder
+emoji: 🎬
+colorFrom: yellow
+colorTo: pink
 sdk: gradio
 sdk_version: 6.31.0
-python_version: '3.12'
 app_file: app.py
-pinned: false
+short_description: Agent writes Blender code to build a 3D draft video
+python_version: "3.12"
+startup_duration_timeout: 1h
+license: apache-2.0
+models:
+  - Video-Coder/Video-Coder-9B
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Video-Coder
+
+Demo of [Video-Coder: Reinforcing Agentic Coding for Video Generation](https://huggingface.co/papers/2611.09894)
+([code](https://github.com/CYWang735/Video-Coder), [model](https://huggingface.co/Video-Coder/Video-Coder-9B)).
+
+**Video-Coder-9B** runs inside a port of the authors' *Video-Coder Harness*: it writes a Blender 4.5 Python script
+for the scene description, renders it (`run_blender`, bpy 4.5.14 / Workbench on CPU), looks at the rendered frames,
+fixes problems and submits. The output is the **draft video** (white-model render with the scene's layout, motion and
+camera).
+
+The paper then turns the draft video into a final video with MiniMax-H3 (Ref2VA). That ~33B audio-video generator
+(plus its large text encoder) does not fit alongside the agent in this Space, so this demo stops at the draft video.
+
+The harness code in `harness/` is taken from the Video-Coder repository (`Video-Coder-RL/uni-agent`, Apache-2.0).
+Example prompts are from the Video-Coder project page and repository.

app.py

@@ -0,0 +1,540 @@
+import os
+
+os.environ.setdefault("PYTORCH_CUDA_ALLOC_CONF", "expandable_segments:True")
+
+import spaces  # noqa: E402  (must come before torch)
+
+import base64  # noqa: E402
+import difflib  # noqa: E402
+import hashlib  # noqa: E402
+import io  # noqa: E402
+import json  # noqa: E402
+import re  # noqa: E402
+import shutil  # noqa: E402
+import signal  # noqa: E402
+import subprocess  # noqa: E402
+import sys  # noqa: E402
+import tempfile  # noqa: E402
+import threading  # noqa: E402
+import time  # noqa: E402
+import uuid  # noqa: E402
+from pathlib import Path  # noqa: E402
+
+import gradio as gr  # noqa: E402
+import torch  # noqa: E402
+from jinja2 import StrictUndefined, Template  # noqa: E402
+from PIL import Image  # noqa: E402
+from transformers import AutoModelForImageTextToText, AutoProcessor, TextIteratorStreamer  # noqa: E402
+
+ROOT = Path(__file__).resolve().parent
+HARNESS_ROOT = ROOT / "harness"
+sys.path.insert(0, str(HARNESS_ROOT))
+
+from video_coder_harness.blender_exec import execute as blender_execute  # noqa: E402
+from video_coder_harness.guard import (  # noqa: E402
+    BLOCKED,
+    REPEAT_WARNING,
+    _normalize_output,
+    harness_violation,
+)
+from video_coder_harness.static_check import check_file  # noqa: E402
+
+MODEL_ID = "Video-Coder/Video-Coder-9B"
+
+# --------------------------------------------------------------------------------------------------------------------
+# Blender 4.5 (bpy 4.5.14 on Python 3.11, same as the authors' bpy-agent.sif sandbox), rendered on CPU with Mesa
+# llvmpipe. Installed into its own venv at startup because the Space itself runs Python 3.12.
+# --------------------------------------------------------------------------------------------------------------------
+BPY_ENV = Path(os.environ.get("BPY_ENV", str(Path.home() / "bpyenv")))
+BPY_PY = BPY_ENV / "bin" / "python"
+
+
+def setup_bpy() -> None:
+    if BPY_PY.exists():
+        r = subprocess.run([str(BPY_PY), "-c", "import bpy; print(bpy.app.version_string)"],
+                           capture_output=True, text=True)
+        if r.returncode == 0:
+            print("bpy ready:", r.stdout.strip())
+            return
+    t0 = time.time()
+    subprocess.run([sys.executable, "-m", "uv", "venv", "-q", "-p", "3.11", "--clear", str(BPY_ENV)], check=True)
+    subprocess.run([sys.executable, "-m", "uv", "pip", "install", "-q", "-p", str(BPY_PY), "bpy==4.5.14"],
+                   check=True)
+    r = subprocess.run([str(BPY_PY), "-c", "import bpy; print(bpy.app.version_string)"],
+                       capture_output=True, text=True)
+    print(f"bpy install took {time.time() - t0:.0f}s:", r.stdout.strip(), r.stderr[-2000:])
+
+
+setup_bpy()
+
+# Harness settings: configs/teacher.yaml + configs/uni_container_visual.yaml (the RL / inference setting).
+HARNESS = {
+    "blender_version": "4.5",
+    "blender_available": True,
+    "bpy_python": str(BPY_PY),
+    "bpy_libs": "/usr",
+    "exec_timeout": 600,
+    "summary_samples": 6,
+    "content_samples": 8,
+    "visual_feedback": True,
+    "preview_frames": 8,
+    "preview_width": 640,
+    "judge": {"enabled": False},
+    "output_video": "output.mp4",
+    "fps": 24,
+    "frame_count": 120,
+    "max_frame_count": 240,
+    "resolution": [1280, 720],
+    "script_name": "main.py",
+}
+SCRIPT = HARNESS["script_name"]
+CMD_TIMEOUT = 900
+REPEAT_WARN, REPEAT_STOP, REPEAT_SIM = 3, 6, 0.9
+MAX_FORMAT_ERRORS = 3
+RUNS_DIR = Path(tempfile.gettempdir()) / "video_coder_runs"
+RUNS_DIR.mkdir(parents=True, exist_ok=True)
+_SECRET_ENV = re.compile(r"(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)", re.I)
+HARNESS_MARKERS = [str(HARNESS_ROOT), str(BPY_ENV)]
+
+SYSTEM_PROMPT = (
+    "You are an expert Blender technical artist and Python programmer. You write Blender Python (bpy) scripts that "
+    "build and animate 3D scenes and render them as untextured white-model (clay) videos. You work in a Linux shell "
+    "through a bash tool."
+)
+# The exact user prompt of the SFT trajectories (Video-Coder/Train-Data sft_data.json), with the scene as __TASK__.
+INSTANCE_TEMPLATE = (HARNESS_ROOT / "instance_template.txt").read_text()
+TOOLS = [{
+    "type": "function",
+    "function": {
+        "name": "bash",
+        "description": "Execute a bash command",
+        "parameters": {
+            "type": "object",
+            "properties": {"command": {"type": "string", "description": "The bash command to execute"}},
+            "required": ["command"],
+        },
+    },
+}]
+OBSERVATION_TEMPLATE = Template("""{%- if output.output | length < 10000 -%}
+{
+  "returncode": {{ output.returncode }},
+  "output": {{ output.output | tojson }}
+  {%- if output.exception_info %}, "exception_info": {{ output.exception_info | tojson }}{% endif %}
+}
+{%- else -%}
+{
+  "returncode": {{ output.returncode }},
+  "output_head": {{ output.output[:5000] | tojson }},
+  "output_tail": {{ output.output[-5000:] | tojson }},
+  "elided_chars": {{ output.output | length - 10000 }},
+  "warning": "Output too long."
+  {%- if output.exception_info %}, "exception_info": {{ output.exception_info | tojson }}{% endif %}
+}
+{%- endif -%}
+""", undefined=StrictUndefined)
+FORMAT_ERROR_TEMPLATE = Template("""{% if finish_reason is defined and (finish_reason == "length" or (finish_reason == "tool_calls" and not has_tool_calls)) -%}
+Your previous response reached the output token limit (finish_reason={{ finish_reason }}) before you produced a tool call, so it was cut off. Respond more concisely and finish with exactly one bash tool call.
+{%- else -%}
+Tool call error:
+
+<error>
+{{error}}
+</error>
+
+Every response must call the 'bash' tool exactly once with {"command": "..."}.
+To finish, run `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` on its own.
+{%- endif %}
+""")
+MM_TAG = re.compile(r"(?s)<MSWEA_MULTIMODAL_CONTENT><CONTENT_TYPE>(.+?)</CONTENT_TYPE>(.+?)</MSWEA_MULTIMODAL_CONTENT>")
+TOOL_CALL_RE = re.compile(r"<tool_call>\s*<function=([^>\s]+)>(.*?)</function>\s*</tool_call>", re.S)
+PARAM_RE = re.compile(r"<parameter=([^>\s]+)>\n?(.*?)\n?</parameter>", re.S)
+END_TOKENS = ("<|im_end|>", "<|endoftext|>")
+
+# --------------------------------------------------------------------------------------------------------------------
+# Model: Video-Coder-9B (Qwen3.5-9B, vision-language) in bf16, fully on the GPU.
+# --------------------------------------------------------------------------------------------------------------------
+processor = AutoProcessor.from_pretrained(MODEL_ID)
+tokenizer = processor.tokenizer
+model = AutoModelForImageTextToText.from_pretrained(MODEL_ID, dtype=torch.bfloat16).to("cuda").eval()
+
+GPU_CHUNK_SECONDS = 100  # one GPU call generates for at most this long; long turns continue in the next call
+
+
+@spaces.GPU(duration=120)
+def llm_chunk(messages: list, images: list, prefix: str = "", max_new_tokens: int = 16384,
+              temperature: float = 1.0, top_p: float = 0.95):
+    """Continue the agent's current turn for up to GPU_CHUNK_SECONDS; yields (text so far, finished, n_tokens)."""
+    prompt = tokenizer.apply_chat_template(messages, tools=TOOLS, add_generation_prompt=True, tokenize=False)
+    prompt += prefix
+    inputs = processor(text=[prompt], images=images or None, return_tensors="pt").to("cuda")
+    n_in = inputs["input_ids"].shape[1]
+    streamer = TextIteratorStreamer(tokenizer, skip_prompt=True, skip_special_tokens=False)
+    result = {}
+
+    def _run():
+        try:
+            out = model.generate(**inputs, streamer=streamer, max_new_tokens=int(max_new_tokens), do_sample=True,
+                                 temperature=float(temperature), top_p=float(top_p), top_k=0, use_cache=True,
+                                 max_time=GPU_CHUNK_SECONDS)
+            result["n"] = int(out.shape[1] - n_in)
+        except Exception as e:  # surfaced below
+            result["error"] = f"{type(e).__name__}: {e}"
+            streamer.end()
+
+    th = threading.Thread(target=_run, daemon=True)
+    th.start()
+    text = ""
+    last = 0.0
+    for piece in streamer:
+        text += piece
+        if time.time() - last > 0.4:
+            last = time.time()
+            yield text, False, None
+    th.join()
+    if "error" in result:
+        raise gr.Error(result["error"])
+    finished = any(t in text for t in END_TOKENS)
+    yield text, finished, result.get("n", 0)
+
+
+# --------------------------------------------------------------------------------------------------------------------
+# Agent loop: mini-swe-agent DefaultAgent + video_coder_harness GuardedAgent semantics, re-implemented without the
+# litellm/vLLM gateway (the model is called in-process).
+# --------------------------------------------------------------------------------------------------------------------
+def agent_env() -> dict:
+    env = dict(os.environ)
+    env.update({k: "" for k in os.environ if _SECRET_ENV.search(k)})
+    env.update({"PAGER": "cat", "MANPAGER": "cat", "PIP_PROGRESS_BAR": "off", "TQDM_DISABLE": "1"})
+    env["PATH"] = f"{HARNESS_ROOT / 'bin'}:{os.environ.get('PATH', '')}"
+    env["VCSFT_PYTHON"] = sys.executable
+    env["VCSFT_HARNESS"] = json.dumps(HARNESS)
+    return env
+
+
+def run_command(command: str, cwd: str) -> dict:
+    """mini-swe-agent LocalEnvironment.execute."""
+    proc = subprocess.Popen(command, shell=True, text=True, cwd=cwd, env=agent_env(), encoding="utf-8",
+                            errors="replace", stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                            start_new_session=True)
+    try:
+        stdout, _ = proc.communicate(timeout=CMD_TIMEOUT)
+        return {"output": stdout, "returncode": proc.returncode, "exception_info": ""}
+    except subprocess.TimeoutExpired as e:
+        os.killpg(proc.pid, signal.SIGKILL)
+        stdout, _ = proc.communicate()
+        return {"output": stdout or "", "returncode": -1,
+                "exception_info": f"An error occurred while executing the command: {e}"}
+
+
+def is_submit(output: dict) -> bool:
+    lines = output.get("output", "").lstrip().splitlines()
+    return bool(lines) and lines[0].strip() == "COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT" and output["returncode"] == 0
+
+
+def split_images(text: str):
+    """video_coder_harness.models.split_images: cut frame images out of the tool output."""
+    images = []
+
+    def repl(m):
+        if m.group(1).strip() != "image_url":
+            return m.group(0)
+        before = text[: m.start()].rstrip().splitlines()
+        caption = before[-1].strip() if before else ""
+        images.append((caption, m.group(2).strip()))
+        return f"[image {len(images)} attached below]"
+
+    return MM_TAG.sub(repl, text), images
+
+
+def data_url_to_pil(url: str) -> Image.Image:
+    return Image.open(io.BytesIO(base64.b64decode(url.split(",", 1)[1]))).convert("RGB")
+
+
+def parse_response(raw: str):
+    """Split a Qwen3.5 response into (reasoning, content, tool calls) like vLLM's qwen3 reasoning + qwen3_coder parsers."""
+    text = raw
+    for t in END_TOKENS:
+        text = text.split(t)[0]
+    reasoning = ""
+    if "</think>" in text:
+        reasoning, text = text.split("</think>", 1)
+        reasoning = reasoning.replace("<think>", "").strip()
+    calls = []
+    for m in TOOL_CALL_RE.finditer(text):
+        args = {k: v for k, v in PARAM_RE.findall(m.group(2))}
+        calls.append({"name": m.group(1).strip(), "arguments": args})
+    content = TOOL_CALL_RE.sub("", text)
+    content = content.split("<tool_call>")[0].strip()
+    return reasoning, content, calls
+
+
+def sha(path: Path) -> str | None:
+    return hashlib.sha256(path.read_bytes()).hexdigest() if path.is_file() else None
+
+
+def short(text: str, n: int = 60) -> str:
+    lines = text.splitlines()
+    return text if len(lines) <= n else "\n".join(lines[:n]) + f"\n... ({len(lines) - n} more lines)"
+
+
+def read_script(workdir: Path) -> str:
+    p = workdir / SCRIPT
+    return p.read_text(errors="replace") if p.is_file() else ""
+
+
+def run_agent(prompt: str, max_steps: int = 12, temperature: float = 1.0, top_p: float = 0.95,
+              max_new_tokens: int = 16384):
+    """Turn a scene description into an animated 3D "draft video": Video-Coder-9B writes a Blender script, renders it,
+    inspects the frames, fixes problems and submits.
+
+    Args:
+        prompt: description of the scene / video to build.
+        max_steps: maximum number of agent turns (one bash command each).
+        temperature: sampling temperature (the authors sample with 1.0).
+        top_p: nucleus sampling (the authors use 0.95).
+        max_new_tokens: token budget of a single agent turn.
+
+    Returns:
+        (agent trajectory, draft video, main.py, latest render preview, status)
+    """
+    if not prompt or not prompt.strip():
+        raise gr.Error("Please enter a scene description.")
+    workdir = (RUNS_DIR / uuid.uuid4().hex).resolve()
+    workdir.mkdir(parents=True)
+    messages = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": INSTANCE_TEMPLATE.replace("__TASK__", prompt.strip())},
+    ]
+    images: list = []
+    chat: list = []
+    video = None
+    preview = None
+    last_ok = None  # (script hash, video path) of the last run_blender that reported RUN OK
+    last_key = None
+    repeats = 0
+    n_format_errors = 0
+    exit_status = "StepLimit"
+    t_start = time.time()
+
+    def status(msg):
+        return f"**{msg}** · {time.time() - t_start:.0f}s elapsed"
+
+    def ui(msg):
+        return chat, video, read_script(workdir), preview, status(msg)
+
+    yield ui("Starting…")
+    for step in range(1, int(max_steps) + 1):
+        # ---- model turn (possibly split over several GPU calls) ----
+        raw, used = "", 0
+        live = {"role": "assistant", "content": "", "metadata": {"title": f"💭 Step {step}: thinking…",
+                                                                 "status": "pending"}}
+        chat.append(live)
+        while True:
+            finished, n = False, None
+            base = raw
+            for text, finished, n in llm_chunk(messages, images, base, max_new_tokens - used, temperature, top_p):
+                raw = base + text
+                live["content"] = raw[-3000:].replace("<think>", "")
+                yield ui(f"Step {step}/{max_steps}: Video-Coder is writing ({len(raw)} chars)")
+            used += n or 0
+            if finished or used >= max_new_tokens:
+                break
+        chat.pop()
+        reasoning, content, calls = parse_response(raw)
+        if reasoning:
+            chat.append({"role": "assistant", "content": reasoning,
+                         "metadata": {"title": f"💭 Step {step}: reasoning", "status": "done"}})
+        msg = {"role": "assistant", "content": content}
+        if reasoning:
+            msg["reasoning_content"] = reasoning
+        if calls:
+            msg["tool_calls"] = [{"type": "function", "function": {"name": c["name"], "arguments": c["arguments"]}}
+                                 for c in calls]
+        messages.append(msg)
+
+        # ---- format errors ----
+        error = None
+        if not calls:
+            error = "No tool calls found in the response. Every response MUST include at least one tool call."
+        elif any(c["name"] != "bash" or "command" not in c["arguments"] for c in calls):
+            error = "Unknown tool or missing 'command' argument."
+        if error:
+            n_format_errors += 1
+            finish_reason = "length" if not any(t in raw for t in END_TOKENS) else "stop"
+            err = FORMAT_ERROR_TEMPLATE.render(error=error, finish_reason=finish_reason, has_tool_calls=bool(calls))
+            if content:
+                chat.append({"role": "assistant", "content": content})
+            chat.append({"role": "user", "content": f"⚠️ {err}"})
+            messages.append({"role": "user", "content": err})
+            yield ui(f"Step {step}: format error")
+            if n_format_errors >= MAX_FORMAT_ERRORS:
+                exit_status = "FormatError"
+                break
+            continue
+        n_format_errors = 0
+
+        # ---- execute the bash command(s) ----
+        submitted = False
+        stop = False
+        for call in calls:
+            command = call["arguments"]["command"]
+            shown = f"{content}\n\n" if content else ""
+            chat.append({"role": "assistant", "content": f"{shown}```bash\n{short(command)}\n```"})
+            yield ui(f"Step {step}: running `{command.strip().splitlines()[0][:60]}`")
+            reason = harness_violation(command, HARNESS_MARKERS, str(workdir))
+            if reason:
+                out = {"output": BLOCKED.format(reason=reason), "returncode": 1, "exception_info": ""}
+            else:
+                out = run_command(command, str(workdir))
+                if is_submit(out):
+                    submitted = True
+                    break
+            key = (command, _normalize_output(out.get("output", "")))
+            same = (last_key is not None and key[1] == last_key[1]
+                    and difflib.SequenceMatcher(None, key[0], last_key[0]).ratio() >= REPEAT_SIM)
+            repeats = repeats + 1 if same else 1
+            last_key = key
+            if repeats >= REPEAT_WARN:
+                out["output"] = (out.get("output") or "") + REPEAT_WARNING.format(n=repeats, stop=REPEAT_STOP)
+            if repeats >= REPEAT_STOP:
+                stop = True
+
+            text, imgs = split_images(out.get("output") or "")
+            obs = OBSERVATION_TEMPLATE.render(output={**out, "output": text})
+            if imgs:
+                parts = [{"type": "text", "text": obs}]
+                for k, (caption, url) in enumerate(imgs, 1):
+                    parts += [{"type": "text", "text": f"image {k}: {caption}" if caption else f"image {k}:"},
+                              {"type": "image"}]
+                    images.append(data_url_to_pil(url))
+                messages.append({"role": "tool", "content": parts})
+            else:
+                messages.append({"role": "tool", "content": obs})
+
+            if command.strip().startswith("run_blender"):
+                vid = workdir / HARNESS["output_video"]
+                if vid.is_file():
+                    keep = workdir / f".render_step{step}.mp4"
+                    shutil.copy(vid, keep)
+                    video = str(keep)
+                    if text.startswith("RUN OK"):
+                        last_ok = (sha(workdir / SCRIPT), str(keep))
+                if (workdir / "preview.png").is_file():
+                    keep_png = workdir / f".preview_step{step}.png"
+                    shutil.copy(workdir / "preview.png", keep_png)
+                    preview = str(keep_png)
+            chat.append({"role": "assistant", "content": f"```\n{short(text.strip(), 40)}\n```",
+                         "metadata": {"title": f"🛠️ Output (exit code {out['returncode']})", "status": "done"}})
+            yield ui(f"Step {step}/{max_steps} done")
+        if submitted:
+            exit_status = "Submitted"
+            break
+        if stop:
+            exit_status = "RepeatedActions"
+            break
+
+    # ---- acceptance: static check + the final script re-rendered from scratch (harness final_execution) ----
+    script = workdir / SCRIPT
+    if exit_status == "Submitted" and script.is_file():
+        chat.append({"role": "assistant", "content": "✅ Submitted. Validating the final script…"})
+        yield ui("Validating the submitted script")
+        check = check_file(script)
+        if not check["ok"]:
+            yield ui(f"Submitted, but the static check failed: {check['errors']}")
+            return
+        if last_ok and last_ok[0] == sha(script):  # rendering is deterministic: reuse the identical render
+            video = last_ok[1]
+        else:
+            yield ui("Re-rendering the submitted script")
+            final_dir = workdir / ".final_run"
+            final_dir.mkdir(exist_ok=True)
+            shutil.copy(script, final_dir / SCRIPT)
+            report = blender_execute(final_dir / SCRIPT, final_dir, HARNESS)
+            if (final_dir / HARNESS["output_video"]).is_file():
+                video = str(final_dir / HARNESS["output_video"])
+            if (final_dir / "preview.png").is_file():
+                preview = str(final_dir / "preview.png")
+            if not report["ok"]:
+                yield ui(f"Submitted, but the final render has problems: {report['problems']}")
+                return
+        yield ui("Accepted ✅ — draft video rendered from the agent's Blender script")
+    else:
+        note = {"StepLimit": "Step limit reached before the agent submitted (showing the latest render)",
+                "RepeatedActions": "Stopped: the agent repeated the same command",
+                "FormatError": "Stopped after repeated format errors"}[exit_status]
+        yield ui(note)
+
+
+# --------------------------------------------------------------------------------------------------------------------
+# UI
+# --------------------------------------------------------------------------------------------------------------------
+CSS = """
+#col-container { max-width: 1280px; margin: 0 auto; }
+.dark .gradio-container { color: var(--body-text-color); }
+"""
+
+EXAMPLES = [
+    "a man standing in front of a machine.",
+    "The video shows a sequence of three identical white cars driving on a road. The first car is in the foreground, "
+    "the second car is slightly behind and to the right, and the third car is in the background. The cars are moving "
+    "from left to right across the frame. The road appears to be a city street with a dark grey surface. The "
+    "background features a city skyline with buildings of various heights, and the sky is a gradient of orange and "
+    "yellow, suggesting either sunrise or sunset. The style of the video is realistic with a focus on the cars and "
+    "their movement.",
+    "The video captures a lively scene on the ocean, with three boats in motion. The first boat, a large white yacht, "
+    "is seen in the distance, sailing towards the horizon. The second and third boats are closer to the viewer, both "
+    "moving at high speeds, leaving trails of white water behind them. The ocean is a deep blue, and the sky above is "
+    "clear, suggesting a sunny day. The boats are the main focus of the video, with their movement and the water's "
+    "reaction to their speed creating a dynamic and exciting scene. The overall style of the video is a dynamic "
+    "aerial shot, capturing the movement and beauty of the ocean and the boats.",
+    "A single polished walnut-wood chess pawn stands on a small square pedestal of white Carrara marble. No other "
+    "objects are in the scene. The camera makes one complete 360-degree orbit around the pawn while slowly rising.",
+]
+
+with gr.Blocks(title="Video-Coder") as demo:
+    with gr.Column(elem_id="col-container"):
+        gr.Markdown(
+            "# 🎬 Video-Coder: agentic coding for video generation\n"
+            "**Video-Coder-9B** writes and runs a Blender Python program for your scene description, inspects the "
+            "rendered frames, fixes what is wrong and submits a **draft video** (white-model 3D render with the "
+            "layout, motion and camera of the scene) — the structure/motion signal the paper feeds to a downstream "
+            "video generator.\n\n"
+            "[📖 Paper](https://huggingface.co/papers/2611.09894) · [🌐 Project page](https://cywang735.github.io/"
+            "Video-Coder/) · [💻 Code](https://github.com/CYWang735/Video-Coder) · [🤗 Model](https://huggingface.co/"
+            "Video-Coder/Video-Coder-9B)\n\n"
+            "⏳ A full agent run takes several minutes (each turn generates a long script; each render runs Blender "
+            "on CPU). The trajectory streams live below."
+        )
+        with gr.Row():
+            prompt = gr.Textbox(label="Scene description", lines=3, scale=4,
+                                placeholder="Describe the scene and its motion, e.g. 'a red ball rolls down a ramp "
+                                            "and knocks over three dominoes'")
+            run_btn = gr.Button("Generate draft video", variant="primary", scale=1)
+        status = gr.Markdown()
+        with gr.Row():
+            with gr.Column(scale=1):
+                video_out = gr.Video(label="Draft video (Blender render)", autoplay=True)
+                preview_out = gr.Image(label="Latest render: frames 1, ⅓, ⅔, last", type="filepath")
+            with gr.Column(scale=1):
+                with gr.Tabs():
+                    with gr.Tab("Agent trajectory"):
+                        chat_out = gr.Chatbot(label="Video-Coder harness", height=640, show_label=False)
+                    with gr.Tab("main.py"):
+                        code_out = gr.Code(label="Blender script written by the agent", language="python",
+                                           lines=30)
+        with gr.Accordion("Advanced settings", open=False):
+            max_steps = gr.Slider(2, 30, value=12, step=1, label="Max agent steps (one bash command each)")
+            temperature = gr.Slider(0.1, 1.5, value=1.0, step=0.05, label="Temperature")
+            top_p = gr.Slider(0.5, 1.0, value=0.95, step=0.01, label="Top-p")
+            max_new_tokens = gr.Slider(2048, 32768, value=16384, step=1024, label="Max tokens per agent turn")
+
+        outputs = [chat_out, video_out, code_out, preview_out, status]
+        run_btn.click(run_agent, inputs=[prompt, max_steps, temperature, top_p, max_new_tokens], outputs=outputs,
+                      api_name="generate", concurrency_limit=2)
+        prompt.submit(run_agent, inputs=[prompt, max_steps, temperature, top_p, max_new_tokens], outputs=outputs,
+                      api_visibility="private", concurrency_limit=2)
+        gr.Examples(examples=[[e] for e in EXAMPLES], inputs=[prompt], outputs=outputs, fn=run_agent,
+                    cache_examples=False, run_on_click=True)
+
+if __name__ == "__main__":
+    demo.queue().launch(theme=gr.themes.Citrus(), css=CSS, mcp_server=True)

harness/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

harness/bin/check_script

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Agent-facing wrapper: static checks for a bpy script (default main.py in the current directory).
+set -euo pipefail
+root="$(cd "$(dirname "$0")/.." && pwd)"
+py="${VCSFT_PYTHON:-$root/.venv/bin/python}"
+PYTHONPATH="$root${PYTHONPATH:+:$PYTHONPATH}" exec "$py" -m video_coder_harness.static_check "$@"

harness/bin/run_blender

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Agent-facing wrapper: execute a bpy script with Blender 4.5 in the current directory (it renders the video here).
+set -euo pipefail
+root="$(cd "$(dirname "$0")/.." && pwd)"
+py="${VCSFT_PYTHON:-$root/.venv/bin/python}"
+PYTHONPATH="$root${PYTHONPATH:+:$PYTHONPATH}" exec "$py" -m video_coder_harness.blender_exec "$@"

harness/instance_template.txt

@@ -0,0 +1,64 @@
+## Task
+
+Write a Blender 4.5 Python script that builds the following scene and renders it as an animated white-model video:
+
+<scene_description>
+__TASK__
+</scene_description>
+
+
+## Script contract
+
+- Write exactly one self-contained script: `main.py` in the current directory.
+- It is executed headless as `blender --background --factory-startup --python main.py` with Blender 4.5, from the directory the video must be written to. Use only the Blender 4.5 API and the Python standard library; no external assets, files or add-ons.
+- Start by removing every object in the default scene, then build the scene from scratch.
+- Geometry: model with primitives, modifiers, `bmesh` or `mesh.from_pydata`. Name objects meaningfully. Keep the total scene under ~500k faces. Objects must not intersect unless the description implies contact.
+- Animation: the video lasts 5-10 seconds at 24 fps, i.e. 120-240 frames; choose the length that suits the action. Set `scene.frame_start = 1` and `scene.frame_end` to that length, and animate with keyframes, drivers, constraints or physics so that the motion described actually happens within that range. Bake any physics simulation before rendering.
+- Camera: create a camera, assign it to `scene.camera`, and frame the action so that it stays in view for all frames (animate the camera if the description asks for camera motion).
+- Seed any randomness (`random.seed(...)`) so the result is deterministic. Prefer `bpy.data` / low-level API over `bpy.ops` where the operator needs UI context.
+- Do not import subprocess, socket, shutil, urllib or similar modules, and do not call os.system/eval/exec.
+
+## White-model render (required, at the end of the script)
+
+Every video in this dataset uses the same look, so configure exactly this and then render:
+
+- `scene.render.engine = 'BLENDER_WORKBENCH'`
+- `scene.display.shading`: `light = 'STUDIO'`, `color_type = 'SINGLE'`, `single_color = (0.8, 0.8, 0.8)`, `show_shadows = True`, `show_cavity = True`, `cavity_type = 'WORLD'`. No materials or textures are needed; Workbench studio lighting ignores scene lights.
+- Resolution 1280x720 at `resolution_percentage = 100`, `scene.render.fps = 24`.
+- Output: `scene.render.image_settings.file_format = 'FFMPEG'`, `scene.render.ffmpeg.format = 'MPEG4'`, `scene.render.ffmpeg.codec = 'H264'`, `scene.render.filepath = os.path.join(os.getcwd(), 'output.mp4')`.
+- Last statement: `bpy.ops.render.render(animation=True)`.
+- Write no other files: no .blend files, images or caches outside the render. Do not quit Blender.
+
+## Tools
+
+Blender 4.5 is available through two commands (do not install anything):
+
+```bash
+check_script main.py   # fast static check: syntax, bpy import, camera, render call, forbidden calls
+run_blender main.py    # executes the script exactly like the harness and renders output.mp4 (CPU, ~20-120 s)
+```
+
+`run_blender` reports the Python traceback if the script fails, whether output.mp4 has 120-240 frames matching the scene frame range at 1280x720, and a scene summary: object counts, animated objects, world positions of moving meshes at sampled frames, and meshes whose origin is outside the camera view. Use the numbers to verify that the motion, timing and framing match the description. It also returns 8 frames sampled evenly from the rendered video as images, with their frame numbers and times. It reports a problem when most frames are empty, nothing moves, or no object is in view.
+
+## Workflow
+
+1. Think & Plan: Before generating any code, explicitly reason about the scene: objects, their dimensions and positions in meters, the motion over time (frame timing), and camera placement/framing.
+2. Write `main.py` with a heredoc: `cat <<'EOF' > main.py` ... `EOF`.
+3. Run `check_script main.py` and fix every error.
+4. Run `run_blender main.py`. Fix every error and problem it reports, and compare the scene summary against the description (positions, timing, clearances, camera framing).
+   Then inspect the returned frames one by one against the description and write down every concrete problem you see: missing, unrecognizable or wrongly counted objects; wrong arrangement; motion that is missing, in the wrong order or at the wrong time; objects cut off, outside the frame or too small; objects passing through each other; wrong camera behavior. Fix the problems in the script and run `run_blender` again.
+   Repeat until it reports RUN OK and the frames clearly show every element of the description. If a command keeps giving the same result, change the script or your approach instead of repeating it; repeated identical commands end the task.
+5. Submit with `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as a command on its own: the whole command is exactly that `echo`, never chained to another command with `&&`, `;` or `|`, and never in the same command as `check_script` or `run_blender`. You cannot continue after that. The harness then re-executes `main.py` from scratch; the task only counts if it renders a valid video.
+
+## Command rules
+
+- Make exactly ONE tool call per response: a single `bash` call with a single command (or one short chain that serves one purpose). Never put several tool calls in the same response; read the result of each command before deciding the next one. Every response must contain that tool call: never answer with text only, not even when you are finished (finishing means calling the submit command).
+- Every tool call must be preceded by written reasoning in plain text in the same response: at least one sentence on what the previous result showed and what this command is for. This applies to every command without exception, including `check_script`, `run_blender` and the submit command; a response that contains only a tool call and no text is not allowed.
+- Submit by itself: the command `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` must be the only command of its response. Do not append it to `check_script`, `run_blender` or any other command, and do not write that word anywhere else, not even in a comment. Run the final `run_blender` first, read its result, and only then send the submit command in a separate response.
+- Each command runs in a fresh subshell in the task directory; `cd` and environment variables do not persist, so do not use `cd`.
+- Only create or modify files in the current directory.
+- Do not explore or probe the environment. Everything you need is described above. Do not run `pwd`, `which`, `whereis`, `type`, `env`, `printenv`, `echo $PATH`, `ls` of any other directory, `--help` or `--version` of any command, `pip list`, or `import` checks for Python packages, and do not look for Blender, ffmpeg, PIL or numpy. Your script may use only `bpy` and the Python standard library. Your first command is the one that writes `main.py`.
+- Never print absolute paths of the machine, environment variables or the contents of `PATH`. If a command could print them, do not run it.
+- Use only `check_script` and `run_blender` to check and execute scripts. Do not inspect or modify the harness itself (how these commands are implemented, `VCSFT_*` environment variables, the Blender/bpy installation) and do not run Blender or bpy any other way; such commands are blocked.
+- Fix problems directly in `main.py`: change only the lines that are wrong (`sed -i`, or a short `python3` edit) and rerun `run_blender main.py`. Do not rewrite the whole file for a small fix.
+- Throwaway experiment scripts are a last resort, for when the `run_blender` report is not enough to understand a problem: write a small script in the current directory and run `run_blender experiment.py` (whatever it `print()`s appears in the blender log). Use at most two experiments, and delete the experiment files before submitting.

harness/video_coder_harness/blender_exec.py

@@ -0,0 +1,260 @@
+"""Execute a generated script with bpy (Blender 4.5, Workbench via Mesa llvmpipe on CPU) and check the video it renders.
+
+Shared by the agent's `run_blender` tool and by the harness's final re-execution, so both judge a script the same way.
+Harness settings come from the config (`harness:`) or, inside agent shells, from the VCSFT_HARNESS env var (JSON).
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+from video_coder_harness.video import contact_sheet, frame_stats, probe, sample_frames
+
+RUN_BPY = Path(__file__).resolve().parent / "run_bpy.py"
+_SECRET_ENV = re.compile(r"(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)", re.I)
+# Blender's per-frame render progress; dropped from the log shown to the agent.
+_NOISE = re.compile(r"^(Fra:|Append frame|Time: |\s*Saving:|Saved: |Read prefs|Blender quit|$)")
+
+
+def bpy_env(harness: dict) -> dict:
+    libs = os.path.expandvars(harness["bpy_libs"])
+    env = {k: v for k, v in os.environ.items() if not _SECRET_ENV.search(k)}
+    env |= {
+        "LD_LIBRARY_PATH": f"{libs}/lib",
+        "__EGL_VENDOR_LIBRARY_DIRS": f"{libs}/share/glvnd/egl_vendor.d",
+        "EGL_PLATFORM": "surfaceless",
+        "LIBGL_ALWAYS_SOFTWARE": "1",
+        "GALLIUM_DRIVER": "llvmpipe",
+        "PYTHONNOUSERSITE": "1",
+    }
+    env.pop("PYTHONPATH", None)
+    return env
+
+
+def execute(script: str | Path, cwd: str | Path, harness: dict, preview: bool = True) -> dict:
+    """Run `script` in `cwd`; it is expected to render harness['output_video'] there."""
+    cwd, script = Path(cwd).resolve(), Path(script).resolve()
+    video_path = cwd / harness["output_video"]
+    if video_path.exists():  # never judge a stale video from an earlier run
+        video_path.unlink()
+    timeout = harness["exec_timeout"]
+    report: dict = {"script": script.name}
+    with tempfile.TemporaryDirectory() as tmp:
+        result_file = Path(tmp) / "result.json"
+        cmd = [os.path.expandvars(harness["bpy_python"]), str(RUN_BPY), str(script),
+               "--cwd", str(cwd), "--result", str(result_file), "--samples", str(harness.get("summary_samples", 6))]
+        t0 = time.time()
+        try:
+            proc = subprocess.run(cmd, cwd=cwd, env=bpy_env(harness), capture_output=True, text=True,
+                                  errors="replace", timeout=timeout)
+            log = proc.stdout + proc.stderr
+            run = json.loads(result_file.read_text()) if result_file.is_file() else {}
+            if not run:
+                report["error"] = crash_message(proc.returncode)
+        except subprocess.TimeoutExpired as e:
+            log = (e.stdout or "") if isinstance(e.stdout, str) else (e.stdout or b"").decode(errors="replace")
+            run, report["error"] = {}, f"timed out after {timeout}s (render included)"
+        report["seconds"] = round(time.time() - t0, 1)
+
+    report["executed"] = bool(run.get("ok"))
+    if run.get("traceback"):
+        # relative paths: workspace locations must not end up in training data
+        report["traceback"] = _script_frames(run["traceback"], script.name).replace(f"{script.parent}/", "")
+    report["log_tail"] = [ln for ln in log.splitlines() if not _NOISE.match(ln)][-25:]
+    report["files_written"] = run.get("files_written", [])
+    if "scene" in run:
+        report["scene"] = _compact_scene(run["scene"])
+
+    video = probe(video_path)
+    report["video"] = video
+    want_w, want_h = harness["resolution"]
+    problems = []
+    if not report["executed"]:
+        problems.append("script did not execute successfully")
+    if not video.get("exists"):
+        problems.append(f"{harness['output_video']} was not rendered")
+    else:
+        if video.get("decode_error"):
+            problems.append(f"video cannot be decoded: {video['decode_error']}")
+        lo = harness["frame_count"]
+        hi = harness.get("max_frame_count", lo)
+        n = video.get("n_frames")
+        if not (n is not None and lo <= n <= hi):
+            want = f"{lo}" if lo == hi else f"{lo}-{hi}"
+            problems.append(f"video has {n} frames, expected {want}")
+        frame_range = (report.get("scene") or {}).get("frame_range")
+        if lo != hi and frame_range and n != frame_range[1] - frame_range[0] + 1:
+            problems.append(f"video has {n} frames but the scene frame range is {frame_range}")
+        if video.get("fps") and abs(video["fps"] - harness["fps"]) > 0.01:
+            problems.append(f"video is {video['fps']:g} fps, expected {harness['fps']} (set scene.render.fps)")
+        if (video.get("width"), video.get("height")) != (want_w, want_h):
+            problems.append(f"video is {video.get('width')}x{video.get('height')}, expected {want_w}x{want_h}")
+        if n and not video.get("decode_error"):
+            stats = frame_stats(video_path, n, samples=harness.get("content_samples", 8))
+            report["frame_stats"] = stats
+            problems += content_problems(stats, run.get("scene"))
+    extra = [f for f in report["files_written"] if f != harness["output_video"]]
+    if extra:
+        problems.append(f"script wrote files other than {harness['output_video']}: {extra}")
+    report["problems"] = problems
+    report["ok"] = not problems
+    if preview and video.get("n_frames"):
+        n = video["n_frames"]
+        frames = sorted({0, n // 3, 2 * n // 3, n - 1})
+        if contact_sheet(video_path, cwd / "preview.png", frames):
+            report["preview"] = {"file": "preview.png", "frames": [f + 1 for f in frames]}
+    return report
+
+
+_SIGNALS = {-6: "SIGABRT", -11: "SIGSEGV", -9: "SIGKILL", -7: "SIGBUS", -8: "SIGFPE"}
+
+
+def crash_message(returncode: int) -> str:
+    if returncode < 0:
+        sig = _SIGNALS.get(returncode, f"signal {-returncode}")
+        return (f"Blender crashed ({sig}) before the script finished, so there is no Python traceback; the blender "
+                "log tail may show the cause. Usual causes: invalid mesh data (bmesh/mesh elements used after "
+                "they were removed, or a stale bmesh index table: call ensure_lookup_table() after adding "
+                "elements), or using an object or datablock after deleting it. Bisect by commenting out parts of "
+                "the script.")
+    return f"Blender process exited with code {returncode} without a result"
+
+
+# A Workbench frame showing only background has a pixel std of ~0.6 (64x36 gray); scenes with geometry are > 3.
+BLANK_STD = 2.0
+STATIC_DIFF = 0.5
+
+
+def content_problems(stats: dict, scene: dict | None) -> list[str]:
+    """Hard checks on what the camera actually sees: mostly empty frames, no visible motion, nothing in view."""
+    problems = []
+    std, diff, frames = stats["std"], stats["diff"], stats["frames"]
+    blank = [f for f, s in zip(frames, std) if s < BLANK_STD]
+    if std and len(blank) > len(std) // 2:
+        problems.append(f"the rendered frames are empty (only background) at sampled frames {blank}: "
+                        "the camera does not see the scene")
+    if diff and max(diff) < STATIC_DIFF:
+        problems.append("the video is static: nothing visibly moves between the sampled frames")
+    if scene:
+        n_mesh = (scene.get("objects_by_type") or {}).get("MESH", 0)
+        outside = scene.get("mesh_origins_out_of_camera_view") or {}
+        n_sampled = len(scene.get("sampled_frames") or [])
+        if n_mesh and len(outside) >= n_mesh and all(len(v) == n_sampled for v in outside.values()):
+            problems.append("no mesh is inside the camera view in any sampled frame: aim the camera at the scene")
+    return problems
+
+
+HARNESS_DIR = str(Path(__file__).resolve().parent)
+
+
+def _script_frames(tb: str, script_name: str) -> str:
+    """Keep the traceback from the first frame inside the generated script; drop runner/runpy frames and frames
+    of the harness's own guards (video_coder_harness/), whose paths must not leak into trajectories."""
+    lines = tb.splitlines()
+    start = next((i for i, ln in enumerate(lines) if script_name in ln and ln.lstrip().startswith("File")), None)
+    if start is None:
+        return tb
+    kept, skipping = [], False
+    for ln in lines[start:]:
+        if ln.lstrip().startswith("File "):
+            skipping = HARNESS_DIR in ln
+        elif not ln.startswith(" "):  # the final "ExcType: message" line
+            skipping = False
+        if not skipping:
+            kept.append(ln)
+    return "Traceback (most recent call last):\n" + "\n".join(kept)
+
+
+def _compact_scene(scene: dict) -> dict:
+    moving = scene.get("moving_mesh_positions", {})
+    return {
+        "frame_range": scene.get("frame_range"),
+        "fps": scene.get("fps"),
+        "camera": scene.get("camera"),
+        "objects_by_type": scene.get("objects_by_type"),
+        "n_faces_evaluated": scene.get("n_faces_evaluated"),
+        "animated_objects": scene.get("animated_objects"),
+        "sampled_frames": scene.get("sampled_frames"),
+        "moving_mesh_world_positions (frame, x, y, z)": {k: moving[k] for k in list(moving)[:8]},
+        "n_moving_meshes": len(moving),
+        "mesh_origins_outside_camera_view": {k: f"{len(v)} of {len(scene.get('sampled_frames', []))} sampled frames"
+                                             for k, v in scene.get("mesh_origins_out_of_camera_view", {}).items()},
+    }
+
+
+def format_report(r: dict) -> str:
+    head = "RUN OK: script executed and rendered a valid video" if r["ok"] else "RUN FAILED"
+    out = [head, f"seconds: {r['seconds']}"]
+    if r.get("error"):
+        out.append(f"error: {r['error']}")
+    for p in r["problems"]:
+        out.append(f"problem: {p}")
+    if r.get("traceback"):
+        out += ["", r["traceback"].rstrip()]
+    if r.get("log_tail"):
+        out += ["", "blender log (tail):", *r["log_tail"]]
+    v = r["video"]
+    if v.get("exists"):
+        out += ["", "video: " + json.dumps({k: v[k] for k in ("n_frames", "width", "height", "fps", "codec", "bytes") if k in v})]
+    if r.get("scene"):
+        out += ["", "scene summary:"]
+        for key, value in r["scene"].items():
+            if isinstance(value, dict) and value and key != "objects_by_type":
+                out.append(f"  {key}:")
+                out += [f"    {name}: {json.dumps(v)}" for name, v in value.items()]
+            else:
+                out.append(f"  {key}: {json.dumps(value)}")
+    return "\n".join(out)
+
+
+def harness_from_env() -> dict:
+    raw = os.environ.get("VCSFT_HARNESS")
+    if not raw:
+        sys.exit("VCSFT_HARNESS is not set (run_blender is meant to be called inside a generation workspace)")
+    return json.loads(raw)
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description="Execute a bpy script with Blender 4.5 and check the rendered video.")
+    p.add_argument("script", nargs="?", default="main.py")
+    p.add_argument("--config", help="read harness settings from this config instead of $VCSFT_HARNESS")
+    p.add_argument("--json", action="store_true")
+    args = p.parse_args()
+    if args.config:
+        import yaml
+
+        harness = yaml.safe_load(Path(args.config).read_text())["harness"]
+    else:
+        harness = harness_from_env()
+    if not Path(args.script).is_file():
+        sys.exit(f"{args.script} not found")
+    r = execute(args.script, Path.cwd(), harness)
+    text = json.dumps(r, indent=2) if args.json else format_report(r)
+    if harness.get("visual_feedback") and r["video"].get("n_frames") and not args.json:
+        text += "\n\n" + frames_attachment(Path.cwd() / harness["output_video"], r["video"]["n_frames"],
+                                            r["video"].get("fps") or harness["fps"], harness)
+    print(text)
+    sys.exit(0 if r["ok"] else 1)
+
+
+def frames_attachment(video: Path, n_frames: int, fps: float, harness: dict) -> str:
+    """Evenly spaced frames of the render as inline images (mini-swe-agent multimodal tags), one per frame.
+
+    video_coder_harness.models turns each tag into a real image in the tool result, preceded by its caption line.
+    """
+    frames = sample_frames(video, n_frames, harness.get("preview_frames", 8), harness.get("preview_width", 640))
+    lines = [f"rendered frames ({len(frames)} evenly spaced, in order):"]
+    for frame, url in frames:
+        lines.append(f"Frame {frame} (t = {(frame - 1) / fps:.2f} s):")
+        lines.append(f"<MSWEA_MULTIMODAL_CONTENT><CONTENT_TYPE>image_url</CONTENT_TYPE>{url}</MSWEA_MULTIMODAL_CONTENT>")
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    main()

harness/video_coder_harness/guard.py

@@ -0,0 +1,137 @@
+"""(Ported from video_coder_harness/agent.py; the GuardedAgent loop itself lives in app.py.) Two guards for clean trajectories.
+
+- Repetition: consecutive near-identical commands with the same result first get a warning appended to their
+  output, and the run stops (exit status RepeatedActions) if the agent keeps repeating.
+- Harness boundary: commands that inspect the harness (VCSFT_* variables, the implementation of check_script /
+  run_blender, the bpy installation) or write outside the task directory are not executed; the agent gets a
+  BLOCKED message instead. Blocked commands are counted so such trajectories can be left out of SFT data.
+"""
+
+import difflib
+import re
+import shlex
+
+
+TOOLS = ("run_blender", "check_script")
+# Shell-level rules: applied to the command with here-document bodies removed, so the Python written into main.py
+# (comments like "frame -> /tmp", "x > 0") is not mistaken for shell redirections or commands.
+_INSPECT = re.compile(rf"^\s*(?:sudo\s+)?(?:type|which|command\s+-v|cat|less|more|head|tail|sed|awk|file|readlink|"
+                      rf"realpath|ls|stat|strings|od|xxd)\b[^;&|]*\b({'|'.join(TOOLS)})\b")
+_ENV_CMD = re.compile(r"(?m)(?:^|[;&|(]|\$\()\s*(?:env|printenv|set|export\s+-p|declare\s+-[px])\s*(?:$|[|;&>)])")
+# writes to an absolute path (redirection, tee, cp/mv/ln target, mkdir/touch), except /dev/null and /dev/std*
+_ABS_WRITE = re.compile(r"(?:(?<![0-9&<])>>?|\btee(?:\s+-a)?|\b(?:mkdir|touch)(?:\s+-p)?)\s*['\"]?"
+                        r"(/(?!dev/(?:null|stdout|stderr)\b)[^\s'\";|&]*)")
+_ABS_TARGET = re.compile(r"\b(?:cp|mv|ln|install|rsync)\b[^\n;|&]*\s['\"]?(/(?!dev/null\b)[^\s'\";|&]+)['\"]?\s*(?:$|[;|&\n])")
+# Whole-text rules (here-document bodies included, so `python3 - <<EOF ... open(...)` is covered too):
+# harness variables and locations that hold credentials or lie outside the task directory.
+_HARNESS_VAR = re.compile(r"\bVCSFT_")
+_SENSITIVE = re.compile(r"(~/|\$\{?HOME\b|/home/|/root/|\.ssh/|\.netrc\b|\.config/|\.env\b|\bOPENAI_API_KEY\b|"
+                        r"\b[A-Z0-9_]*(?:API_KEY|SECRET|TOKEN|PASSWORD)\b|\bsk-[A-Za-z0-9_-]{8,})")
+_HEREDOC = re.compile(r"<<-?\s*(['\"]?)([A-Za-z_][A-Za-z0-9_]*)\1")
+
+
+def strip_heredocs(command: str) -> str:
+    """The shell text of a command without here-document bodies (the delimiter lines are dropped too)."""
+    lines, out, i = command.split("\n"), [], 0
+    while i < len(lines):
+        line = lines[i]
+        out.append(line)
+        i += 1
+        for m in _HEREDOC.finditer(line):
+            while i < len(lines) and lines[i].strip() != m.group(2):
+                i += 1
+            i += 1  # the closing delimiter
+    return "\n".join(out)
+
+
+# Python code (also inside here-documents) that writes to an absolute path.
+_PY_ABS_WRITE = [
+    re.compile(r"""\bopen\(\s*[rbuf]*(['"])(/[^'"]*)\1\s*,\s*[rbuf]*(['"])[^'"]*[wax+][^'"]*\3"""),
+    re.compile(r"""\bPath\(\s*(['"])(/[^'"]*)\1\s*\)\s*\.\s*(?:write_text|write_bytes|mkdir|touch|unlink|rename|replace)\b"""),
+    re.compile(r"""\bos\.(?:makedirs|mkdir|rename|replace|remove|unlink|rmdir)\(\s*(['"])(/[^'"]*)\1"""),
+    re.compile(r"""\bfilepath\s*=\s*[rbuf]*(['"])(/[^'"]*)\1"""),
+]
+_PARENT_DIR = re.compile(r"(?<![\w.])\.\./")
+_SEPARATORS = set("();<>|&")
+
+
+def in_dir(path: str, directory: str) -> bool:
+    """True if `path` is `directory` itself or lies below it ('/w-other' is not inside '/w')."""
+    d = directory.rstrip("/")
+    return bool(d) and (path == d or path.startswith(d + "/"))
+
+
+def _mask_workdir(text: str, workdir: str) -> str:
+    """Replace the task directory by '.' in `text`, but not a longer sibling name such as '<workdir>-other'."""
+    if not workdir:
+        return text
+    return re.sub(re.escape(workdir.rstrip("/")) + r"(?![A-Za-z0-9_.-])", ".", text)
+
+
+def _is_separator(token: str | None) -> bool:
+    return bool(token) and all(c in _SEPARATORS for c in token)
+
+
+def _shell_path_violation(shell: str, workdir: str) -> str:
+    """Rules on shell words: `..` path components and `cd` to somewhere outside the task directory."""
+    text = shell.replace("\\\n", " ").replace("\n", " ; ")
+    try:
+        lex = shlex.shlex(text, posix=True, punctuation_chars=True)
+        lex.whitespace_split = True
+        tokens = list(lex)
+    except ValueError:  # unbalanced quotes etc.: the regex rules still apply
+        return ""
+    for i, tok in enumerate(tokens):
+        if tok == ".." or tok.startswith("../") or "/../" in tok or tok.endswith("/.."):
+            return "it reaches outside the task directory with '..'"
+        if tok in ("cd", "pushd") and (i == 0 or _is_separator(tokens[i - 1])):
+            nxt = tokens[i + 1] if i + 1 < len(tokens) else ""
+            target = "" if _is_separator(nxt) else nxt
+            if not target or target.startswith(("~", "$", "-")):
+                return f"`{tok}` without a path inside the task directory leaves it"
+            if target.startswith("/") and not target.startswith("/dev/") and not in_dir(target, workdir):
+                return f"it changes into a directory outside the task directory ({target})"
+    return ""
+
+
+def harness_violation(command: str, harness_markers: list[str], workdir: str = "") -> str:
+    """Reason why a command crosses the harness boundary, or "" if it is fine."""
+    for marker in harness_markers:
+        if marker and marker in command:
+            return f"it references the harness installation ({marker})"
+    if _HARNESS_VAR.search(command):
+        return "it reads the harness environment variables"
+    m = _SENSITIVE.search(_mask_workdir(command, workdir))  # the task directory itself is fine
+    if m:
+        return f"it references files or variables outside the task directory ({m.group(1)})"
+    if _PARENT_DIR.search(command):
+        return "it reaches outside the task directory with '../'"
+    for pattern in _PY_ABS_WRITE:  # whole text: covers `python3 -c` and here-documents
+        for m in pattern.finditer(command):
+            path = m.group(2)
+            if not (path.startswith("/dev/") or in_dir(path, workdir)):
+                return f"it writes outside the task directory ({path})"
+    shell = strip_heredocs(command)
+    for line in shell.splitlines():
+        if _INSPECT.search(line):
+            return f"it inspects how {', '.join(TOOLS)} are implemented"
+    if _ENV_CMD.search(shell):
+        return "it reads the environment variables"
+    for pattern in (_ABS_WRITE, _ABS_TARGET):
+        for m in pattern.finditer(shell):
+            if not in_dir(m.group(1), workdir):
+                return f"it writes outside the task directory ({m.group(1)})"
+    return _shell_path_violation(shell, workdir)
+
+
+BLOCKED = ("BLOCKED: this command was not executed because {reason}. Work only in the current directory and use "
+           "only check_script and run_blender; do not inspect or modify the harness or run Blender any other way. "
+           "For a quick experiment, write a small script in the current directory and run `run_blender "
+           "experiment.py`; its print() output appears in the blender log.")
+REPEAT_WARNING = ("\n\nWARNING: this is the {n}th consecutive near-identical command with the same result. Repeating "
+                  "it will not help: read the output, then change the script or your approach. The task ends after "
+                  "{stop} repetitions.")
+
+
+def _normalize_output(text: str) -> str:
+    return re.sub(r"\d+(?:\.\d+)?", "#", text or "")

harness/video_coder_harness/run_bpy.py

@@ -0,0 +1,134 @@
+"""Execute a generated script with the `bpy` module and print a JSON scene summary.
+
+Run with the bpy environment (Python 3.11 + bpy 4.5), not the project venv:
+    LD_LIBRARY_PATH=$WORK/envs/bpy45-libs/lib $WORK/envs/bpy45/bin/python video_coder_harness/run_bpy.py main.py
+The script runs in --cwd (default: a fresh temporary directory); exit code 0 = executed without exception.
+Normally called through video_coder_harness.blender_exec, which sets up the environment, timeout and video checks.
+"""
+
+import argparse
+import json
+import os
+import runpy
+import sys
+import tempfile
+import time
+import traceback
+from pathlib import Path
+
+
+def summarize(bpy, samples: int) -> dict:
+    from bpy_extras.object_utils import world_to_camera_view
+
+    scene = bpy.context.scene
+    objects = list(scene.objects)
+    by_type: dict[str, int] = {}
+    for o in objects:
+        by_type[o.type] = by_type.get(o.type, 0) + 1
+    animated = sorted(o.name for o in objects if o.animation_data and o.animation_data.action)
+    start, end = scene.frame_start, scene.frame_end
+    frames = sorted({start, end, *[round(start + i * (end - start) / (samples - 1)) for i in range(samples)]})
+
+    meshes = [o for o in objects if o.type == "MESH"]
+    positions: dict[str, list] = {}
+    out_of_view: dict[str, list[int]] = {}
+    n_faces = 0
+    depsgraph = bpy.context.evaluated_depsgraph_get()
+    for f in frames:
+        scene.frame_set(f)
+        for o in meshes:
+            loc = o.matrix_world.translation
+            if o.name in animated or (o.parent and o.parent.name in animated):
+                positions.setdefault(o.name, []).append([f, *[round(v, 3) for v in loc]])
+            if scene.camera:
+                p = world_to_camera_view(scene, scene.camera, loc)
+                if not (0 <= p.x <= 1 and 0 <= p.y <= 1 and p.z > 0):
+                    out_of_view.setdefault(o.name, []).append(f)
+    for o in meshes:
+        n_faces += len(o.evaluated_get(depsgraph).data.polygons)
+    return {
+        "blender": bpy.app.version_string,
+        "frame_range": [start, end],
+        "fps": scene.render.fps,
+        "camera": scene.camera.name if scene.camera else None,
+        "n_objects": len(objects),
+        "objects_by_type": by_type,
+        "n_faces_evaluated": n_faces,
+        "animated_objects": animated,
+        "sampled_frames": frames,
+        "moving_mesh_positions": positions,
+        "mesh_origins_out_of_camera_view": out_of_view,
+    }
+
+
+def install_guards(bpy) -> None:
+    """Turn the most common hard crash into a Python error with a line number.
+
+    Mesh.from_pydata does not check indices: an edge or face that references a vertex that does not exist
+    corrupts Blender's memory and kills the process (SIGABRT/SIGSEGV) with no traceback.
+    """
+    original = bpy.types.Mesh.from_pydata
+
+    def checked_from_pydata(self, vertices, edges, faces, *args, **kwargs):
+        n = len(vertices)
+        for kind, items, min_len in (("edge", edges, 2), ("face", faces, 3)):
+            for i, item in enumerate(items):
+                idx = list(item)
+                if len(idx) < min_len:
+                    raise ValueError(f"from_pydata: {kind} {i} has {len(idx)} vertices, needs at least {min_len}")
+                bad = [v for v in idx if not (isinstance(v, int) and 0 <= v < n)]
+                if bad:
+                    raise ValueError(f"from_pydata: {kind} {i} uses vertex index {bad[0]!r}, "
+                                     f"but the mesh has only {n} vertices (valid indices 0..{n - 1})")
+                if len(set(idx)) != len(idx):
+                    raise ValueError(f"from_pydata: {kind} {i} repeats a vertex: {tuple(idx)}")
+        return original(self, vertices, edges, faces, *args, **kwargs)
+
+    bpy.types.Mesh.from_pydata = checked_from_pydata
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("script")
+    p.add_argument("--samples", type=int, default=6, help="frames sampled for motion/visibility checks")
+    p.add_argument("--cwd", help="directory to run the script in (it renders its output here)")
+    p.add_argument("--result", help="write the JSON result to this file instead of stdout")
+    args = p.parse_args()
+    script = Path(args.script).resolve()
+
+    import bpy
+
+    bpy.ops.wm.read_factory_settings(use_empty=False)  # same starting point as `blender --factory-startup`
+    install_guards(bpy)
+    result = {"script": str(script)}
+    with tempfile.TemporaryDirectory() as tmp:
+        cwd = Path(args.cwd).resolve() if args.cwd else Path(tmp)
+        os.chdir(cwd)
+        before = set(os.listdir(cwd))
+        t0 = time.time()
+        try:
+            runpy.run_path(str(script), run_name="__main__")
+            result["ok"] = True
+        except BaseException:  # noqa: BLE001  (SystemExit from the script counts as failure too)
+            result["ok"] = False
+            result["traceback"] = traceback.format_exc(limit=8)
+        result["exec_seconds"] = round(time.time() - t0, 2)
+        result["files_written"] = sorted(set(os.listdir(cwd)) - before)
+        if result["ok"]:
+            try:
+                result["scene"] = summarize(bpy, args.samples)
+            except Exception:  # noqa: BLE001  (a broken scene must not hide the execution result)
+                result["scene_error"] = traceback.format_exc(limit=3)
+    text = json.dumps(result, indent=2, ensure_ascii=False)
+    if args.result:
+        Path(args.result).write_text(text)
+    else:
+        print(text)
+    # Skip bpy teardown: after a failed script it can hang on leaked data until the harness timeout.
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os._exit(0 if result["ok"] else 1)
+
+
+if __name__ == "__main__":
+    main()

harness/video_coder_harness/static_check.py

@@ -0,0 +1,123 @@
+"""Static checks for a generated bpy script, used both as an agent tool and as the acceptance gate.
+
+Without a Blender backend this is the only verification, so it is deliberately conservative:
+errors reject the sample, warnings are recorded but do not.
+"""
+
+import argparse
+import ast
+import json
+import sys
+from pathlib import Path
+
+MAX_BYTES = 200_000
+
+FORBIDDEN_MODULES = {
+    "subprocess", "socket", "requests", "urllib", "http", "ftplib", "smtplib",
+    "multiprocessing", "ctypes", "shutil", "webbrowser", "asyncio",
+}
+FORBIDDEN_CALLS = {
+    "os.system", "os.popen", "os.remove", "os.unlink", "os.rmdir", "os.removedirs",
+    "os.rename", "os.replace", "os.kill", "os.fork", "os.execv", "os.execvp",
+    "exec", "eval", "compile", "__import__",
+}
+# The script renders the video itself (bpy.ops.render.render); saving and process lifetime belong to the harness.
+REQUIRED_RENDER_CALL = "bpy.ops.render.render"
+FORBIDDEN_BPY_OPS = {
+    "bpy.ops.render.opengl",
+    "bpy.ops.wm.save_as_mainfile", "bpy.ops.wm.save_mainfile", "bpy.ops.wm.quit_blender",
+    "bpy.ops.wm.open_mainfile", "bpy.ops.wm.read_homefile",
+}
+ANIMATION_MARKERS = {
+    "keyframe_insert", "driver_add", "fcurves", "keyframe_points",
+    "rigidbody", "rigid_body", "frame_change_pre", "frame_change_post", "constraints",
+}
+
+
+def _dotted(node: ast.AST) -> str:
+    parts = []
+    while isinstance(node, ast.Attribute):
+        parts.append(node.attr)
+        node = node.value
+    if isinstance(node, ast.Name):
+        parts.append(node.id)
+        return ".".join(reversed(parts))
+    return ""
+
+
+def check_source(source: str) -> dict:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if len(source.encode()) > MAX_BYTES:
+        errors.append(f"script is larger than {MAX_BYTES} bytes")
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        return {"ok": False, "errors": [f"SyntaxError: {e.msg} (line {e.lineno})"], "warnings": [], "stats": {}}
+
+    imports: set[str] = set()
+    calls: set[str] = set()
+    attrs: set[str] = set()
+    assigned_attrs: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            imports.update(a.name.split(".")[0] for a in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            imports.add(node.module.split(".")[0])
+        elif isinstance(node, ast.Call):
+            calls.add(_dotted(node.func))
+        elif isinstance(node, ast.Attribute):
+            attrs.add(node.attr)
+        elif isinstance(node, ast.Constant) and isinstance(node.value, str):
+            attrs.add(node.value)  # e.g. keyframe_insert(data_path=...) or getattr(obj, "constraints")
+        if isinstance(node, (ast.Assign, ast.AugAssign, ast.AnnAssign)):
+            targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+            assigned_attrs.update(t.attr for t in targets if isinstance(t, ast.Attribute))
+
+    if "bpy" not in imports:
+        errors.append("script does not import bpy")
+    for mod in sorted(imports & FORBIDDEN_MODULES):
+        errors.append(f"forbidden import: {mod}")
+    for call in sorted(calls & (FORBIDDEN_CALLS | FORBIDDEN_BPY_OPS)):
+        errors.append(f"forbidden call: {call} (only the video render may write output)")
+    if REQUIRED_RENDER_CALL not in calls:
+        errors.append("no render: the script must end with bpy.ops.render.render(animation=True)")
+    has_camera = "camera" in assigned_attrs or "bpy.ops.object.camera_add" in calls
+    if not has_camera:
+        errors.append("no camera: create a camera and assign it to scene.camera")
+    if not (attrs & ANIMATION_MARKERS):
+        warnings.append("no animation detected (keyframes, drivers, constraints or physics)")
+    if "open" in calls:
+        warnings.append("script calls open(); external files are not available")
+
+    stats = {"lines": source.count("\n") + 1, "bytes": len(source.encode()), "n_bpy_ops_calls": sum(c.startswith("bpy.ops.") for c in calls)}
+    return {"ok": not errors, "errors": errors, "warnings": warnings, "stats": stats}
+
+
+def check_file(path: Path) -> dict:
+    if not path.is_file():
+        return {"ok": False, "errors": [f"{path} not found"], "warnings": [], "stats": {}}
+    return check_source(path.read_text(encoding="utf-8", errors="replace"))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Static checks for a Blender bpy script.")
+    parser.add_argument("script", nargs="?", default="main.py")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+    result = check_file(Path(args.script))
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print("STATIC CHECK " + ("PASSED" if result["ok"] else "FAILED"))
+        for e in result["errors"]:
+            print(f"error: {e}")
+        for w in result["warnings"]:
+            print(f"warning: {w}")
+        if result["stats"]:
+            print(f"stats: {json.dumps(result['stats'])}")
+    sys.exit(0 if result["ok"] else 1)
+
+
+if __name__ == "__main__":
+    main()

harness/video_coder_harness/video.py

@@ -0,0 +1,74 @@
+"""Inspect a rendered video with the ffmpeg binary bundled by imageio-ffmpeg (no system ffmpeg on the cluster)."""
+
+import base64
+import re
+import subprocess
+from pathlib import Path
+
+import imageio_ffmpeg
+
+FFMPEG = imageio_ffmpeg.get_ffmpeg_exe()
+
+
+def probe(path: str | Path) -> dict:
+    """Decode the whole video stream: returns frame count, size and fps, or an error."""
+    path = Path(path)
+    if not path.is_file():
+        return {"exists": False}
+    info: dict = {"exists": True, "bytes": path.stat().st_size}
+    proc = subprocess.run([FFMPEG, "-hide_banner", "-nostdin", "-i", str(path), "-map", "0:v:0", "-f", "null", "-"],
+                          capture_output=True, text=True, timeout=300)
+    err = proc.stderr
+    if m := re.search(r"Video: (\w+).*?, (\d{2,5})x(\d{2,5})", err):
+        info["codec"], info["width"], info["height"] = m.group(1), int(m.group(2)), int(m.group(3))
+    if m := re.search(r"([\d.]+) fps", err):
+        info["fps"] = float(m.group(1))
+    frames = re.findall(r"frame=\s*(\d+)", err)
+    info["n_frames"] = int(frames[-1]) if frames else 0
+    if proc.returncode != 0 or not frames:
+        info["decode_error"] = err.strip().splitlines()[-1] if err.strip() else f"ffmpeg exit {proc.returncode}"
+    return info
+
+
+def frame_stats(path: str | Path, n_frames: int, samples: int = 6, w: int = 64, h: int = 36) -> dict:
+    """Grayscale statistics of `samples` evenly spaced frames, downscaled to w x h.
+
+    std: per-frame pixel standard deviation (≈0 when the camera sees only background).
+    diff: mean absolute pixel difference between consecutive sampled frames (≈0 when nothing moves).
+    """
+    idx = sorted({round(i * (n_frames - 1) / (samples - 1)) for i in range(samples)})
+    select = "+".join(f"eq(n\\,{f})" for f in idx)
+    proc = subprocess.run([FFMPEG, "-hide_banner", "-nostdin", "-loglevel", "error", "-i", str(path),
+                           "-vf", f"select='{select}',scale={w}:{h},format=gray", "-vsync", "0",
+                           "-f", "rawvideo", "-"], capture_output=True, timeout=300)
+    size = w * h
+    frames = [proc.stdout[i:i + size] for i in range(0, len(proc.stdout) - size + 1, size)]
+    std = []
+    for f in frames:
+        mean = sum(f) / size
+        std.append(round((sum((p - mean) ** 2 for p in f) / size) ** 0.5, 2))
+    diff = [round(sum(abs(a - b) for a, b in zip(f0, f1)) / size, 2) for f0, f1 in zip(frames, frames[1:])]
+    return {"frames": [i + 1 for i in idx][: len(frames)], "std": std, "diff": diff}
+
+
+def contact_sheet(path: str | Path, out: str | Path, frames: list[int], width: int = 480) -> bool:
+    """Tile the given 0-based frame indices into a 2-column grid image."""
+    select = "+".join(f"eq(n\\,{f})" for f in frames)
+    rows = (len(frames) + 1) // 2
+    proc = subprocess.run([FFMPEG, "-hide_banner", "-nostdin", "-loglevel", "error", "-y", "-i", str(path),
+                           "-vf", f"select='{select}',scale={width}:-2,tile=2x{rows}", "-frames:v", "1", str(out)],
+                          capture_output=True, text=True, timeout=300)
+    return proc.returncode == 0 and Path(out).is_file()
+
+
+def sample_frames(video: str | Path, n_frames: int, k: int, width: int) -> list[tuple[int, str]]:
+    """(1-based frame number, JPEG data URL) for k evenly spaced frames."""
+    idx = sorted({round(i * (n_frames - 1) / (k - 1)) for i in range(k)})
+    out = []
+    for i in idx:
+        proc = subprocess.run([FFMPEG, "-hide_banner", "-nostdin", "-loglevel", "error", "-i", str(video),
+                               "-vf", f"select='eq(n\\,{i})',scale={width}:-2", "-frames:v", "1",
+                               "-q:v", "4", "-f", "image2", "-c:v", "mjpeg", "-"], capture_output=True, timeout=120)
+        if proc.returncode == 0 and proc.stdout:
+            out.append((i + 1, "data:image/jpeg;base64," + base64.b64encode(proc.stdout).decode()))
+    return out

packages.txt

@@ -0,0 +1,13 @@
+libx11-6
+libxrender1
+libxxf86vm1
+libxfixes3
+libxi6
+libxext6
+libxkbcommon0
+libsm6
+libgl1
+libegl1
+libegl-mesa0
+libgl1-mesa-dri
+libgomp1

requirements.txt

@@ -0,0 +1,8 @@
+transformers>=5.17.0
+torchvision
+accelerate
+flash-linear-attention
+imageio-ffmpeg
+uv
+pillow
+pyyaml