README.md

---
title: LifeChoice Simulator
emoji: 🧭
colorFrom: purple
colorTo: pink
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
pinned: true
license: mit
models:
  - Qwen/Qwen2.5-7B-Instruct
tags:
  - build-small-hackathon
  - gradio
  - agent
  - decision-support
  - thousand-token-wood
  - best-agent
  - best-demo
  - openai
  - track:wood
  - sponsor:openai
  - achievement:offbrand
  - achievement:sharing
  - achievement:fieldnotes
---

# LifeChoice Simulator

LifeChoice Simulator is an LLM-powered interactive future game for the **Thousand Token Wood** track. It turns a real fork in the road into a strange, playable eight-node future where choices change the world, the character, the pressure, and the ending report.

The experience sits between a text-adventure dungeon master, a decision simulator, and a pocket-sized alternate-life RPG. A 7B model dreams up adaptive scenarios; deterministic game state keeps those dreams consequential.

![Architecture](docs/architecture.svg)

## Why This Exists

Some decisions are too personal for a pros-and-cons list and too uncertain for a single chatbot answer. A student choosing between an MTech path and a software job is not only comparing two labels. They are carrying family expectations, money pressure, identity, validation, time, and fear of regret.

Traditional advice tools usually collapse that complexity into one recommendation. LifeChoice takes a different approach: it turns the decision into a small playable future, so the player can feel how tradeoffs evolve over time.

## The Story

Meet Aarav. He has two possible roads:

- **MTech**: meaningful research, a professor who is interested, and a path that could grow into deeper expertise.
- **Software Job**: faster income, clearer timelines, and relief for a family that needs financial stability soon.

Aarav chooses to enter the MTech future. The first month feels promising: a professor asks him to commit to a defined project. But the choice is not abstract anymore. Every decision changes something: money, fulfillment, validation, stress, and family trust.

If Aarav chases research too aggressively, fulfillment rises but stress and money pressure may break the world around him. If he protects stability too much, the research path may lose momentum. Earlier decisions come back later as obligations, closed doors, or delayed opportunities.

By the end, LifeChoice does not tell Aarav what to do. It shows the shape of the future he played: what he protected, what he sacrificed, and what costs kept returning.

## Our Solution

LifeChoice is an AI-native playable mirror for high-stakes personal choices. The LLM generates adaptive future scenarios from the player's dilemma, chosen path, calibration pressure, and previous decisions. A deterministic game engine tracks the consequences so the experience behaves like a game, not a loose chat.

The goal is not prediction. The goal is rehearsal. LifeChoice lets a player step into one possible future, make decisions inside it, and see how the emotional and practical state of the world changes.

## Live Links

