_<timestamp>.mp3` 5. **Encodes** the file as a base64 string — because Fetch.ai agent messages are JSON, a raw binary MP3 cannot be sent directly via `ctx.send()` The base64 payload and the local file path are both returned to the Orchestrator in an `AudioResponse` model. --- ### Action 5 — Final Delivery (Orchestrator) The Orchestrator receives the `AudioResponse`, then sends back a `ChatMessage` to ASI:One containing: - The episode title generated by the Scriptwriter - The number of dialogue lines - The local path to the saved MP3 - A 4-line script preview so you can see what the hosts are saying --- ## Why This Architecture Is Bulletproof | Design choice | Why it matters | |---------------|----------------| | Separate Extractor and Scriptwriter LLM calls | If you ask one model to read 40 pages AND write a funny script simultaneously, it loses the exact metrics. Splitting the calls keeps each model focused on one task. | | Pydantic `Model` schemas at every hop | The Voice Studio physically cannot receive a malformed script. Every message is validated before it moves forward. | | Parallel TTS via `asyncio.gather` | A 12-line script with sequential calls would take ~60 s. Parallel cuts it to ~6 s. | | Orchestrator as the sole public-facing agent | The three sub-agents never appear in ASI:One's discovery index. Only the Orchestrator registers a mailbox, keeping the surface area small and predictable. | | Base64 encoding for the final audio | Fetch.ai agent messages are JSON. Encoding the MP3 as base64 lets it travel through `ctx.send()` without corruption. | --- ## How to Interact with the Agent on ASI:One ### Method 1 — Paste PDF text directly In the ASI:One chat, paste the full extracted text of any research paper and add a prompt on the same message: ``` [paste the full paper text here] Turn this into a 3-minute debate. ``` The agent detects that the message body is longer than 300 characters and treats it as the document. ### Method 2 — Server-side file path If the agent is running on your local machine or a server you control, send the absolute path to a PDF file: ``` /home/user/papers/my_research.pdf ``` The Orchestrator reads the file directly from disk using `pdfplumber`. ### What you get back The agent replies with: ``` Podcast ready! Episode: "59.1 vs 39.63: Is Deterministic Scaffolding the Real Winner?" 12 lines • saved to: output/podcast_59_1_vs_39_63_20260327_142301.mp3 Script preview: [A] So wait — the baseline was only 39.63? That's not even 40 percent... [B] Right, exactly. But isolate the ADW repair set and it drops to 33.54... [A] Okay but that union result — how reproducible is that actually? [B] That's the thing — they ran it across three separate model checkpoints... ... ``` --- ## Example Queries These are real prompts you can send to the agent on ASI:One. Paste the full PDF text first, then append one of the prompts below. --- ### Research Papers **General — quick debate** ``` [paste paper text] Turn this into a 3-minute debate. ``` **Machine Learning — emphasise numbers** ``` [paste paper text] Make a podcast where Host B defends every benchmark claim with exact numbers and Host A won't accept anything without a confidence interval. ``` **Biology / Medicine — lay-audience friendly** ``` [paste paper text] Create a debate podcast. Host A is a curious science journalist with no PhD, Host B is the lead author. Keep the jargon accessible but don't lose the nuance. ``` **Economics / Policy — adversarial tone** ``` [paste paper text] Turn this paper into a heated 4-minute podcast debate. Host A thinks the methodology is flawed. Host B has to defend every assumption. End on an unresolved disagreement. ``` --- ### Format Variations **Shorter episode** ``` [paste paper text] Summarise this as a fast 90-second podcast. Two hosts, punchy lines, no filler. ``` **Longer, deeper episode** ``` [paste paper text] I want a full 6-minute podcast debate — go deep on the controversial_point, make sure at least 5 key metrics are cited verbatim, and close with an open question the paper never answers. ``` **Solo explainer instead of debate** ``` [paste paper text] Skip the debate format. One host walks me through the 3 biggest ideas in this paper as if explaining to a smart undergraduate. 8–10 lines. ``` --- ### Local File Path (server-side mode) ``` C:\Users\you\papers\attention_is_all_you_need.pdf ``` ``` /home/ubuntu/papers/gpt4_technical_report.pdf Turn this into a 3-minute debate focusing on the safety evaluations section. ``` --- ### What Changes Based on Your Prompt | Prompt element | What the agent adjusts | |----------------|------------------------| | `"3-minute"` / `"90-second"` / `"6-minute"` | Target line count sent to the Scriptwriter (10, 6, or 18 lines) | | `"emphasise numbers"` | Scriptwriter system prompt is told to cite ≥5 metrics instead of the default 3 | | `"lay-audience friendly"` | Persona descriptions for Host A and B are rewritten by the Orchestrator before dispatch | | `"heated"` / `"adversarial"` | Tone instruction appended to the Showrunner prompt | | Bare file path (no extra text) | Orchestrator falls back to the default `"Turn this into a 3-minute debate."` prompt | --- ## Data Schemas (Typed Contracts Between Agents) ```python # 1. Orchestrator → Extractor class ExtractRequest(Model): document_text: str # raw PDF text, truncated to 50k chars session_id: str # 2. Extractor → Orchestrator → Scriptwriter class ResearchInsights(Model): core_thesis: str key_metrics: List[str] # exact numbers from the paper controversial_point: str session_id: str # 3. Scriptwriter → Orchestrator → Voice Studio class DialogueLine(Model): speaker: str # "HostA" or "HostB" text: str class PodcastScript(Model): lines: List[DialogueLine] topic_title: str session_id: str # 4. Voice Studio → Orchestrator class AudioResponse(Model): audio_base64: str # base64-encoded final MP3 audio_path: str # local path where MP3 was saved session_id: str line_count: int ``` --- ## Architecture Diagram ``` ASI:One Chat | (Agent Chat Protocol) v +----------------------------------------------------------+ | Orchestrator (port 8000) | | Action 1: Strip PDF text with pdfplumber | | Action 3: Dispatch to Extractor (send_and_receive) | | Action 4: Route Insights -> Scriptwriter | | Action 4: Route Script -> Voice Studio | | Action 5: Deliver MP3 path + preview back to ASI:One | +--------+-----------------+--------------+---------------+ | | | ExtractRequest ResearchInsights PodcastScript v v v +----------------+ +-------------+ +----------------------+ | RAG Extractor | | Scriptwriter| | Voice Studio | | (port 8001) | | (port 8002) | | (port 8003) | | | | | | | | Action 2: | | Action 3: | | Action 4: | | GPT-4o-mini | | GPT-4o- | | asyncio.gather | | JSON mode | | mini | | all TTS calls | | -> 3 facts | | -> 10-14 | | pydub stitch | | | | lines | | -> final .mp3 | +----------------+ +-------------+ +----------------------+ ``` --- ## Prerequisites | Tool | Install | |------|---------| | Python 3.10+ | [python.org](https://python.org) | | ffmpeg | `winget install ffmpeg` · `brew install ffmpeg` · `apt install ffmpeg` | | OpenAI API key | [platform.openai.com](https://platform.openai.com) | | Agentverse API key | [agentverse.ai](https://agentverse.ai) | --- ## Setup ```powershell # 1. Navigate to the project cd "Fetch.ai - Agent Project/pdf-podcast-agent" # 2. Create and activate virtual environment python -m venv venv .\venv\Scripts\Activate.ps1 # Windows # source venv/bin/activate # macOS / Linux # 3. Install all dependencies pip install -r requirements.txt # 4. Copy env file and fill in your API keys copy .env.example .env ``` Minimum `.env` values: ``` OPENAI_API_KEY=sk-... AGENTVERSE_API_KEY=AV-... EXTRACTOR_ADDRESS= # from: python get_addresses.py SCRIPTWRITER_ADDRESS= VOICE_STUDIO_ADDRESS= ``` --- ## Running (4 terminals) ```powershell # First — print all agent addresses and add them to .env python get_addresses.py # Terminal 1 python extractor_agent.py # Terminal 2 python scriptwriter_agent.py # Terminal 3 python voice_studio_agent.py # Terminal 4 (start last) python orchestrator.py ``` --- ## Connecting to ASI:One 1. With the Orchestrator running, copy the Inspector URL from its startup log: ``` Agent inspector available at https://agentverse.ai/inspect/?uri=... ``` 2. Open that URL in your browser 3. Click **Connect** → **Mailbox** → **Finish** 4. Go to [asi1.ai](https://asi1.ai) and find the agent by name `pdf_podcast_orchestrator` or by its address --- ## Local Test (no ASI:One needed) ```powershell python test_pipeline.py "C:\absolute\path\to\paper.pdf" ``` --- ## Configuration | Variable | Default | Description | |----------|---------|-------------| | `OPENAI_API_KEY` | — | **Required** | | `AGENTVERSE_API_KEY` | — | **Required** for ASI:One mailbox | | `EXTRACTOR_ADDRESS` | — | From `get_addresses.py` | | `SCRIPTWRITER_ADDRESS` | — | From `get_addresses.py` | | `VOICE_STUDIO_ADDRESS` | — | From `get_addresses.py` | | `EXTRACTION_MODEL` | `gpt-4o-mini` | LLM for extraction | | `SCRIPTWRITER_MODEL` | `gpt-4o-mini` | LLM for scripting | | `TTS_MODEL` | `tts-1` | `tts-1` (fast) or `tts-1-hd` (HD) | | `VOICE_HOST_A` | `alloy` | Voice for the Skeptic host | | `VOICE_HOST_B` | `echo` | Voice for the Expert host | | `SILENCE_MS` | `400` | Gap between dialogue lines (ms) | | `OUTPUT_DIR` | `output` | Where MP3 files are saved | --- ## Project Structure ``` pdf-podcast-agent/ ├── schemas.py <- Pydantic models (typed contracts between agents) ├── extractor_agent.py <- Agent 1: RAG extraction port 8001 ├── scriptwriter_agent.py <- Agent 2: Debate script port 8002 ├── voice_studio_agent.py <- Agent 3: TTS + stitch port 8003 ├── orchestrator.py <- Orchestrator + chat proto port 8000 ├── get_addresses.py <- Prints agent addresses (run first) ├── run.py <- Optional: starts all 4 as subprocesses ├── test_pipeline.py <- Local smoke test ├── requirements.txt ├── .env.example ├── render.yaml <- Render.com one-click deployment └── output/ <- Generated MP3s land here ``` </article></body></html>

