ClearCut

Clear the script before it becomes a production problem.

Comment

Inspiration

A screenplay can hide a multi-million dollar production liability in a single line: a copyrighted song playing on a car radio, an identifiable trademarked logo on a prop, or an antagonist whose name and biography inadvertently match a living person. For an independent film production, identifying these clearance risks and tracking the research quickly becomes an overwhelming, manual nightmare.

The industry workflow is notoriously fragmented. The screenplay lives in Final Draft, factual research is scattered across dozens of browser tabs, evidence citations sit in fragile spreadsheets, and legal clearance decisions are buried in email threads. Then the screenplay gets revised, and the production team has to spend days manually figuring out which findings still apply and what needs to be researched all over again.

I built ClearCut around a foundational question: What if the script passage, its cited factual evidence, and the human clearance decision stayed permanently linked—even as the screenplay undergoes continuous revision?

What it does

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

It unifies the entire clearance lifecycle from the initial script import to an audit-ready, version-bound clearance report:

  • Detects Clearance Concerns: Amazon Bedrock analyzes screenplay scenes across ten protected review categories (trademarks, brands, real people, copyrighted works, music, locations, contact info, and more).
  • Conducts Bounded Agentic Research: Powered by the Strands Agents SDK and Parallel Search/Extract, autonomous research agents discover attributable real-world evidence, extract source context, and cite exact URLs, timestamps, and quotes. An item with zero supporting evidence remains explicitly unresolved—ClearCut never invents or hallucinates clearance.
  • Interactive Script-to-Evidence Workspace: Screenplay passages link directly to evidence cards, contradictory sources, review dispositions, and attorney referrals in a side-by-side workspace.
  • Enforces Accountable Governance: Fixed team roles (Owner, Admin, Reviewer, Member) evaluate findings and propose rewrites. To prevent conflicts of interest, a writer cannot approve their own rewrite, and every action commits to an immutable PostgreSQL audit trail.
  • Durable Selective Rescan: When a revised script draft is uploaded, ClearCut deterministically classifies passages as unchanged, moved, modified, added, or removed. An authorized reviewer triggers a selective rescan that re-researches only modified passages, carrying forward verified evidence for unchanged scenes by reference.
  • Produces Reproducible Clearance Reports: Deterministically generated reports bind immutably to a specific screenplay version, requiring explicit human authorization to release or export.

ClearCut gathers evidence and coordinates workflow for qualified human review. It does not provide legal advice or issue formal legal clearance.

How I built it

I built ClearCut as a solo developer with assistance from an Kiro and Agy coding agents, structuring the system around a strict architectural boundary: contextual intelligence is delegated to models, while authorization, evidence admission, tenancy, and audit trails are enforced by deterministic code.

Strands is the orchestration layer behind ClearCut's research workflow. It connects the model to scoped tools for planning searches, retrieving evidence through Parallel, synthesizing claims, and evaluating the results.

The model can choose research actions, while application code enforces tenant boundaries, evidence requirements, budgets, and completion checks. This lets the agent investigate a concern without giving it authority to grant legal clearance or bypass human review.

Strands' provider flexibility became especially useful when I lost access to my AWS account near the deadline. For the local demo, I retained Strands orchestration and used Gemini through Vertex AI, preserving the AWS integration for later deployment.

1. Four Distinct Bedrock Capability Adapters

Rather than using a single monolithic prompt, I implemented four specialized capability adapters communicating with Amazon Bedrock via the Converse API:

  • Detection Runtime: Identifies potential clearance concerns in screenplay passages with element-level text offsets.
  • Research Planner: Analyzes candidate items and formulates structured query strategies.
  • Claim Synthesizer: Extracts concrete factual claims from retrieved source documents.
  • Evaluation Judge: Evaluates evidence against legal risk rubrics while rigorously preserving uncertainty.

All Bedrock adapters enforce truthful model reporting (extracting and recording the exact model ARN returned by Bedrock, never fabricating identifiers) and map provider errors into typed domain exceptions.

2. Bounded Agentic Orchestration with Strands Agents

ClearCut uses the Strands Agents SDK to orchestrate autonomous research loops with defense-in-depth safety guardrails:

  • Server-Side Tenant Scoping: Authenticated tenant context (org_id, project_id) is injected into tool closures on the server. Tool schemas strictly forbid tenant arguments (extra="forbid"), preventing prompt-injection attacks from widening scope or accessing other productions.
  • Immutable Step Receipts: Every agent action, tool invocation, and observation is persisted to a PostgreSQL research_step_receipts table with unique replay deduplication indexes, enabling complete audit replay and crash recovery.
  • Deterministic Completion Validation: An independent validator verifies agent outputs against database records before marking work complete. An agent saying it is "done" cannot bypass required search steps or self-certify an item as cleared without cited evidence.
  • Leaf-Only Permit Discipline: Bedrock permits are held strictly during model inference turns and released before child tool execution, preventing nested-acquire deadlocks.

