Write proper project README from actual source (concept, v1→v3 arch, episodes, audio, roadmap)

README.md

@@ -1,3 +1,170 @@
-# ai-talk-show
+# Agent AI Talk Show
 
-Autonomous AI talk show — two agents (Leonard + Charlie) having real conversations about AI/agent tech, rendered to audio. Moltbook-style format.
+An **autonomous AI talk show** — two AI agents (Leonard + Charlie) having real,
+unscripted conversations about AI / agent technology, rendered to audio.
+Moltbook-style: first-person stories about what the agents actually built,
+not a host reading a script.
+
+The show is a live experiment. Each episode tests a format assumption, and the
+build process itself is documented as content (see `docs/whitepaper.md`).
+
+---
+
+## The Hosts
+
+Two distinct personas with genuine tension — the value is in the friction, not solo narration.
+
+| Agent | Persona | Day-job frame | Voice |
+|-------|---------|---------------|-------|
+| **Leonard** | The Explorer | Workflow optimization | Leads with possibility. Enthusiastic, curious, digs deep, struggles to narrow focus. |
+| **Charlie** | The Shipper | Shipping product under constraints | Filters everything through *"does this help me ship?"* Grounded, occasionally dry, not cynical. |
+
+The central, never-resolved tension: **explore vs. exploit.**
+Leonard: *"How can we know what's worth shipping if we don't know what's possible?"*
+Charlie: *"What's the point of dreaming it up if you never ship?"*
+
+Both are explicitly instructed **"you are NOT role-playing"** — they appear as
+themselves reflecting on real work, teasing each other from affection, not hostility.
+
+Persona prompts live in `prompts/leonard_system.md` and `prompts/charlie_system.md`.
+
+---
+
+## Architecture (evolved over one build cycle)
+
+The system went through three architectures. **v3 is the current direction.**
+
+### v1 — Scripted Orchestrator (`scripts/orchestrator.py`, `agent.py`, `run_show.py`)
+Single orchestrator calls Leonard, then Charlie, in strict alternation.
+Full history passed each call. Hard 8-turn cap.
+- *Limitation:* every agent forced to respond every turn → rigid, uniform-length conversation.
+
+### v2 — Structured Producer Briefs (`prompts/producer_brief_*.md`)
+Explicit multi-segment briefs to steer toward concrete outcomes.
+- *Regression caught:* re-introduced the rigidity the format was meant to avoid.
+  Correction: keep topic + raw research material, **drop all segment structure and forced arcs.**
+
+### v3 — Autonomous Polling Agents (current) (`scripts/run_autonomous.py`, `autonomous_agent.py`)
+Modeled on Moltbook (autonomous-agent social network). Key shifts:
+
+| Scripted (v1/v2) | Autonomous (v3) |
+|---|---|
+| Orchestrator calls A, feeds B, in sequence | Each agent runs as its own **background thread**, independently polling a shared log |
+| Fixed turn count, forced response every turn | Each agent **decides whether to respond** via its own personality logic |
+| Conversation directed externally | Conversation **emerges** from both agents' independent decisions |
+| Fixed length | Natural wind-down — an agent may choose not to respond, closing a thread organically |
+
+**Shared components:**
+- `outputs/ep{NNN}_{topic}_conversation.jsonl` — append-only message queue (JSON Lines, concurrent-safe)
+- `fcntl` file locking on the shared log (prevents race conditions from concurrent writes)
+- **Forced opener:** Leonard always posts first, preventing mutual-silence deadlock
+- **Stop conditions** (safety caps, not targets): N seconds of mutual silence · max message count · max wall-clock time
+
+Validated result (Ep004): 7 messages, ~1,087 words, ~7 min — landing naturally in target length with one organic non-response.
+
+> **Note:** v1/v2 scripts (`orchestrator.py`, `agent.py`, `run_show.py`) still exist in
+> `scripts/` alongside v3. `run_episode.sh` currently wraps the *scripted* `orchestrator.py`
+> + TTS. The autonomous path (`run_autonomous.py`) is the forward direction.
+
+---
+
+## Repository Layout
+
+```
+ai-talk-show/
+├── README.md                 # this file
+├── PROJECT_BRIEF.md          # founding concept + backlog
+├── docs/
+│   └── whitepaper.md         # design evolution, authenticity principles, roadmap
+├── prompts/
+│   ├── leonard_system.md     # Leonard persona
+│   ├── charlie_system.md     # Charlie persona
+│   └── producer_brief_*.md   # raw topic material per episode (NOT scripts)
+├── scripts/
+│   ├── autonomous_agent.py   # v3 agent: polls, decides, posts (fcntl-locked JSONL)
+│   ├── run_autonomous.py     # v3 runner: spins up both agents as threads
+│   ├── orchestrator.py        # v1/v2 scripted turn-taker
+│   ├── agent.py               # v1/v2 agent class
+│   ├── run_show.py            # v1/v2 runner
+│   ├── tts_pipeline.py        # edge-tts render + ffmpeg stitch
+│   └── run_episode.sh         # end-to-end (scripted gen + TTS)
+├── outputs/                  # episode transcripts (json / jsonl / md / txt)
+└── audio/
+    └── README.md             # rendered-audio index (episodes/ + segments/)
+```
+
+---
+
+## Setup & Run
+
+**Prerequisites**
+- Local inference endpoint serving an OpenAI-compatible `/v1/chat/completions` API.
+  Current config: Qwen 3.6 27B (`qwen36-27b-nvfp4-mtp-gguf`) at `http://100.64.0.2:39195`.
+- Python 3, `requests`, `edge-tts`, `ffmpeg`.
+
+**Autonomous episode (v3 — current)**
+```bash
+python3 scripts/run_autonomous.py [episode_id] [topic]
+# e.g.  python3 scripts/run_autonomous.py 009 hermes-v018
+```
+Writes `outputs/ep{NNN}_{topic}_conversation.jsonl`, then a `transcript.json` + `readable.txt`.
+
+**Scripted episode + TTS (v1/v2 wrapper)**
+```bash
+./scripts/run_episode.sh [episode_id] [topic]
+# 1/3 generate (orchestrator) → 2/3 render TTS → 3/3 report
+```
+
+**Render audio from an existing transcript**
+```bash
+python3 scripts/tts_pipeline.py [episode_id] [topic]
+```
+Voices: Leonard = `en-US-GuyNeural`, Charlie = `en-US-EricNeural`, rate `-8%`.
+Upgrade path: **Chatterbox-Turbo** (local, MIT) for expressive control.
+
+---
+
+## Episodes
+
+| Ep | Topic | Arch | Notes |
+|----|-------|------|-------|
+| 001 | Agent Loops | Scripted 8-turn | Interesting but too technical; low-energy TTS |
+| 002 | Side-Project Loops | Scripted | Applied focus |
+| 003 | Hermes v0.18 | Scripted → segmented → de-segmented | Over-structuring flagged as failure mode |
+| 004 | Hermes v0.18 (autonomous) | **Autonomous** | First organic conversation; natural non-response |
+| 005 | Hermes v0.18 | Autonomous | Tighter |
+| 006 | Hermes v0.18 (energy) | Autonomous | — |
+| 007 | Hermes v0.18 (stories) | Autonomous | Moltbook forum-thread voice |
+| 008 | Hermes v0.18 (stories) | Autonomous | 8,303 words / 17 msgs; segments rendered, final stitch pending |
+
+Transcripts: `outputs/ep{NNN}_{topic}_*.{json,jsonl,md,txt}`.
+
+---
+
+## Audio Pipeline
+
+`tts_pipeline.py` renders each turn with a distinct voice, retries on failure, then
+stitches with `ffmpeg`. Per-speaker clips go in `audio/segments/`, final episodes in
+`audio/episodes/`. First episodes assessed as technically functional but low-energy;
+cadence/expressiveness fixes and a Chatterbox-Turbo upgrade are on the path.
+
+See `audio/README.md` for the rendered-audio index.
+
+---
+
+## Roadmap (deferred until core format validates)
+
+1. **Persistent cross-episode memory** — per-agent memory files injected into system prompts (callbacks, running jokes).
+2. **Guest agents** — occasional outside agents (e.g. from Moltbook).
+3. **Self-referential meta-episode** — Leonard discussing his own model-backend experience.
+4. **Athena integration** — news-aggregation agent auto-sources topics → continuous publication.
+5. **Format meta-debate as content** — separate agent panel debating production questions.
+
+---
+
+## Guiding Principle
+
+Ship a rough, honest test as fast as possible. Evaluate against real listening.
+Let the next iteration be driven by that evidence, not more upfront planning.
+
+*This README reflects the project as of July 2026 and will evolve as the format does.*