| --- |
| title: "Omniscient Reader — Scenario Simulator" |
| emoji: 📖 |
| colorFrom: indigo |
| colorTo: purple |
| sdk: gradio |
| sdk_version: "6.18.0" |
| app_file: app.py |
| hardware: cpu |
| pinned: true |
| license: mit |
| tags: |
| - game |
| - ai |
| - interactive-fiction |
| - omniscient-reader |
| - build-small |
| - thousand-token-wood |
| - best-use-of-modal |
| - off-brand |
| - llama-champion |
| - custom-ui |
| - llama-cpp |
| - track:wood |
| - sponsor:modal |
| - achievement:offbrand |
| - achievement:llama |
| short_description: "Play as Kim Dokja. The Dokkaebi knows you know everything." |
| --- |
| --- |
| title: "Omniscient Reader — Scenario Simulator" |
| emoji: 📖 |
| colorFrom: indigo |
| colorTo: purple |
| sdk: gradio |
| sdk_version: "6.18.0" |
| app_file: app.py |
| hardware: cpu |
| pinned: true |
| license: mit |
| tags: |
| - game |
| - ai |
| - interactive-fiction |
| - omniscient-reader |
| - build-small |
| - thousand-token-wood |
| - best-use-of-modal |
| - best-agent |
| - off-brand |
| - llama-champion |
| - custom-ui |
| - llama-cpp |
| short_description: "Play as Kim Dokja. The Dokkaebi knows you know everything." |
| --- |
| |
| <div align="center"> |
| <h1>📖 Omniscient Reader — Scenario Simulator</h1> |
| <p><em>"The AI isn't a narrator — it's the antagonist."</em></p> |
| </div> |
| |
| An AI-powered scenario simulator based on the legendary Korean web novel and manhwa **Omniscient Reader's Viewpoint (ORV)**. You play as Kim Dokja — a man who has read the apocalypse novel exactly 3,149 times. |
| |
| The twist? The Dokkaebi (the AI Game Master) **knows you know everything** — and has been redesigning reality specifically to break your meta-knowledge. |
| |
| Built for the **Build Small Hackathon 2026**. |
| |
| --- |
| |
| ## 🏆 Hackathon Categories & Justifications |
| |
| ### 🍄 Track 2: Thousand Token Wood |
| We built a complex, immersive narrative game utilizing a dual-model architecture to stay strictly under the 32B parameter limit (8B + 14B = 22B total). |
| |
| ### 🟢 Best Use of Modal |
| We utilize Modal to host our "Cinematic Engine". While our fast gameplay loop uses an 8B model on Groq, high-stakes cinematic moments are dynamically routed to a **Qwen 2.5 14B GGUF** running via `llama.cpp` on a **Modal A10G GPU**. We use a persistent volume cache on Modal to keep the model warm, preventing cold starts during active gameplay sessions. |
| |
| ### 🤖 Best Agent |
| The Dokkaebi operates as an **autonomous adversarial agent**. Instead of simply generating text, it continuously runs an internal planning loop evaluating the player's *intent*. It autonomously decides when to trigger "Phase Shifts" (Combat/Exploration), when to deploy "Probability Storms", and manipulates internal state tools (Meta Exposure, Probability Stability) to actively work against the player's meta-knowledge. |
| |
| ### 🎨 Off-Brand Badge |
| 100% custom UI overriding Gradio defaults. We injected 14KB of custom CSS and 21KB of JS to create glassmorphism panels, glitch shaders, and particle effects without utilizing a single default Gradio visual component. |
| |
| ### 🦙 Llama Champion Badge |
| Heavy narrative lifting and agentic planning are powered by `llama.cpp` serving the Qwen 2.5 14B model on our Modal backend. |
| |
| --- |
| |
| ## 🕹️ The Rules of the Star Stream |
| |
| 1. **Begin the Scenario**: Initiate the apocalypse. |
| 2. **Declare Your Action**: Type freely or select from contextual suggestions. |
| 3. **Choose Your Stance**: *Aggressive / Deceptive / Empathetic / Observant / Neutral*. Your stance dictates how the Dokkaebi interprets your intent. |
| 4. **Beware the Dokkaebi**: The AI evaluates your *intent*. If you use out-of-universe novel knowledge to solve problems too easily, reality fights back. |
| 5. **The Constellations are Watching**: A live cosmic audience reacts to your every move. |
| 6. **Monitor Your Gauges**: Watch your HP, Probability Stability, and most importantly... **Meta Exposure**. |
| 7. **Do Not Get Noticed**: Push Meta Exposure to 100% and reality breaks. |
| |
| --- |
| |
| ## ⚙️ Dual-Model Architecture |
| |
| Built strictly under the 32B parameter hackathon cap. **Total Parameters: 22B ✅** |
| |
| | Backend | Model | Size | Usage / Latency | |
| | :--- | :--- | :--- | :--- | |
| | **Groq LPU** | Llama 3.1 8B Instant | 8B | Gameplay Loop, State Tracking & Intent Parsing (~2s) | |
| | **Modal (A10G)** | Qwen 2.5 14B (llama.cpp) | 14B | Cinematic Scenario Generation & Deep Agentic Planning | |
| |
| --- |
| |
| ## 🛠️ Local Setup |
| |
| ```bash |
| # 1. Clone the repository |
| git clone https://huggingface.co/spaces/build-small-hackathon/omniscient-reader |
| |
| # 2. Install dependencies |
| pip install -r requirements.txt |
| |
| # 3. Set your Groq API Key |
| export GROQ_API_KEY="your_groq_key_here" |
| |
| # 4. Launch the Scenario |
| python app.py |
| ``` |
| *Note: On HuggingFace Spaces, ensure `GROQ_API_KEY` is added to the Space Secrets.* |
| |
| --- |
|
|
| ## 🔗 Links & Media |
| - 🎬 **Demo Video:** [Watch the Gameplay on YouTube](https://youtu.be/x6-GxICsk2I) |
| - 💼 **Social Proof:** [Read the LinkedIn Architecture Breakdown](https://www.linkedin.com/posts/aswini-kumar-yanamadala_llm-aiengineering-gradio-share-7472424679501103104-NhwT/) |
|
|
