Big Leagues Calling

README.md

@@ -7,6 +7,7 @@ sdk: gradio
 sdk_version: 6.17.3
 python_version: '3.12'
 app_file: app.py
+hf_oauth: true
 pinned: true
 license: apache-2.0
 short_description: A text-image based RPG built to help fight procrastination
@@ -27,9 +28,15 @@ boss quest you face first.
   reference, then edits that same image into success / "retreat to fight another day" states.
 
 Your photo and quest state live in your browser (localStorage) **and** in a private per-user JSON
-record on the Space's storage, keyed by a random **Hero Code** shown in the left panel — write it
-down and paste it on any device (or after a cleared browser) to get everything back. No login.
-The photo is sent to the GPU only transiently during generation.
+record on the Space's storage. **Sign in with your Hugging Face account** (top right) and the
+record is keyed to your account — same state on any device, nothing to remember. Logged out, it's
+keyed by a random **Hero Code** shown in the left panel instead — paste it on a new device (or
+after a cleared browser) to get everything back. The photo is sent to the GPU only transiently
+during generation.
+
+NOTE: after enabling/changing `hf_oauth`, fully restart (factory rebuild) the Space so the OAuth
+login route gets registered — clicking Sign in before that yields a "Could not parse server
+response" error.
 
 ### Durable storage (Storage Bucket)
 

app.py

@@ -48,7 +48,7 @@ def _warmup():
 MODEL_IMPORT_ERROR = None
 try:
     from llm import generate_campaign_raw, generate_quests_raw, route_intent
-    from images import edit_image, initial_image, pil_to_data_url
+    from images import edit_image, initial_image, initial_images, pil_to_data_url
 except Exception:
     MODEL_IMPORT_ERROR = traceback.format_exc()
 
@@ -208,7 +208,8 @@ def select_quest(qid, photo, adventure, images, quests, campaigns, browser):
     images = dict(images or {})
     quest = _find(quests, qid)
     if quest is None:
-        return qid, None, _desc_html(None, adventure), images, _merge(browser, selected_id=qid)
+        return (qid, None, _desc_html(None, adventure), images,
+                _persist_browser(_merge(browser, selected_id=qid)))
 
     world = _world_for(quest, adventure, campaigns)
     cache = dict(images.get(qid) or {})
@@ -232,7 +233,8 @@ def select_quest(qid, photo, adventure, images, quests, campaigns, browser):
             images[qid] = cache
             images = _trim_images(images, qid)
             scene = pil
-    return qid, scene, _desc_html(quest, world or adventure, hint), images, _merge(browser, selected_id=qid, images=images)
+    return (qid, scene, _desc_html(quest, world or adventure, hint), images,
+            _persist_browser(_merge(browser, selected_id=qid, images=images)))
 
 
 def _apply_result(qid, quests, adventure, photo, images, campaigns, browser, kind, reason):
@@ -309,7 +311,7 @@ def remove_quest(qid, quests, adventure, images, selected_id, browser):
         if data:
             scene = _dataurl_to_pil(data)
     return (quests, images, selected_id, scene, _desc_html(quest, adventure), _stats_html(quests),
-            _merge(browser, quests=quests, images=images, selected_id=selected_id))
+            _persist_browser(_merge(browser, quests=quests, images=images, selected_id=selected_id)))
 
 
 # ----------------------------- chat (Frog Master, full intent routing) -----------------------------
@@ -338,9 +340,22 @@ def _resolve_target(quests: list, target: str, selected_id):
     return selected_id
 
 
