# godkillersajal/promo-finder architecture

> Architecture diagram of the GitHub repository godkillersajal/promo-finder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/godkillersajal/promo-finder
- Repository: https://github.com/godkillersajal/promo-finder

## Overview

Promo Finder turns episode screenplay files into ranked, ready-to-post short-form promos. The documented workflow parses timed blocks, asks Gemini to identify promo candidates, validates and repairs cuts in code, creates trailers, judges and ranks the results, then writes CSV, JSON, raw replies, and a run log. The README describes these stages and the model’s role; the sampled source is partial, so internal call relationships beyond that documentation are not inferred.

Main entry points: [`promo_finder.py`](https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py) (Model requests and cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Script intake"]
  node_scripts["Episode scripts"]
  node_parser["Timed-block parser<br/>[promo_finder.py]"]
  node_blocks["Numbered script blocks<br/>[promo_finder.py]"]
end

subgraph group_creation["Promo creation"]
  node_bible["Series bible<br/>[promo_finder.py]"]
  node_episode_candidates["Episode promo candidates<br/>[promo_finder.py]"]
  node_cut_rules["Cut validation and repair<br/>[promo_finder.py]"]
  node_trailers["Trailer selection and cuts<br/>[promo_finder.py]"]
end

subgraph group_evaluation["Evaluation and ranking"]
  node_judge["Promo judging<br/>[promo_finder.py]"]
  node_ranking["Scoring and ranking<br/>[promo_finder.py]"]
end

subgraph group_runtime["Model and output"]
  node_model_client["Model requests and cache<br/>[promo_finder.py]"]
  node_results["Promo result files<br/>[promo_finder.py]"]
end

node_editor(("Show editor"))
node_gemini{{"Google Gemini"}}

node_editor -->|"provides"| node_scripts
node_scripts -->|"reads scripts"| node_parser
node_parser -->|"numbers and times"| node_blocks
node_blocks -->|"provides episode context"| node_bible
node_bible -->|"requests synthesis"| node_model_client
node_model_client -->|"sends model calls"| node_gemini
node_gemini -->|"returns judgments"| node_model_client
node_blocks -->|"provides script blocks"| node_episode_candidates
node_episode_candidates -->|"requests candidates"| node_model_client
node_model_client -->|"returns candidate cuts"| node_cut_rules
node_cut_rules -->|"provides validated moments"| node_trailers
node_trailers -->|"requests trailer picks"| node_model_client
node_model_client -->|"returns trailer picks"| node_judge
node_cut_rules -->|"provides promo cuts"| node_judge
node_judge -->|"requests promo scores"| node_model_client
node_model_client -->|"returns scores"| node_ranking
node_ranking -->|"writes ranked outputs"| node_results

click node_parser "https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py"
click node_blocks "https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py"
click node_bible "https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py"
click node_episode_candidates "https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py"
click node_cut_rules "https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py"
click node_trailers "https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py"
click node_judge "https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py"
click node_ranking "https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py"
click node_model_client "https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py"
click node_results "https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scripts,node_parser,node_blocks toneBlue
class node_bible,node_episode_candidates,node_cut_rules,node_trailers toneAmber
class node_judge,node_ranking toneMint
class node_model_client,node_results toneRose
class node_editor,node_gemini toneIndigo
```

## Components

### Script intake

- **Episode scripts**
- [Timed-block parser](https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py): `promo_finder.py`
- [Numbered script blocks](https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py): `promo_finder.py`

### Promo creation

- [Series bible](https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py): `promo_finder.py`
- [Episode promo candidates](https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py): `promo_finder.py`
- [Cut validation and repair](https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py): `promo_finder.py`
- [Trailer selection and cuts](https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py): `promo_finder.py`

### Evaluation and ranking

- [Promo judging](https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py): `promo_finder.py`
- [Scoring and ranking](https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py): `promo_finder.py`

### Model and output

- [Model requests and cache](https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py): `promo_finder.py`
- [Promo result files](https://github.com/godkillersajal/promo-finder/blob/main/promo_finder.py): `promo_finder.py`

### Other components

- **Show editor**
- **Google Gemini**

## Connections

- Show editor → Episode scripts: provides (evidence: `README.md`)
- Episode scripts → Timed-block parser: reads scripts (evidence: `README.md`)
- Timed-block parser → Numbered script blocks: numbers and times (evidence: `README.md`)
- Numbered script blocks → Series bible: provides episode context (evidence: `README.md`)
- Series bible → Model requests and cache: requests synthesis (evidence: `README.md`)
- Model requests and cache → Google Gemini: sends model calls (evidence: `README.md`)
- Google Gemini → Model requests and cache: returns judgments (evidence: `README.md`)
- Numbered script blocks → Episode promo candidates: provides script blocks (evidence: `README.md`)
- Episode promo candidates → Model requests and cache: requests candidates (evidence: `README.md`)
- Model requests and cache → Cut validation and repair: returns candidate cuts (evidence: `README.md`)
- Cut validation and repair → Trailer selection and cuts: provides validated moments (evidence: `README.md`)
- Trailer selection and cuts → Model requests and cache: requests trailer picks (evidence: `README.md`)
- Model requests and cache → Promo judging: returns trailer picks (evidence: `README.md`)
- Cut validation and repair → Promo judging: provides promo cuts (evidence: `README.md`)
- Promo judging → Model requests and cache: requests promo scores (evidence: `README.md`)
- Model requests and cache → Scoring and ranking: returns scores (evidence: `README.md`)
- Scoring and ranking → Promo result files: writes ranked outputs (evidence: `README.md`)
