ARIS-Movie-Director

🌐 中文 README · English

Hand a fuzzy story to your agent, wake up to a cross-model-audited movie 🎬 — no forgotten facts, no frame signing off on itself.
🎞️ Image-based today, video next.
🤖 Agentic by design — planning · gating · cross-model review on the agent; rendering on the diffusion model.

📚 Jump to — ▶ Watch the movie · ⚡ Quick Start · 🔄 Workflows · 📝 Make your own · 🧩 Layout · 💬 Community · 📖 Cite · 🤝 Contributing

· · · · · · ·

This is an agentic, long-horizon visual generation task: hand a fuzzy story to an agent and produce a whole image-based movie (the reference run is a 19-scene / 24-frame story), not a single image. The concrete job is fuzzy story → authored comic.json → audited panels → single-file viewer.

The hard part is faithfulness over time. Generated visual stories can look coherent while quietly changing the facts — a chart rounds a number, a label mutates, a character's face drifts — and the run still ships, because the same system that drew the frame is the one saying it looks fine. Across a long horizon, two failure modes dominate:

• 🧠 Long-range forgetting — over many frames, identity, established facts, and earlier decisions drift.
• 🗣️ Linear, self-approved streaming — each frame is committed by the model that drew it, so mistakes compound unchecked.

🔬 Method at a glance. Read the figure left-to-right — the /movie-pipeline agent workflow runs the full loop (author a source of truth → bake → cross-model gate): (1) comic-author turns fuzzy intent into an authored comic.json + locked refs, (2) comic-director runs the per-panel audited spiral — the multi-agent debate (Codex narrative ‖ Gemini + Codex visual blind-read → deterministic diff), logging every attempt / decision to the research-wiki — (3) the pipeline assembles accepted panels into the released viewer. The bottom-left failure is the whole rule: a beautiful but wrong literal still fails (+6.2 expected vs +6.25 observed).

_{Figure 1 — from story intent to a verified movie, end-to-end (the loop described above). Full caption ↓}

ARIS-Movie-Director treats every frame as an auditable artifact: author a deterministic comic.json first (lock the expected_literals + identity refs before any pixels), let a generative model bake the look, then require independent cross-model blind-transcription + a deterministic token-diff before a panel is kept. Looks right ≠ passes — a beautiful frame with a wrong literal is rejected. It answers the two failure modes with two ideas from the ARIS series:

• 🧠→ a research-wiki — persistent, inspectable memory (locked refs · expected_literals · every decision & failure as a node) that anchors late frames to early truth.
• 🗣️→ multi-agent debate — independent cross-model reviewers blind-read every frame and a deterministic diff decides KEEP / RETRY, so no frame signs off on itself. Every attempt / decision lands in that wiki trace.

This first release is image-based — the movie is told in baked still frames you flip through. Video-based generation is what comes next; this is just the beginning.

▶ Watch the image-based movie in your browser — flip through all 19 scenes of the cross-model-audited reference run.