- Live Space: [build-small-hackathon/LifeChoice-Simulator](https://huggingface.co/spaces/build-small-hackathon/LifeChoice-Simulator)
- Demo video: [YouTube walkthrough](https://youtu.be/pHPdT6BKJcI)
- Social post: [LinkedIn announcement](https://www.linkedin.com/posts/ajeyabhargava-jashwanth-reddy-aa1a57270_buildsmallhackathon-huggingface-openai-share-7472378829567614979-dGUp/?utm_source=share&utm_medium=member_desktop&rcm=ACoAAEJdAlkBcnz7M6u7dt4WCnDYophXfRZ0MPM)
- Public build trace: [lifechoice-simulator-trace](https://huggingface.co/datasets/build-small-hackathon/lifechoice-simulator-trace)
- Social post script: [docs/social-post.md](docs/social-post.md)
- Demo script: [docs/demo-script.md](docs/demo-script.md)
- Compliance checklist: [docs/compliance-checklist.md](docs/compliance-checklist.md)

## Thousand Token Wood Fit

LifeChoice is built for the whimsical track: a playful, AI-native interaction that lets a small model wander somewhere stranger than a normal productivity app.

| Track Signal | How LifeChoice Fits |
|---|---|
| Interactive AI game | Eight playable decision nodes, persistent stats, branching consequences, persona reactions, and final report |
| Out-of-the-box entertainment | A serious life dilemma becomes an alternate-future game with pixel-art scenes and a reactive character |
| Small model imagination | `Qwen/Qwen2.5-7B-Instruct` generates bounded future scenarios from the user's fork, pressure, and past choices |
| Text-adventure energy | The model acts like a constrained future narrator while the state engine remembers what the player did |
| Delightful presentation | Custom Gradio UI, cinematic scenario cards, world-state badges, metric bars, and pixel-art backgrounds |

## Experience

The player enters a dilemma such as `MTech vs Software Job`, chooses one path to enter, adds the pressure that makes the decision real, and selects a voice that follows them through the simulation.

Each turn combines:

- an LLM-generated scenario constrained by the current causal state
- three consequential choices
- five changing metrics: financial security, fulfillment, validation, stress, and family satisfaction
- durable facts, obligations, and closed options
- a reactive world state: `stable`, `thriving`, or `struggling`
- a character expression: `neutral`, `stressed`, or `confident`

The result is not a prediction engine and not an advice bot. It is a playable mirror: a fictional system for feeling how tradeoffs compound.

## Reactive Worlds

The visual world is not static. LifeChoice chooses a background family from the player's chosen path, then switches the image as the metrics change.

There are **6 environment types**:

| Environment | Trigger Examples |
|---|---|
| `campus_academic` | MTech, PhD, college, study, masters, research |
| `studio_creative` | artist, art, music, design, film, creative, writer |
| `startup_chaotic` | startup, founder, business |
| `medical_clinical` | doctor, medical, NEET, hospital |
| `corporate` | corporate, manager, consulting, MBA |
| `tech_office` | default environment for other paths |

Each environment has **3 metric-driven states**:

| State | Meaning |
|---|---|
| `stable` | The path is tense but balanced enough to continue |
| `thriving` | Overall wellbeing is high and stress is controlled |
| `struggling` | Stress, money pressure, or low wellbeing is visibly damaging the world |

That creates **18 background variants** in total, such as:

```text
campus_academic_stable.png
campus_academic_thriving.png
campus_academic_struggling.png
startup_chaotic_stable.png
startup_chaotic_thriving.png
startup_chaotic_struggling.png
```

The character also reacts to the same simulation state:

| Character State | Trigger |
|---|---|
| `neutral` | Default state |
| `stressed` | Stress rises above the danger threshold |
| `confident` | Fulfillment is high while stress stays low |

The background represents the condition of the world around the player. The character represents how the player is holding up inside that world.

## AI Role

The LLM is central to the project. It generates the adaptive future scenarios that make each run feel personal to the player's dilemma, chosen path, calibration pressure, and earlier decisions.

The deterministic layer gives the model a game board:

- state transitions and metric arithmetic
- causal memory through facts, obligations, and closed options
- narrative validation for stress, money, and family-pressure thresholds
- fallback resilience during model outages
- final report generation from the recorded causal ledger

This split keeps the app AI-native without turning it into an unconstrained chat transcript.

## Architecture

1. Gradio captures the dilemma, chosen path, calibration fact, and persona.
2. The first scene appears immediately to keep the game responsive.
3. A background worker prepares future scenario nodes with the 7B model.
4. The state engine applies choice deltas and updates the causal ledger.
5. Narrative validation keeps generated scenes aligned with critical metrics.
6. The visual environment updates from all five metrics.
7. Earlier decisions return through cascade moments.
8. The final report summarizes the observed playthrough.

## Model Compliance

Only one model is configured.

| Model | Parameters | Purpose |
|---|---:|---|
| [`Qwen/Qwen2.5-7B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct) | 7.616B | Bounded adaptive scenario generation |

Hugging Face model metadata reports `7,615,616,512` parameters. No secondary model is configured, and no model at or above 32B is used. Deterministic authored content exists only as a resilience path if inference is unavailable; the submitted product experience is centered on model-generated scenarios.

## Product Design

| Capability | Design |
|---|---|
| Fast start | The game opens without waiting on model latency |
| Adaptive scenario loop | Later nodes are generated by the 7B model from bounded causal context |
| Bounded memory | Recent choices, facts, obligations, and closed options are carried forward |
| Consequential choices | Every decision mutates metrics and the causal ledger |
| Delayed consequences | Prior decisions return at cascade moments instead of disappearing |
| Reactive visuals | 6 environment families, 18 background states, metric bars, world label, and sprite expression change with state |
| Final report | The ending is computed from what happened in the playthrough |

## Safety

LifeChoice is framed as reflective fiction. It does not provide medical, legal, financial, mental-health, or career advice, and it does not claim to predict the user's future.

Safety controls include:

- bounded model context
- strict generated-node schema validation
- deterministic metric arithmetic
- no autonomous real-world actions
- no recommendation of a single correct path
- visible disclaimer text in the UI
- final report grounded in the simulated ledger, not external claims

## Built With Codex

Codex was used as an implementation partner across product design, architecture, code, validation, documentation, and deployment polish.

Codex contributed to:

- translating the hackathon concept into a modular LLM-powered simulation architecture
- implementing the Gradio interface, custom game UI, scenario cards, metric panel, persona panel, sprite state, and final report view
- designing the causal ledger with facts, obligations, closed options, recent choices, and delayed cascade moments
- integrating Hugging Face `InferenceClient` for bounded 7B scenario generation
- adding validation so generated scenes respect critical stress, money, and family thresholds
- documenting model compliance, safety posture, architecture, screenshots, demo flow, and badge evidence
- verifying live Space access, runtime metadata, world-state transitions, and character-state transitions
- publishing the public agent build trace for transparency

The workflow stayed human-directed: the project owner shaped the concept, evaluated the running Space, selected badge claims, and guided final submission positioning. Codex handled implementation depth, consistency checks, and documentation polish.

Codex-attributed commits use:

```text
Author: Codex <codex@openai.com>
```

## Bonus Badges

- **Off-Brand**: custom game-style Gradio frontend instead of the default Gradio look.
- **Field Notes**: README, architecture diagram, demo script, compliance checklist, screenshots, and submission notes.
- **Sharing is Caring**: public [agent build trace dataset](https://huggingface.co/datasets/build-small-hackathon/lifechoice-simulator-trace) with 26 event rows.

This submission does not claim Tiny Titan, OpenBMB, NVIDIA, Modal credits, Off the Grid, Well-Tuned, or Llama Champion.

## Technical Snapshot

- Python 3.10+
- Gradio 5
- Hugging Face Hub `InferenceClient`
- `Qwen/Qwen2.5-7B-Instruct` at 7.616B parameters
- Thread-pool prefetching
- Deterministic state engine
- 6 environment families and 18 metric-driven background variants
- 3 character states: `neutral`, `stressed`, and `confident`
- Pixel-art environment assets
- Public Hugging Face Space deployment

## Screenshots

### Immediate First Scene

![Immediate first scene](docs/screenshots/simulation.png)

### Cascade

![Earlier decision returning](docs/screenshots/cascade.png)

### Final Report

![Causal final report](docs/screenshots/report.png)

## Submission Evidence

Code, Space metadata, model compliance, safety documentation, architecture, screenshots, demo script, public trace dataset, social post script, and badge evidence are included in the repository.