BranchArchitectAI

Interactive screenplay analysis using multi-agent: branch story graph, continuity flags, and budget optimization.

Comment

Project Overview

BranchArchitect AI is an interactive screenplay analysis platform. Upload a script, then our multi-agent system analyzes the entire story graph, catches plot contradictions and production cost overruns, and surfaces fixes you approve with one click. It's a co-pilot for screenwriters and producers building interactive films and game narratives.

Interactive narratives are exponentially harder to produce than linear films. Black Mirror: Bandersnatch (https://youtu.be/zBsh7Byu044?si=Bx2Qvr1zdSjoOVkT) is a prime example - one interactive film with multiple branching paths and narrative outcomes. Each viewer choice creates a new branch. Each branch has its own logic, characters, and continuity requirements. One subtle mistake in one branch breaks the entire story downstream.

BranchArchitect treats the entire story as a unified graph. Our multi-agent system catches what humans miss, not through prompting, but through tool-driven analysis grounded in real data. Once you upload screenplay with budget information, our agents identify contradictions, surface cost savings, and visualize the story graph. You review each issue and watch the graph update in real-time depending on your choices (No auto-fixes - just agentic reasoning giving you the information you need to decide)

Agent Architecture

Three specialist agents work under one supervisor, the Root Agent, and each reports back to it when done rather than handing off to each other, so one place always decides what runs next.

  • Root Agent. Routes the work. A fresh upload gets the full pipeline: parse, then audit, then check the budget. A targeted question like "just check the budget" goes straight to the specialist that can answer it.
  • Parser Agent. Reads uploaded PDFs and pulls out scenes, choices, locations, and cost limits as structured data. It's the only agent that writes the graph's first version, and when something is genuinely ambiguous, like a location the budget prices two ways, it stops and asks instead of guessing.
  • Graph Auditor Agent. Has read & write access to the story graph. It finds dead ends, choices that lead nowhere, and scenes nobody can reach, and records each as a suggestion, a finding plus up to three fix options, instead of losing it at the end of a chat turn. It also owns the graph's history: listing what changed on a scene and rolling one back once a person confirms.
  • Budget Agent. Has read only access to costs and story graph. It works out what the production actually costs, meaning every location that gets used, counted once, since a film shoots every branch even though a viewer only walks one. It drafts savings ideas and checks each one with the Auditor first (without giving up its own turn) to make sure its proposed suggestions do not break the story’s logic.

Approving a fix is a plain backend write, not another agent turn, since the agents already decided what the fix should be during their audit turns and a simple function applies it. Approving one can invalidate another suggestion touching the same scene, which then locks until the analysis runs again.

Features in Action

  • Interactive Story Graph. A visual map of the branching structure, built with React Flow. Click a scene for its location and characters, or a location to see every scene shot there light up.
  • Suggestions panel. Every finding lands here with its fix options: approve, dismiss, or take it on yourself. A fix option built against an older version of the story (a stale option) shows up locked and struck through, so it can't be applied once the story has moved past it.
  • History and rollback, in chat. Ask to see a scene's versions for a plain language list of what changed and when. Ask for a rollback and the agent reaches for a real write tool that still can't fire without your confirmation, and the old version is written forward as a new one, so even a rollback can be undone.

Partner tool: ClickHouse

  • We picked ClickHouse because the problem itself is a version history problem. A story graph is state that keeps replacing itself, scene by scene, while every prior version still needs to stay around for rollback. Most databases make you do that with extra tables and application code. ClickHouse can do it natively, so the schema leans on that instead of working around it.
  • Reads and writes are kept apart from the start. The two read only specialists connect through the official mcp-clickhouse server with write access turned off, since that flag is all or nothing and would let any agent holding it run arbitrary inserts or deletes. Every real write instead goes through a small set of narrow tools, each accepting one shape of data and touching one table.
  • The story graph itself splits across two kinds of table, since "what does it look like now" and "what has ever happened to it" are genuinely different jobs. Current state lives in script_nodes and script_edges on ClickHouse's ReplacingMergeTree engine, which keeps only the newest version of each row and is read with FINAL, since old versions are only cleaned up in the background. Full history lives in separate, append only log tables where nothing is ever erased, which is what actually powers the version list and rollback.
  • A materialized view is what connects the two. Every write inserts one row into the log tables, and ClickHouse copies it into the current state table in that same insert, so every write in the app, including the first time a script is parsed, runs through this single path. That includes deletes: cutting a location just adds a row marking it removed, rather than a real delete rewriting data that can't be undone.
  • The suggestions table follows the same pattern, and each fix option remembers which version of the story it was built against. The instant someone approves it, the system checks that version against the live graph and refuses the write if anything moved, and that check, made at the moment of approval, is the real safety net.

Tech Stack

  • Agents: Google Agent Development Kit (ADK), Gemini 2.5 Flash and 3.7 Flash
  • Tools and connections: MCP-ClickHouse
  • Backend: FastAPI, server-sent event streaming
  • Frontend: React, TanStack Start, React Flow, Tailwind, Radix
  • Database: ClickHouse Cloud

Learnings

  • Agents work best as advisors. The more we thought about it, auto-applying fixes felt wrong. Why would you replace human judgment on a creative project? Agents should surface options and contradictions and producers decide what to do.
  • Graph visualization is everything. Early designs were table-heavy. It's so much easier to understand your story when you can see it.
  • Branching complexity is a system problem. Traditional screenwriting tools don't understand that you're building one coherent story with branches, not separate stories. Thinking of the entire graph as unified, not isolated branches, is how you catch real contradictions.
  • The stale lock feature was a key insight. Once you approve a fix and the graph changes, old suggestions become meaningless. Striking them out instead of letting them hang around was a small but important detail for not confusing producers.

Next Steps

  • In chat edits. Every graph change today starts as a structured finding from one of the two specialists. A free form request typed into chat, like "move scene 4 to the diner instead," has no path to a suggestion card yet.
  • Support for more than one project. The system tracks one production at a time, by design, to keep the first version simple. Supporting more means a project identifier on every table and a real switcher instead of today's single reset button.
  • Evaluations. There's no real evaluations dataset yet. The next one should check whether the supervisor routes a targeted question to just the right specialist, and whether the Parser Agent asks a clarifying question only when genuinely needed with ADK's evaluation tooling.

Built With

Share this project:

Updates

Submission history