Reading DramaClaw's Source: What a Source-Available AIGC Drama Pipeline Actually Ships — and What It Holds Back

Source-available AI projects keep multiplying, but almost nobody clones the whole repo and reads it. The interesting part is rarely what the README says — it's what the README leaves out: which layer was pulled, which headline feature ships switched off, which dependency's weights forbid commercial use.

DramaClaw makes a good specimen. It ships a complete industrialized short-drama production line: manuscript in, finished film out, with character extraction, episode planning, script generation, storyboard frames, voice synthesis and final assembly all in the repo. I've written separately about character consistency and scene consistency in AI short drama; this is the first time I've seen both problems' solutions sitting in one readable repository. As of 9 August 2026 it has 3,428 stars, 297 forks, 19 open and 57 closed issues on GitHub. The repo was created on 27 March 2026, cut its first release on 2 July, and reached v1.3.2 by 7 August — twenty releases in five weeks.

I cloned it and read it. Here's what's actually in there.

1. The size of the thing

Metric	Value (as of 2026-08-09)
Backend Python	~157,000 lines under src/
Frontend TS/TSX	~256,000 lines
Backend tests	232 files / ~77,000 lines
Frontend tests	322 files
Actual authors of the last 50 commits	5 accounts (the README's contributor wall lists 11)
GitHub Discussions	0

A test-to-source ratio near 1:2 is uncommon for an AI application project this young.

The stack is Python 3.11–3.12 + FastAPI + React 19 + TanStack Router/Query + XYFlow + Zustand + PlayCanvas, with uv and pnpm for packages. The story knowledge graph runs on Cognee; the agent framework is pydantic-ai, pinned hard:

# pydantic-ai 2.x removed Agent(output_retries=...) which the scene/prop/asset
# planners and verifiers here still pass.
"pydantic-ai-slim[anthropic,google,openai,openrouter]==1.107.0",

That comment is worth reading twice — it records a real incident: an unbounded >= let two distributions' image builds drift onto different majors and blow up on unexpected keyword argument. Writing the postmortem into the dependency comment is worth more than writing it into an issue.

2. The best idea in the repo: one codebase, two distributions, zero fork

This is the most transferable design here, and the part I'd most want other commercial-open-source teams to copy.

The public repo is the Community Edition. The Enterprise Edition is not in it. But they are not two codebases — they share one engine, with different implementations injected at runtime via Ports & Adapters (hexagonal architecture).

Twelve Protocol ports carry the split: auth, auth_session, project_registry, project_access, audit_sink, credit_quote, usage_meter, provider_instrumentation, task_backend, cancellation_store, lifecycle, product_surface_access.

The startup dispatch is fail-closed — none of the three paths degrades silently:

dsn = os.environ.get("ST_CONTROL_PLANE_DSN", "").strip()
edition = os.environ.get("ST_EDITION", "").strip().lower()
if dsn and edition == "ce":
    raise RuntimeError("a control-plane DSN means EE; declaring CE means no DSN — pick one")
if dsn:
    # load EE adapters from the entry-point group
    missing = [name for name in _EE_REQUIRED_PORTS if name not in _PORTS]
    if missing:
        raise RuntimeError("EE ports incomplete, missing: " + ", ".join(missing))
    ...
if edition == "ce":
    register_local_ports(); ...
raise RuntimeError("no DSN and no explicit CE declaration — refusing to start")

Contradictory config refuses to boot. One missing EE port refuses to boot. Neither flag set refuses to boot. There is no helpful "default to CE" fallback — and that helpful fallback is exactly how this architecture usually fails in production: one missing env var and the service quietly degrades into single-user, no-auth mode.

What makes the split actually hold is the CI gate, not the architecture. An import lint walks the AST of every file under src/, catching static imports, lazy imports, literal strings passed to importlib.import_module(), and every string in pyproject.toml (entry-point metadata counts), confirming the core never references the three commercial module prefixes. The rule file states its own policy:

Hard zero: one hit fails, no baseline retained.

Contrast that with the ruff lint in the same repo, which does allow a legacy baseline of per-file ignores to be paid down gradually. The import lint grants not one exemption. The distinction is deliberate: style debt can be amortized; an architectural boundary cannot. A companion CI script verifies port closure — in CE mode every port must be satisfied by a local implementation, with no external adapter.

All guard exemptions live in a single allowlist file, each requiring an explicit path, guard name and reason — and a test enforces that registering a path that doesn't exist fails the build. That detail says a lot about the team: they knew the exemption list would eventually rot into zombie entries nobody dares delete, so they gave it a health check up front.

My verdict: this is the most thorough open-source/commercial split I've read. Most projects' "open version" is hand-carved out of an internal repo and diverges within months. Here the core exists exactly once, and the commercial edition only supplies implementations plus startup registration.

3. Source-available is not open source — and they enforce that with CI

The repo ships under Elastic License 2.0: free to use, modify and redistribute, with one restriction — you may not provide the software to third parties as a hosted or managed service.

What's unusual is how they police the wording. A lint script scans every git-tracked document and fails the build on the phrase "open source" (case-insensitive, hyphen and underscore variants included, plus the Chinese equivalent). The docstring is blunt:

Elastic License v2 means source-available. It is not open source. Public-facing text must not call this project open source, to avoid confusion with the OSI definition.

Three exemptions only: the license explainer itself (which needs to say "this is not open source"), the vendored third-party license compilation, and the standard DCO legal text — the latter two contain the phrase in upstream text that cannot be edited and is not the project describing itself.

I've never seen brand wording enforced as a CI gate before. It solves a real problem: on a project shipping twenty releases in five weeks with multiple contributors, relying on code review to catch "don't write open source" will leak. But it also exposes the awkwardness of this license class — you have to spend continuous effort stopping people, including your own team, from assuming it's open source.

4. What was pulled from the public edition

This is the part you cannot get from the README.

4.1 The flagship assistant ships hidden

The README lists the "director agent" among core capabilities, with a screenshot. But product-surface visibility defaults are hardcoded in the port contract:

{"surface_code": "mainline",           "default_available": True},
{"surface_code": "freezone",           "default_available": True},
{"surface_code": "assistant",          "default_available": False},   # ← the AI assistant
{"surface_code": "freezone_assistant", "default_available": False},   # ← assistant on the canvas

The CE implementation returns those defaults verbatim, with no environment variable to flip them; the app shell, the project navigation and the canvas shell all gate their entry points on this endpoint. The public edition ships a hidden entry — turning it on means editing code and rebuilding.

To be precise: this is entry-point visibility, not an API block. The assistant's chat route itself passes in CE, because the quota checker is a no-op there. But to a self-hosting user who doesn't read source, the feature simply does not exist.

4.2 Twenty-two model aliases that only resolve on the vendor gateway

The example env file defines 83 variables, of which 22 are DC-* model aliases: content rewriting, identity planning, scene building, storyboard prompt composition, style analysis, screenplay normalization — a dedicated alias per stage.

Those aliases only map on the official gateway. The README says the project is model-neutral, which is true — any OpenAI-compatible endpoint works. But being model-neutral out of the box is a different claim: a bring-your-own-gateway user must map 22 roles onto real models by hand. There's a 272-line configuration doc for it, and it is still real friction.

The code corroborates this. The catalog of selectable image/video models now ships from object storage, with an optional local auto-update poller (off by default). And BYO test coverage is visibly thinner — one open issue reports first/last-frame video generation coming out wrong specifically on a self-configured channel.

4.3 Single machine, single user, no login

CE is fixed to one local user, and the auth port implementation unconditionally returns an owner-role local user. The architecture doc states this plainly ("Local single user, no login"), so nothing is hidden. But spell out the implication: exposing the web port to the internet means anyone can spend your gateway key.

Likewise, multi-user collaboration, distributed task scheduling, metering and billing all live in EE. The README's capability matrix puts a ✅ next to "team production (sharing, roles, tasks, cost)" — that's the product's capability, not the public edition's.

5. The "3D virtual set" is much less 3D than it sounds

This was the most counterintuitive finding in the whole repo.

The project headlines a "director world": a 3D Gaussian Splatting virtual set that locks spatial structure, character blocking and camera placement so a location stays consistent across shots. It sounds like a realtime 3D pipeline bolted into an AI video tool.

Here's what it actually is:

Three facts worth stating outright:

First, the 3D layer's only contribution to the finished film is one control screenshot. The user flies a camera in the browser, places figure and prop blocks, picks an aspect ratio, and screenshots. That screenshot is fed to an image model as a reference to redraw into the real storyboard frame — and downstream stages consume only the redrawn frame. A file header states it directly: downstream consumes the sketch, never the raw 3D screenshot. More tellingly, the prompt explicitly instructs the model to discard the screenshot's style, texture, noise and game-engine look. It locks where the camera is and who stands where on screen. Nothing else survives.

Second, the much-referenced "spatial contract" contains no 3D at all. It's JSON produced by a single VLM call. Its own schema version string says topology_only, and it explicitly forbids emitting bounding boxes or source-image coordinates — the downstream guide is coordinate-free. It constrains only which fixtures belong at which bearing on a 360° panorama. Not the camera, not the blocking, not the lighting. Zero GPU, zero model weights.

Three engineering details here deserve their own mention, because they model the right way to not trust an LLM's first output:

1. Deterministic post-processing overrides the LLM. The raw JSON gets rewritten by code: anchors that overlap analysis marked as shared are deleted from the front and back walls and moved into the side walls; direction-exclusion locks ("the bookshelf may only appear on the back wall, never the front wall or the seams") are generated entirely by code from object-type and size whitelists. The LLM doesn't get a vote.
2. The contract is a derived artifact that can expire, not a permanent fact. If the contract file's mtime predates the reference images, it's discarded. Schema version mismatch, also discarded.
3. The injected prompt header is synthesized deterministically by code, not written by the model — so its wording cannot drift between runs.

Third, the production default path doesn't run the famous 3D reconstruction network at all. The default geometry mode is panorama-plus-depth, using one Apache-2.0 panoramic depth model. The big-lab 3D reconstruction library is imported only for two pure-code utilities (a point-cloud data structure and PLY serialization); the weight-downloading constructor is called only in a non-default branch. That distinction has enormous legal consequences — see the next section.

Finally: the whole thing is an optional enhancement, not a requirement. The flag in the main storyboard runner defaults to off, the official docs label it optional, and a frontend contract test hardcodes the word "optional" into its title. With it off, shot backgrounds come from cropping the panorama. So the 3D layer's genuinely unique increment is just two things: arbitrary camera positions (instead of a few fixed crop anchors), and true three-dimensional occlusion between characters and props.

6. The post-generation verification loop: keeping the checker cheaper than the generator

This is the other transferable block, especially for anyone building "AI generates, then something checks it."

Start with a structural fact that's easy to misread: the verification code is not on the generation path. That ~7,700-line verification package has exactly two external importers in the entire backend; the generation runners don't import it at all. It's a side channel triggered by CLI and by user button clicks, and the gate sits at the promotion step — candidate artifact to official artifact — not at generation. Failure semantics are "don't promote, keep the old artifact, and log it." No auto-retry, no auto-repair.

6.1 The failure-mode registry: one definition, three consumers

The heart of the system is a table of failure modes. Note the granularity: it registers recurring defect classes, not failure instances. Each entry has seven fields, three of which feed three completely different consumers:

Field	Consumer	Role
detection	the visual gate	rendered into "does this image show X?"
negative_prompt_clause	the generation prompt	assembled into a negative-constraint block injected into the next generation
correction_template	repair instructions	teaches the repairer how to phrase an edit instruction
gate_enabled	the cost switch	decides whether this defect is worth a model call at all

The second row is the interesting one: an observed failure becomes a registered mode, which automatically enters the prompt of every subsequent generation. That's a prevention loop, not a same-round repair loop. And gate_enabled separates "worth paying to ask" from "prevention only" — of the ten seeded modes, only five participate in gate questioning.

Storage is split: definitions live in a cross-project shared store, hit counts in a per-project one. That split is correct — definitions are shared knowledge, counts are project facts.

6.2 Cost control: seven levers stacked

"Every verification is a model call" is where systems like this run away. Their answer is cascade pruning plus a pile of unglamorous measures:

Beyond the cascade: ask about every registered defect in a single call (not one call per defect); collage the candidate and its references into one image; review a whole episode by tiling every frame into one numbered grid, one call per episode; compress context images to quality 35 and a 512px long edge; small model, temperature 0, output capped at 512 tokens.

One more judgement worth calling out: when no reference image exists, the checks that depend on one are automatically dropped. No baseline, no question — considerably more honest than asking anyway and getting a fabricated verdict.

6.3 One tradeoff I disagree with

The gate treats an unsure verdict as a pass; only an explicit yes counts as a hit. The file header says this conservatism is deliberate.

I think it's wrong, or at least pointed the wrong way. The entire reason this system exists is the "generated, therefore fine" failure mode — and ruling "the model couldn't tell" as a pass lets things through precisely when human attention is most warranted. Unverified and verified are two different states, and folding the first into the second manufactures false positives in the report. Users discover that before the system does.

The more conservative design keeps uncertainty as a distinct third state and hands the decision to the caller, rather than making it inside the gate.

6.4 The data flywheel that only writes

There's a complete replay-capture and training database: one row per beat per attempt, carrying three version hashes (registry, prompt, format) plus content-addressed storage of the prompt text and response — so several beats in one batch naturally share a single prompt blob and dedupe for free. Candidates the gate rejected go into a reject buffer that comments describe as negative-sample mining.

None of the three version hashes may be hand-entered: the registry hash is the canonicalized JSON of the definitions, and the prompt version hashes the bytes actually sent, not the template. That distinction matters — same template, different variables, different experiment.

But state it honestly: there is no training or fine-tuning consumer anywhere in the code. The flywheel writes and never reads; it's staged for "compare a new strategy against this once there's more data in a few months." The convergence log's own comment describes the controller as "upcoming" — meaning the automatic convergence loop is not implemented, and today's stopping condition is a human reading a trend table.

7. Three licensing landmines

If you plan to lift any of this for commercial use, this section matters more than everything above. I pulled each upstream license text.

Component	Code license	Weights license	Commercial hosted service
The project itself	Elastic License 2.0	—	⛔ explicitly forbids providing it to third parties as a hosted or managed service
Panoramic depth model (the one actually used by default)	Apache-2.0	Apache-2.0	✅ clear
Big-lab 3D reconstruction library	commercial use allowed, but zero patent grant	⛔ research purposes only; explicitly excludes commercial exploitation, product development, or use in any commercial product or service — model derivatives including fine-tunes are equally locked, and the license is revocable	⛔
PLY point-cloud serializer	GPL-3.0-or-later	—	⚠️ pure SaaS doesn't trigger copyleft; distributing an image or installer does

Three takeaways:

1. Weight licenses and code licenses are separate, and they frequently point in opposite directions. That 3D library's code permits commercial use while its weights forbid it, the "model derivatives" clause sweeps in fine-tunes, and the grant is revocable. Worse, the weights auto-download on first run — "we didn't bundle them" is not a defense.
2. Within one model family, different sizes can carry entirely different licenses. I hit a textbook case while checking: a widely used depth model's Small variant is Apache-2.0 while its Large variant is CC-BY-NC-4.0. Judging a license by family name will burn you.
3. A GPL dependency doesn't trigger under pure SaaS, but does the moment you distribute a container image. This one is easy to miss, because the "we're a SaaS" assessment expires on the day the team starts publishing Docker images.

Worth noting: this project's own default geometry path doesn't need the non-commercial weights. Anyone wanting to rebuild the pipeline can route around them entirely — which reads less like coincidence and more like the team ran the same check.

8. Code quality: clean boundaries, messy interiors

Having praised a lot, here's the other side.

File	Lines
Free-canvas API routes	13,060
Grid image generator (the nine-panel storyboard approach)	7,552
Main generation routes	6,189
Frontend settings dialog	5,852
Frontend canvas component	5,080

Thirty-three backend files exceed 1,000 lines. A 13,000-line HTTP route file means that entire domain was never separated from the transport layer — a jarring contrast with the fastidiousness on display in the ports layer.

My reading: this is the price of twenty releases in five weeks, and a deliberate one. Architectural boundaries — ports, CI gates, license compliance — are irreversible and brutally expensive to fix later. Bloat inside a module is reversible; it can be split any time. They spent their discipline on the irreversible half. I think that priority is correct, even though the 13,000-line file will eventually come due.

Two more observations:

• Comment language. Roughly 1,600 of ~2,600 backend comments are in Chinese. Fine for the target market; a real barrier to international contributors.
• Documentation depth. Chinese and English docs together run about 2,170 lines — thin for a 400,000-line product. The actual product manual is an external link, in Chinese only. The Discussions board the README links to has zero threads.

9. Scores

Dimension	Score	Reasoning
Architectural boundary design	9/10	Port injection + fail-closed startup + zero-exemption import lint; a textbook split
Compliance infrastructure	9/10	SBOM, license inventory, secret scanning, DCO, REUSE — far beyond its peer group
Vertical domain depth	8/10	Episode beats, identity consistency and spatial contracts are real know-how, not a generic workflow reskin
Verification loop design	7/10	Cascade pruning and the failure registry are solid; treating unsure as pass is wrong, and the convergence controller is unimplemented
Module-level code quality	4/10	A 13,000-line route file; 33 files over 1,000 lines
Completeness of the public edition	5/10	Flagship assistant hidden by default, 22 aliases bound to the vendor gateway, single-user with no auth
Documentation	5/10	2,170 lines can't carry 400,000 lines of code; the main manual is external and monolingual
Runtime reliability	5/10	Open issues include timeouts causing duplicate generation and duplicate billing, lost results, and media vanishing after restart

Conclusion

Read it for its boundaries, not its interiors.

If you're building commercial open source, sections 2 and 3 are worth lifting wholesale as a pattern: port protocols, runtime injection, fail-closed startup, a zero-exemption import lint, and an exemption list with its own rot-detection test. That combination turns "community and commercial never fork" from a slogan into a constraint CI will stop you at. Most teams stop at "separated in the architecture" — and an architectural separation with no gate will be punched through by one rushed import inside six months.

If you're building anything that generates with AI, section 6's cost model has more immediate value than the architecture: zero-call deterministic pre-filtering → cheap-model fact checking → scoring → a head-to-head comparison only when the scores are too close, plus "ask every defect in one call" and "collage instead of multiple images." The essence isn't any single trick — it's accepting that verification has a cost and budgeting for it. Too many teams optimize the generation side to the token while letting verification call the most expensive model available to answer a yes/no question.

As for the product itself — don't treat it as a base you can commercialize. The Elastic License 2.0 hosted-service restriction alone rules out most commercial scenarios, and the missing collaboration layer, the hidden assistant, and the gateway-bound aliases together describe a positioning of "open funnel, gateway rake, enterprise license" — not "take this and sell it."

One closing observation, non-technical but worth recording: this project earned 3,400 stars and 297 forks in five weeks without a single technical breakthrough — every piece of it has an equivalent somewhere on the 2026 AI video generation tooling map. What it captured was the right to define what "AI short-drama pipeline" means. In a category with no settled answer yet, the first team to put the entire chain on the table gets to write everyone else's vocabulary.

References

1. DramaClaw — GitHub repository (figures in this article as of 2026-08-09: 3,428 stars / 297 forks / 19 open / 57 closed issues)
2. DramaClaw — English documentation
3. DramaClaw — Installation guide
4. DramaClaw — Official site
5. Elastic — Elastic License 2.0 full text
6. Open Source Initiative — The Open Source Definition (the benchmark for "source-available ≠ open source")
7. Linux Foundation — Developer Certificate of Origin 1.1
8. FSFE — REUSE Specification (the license-metadata standard the repo adopts)