+def _batch_initials(photo, art_style, seed, quests, images, keep_id):
+    """ONE batched GPU call generating every quest's initial scene into the images cache.
+    Mutates and returns `images`. No-op without a photo (lazy/hint path takes over)."""
+    if not photo or not quests:
+        return images
+    pils = initial_images(_dataurl_to_pil(photo), art_style,
+                          [q.get("initial_image_prompt", "") for q in quests], int(seed))
+    for q, pil in zip(quests, pils):
+        images.setdefault(q["id"], {})["initial"] = pil_to_data_url(pil)
+    return _trim_images(images, keep_id)
+
+
 def _do_forge(message, theme, photo, quests_old, images_old, campaigns, browser):
     """Forge a fresh DAY log. Campaign quests (and their cached scenes) survive the re-forge —
-    only standalone day quests are replaced."""
+    only standalone day quests are replaced. With a photo present, ALL day scenes are generated
+    eagerly in one batched GPU call (clicking quests afterwards is instant)."""
     raw = generate_quests_raw(message, theme)
     adv = validate_and_clamp(raw, theme)
     day_quests, adventure = adv["quests"], adv["adventure"]
@@ -352,6 +367,9 @@ def _do_forge(message, theme, photo, quests_old, images_old, campaigns, browser)
     quests = day_quests + keep
     images = {k: v for k, v in (images_old or {}).items() if k in keep_ids}
     frog_id = day_quests[0]["id"]
+    images = _batch_initials(photo, adventure["art_style"], adventure["seed"],
+                             day_quests, images, frog_id)
+    # Cache is warm now (or photo absent) -> this just selects the frog; no extra GPU call.
     _sel, scene, desc, images2, _b = select_quest(frog_id, photo, adventure, images, quests,
                                                   campaigns, browser)
     browser2 = _merge(browser, theme=theme, adventure=adventure, quests=quests,
@@ -414,12 +432,15 @@ def upload_photo(pil, browser):
     return b64, _merge(browser, photo=b64)
 
 
-# forge_campaign outputs (order): campaign_goal_box, quests_state, campaigns_state, stats_html, browser
-def forge_campaign(goal, do_research, theme, quests, campaigns, browser):
+# forge_campaign outputs (order): campaign_goal_box, quests_state, campaigns_state, stats_html,
+#                                 images_state, selected_id_state, scene_image, desc_html, browser
+def forge_campaign(goal, do_research, theme, photo, quests, campaigns, images, browser):
     """One long-term goal -> a campaign + its ordered quest chain, appended to the log. With
-    do_research, ddgs+BS4 snippets ground the plan (research.py; degrades gracefully without it)."""
+    do_research, ddgs+BS4 snippets ground the plan (research.py; degrades gracefully without it).
+    With a photo present, ALL the campaign's scenes are generated in one batched GPU call and the
+    first quest is shown."""
     goal = (goal or "").strip()
-    nochange = (gr.update(),) * 4
+    nochange = (gr.update(),) * 8
     if not goal:
         gr.Info("Name your long-term goal first.")
         return (gr.update(),) + nochange
@@ -433,7 +454,7 @@ def forge_campaign(goal, do_research, theme, quests, campaigns, browser):
     snippets, sources = "", []
     if do_research:
         try:
-            from research import research_goal  # lazy: optional until Phase 3 ships
+            from research import research_goal
             gr.Info("Scouting the web for your goal…")
             r = research_goal(goal)
             snippets = "\n".join(f"- {s}" for s in r.get("snippets") or [])
@@ -450,10 +471,20 @@ def forge_campaign(goal, do_research, theme, quests, campaigns, browser):
     camp = result["campaign"]
     camp["sources"] = sources
     campaigns2 = campaigns + [camp]
-    quests2 = list(quests or []) + result["quests"]
-    gr.Info(f"Campaign forged: {camp['title']} — {len(result['quests'])} quests.")
-    return ("", quests2, campaigns2, _stats_html(quests2),
-            _merge(browser, quests=quests2, campaigns=campaigns2))
+    new_quests = result["quests"]
+    quests2 = list(quests or []) + new_quests
+    first = new_quests[0]
+
+    images2 = _batch_initials(photo, camp["art_style"], camp["seed"],
+                              new_quests, dict(images or {}), first["id"])
+    cache = images2.get(first["id"]) or {}
+    scene = _dataurl_to_pil(cache["initial"]) if cache.get("initial") else None
+    desc = _desc_html(first, _world_for(first, None, campaigns2),
+                      None if scene else "Upload your photo (left) to draw this scene.")
+    gr.Info(f"Campaign forged: {camp['title']} — {len(new_quests)} quests.")
+    return ("", quests2, campaigns2, _stats_html(quests2), images2, first["id"], scene, desc,
+            _merge(browser, quests=quests2, campaigns=campaigns2, images=images2,
+                   selected_id=first["id"]))
 
 
 def change_theme(theme, adventure, images, browser):
@@ -478,29 +509,44 @@ def reset_all(uid):
 
 
 def persist(uid, browser):
-    """Write-through the full state to the user's durable SQLite record. No-op when logged out
-    (anonymous users live in BrowserState only). Bound via .then(...) after every write event."""
+    """Write-through the full state to the user's durable server record. Bound via .then(...) on
+    TOP-LEVEL events only — never on events created inside @gr.render: a render re-run re-registers
+    those functions under new indices, so a queued .then step 500s with KeyError."""
     store.save(uid, browser)
 
 
