Deploy LifeChoice Simulator from Codex-built repository

.gitattributes

@@ -33,3 +33,26 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/environments/campus_academic_stable.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/campus_academic_struggling.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/campus_academic_thriving.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/corporate_stable.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/corporate_struggling.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/corporate_thriving.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/medical_clinical_stable.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/medical_clinical_struggling.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/medical_clinical_thriving.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/startup_chaotic_stable.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/startup_chaotic_struggling.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/startup_chaotic_thriving.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/studio_creative_stable.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/studio_creative_struggling.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/studio_creative_thriving.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/tech_office_stable.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/tech_office_struggling.png filter=lfs diff=lfs merge=lfs -text
+assets/environments/tech_office_thriving.png filter=lfs diff=lfs merge=lfs -text
+docs/lifechoice-demo.mp4 filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/cascade.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/onboarding.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/report.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/simulation.png filter=lfs diff=lfs merge=lfs -text

MODEL_MANIFEST.json

@@ -0,0 +1,12 @@
+{
+  "models": [
+    {
+      "id": "Qwen/Qwen2.5-7B-Instruct",
+      "parameters_billions": 7.616,
+      "purpose": "Optional bounded decision-node enrichment",
+      "required": false
+    }
+  ],
+  "maximum_allowed_parameters_billions": 31.999,
+  "fallback": "Deterministic Python simulation content; no fallback model"
+}

README.md

@@ -1,13 +1,184 @@
 ---
 title: LifeChoice Simulator
-emoji: ⚡
+emoji: 🧭
 colorFrom: purple
-colorTo: blue
+colorTo: pink
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: 5.50.0
 app_file: app.py
 pinned: false