# PDF-to-Podcast Agent > Turn any 40-page technical PDF into a playable 2-host debate podcast — right inside ASI:One. > Built on the Fetch.ai uAgents framework for the ASI:One Innovation Lab. --- ## What This Agent Does Reading dense research papers causes serious fatigue. This agent replicates the "NotebookLM" podcast feature: you hand it a technical PDF, it hands you back an MP3 of two AI hosts debating the paper's key findings. **Trigger in ASI:One:** > Paste the text of any research PDF and type: *"Turn this into a 3-minute debate."* The agent handles everything else — parsing, scriptwriting, voice synthesis, and audio stitching — and replies with the episode title, a script preview, and the path to the saved MP3 file. --- ## Agent Actions ### Action 1 — PDF Parsing (Orchestrator) The Orchestrator is the only agent that talks to the outside world. When it receives a message from ASI:One it: 1. Strips all text from the uploaded PDF using `pdfplumber` 2. Generates a unique `session_id` for state tracking 3. Dispatches the raw text to the RAG Extractor via `ctx.send_and_receive` The PDF is dropped immediately after extraction — it is never passed between sub-agents, keeping message sizes small. --- ### Action 2 — RAG Extraction (Agent 1) **Goal:** Turn 40 pages of dense academic text into three bullet points. The RAG Extractor receives the raw document text and makes a single call to `AsyncOpenAI` with `response_format={"type": "json_object"}` (JSON mode), forcing the LLM to return only structured data — never conversational prose. **System prompt instructs the model to extract exactly:** - `core_thesis` — the central argument in 2–3 sentences - `key_metrics` — 4–6 exact numbers or percentages pulled verbatim from the text - `controversial_point` — the most surprising or debatable claim **Example output for an SLM research paper:** ```json { "core_thesis": "Deterministic scaffolding applied to sub-1B models achieves pass@1 rates that exceed much larger models on HumanEval.", "key_metrics": ["Baseline: 39.63", "ADW: 33.54", "ADB from ADW: 38.53", "ADW ∪ ADB union: 59.1", "Beats baseline by +19.47 points"], "controversial_point": "The union of ADW and ADB repair sets outperforms the individual sets, suggesting complementary failure modes." } ``` The 40-page document is then discarded. Only this tight JSON payload moves forward in the pipeline, preventing token waste in downstream calls. --- ### Action 3 — Script Generation (Agent 2) **Goal:** Turn sterile JSON facts into natural, engaging podcast banter. The Scriptwriter receives the `ResearchInsights` payload and fires a second LLM call using a "Showrunner" system prompt that defines two distinct host personas: | Host | Persona | Voice | |------|---------|-------| | **Host A** | The Skeptic — pushes back, demands proof, asks "but how?" | `alloy` | | **Host B** | The Expert — defends the work with exact numbers | `echo` | **Rules enforced by the prompt:** - 10–14 lines of back-and-forth dialogue - Host B must cite at least 3 of the extracted `key_metrics` by exact value - The `controversial_point` must be debated directly - Natural speech patterns: *"Wait, really?"*, *"Right, but—"*, *"Okay hold on…"* - No stage directions, music cues, or cheesy intros - Ends on an unresolved tension or open question **Example script output:** ```json [ {"speaker": "HostA", "text": "So wait — the baseline was only 39.63? That's not even 40 percent pass rate."}, {"speaker": "HostB", "text": "Right, exactly. But isolate the ADW repair set and it drops to 33.54 — which sounds worse until you take the union with ADB. That spikes to 59.1. It completely crushes the baseline."}, {"speaker": "HostA", "text": "Okay but that union result — how reproducible is that actually?"} ] ``` Because the output is validated against the `PodcastScript` Pydantic model, the Voice Studio can never receive a malformed script. --- ### Action 4 — Voice Synthesis & Stitching (Agent 3) **Goal:** Turn the JSON script into a single playable MP3 file. The Voice Studio is the most technically complex agent. It: 1. **Parallelises all TTS calls** using `asyncio.gather` — every dialogue line is sent to the OpenAI TTS API simultaneously, cutting generation time by ~10× compared to sequential calls 2. **Routes voices** by speaker: `HostA → alloy`, `HostB → echo` 3. **Stitches** the returned MP3 byte chunks into one file using `pydub`, with a configurable silence gap (default 400 ms) inserted between lines for natural pacing 4. **Saves** the final MP3 to `output/podcast__<timestamp>.mp3` 5. **Encodes** the file as a base64 string — because Fetch.ai agent messages are JSON, a raw binary MP3 cannot be sent directly via `ctx.send()` The base64 payload and the local file path are both returned to the Orchestrator in an `AudioResponse` model. --- ### Action 5 — Final Delivery (Orchestrator) The Orchestrator receives the `AudioResponse`, then sends back a `ChatMessage` to ASI:One containing: - The episode title generated by the Scriptwriter - The number of dialogue lines - The local path to the saved MP3 - A 4-line script preview so you can see what the hosts are saying --- ## Why This Architecture Is Bulletproof | Design choice | Why it matters | |---------------|----------------| | Separate Extractor and Scriptwriter LLM calls | If you ask one model to read 40 pages AND write a funny script simultaneously, it loses the exact metrics. Splitting the calls keeps each model focused on one task. | | Pydantic `Model` schemas at every hop | The Voice Studio physically cannot receive a malformed script. Every message is validated before it moves forward. | | Parallel TTS via `asyncio.gather` | A 12-line script with sequential calls would take ~60 s. Parallel cuts it to ~6 s. | | Orchestrator as the sole public-facing agent | The three sub-agents never appear in ASI:One's discovery index. Only the Orchestrator registers a mailbox, keeping the surface area small and predictable. | | Base64 encoding for the final audio | Fetch.ai agent messages are JSON. Encoding the MP3 as base64 lets it travel through `ctx.send()` without corruption. | --- ## How to Interact with the Agent on ASI:One ### Method 1 — Paste PDF text directly In the ASI:One chat, paste the full extracted text of any research paper and add a prompt on the same message: ``` [paste the full paper text here] Turn this into a 3-minute debate. ``` The agent detects that the message body is longer than 300 characters and treats it as the document. ### Method 2 — Server-side file path If the agent is running on your local machine or a server you control, send the absolute path to a PDF file: ``` /home/user/papers/my_research.pdf ``` The Orchestrator reads the file directly from disk using `pdfplumber`. ### What you get back The agent replies with: ``` Podcast ready! Episode: "59.1 vs 39.63: Is Deterministic Scaffolding the Real Winner?" 12 lines • saved to: output/podcast_59_1_vs_39_63_20260327_142301.mp3 Script preview: [A] So wait — the baseline was only 39.63? That's not even 40 percent... [B] Right, exactly. But isolate the ADW repair set and it drops to 33.54... [A] Okay but that union result — how reproducible is that actually? [B] That's the thing — they ran it across three separate model checkpoints... ... ``` --- ## Example Queries These are real prompts you can send to the agent on ASI:One. Paste the full PDF text first, then append one of the prompts below. --- ### Research Papers **General — quick debate** ``` [paste paper text] Turn this into a 3-minute debate. ``` **Machine Learning — emphasise numbers** ``` [paste paper text] Make a podcast where Host B defends every benchmark claim with exact numbers and Host A won't accept anything without a confidence interval. ``` **Biology / Medicine — lay-audience friendly** ``` [paste paper text] Create a debate podcast. Host A is a curious science journalist with no PhD, Host B is the lead author. Keep the jargon accessible but don't lose the nuance. ``` **Economics / Policy — adversarial tone** ``` [paste paper text] Turn this paper into a heated 4-minute podcast debate. Host A thinks the methodology is flawed. Host B has to defend every assumption. End on an unresolved disagreement. ``` --- ### Format Variations **Shorter episode** ``` [paste paper text] Summarise this as a fast 90-second podcast. Two hosts, punchy lines, no filler. ``` **Longer, deeper episode** ``` [paste paper text] I want a full 6-minute podcast debate — go deep on the controversial_point, make sure at least 5 key metrics are cited verbatim, and close with an open question the paper never answers. ``` **Solo explainer instead of debate** ``` [paste paper text] Skip the debate format. One host walks me through the 3 biggest ideas in this paper as if explaining to a smart undergraduate. 8–10 lines. ``` --- ### Local File Path (server-side mode) ``` C:\Users\you\papers\attention_is_all_you_need.pdf ``` ``` /home/ubuntu/papers/gpt4_technical_report.pdf Turn this into a 3-minute debate focusing on the safety evaluations section. ``` --- ### What Changes Based on Your Prompt | Prompt element | What the agent adjusts | |----------------|------------------------| | `"3-minute"` / `"90-second"` / `"6-minute"` | Target line count sent to the Scriptwriter (10, 6, or 18 lines) | | `"emphasise numbers"` | Scriptwriter system prompt is told to cite ≥5 metrics instead of the default 3 | | `"lay-audience friendly"` | Persona descriptions for Host A and B are rewritten by the Orchestrator before dispatch | | `"heated"` / `"adversarial"` | Tone instruction appended to the Showrunner prompt | | Bare file path (no extra text) | Orchestrator falls back to the default `"Turn this into a 3-minute debate."` prompt | --- ## Data Schemas (Typed Contracts Between Agents) ```python # 1. Orchestrator → Extractor class ExtractRequest(Model): document_text: str # raw PDF text, truncated to 50k chars session_id: str # 2. Extractor → Orchestrator → Scriptwriter class ResearchInsights(Model): core_thesis: str key_metrics: List[str] # exact numbers from the paper controversial_point: str session_id: str # 3. Scriptwriter → Orchestrator → Voice Studio class DialogueLine(Model): speaker: str # "HostA" or "HostB" text: str class PodcastScript(Model): lines: List[DialogueLine] topic_title: str session_id: str # 4. Voice Studio → Orchestrator class AudioResponse(Model): audio_base64: str # base64-encoded final MP3 audio_path: str # local path where MP3 was saved session_id: str line_count: int ``` --- ## Architecture Diagram ``` ASI:One Chat | (Agent Chat Protocol) v +----------------------------------------------------------+ | Orchestrator (port 8000) | | Action 1: Strip PDF text with pdfplumber | | Action 3: Dispatch to Extractor (send_and_receive) | | Action 4: Route Insights -> Scriptwriter | | Action 4: Route Script -> Voice Studio | | Action 5: Deliver MP3 path + preview back to ASI:One | +--------+-----------------+--------------+---------------+ | | | ExtractRequest ResearchInsights PodcastScript v v v +----------------+ +-------------+ +----------------------+ | RAG Extractor | | Scriptwriter| | Voice Studio | | (port 8001) | | (port 8002) | | (port 8003) | | | | | | | | Action 2: | | Action 3: | | Action 4: | | GPT-4o-mini | | GPT-4o- | | asyncio.gather | | JSON mode | | mini | | all TTS calls | | -> 3 facts | | -> 10-14 | | pydub stitch | | | | lines | | -> final .mp3 | +----------------+ +-------------+ +----------------------+ ``` --- ## Prerequisites | Tool | Install | |------|---------| | Python 3.10+ | [python.org](https://python.org) | | ffmpeg | `winget install ffmpeg` · `brew install ffmpeg` · `apt install ffmpeg` | | OpenAI API key | [platform.openai.com](https://platform.openai.com) | | Agentverse API key | [agentverse.ai](https://agentverse.ai) | --- ## Setup ```powershell # 1. Navigate to the project cd "Fetch.ai - Agent Project/pdf-podcast-agent" # 2. Create and activate virtual environment python -m venv venv .\venv\Scripts\Activate.ps1 # Windows # source venv/bin/activate # macOS / Linux # 3. Install all dependencies pip install -r requirements.txt # 4. Copy env file and fill in your API keys copy .env.example .env ``` Minimum `.env` values: ``` OPENAI_API_KEY=sk-... AGENTVERSE_API_KEY=AV-... EXTRACTOR_ADDRESS= # from: python get_addresses.py SCRIPTWRITER_ADDRESS= VOICE_STUDIO_ADDRESS= ``` --- ## Running (4 terminals) ```powershell # First — print all agent addresses and add them to .env python get_addresses.py # Terminal 1 python extractor_agent.py # Terminal 2 python scriptwriter_agent.py # Terminal 3 python voice_studio_agent.py # Terminal 4 (start last) python orchestrator.py ``` --- ## Connecting to ASI:One 1. With the Orchestrator running, copy the Inspector URL from its startup log: ``` Agent inspector available at https://agentverse.ai/inspect/?uri=... ``` 2. Open that URL in your browser 3. Click **Connect** → **Mailbox** → **Finish** 4. Go to [asi1.ai](https://asi1.ai) and find the agent by name `pdf_podcast_orchestrator` or by its address --- ## Local Test (no ASI:One needed) ```powershell python test_pipeline.py "C:\absolute\path\to\paper.pdf" ``` --- ## Configuration | Variable | Default | Description | |----------|---------|-------------| | `OPENAI_API_KEY` | — | **Required** | | `AGENTVERSE_API_KEY` | — | **Required** for ASI:One mailbox | | `EXTRACTOR_ADDRESS` | — | From `get_addresses.py` | | `SCRIPTWRITER_ADDRESS` | — | From `get_addresses.py` | | `VOICE_STUDIO_ADDRESS` | — | From `get_addresses.py` | | `EXTRACTION_MODEL` | `gpt-4o-mini` | LLM for extraction | | `SCRIPTWRITER_MODEL` | `gpt-4o-mini` | LLM for scripting | | `TTS_MODEL` | `tts-1` | `tts-1` (fast) or `tts-1-hd` (HD) | | `VOICE_HOST_A` | `alloy` | Voice for the Skeptic host | | `VOICE_HOST_B` | `echo` | Voice for the Expert host | | `SILENCE_MS` | `400` | Gap between dialogue lines (ms) | | `OUTPUT_DIR` | `output` | Where MP3 files are saved | --- ## Project Structure ``` pdf-podcast-agent/ ├── schemas.py <- Pydantic models (typed contracts between agents) ├── extractor_agent.py <- Agent 1: RAG extraction port 8001 ├── scriptwriter_agent.py <- Agent 2: Debate script port 8002 ├── voice_studio_agent.py <- Agent 3: TTS + stitch port 8003 ├── orchestrator.py <- Orchestrator + chat proto port 8000 ├── get_addresses.py <- Prints agent addresses (run first) ├── run.py <- Optional: starts all 4 as subprocesses ├── test_pipeline.py <- Local smoke test ├── requirements.txt ├── .env.example ├── render.yaml <- Render.com one-click deployment └── output/ <- Generated MP3s land here ``` </article></body></html>