# hardikagarwal23/kuku_promo_studio architecture

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

- Interactive diagram: https://gitdiagram.com/hardikagarwal23/kuku_promo_studio
- Repository: https://github.com/hardikagarwal23/kuku_promo_studio

## Overview

Kuku PS1 turns screenplay text into ranked, event-boundary promo recommendations; it does not edit video. The CLI pipeline parses episodes, builds a show profile, generates and filters candidates, scores them with an LLM, optionally extends strong candidates, validates and ranks them, then exports results. A Streamlit review UI and studio operations provide a separate editorial workflow. The README documents the stages; source-index references and excerpts support the internal links shown here, while unsampled implementation details are not assumed.

Main entry points: [`src/run.py`](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/run.py) (CLI Runner), [`src/llm_client.py`](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/llm_client.py) (LLM Client), [`app.py`](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/app.py) (Review Dashboard), [`src/scoring.py`](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/scoring.py) (Candidate Scorers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Recommendation Pipeline"]
  node_cli["CLI Runner<br/>[run.py]"]
  node_parser["Screenplay Parser<br/>[parser.py]"]
  node_events["Parsed Events<br/>[schemas.py]"]
  node_candidates["Window Generator<br/>[candidates.py]"]
  node_prefilter["Recall Prefilter<br/>[prefilter.py]"]
  node_validation["Validation and Ranking"]
  node_exporter["Result Exporter<br/>[exporter.py]"]
end

subgraph group_analysis["Narrative Analysis"]
  node_profile["Show Profiler<br/>[show_profile.py]"]
  node_scorer["Candidate Scorers<br/>[scoring.py]"]
  node_extension["Start Extension<br/>[extension.py]"]
  node_llm["LLM Client<br/>[llm_client.py]"]
end

subgraph group_operations["Run Operations"]
  node_settings["App Configuration<br/>[config.py]"]
  node_reliability["Run Reliability<br/>[reliability.py]"]
  node_outputs[("Run Outputs")]
end

subgraph group_review["Editorial Review"]
  node_ui["Review Dashboard<br/>[app.py]"]
  node_dashboard_data["Dashboard Data<br/>[dashboard_data.py]"]
  node_studio["Studio Operations<br/>[studio_ops.py]"]
end

node_editor(("Screenplay Editor"))
node_provider{{"LLM Provider"}}
node_reviewer(("Human Editor"))

node_editor -->|"provides scripts"| node_cli
node_cli -->|"parses episodes"| node_parser
node_parser -->|"creates events"| node_events
node_cli -->|"generates windows"| node_candidates
node_cli -->|"filters candidates"| node_prefilter
node_cli -->|"builds profile"| node_profile
node_profile -->|"requests profile"| node_llm
node_cli -->|"scores candidates"| node_scorer
node_scorer -->|"requests evaluations"| node_llm
node_llm -->|"sends prompts"| node_provider
node_cli -->|"may extend"| node_extension
node_extension -->|"rescores extension"| node_scorer
node_cli -->|"validates and ranks"| node_validation
node_cli -->|"exports results"| node_exporter
node_cli -->|"writes run files"| node_outputs
node_cli -->|"records checkpoints"| node_reliability
node_llm -->|"loads settings"| node_settings
node_ui -->|"loads dashboard data"| node_dashboard_data
node_ui -->|"uses studio operations"| node_studio
node_reviewer -->|"reviews promos"| node_ui
node_dashboard_data -.->|"reads run data"| node_outputs
node_studio -.->|"starts pipeline"| node_cli

click node_cli "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/run.py"
click node_parser "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/parser.py"
click node_events "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/schemas.py"
click node_candidates "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/candidates.py"
click node_prefilter "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/prefilter.py"
click node_profile "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/show_profile.py"
click node_scorer "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/scoring.py"
click node_extension "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/extension.py"
click node_llm "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/llm_client.py"
click node_validation "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/validation_ranking.py"
click node_settings "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/config.py"
click node_reliability "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/reliability.py"
click node_exporter "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/exporter.py"
click node_ui "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/app.py"
click node_dashboard_data "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/dashboard_data.py"
click node_studio "https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/studio_ops.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_cli,node_parser,node_events,node_candidates,node_prefilter,node_validation,node_exporter,node_editor toneBlue
class node_profile,node_scorer,node_extension,node_llm toneAmber
class node_settings,node_reliability,node_outputs toneMint
class node_ui,node_dashboard_data,node_studio toneRose
class node_provider,node_reviewer toneIndigo
```

## Components

### Recommendation Pipeline

- [CLI Runner](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/run.py): `src/run.py`
- [Screenplay Parser](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/parser.py): `src/parser.py`
- [Parsed Events](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/schemas.py): `src/schemas.py`
- [Window Generator](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/candidates.py): `src/candidates.py`
- [Recall Prefilter](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/prefilter.py): `src/prefilter.py`
- [Validation and Ranking](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/validation_ranking.py): `src/validation_ranking.py`
- [Result Exporter](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/exporter.py): `src/exporter.py`

### Narrative Analysis

- [Show Profiler](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/show_profile.py): `src/show_profile.py`
- [Candidate Scorers](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/scoring.py): `src/scoring.py`
- [Start Extension](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/extension.py): `src/extension.py`
- [LLM Client](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/llm_client.py): `src/llm_client.py`

### Run Operations

- [App Configuration](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/config.py): `src/config.py`
- [Run Reliability](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/src/reliability.py): `src/reliability.py`
- **Run Outputs**

### Editorial Review

- [Review Dashboard](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/app.py): `app.py`
- [Dashboard Data](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/dashboard_data.py): `dashboard_data.py`
- [Studio Operations](https://github.com/hardikagarwal23/kuku_promo_studio/blob/main/studio_ops.py): `studio_ops.py`

### Other components

- **Screenplay Editor**
- **LLM Provider**
- **Human Editor**

## Connections

- Screenplay Editor → CLI Runner: provides scripts (evidence: `README.md`)
- CLI Runner → Screenplay Parser: parses episodes (evidence: `src/run.py`)
- Screenplay Parser → Parsed Events: creates events (evidence: `src/parser.py`)
- CLI Runner → Window Generator: generates windows (evidence: `src/run.py`)
- CLI Runner → Recall Prefilter: filters candidates (evidence: `src/run.py`)
- CLI Runner → Show Profiler: builds profile (evidence: `src/run.py`)
- Show Profiler → LLM Client: requests profile (evidence: `src/show_profile.py`)
- CLI Runner → Candidate Scorers: scores candidates (evidence: `src/run.py`)
- Candidate Scorers → LLM Client: requests evaluations (evidence: `src/scoring.py`)
- LLM Client → LLM Provider: sends prompts (evidence: `src/llm_client.py`)
- CLI Runner → Start Extension: may extend (evidence: `src/run.py`)
- Start Extension → Candidate Scorers: rescores extension (evidence: `src/extension.py`)
- CLI Runner → Validation and Ranking: validates and ranks (evidence: `src/run.py`)
- CLI Runner → Result Exporter: exports results (evidence: `README.md`)
- CLI Runner → Run Outputs: writes run files (evidence: `README.md`)
- CLI Runner → Run Reliability: records checkpoints (evidence: `src/run.py`)
- LLM Client → App Configuration: loads settings (evidence: `src/llm_client.py`)
- Review Dashboard → Dashboard Data: loads dashboard data (evidence: `app.py`)
- Review Dashboard → Studio Operations: uses studio operations (evidence: `app.py`)
- Human Editor → Review Dashboard: reviews promos (evidence: `README.md`)
- Dashboard Data → Run Outputs: reads run data
- Studio Operations → CLI Runner: starts pipeline (evidence: `studio_ops.py`)