🎙️ Guidelines Podcast Generator

Turns medical/professional guidelines into a two-host podcast episode, delivered via an RSS feed you subscribe to in any podcast app.

Pipeline:

Guidelines text → Hermes Nous (script) → OpenAI TTS (audio) → RSS feed → your car

---

Prerequisites

These need to be installed on agent37 before you start.

1. Python 3.11+

python3 --version  # should be 3.11 or newer

2. ffmpeg

pydub uses ffmpeg under the hood for audio encoding. Install it with:

sudo apt install ffmpeg -y

3. Your Hermes Nous instance

This app assumes Hermes is already running and accessible at a local port. If you're using Ollama:

ollama serve       # starts the API server on port 11434
ollama list        # shows available models — note the exact name

---

Installation

# 1. Clone / copy the project to agent37
cd /opt
git clone ... podcast_generator    # or scp the folder
cd podcast_generator

# 2. Create a Python virtual environment
#    (keeps dependencies isolated from the system Python)
python3 -m venv venv
source venv/bin/activate

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Set up your configuration
cp .env.example .env
nano .env          # fill in your OpenAI key, VPS IP, and model name

---

Running the Server

# Make sure your venv is active
source venv/bin/activate

# Start the API server on port 8080
uvicorn main:app --host 0.0.0.0 --port 8080

Open a firewall port if needed:

sudo ufw allow 8080

Visit http://YOUR_VPS_IP:8080 to confirm it's running.

---

Generating Your First Episode

Option A — Interactive API docs (easiest)

Open http://YOUR_VPS_IP:8080/docs in your browser. Click POST /generate → Try it out → paste your guidelines → Execute.

Option B — curl from terminal

curl -X POST http://YOUR_VPS_IP:8080/generate \
  -H "Content-Type: application/json" \
  -d '{
    "source_text": "paste your full guidelines text here...",
    "title": "NICE Guidelines on Occupational Health 2024",
    "description": "Covering fitness to work assessments and return-to-work protocols."
  }'

You'll get back:

{
  "job_id": "abc12345-...",
  "status": "queued",
  "message": "Generation started. Poll /status/abc12345-... for progress."
}

Checking progress

curl http://YOUR_VPS_IP:8080/status/abc12345-...

Status values in order:

• queued → accepted, not started yet
• generating_script → Hermes is writing the dialogue (~30-90 seconds)
• rendering_audio → OpenAI TTS is rendering lines (~2-4 minutes for 60 lines)
• registering → adding to RSS feed
• done → episode is ready, includes episode_url

---

Subscribing in Your Podcast App

Add this URL to any podcast app:

http://YOUR_VPS_IP:8080/feed.xml

App	How to add a custom feed
Overcast (iOS)	Add Podcast → paste URL
Pocket Casts (iOS/Android)	+ → Add URL
Apple Podcasts	Library → ... → Follow a Show → paste URL
AntennaPod (Android)	+ → Add podcast → URL

New episodes appear automatically after each generation run. Hit play in the car.

---

Running as a Persistent Service (so it survives reboots)

Create a systemd service file:

sudo nano /etc/systemd/system/podcast-generator.service

Paste:

[Unit]
Description=Guidelines Podcast Generator
After=network.target

[Service]
User=YOUR_USERNAME
WorkingDirectory=/opt/podcast_generator
ExecStart=/opt/podcast_generator/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8080
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable podcast-generator
sudo systemctl start podcast-generator
sudo systemctl status podcast-generator  # should show "active (running)"

---

Troubleshooting

"Connection refused" on Hermes endpoint → Make sure your local LLM server is running. curl http://localhost:11434/v1/models should return a list.

Script is dry / sounds like a lecture → In generate.py, tweak the SYSTEM_PROMPT. Add more explicit instructions like "hosts should disagree occasionally" or "use concrete examples".

Audio has weird pauses / cuts → Adjust PAUSE_BETWEEN_TURNS_MS in tts.py. 400ms is a good default but you may want 200–600ms.

Episode too short → Increase max_tokens in generate.py (currently 4000). Or add "aim for 100 exchanges" to the prompt.

TTS is slow → Expected. Each line is a separate API call. 60 lines ≈ 60 requests. Switch to tts-1 (faster, slightly lower quality) by changing TTS_MODEL=tts-1 in .env.