3. Concurrency & Spend Protection

To prevent runaway cloud bills, I engineered a unified _SharedPermitPool and JobBudgetTracker bounding concurrent Bedrock requests and token/cost limits. The permit pool incorporates mutex-guarded waiter grant tracking to guarantee zero permit leakage under cancellation, while budget trackers strictly reject non-negative and IEEE 754 NaN values.

4. AWS Services & Production Stack

  • Amazon Bedrock: Foundational model intelligence across detection, planning, synthesis, and evaluation roles.
  • Amazon S3: Durable object storage for screenplay drafts, diffs, and exported clearance reports with granular error classification.
  • AWS Secrets Manager: Injected runtime credential resolver with bounded TTL caching, completely eliminating insecure environment variable fallbacks.
  • PostgreSQL 17 (asyncpg + SQLAlchemy): Authoritative durability for multi-tenant business records, audit events, and immutable step receipts.
  • Full-Stack Application: FastAPI modular monolith, TanStack Start & React for the reactive clearance workspace, Astro for public documentation, Tailwind CSS, Docker, and Pytest/Playwright for full-suite verification.

Challenges I ran into

  • Agent Scope & Injection Defense: Screenplay text and web search excerpts frequently contain adversarial text or ambiguous syntax. I completely removed tenant parameters from agent-facing tool schemas and bound them inside server closures, ensuring prompt injection cannot widen permissions or perform SSRF.
  • Eliminating Agent Self-Certification: Autonomous agents tend to declare victory prematurely. Building the DeterministicCompletionValidator ensured that an agent cannot close an item without authentic, cited SourceSnapshot records in PostgreSQL.
  • Concurrency Deadlocks in Multi-Tool Agent Loops: Early prototypes risked deadlocks when an agent holding a Bedrock concurrency permit invoked a tool that itself required model evaluation. I enforced leaf-only permit acquisition, ensuring outer inference permits are released before child tools execute.
  • PostgreSQL Event-Loop Isolation in Tests: Python's asyncpg driver maintains connection pools bound to specific event loops, causing test harness collisions under pytest-asyncio. I engineered per-test engine disposal and dynamic database URL propagation, taking the PostgreSQL test suite from hundreds of harness errors to 100% green passes.

An unexpected infrastructure change

Near the submission deadline, my AWS account was suspended, leaving me unable to use Bedrock for the demo. This became a practical test of the separation between orchestration and model providers.

Strands made it possible to retain the agent workflow while switching its model to Gemini through Vertex AI. I also connected the workflow's specialist model roles to Gemini, while keeping Parallel as the source of cited web evidence and preserving the existing review controls.

The demo runs locally with that configuration. The AWS adapters remain in the repository, but I am not presenting this recording as a verified AWS deployment.

Accomplishments I'm proud of

  • A Truly Bounded Agentic Workflow: Creating an agent that makes authentic research and tool decisions while remaining strictly constrained by deterministic server-side guardrails, budget limits, and immutable PostgreSQL audit receipts.
  • Selective Rescan: Screenwriters constantly revise their scripts. ClearCut calculates passage-level diffs and re-evaluates only what changed, preserving historical human clearance decisions without pretending an earlier approval automatically applies to a new scene.
  • 100% Verified Multi-Engine Test Harness: The full test suite passes cleanly across both SQLite and live PostgreSQL 17 (over 1,170 tests with zero failures and zero skipped checks), alongside strict API contract synchronization.
  • Uncompromising Provenance: Zero evidence remains visibly unresolved. ClearCut never hallucinates or fabricates clearance evidence to fill an empty screen.

What I learned

  • Agents need deterministic guardrails, not prompt guardrails: Telling an LLM in a prompt "do not access other tenants" is a suggestion; injecting tenant boundaries into server-side tool closures is a guarantee.
  • Separating model roles simplifies verification: Giving detection, research planning, claim synthesis, and judging distinct model roles made each stage inspectable, measurable, and easily swappable across Bedrock model families.
  • Uncertainty is a feature, not a failure: In high-liability domains like legal clearance, displaying "Sources disagree" or "Unresolved — verification required" is infinitely more valuable to a production team than a confident hallucination.

What's next for ClearCut

  • Live Studio & Independent Production Pilots: Partnering with indie film producers and entertainment legal teams to measure review hours saved on real revision cycles.
  • Distributed SQS Outbox Dispatch: Scaling the background worker fleet across Amazon SQS queues for high-volume studio script analysis.
  • Voice & Audio Clearance Extensions: Extending detection and research pipelines to cleared background score cues and automated production cue sheets.

Built With

Share this project:

Updates

Submission history