_{A few frames from the reference movie — including the story's own integrity beat: a run that reported +6.2 improvement but really moved +1.4 (that's the plot, distinct from the figure's bake-time +6.2/+6.25 token-diff). Watch all 19 scenes →}

⚡ Quick Start

# 1 · get the repo + Python deps  (everything but jsonschema is stdlib)
git clone https://github.com/wanshuiyin/ARIS-Movie-Director.git && cd ARIS-Movie-Director
python3 -m pip install -r requirements.txt

# 2 · external tools for the bake/review stages — install + authenticate, then verify:
#     codex CLI  ·  a google-family reviewer (legacy gemini CLI, or Antigravity via the shipped shim — see note)  ·  headless Chrome / Chromium
python3 cli/preflight.py

There is no bundled installer — the skills/ are followed by your coding agent pointed at this repo; the deterministic CLIs run in-repo.

Google-family reviewer (2026-07): the legacy gemini CLI is deprecated upstream (it now dies with IneligibleTierError — Gemini Code Assist for individuals is retired; Google's migration target is Antigravity). Install Antigravity (agy) + log in, then pass --gemini-cmd "python3 cli/gemini_agy_shim.py" to run_comic.py / run_spiral.py — the shipped shim translates the old gemini -p "@file …" reviewer interface to agy and pins a Gemini model (Antigravity also serves Claude/GPT-OSS; the second-reviewer slot must stay google-family or the cross-model quorum's provenance is corrupted). If your legacy gemini CLI still works, the default is unchanged.

Run the two workflows — in a coding agent that has these skills (/… is a slash-command agent workflow, not a shell binary):

> /movie-pipeline "a short film about an autonomous research run"   # Workflow 1 — fuzzy idea → audited movie + viewer (pauses at intent + outline)
> /method-figure  path/to/method_figure_brief.json                 # Workflow 2 — a brief → audited Figure-1 (render + verify → Claude sign-off)

See it first — zero setup, no API: ▶ open the hosted movie at https://wanshuiyin.github.io/ARIS-Movie-Director/comic/ (all 19 scenes / 24 frames). To rebuild it locally, see Workflow 1 → See the reference movie below.

_{Full map — fuzzy story → /movie-pipeline → comic.json + audited panels + outputs/index.html · method_figure_brief.json → /method-figure → figure.png + blueprint + trace}

🔄 Workflows

Two cross-model-audited workflows. Each is one slash-command agent workflow (the ARIS /research-pipeline paradigm — an agent runs it, pausing at the human gates), with a deterministic CLI core you can also run standalone (the part CI tests).

🎬 Workflow 1 · Movie pipeline — /movie-pipeline (fuzzy idea → audited movie)

Hand your agent a fuzzy story, approve two story gates, wake up to a baked, cross-model-audited movie + a clickable viewer:

> /movie-pipeline "a short film about an autonomous research run"

It chains comic-author (Phase 1 — author the source of truth) → the zero-credit p0_proof gate → comic-director (Phase 2/3 — the audited spiral → viewer); the orchestrator is movie-pipeline. It's an agent workflow, not a shell binary — it needs a coding-agent runtime and pauses at intent + outline for your approval. (A step that doesn't fire is safe — each layer consumes the prior LOCKED node, so a skipped step fails closed at the next gate, never shipping a wrong frame.)

