CinePilot

Inspiration

Continuity errors are easy to miss in a screenplay. A prop can disappear between scenes, a character detail can contradict itself much later, or an important story element can be introduced and never resolved. Script supervisors catch many of these problems manually, but tracking hundreds of details across an entire script is difficult.

What it does

CinePilot is an AI script supervisor that turns a screenplay into structured story intelligence.

Upload a screenplay PDF and it:

• Extracts scenes, characters, props, locations, and other story details into a structured Story Bible
• Tracks entities across scenes to identify continuity inconsistencies
• Checks for prop, character detail, timeline, and plot thread issues
• Turns each finding into a plain-English Flag that explains what was established, where it changes, and the scenes involved
• Lets you ask natural-language questions about the screenplay and get grounded answers with scene references
• Uses ClickHouse as the underlying production data layer so the extracted story information can be queried throughout the application

How we built it

• Extraction: Google ADK and Gemini through Vertex AI power a two-stage extraction pipeline. An Entity Registry Agent builds a canonical, alias-aware registry of characters, props, and locations. A Script Reader Agent then extracts scenes against those canonical entities. Scanned PDFs are handled through OCR with Tesseract and pdf2image.
• Continuity checking: Deterministic rules handle structured continuity checks such as prop and timeline contradictions. Plot thread detection uses a two-stage approach where deterministic filtering identifies candidates before an LLM confirms whether there is enough explicit evidence to flag the thread.
• Data layer: ClickHouse Cloud stores scenes, characters, props, appearances, and continuity issues. The chat agent queries this live through the official mcp-clickhouse MCP server. Project-scoped access is enforced independently of the SQL generated by the LLM.
• Narrative findings: Each issue type has a deterministic formatter that converts structured facts into consistent, readable findings. This keeps every claim traceable to the underlying screenplay data.
• Frontend: Next.js App Router, TypeScript, and Tailwind power the application interface and persistent project-scoped chat experience.
• Backend: FastAPI handles the application API and authentication. The backend is deployed on Cloud Run with credentials managed through Secret Manager, while the frontend is deployed on Vercel.

Challenges we ran into

• Screenplay extraction is messy. Character names can change as identities are revealed, and the same prop can be described differently across scenes. We built alias-aware entity matching to keep references connected.
• Early plot thread detection produced too many false positives. We redesigned it so deterministic filtering happens before an LLM is called, and a thread is only flagged when the model can identify an explicit setup and supporting evidence.
• Connecting an LLM to ClickHouse safely required more than asking the model to filter by project. We added an enforcement layer that keeps queries project-scoped regardless of what SQL the agent generates.

Accomplishments that we're proud of

• Built a working end-to-end pipeline from screenplay upload to extraction, continuity checking, findings, and grounded chat.
• Built the system around a simple principle: AI extracts the story, rules verify it.
• Made continuity findings explainable by showing what was established, where it changed, and which scenes provide the evidence.
• Integrated real screenplay data with ClickHouse rather than relying on mocked production data.
• Built and deployed the project independently, including the Google Cloud and ClickHouse infrastructure.

What we learned

• LLM extraction becomes much more reliable when it is constrained by schemas, canonical entity registries, alias resolution, and deterministic validation.
• Not every problem should be solved with an LLM. Deterministic rules are better for structured continuity checks, while LLMs are useful when interpretation is actually required.
• Separating structured data from narrative presentation made the system easier to debug and made every finding easier to trace back to its source.
• A useful AI system is not just about generating answers. It also needs to make those answers verifiable.

What's next for CinePilot

• Test the complete pipeline on a full 130+ page screenplay
• Expand the Story Bible with a dedicated Timeline and Events view
• Add multi-project support
• Add richer collaboration and review workflows

Built With

• clickhouse
• fastapi
• gemini
• google-adk
• mcp-clickhouse
• next.js
• python
• react
• tailwind-css
• typescript
• vertex-ai