Refocus README for Thousand Token Wood track

README.md

@@ -28,87 +28,72 @@ tags:
 
 # LifeChoice Simulator
 
-LifeChoice Simulator turns a difficult real-life dilemma into a short, consequential future that a user can play through. It is built for reflection, not prediction or advice: the app shows how tradeoffs can compound across money, fulfillment, social validation, stress, and family pressure.
+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)
 
-## Live Demo
+## Live Links
 
 - Live Space: [build-small-hackathon/LifeChoice-Simulator](https://huggingface.co/spaces/build-small-hackathon/LifeChoice-Simulator)
-- Agent build trace: [lifechoice-simulator-trace](https://huggingface.co/datasets/build-small-hackathon/lifechoice-simulator-trace)
-- Public demo video: [watch the 22-second walkthrough](https://github.com/Ajey95/LifeChoice-Simulator-Hackathon/raw/main/docs/lifechoice-demo.mp4)
-- Social post draft: [docs/social-post.md](docs/social-post.md)
-- Demo script: [docs/demo-script.md](docs/demo-script.md)
-
-## Record A Demo
-
-The submission includes a demo recording plan so judges can evaluate the app even if live API limits, model latency, or runtime availability affect the Space during review.
-
+- Demo video: [22-second walkthrough](https://github.com/Ajey95/LifeChoice-Simulator-Hackathon/raw/main/docs/lifechoice-demo.mp4)
+- 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)
-- Existing walkthrough video: [docs/lifechoice-demo.mp4](docs/lifechoice-demo.mp4)
-- Suggested length: 45-90 seconds
-- Required coverage: setup flow, first deterministic scene, at least one committed choice, metric changes, world/character state, and final report or cascade if time allows
-
-The demo should make the core product claim visible: LifeChoice is a stateful causal simulation with deterministic consequences, not a one-shot advice chatbot.
+- Compliance checklist: [docs/compliance-checklist.md](docs/compliance-checklist.md)
 
-## Post It
+## Thousand Token Wood Fit
 
-The submission also includes a ready-to-use social media post script that links back to the live Space and public build trace.
-
-- Social post script: [docs/social-post.md](docs/social-post.md)
-- Live Space: [build-small-hackathon/LifeChoice-Simulator](https://huggingface.co/spaces/build-small-hackathon/LifeChoice-Simulator)
-- Public trace dataset: [lifechoice-simulator-trace](https://huggingface.co/datasets/build-small-hackathon/lifechoice-simulator-trace)
+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.
 
-The post highlights the app, the hackathon track, the Codex-assisted build process, and the public trace dataset for the `Sharing is Caring` badge.
+| 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 |
 
-## What It Does
+## Experience
 
-The user enters a fork in the road, chooses one path to simulate, adds one real constraint, and selects a persona voice. LifeChoice then uses a 7B language model to help generate adaptive future scenarios inside an eight-node simulation where every decision changes the state of the world and creates durable consequences.
+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.
 
-Unlike a normal chatbot, the LLM is not asked to improvise the whole product from scratch on every turn. It is the narrative scenario engine for the adaptive experience, while deterministic code provides the structure around it: arithmetic, state transitions, facts, obligations, closed options, cascade moments, safety boundaries, and the final report.
+Each turn combines:
 
-## Why It Is Not Just A Chatbot
+- 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`
 
-A chatbot responds turn by turn with prose. LifeChoice runs a stateful simulation engine:
+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.
 
-- Every choice changes five deterministic metrics.
-- Choices create durable facts, obligations, and closed options.
-- Later scenes must respect causal records and metric thresholds.
-- Earlier choices return through three cascade moments.
-- The visual environment changes among `thriving`, `stable`, and `struggling`.
-- The player sprite changes among `neutral`, `stressed`, and `confident`.
-- A bounded context packet prevents token growth across the simulation.
-- The final report is computed from actual behavior, not a conversational impression.
+## AI Role
 
-The LLM generates and adapts the scenario text inside bounded decision nodes. Deterministic code handles scoring, state transitions, safety limits, and simulation completion so the model's creativity stays grounded in a consistent causal system.
+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.
 
-## Product Design
+The deterministic layer gives the model a game board:
 
-LifeChoice is designed around fast entry, bounded generation, and visible consequences.
+- 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
 
-| Capability | Design |
-|---|---|
-| Fast onboarding | Dilemma, path selection, one calibration answer, and persona selection |
-| Immediate play | The opening node is deterministic and available without model latency |
-| Efficient generation | One future node is generated at a time and prefetched in the background |
-| Bounded context | Last 3 choices, 8 facts, 5 obligations, and 5 closed options only |
-| Stable characters | Characters remain static session data, not regenerated every turn |
-| Consistent world state | Threshold facts and narrative validation enforce visible pressure |
-| Meaningful choices | Every choice mutates facts, obligations, closed options, and metrics |
-| Persona continuity | Reactions appear at opening, selected later nodes, and critical thresholds |
-| Delayed consequences | Small echo at node 2, major consequence at node 5, final payoff at node 7 |
-| Reactive visuals | Environment image, metric panel, and sprite expression update after decisions |
+This split keeps the app AI-native without turning it into an unconstrained chat transcript.
 
 ## Architecture
 
-1. Gradio captures a dilemma, chosen path, calibration fact, and persona.
-2. The engine returns an immediate deterministic opening scene.
-3. A background worker generates future scenario nodes with the 7B model.
-4. The deterministic state engine applies deltas and updates the causal ledger.
-5. Narrative validation rejects generated scenes that contradict critical metrics.
-6. The environment derives its visual state from all five metrics.
-7. Persona reactions and cascade events reuse the causal ledger.
-8. The final report summarizes observed behavior inside the simulation.
+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
 
@@ -118,44 +103,50 @@ Only one model is configured.
 |---|---:|---|
 | [`Qwen/Qwen2.5-7B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct) | 7.616B | Bounded adaptive scenario generation |
 
-Hugging Face repository metadata reports `7,615,616,512` parameters. No secondary model is configured, and no model at or above 32B is used. The submitted experience is LLM-centered: the model is what makes later scenarios adaptive to the user's dilemma and prior choices. Deterministic authored nodes remain as a reliability fallback for demos and outages, but they are not the core creative experience.
+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.
 
-Run the compliance test:
+## Product Design
 
-```bash
-pytest tests/test_model_compliance.py
-```
+| 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 | Backgrounds, metrics, world label, and sprite expression change with state |
+| Final report | The ending is computed from what happened in the playthrough |
 
 ## Safety
 
-LifeChoice is a reflective simulation, not medical, legal, financial, mental-health, or career advice. Its futures are fictional hypotheses rather than predictions. Users should not enter secrets or sensitive personal data. High-stakes decisions should be discussed with qualified people who understand the real situation.
+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:
 
-- Deterministic metric arithmetic and clamping to `0..100`
-- Bounded model context
-- Strict model-output schema validation
-- Deterministic fallback for outages or invalid model output
-- No autonomous real-world action
-- No recommendation of a "correct" path
-- Explicit uncertainty and disclaimer text in the UI
+- 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
 
-This submission was developed with Codex as an implementation partner, not just as a code autocomplete tool. Codex was used across product design, architecture, implementation, verification, documentation, and deployment preparation.
+Codex was used as an implementation partner across product design, architecture, code, validation, documentation, and deployment polish.
 
-Codex helped turn the initial hackathon concept into a production-shaped system:
+Codex contributed to:
 
-- Converted the idea into a modular simulation architecture with deterministic state ownership.
-- Implemented the Gradio application, custom interface, scenario rendering, persona panel, sprite state, metrics, and report view.
-- Designed the causal ledger model: facts, obligations, closed options, recent choices, and delayed cascade moments.
-- Integrated Hugging Face `InferenceClient` so the 7B model can generate bounded adaptive scenarios while deterministic code validates and scores the simulation.
-- Built validation logic so generated scenes cannot ignore critical stress, money, or family thresholds.
-- Created compliance artifacts for model-size limits, safety posture, architecture, screenshots, demo flow, and submission evidence.
-- Verified live Space access, runtime state, repository files, world-state transitions, and character-state transitions.
-- Published a public agent build trace for transparency and the `Sharing is Caring` badge.
+- 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 selected the product direction, reviewed behavior in the running Space, chose badge claims, and guided final submission positioning. Codex handled implementation details, consistency checks, and documentation polish so the build could move from prototype to submission-ready artifact quickly.
+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:
 
@@ -165,54 +156,22 @@ Author: Codex <codex@openai.com>
 
 ## Bonus Badges
 
-- **Off-Brand**: custom game-style Gradio frontend instead of default Gradio presentation.
+- **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.
 
-## Tech Stack
+## Technical Snapshot
 
 - Python 3.10+
 - Gradio 5
 - Hugging Face Hub `InferenceClient`
-- `Qwen/Qwen2.5-7B-Instruct` (7B)
+- `Qwen/Qwen2.5-7B-Instruct` at 7.616B parameters
 - Thread-pool prefetching
-- Pytest
+- Deterministic state engine
 - Pixel-art environment assets
-
-## Run Locally
-
-```bash
-python -m venv .venv
-.\.venv\Scripts\activate
-pip install -r requirements.txt
-python app.py
-```
-
-`HF_TOKEN` should be configured for the submitted experience. The fallback path exists only to avoid a blank demo during outages; it is not the intended model-driven product mode.
-
-## Tests
-
-```bash
-pytest -q
-```
-
-The suite covers model-size compliance, bounded context, branch divergence, world-state clamping, state-to-narrative consistency, cascades, persona cadence, and metric-driven environment changes.
-
-## Deployment
-
-Authenticate as an account with write permission in `build-small-hackathon`, then upload the Space files to:
-
-```text
-build-small-hackathon/LifeChoice-Simulator
-```
-
-The current public Space is available at:
-
-```text
-https://huggingface.co/spaces/build-small-hackathon/LifeChoice-Simulator
-```
+- Public Hugging Face Space deployment
 
 ## Screenshots
 
@@ -228,8 +187,6 @@ https://huggingface.co/spaces/build-small-hackathon/LifeChoice-Simulator
 
 ![Causal final report](docs/screenshots/report.png)
 
-## Submission Status
-
-Code, Space metadata, model compliance, safety documentation, architecture, screenshots, demo script, public trace dataset, and badge evidence are included.
+## Submission Evidence
 
-See the dated [compliance checklist](docs/compliance-checklist.md) for requirement-by-requirement 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.