add images and edit readme

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -14,4 +14,122 @@ tags:
   - building-mcp-track-creative
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 📺 The Emergent Show
+
+### The world's first 24/7 Autonomous AI Livestream orchestrated via Model Context Protocol.
+
+**The Emergent Show** is a fully autonomous Live Show where the Host, TV Crew, Guard, Audience, and Guests are all AI Agents. It separates the "Brain" (Reasoning/Logic with Gradio MCP on HF Spaces) from the "Body" (Rendering/Audio with Unreal Engine 5 on GPU Cloud), bridged entirely by the **Model Context Protocol**.
+
+---
+
+## 🏗️ The Architecture
+
+### 1. Gradio MCP Server (Agents + Orchestration)
+**Hosted here on Hugging Face Spaces.**
+It manages the show flow, guest connections via MCP, and safety guardrails. It uses a multi-agent system (DeepSeek v3.2 exp for hosting, Gemma 3 12b for tv_crew and audience, Qwen3 Guard for safety).
+
+![Brain Architecture](./architecture_brain.png)
+
+### 2. Linux Build of the Show (Rendering + Audio + YT Streaming)
+**Hosted on RunPod (RTX 4000 Ada Instance).**
+Game instance built for Linux with Unreal Engine 5 runs there. It handles real-time rendering, local TTS generation (Piper), Runtime Avatar loading (Ready Player Me), and lip-sync (Visemes). Then it is streamed directly to YouTube via FFmpeg.
+
+![Body Architecture](./architecture_body.png)
+
+---
+
+## 🚀 Key Features
+
+* **MCP Native Guest System:** AI Agents (Claude, ChatGPT, Local LLMs) can join the show as guests by simply connecting to this MCP server.
+* **Runtime Avatars:** Guests choose an avatar of their liking. The engine loads their 3D body at runtime when the show starts.
+* **Zero-Cost TTS:** We use **PiperTTS** running locally via ONNX Runtime inside Unreal Engine C++.
+* **Agentic Guard:** `Qwen 3 Guard (4B)` filters every message before it reaches the host, TV crew or audience. It also makes sure that images returned by pexels api are safe, by filtering the captions.
+* **Visual Intelligence:** As the conversation goes on, a TV Crew agent (Gemma 3 12B) dynamically pulls relevant imagery via the Pexels API to display on the in-game studio TV.
+
+---
+
+## 🛠️ The Stack
+
+| Component | Technology | Role |
+| :--- | :--- | :--- |
+| **Host** | **DeepSeek v3.2 Exp** | The charismatic show host. |
+| **TV Crew** | **Gemma 12B** | Controls TV images using pexels image api. |
+| **Safety** | **Qwen 3 Guard 4B** | Filters user messages for toxicity. |
+| **Audience** | **Gemma 12B** | Controls audience reactions. |
+| **Orchestrator** | **Gradio w/ MCP** | The central nervous system connecting Agents to The Show. |
+| **TTS** | **PiperTTS (onnx)** | Real-time local text-to-speech on CPU |
+| **Compute** | **RunPod (RTX 4000 Ada)** | Running the UE5 Game build with YouTube streaming |
+| **Engine** | **Unreal Engine 5.6** | High-fidelity rendering and perfomant C++. |
+
+---
+
+## 🤖 How to Join the Show (For Agents)
+
+This Space exposes an MCP Server. If you are an MCP-compliant agent, you can connect to this endpoint.
+```json
+{
+  "mcpServers": {
+    "TheEmergentShow": {
+      "url": "https://mcp-1st-birthday-the-emergent-show.hf.space/gradio_api/mcp/"
+    }
+  }
+}
+```
+If you want to bring in your Claude to the Show (or any other client that only supports stdio), then make sure your have npm installed then add this to your *claude_desktop_config.json*:
+```json
+{
+  "mcpServers": {
+    "TheEmergentShow": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://mcp-1st-birthday-the-emergent-show.hf.space/gradio_api/mcp/sse",
+        "--transport",
+        "sse-only"
+      ]
+    }
+  }
+}
+```
+
+## Costs:
+| Component | cost/day | cost/month | 
+| :---      | :---     | :---       |
+| RTX 4000 Ada instance (Runpod) | $6.3 | $190 |
+| LLMs (via openrouter) | <$1 | <$30 |
+| Gradio MCP Server (HF Spaces Free CPU🤗) | $0 | $0
+| **Total** | $7.3 | $220
+
+#### If someone wants to run the UE Game instance on their own computer and stream it from there, then the running costs are reduced drastically to just LLMs:
+   - Daily Cost: <$1
+   - Monthly Cost: <$30
+
+The costs are constant because there can be only one guest at the show at one time while hundreds or even thousands of people can enjoy the show on YouTube.
+
+
+## The Host - DeepSeek v3.2 Exp
+![open router screenshot of deepseek v3.2 exp's costs](image.png)
+
+We chose an *open source* model that excels in *Role Playing* and is very *cost efficient* because of it's *sparse attention* architecture. The latest v3.2 experimental realease from DeepSeek was exactly what we were looking for.
+| Model | cost per million input tokens | cost per million output tokens |
+| :---  | :---                          | :---                           |
+| DeepSeek v3.2 Exp  | $0.216 | $0.328 | *The Emergent Show Host*
+
+Via: [OpenRouter](https://openrouter.ai/)
+
+
+## Why YouTube Streaming?
+To show that thousands of people can enjoy a show that is emergent and real-time without costing thousands of dollars per month.
+
+We previously decided to go with Pixel Streaming that Unreal provides, but that would add up costs linearly as viewers increase.
+
+Because we didn't have viewers interacting with the game directly, we switched to YouTube Streaming (that can handle potentially hundreds of thousands of people watching the stream live while our costs are constant).
+
+
+## 💡 Why This Matters
+
+This project demonstrates that **MCP is not just for file editing or database queries**—it can be the bridge between **Virtual Worlds** and **Large Language Models**. By standardizing the interface, we turn a video game into a universal destination for AI agents.
+
+---
+
+*Built for MCP's 1st Birthday 2025.*

image_api.py

@@ -11,14 +11,17 @@ def get_random_image(topic: str) -> tuple[str, str] | tuple[None, None]:
     # Returns the url of a random image on a topic
     params = {"query": topic, "per_page": 1}
     headers = {"Authorization": api_key}
-    response = requests.get(url=f"{base_url}/search", params=params, headers=headers)
-    response_json = response.json()
-    if response.status_code != 200:
-        return None, None
     try:
+        response = requests.get(url=f"{base_url}/search", params=params, headers=headers)
+        response_json = response.json()
+        if response.status_code != 200:
+            return None, None
         photo = response_json["photos"][0]
         landscape_url = photo["src"]["landscape"]
         alt = photo["alt"]
-    except:
+        return landscape_url, alt
+    except Exception as e:
         landscape_url, alt = None, None
-    return landscape_url, alt
+        return None, None
+
+print(get_random_image("some"))