The Script Agent: Turning a Single Sentence Into Structured Data — Character Cards, Scenes, and Shots

Today's Goals

1. Constrain model output with a schema so the script lands directly as program-readable character cards, scenes, and shot data
2. Add a reviewer role to the script agent that improves the draft in a loop against judgeable criteria
3. Extract character and world-bible settings into a separate store, so every later episode stays on track

On yesterday's task graph, every node other than the script feeds on fields of the shot data. Today we enter the writers' room and genuinely produce that data — come back and tick off the three goals.

Plain-Language Walkthrough

The line between prose and data: why a script must become structured data first

Ask a model to write a short drama script and you get a rather presentable stretch of prose: scene description, dialogue, emotional cues, all in one flow. Comfortable for a person to read and entirely unusable by a program.

Think about how a crew works. The writer delivers a script, and no department works from the script directly. The script first becomes a shot list: which shot number, what shot size, how long, who is present, what is in frame, how the camera moves, which line is spoken. The art department reads what is in frame, the camera department how the camera moves, sound which line is spoken, and editing how long. One table split across six departments, each reading only its own columns.

Our pipeline is the same thing with departments replaced by six nodes. The image node reads visual, the video node reads camera and durationSec, the voiceover node reads dialogue and the character's voiceId, and the timeline node reads durationSec. All that information exists in a stretch of prose, and mixed together it may as well not — you cannot reliably extract a slow push-in, six seconds, and half a line from "he walks slowly to the window, his voice dropping."

Somebody will think a regex, or another model call parsing the prose, would do. It would, at two costs: one generation and one parse, with the parse's failure rate fluctuating with script style so you never know whether the next episode parses into an empty array. Better to have the model produce the data structure from the outset, merging writing and formatting into one step.

So today's dividing line is drawn like this:

That line recurs in every later section. Anything a program can judge should never be given to the model.

Which fields a shot card should have

More fields is not better, and there is one criterion: does a downstream node genuinely read it? This course fixes seven fields on a shot card, with nothing added or removed across fourteen days:

type Shot = {
  id: string // the shot number, shaped s01, unique in the episode — also part of the artifact directory name and the cache key
  sceneId: string // a scene id pointing at one entry in this episode's scene table
  shotSize: 'wide' | 'medium' | 'close' // three sizes only; do not introduce a fourth
  durationSec: number // the planned duration, possibly rewritten by the real voiceover duration on day 5
  characters: string[] // character ids present, used on day 3 to decide which reference sheet to pass
  visual: string // the visual description, entering the image and video prompts
  camera: string // the camera movement, entering the video prompt
  dialogue: { characterId: string; text: string }[] // the lines, entering voiceover
}

from typing import Literal, TypedDict
 
 
class Line(TypedDict):
    characterId: str
    text: str
 
 
class Shot(TypedDict):
    id: str  # the shot number, shaped s01, unique in the episode
    sceneId: str  # a scene id pointing at one entry in this episode's scene table
    shotSize: Literal["wide", "medium", "close"]  # three sizes only; do not introduce a fourth
    durationSec: int  # the planned duration, possibly rewritten by the real voiceover duration on day 5
    characters: list[str]  # character ids present, deciding which reference sheet to pass on day 3
    visual: str  # the visual description, entering the image and video prompts
    camera: str  # the camera movement, entering the video prompt
    dialogue: list[Line]  # the lines, entering voiceover

Three conventions deserve their own mention.

Three shot sizes only. Film distinguishes seven or eight, and our downstream only splices it into a prompt, where a model cannot tell finer distinctions apart, while extra branches burden validation and later statistics. An enum's size should be decided by downstream discriminating power, not by industry habit.

Duration fields always end in Sec or Ms. Day 5's voiceover duration is milliseconds and day 6's timeline is milliseconds while a shot's planned duration is seconds. A bare duration mixed among them will sooner or later be multiplied wrongly by a thousand — a very quiet bug making the finished cut a thousandth of its correct length.

A shot number is s01 rather than 1. It becomes a directory name, a filename prefix, and part of day 8's cache key. Zero-padded, sorting matches visual order, which you will thank yourself for past ten shots.

The engineering cost is that once fixed, fields are hard to change. Every key written into Shot today has code reading it across the next twelve days; and by day 10's review console there will also be a front-end page rendering it. So take this step slowly and ask, key by key, which downstream reads it.

Using a schema to make the model be quiet: three roads and how each crashes

Getting a model to output valid JSON has broadly three roads in the industry.

One: prompt constraint plus local validation. Write "output JSON only, no explanation" into the system prompt, extract the JSON from the reply, validate it yourself, and feed the problems back for another attempt when it fails. It crashes when the model does not obey — adding pleasantries, adding explanation, or wrapping the JSON in fences.

Two: a vendor's JSON mode or structured output parameter. Some vendors offer a parameter forcing JSON or constraining decoding to a schema, with the server guaranteeing parseability. It crashes because support and field names differ between vendors; whether it exists and what it is called is per the official documentation, and using it binds this code to that vendor.

