# Keyframe Storyboard Credit Simulator (SimPy + NumPy)

## PURPOSE
This discrete-event simulation models the workflow shown in the video: generate
a set of key frames (up to 10, used as checkpoints inside a clip), pause for human
storyboard approval, then move into video generation — approving credits before
spend and only then rendering the 30-second piece. It answers the planning
question "how many clips can my credit budget produce this week, and which model
tier should I use?" by simulating many runs across Kling 4.0, Seedance 2.5 and the
cheaper LTX 2.5.

## WHY THIS MATTERS
The transcript makes two concrete claims a planner must reconcile: Kling 4 is
~70% cheaper (about $0.80 vs $2.85 for a 5-second 1080p clip) and supports up to
10 key frames and 30-second output, while re-rendering costs money. Since every
generation — key frames and final video — burns credits, the cheapest per-clip
model is not automatically the cheapest per *approved deliverable*. Students
learn to model retries, approval delays, and rejection as a queueing system.

## HOW TO BUILD
1. `pip install simpy numpy`
2. Define an environment where each `storyboard` process generates key frames
   (drawn from the model's max key-frame count), waits a human approval delay,
   and retries on rejection.
3. Sample quality and rejection with NumPy seeded for determinism.
4. Accumulate credit spend and stop when the budget cap is reached.

```python
def storyboard(env, model, rng, stats, budget_cap):
    while not stats["done"] and stats["spent"] < budget_cap:
        kf = rng.integers(1, model.max_keyframes + 1)
        stats["spent"] += kf * model.credit_per_keyframe
        yield env.timeout(model.keyframe_latency)
        if rng.random() < model.reject_prob:      # storyboard not approved
            continue
        stats["spent"] += model.credit_per_video
        yield env.timeout(model.render_latency)
        stats["approved"] += 1
        break
```

## WHEN TO USE IN PRODUCTION
Use it before committing to a subscription tier: forecasting monthly credit burn
for a content calendar, or deciding when a cheap tier plus more re-rolls beats a
premium tier. Not appropriate when spend is unpredictable by nature (one-off
campaigns), when exact credit accounting must come from the vendor's own counter,
or for creative decisions the simulation cannot capture.

## HOW IT HELPS STUDENTS
Students gain hands-on SimPy process modelling, NumPy seeded Monte Carlo, and the
skill of reasoning about cost under uncertainty — the same trade-off studios face
when choosing a video-generation plan.

## STARTER CODE
`starter/main.py` runs a seeded simulation across the three tiers and prints
approved clips and dollars spent, with `# TODO` markers for real credit rates.