-def _hero_code_html(uid) -> str:
+def _persist_browser(b):
+    """In-handler persistence for @gr.render-created events (quest select/remove), where a chained
+    .then(persist) would break (see persist's docstring). The uid travels inside the browser dict."""
+    store.save((b or {}).get("uid"), b)
+    return b
+
+
+def _hero_code_html(uid, hf_user=None) -> str:
+    if hf_user:
+        return (f'<p class="hint">Synced to your Hugging Face account (<b>{_esc(hf_user)}</b>) — '
+                'no code needed. Your quests follow your login on any device.</p>')
     return (f'<p class="hint">Your Hero Code: <b>{_esc(uid)}</b><br>Write it down — paste it on '
-            'any device (or after a cleared browser) to summon this hero back.</p>')
+            'any device (or after a cleared browser) to summon this hero back. Or just sign in '
+            'with Hugging Face (top right) and skip the code.</p>')
 
 
-def boot(browser):
-    """Restore on page load. The uid ("Hero Code") lives in the browser dict; the server-side JSON
-    record for that uid is the source of truth and is mirrored back into BrowserState. A fresh
-    browser gets a new uid. Shows cached scenes only (never generates) so reloads are instant."""
+def boot(browser, request: gr.Request):
+    """Restore on page load. Identity precedence: a logged-in HF account ("hf-<username>", durable
+    and cross-device) > the browser dict's random uid ("Hero Code") > a freshly generated one.
+    The server-side JSON record for that uid is the source of truth and is mirrored back into
+    BrowserState; on first sight of an identity the browser's current state migrates into it.
+    Shows cached scenes only (never generates) so reloads are instant."""
     b = dict(browser or _default_state())
-    uid = b.get("uid") or uuid.uuid4().hex[:12]
+    hf_user = getattr(request, "username", None) if request is not None else None
+    uid = f"hf-{hf_user}" if hf_user else (b.get("uid") or uuid.uuid4().hex[:12])
     saved = store.load(uid)
     if saved:
         b = saved
     b["uid"] = uid
     if not saved:
-        store.save(uid, b)  # first visit under this uid: adopt the browser's current state
-    return _rehydrate(uid, b)
+        store.save(uid, b)  # first visit under this identity: adopt the browser's current state
+    return _rehydrate(uid, b, hf_user)
 
 
 def restore_hero(code, browser):
@@ -514,7 +560,7 @@ def restore_hero(code, browser):
     return _rehydrate(code, saved)
 
 
-def _rehydrate(uid, b):
+def _rehydrate(uid, b, hf_user=None):
     """Build the full page state tuple (shared by boot and restore_hero)."""
     photo = b.get("photo")
     quests = b.get("quests") or []
@@ -533,8 +579,8 @@ def _rehydrate(uid, b):
             scene = _dataurl_to_pil(data)
     photo_pil = _dataurl_to_pil(photo) if photo else None
     world = _world_for(quest, adventure, campaigns) or adventure
-    return (uid, _hero_code_html(uid), b, photo_pil, photo, quests, campaigns, adventure, selected,
-            images, scene, _desc_html(quest, world), _stats_html(quests), theme)
+    return (uid, _hero_code_html(uid, hf_user), b, photo_pil, photo, quests, campaigns, adventure,
+            selected, images, scene, _desc_html(quest, world), _stats_html(quests), theme)
 
 
 # ----------------------------- UI -----------------------------
@@ -554,7 +600,9 @@ with gr.Blocks(title="FrogQuest") as demo:
     campaign_filter_state = gr.State(None)  # campaign id to filter the quest log by (None = all)
     uid_state = gr.State(None)            # the "Hero Code" uid; generated by boot, lives in BrowserState
 
-    gr.HTML('<div class="fq-topbar"><h1 class="fq-logo">FROG<b>QUEST</b></h1></div>')
+    with gr.Row(elem_classes=["fq-topbar"]):
+        gr.HTML('<h1 class="fq-logo">FROG<b>QUEST</b></h1>')
+        gr.LoginButton(elem_classes=["fq-login"])
 
     with gr.Row(elem_classes=["fq-app-grid"]):
         # ---------- LEFT: hero ----------
@@ -677,7 +725,7 @@ with gr.Blocks(title="FrogQuest") as demo:
                                     inputs=[photo_state, adventure_state, images_state, quests_state,
                                             campaigns_state, browser],
                                     outputs=[selected_id_state, scene_image, desc_html, images_state, browser],
-                                ).then(persist, [uid_state, browser])
+                                )  # NO .then here: render-internal chains 500 (see persist docstring)
                                 # Clear button appears only once a quest is done/failed, to remove it.
                                 if finished:
                                     clr = gr.Button("✕", elem_classes=["pix-btn", "small", "fq-task-clear"])