Three: borrowing tool calling's parameter schema. Define "submit the script" as a tool whose parameter schema is your data structure and have the model call it. It crashes because some implementations treat the schema as a strong suggestion and may still produce invalid arguments.

This course takes the first, for a reason continuous with yesterday's provider abstraction: it depends on no vendor's extension field, and switching vendors needs not one line changed. The cost is writing two things yourself — extracting the JSON and validating it.

The extraction must handle the two most common cases, pleasantries around it and fences wrapping it; and when validation fails, feeding the pathed problems back verbatim and asking it to fix only those helps far more than switching to a larger model:

// Find the first brace or bracket, then the last matching closer, and parse only what lies between.
// JSON.parse over the whole reply blows up three times in ten against a real model.
function extractJson(text: string): unknown {
  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text)
  const body = fenced ? fenced[1] : text
  const start = body.search(/[[{]/)
  const close = body[start] === '{' ? '}' : ']'
  return JSON.parse(body.slice(start, body.lastIndexOf(close) + 1))
}
 
// On a validation failure, feed back "path plus reason" and retry once; failing twice is a real failure.
async function ask(text, system, user, parse) {
  for (let attempt = 1; attempt <= 2; attempt++) {
    const raw = await text.complete({ system, user })
    const issues = []
    const value = parse(extractJson(raw.text), issues)
    if (issues.length === 0) return value
    if (attempt === 2) throw new Error('schema validation failed twice')
    user += `\n\nThe last version had these field problems. Fix only these and change nothing else:\n${issues.map((i) => `- ${i.path}: ${i.message}`).join('\n')}`
  }
}

import json
import re
 
 
# Find the first brace or bracket, then the last matching closer, and parse only what lies between.
# json.loads over the whole reply blows up three times in ten against a real model.
def extract_json(text: str):
    fenced = re.search(r"```(?:json)?\s*(.*?)```", text, re.S)
    body = fenced.group(1) if fenced else text
    start = min((i for i in (body.find("["), body.find("{")) if i >= 0), default=-1)
    close = "}" if body[start] == "{" else "]"
    return json.loads(body[start : body.rfind(close) + 1])
 
 
# On a validation failure, feed back "path plus reason" and retry once; failing twice is a real failure.
async def ask(text, system, user, parse):
    for attempt in (1, 2):
        raw = await text.complete(system=system, user=user)
        issues: list[dict] = []
        value = parse(extract_json(raw["text"]), issues)
        if not issues:
            return value
        if attempt == 2:
            raise ValueError("schema validation failed twice")
        lines = "\n".join(f"- {i['path']}: {i['message']}" for i in issues)
        user += f"\n\nThe last version had these field problems. Fix only these:\n{lines}"

A writer and a reviewer: give the second role a scorecard

Generating one version at a time and starting over when dissatisfied is the most expensive way to revise, because each pass pays again for the ninety percent already correct. A crew does not work that way: the writer delivers, the producer and director go through a list item by item, and the writer changes only what was flagged.

Bringing that in gives a writer and a reviewer. But there is a key engineering judgment here, and it is today's most portable sentence:

The reviewer is not a model but two layers: code judging hard faults and a model judging soft faults.

Hard faults are program-decidable: does each shot have a camera, is the duration between 3 and 8 seconds, does any single line exceed 25 characters, does everyone in the character cards appear, is the episode's total between 45 and 90 seconds. Those five take a few lines to check, cost nothing, miss nothing, and give stable verdicts. Soft faults are what a program cannot judge: is there a hook in the first three seconds, does the motivation hold, does the ending leave people wanting — those belong to a model.

// Five hard faults, each matching a real constraint on a later day rather than padding
function checkHard(ep, characters) {
  const issues = []
  for (const s of ep.shots) {
    if (!s.camera.trim()) issues.push(`[camera] ${s.id} has no camera movement; day 4 has nothing for the prompt`)
    if (s.durationSec < 3 || s.durationSec > 8) issues.push(`[duration] ${s.id} duration out of range`)
    for (const d of s.dialogue) {
      if (d.text.length > 25) issues.push(`[dialogue] ${s.id} line is ${d.text.length} characters, over 25`)
    }
  }
  return issues
}
 
// Seventy percent hard, thirty percent soft: what a machine can judge must not be outweighed by a model's praise
const hardScore = Math.max(0, 100 - hard.length * 8)
const score = Math.round(hardScore * 0.7 + softScore * 0.3)

# Five hard faults, each matching a real constraint on a later day rather than padding
def check_hard(ep, characters):
    issues = []
    for s in ep["shots"]:
        if not s["camera"].strip():
            issues.append(f"[camera] {s['id']} has no camera movement; day 4 has nothing for the prompt")
        if not 3 <= s["durationSec"] <= 8:
            issues.append(f"[duration] {s['id']} duration out of range")
        for d in s["dialogue"]:
            if len(d["text"]) > 25:
                issues.append(f"[dialogue] {s['id']} line is {len(d['text'])} characters, over 25")
    return issues
 
 
# Seventy percent hard, thirty percent soft: what a machine can judge must not be outweighed by praise
hard_score = max(0, len(hard) * -8 + 100)
score = round(hard_score * 0.7 + soft_score * 0.3)

Note the bracketed category code at the start of each hard fault. It is not for a human but for the writer: given [camera], the writer knows what class to fix, and that class disappears next round. Categorized feedback makes revision converge; a bare "not good enough" only makes the model rewrite everything and break what it already fixed.

The lab's offline scores rise 69, 86, 91 across three rounds, with hard fault counts genuinely falling each round — because those five rules are computed locally rather than invented. Run it with a different sentence and the curve's shape holds while the content changes entirely, which is what the business logic genuinely running looks like.

The world bible: cross-episode consistency appears for the first time

So far we made one episode. But this course ends at a five-episode season, and the problem arrives immediately: in episode two, is the lead still the same person?

Short drama audiences are extremely sensitive to that. A changed name, a changed occupation, a personality that does not match, and the comments start. And a model has no memory — on your second call it knows nothing of episode one.

The remedy is plain: extract what does not change across episodes into its own store, read before generating each episode. That is the world bible, landed at script/world.json, with character cards at script/characters.json:

• world.json: the title, a one-line premise, the tone, the setting, and a few hard rules (only the lead knows this, or every episode must end on an unanswered question).
• characters.json: each character's id, name, appearance, personality, and voice id.

Why are appearance and voice here too? Because they are not merely settings but downstream input parameters: the appearance description goes verbatim into day 3's image prompt, and the voice id goes verbatim into day 5's speech endpoint. Putting them in the same file as the name solves consistency in one file rather than in three places written three times.

Day 14 genuinely puts that bible to work: five episodes generated in sequence, each carrying the same world.json and characters.json, so characters and style do not drift across episodes. Today you only need it stored separately with field names matching exactly what downstream will use.

When to stop: three exits, none omissible

A generate-and-review loop carries a fatal temptation: if every round improves it, run a few more. That is the fastest way to burn money.

A production-ready loop needs three exits:

Exit one, stop on passing. Wrap the moment the score reaches the threshold. Do not chase a perfect score — in this lab the loop stops at 91 with one [dialogue] hard fault still present. That is deliberate: a threshold means good enough, not perfect, and chasing those last few points costs far more than it returns.

Exit two, stop at the round limit. Write the scoring criteria strictly enough and the model may never reach the threshold, and a loop without a limit runs forever. On hitting the limit do two things: deliver the highest-scoring draft (not the last, since review fluctuates) and print explicitly that it did not pass and hit the limit, so the user knows a human is needed.

Exit three, a human decides. Today leaves only the interface, with day 10's review console implementing it. The criterion: when the remaining problems are all soft faults, hand it to a person. A loop can fix hard faults, and soft fault scores come from the model itself, so a model evaluating and revising itself only circles in place.

The engineering cost is that all three exits need parameters, and parameters need tuning. Set the threshold high and rounds run out; set it low and the draft is unusable; set the round limit high and money burns; set it low and it is always one push short. The lab makes them the environment variables PASS_SCORE and MAX_ROUNDS, and you should genuinely change them and watch how the score curve moves — worth more than reading this section ten times.

Source Reading

Hands-On Lab

Today needs no ffmpeg and calls no image, video, or speech endpoint, using only the text category of the four providers; MOCK=1 throughout is enough. starter/ runs as-is with the score unchanged across four rounds, the limit exhausted, and a 12-second shot and a 40-character line surviving into the final draft — the four numbered exercises match those symptoms.

1. Run the solution once, read the three rounds' scores and each round's hard fault list, then open drafts/ and diff adjacent rounds to see exactly what changed each round.
2. Back in the starter, do exercise 1: add the other four hard faults to the scorecard, and round one's hard fault count should rise from 3 to 5.
3. Do exercise 2: change the final score to seventy percent hard and thirty percent soft, at which point the score rises as hard faults fall.
4. Do exercise 3: add the stop-on-passing and deliver-the-best-draft-at-the-limit exits to the loop, and confirm it stops at round 3 rather than round 4.
5. Do exercise 4: add the referential integrity check, verify with INJECT=badref that a bad draft is caught, then run three premises of your own and confirm no field is missing and the content changes.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward structured output's implementation routes and failure modes, a generate-and-review loop's convergence conditions, and where cross-episode consistency is stored. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets. The high-frequency labels for the domestic and overseas markets are there so you can pick by target market.

Checklist and Tomorrow

• Constrain model output with a schema so the script lands directly as program-readable character cards, scenes, and shot data
• Add a reviewer role to the script agent that improves the draft in a loop against judgeable criteria
• Extract character and world-bible settings into a separate store, so every later episode stays on track
• Name structured output's three implementation routes, and why this course took the first
• Explain why validation must have both a type layer and a referential integrity layer
• All 5 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D3) we visit the art department: wiring up the image generation endpoint and producing character reference sheets and scene images in batch from today's shot data. Why that order? Because the image node feeds on exactly two fields settled today — the character cards' appearance and the shots' visual. And the moment images appear, a problem that is only latent today explodes on the spot: a generation model has no memory, and the lead in the second image quite likely has a different face. D3 explains that cause and what each of three locking techniques — reference images, seeds, and prompt templates — can and cannot hold in place.