# moonwalker199/kuku-recruitment-assignment-iitr26 architecture

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

- Interactive diagram: https://gitdiagram.com/moonwalker199/kuku-recruitment-assignment-iitr26
- Repository: https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26

## Overview

Kuku FM Promotional Moment Discovery is a pipeline for turning screenplay episodes into explainable, ranked promo recommendations. Users provide episode scripts through the CLI or Streamlit app; scripts are parsed or loaded, analyzed for story moments, structurally shortlisted, boundary-optimized, evaluated, deduplicated, ranked, and exported for review. The graph includes the documented stages and major source-index modules. Some orchestration details are unsampled, so documented relationships use README evidence and uncertain links are omitted.

Main entry points: [`main.py`](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/main.py) (CLI pipeline), [`src/llm/semantic_analyzer.py`](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/llm/semantic_analyzer.py) (Semantic analyzer), [`app.py`](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/app.py) (Interactive UI), [`src/preprocessing/screenplay_parser.py`](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/preprocessing/screenplay_parser.py) (Screenplay parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["CLI pipeline<br/>[main.py]"]
  node_webapp["Interactive UI<br/>[app.py]"]
end

subgraph group_content["Episode processing"]
  node_scripts["Raw scripts"]
  node_parser["Screenplay parser"]
  node_episodes["Processed episodes"]
  node_loader["Episode loader<br/>[episode_loader.py]"]
  node_windows["Candidate windows"]
end

subgraph group_analysis["AI and scoring"]
  node_analyzer["Semantic analyzer"]
  node_prompts["Analysis prompts<br/>[prompts.py]"]
  node_llmclient["LLM client<br/>[client.py]"]
  node_features["Feature extraction"]
  node_lexicons["Promo lexicons<br/>[lexicons.py]"]
  node_config["Pipeline config<br/>[config.py]"]
end

subgraph group_delivery["Ranking and outputs"]
  node_scorer["Candidate scoring<br/>[scorer.py]"]
  node_ranker["Ranking and decisions<br/>[ranker.py]"]
  node_dedup["Overlap deduplication<br/>[deduplicator.py]"]
  node_explainer["Recommendation explanations<br/>[explainer.py]"]
  node_outputs["Pipeline outputs"]
end

node_user(("Operator"))
node_provider{{"LLM provider"}}

node_user -->|"runs"| node_cli
node_user -->|"uses"| node_webapp
node_scripts -->|"parses"| node_parser
node_webapp -->|"parses uploads"| node_parser
node_parser -->|"writes JSON"| node_episodes
node_episodes -->|"loads JSON"| node_loader
node_cli -->|"loads episodes"| node_loader
node_cli -->|"analyzes episodes"| node_analyzer
node_analyzer -->|"builds prompts"| node_prompts
node_analyzer -->|"requests analysis"| node_llmclient
node_llmclient -->|"sends requests"| node_provider
node_analyzer -->|"optimizes boundaries"| node_windows
node_windows -->|"provides candidates"| node_features
node_features -->|"uses vocabulary"| node_lexicons
node_cli -->|"shortlists candidates"| node_scorer
node_scorer -->|"prioritizes candidates"| node_analyzer
node_cli -->|"evaluates promos"| node_analyzer
node_cli -->|"ranks results"| node_ranker
node_ranker -->|"removes overlaps"| node_dedup
node_cli -->|"creates explanations"| node_explainer
node_cli -->|"exports results"| node_outputs
node_webapp -->|"shows results"| node_outputs
node_config -->|"configures pipeline"| node_cli
node_config -->|"sets LLM stages"| node_analyzer

click node_cli "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/main.py"
click node_webapp "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/app.py"
click node_scripts "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/tree/main/data/raw"
click node_parser "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/preprocessing/screenplay_parser.py"
click node_episodes "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/tree/main/data/processed"
click node_loader "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/ingestion/episode_loader.py"
click node_windows "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/candidate_generation/window_generator.py"
click node_analyzer "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/llm/semantic_analyzer.py"
click node_prompts "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/llm/prompts.py"
click node_llmclient "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/llm/client.py"
click node_features "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/feature_extraction/feature_extractor.py"
click node_lexicons "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/feature_extraction/lexicons.py"
click node_config "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/config.py"
click node_scorer "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/ranking/scorer.py"
click node_ranker "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/ranking/ranker.py"
click node_dedup "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/ranking/deduplicator.py"
click node_explainer "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/ranking/explainer.py"
click node_outputs "https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/tree/main/outputs"

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_webapp toneBlue
class node_scripts,node_parser,node_episodes,node_loader,node_windows toneAmber
class node_analyzer,node_prompts,node_llmclient,node_features,node_lexicons,node_config toneMint
class node_scorer,node_ranker,node_dedup,node_explainer,node_outputs toneRose
class node_user,node_provider toneIndigo
```

## Components

### User entry

- [CLI pipeline](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/main.py): `main.py`
- [Interactive UI](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/app.py): `app.py`

### Episode processing

- [Raw scripts](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/tree/main/data/raw): `data/raw`
- [Screenplay parser](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/preprocessing/screenplay_parser.py): `src/preprocessing/screenplay_parser.py`
- [Processed episodes](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/tree/main/data/processed): `data/processed`
- [Episode loader](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/ingestion/episode_loader.py): `src/ingestion/episode_loader.py`
- [Candidate windows](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/candidate_generation/window_generator.py): `src/candidate_generation/window_generator.py`

### AI and scoring

- [Semantic analyzer](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/llm/semantic_analyzer.py): `src/llm/semantic_analyzer.py`
- [Analysis prompts](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/llm/prompts.py): `src/llm/prompts.py`
- [LLM client](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/llm/client.py): `src/llm/client.py`
- [Feature extraction](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/feature_extraction/feature_extractor.py): `src/feature_extraction/feature_extractor.py`
- [Promo lexicons](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/feature_extraction/lexicons.py): `src/feature_extraction/lexicons.py`
- [Pipeline config](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/config.py): `src/config.py`

### Ranking and outputs

- [Candidate scoring](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/ranking/scorer.py): `src/ranking/scorer.py`
- [Ranking and decisions](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/ranking/ranker.py): `src/ranking/ranker.py`
- [Overlap deduplication](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/ranking/deduplicator.py): `src/ranking/deduplicator.py`
- [Recommendation explanations](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/blob/main/src/ranking/explainer.py): `src/ranking/explainer.py`
- [Pipeline outputs](https://github.com/moonwalker199/kuku-recruitment-assignment-iitr26/tree/main/outputs): `outputs`

### Other components

- **Operator**
- **LLM provider**

## Connections

- Operator → CLI pipeline: runs (evidence: `README.md`)
- Operator → Interactive UI: uses (evidence: `README.md`)
- Raw scripts → Screenplay parser: parses (evidence: `README.md`)
- Interactive UI → Screenplay parser: parses uploads (evidence: `app.py`)
- Screenplay parser → Processed episodes: writes JSON (evidence: `README.md`)
- Processed episodes → Episode loader: loads JSON (evidence: `src/ingestion/episode_loader.py`)
- CLI pipeline → Episode loader: loads episodes (evidence: `main.py`)
- CLI pipeline → Semantic analyzer: analyzes episodes (evidence: `main.py`)
- Semantic analyzer → Analysis prompts: builds prompts (evidence: `src/llm/semantic_analyzer.py`)
- Semantic analyzer → LLM client: requests analysis (evidence: `src/llm/semantic_analyzer.py`)
- LLM client → LLM provider: sends requests (evidence: `README.md`)
- Semantic analyzer → Candidate windows: optimizes boundaries (evidence: `src/llm/semantic_analyzer.py`)
- Candidate windows → Feature extraction: provides candidates (evidence: `src/feature_extraction/feature_extractor.py`)
- Feature extraction → Promo lexicons: uses vocabulary (evidence: `src/feature_extraction/feature_extractor.py`)
- CLI pipeline → Candidate scoring: shortlists candidates (evidence: `README.md`)
- Candidate scoring → Semantic analyzer: prioritizes candidates (evidence: `README.md`)
- CLI pipeline → Semantic analyzer: evaluates promos (evidence: `README.md`)
- CLI pipeline → Ranking and decisions: ranks results (evidence: `README.md`)
- Ranking and decisions → Overlap deduplication: removes overlaps (evidence: `src/ranking/ranker.py`)
- CLI pipeline → Recommendation explanations: creates explanations (evidence: `README.md`)
- CLI pipeline → Pipeline outputs: exports results (evidence: `README.md`)
- Interactive UI → Pipeline outputs: shows results (evidence: `app.py`)
- Pipeline config → CLI pipeline: configures pipeline (evidence: `README.md`)
- Pipeline config → Semantic analyzer: sets LLM stages (evidence: `src/config.py`)