ClearCut

Clear the script before it becomes a production problem.

Comment

Inspiration

A screenplay can hide a production problem in a single line: a song playing on a radio, a recognizable product on a desk, or a character whose name matches a real person. For an independent production, identifying those concerns and keeping track of the research can become a job of its own.

The workflow is fragmented. The script lives in one tool, research in browser tabs, evidence in spreadsheets, and review decisions in email. Then the screenplay changes, and the team has to work out which findings still apply.

I built ClearCut around a question: what if the passage, its evidence, and the human decision stayed connected—even as the script changed?

What it does

ClearCut is an open-source screenplay pre-clearance evidence workspace for independent filmmakers, screenwriters, and clearance teams.

It connects the workflow from the first screenplay import to a reproducible review report:

  • Find potential concerns. Gemini identifies items across ten review categories, including real people, brands, copyrighted works, music, locations, and contact information.
  • Research them with current sources. Parallel Search discovers attributable evidence, while bounded Extract retrieves additional context from selected sources. Evidence retains its source URL, retrieval time, excerpt, and provenance. An item with no supporting evidence stays unresolved.
  • Review evidence beside the screenplay. Highlighted passages connect directly to evidence cards, conflicting sources, assignments, and review actions.
  • Keep people accountable. Authorized team members assess evidence, propose and review rewrites, refer concerns, and record decisions with an audit trail. A proposer cannot approve their own rewrite.
  • Recheck what changed. ClearCut distinguishes unchanged, moved, modified, added, and removed passages. After an authorized person starts a selective rescan, fresh research focuses on changed material while earlier evidence and decisions remain traceable.
  • Produce a reproducible report. Reports bind to a specific screenplay version, with separate human actions for generation and release.

Scheduled source re-checking uses the same research and evidence-admission path.

ClearCut supports research and qualified human review. It does not provide legal advice or guarantee clearance.

How I built it

I built ClearCut as a solo developer with assistance from an AI coding agent.

I separated contextual AI tasks from deterministic application rules. Models identify candidates, plan research, and evaluate evidence; application code controls permissions, evidence admission, version relationships, job execution, and accountable decisions.

Three distinct Gemini roles on Vertex AI

I configured separate models for different responsibilities:

Role Model Responsibility
Screenplay detection gemini-3.8-flash Identify potential clearance concerns in screenplay passages.
Research planning gemini-3.5-flash-lite Turn a candidate concern into a bounded research plan.
Evaluation judge gemini-3.1-pro-preview Evaluate evidence against the configured review criteria while preserving uncertainty.

The integration uses Google's Gen AI SDK with Vertex AI. Vertex AI Model Garden supports model availability checks during configuration.

ClearCut records the requested model and the model identity returned by the provider when available, preserving a traceable record of how AI-generated results were produced. Model evaluation informs review; final decisions remain with authorized people.

Parallel as the evidence layer

Parallel is central to ClearCut: model knowledge alone cannot establish a current, attributable source record.

Parallel Search provides the source-discovery path through which evidence claims are admitted. Bounded Extract adds depth from selected sources without creating an independent route around those provenance requirements.

A successful request does not automatically mean useful evidence. Empty, irrelevant, weak, or conflicting results remain visible for review. Scheduled re-checking follows the same path. The Parallel Monitor event-stream adapter is implemented but remains disabled and is not part of the demonstrated workflow.

One application, with explicit Google Cloud responsibilities

I designed the deployment architecture to give each service a concrete role:

  • Cloud Run: one public service hosts the entire application. A separate migration job uses the identical application image digest.
  • Artifact Registry: stores the single immutable clearcut image promoted through build, migration, and deployment.
  • Cloud Storage: provides durable storage for screenplay imports and report artifacts.
  • Cloud Tasks: dispatches detection, research, and rescan jobs through OIDC-authenticated internal delivery.
  • Secret Manager: resolves provider credentials at runtime.
  • PostgreSQL, with Cloud SQL as the managed deployment option: stores application state, with evidence decisions and their authoritative audit events committed atomically.

Product and delivery stack

The backend uses Python, FastAPI, SQLAlchemy, and Alembic. Versioned migrations run separately; the application never migrates its database at startup.

The workspace uses React and TanStack, while Astro serves the public site. I drew the interface's visual language from screenplay pages, revision colors, annotations, and production paperwork.

pypdf supports a deterministic PDF import pipeline, helping keep screenplay elements and subsequent diffs stable for the same input and parser version.

A contract-first OpenAPI specification generates TypeScript and Python clients. Contract checks help keep the interface, API, and consumers aligned.

Docker packages the application into one image for local, portable-server, and Cloud Run configurations. GitHub Actions binds build, migration, deployment, and promotion evidence to that image digest. Terraform defines the infrastructure, and Playwright verifies browser behavior across desktop, tablet, and mobile configurations.

Challenges I ran into

The hardest challenge was preserving meaning across revisions. Moving a passage should not trigger unnecessary research, but changing its meaning should. I built conservative passage matching and explicit lineage so uncertainty in a match never silently becomes reused evidence.

Another challenge was distinguishing evidence from confidence. A successful search can return weak, contradictory, or irrelevant material. ClearCut needs to preserve those limitations rather than turn every completed request into a reassuring answer.

Testing against PostgreSQL also exposed migration failures that my SQLite test environment had missed. I added verification against the database I actually deploy to—a reminder that passing tests are only as representative as their environment.

Long-running research required careful handling of retries, interrupted jobs, and browser reloads. Persisted progress, checkpoints, and explicit job relationships allow the workflow to reconstruct its state without depending on an open tab.

Finally, the interface had to expose enough detail for serious review without burying the screenplay. Keeping the selected passage beside its evidence became the organizing principle.

Accomplishments I'm proud of

I'm proud that a reviewer can follow a concern from its original screenplay passage to its supporting sources, see who acted on it, and understand what happened to it in the next draft.

Selective rescanning is a particular achievement. It preserves evidence for unchanged passages without pretending that an earlier human decision automatically approves a new draft.

I also built governance into the underlying operations. Consequential actions require an authorized person, and the governed change and its audit record commit together or not at all.

The infrastructure supports the same traceability: one application image, explicit migration execution, authenticated background delivery, and durable artifacts.

The tests cover permissions, tenant isolation, conflicting updates, evidence provenance, revision lineage, provider failures, and report release. Browser coverage exercises the user journey across desktop and mobile configurations.

What I learned

An agent's usefulness depends on what happens around its model calls: what information it receives, which sources support its output, how failures appear, and who can act on the result.

Giving detection, research planning, and evaluation distinct model roles also made their responsibilities easier to reason about and test. Each stage has a defined purpose and an inspectable output.

I learned that uncertainty deserves a clear place in the interface. “Sources disagree” and “could not verify” are useful outcomes when they help someone decide what to investigate next.

Screenplay review is a continuing process. Preserving the relationship between versions, evidence, and decisions can be as valuable as producing the initial findings.

What's next for ClearCut

My next priority is testing with filmmakers and clearance professionals using representative screenplay drafts. I want to measure research usefulness, missed concerns, unnecessary flags, review time, and the work avoided through selective rescanning.

I also plan to improve source coverage, refine category-specific research, and make onboarding and deployment easier for small teams.

The direction remains consistent: help filmmakers identify concerns earlier, keep the supporting evidence organized, and make informed human decisions throughout a production's revision cycle.

Built With

Share this project:

Updates

Submission history