• 🧭 Intent — fuzzy idea → intent_spec · stop for your approval
• 🎨 Style lock — the ART_BIBLE.md + locked style_anchors (warm-lab / dark-cyber / starfield)
• 🧱 Outline — 3-lens debate → synthesis → outline_spec · stop for your approval
• 🎞️ Storyboard — pages · panels · the MOTIF STATE TABLE · consolidated asset_requests
• 🧑‍🎨 Assets — a single-source library, reviewed to locked (准×3 same-round unanimity)
• 📐 Blueprints — a deterministic content_svg per panel (no baked bubbles)
• 🧾 Prompts — exact bake prompts + verbatim expected_literals (搬运工原則)
• ✅ Compile — schema-valid comic.json; the zero-credit p0_proof gate runs BEFORE any image credit
• 🔥 Spiral bake — render → agent mcp__codex__codex sidecar bake (Codex's native image tool) → 3-reviewer panel_gate → keep / retry-same-panel → assembly_gate (re-bakes only NAMED drifting panels on cross-page drift) → viewer

📐 Flow — the skill chain (trace it top-to-bottom):

/movie-pipeline "fuzzy idea"            one slash-command · agent-run, NOT a shell binary
   │
   ▼   comic-author drives these Phase-1 skills IN ORDER (they are not separate slash-commands):
   comic-intent-parser
     → ⟨HUMAN APPROVE — intent⟩
     → comic-style-bible-lock
     → comic-outline-creator
     → ⟨HUMAN APPROVE — outline⟩
     → comic-storyboard-creator
     → comic-asset-ref-generator → comic-asset-review-loop          (准×3 unanimity → assets LOCKED)
     → comic-blueprint-author → comic-panel-prompt-builder → comic-json-compiler
   ├──────────────── Phase 1 · comic-author — author the source of truth ────────────────┤
   │
   │   → comic.json + locked assets + the author wiki trace
   ▼
   comic-cross-layer-gate --gate p0_proof     ├─ P0 · ZERO-CREDIT proof — must pass before any image credit ─┤
   │
   ▼   comic-director — the audited spiral     (run_comic.py  |  packages/core/spiral_engine.js)
   per panel:  content_svg → agent mcp__codex__codex sidecar bake → panel_gate
                  reviewers: Codex narrative ‖ Gemini visual ‖ Codex visual
                  → blind transcriptions → deterministic token-diff vs expected_literals
               verdict ─ KEEP → page pool
                       ├ RETRY ≤4   (re-bake the SAME panel + repair note)
                       └ assembly_gate repair ≤6 — re-bake ONLY the NAMED drifting panels when drift is localized (seed-anchored; never wipes prior good panels)
   page assembly_gate → project accepted panels to comic.json → build_comic.py → outputs/index.html
   ├──────────────── Phase 2/3 · comic-director — audited spiral + viewer ────────────────┤

   📚 research-wiki — reads the locked source nodes before each layer; writes every attempt / review /
                      decision / failure after each gate & bake (the inspectable audit trace).
   🔄 human-in-loop — intent + outline are HARD stops; a failed p0 / panel / assembly gate stops or
                      escalates; a non-convergent panel is flagged for you, never silently shipped.

The panel_gate (Phase 2/3, per panel): the bake is read by 3 independent reviewers — a narrative reviewer (does it land the beat? — currently the codex CLI, recorded honestly as family openai; a configurable --narrative-reviewer is planned, not yet implemented) ‖ Gemini visual ‖ Codex visual — who blind-transcribe the pixels; a deterministic token-diff of observed_literals vs the authored expected_literals decides KEEP / RETRY; content_corruption is a single-vote veto, both visual reviewers must score, and no model self-acquits. Every attempt / review×3 / decision / failure is written to the research-wiki. There is no live Claude CLI reviewer in this panel — Claude's role is the workflow-layer structural sign-off; cross-family acquittal vs the Claude-authored prompts comes from Gemini + the deterministic fuse.

Phase 2/3 standalone (once comic.json exists). Only the zero-credit --dry-run below is genuinely agent-free — that's the CI-tested slice:

python3 skills/comic-director/scripts/run_comic.py --project examples/<name> --page <PAGE> --panels S01,S02 --dry-run    # zero credit, NO agent: prints bake prompts (the CI-tested slice)
python3 skills/comic-director/scripts/run_comic.py --project examples/<name> --page <PAGE> --panels S01,S02 --finalize   # REAL bake — REQUIRES the agent sidecar SOP (see below)

run_comic.py is a subprocess port of packages/core/spiral_engine.js's movie branch; it starts from an existing comic.json — it cannot start from a fuzzy idea. The deterministic CLI core (validation, blueprint render, the token-diff gates) is what CI exercises, but the --finalize bake is NOT agent-free: each panel bake is fulfilled by the agent-sidecar SOP — the comic-director skill agent watches for the core's *.bakereq.json, calls mcp__codex__codex (with config: {include_image_gen_tool: true, model_reasoning_effort: xhigh}) to fire the native image tool, and writes back *.bakestatus.json. So a real movie bake needs a coding-agent runtime; only --dry-run runs standalone. Model honesty: the bake payload pins model: gpt-5.5 + effort xhigh as a single compatibility default (run_comic.get_bake_plan() — the exact plan the P0 certificate digests; a config-driven override is planned, not yet implemented), while the codex CLI reviewers pin no model — they follow your local codex config, at effort xhigh (--review-effort). Throttling: a rate-limited bake stops cleanly with fresh_run_required — after cooldown launch a fresh run for the remaining panels, do not resume cached state. Caps: ≤4 attempts/panel · ≤6 rollbacks/run · no concurrent bakes (docs/spiral-runtime.md).

Authoring template: copy the Phase-1 author-node shapes from examples/comic_min_author/ when adding a new project. The flow diagram above is the canonical skill chain — the two human gates and the fail-closed gates are shown there; prereqs (codex + gemini + headless Chrome) are in Quick Start.

▶️ See the reference movie — what Workflow 1 produces (zero setup, no API)

python3 cli/validate_wiki.py examples/comic_m3_audit             # verify the shipped trace → PASS (198 nodes, 26 edges)
python3 packages/viewer/build_comic.py examples/comic_m3_audit  # (re)build the single-file viewer from comic.json + panels
open  examples/comic_m3_audit/outputs/index.html

…or just open the hosted one: https://wanshuiyin.github.io/ARIS-Movie-Director/comic/ — all 19 scenes / 24 frames of the cross-model-audited reference run.

🖼️ Workflow 2 · Method figure — /method-figure (a brief → Figure-1)

One slash-command, /method-figure — give it a method_figure_brief.json (the same brief paper-plan emits after its claims_matrix) and it runs the whole audited spiral to a signed-off figure (Step-0 compile → render condition → sidecar bake via Codex's native image-generation tool → Gemini + Codex blind panel + content_diff → retry until clean → Claude structural sign-off):

> /method-figure path/to/method_figure_brief.json

The deterministic core — Step-0 compile, blueprint validation, the condition render, and the content-diff gate — is driven by one command, run_spiral.py. Its zero-credit slices (--p0-only / --dry-run) run with no agent runtime; a real bake — Codex's native image-generation tool (image backend not runtime-attested) — REQUIRES the agent sidecar SOP (the method-figure skill agent services the core's *.bakereq.json by calling mcp__codex__codex with config: {include_image_gen_tool: true, model_reasoning_effort: xhigh}):

# OUR example brief bakes ARIS's own Figure 1 — swap in your own method_figure_brief.json
python3 skills/method-figure/scripts/run_spiral.py \
    skills/method-figure/examples/method_figure/method_figure_brief.json \
    --out-dir figures/method_figure/demo
#  → figures/method_figure/demo/figure.png   (the PANEL-CLEAN candidate, awaiting your structural sign-off)
#     (+ blueprint.json + traceability.json + trace.jsonl of every round)
#  the REAL bake above needs the agent sidecar (mcp__codex__codex servicing .bakereq.json) — NOT agent-free.
#  first run? add --p0-only — that slice IS agent-free (zero image credits: validate + compile + render + lint).
#  NOTE: --dry-run (also agent-free) still writes these files.

(upstream — only if you have a paper; NOT part of /method-figure):
   paper_to_brief.md  →  method_figure_brief.json      agent-authored; claims / numbers copied VERBATIM
        │
        ▼
/method-figure  <method_figure_brief.json | blueprint.json>        the skill = pure render + verify
   run_spiral.py — the deterministic core (starts from a brief):
     compile_brief.py (Step-0) → blueprint.json + traceability.json     every node traces to a brief field — else FAIL-CLOSED
       → validate_blueprint.py → render_condition.py                    labeled condition SVG → PNG
       → agent mcp__codex__codex (workspace-write, config{xhigh}) → native image-gen bake    fail-closed verifier, not a sandbox setting
       → Gemini blind-transcribe ‖ Codex blind-transcribe → content_diff.py     deterministic vetoes
       → RETRY ≤4 (re-assert the locked labels) → Claude STRUCTURAL sign-off
   → figure.png   (+ blueprint.json + traceability.json + trace.jsonl of every round)
   ├──────────────── method-figure · audited render / verify spiral ────────────────┤

Step-0 is deterministic inside the skill — you never hand-write a blueprint or place coordinates; the identity sheet resolves from the brief's identity_refs[].path (no separate --identity); every node is traceability-checked back to a brief field (un-traceable → fail-closed). No model self-acquits — the bake is ratified by Gemini + Codex blind reads + a deterministic content_diff, then a separate Claude structural sign-off. Needs the codex + gemini CLIs + headless Chrome (python3 cli/preflight.py).

Only have a paper, no brief yet? Author the brief FIRST — point your coding agent (e.g. the ARIS main project) at your paper via paper_to_brief.md (claims/numbers verbatim) — then /method-figure it. Power-user: already have a hand-tuned blueprint? run_spiral.py blueprint.json --identity sheet.png --out-dir … --from-blueprint runs the legacy path. The worked 4-round convergence (the exact prompts) is in PROMPTS.md.

🛡️ Why the two gates differ (both correct, by design)

The movie panel_gate is a 3-reviewer panel (narrative — currently the codex CLI ‖ Gemin