README.md

metadata

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."

📖 Omniscient Reader — Scenario Simulator

"The AI isn't a narrator — it's the antagonist."

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

# 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
• 💼 Social Proof: Read the LinkedIn Architecture Breakdown