# Python Tool Reference

> **STALENESS WARNING (2026-04-25):** This document was last touched 2026-03-07 — predates the June 1 refactor and the engine reorg. Likely-missing tools include `recoil/pipeline/cli/generate.py` (the `/generate-video` entry point), `tools/test_via_steprunner.py`, `tools/build_coverage_passes.py`, and any post-engine-reorg path changes. Sections describing tool paths may reference pre-reorg locations. Do not rely on this file for current tool inventory or paths. Cross-reference: `audit-2026-04-25/docs-freshness.md` (entry 6). Scheduled rewrite: post-CP-2 verification (~2026-06-08).

All Python scripts in the Recoil engine, organized by category.

## Narrative Pipeline

| Script | Location | Purpose |
|--------|----------|---------|
| `episode_metrics.py` | `/tools/` | **Per-episode validation** (word count, exchanges, dialogue %, Kill Box) |
| `validate_batch.py` | `.claude/hooks/` | Batch validation (incl. meta-reference check) |
| `save_checkpoint.py` | `.claude/hooks/` | Batch checkpoint + baseline + batch summary |
| `compile_episodes.py` | `/tools/` | Merge episodes to Fountain |
| `compile_treatment.py` | `/tools/` | Treatment compilation to Fountain |
| `script_doctor.py` | `/tools/` | **Full-series diagnostic** (bundles corpus, calls Gemini API, produces revision brief) |
| `apply_annotations.py` | `/tools/` | **Batch annotation applicator** (auto-applies REWRITE/DELETE from script-doctor brief, backups, revision log. `--dry-run`, `--p1-only`) |
| `fountain_reader.py` | `/tools/` | **Fountain parser + TTS** (ElevenLabs, Qwen3, Qwen3 clone) |

## Validation Gates

| Script | Location | Purpose |
|--------|----------|---------|
| `validate_behavioral_dna.py` | `.claude/hooks/` | Character validation gate |
| `validate_pre_treatment.py` | `.claude/hooks/` | Pre-treatment gate (promotion check) |
| `validate_treatment.py` | `/tools/` | Treatment validation |
| `validate_pre_generation.py` | `.claude/hooks/` | Pre-generation treatment.md check |
| `validate_docs.py` | `/tools/` | Documentation consistency |
| `validate_arc.py` | `/tools/` | Arc structure validation |
| `validate_project.py` | `/tools/` | Project validation |
| `validate_treatment_batch.py` | `/tools/` | Treatment batch validation |
| `validate_episode_arc.py` | `.claude/hooks/` | Pre-promotion episode arc validation |
| `enforce_context_load.py` | `.claude/hooks/` | Pre-write context load enforcement |
| `episode_enforcement.py` | `.claude/hooks/` | Post-episode-write validation enforcement |
| `quality_gate.py` | `.claude/hooks/` | Per-episode quality gate |
| `transition_gate.py` | `.claude/hooks/` | Phase transition gate enforcement |
| `dramatic_qc_gate.py` | `.claude/hooks/` | Post-generation dramatic quality check |

## Orchestration

| Script | Location | Purpose |
|--------|----------|---------|
| `init_orchestrator_state.py` | `/tools/` | Initialize orchestrator state from treatment |
| `update_orchestrator_state.py` | `/tools/` | Update orchestrator after each batch |
| `generate_batch_summary.py` | `/tools/` | Extract batch metadata for orchestrator |
| `orchestrator_verify.py` | `/tools/` | Combined verification (threads, beats, patterns) |
| `extract_treatment_batch.py` | `/tools/` | Extract treatment batch for generation |
| `promote_project.py` | `/tools/` | Create production folder from development docs |

## Thread & Beat Tracking

| Script | Location | Purpose |
|--------|----------|---------|
| `track_threads.py` | `/tools/` | Thread tracking utility |
| `verify_emotional_beats.py` | `/tools/` | Emotional beat tracking |
| `verify_pattern_variety.py` | `/tools/` | Hook/cliffhanger pattern variety |
| `verify_thread_continuity.py` | `/tools/` | Thread plant/payoff tracking |
| `baseline_comparison.py` | `.claude/hooks/` | Post-batch baseline comparison |
| `checkpoint_reminder.py` | `.claude/hooks/` | Periodic checkpoint reminders |

## Visual Production (Recoil-side)

| Script | Location | Purpose |
|--------|----------|---------|
| `script_breakdown.py` | `/tools/` | Script breakdown extraction (visual assets) |
| `validate_breakdown.py` | `/tools/` | Breakdown verification (continuity + completeness) |
| `validate_visual_bible.py` | `/tools/` | Visual bible verification |
| `validate_storyboard.py` | `/tools/` | Storyboard verification (shot grammar) |
| `motion_complexity.py` | `/tools/` | Motion complexity classifier (LOW/MEDIUM/HIGH) |
| `storyboard_version.py` | `/tools/` | Storyboard versioning (save/list/diff/revert) |
| `validate_pre_production.py` | `/tools/` | Pre-production gate |
| `generate_previz.py` | `/tools/` | Previz keyframe generator |
| `generate_storyboard_keyframes.py` | `/tools/` | T2I keyframes via fal.ai Flux 2+LoRA |
| `batch_generate_refs.py` | `/tools/` | Reference image batch generation |
| `engine_shootout.py` | `/tools/` | Engine comparison tool |
| `batch_threepass.py` | `/tools/` | Three-pass LoRA candidate batch generator |
| `train_lora.py` | `/tools/` | LoRA training pipeline (fal.ai) |
| `visual_qc.py` | `/tools/` | Visual QC (completeness, coverage) |
| `visual_gate.py` | `/tools/` | Visual Gate (artifact detection + semantic alignment) |
| `gemini_qc.py` | `/tools/` | Gemini Visual QC Pipeline (8-dimension scoring) |
| `prompt_doctor.py` | `/tools/` | Pre-generation prompt analysis |
| `ab_test_models.py` | `/tools/` | A/B model comparison |
| `extract_palette.py` | `/tools/` | Palette extraction (K-means clustering) |
| `asset_naming.py` | `/tools/` | Asset naming convention |

## Libraries

| Script | Location | Purpose |
|--------|----------|---------|
| `config_loader.py` | `/lib/` | Shared config loader (camera, lenses, quality guard, identity lock) |
| `cost_tracker.py` | `/tools/` | Project cost tracking |
| `prompt_compiler.py` | `/lib/` | Prompt compilation (framing-first, layer skipping, model-aware) |
| `prompt_validators.py` | `/lib/` | Post-compile prompt validation |
| `engine_constants.py` | `/tools/` | Shared constants parser (reads CONSTANTS.md) |
| `engine_check.py` | `/tools/` | 53-check engine audit (8 categories) |