I Made an AI Film Pipeline. Now It's Open Source.
github.com/ghassan-ai-projects/film-pipeline-langgraph — Python, LangGraph, MCP, MIT licensed.
The first version of this pipeline was oversold by the easiest person to fool: me.
The failures that followed had names. Content moderation walls. A 7x cost-estimation mistake. An API key that died four shots before the end of a sequential chain. Validation loops that let agents approve their own work. A provider abstraction copied between film folders because it was useful before it was disciplined.
I wrote the postmortem in June. This is the follow-up.
The rebuild is now a public repository: a LangGraph-based film production pipeline that takes an idea through structured pre-production, generation planning, QC evidence, and a validated handoff state.
It does not claim to generate a finished film by itself. That boundary is important. The repository is machinery for making the work inspectable: approved artifacts, human gates, provider routing, cost approval, checkpoints, rollback, audit events, and validation reports.
idea -> approved artifacts -> generation planning -> QC-ready project stateFinal editorial finishing, sound, color, and delivery export still belong to a human production pipeline. The repo makes that boundary visible instead of hiding it behind a demo video.
The Rebuild Was the Product
The postmortem described a provider layer called scripts/film/providers.py. It helped the first two films move, but it lived outside proper repository discipline and accumulated scar tissue with every production failure.
The rebuild turned that fragile operating knowledge into a package with a narrow contract:
- LangGraph supervisor graph with one phase per production stage
- Typed
StudioGraphStateinstead of dict-shaped plumbing - Real human gates using LangGraph
interrupt()and resume commands - Versioned artifacts, checkpoints, rollback, and audit visibility
- A terminal UI, a headless CLI, and an MCP server over the same core state
The current package metadata is deliberately boring: Python 3.12+, Python 3.13 classifier, MIT license, uv-based setup, and command-line entry points for both the runner and the TUI. That matters because the first pipeline failed in exactly the places where prototypes usually stay vague.
What the Pipeline Actually Does
The graph has eleven phases. They are not marketing stages. They are the operating procedure the postmortem forced into code.
| Phase | What the phase produces |
|---|---|
intake |
Idea analysis, classification, constraints, and approval decision |
constitution |
Film constitution: theme, tone, visual language, and guardrails |
development |
Logline, treatment, structure, character and world development |
script |
Scene-by-scene screenplay artifacts |
visual_dev |
Character, environment, style, and reference development |
shot_bible |
Shot-by-shot planning, continuity, prompt material, and camera language |
gen_planning |
Generation batches, spend approval, provider routing, and risk review |
generation |
Provider-backed image and video generation lifecycle state |
qc |
Validator reports, issues, repair feedback, and readiness evidence |
post |
Assembly, transition, audio, subtitle, and delivery plans |
delivery |
Packaging and handoff state, not a claim of complete in-repo finishing |
Every phase writes structured artifacts. Every gate creates a record. The state object uses append-only reducers for artifact references, issues, and validation report references, so the graph remains inspectable as it moves.
That is the practical difference between a film script with helper files and a production pipeline. You can ask what was approved, what was built from what, why a phase is blocked, which provider is unhealthy, what a validation report found, and where rollback would land.
The Architecture Answers Real Failures
The repository documents an eight-part architecture optimization. Each item maps to a failure mode from the earlier pipeline.
| # | Mechanism | Failure it answers |
|---|---|---|
| 0 | Agent profile routing, quality instructions, retry wrapper | Generic prompts producing generic film artifacts |
| 1 | Real human gates via interrupt() and MemorySaver |
Approval workarounds and agents approving their own output |
| 2 | Typed StudioGraphState and partial-update nodes |
Mutable dict state and defensive copying everywhere |
| 3 | Auto-increment artifact versions with built_from tracking |
Repairs overwriting the artifact they were meant to fix |
| 4 | Living Master Film Matrix through versioned patches | A matrix frozen at the moment it was written |
| 5 | Structured RepairFeedback |
Unstructured "fix it" loops that never converged |
| 6 | Per-phase scoped context packets | Agents drowning in all artifacts at once |
| 7 | QC subgraph with LangGraph Send fan-out |
Validation as a serial bottleneck |
| 8 | Sampling controls such as top_p and frequency_penalty |
Creative agents repeating themselves |
Two fixes matter most.
Human gates are real now. The graph interrupts after a phase and waits for an operator decision. Approve moves forward. Request revision cycles back into the phase. Repair sends the system into a targeted correction flow. The old failure was pretending a validator could be an authority over its own output. The new contract makes authority explicit.
The film matrix is living now. The original matrix was useful until the next phase changed the project. Downstream phases now emit versioned patches that update individual rows. Continuity state becomes something the pipeline maintains, not a PDF everyone forgets to edit.
The small fix I appreciate most is less dramatic: stalled phases now expose an explicit escalate action instead of looping repair to approval forever. Infinite loops are rarely model problems. They are usually missing state-machine exits.
Three Interfaces, One State
The same core is reachable three ways.
The TUI runs with uv run film-pipeline-tui. It opens a terminal studio with a project gallery, a phase rail, content tabs for scenes, artifacts, assets, and issues, and a reader for screenplay-style review. The important shortcuts are simple: approve, request revision, validate, generate, refresh, and inspect.
The headless CLI runs with uv run film-pipeline-run my-idea.txt. In mock mode it can move through the pipeline without provider keys. Real-provider mode requires explicit confirmation because Seedance through OpenRouter and Veo or Imagen through Google can spend real money.
The MCP server exposes project creation, intake, phase review, approval, artifacts, shots, validation reports, generation planning, spend approval, provider health, checkpoints, rollback, audit logs, and knowledge-base search. That makes the pipeline usable by another agent without giving that agent a private path around the rules.
Different operators need different surfaces. A human reviewing a script wants a reader. A batch run wants a non-interactive command. An orchestrator agent wants typed tools. They should all operate on the same project state.
Verification Is Part of the Contract
The repository does not treat testing as a cleanup task after the interesting work. The development contract is visible in the project itself:
make ci-checkruns format checking, Ruff lint, mypy strict, pytest with coverage, package build, and the working-product gate.- Pytest is configured with
--cov-fail-under=90and branch coverage. - The package builds as an installable Python project instead of a folder of scripts.
- Mock mode exists so operators can test the machinery without provider keys or generation spend.
I am being careful with the wording here. The draft article I started from claimed a precise local green test count, but the coverage artifact available on this machine was partial and not a trustworthy snapshot of a full CI run. The stronger claim is the one encoded in the repository: the release contract requires the 90% coverage gate and the working-product gate before the project is considered done.
That distinction matters. This pipeline can spend real money in real-provider mode. A regression in a shot bible, cost approval, or provider routing path is not just a red CI job. It can waste hours of generation time and produce assets that cannot be chained.
What It Does Not Solve
Open-sourcing the pipeline does not make filmmaking easy.
It will not fix a weak idea. Intake can surface contradictions, but it cannot make a premise compelling.
It does not remove humans from the loop. Creative phase gates are human gates on purpose. If the goal is an autonomous film factory where the system approves itself, this is the wrong repository.
Mock mode verifies the machinery, not model quality. Real generation quality still depends on providers, prompts, references, and taste. The pipeline makes those dependencies visible; it does not erase them.
Post-production is planned, not fully executed inside the repository. The system can produce assembly, transition, audio, subtitle, and delivery plans. Actual finishing remains outside the current product target.
The project is young. The package is versioned as 0.2.0, artifact schemas may change, and some surfaces are intentionally stubbed while the core contract matures.
I am stating those limits because agent infrastructure is easy to oversell. The first version failed partly because the boundary between "useful automation" and "finished production system" was too blurry. The rebuild is better because the boundary is explicit.
Why I Open-Sourced It
The interesting part is not that two film projects used earlier versions of this machinery. The interesting part is the architecture that survived the failures: typed graph state, interrupt-based approvals, versioned artifacts, scoped context, a living continuity matrix, cost-aware generation planning, parallel QC, and an MCP surface other agents can inspect.
Those mechanisms get better when other engineers can read them, run them, break them, and argue with them.
The failures that shaped this pipeline are not unique to film. Moderation walls, bad cost models, expired keys, missing checkpoints, self-approving validators, and unbounded repair loops show up in agent infrastructure under different names.
I wrote the postmortem because the failures were worth documenting.
I open-sourced the code because the fixes are worth inspecting.
Want to inspect the pipeline boundary and MCP surface?
Open the Repository