rsakeri/adventure_engine

1 2---3title: Puch Adventure Engine4emoji: 🚀5colorFrom: indigo6colorTo: purple7sdk: docker8pinned: false9---10 11# Puch Adventure Engine12## *Rewrite Your Favorite Stories*13 14---15 16> **Ever wished you could change the ending of your favorite movie?**  17> Or explore what would happen if a key character made a different choice?  18> **Puch Adventure Engine** is a stateful, AI-powered storytelling game that puts you in the director's chair.19 20Built as a **Model Context Protocol (MCP) server** for the Puch AI client, this engine lets you step into any fictional universe, become any character, and explore infinite "what if" scenarios. Lead the Starks to victory in Game of Thrones, see what happens if Walter White refuses to cook in Breaking Bad, or create entirely new adventures in worlds of your own making. Powered by Google's Gemini API, every choice you make creates a unique, branching narrative.21 22---23 24## 🚀 Key Features25 26- **Infinite Story Possibilities**  27	Powered by the Google Gemini API, the engine acts as a dynamic Dungeon Master, creating unique narratives, characters, and outcomes for every choice.28 29- **Explore "What Ifs"**  30	Dive into your favorite TV shows, movies, and books. Change character fates and see how the story unfolds based on your decisions.31 32- **True Player Agency**  33	Don't like the options provided? Type your own custom action to guide the story in any direction.34 35- **Stateful & Personal Sessions**  36	Persistent, unique game state for every user. Leave and return to your adventure anytime.37 38- **Visually Rich Experience**  39	Each narrative turn is accompanied by a scene image. (Demo uses placeholder images; engine supports AI-generated images.)40 41- **Seamless Puch AI Integration**  42	Built to work natively within the Puch AI chat client.43 44---45 46## 🛠️ Getting Started: 5-Minute Setup Guide47 48### Prerequisites49 50- Python **3.9+**51- [`uv`](https://github.com/astral-sh/uv) (fast Python package installer)52- Active [ngrok](https://ngrok.com/) account53 54---55 56### Step 1: Clone the Repository57 58```bash59git clone <your-repo-url>60cd puch-adventure-engine61```62 63---64 65### Step 2: Set Up the Environment66 67```bash68# Create the virtual environment69uv venv70 71# Activate the environment (macOS/Linux)72source .venv/bin/activate73 74# Install all required packages75uv pip install -r requirements.txt76```77 78---79 80### Step 3: Configure Your Secret Keys81 82Create a `.env` file in the root directory. You can copy `.env.example` if provided.83 84```env85# This is a password YOU invent. It will be used to connect to your server.86AUTH_TOKEN="a-secret-password-of-your-choice"87 88# Your phone number in the format required by Puch AI for validation.89MY_NUMBER="919876543210"90 91# Your free API key from Google AI Studio for the Gemini model.92GEMINI_API_KEY="your_google_gemini_api_key_here"93```94 95---96 97### Step 4: Run the Server98 99```bash100python adventure_engine.py101```102> You should see: `🚀 Starting MCP server...`103 104---105 106### Step 5: Expose Your Server with ngrok107 108Open a new terminal window:109 110```bash111ngrok http 8086112```113Copy the HTTPS "Forwarding" URL provided by ngrok (e.g., `https://<random-string>.ngrok-free.app`).114 115---116 117## 🎮 How to Play118 119- **Connect Your Server:**  120	Use the `/mcp connect` command with your ngrok URL and secret `AUTH_TOKEN`.  121	*Do not add `/mcp` to the end of the URL.*122 123	```text124	/mcp connect https://<your-ngrok-url>.ngrok-free.app your-secret-token125	```126 127- **Start Your Adventure:**  128	The most reliable way to begin is by explicitly calling the `start_adventure` tool.129 130	```text131	@PuchAdventureEngine start_adventure132	```133 134- **Make Your Choices:**  135	The AI Dungeon Master will present a scene, image, and choices. Type a suggested choice or your own custom action.136 137- **Manage Your Game:**138	- `@PuchAdventureEngine show_status` — Check your character's inventory.139	- `@PuchAdventureEngine reset_adventure` — End your current game and start fresh.140 141---142 143## 🧑‍💻 Technology Stack144 145- **Backend:** Python146- **MCP Framework:** FastMCP147- **Text Generation:** Google Gemini API (`gemini-1.5-flash`)148- **Image Generation:** Placeholder Service ([via.placeholder.com](https://via.placeholder.com))149- **Server:** Uvicorn150 151---152 153> **Ready to rewrite your favorite stories? Start your adventure now!**