+license: mit
+models:
+  - Qwen/Qwen2.5-7B-Instruct
+tags:
+  - build-small-hackathon
+  - gradio
+  - agent
+  - decision-support
+  - thousand-token-wood
+  - best-agent
+  - best-demo
+  - openai
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# LifeChoice Simulator
+
+LifeChoice Simulator turns a difficult real-life dilemma into a short, consequential future you can play through. It is designed for reflection, not prediction or advice.
+
+![Architecture](docs/architecture.svg)
+
+## Live Demo
+
+- Hugging Face Space target: `build-small-hackathon/LifeChoice-Simulator` (organization authorization pending)
+- Public demo video: [watch the 22-second walkthrough](https://github.com/Ajey95/LifeChoice-Simulator-Hackathon/raw/main/docs/lifechoice-demo.mp4)
+- Social post: publishing pending
+
+The repository includes a longer [demo script](docs/demo-script.md) and [social post draft](docs/social-post.md) ready for public publishing.
+
+## Why It Is Not Just a Chatbot
+
+A chatbot responds turn by turn with prose. LifeChoice runs a stateful simulation engine:
+
+- Every choice changes five deterministic metrics.
+- Choices create durable facts, obligations, and closed options.
+- Later scenes must respect those causal records and metric thresholds.
+- Earlier choices return through three cascade moments.
+- The visual environment changes among `thriving`, `stable`, and `struggling`.
+- A bounded context packet prevents token growth across the simulation.
+- The final report is computed from actual behavior, not a conversational impression.
+
+The language model enriches bounded decision nodes. It does not own arithmetic, state transitions, safety limits, or simulation completion.
+
+## Product Design
+
+LifeChoice is designed around fast entry, bounded generation, and consequences that remain visible:
+
+| Capability | Design |
+|---|---|
+| Fast onboarding | Dilemma, path, one concrete calibration answer, and one persona selection |
+| Immediate play | The opening node is deterministic and available without model latency |
+| Efficient generation | One future node is enriched 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 |
+| Consistent world state | Threshold facts and narrative validation enforce visible pressure |
+| Meaningful choices | Every choice mutates causal facts, obligations, closed options, and metrics |
+| Persona continuity | Reactions appear at opening, nodes 1/3/5/7, and critical thresholds |
+| Delayed consequences | Small echo at node 2, major consequence at node 5, final payoff at node 7 |
+| Reactive visuals | Environment image and metric panel update after every decision |
+
+## 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 | Optional bounded node enrichment |
+
+Hugging Face repository metadata reports `7,615,616,512` parameters. No secondary model is configured, and no model at or above 32B is used. If hosted inference is unavailable, the simulation uses deterministic authored nodes and remains fully playable.
+
+Run the compliance test:
+
+```bash
+pytest tests/test_model_compliance.py
+```
+
+## Architecture
+
+1. Gradio captures a dilemma, chosen path, one calibration fact, and persona.
+2. The engine returns an immediate deterministic opening scene.
+3. A background worker optionally enriches future 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. Cascades and the final report use the causal ledger.
+
+## 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.
+
+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 output
+- No autonomous real-world action
+- No recommendation of a “correct” path
+- Explicit uncertainty and disclaimer text in the UI
+
+## Tech Stack
+
+- Python 3.10+
+- Gradio 5
+- Hugging Face Hub `InferenceClient`
+- `Qwen/Qwen2.5-7B-Instruct` (7B)
+- Thread-pool prefetching
+- Pytest
+- Pixel-art environment assets
+
+## Run Locally
+
+```bash
+python -m venv .venv
+.\.venv\Scripts\activate
+pip install -r requirements.txt
+python app.py
+```
+
+`HF_TOKEN` is optional. Without it, deterministic fallback content is used.
+
+### Deploy The Organization Space
+
+Authenticate specifically as `Ajeya95`, with write permission in `build-small-hackathon`, then run:
+
+```bash
+hf auth login
+python scripts/deploy_space.py
+```
+
+The deployment script checks both the username and organization role before creating or updating the public Space.
+
+## 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.
+
+## Hackathon Categories
+
+- Thousand Token Wood
+- Best Agent
+- Best Demo
+- OpenAI Prize
+
+This submission does not claim Tiny Titan, OpenBMB, NVIDIA, Modal credits, or Off Brand unless the implementation is later changed to meet those category-specific requirements.
+
+## Built With Codex
+
+Codex built the simulation architecture, Gradio interface, tests, documentation, and deployment workflow. Codex-attributed commits use:
+
+```text
+Author: Codex <codex@openai.com>
+```
+
+## 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 Status
+
+Code, tests, Space metadata, model compliance, safety documentation, architecture, and publishing assets are included. Public URL fields are updated only after the authenticated GitHub repository, Hugging Face organization Space, video, and social post exist.
+
+See the dated [compliance checklist](docs/compliance-checklist.md) for requirement-by-requirement evidence and external blockers.

app.py

@@ -0,0 +1,671 @@
+from __future__ import annotations
+
+import base64
+import html
+import json
+import mimetypes
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+
+from lifechoice_engine import (
+    METRICS,
+    MODEL_ID,
+    SimulationSession,
+    choose,
+    current_node,
+    environment_image,
+    environment_state,
+    split_dilemma,
+    start_session,
+)
+
+ROOT = Path(__file__).parent
+PERSONA_ASSETS = {
+    "Family": ROOT / "assets" / "personas" / "family.webp",
+    "Friend": ROOT / "assets" / "personas" / "friend.webp",
+    "Mentor": ROOT / "assets" / "personas" / "mentor.webp",
+    "Partner": ROOT / "assets" / "personas" / "friend.webp",
+    "Inner Voice": ROOT / "assets" / "personas" / "mentor.webp",
+}
+
+CSS = """
+:root {
+  --night: #070a12;
+  --panel: rgba(9, 13, 24, .90);
+  --line: rgba(255, 255, 255, .14);
+  --cream: #fff7df;
+  --muted: #bbb7aa;
+  --gold: #ffc857;
+  --coral: #ff6b5f;
+  --cyan: #5ce1e6;
+  --green: #74e59b;
+}
+* { box-sizing: border-box; }
+body, .gradio-container {
+  background:
+    radial-gradient(circle at 12% -8%, rgba(65, 71, 150, .34), transparent 32rem),
+    linear-gradient(180deg, #11162a 0%, var(--night) 48%, #05070c 100%) !important;
+  color: var(--cream) !important;
+}
+.gradio-container {
+  max-width: 1180px !important;
+  padding: 22px 22px 34px !important;
+  font-family: Inter, ui-sans-serif, system-ui, sans-serif !important;
+}
+footer { display: none !important; }
+.app-header {
+  display: flex;
+  align-items: flex-end;
+  justify-content: space-between;
+  gap: 24px;
+  margin: 5px 2px 18px;
+}
+.brand-lockup h1 {
+  color: #fff !important;
+  font-family: "Arial Black", Impact, sans-serif;
+  font-size: clamp(2rem, 6vw, 4.7rem);
+  line-height: .84;
+  letter-spacing: -.075em;
+  margin: 7px 0 9px;
+  text-transform: uppercase;
+}
+.brand-lockup h1 span { color: var(--gold); }
+.brand-lockup p { color: var(--muted) !important; margin: 0; max-width: 670px; }
+.eyebrow {
+  color: var(--cyan) !important;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: .72rem;
+  font-weight: 800;
+  letter-spacing: .14em;
+  text-transform: uppercase;
+}
+.model-chip {
+  border: 1px solid rgba(92, 225, 230, .4);
+  border-radius: 999px;
+  color: var(--cyan);
+  flex: 0 0 auto;
+  font: 700 .72rem ui-monospace, monospace;
+  padding: 9px 12px;
+}
+.setup-card {
+  background: linear-gradient(145deg, rgba(22, 27, 48, .98), rgba(8, 11, 21, .98));
+  border: 1px solid var(--line);
+  border-radius: 22px;
+  box-shadow: 0 24px 80px rgba(0, 0, 0, .36);
+  overflow: hidden;
+  padding: 10px;
+}
+.setup-intro {
+  min-height: 100%;
+  padding: 26px 22px;
+  background:
+    linear-gradient(180deg, rgba(7, 10, 18, .08), rgba(7, 10, 18, .92)),
+    url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='80' height='80'%3E%3Cpath d='M0 40h80M40 0v80' stroke='%23ffffff' stroke-opacity='.035'/%3E%3C/svg%3E");
+  border-radius: 15px;
+}
+.setup-intro h2 {
+  color: #fff !important;
+  font-family: "Arial Black", Impact, sans-serif;
+  font-size: clamp(1.8rem, 4vw, 3.2rem);
+  letter-spacing: -.05em;
+  line-height: .95;
+  margin: 24px 0 14px;
+  text-transform: uppercase;
+}
+.setup-intro p { color: var(--muted) !important; line-height: 1.65; }
+.feature-list { display: grid; gap: 11px; margin-top: 26px; }
+.feature {
+  align-items: center;
+  border-top: 1px solid rgba(255,255,255,.09);
+  color: #ddd8ca;
+  display: flex;
+  font-size: .88rem;
+  gap: 10px;
+  padding-top: 11px;
+}
+.feature b { color: var(--gold); font: 800 .72rem ui-monospace, monospace; }
+.form-panel { padding: 18px 14px 12px; }
+.gradio-container label span { color: #d9d5c8 !important; font-weight: 700 !important; }
+.gradio-container textarea,
+.gradio-container input {
+  color: #fff !important;
+}
+.gradio-container .block {
+  border-color: rgba(255,255,255,.12) !important;
+}
+#begin-button, #commit-button {
+  background: linear-gradient(135deg, var(--gold), #ff9f43) !important;
+  border: 0 !important;
+  box-shadow: 0 10px 30px rgba(255, 159, 67, .22);
+  color: #17120a !important;
+  font-family: "Arial Black", Impact, sans-serif !important;
+  letter-spacing: .04em;
+  min-height: 50px;
+  text-transform: uppercase;
+}
+#begin-button:hover, #commit-button:hover { filter: brightness(1.08); transform: translateY(-1px); }
+.microcopy { color: #8f8b80 !important; font-size: .75rem; line-height: 1.5; margin: 9px 2px 0; }
+.game-frame {
+  aspect-ratio: 16 / 9;
+  background: #111;
+  border: 1px solid rgba(255,255,255,.18);
+  border-radius: 22px;
+  box-shadow: 0 26px 90px rgba(0,0,0,.52);
+  isolation: isolate;
+  min-height: 530px;
+  overflow: hidden;
+  position: relative;
+}
+.world-bg {
+  background-position: center;
+  background-size: cover;
+  filter: saturate(.9) contrast(1.04);
+  inset: 0;
+  position: absolute;
+  transform: scale(1.015);
+  z-index: -3;
+}
+.world-shade {
+  background:
+    linear-gradient(90deg, rgba(3,5,10,.88) 0%, rgba(3,5,10,.34) 57%, rgba(3,5,10,.72) 100%),
+    linear-gradient(0deg, rgba(3,5,10,.94) 0%, transparent 38%, rgba(3,5,10,.25) 100%);
+  inset: 0;
+  position: absolute;
+  z-index: -2;
+}
+.scanlines {
+  background: repeating-linear-gradient(0deg, transparent 0, transparent 3px, rgba(0,0,0,.08) 4px);
+  inset: 0;
+  pointer-events: none;
+  position: absolute;
+  z-index: 5;
+}
+.stage-top {
+  align-items: flex-start;
+  display: flex;
+  justify-content: space-between;
+  padding: clamp(16px, 3vw, 28px);
+}
+.scenario-card {
+  backdrop-filter: blur(12px);
+  background: var(--panel);
+  border: 1px solid rgba(255,255,255,.17);
+  border-left: 4px solid var(--gold);
+  border-radius: 6px 16px 16px 6px;
+  box-shadow: 0 18px 55px rgba(0,0,0,.34);
+  max-width: 64%;
+  padding: clamp(15px, 2.5vw, 25px);
+}
+.scene-meta {
+  color: var(--cyan);
+  font: 800 .68rem ui-monospace, monospace;
+  letter-spacing: .12em;
+  text-transform: uppercase;
+}
+.scenario-card h2 {
+  color: #fff !important;
+  font-family: "Arial Black", Impact, sans-serif;
+  font-size: clamp(1.25rem, 3vw, 2.15rem);
+  letter-spacing: -.035em;
+  line-height: 1;
+  margin: 9px 0 12px;
+  text-transform: uppercase;
+}
+.scenario-card p { color: #f0ecdf !important; font-size: clamp(.87rem, 1.5vw, 1rem); line-height: 1.58; margin: 0; }
+.source-line { color: #8f8b80; display: block; font: .64rem ui-monospace, monospace; margin-top: 14px; }
+.hud {
+  backdrop-filter: blur(10px);
+  background: rgba(7,10,18,.84);
+  border: 1px solid rgba(255,255,255,.14);
+  border-radius: 14px;
+  min-width: 210px;
+  padding: 13px;
+  width: 25%;
+}
+.hud-title { color: var(--gold); font: 900 .68rem ui-monospace, monospace; letter-spacing: .12em; margin-bottom: 10px; }
+.metric-row { margin: 8px 0; }
+.metric-label { color: #d6d2c7; display: flex; font: 700 .62rem ui-monospace, monospace; justify-content: space-between; text-transform: uppercase; }
+.metric-track { background: rgba(255,255,255,.11); height: 5px; margin-top: 5px; overflow: hidden; }
+.metric-fill { background: linear-gradient(90deg, var(--cyan), var(--green)); height: 100%; }
+.metric-row.stress .metric-fill { background: linear-gradient(90deg, #ffb347, var(--coral)); }
+.stage-bottom { bottom: 0; display: flex; justify-content: space-between; left: 0; padding: 0 27px 24px; position: absolute; right: 0; }
+.persona-bubble {
+  align-self: flex-end;
+  backdrop-filter: blur(10px);
+  background: rgba(10,13,22,.91);
+  border: 1px solid rgba(255,255,255,.16);
+  border-radius: 14px;
+  display: flex;
+  gap: 12px;
+  max-width: 58%;
+  padding: 10px 13px;
+}
+.persona-bubble img { border: 2px solid var(--cyan); border-radius: 8px; height: 58px; object-fit: cover; width: 58px; }
+.persona-copy b { color: var(--cyan); display: block; font: 800 .68rem ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }
+.persona-copy p { color: #eee9dc !important; font-size: .8rem; line-height: 1.4; margin: 5px 0 0; }
+.player-wrap { align-items: flex-end; display: flex; gap: 12px; }
+.state-pill {
+  background: rgba(7,10,18,.82);
+  border: 1px solid rgba(255,255,255,.15);
+  border-radius: 999px;
+  color: var(--cream);
+  font: 800 .63rem ui-monospace, monospace;
+  margin-bottom: 8px;
+  padding: 7px 10px;
+  text-transform: uppercase;
+}
+.player-sprite {
+  background-repeat: no-repeat;
+  background-size: 400% 100%;
+  filter: drop-shadow(0 16px 9px rgba(0,0,0,.55));
+  height: 142px;
+  image-rendering: pixelated;
+  width: 126px;
+}
+.cascade-banner {
+  animation: slide-in .28s ease-out;
+  background: linear-gradient(90deg, rgba(255,107,95,.96), rgba(118,52,83,.94));
+  border: 1px solid rgba(255,255,255,.2);
+  box-shadow: 0 10px 35px rgba(0,0,0,.35);
+  color: #fff;
+  left: 50%;
+  max-width: 70%;
+  padding: 10px 18px;
+  position: absolute;
+  text-align: center;
+  top: 49%;
+  transform: translate(-50%, -50%);
+  z-index: 4;
+}
+.cascade-banner b { display: block; font: 900 .7rem ui-monospace, monospace; letter-spacing: .12em; text-transform: uppercase; }
+.cascade-banner span { font-size: .76rem; }
+.report-card {
+  backdrop-filter: blur(15px);
+  background: rgba(7,10,18,.94);
+  border: 1px solid rgba(255,255,255,.18);
+  border-top: 4px solid var(--gold);
+  border-radius: 16px;
+  inset: 6%;
+  overflow: auto;
+  padding: clamp(20px, 4vw, 42px);
+  position: absolute;
+  z-index: 4;
+}
+.report-card h2 { color: var(--gold) !important; font: clamp(1.8rem, 5vw, 3.7rem)/.95 "Arial Black", Impact, sans-serif; letter-spacing: -.055em; margin: 8px 0 18px; text-transform: uppercase; }
+.report-card p { color: #e7e2d5 !important; line-height: 1.62; max-width: 850px; }
+.report-card details { color: #aaa59a; margin-top: 18px; }
+.report-card pre { white-space: pre-wrap; }
+.choices-shell {
+  background: rgba(8,11,20,.78);
+  border: 1px solid rgba(255,255,255,.12);
+  border-radius: 18px;
+  margin-top: 14px;
+  padding: 14px;
+}
+.choice-heading { align-items: center; display: flex; justify-content: space-between; margin: 2px 2px 11px; }
+.choice-heading b { color: #fff; font-family: "Arial Black", Impact, sans-serif; letter-spacing: .02em; text-transform: uppercase; }
+.choice-heading span { color: #827e74; font: .66rem ui-monospace, monospace; }
+#choice-cards label {
+  background: rgba(255,255,255,.035) !important;
+  border: 1px solid rgba(255,255,255,.12) !important;
+  border-radius: 10px !important;
+  margin: 6px 0 !important;
+  padding: 11px 12px !important;
+  transition: .16s ease;
+}
+#choice-cards label:hover { background: rgba(255,200,87,.08) !important; border-color: rgba(255,200,87,.55) !important; transform: translateX(3px); }
+#choice-cards label:has(input:checked) { background: rgba(255,200,87,.13) !important; border-color: var(--gold) !important; }
+#path-options label, #persona-options label {
+  background: rgba(255,255,255,.045) !important;
+  border: 1px solid rgba(255,255,255,.11) !important;
+  color: #e6e1d4 !important;
+}
+#path-options label:has(input:checked), #persona-options label:has(input:checked) {
+  background: rgba(255,200,87,.12) !important;
+  border-color: rgba(255,200,87,.7) !important;
+}
+#detected-paths { color: var(--cyan) !important; opacity: .74; }
+#reset-button {
+  background: transparent !important;
+  border: 1px solid rgba(255,255,255,.15) !important;
+  color: #aaa59a !important;
+  margin-top: 11px;
+}
+#reset-button:hover { border-color: rgba(255,200,87,.45) !important; color: var(--gold) !important; }
+@keyframes slide-in { from { opacity: 0; transform: translate(-50%, -42%); } to { opacity: 1; transform: translate(-50%, -50%); } }
+@media (max-width: 760px) {
+  .gradio-container { padding: 12px !important; }
+  .app-header { align-items: flex-start; flex-direction: column; }
+  .game-frame { aspect-ratio: auto; min-height: 660px; }
+  .stage-top { display: block; }
+  .scenario-card { max-width: 100%; }
+  .hud { margin-top: 10px; width: 100%; }
+  .metric-row { display: inline-block; margin: 6px 1.2%; width: 46%; }
+  .stage-bottom { padding: 0 15px 17px; }
+  .persona-bubble { max-width: 74%; }
+  .player-sprite { height: 105px; width: 93px; }
+  .state-pill { display: none; }
+}
+"""
+
+
+@lru_cache(maxsize=32)
+def image_data_uri(path_text: str) -> str:
+    path = Path(path_text)
+    mime = mimetypes.guess_type(path.name)[0] or "image/png"
+    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
+    return f"data:{mime};base64,{encoded}"
+
+
+def parse_paths(dilemma: str) -> tuple[gr.Radio, str]:
+    path_a, path_b = split_dilemma(dilemma)
+    return (
+        gr.Radio(choices=[(path_a, "A"), (path_b, "B")], value="A", label="Choose the future to enter"),
+        f"PATHS DETECTED: {path_a.upper()} / {path_b.upper()}",
+    )
+
+
+def begin(dilemma: str, chosen_key: str, calibration: str, persona: str):
+    if len(dilemma.strip()) < 5:
+        raise gr.Error("Enter a real dilemma first.")
+    if not calibration.strip():
+        raise gr.Error("Add one concrete pressure, constraint, or proof point.")
+    session = start_session(dilemma, chosen_key or "A", calibration, persona)
+    node = current_node(session)
+    return (
+        session,
+        game_html(session, node),
+        gr.Radio(choices=_choice_options(node), value=None, label="Choose your move"),
+        "",
+        gr.Group(visible=False),
+        gr.Column(visible=True),
+        gr.Group(visible=False),
+        gr.Button(interactive=True),
+    )
+
+
+def make_choice(session: SimulationSession, choice_value: str | None, custom_choice: str):
+    if session is None:
+        raise gr.Error("Start a simulation first.")
+    custom = custom_choice.strip()
+    if not custom and choice_value is None:
+        raise gr.Error("Choose an option or write your own move.")
+    result = choose(session, int(choice_value or 0), custom)
+    if result["complete"]:
+        return (
+            session,
+            game_html(
+                session,
+                reaction=result.get("reaction", ""),
+                cascade=result.get("cascade"),
+                report=result["report"],
+            ),
+            gr.Radio(choices=[], value=None),
+            "",
+            gr.Group(visible=True),
+            gr.Column(visible=False),
+            gr.Group(visible=False),
+            gr.Button(interactive=False),
+        )
+    node = result["node"]
+    return (
+        session,
+        game_html(
+            session,
+            node,
+            reaction=result.get("reaction", ""),
+            cascade=result.get("cascade"),
+        ),
+        gr.Radio(choices=_choice_options(node), value=None, label="Choose your move"),
+        "",
+        gr.Group(visible=False),
+        gr.Column(visible=True),
+        gr.Group(visible=False),
+        gr.Button(interactive=True),
+    )
+
+
+def reset():
+    return (
+        None,
+        "",
+        gr.Radio(choices=[], value=None),
+        "",
+        gr.Group(visible=False),
+        gr.Column(visible=False),
+        gr.Group(visible=True),
+        gr.Button(interactive=True),
+    )
+
+
+def game_html(
+    session: SimulationSession,
+    node: dict[str, Any] | None = None,
+    reaction: str = "",
+    cascade: dict[str, str] | None = None,
+    report: dict[str, Any] | None = None,
+) -> str:
+    state = environment_state(session.world_state)
+    background = image_data_uri(environment_image(session))
+    sprite = image_data_uri(str(ROOT / "assets" / "characters" / "character.png"))
+    portrait = image_data_uri(str(PERSONA_ASSETS[session.persona]))
+    sprite_position = {"thriving": "100%", "stable": "33.333%", "struggling": "66.666%"}[state]
+    node = node or {
+        "month_label": "Future report",
+        "node_theme": "reflection",
+        "scenario": "",
+        "generation_source": "causal ledger",
+    }
+
+    cascade_markup = ""
+    if cascade:
+        cascade_markup = f"""
+        <div class="cascade-banner">
+          <b>{html.escape(cascade['label'])}</b>
+          <span>{html.escape(cascade['memory'])} {html.escape(cascade['effect'])}</span>
+        </div>
+        """
+
+    persona_text = reaction or (
+        f"I'll stay with you through this version of {session.chosen_path}. "
+        "Pay attention to what each choice costs, not only what it promises."
+    )
+    persona_markup = f"""
+      <div class="persona-bubble">
+        <img src="{portrait}" alt="{html.escape(session.persona)}">
+        <div class="persona-copy">
+          <b>{html.escape(session.persona)}</b>
+          <p>{html.escape(persona_text)}</p>
+        </div>
+      </div>
+    """
+
+    report_markup = report_html(report) if report else ""
+    return f"""
+    <div class="game-frame">
+      <div class="world-bg" style="background-image:url('{background}')"></div>
+      <div class="world-shade"></div>
+      <div class="stage-top">
+        <section class="scenario-card">
+          <div class="scene-meta">{html.escape(node['month_label'])} / {html.escape(node['node_theme'])}</div>
+          <h2>{html.escape(session.chosen_path)}</h2>
+          <p>{html.escape(node['scenario'])}</p>
+          <small class="source-line">SOURCE: {html.escape(node.get('generation_source', 'deterministic')).upper()}</small>
+        </section>
+        {metrics_html(session)}
+      </div>
+      {cascade_markup}
+      <div class="stage-bottom">
+        {persona_markup}
+        <div class="player-wrap">
+          <span class="state-pill">World: {state}</span>
+          <div class="player-sprite" style="background-image:url('{sprite}');background-position:{sprite_position} 0"></div>
+        </div>
+      </div>
+      {report_markup}
+      <div class="scanlines"></div>
+    </div>
+    """
+
+
+def metrics_html(session: SimulationSession) -> str:
+    labels = {
+        "financial_security": "Financial",
+        "creative_fulfillment": "Fulfillment",
+        "social_validation": "Validation",
+        "stress": "Stress",
+        "family_satisfaction": "Family",
+    }
+    rows = []
+    for key in METRICS:
+        value = session.world_state[key]
+        rows.append(
+            f"""
+            <div class="metric-row {'stress' if key == 'stress' else ''}">
+              <div class="metric-label"><span>{labels[key]}</span><span>{value}</span></div>
+              <div class="metric-track"><div class="metric-fill" style="width:{value}%"></div></div>
+            </div>
+            """
+        )
+    return f"<aside class='hud'><div class='hud-title'>LIVE WORLD STATE</div>{''.join(rows)}</aside>"
+
+
+def report_html(report: dict[str, Any]) -> str:
+    ledger = html.escape(
+        json.dumps(
+            {"facts": report["facts"], "obligations": report["obligations"]},
+            indent=2,
+        )
+    )
+    return f"""
+    <section class="report-card">
+      <div class="eyebrow">Simulation complete / causal reflection</div>
+      <h2>{html.escape(report['archetype'])}</h2>
+      <p>{html.escape(report['summary'])}</p>
+      <p>{html.escape(report['honest_mirror'])}</p>
+      <details><summary>Open the causal ledger</summary><pre>{ledger}</pre></details>
+    </section>
+    """
+
+
+def _choice_options(node: dict[str, Any]) -> list[tuple[str, str]]:
+    return [(choice["text"], str(index)) for index, choice in enumerate(node["choices"])]
+
+
+theme = gr.themes.Base(
+    primary_hue="orange",
+    neutral_hue="slate",
+    font=[gr.themes.GoogleFont("Inter"), "ui-sans-serif", "system-ui"],
+).set(
+    body_background_fill="#070a12",
+    block_background_fill="#0d1120",
+    block_border_color="rgba(255,255,255,.12)",
+    input_background_fill="#080b15",
+    input_border_color="rgba(255,255,255,.14)",
+)
+
+with gr.Blocks(css=CSS, theme=theme, title="LifeChoice Simulator") as demo:
+    session_state = gr.State()
+    gr.HTML(
+        f"""
+        <header class="app-header">
+          <div class="brand-lockup">
+            <div class="eyebrow">A causal future simulator</div>
+            <h1>Life<span>Choice</span></h1>
+            <p>Enter one road not taken. Make decisions inside it. Watch the world remember.</p>
+          </div>
+          <div class="model-chip">{MODEL_ID} / 7B</div>
+        </header>
+        """
+    )
+
+    with gr.Group(elem_classes="setup-card") as setup_group:
+        with gr.Row(equal_height=True):
+            with gr.Column(scale=5):
+                gr.HTML(
+                    """
+                    <section class="setup-intro">
+                      <div class="eyebrow">New simulation</div>
+                      <h2>Try the future<br>before it happens.</h2>
+                      <p>This is not a chatbot. It is an eight-node causal simulation with persistent metrics, delayed consequences, and a world that changes with your decisions.</p>
+                      <div class="feature-list">
+                        <div class="feature"><b>01</b> Immediate first scene</div>
+                        <div class="feature"><b>02</b> Choices produce distinct state changes</div>
+                        <div class="feature"><b>03</b> Your persona remembers what happened</div>
+                      </div>
+                    </section>
+                    """
+                )
+            with gr.Column(scale=6, elem_classes="form-panel"):
+                dilemma = gr.Textbox(
+                    label="The fork in the road",
+                    placeholder="Artist vs Software Engineer",
+                    value="MTech vs Software Job",
+                )
+                path_choice = gr.Radio(
+                    choices=[("MTech", "A"), ("Software Job", "B")],
+                    value="A",
+                    label="Choose the future to enter",
+                    elem_id="path-options",
+                )
+                detected = gr.Markdown(
+                    "PATHS DETECTED: MTECH / SOFTWARE JOB",
+                    elem_classes="eyebrow",
+                    elem_id="detected-paths",
+                )
+                calibration = gr.Textbox(
+                    label="What makes this decision real?",
+                    placeholder="A pressure, deadline, responsibility, or proof point...",
+                    value="My family needs income soon, but a professor is already interested in my research.",
+                    lines=2,
+                )
+                persona = gr.Radio(
+                    choices=["Family", "Friend", "Mentor", "Partner", "Inner Voice"],
+                    value="Mentor",
+                    label="Choose the voice that follows you",
+                    elem_id="persona-options",
+                )
+                begin_btn = gr.Button("Enter this future", variant="primary", elem_id="begin-button")
+                gr.HTML(
+                    "<p class='microcopy'>Reflective simulation only. Not medical, legal, financial, or professional advice. The first scene starts immediately while later scenes prepare in the background.</p>"
+                )
+
+    with gr.Group(visible=False) as game_group:
+        game_board = gr.HTML()
+        with gr.Column(visible=False, elem_classes="choices-shell") as play_column:
+            gr.HTML("<div class='choice-heading'><b>What do you do?</b><span>YOUR DECISION CHANGES THE STATE</span></div>")
+            choices = gr.Radio(choices=[], show_label=False, elem_id="choice-cards")
+            custom = gr.Textbox(
+                label="Or make your own move",
+                placeholder="Describe one specific action...",
+                lines=1,
+            )
+            choose_btn = gr.Button("Commit choice", variant="primary", elem_id="commit-button")
+        with gr.Group(visible=False) as report_group:
+            gr.Markdown(
+                "The report reflects patterns in your causal ledger. It does not predict your future or tell you what to do."
+            )
+        reset_btn = gr.Button("Start a different simulation", variant="secondary", elem_id="reset-button")
+
+    dilemma.change(parse_paths, dilemma, [path_choice, detected], show_progress="hidden")
+    begin_btn.click(
+        begin,
+        [dilemma, path_choice, calibration, persona],
+        [session_state, game_board, choices, custom, report_group, play_column, setup_group, choose_btn],
+    ).then(lambda: gr.Group(visible=True), outputs=game_group, show_progress="hidden")
+    choose_btn.click(
+        make_choice,
+        [session_state, choices, custom],
+        [session_state, game_board, choices, custom, report_group, play_column, setup_group, choose_btn],
+    )
+    reset_btn.click(
+        reset,
+        outputs=[session_state, game_board, choices, custom, report_group, play_column, setup_group, choose_btn],
+        show_progress="hidden",
+    ).then(lambda: gr.Group(visible=False), outputs=game_group, show_progress="hidden")
+
+if __name__ == "__main__":
+    demo.queue(default_concurrency_limit=8).launch()

assets/environments/.gitkeep

@@ -0,0 +1 @@
+

docs/compliance-checklist.md

@@ -0,0 +1,42 @@
+# Build Small Hackathon Compliance
+
+Verified on June 13, 2026.
+
+| Requirement | Status | Evidence |
+|---|---|---|
+| Use a model under 32B | Complete | Runtime model is `Qwen/Qwen2.5-7B-Instruct` at 7.616B parameters |
+| Keep every fallback under 32B | Complete | No secondary model is configured; fallback behavior is deterministic Python |
+| Every model is under 32B | Complete | Hub metadata: 7,615,616,512 parameters; `MODEL_MANIFEST.json`; compliance tests |
+| Deploy as Gradio Space | Blocked externally | Gradio app and guarded deploy script are complete |
+| Host under `build-small-hackathon` | Blocked externally | `Ajeya95` lacks an active writable CLI login/organization Space-creation permission |
+| Public without local setup | Pending Space deployment | Space frontmatter, dependencies, and deterministic no-token mode are complete |
+| Public demo video | Complete | `docs/lifechoice-demo.mp4`, publicly served from GitHub |
+| Public social media post | Blocked externally | Final copy is in `docs/social-post.md`; installed connectors cannot publish |
+| Demo video link in README | Complete | README links the public GitHub-hosted MP4 |
+| Social post link in README | Pending publication | Placeholder remains explicit |
+| Hackathon frontmatter tags | Complete | README YAML frontmatter |
+| Short top description | Complete | First paragraph under title |
+| Screenshots/GIFs | Complete | Four browser-verified screenshots |
+| Architecture diagram image | Complete | `docs/architecture.svg` |
+| Built with Codex section | Complete | README section |
+| Codex-attributed commits | Complete | Commits `6929152` and `a340a52` |
+| AI safety/disclaimer | Complete | UI and README |
+| Explain why not a chatbot | Complete | README architecture explanation |
+| Models and stack documented | Complete | README and model manifest |
+| Test full Space incognito | Pending Space deployment | Full local browser flow verified; public Space cannot yet exist under target org |
+| Verify no model violates rule | Complete | Automated source scan and manifest tests |
+| Target requested categories | Complete | README lists Thousand Token Wood, Best Agent, Best Demo, OpenAI Prize |
+| Modal credits | Not targeted | No claim made |
+| Off Brand | Not targeted | Custom UI exists, but no category claim made |
+| Tiny Titan | Not targeted | 7.616B model, so no claim made |
+| OpenBMB | Not targeted | No MiniCPM claim |
+| NVIDIA | Not targeted | No Nemotron claim |
+
+## Verification Commands
+
+```bash
+pytest -q
+python scripts/deploy_space.py
+```
+
+The deployment command intentionally refuses to use any Hub identity other than `Ajeya95`.

docs/create_demo_video.py

@@ -0,0 +1,78 @@
+from pathlib import Path
+
+import imageio.v2 as imageio
+import numpy as np
+from PIL import Image, ImageDraw, ImageFont
+
+
+ROOT = Path(__file__).resolve().parent
+OUT = ROOT / "lifechoice-demo.mp4"
+SIZE = (1280, 720)
+FPS = 12
+
+
+def font(size: int, bold: bool = False):
+    names = [
+        "C:/Windows/Fonts/arialbd.ttf" if bold else "C:/Windows/Fonts/arial.ttf",
+        "C:/Windows/Fonts/segoeuib.ttf" if bold else "C:/Windows/Fonts/segoeui.ttf",
+    ]
+    for name in names:
+        if Path(name).exists():
+            return ImageFont.truetype(name, size)
+    return ImageFont.load_default()
+
+
+def title_card(title: str, subtitle: str) -> Image.Image:
+    image = Image.new("RGB", SIZE, "#080812")
+    draw = ImageDraw.Draw(image)
+    draw.rounded_rectangle((80, 90, 1200, 630), radius=32, fill="#141128", outline="#7568ff", width=3)
+    draw.text((130, 155), "BUILD SMALL HACKATHON", fill="#a99fff", font=font(24, True))
+    draw.text((130, 245), title, fill="white", font=font(62, True))
+    draw.multiline_text((130, 350), subtitle, fill="#d3cee7", font=font(30), spacing=12)
+    return image
+
+
+def screenshot_card(filename: str, heading: str, caption: str, crop_top: int = 0) -> Image.Image:
+    source = Image.open(ROOT / "screenshots" / filename).convert("RGB")
+    source = source.crop((0, crop_top, source.width, min(source.height, crop_top + int(source.width * 0.56))))
+    source.thumbnail((1120, 540), Image.Resampling.LANCZOS)
+    image = Image.new("RGB", SIZE, "#080812")
+    draw = ImageDraw.Draw(image)
+    draw.text((70, 34), heading, fill="white", font=font(34, True))
+    x = (SIZE[0] - source.width) // 2
+    image.paste(source, (x, 100))
+    draw.rounded_rectangle((60, 640, 1220, 700), radius=16, fill="#18152e")
+    draw.text((90, 656), caption, fill="#eeeaff", font=font(22))
+    return image
+
+
+def write_frames(writer, image: Image.Image, seconds: float) -> None:
+    frame = np.asarray(image)
+    for _ in range(round(FPS * seconds)):
+        writer.append_data(frame)
+
+
+def main() -> None:
+    cards = [
+        (title_card("LifeChoice Simulator", "A causal decision simulator, not another chatbot.\nQwen2.5-7B + Gradio + deterministic state."), 3.0),
+        (screenshot_card("onboarding.png", "Start in seconds", "One concrete calibration answer takes you directly into the simulation."), 4.0),
+        (screenshot_card("simulation.png", "Immediate first scene", "The opening is deterministic; later nodes prefetch in the background."), 4.0),
+        (screenshot_card("cascade.png", "Choices return later", "Facts, obligations, and closed options make branches materially different.", 500), 4.0),
+        (screenshot_card("report.png", "A report grounded in behavior", "Five metrics, three cascade moments, and a bounded causal ledger.", 500), 4.0),
+        (title_card("Small model. Real state.", "7.616B parameters. No 32B+ fallback.\nBuilt with Codex for the Build Small Hackathon."), 3.0),
+    ]
+    with imageio.get_writer(
+        OUT,
+        fps=FPS,
+        codec="libx264",
+        quality=8,
+        pixelformat="yuv420p",
+        macro_block_size=1,
+    ) as writer:
+        for card, seconds in cards:
+            write_frames(writer, card, seconds)
+    print(OUT)
+
+
+if __name__ == "__main__":
+    main()

docs/demo-script.md

@@ -0,0 +1,20 @@
+# Public Demo Video Script
+
+Target length: 75-90 seconds.
+
+1. Open the public Hugging Face Space and show that no local setup is required.
+2. Enter `MTech vs Software Job`.
+3. Highlight the single calibration answer and immediate first scene.
+4. Choose a high-risk option and show all five metrics and the environment update.
+5. Explain the causal ledger: facts, obligations, and closed options.
+6. Advance to the node-2 echo and node-5 delayed consequence.
+7. Show a different choice changing the later scene.
+8. Finish on the report and safety disclaimer.
+9. Close with: “One 7B model, bounded context, deterministic state, and a playable future rather than another chatbot.”
+
+Suggested title: `LifeChoice Simulator | Build Small Hackathon Demo`
+
+Suggested description:
+
+> LifeChoice Simulator turns a real dilemma into a causal, metric-driven future. Built with Gradio, Qwen2.5-7B-Instruct, Hugging Face, and Codex for the Build Small Hackathon.
+

docs/lifechoice-demo.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8e21579f0cc2a5bd22a36aaf456315ae09fb255452eea5f1663253ad04eba5a7
+size 696040

docs/social-post.md

@@ -0,0 +1,16 @@
+# Social Post Draft
+
+I built **LifeChoice Simulator** for the Hugging Face Build Small Hackathon.
+
+Instead of chatting about a difficult decision, you step into one path and play through eight consequential moments. Every choice changes five metrics, creates durable facts and obligations, alters the visual world, and can return later as a cascade.
+
+The agent uses **Qwen2.5-7B-Instruct**, bounded context, strict validation, and deterministic fallbacks. No model is 32B or larger.
+
+Built with Gradio, Hugging Face, and Codex.
+
+Live Space: [ADD PUBLIC SPACE URL]
+Code: [ADD PUBLIC GITHUB URL]
+Demo: [ADD PUBLIC VIDEO URL]
+
+#BuildSmall #HuggingFace #Gradio #AI #Codex
+

lifechoice_engine.py

@@ -0,0 +1,559 @@
+from __future__ import annotations
+
+import copy
+import json
+import os
+import re
+import threading
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+MODEL_ID = "Qwen/Qwen2.5-7B-Instruct"
+MODEL_PARAMETERS_B = 7
+METRICS = (
+    "financial_security",
+    "creative_fulfillment",
+    "social_validation",
+    "stress",
+    "family_satisfaction",
+)
+MONTHS = ("Month 1", "Month 2", "Month 3", "Month 4", "Month 5", "Month 6", "Month 8", "Month 10")
+THEMES = (
+    "first commitment",
+    "money pressure",
+    "social comparison",
+    "identity friction",
+    "family pressure",
+    "delayed consequence",
+    "survival versus meaning",
+    "final reckoning",
+)
+EXECUTOR = ThreadPoolExecutor(max_workers=4, thread_name_prefix="lifechoice")
+
+
+@dataclass
+class SimulationSession:
+    dilemma: str
+    chosen_path: str
+    unchosen_path: str
+    calibration: str
+    persona: str
+    environment_category: str
+    world_state: dict[str, int]
+    characters: dict[str, dict[str, str]]
+    current_node: int = 0
+    history: list[dict[str, Any]] = field(default_factory=list)
+    facts: list[str] = field(default_factory=list)
+    obligations: list[str] = field(default_factory=list)
+    closed_options: list[str] = field(default_factory=list)
+    generated_nodes: dict[int, dict[str, Any]] = field(default_factory=dict)
+    pending_nodes: dict[int, Future] = field(default_factory=dict, repr=False)
+    lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+
+def split_dilemma(dilemma: str) -> tuple[str, str]:
+    text = " ".join(dilemma.strip().split())
+    for pattern in (r"\s+vs\.?\s+", r"\s+versus\s+", r"\s*/\s*", r"\s+or\s+"):
+        parts = re.split(pattern, text, maxsplit=1, flags=re.IGNORECASE)
+        if len(parts) == 2 and all(parts):
+            return _label(parts[0]), _label(parts[1])
+    return _label(text) or "Path A", "Safer Alternative"
+
+
+def start_session(
+    dilemma: str,
+    chosen_key: str,
+    calibration: str,
+    persona: str,
+) -> SimulationSession:
+    path_a, path_b = split_dilemma(dilemma)
+    chosen, unchosen = (path_b, path_a) if chosen_key == "B" else (path_a, path_b)
+    session = SimulationSession(
+        dilemma=dilemma.strip(),
+        chosen_path=chosen,
+        unchosen_path=unchosen,
+        calibration=calibration.strip(),
+        persona=persona,
+        environment_category=infer_environment(chosen),
+        world_state=derive_initial_world_state(dilemma, calibration),
+        characters=_characters(chosen, unchosen),
+    )
+    session.generated_nodes[0] = build_node(session, 0, use_llm=False)
+    prefetch_node(session, 1)
+    return session
+
+
+def choose(session: SimulationSession, choice_index: int, custom_text: str = "") -> dict[str, Any]:
+    node = current_node(session)
+    if custom_text.strip():
+        choice = _custom_choice(node, custom_text.strip())
+        choice_index = -1
+    else:
+        choice_index = max(0, min(choice_index, len(node["choices"]) - 1))
+        choice = node["choices"][choice_index]
+
+    for key in METRICS:
+        session.world_state[key] = _clamp(session.world_state[key] + int(choice["delta"].get(key, 0)))
+
+    record = {
+        "node_index": session.current_node,
+        "month_label": node["month_label"],
+        "theme": node["node_theme"],
+        "scenario": node["scenario"],
+        "choice_index": choice_index,
+        "choice_text": choice["text"],
+        "delta": copy.deepcopy(choice["delta"]),
+        "world_state_after": copy.deepcopy(session.world_state),
+    }
+    session.history.append(record)
+    _merge_unique(session.facts, choice.get("facts_created", []), limit=10)
+    _merge_unique(session.obligations, choice.get("obligations", []), limit=6)
+    _merge_unique(session.closed_options, choice.get("closed_options", []), limit=6)
+    session.current_node += 1
+
+    reaction = persona_reaction(session, record)
+    cascade = cascade_for(session, record)
+    if session.current_node >= len(MONTHS):
+        return {"complete": True, "record": record, "reaction": reaction, "cascade": cascade, "report": build_report(session)}
+
+    next_node = _consume_or_build(session, session.current_node)
+    prefetch_node(session, session.current_node + 1)
+    return {
+        "complete": False,
+        "record": record,
+        "reaction": reaction,
+        "cascade": cascade,
+        "node": next_node,
+    }
+
+
+def current_node(session: SimulationSession) -> dict[str, Any]:
+    return session.generated_nodes[session.current_node]
+
+
+def prefetch_node(session: SimulationSession, index: int) -> None:
+    if index >= len(MONTHS) or index in session.generated_nodes or index in session.pending_nodes:
+        return
+    snapshot = compact_context(session)
+    session.pending_nodes[index] = EXECUTOR.submit(build_node_from_context, snapshot, index, True)
+
+
+def compact_context(session: SimulationSession) -> dict[str, Any]:
+    return {
+        "dilemma": session.dilemma,
+        "chosen_path": session.chosen_path,
+        "unchosen_path": session.unchosen_path,
+        "calibration": session.calibration[:360],
+        "persona": session.persona,
+        "world_state": copy.deepcopy(session.world_state),
+        "characters": copy.deepcopy(session.characters),
+        "facts": session.facts[-8:],
+        "obligations": session.obligations[-5:],
+        "closed_options": session.closed_options[-5:],
+        "recent_choices": [
+            {"month": item["month_label"], "choice": item["choice_text"]}
+            for item in session.history[-3:]
+        ],
+    }
+
+
+def build_node(session: SimulationSession, index: int, use_llm: bool = True) -> dict[str, Any]:
+    return build_node_from_context(compact_context(session), index, use_llm)
+
+
+def build_node_from_context(context: dict[str, Any], index: int, use_llm: bool = True) -> dict[str, Any]:
+    fallback = deterministic_node(context, index)
+    if not use_llm:
+        return fallback
+    generated = _generate_node_with_hf(context, index)
+    return validate_node(generated, fallback, context)
+
+
+def deterministic_node(context: dict[str, Any], index: int) -> dict[str, Any]:
+    chosen = context["chosen_path"]
+    unchosen = context["unchosen_path"]
+    state = context["world_state"]
+    pressure = state_facts(state)
+    prior = context.get("recent_choices", [])
+    prior_text = prior[-1]["choice"] if prior else f"step into {chosen}"
+    facts = context.get("facts") or ["your first commitment"]
+    fact = facts[-1]
+
+    scenarios = (
+        f"A real opening appears on the {chosen} path. Taking it makes your decision visible to people who still expect {unchosen}. {pressure[0]}",
+        f"The first bill and deadline arrive together. Your choice to {prior_text.lower()} now has a practical cost. {pressure[0]}",
+        f"A peer posts a polished update from {unchosen} while your progress stays private. {pressure[1]}",
+        f"An easier offer would protect your routine but blur the identity you wanted from {chosen}. {pressure[0]}",
+        f"Your family asks for proof that {chosen} can become sustainable. The conversation is shaped by {fact}. {pressure[1]}",
+        f"An earlier commitment returns as an opportunity with conditions attached. You cannot accept it without paying a cost created months ago. {pressure[0]}",
+        f"You are no longer choosing only between paths. You are choosing what structure makes {chosen} survivable. {pressure[1]}",
+        f"Ten months in, the outside decision is clearer. The final choice is whether your version of {chosen} can carry both meaning and responsibility. {pressure[0]}",
+    )
+    choices = _choice_templates(chosen, unchosen, index)
+    return {
+        "month_label": MONTHS[index],
+        "node_theme": THEMES[index],
+        "scenario": scenarios[index],
+        "choices": choices,
+        "generation_source": "deterministic",
+    }
+
+
+def _choice_templates(chosen: str, unchosen: str, index: int) -> list[dict[str, Any]]:
+    templates = (
+        (
+            (f"Accept the first concrete {chosen} opportunity and tell people you are committed", _delta(-7, 12, 5, 9, -3), ["publicly_committed"], ["prove_progress"], []),
+            (f"Negotiate a smaller {chosen} commitment while keeping income or study stability", _delta(5, 5, 1, 2, 3), ["built_a_safety_floor"], ["maintain_two_tracks"], []),
+            (f"Delay the move and keep {unchosen} fully available for another month", _delta(6, -7, -3, 7, 4), ["delayed_commitment"], ["make_a_deadline"], []),
+        ),
+        (
+            ("Cut optional spending and protect time for the path you chose", _delta(-4, 8, -2, 7, -4), ["protected_the_bold_path"], ["tight_budget"], []),
+            ("Take paid side work and reduce the pace of the main path", _delta(10, -3, 3, 5, 4), ["added_paid_work"], ["less_time_for_core_path"], []),
+            (f"Pause {chosen} until savings recover, even if momentum disappears", _delta(12, -11, 4, -5, 7), ["paused_for_money"], [], ["current_momentum"]),
+        ),
+        (
+            ("Share unfinished work publicly and accept comparison as part of growth", _delta(-1, 6, 11, 8, -1), ["became_visible"], ["respond_to_feedback"], []),
+            ("Ignore the comparison and protect a private building phase", _delta(1, 8, -5, 2, 0), ["chose_private_progress"], [], []),
+            (f"Ask someone on {unchosen} for an honest comparison of both paths", _delta(3, 1, 5, 4, 3), ["sought_cross_path_advice"], ["face_comparison"], []),
+        ),
+        (
+            ("Reject the easier offer because it changes what the work means to you", _delta(-10, 13, -2, 8, -3), ["protected_identity"], ["replace_lost_income"], ["easy_offer"]),
+            ("Accept the compromise and use the stability to recover", _delta(13, -7, 5, -6, 7), ["accepted_compromise"], [], []),
+            ("Negotiate narrower terms that preserve both income and ownership", _delta(6, 6, 3, 4, 2), ["negotiated_middle_path"], ["deliver_negotiated_terms"], []),
+        ),
+        (
+            ("Show your family the real plan, including risks and deadlines", _delta(2, 2, 3, -3, 11), ["shared_full_plan"], ["report_progress"], []),
+            ("Hide the uncertainty until results become visible", _delta(0, 4, -2, 9, -9), ["hid_the_messy_parts"], ["maintain_the_story"], []),
+            ("Let family concern change the next move toward stability", _delta(8, -8, 5, -3, 12), ["family_changed_direction"], [], ["unrestricted_risk"]),
+        ),
+        (
+            ("Accept the returning opportunity and absorb its delayed cost", _delta(-11, 13, 9, 12, -4), ["accepted_delayed_payoff"], ["pay_delayed_cost"], []),
+            ("Decline because the earlier choice made the cost unsustainable", _delta(8, -10, -2, -7, 6), ["declined_delayed_payoff"], [], ["returning_opportunity"]),
+            ("Redesign the opportunity around the obligations you already created", _delta(4, 7, 5, 3, 4), ["redesigned_consequence"], ["honor_existing_obligations"], []),
+        ),
+        (
+            ("Build a financial and time floor around the meaningful work", _delta(12, 6, 2, -9, 5), ["built_sustainable_structure"], ["follow_weekly_limits"], []),
+            ("Push harder for visible progress and accept another intense season", _delta(-6, 10, 8, 14, -5), ["chose_intensity"], ["recover_after_push"], []),
+            (f"Return to {unchosen} as the main path and keep this work secondary", _delta(14, -12, 7, -5, 9), ["returned_to_alternative"], [], ["chosen_path_as_primary"]),
+        ),
+        (
+            ("Commit to the chosen path with explicit money, health, and relationship boundaries", _delta(8, 11, 6, -10, 7), ["committed_with_boundaries"], [], []),
+            (f"Choose {unchosen} and preserve the meaningful parts as a serious side practice", _delta(14, -7, 8, -7, 10), ["chose_stability_with_meaning"], [], ["chosen_path_as_primary"]),
+            ("Run a measured three-month experiment before using a permanent label", _delta(5, 5, 1, -2, 2), ["chose_measured_experiment"], ["define_success_metrics"], []),
+        ),
+    )
+    result = []
+    for text, delta, facts, obligations, closed in templates[index]:
+        result.append(
+            {
+                "text": text,
+                "delta": delta,
+                "facts_created": facts,
+                "obligations": obligations,
+                "closed_options": closed,
+            }
+        )
+    return result
+
+
+def validate_node(data: Any, fallback: dict[str, Any], context: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(data, dict) or not isinstance(data.get("choices"), list) or len(data["choices"]) != 3:
+        return fallback
+    scenario = " ".join(str(data.get("scenario", "")).split())[:420]
+    if len(scenario) < 50 or not narrative_respects_state(scenario, context["world_state"]):
+        return fallback
+    choices = []
+    for index, raw in enumerate(data["choices"]):
+        if not isinstance(raw, dict) or len(str(raw.get("text", ""))) < 12:
+            return fallback
+        base = fallback["choices"][index]
+        choices.append(
+            {
+                "text": " ".join(str(raw["text"]).split())[:150],
+                "delta": _normalize_delta(raw.get("delta")),
+                "facts_created": _clean_list(raw.get("facts_created")) or base["facts_created"],
+                "obligations": _clean_list(raw.get("obligations")),
+                "closed_options": _clean_list(raw.get("closed_options")),
+            }
+        )
+    return {**fallback, "scenario": scenario, "choices": choices, "generation_source": "hf_llm"}
+
+
+def narrative_respects_state(text: str, state: dict[str, int]) -> bool:
+    lower = text.lower()
+    if state["stress"] >= 80 and not any(word in lower for word in ("stress", "tired", "exhaust", "pressure", "overwhelm", "sleep")):
+        return False
+    if state["financial_security"] <= 25 and not any(word in lower for word in ("money", "rent", "bill", "saving", "income", "cost", "financial")):
+        return False
+    if state["family_satisfaction"] <= 25 and not any(word in lower for word in ("family", "home", "parent", "trust", "conversation")):
+        return False
+    return True
+
+
+def state_facts(state: dict[str, int]) -> list[str]:
+    facts = []
+    if state["financial_security"] <= 25:
+        facts.append("Money is now urgent enough to constrain the available choices.")
+    elif state["financial_security"] >= 75:
+        facts.append("Savings provide room to choose without immediate panic.")
+    if state["stress"] >= 80:
+        facts.append("Exhaustion is visible and cannot be treated as background noise.")
+    elif state["stress"] <= 30:
+        facts.append("You have enough emotional room to think beyond survival.")
+    if state["family_satisfaction"] <= 30:
+        facts.append("Trust at home is strained and affects the next decision.")
+    if state["creative_fulfillment"] >= 75:
+        facts.append("The work feels meaningful enough that walking away has a real emotional cost.")
+    if state["social_validation"] <= 30:
+        facts.append("Progress is difficult to explain publicly, increasing isolation.")
+    while len(facts) < 2:
+        facts.append("The trade-off remains real: every available move protects one value by spending another.")
+    return facts[:2]
+
+
+def persona_reaction(session: SimulationSession, record: dict[str, Any]) -> str:
+    index = record["node_index"]
+    if index not in {0, 1, 3, 5, 7} and not _threshold_crossed(record):
+        return ""
+    choice = record["choice_text"]
+    state = session.world_state
+    if session.persona == "Inner Voice":
+        return f"I chose to {choice.lower()}, and I can feel which cost I am pretending not to notice."
+    if session.persona == "Friend":
+        return f"I understand why you chose to {choice.lower()}. Just do not confuse momentum with proof that the pressure is sustainable."
+    if session.persona == "Mentor":
+        return f"What does choosing to {choice.lower()} protect that the safer option cannot, and what obligation did it create?"
+    if session.persona == "Partner":
+        return f"I support the reason behind this choice, but stress is at {state['stress']}; our shared plan has to include that cost."
+    return f"I see why you chose to {choice.lower()}, but stability and family trust are part of the decision too, not enemies of it."
+
+
+def cascade_for(session: SimulationSession, record: dict[str, Any]) -> dict[str, str] | None:
+    index = record["node_index"]
+    if index not in {2, 5, 7} or not session.history:
+        return None
+    source_index = 0 if index in {2, 5} else min(3, len(session.history) - 1)
+    source = session.history[source_index]
+    labels = {2: "A small echo", 5: "The delayed consequence", 7: "The final payoff"}
+    return {
+        "label": labels[index],
+        "memory": f"In {source['month_label']}, you chose: {source['choice_text']}",
+        "effect": "That decision changed the constraints and obligations shaping this moment.",
+    }
+
+
+def build_report(session: SimulationSession) -> dict[str, Any]:
+    state = session.world_state
+    risk_count = sum(1 for item in session.history if item["delta"].get("stress", 0) >= 7)
+    structure_count = sum(1 for item in session.history if item["delta"].get("financial_security", 0) >= 5)
+    meaning_count = sum(1 for item in session.history if item["delta"].get("creative_fulfillment", 0) >= 5)
+    if meaning_count > structure_count:
+        archetype = "Meaning Builder"
+    elif structure_count > meaning_count:
+        archetype = "Practical Architect"
+    else:
+        archetype = "Measured Explorer"
+    return {
+        "archetype": archetype,
+        "summary": (
+            f"You made {meaning_count} meaning-protecting moves, {structure_count} stabilizing moves, "
+            f"and {risk_count} high-pressure moves while testing {session.chosen_path}."
+        ),
+        "honest_mirror": (
+            f"Your choices show that {session.chosen_path} is attractive only when it can become livable. "
+            f"You did not simply choose courage or safety; you repeatedly negotiated between identity, money, and relationships. "
+            f"The causal record matters: {', '.join(session.facts[-3:]) or 'you kept options open'}. "
+            f"Your next real-world experiment should test those obligations without treating this simulation as a prediction."
+        ),
+        "world_state": copy.deepcopy(state),
+        "facts": session.facts,
+        "obligations": session.obligations,
+        "model": MODEL_ID,
+    }
+
+
+def environment_image(session: SimulationSession) -> str:
+    state = environment_state(session.world_state)
+    path = Path(__file__).parent / "assets" / "environments"
+    return str(path / f"{session.environment_category}_{state}.png")
+
+
+def environment_state(state: dict[str, int]) -> str:
+    wellbeing = (
+        state["financial_security"]
+        + state["creative_fulfillment"]
+        + state["social_validation"]
+        + state["family_satisfaction"]
+        + (100 - state["stress"])
+    ) / 5
+    if state["stress"] >= 82 or state["financial_security"] <= 18 or wellbeing < 38:
+        return "struggling"
+    if wellbeing >= 67 and state["stress"] <= 55:
+        return "thriving"
+    return "stable"
+
+
+def infer_environment(path: str) -> str:
+    text = path.lower()
+    mapping = (
+        (("artist", "art", "music", "design", "film", "creative", "writer"), "studio_creative"),
+        (("startup", "founder", "business"), "startup_chaotic"),
+        (("phd", "mtech", "college", "study", "masters", "research"), "campus_academic"),
+        (("doctor", "medical", "neet", "hospital"), "medical_clinical"),
+        (("corporate", "manager", "consulting", "mba"), "corporate"),
+    )
+    for words, category in mapping:
+        if any(word in text for word in words):
+            return category
+    return "tech_office"
+
+
+def derive_initial_world_state(dilemma: str, calibration: str) -> dict[str, int]:
+    state = {
+        "financial_security": 58,
+        "creative_fulfillment": 58,
+        "social_validation": 50,
+        "stress": 42,
+        "family_satisfaction": 50,
+    }
+    text = f"{dilemma} {calibration}".lower()
+    if any(word in text for word in ("rent", "loan", "salary", "money", "saving", "fees")):
+        state["financial_security"] -= 13
+        state["stress"] += 9
+    if any(word in text for word in ("family", "parent", "approval", "relatives")):
+        state["family_satisfaction"] -= 11
+        state["stress"] += 6
+    if any(word in text for word in ("passion", "meaning", "creative", "research", "freedom")):
+        state["creative_fulfillment"] += 10
+    if any(word in text for word in ("offer", "admitted", "selected", "client", "revenue")):
+        state["social_validation"] += 8
+        state["stress"] -= 3
+    return {key: _clamp(value) for key, value in state.items()}
+
+
+def _consume_or_build(session: SimulationSession, index: int) -> dict[str, Any]:
+    fallback = build_node(session, index, use_llm=False)
+    context = compact_context(session)
+    future = session.pending_nodes.pop(index, None)
+    if future and future.done():
+        try:
+            node = validate_node(future.result(), fallback, context)
+        except Exception:
+            node = fallback
+    else:
+        node = fallback
+    session.generated_nodes[index] = node
+    return node
+
+
+def _generate_node_with_hf(context: dict[str, Any], index: int) -> Any:
+    token = os.getenv("HF_TOKEN")
+    try:
+        from huggingface_hub import InferenceClient
+
+        client = InferenceClient(model=MODEL_ID, token=token, timeout=12)
+        prompt = {
+            "task": "Generate one LifeChoice Simulator decision node as strict JSON.",
+            "rules": [
+                "Exactly three materially different choices.",
+                "Each choice must create a fact and use all five integer delta keys from -15 to 15.",
+                "Respect metric constraints and causal facts. Never contradict closed options.",
+                "No advice, diagnosis, certainty, or prediction.",
+            ],
+            "month": MONTHS[index],
+            "theme": THEMES[index],
+            "context": context,
+            "schema": {
+                "scenario": "string",
+                "choices": [
+                    {
+                        "text": "string",
+                        "delta": {key: 0 for key in METRICS},
+                        "facts_created": ["string"],
+                        "obligations": ["string"],
+                        "closed_options": ["string"],
+                    }
+                ],
+            },
+        }
+        response = client.chat_completion(
+            messages=[{"role": "user", "content": json.dumps(prompt, ensure_ascii=True)}],
+            max_tokens=850,
+            temperature=0.55,
+        )
+        text = response.choices[0].message.content
+        match = re.search(r"\{.*\}", text, flags=re.DOTALL)
+        return json.loads(match.group(0)) if match else None
+    except Exception:
+        return None
+
+
+def _custom_choice(node: dict[str, Any], text: str) -> dict[str, Any]:
+    totals = {key: 0 for key in METRICS}
+    for choice in node["choices"]:
+        for key in METRICS:
+            totals[key] += int(choice["delta"].get(key, 0))
+    return {
+        "text": text[:150],
+        "delta": {key: round(value / len(node["choices"])) for key, value in totals.items()},
+        "facts_created": [f"custom_choice_{_slug(text)[:40]}"],
+        "obligations": ["review_custom_choice_consequences"],
+        "closed_options": [],
+    }
+
+
+def _characters(chosen: str, unchosen: str) -> dict[str, dict[str, str]]:
+    return {
+        "family": {"name": "Family", "context": f"Wants {chosen} to have a credible safety floor."},
+        "friend": {"name": "Friend", "context": f"Chose {unchosen} and provides a living comparison."},
+        "mentor": {"name": "Mentor", "context": f"Five years ahead on {chosen}, including its difficult middle."},
+    }
+
+
+def _threshold_crossed(record: dict[str, Any]) -> bool:
+    state = record["world_state_after"]
+    return state["stress"] >= 80 or state["financial_security"] <= 20 or state["family_satisfaction"] <= 25
+
+
+def _delta(financial: int, creative: int, social: int, stress: int, family: int) -> dict[str, int]:
+    return dict(
+        financial_security=financial,
+        creative_fulfillment=creative,
+        social_validation=social,
+        stress=stress,
+        family_satisfaction=family,
+    )
+
+
+def _normalize_delta(value: Any) -> dict[str, int]:
+    if not isinstance(value, dict):
+        value = {}
+    return {key: max(-15, min(15, int(value.get(key, 0)))) for key in METRICS}
+
+
+def _clean_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [_slug(str(item))[:60] for item in value[:3] if str(item).strip()]
+
+
+def _merge_unique(target: list[str], values: list[str], limit: int) -> None:
+    for value in values:
+        if value and value not in target:
+            target.append(value)
+    del target[:-limit]
+
+
+def _slug(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", value.lower()).strip("_")
+
+
+def _label(value: str) -> str:
+    cleaned = re.sub(r"^(?:i am |i'm |should i |choose |between )", "", value.strip(), flags=re.IGNORECASE)
+    return " ".join(word if word.isupper() else word.capitalize() for word in cleaned.strip(" ?.,").split())
+
+
+def _clamp(value: int) -> int:
+    return max(0, min(100, int(value)))

requirements.txt

@@ -0,0 +1,3 @@
+gradio>=5.33,<6
+huggingface_hub>=0.30
+pytest>=8.0