@@ -687,7 +735,7 @@ with gr.Blocks(title="FrogQuest") as demo:
                                         inputs=[quests_state, adventure_state, images_state, selected_id_state, browser],
                                         outputs=[quests_state, images_state, selected_id_state, scene_image,
                                                  desc_html, stats_html, browser],
-                                    ).then(persist, [uid_state, browser])
+                                    )  # NO .then here: render-internal chains 500 (see persist docstring)
 
     # ---------- BOTTOM: Frog Master chat ----------
     with gr.Row(elem_classes=["fq-chatbar"]):
@@ -723,9 +771,10 @@ with gr.Blocks(title="FrogQuest") as demo:
     ).then(persist, [uid_state, browser])
 
     campaign_btn.click(
-        forge_campaign, [campaign_goal_box, research_check, theme_radio, quests_state,
-                         campaigns_state, browser],
-        [campaign_goal_box, quests_state, campaigns_state, stats_html, browser],
+        forge_campaign, [campaign_goal_box, research_check, theme_radio, photo_state, quests_state,
+                         campaigns_state, images_state, browser],
+        [campaign_goal_box, quests_state, campaigns_state, stats_html, images_state,
+         selected_id_state, scene_image, desc_html, browser],
     ).then(persist, [uid_state, browser])
 
     _chat_inputs = [chat_input, quests_state, adventure_state, theme_radio, photo_state,

images.py

@@ -98,6 +98,15 @@ def _initial_image_local(user_photo: Image.Image, art_style: str, scene_prompt:
     return _gen(build_initial_prompt(art_style, scene_prompt), image=[user_photo], seed=seed)
 
 
+def _initial_images_local(user_photo: Image.Image, art_style: str, scene_prompts: list[str],
+                          seed: int) -> list[Image.Image]:
+    """Batch: ALL of a forge's initial scenes in ONE GPU call. On ZeroGPU each @spaces.GPU call is
+    a separate metered reservation (+~30s admission overhead), so looping initial_image would cost
+    N reservations; here the pipeline loads once and the gens run back-to-back."""
+    return [_gen(build_initial_prompt(art_style, p), image=[user_photo], seed=seed)
+            for p in scene_prompts]
+
+
 def _edit_image_local(base_image: Image.Image, edit_instruction: str, art_style: str, seed: int) -> Image.Image:
     """Edit the existing image into a success/failure state."""
     return _gen(build_edit_prompt(art_style, edit_instruction), image=base_image, seed=seed)
@@ -111,6 +120,13 @@ def _initial_image_modal(user_photo: Image.Image, art_style: str, scene_prompt:
     return flux.initial.remote(user_photo, art_style, scene_prompt, seed)
 
 
+def _initial_images_modal(user_photo: Image.Image, art_style: str, scene_prompts: list[str],
+                          seed: int) -> list[Image.Image]:
+    import modal
+    flux = modal.Cls.from_name("frogquest", "Flux")()
+    return flux.initials.remote(user_photo, art_style, scene_prompts, seed)
+
+
 def _edit_image_modal(base_image: Image.Image, edit_instruction: str, art_style: str, seed: int) -> Image.Image:
     import modal
     flux = modal.Cls.from_name("frogquest", "Flux")()
@@ -120,9 +136,11 @@ def _edit_image_modal(base_image: Image.Image, edit_instruction: str, art_style:
 # ----------------------------- bind public names from the backend -----------------------------
 if BACKEND == "modal":
     initial_image = _initial_image_modal
+    initial_images = _initial_images_modal
     edit_image = _edit_image_modal
 else:
     initial_image = spaces.GPU(duration=30)(_initial_image_local)
+    initial_images = spaces.GPU(duration=60)(_initial_images_local)  # one reservation, many gens
     edit_image = spaces.GPU(duration=30)(_edit_image_local)
 
 

modal_app.py

@@ -191,6 +191,12 @@ class Flux:
     def initial(self, user_photo, art_style: str, scene_prompt: str, seed: int):
         return self._gen(build_initial_prompt(art_style, scene_prompt), [user_photo], seed)
 
+    @modal.method()
+    def initials(self, user_photo, art_style: str, scene_prompts: list, seed: int):
+        """Batch counterpart of initial() — all of a forge's scenes in one container call."""
+        return [self._gen(build_initial_prompt(art_style, p), [user_photo], seed)
+                for p in scene_prompts]
+
     @modal.method()
     def edit(self, base_image, edit_instruction: str, art_style: str, seed: int):
         return self._gen(build_edit_prompt(art_style, edit_instruction), base_image, seed)