# azzedde/paper_to_podcast architecture

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

- Interactive diagram: https://gitdiagram.com/azzedde/paper_to_podcast
- Repository: https://github.com/azzedde/paper_to_podcast

## Overview

Paper-to-Podcast is a command-line tool that turns a research-paper PDF into a three-person conversational script and then a merged podcast MP3. The workflow extracts paper text, plans sections, generates an introduction and retrieval-grounded section dialogue, refines the script, synthesizes each persona’s voice, and merges the audio. The README also documents the planning, discussion, enhancement, and text-to-speech capabilities. Edges reflect the sampled entry point and script/audio modules; unsampled internals are not inferred.

Main entry points: [`utils/script.py`](https://github.com/azzedde/paper_to_podcast/blob/main/utils/script.py) (Script workflow), [`paper_to_podcast.py`](https://github.com/azzedde/paper_to_podcast/blob/main/paper_to_podcast.py) (Prompt chains), [`utils/audio_gen.py`](https://github.com/azzedde/paper_to_podcast/blob/main/utils/audio_gen.py) (Audio workflow), [`templates.py`](https://github.com/azzedde/paper_to_podcast/blob/main/templates.py) (Planning prompt)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Podcast workflow"]
  node_cli["CLI entry point"]
end

subgraph group_script["Script generation"]
  node_script_flow["Script workflow<br/>[script.py]"]
  node_pdf_extract["PDF extraction<br/>[script.py]"]
  node_script_chains["Prompt chains"]
  node_plan_prompt["Planning prompt<br/>[templates.py]"]
  node_intro_prompt["Introduction prompt<br/>[templates.py]"]
  node_discussion_prompt["Discussion prompt<br/>[templates.py]"]
  node_enhance_prompt["Enhancement prompt<br/>[templates.py]"]
  node_plan_parse["Plan parser<br/>[script.py]"]
end

subgraph group_retrieval["Context retrieval"]
  node_rag[("Retrieval context<br/>[script.py]")]
end

subgraph group_audio["Audio production"]
  node_audio_flow["Audio workflow<br/>[audio_gen.py]"]
  node_speaker_tts["Persona voice synthesis<br/>[audio_gen.py]"]
  node_audio_merge["MP3 merge<br/>[audio_gen.py]"]
end

node_user(("User"))
node_pdf["Research PDF"]
node_llm["OpenAI language models"]
node_openai_audio["OpenAI speech API"]
node_podcast["Podcast MP3"]

node_user -->|"runs"| node_cli
node_user -->|"provides"| node_pdf
node_pdf -->|"input path"| node_cli
node_cli -->|"generates script"| node_script_flow
node_cli -->|"generates audio"| node_audio_flow
node_script_flow -->|"extracts text"| node_pdf_extract
node_script_flow -->|"invokes chains"| node_script_chains
node_script_chains -->|"uses"| node_plan_prompt
node_script_chains -->|"uses"| node_intro_prompt
node_script_chains -->|"uses"| node_enhance_prompt
node_script_chains -->|"parses plan"| node_plan_parse
node_script_flow -->|"builds context"| node_rag
node_script_flow -->|"generates dialogue"| node_discussion_prompt
node_rag -->|"embeds text"| node_llm
node_script_flow -->|"generates script"| node_llm
node_audio_flow -->|"dispatches lines"| node_speaker_tts
node_speaker_tts -->|"synthesizes speech"| node_openai_audio
node_audio_flow -->|"merges files"| node_audio_merge
node_audio_merge -->|"exports MP3"| node_podcast

click node_cli "https://github.com/azzedde/paper_to_podcast/blob/main/paper_to_podcast.py"
click node_script_flow "https://github.com/azzedde/paper_to_podcast/blob/main/utils/script.py"
click node_pdf_extract "https://github.com/azzedde/paper_to_podcast/blob/main/utils/script.py"
click node_script_chains "https://github.com/azzedde/paper_to_podcast/blob/main/paper_to_podcast.py"
click node_plan_prompt "https://github.com/azzedde/paper_to_podcast/blob/main/templates.py"
click node_intro_prompt "https://github.com/azzedde/paper_to_podcast/blob/main/templates.py"
click node_discussion_prompt "https://github.com/azzedde/paper_to_podcast/blob/main/templates.py"
click node_enhance_prompt "https://github.com/azzedde/paper_to_podcast/blob/main/templates.py"
click node_plan_parse "https://github.com/azzedde/paper_to_podcast/blob/main/utils/script.py"
click node_rag "https://github.com/azzedde/paper_to_podcast/blob/main/utils/script.py"
click node_audio_flow "https://github.com/azzedde/paper_to_podcast/blob/main/utils/audio_gen.py"
click node_speaker_tts "https://github.com/azzedde/paper_to_podcast/blob/main/utils/audio_gen.py"
click node_audio_merge "https://github.com/azzedde/paper_to_podcast/blob/main/utils/audio_gen.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_user toneBlue
class node_script_flow,node_pdf_extract,node_script_chains,node_plan_prompt,node_intro_prompt,node_discussion_prompt,node_enhance_prompt,node_plan_parse toneAmber
class node_rag,node_openai_audio toneMint
class node_audio_flow,node_speaker_tts,node_audio_merge toneRose
class node_pdf,node_llm,node_podcast toneIndigo
```

## Components

### Podcast workflow

- [CLI entry point](https://github.com/azzedde/paper_to_podcast/blob/main/paper_to_podcast.py): `paper_to_podcast.py`

### Script generation

- [Script workflow](https://github.com/azzedde/paper_to_podcast/blob/main/utils/script.py): `utils/script.py`
- [PDF extraction](https://github.com/azzedde/paper_to_podcast/blob/main/utils/script.py): `utils/script.py`
- [Prompt chains](https://github.com/azzedde/paper_to_podcast/blob/main/paper_to_podcast.py): `paper_to_podcast.py`
- [Planning prompt](https://github.com/azzedde/paper_to_podcast/blob/main/templates.py): `templates.py`
- [Introduction prompt](https://github.com/azzedde/paper_to_podcast/blob/main/templates.py): `templates.py`
- [Discussion prompt](https://github.com/azzedde/paper_to_podcast/blob/main/templates.py): `templates.py`
- [Enhancement prompt](https://github.com/azzedde/paper_to_podcast/blob/main/templates.py): `templates.py`
- [Plan parser](https://github.com/azzedde/paper_to_podcast/blob/main/utils/script.py): `utils/script.py`

### Context retrieval

- [Retrieval context](https://github.com/azzedde/paper_to_podcast/blob/main/utils/script.py): `utils/script.py`

### Audio production

- [Audio workflow](https://github.com/azzedde/paper_to_podcast/blob/main/utils/audio_gen.py): `utils/audio_gen.py`
- [Persona voice synthesis](https://github.com/azzedde/paper_to_podcast/blob/main/utils/audio_gen.py): `utils/audio_gen.py`
- [MP3 merge](https://github.com/azzedde/paper_to_podcast/blob/main/utils/audio_gen.py): `utils/audio_gen.py`

### Other components

- **User**
- **Research PDF**
- **OpenAI language models**
- **OpenAI speech API**
- **Podcast MP3**

## Connections

- User → CLI entry point: runs (evidence: `README.md`)
- User → Research PDF: provides (evidence: `README.md`)
- Research PDF → CLI entry point: input path (evidence: `README.md`)
- CLI entry point → Script workflow: generates script (evidence: `paper_to_podcast.py`)
- CLI entry point → Audio workflow: generates audio (evidence: `paper_to_podcast.py`)
- Script workflow → PDF extraction: extracts text (evidence: `utils/script.py`)
- Script workflow → Prompt chains: invokes chains (evidence: `utils/script.py`)
- Prompt chains → Planning prompt: uses (evidence: `paper_to_podcast.py`)
- Prompt chains → Introduction prompt: uses (evidence: `paper_to_podcast.py`)
- Prompt chains → Enhancement prompt: uses (evidence: `paper_to_podcast.py`)
- Prompt chains → Plan parser: parses plan (evidence: `paper_to_podcast.py`)
- Script workflow → Retrieval context: builds context (evidence: `utils/script.py`)
- Script workflow → Discussion prompt: generates dialogue (evidence: `utils/script.py`)
- Retrieval context → OpenAI language models: embeds text (evidence: `utils/script.py`)
- Script workflow → OpenAI language models: generates script
- Audio workflow → Persona voice synthesis: dispatches lines (evidence: `utils/audio_gen.py`)
- Persona voice synthesis → OpenAI speech API: synthesizes speech (evidence: `utils/audio_gen.py`)
- Audio workflow → MP3 merge: merges files (evidence: `utils/audio_gen.py`)
- MP3 merge → Podcast MP3: exports MP3 (evidence: `utils/audio_gen.py`)
