How sanand0/generative-ai-group works
Project Type and Purpose
• This is an open-source, Python-based CLI tool (and library) that automates the transformation of a WhatsApp group JSON export into a weekly podcast.
• It performs a staged data-processing pipeline: reading/filtering messages → threading into weekly transcripts → generating a two-host dialogue script via OpenAI Chat API → producing per-speaker TTS audio → concatenating into an MP3 → releasing via GitHub.
Key Components
a. Inputs & Configuration
• gen-ai-messages.json – raw WhatsApp scrape JSON
• config.toml – voice/style and prompt overrides
• Environment: OPENAI_API_KEY, ffmpeg in PATH
b. CLI Entrypoint
• podcast.py invoked via uv run podcast.py
c. Core Pipeline Modules
1. load_messages()
2. group_by_week()
3. build_threads()
4. render_message() → writes weekly/messages.txt
5. get_podcast_script() → calls OpenAI Chat Completion (gpt-4.1-mini) → writes weekly/podcast.md
6. generate_podcast_audio()
• splits script by speaker
• calls OpenAI TTS (gpt-4o-mini-tts) → writes .opus files
• invokes ffmpeg to concatenate → weekly/podcast.mp3
d. Outputs
• {WEEK}/messages.txt, podcast.md, *.opus, podcast.mp3
• podcast.xml (RSS feed)
e. Release Automation
• GitHub Releases via gh release commands
External Services & Tools
• OpenAI Chat Completion API (script generation)
• OpenAI TTS API (audio synthesis)
• ffmpeg (audio concatenation)
• GitHub CLI (release management)
Relationships and Data Flows
• JSON Export → [load_messages] → filtered messages
→ [group_by_week] → per-week buckets
→ [build_threads] → threaded data
→ [render_message] → messages.txt
→ [get_podcast_script] → podcast.md (via Chat API)
→ [generate_podcast_audio]
––TTS API calls per speaker → .opus
––ffmpeg concat → podcast.mp3
→ [gh release] → remote GitHub release & podcast.xml
Architectural Patterns & Principles
• Linear pipeline: each stage reads from FS or in-memory object, writes artifacts for the next stage
• Modular functions: clear single responsibility for parsing, grouping, rendering, API interaction, and file I/O
• Configurable via TOML for easy extension and voice/prompt tuning