oracles/story_graph.py

"""Branching story graph for the Wizard's Oracles.

Replaces the linear ``5 random obstacles → dragon → epilogue`` chain
with a hand-authored DAG of 15 obstacle nodes that branch on trials
2, 3, and 4 and converge into one of 5 distinct endings on trial 5.

Each node knows its own ``setup`` text in en + zh, the candidate
successor node-ids, and (for trial-5 boss nodes) the ``ending_id``
to play once the player survives that boss.

Branch picking happens at trials 2/3/4 — when the player finishes a
trial, the runtime calls ``pick_next_node()`` which asks the LLM
"given the player's narration so far and oracle history, pick one of
these N candidates."  This is a tiny separate LLM call per fork
(not the main trial resolution), so failures fall back to a
deterministic heuristic and never block gameplay.

The graph is fantasy-theme only for now. Other themes still run the
old random-obstacles flow.
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Optional


# ---------------------------------------------------------------------------
# Node + ending dataclasses
# ---------------------------------------------------------------------------


@dataclass
class StoryNode:
    """One obstacle on the branching tree.

    Two ways a node's surface text can be rendered:

    * **Hand-authored** (fantasy theme): ``setup_en`` / ``setup_zh`` are
      vivid 2-3 sentence descriptions, used verbatim.
    * **LLM-rendered** (every other theme): the ``concept`` field is a
      short theme-neutral role description (e.g. "first gatekeeper —
      a single large antagonist blocks a chokepoint the apprentice MUST
      cross"). At send-off time, ``generate_themed_setups`` fires one
      LLM call per node that expands the concept into the target theme's
      world and language.

    ``shape`` is the obstacle shape (beast / trap / passage / seekers /
    finale) — controls which sprite gets composited into the trial
    image.

    ``trial`` is the trial number (1..5) this node lives at — used
    only for sanity-checking + tree-rendering.

    ``successors`` is the list of node ids the player can transition to
    after resolving this node. For trial-5 nodes ``successors`` is
    empty and ``ending_id`` is set instead.

    ``ending_id`` (only on trial-5 nodes) selects which ENDINGS entry
    plays as the epilogue.

    ``tag`` is a soft thematic tag (action / wit / mystic / cunning /
    lore) the LLM uses as a hint when picking branches.
    """
    id: str
    trial: int
    shape: str
    setup_en: str
    setup_zh: str
    concept: str = ""
    tag: str = ""
    successors: list = field(default_factory=list)
    ending_id: str = ""
    is_dragon: bool = False

    def setup(self, lang: str) -> str:
        if lang == "zh" and self.setup_zh:
            return self.setup_zh
        return self.setup_en


@dataclass
class Ending:
    id: str
    title_en: str
    title_zh: str
    seed_en: str
    seed_zh: str
    shape: str = ""    # theme-neutral outcome shape — LLM expands per theme

    def title(self, lang: str) -> str:
        return self.title_zh if lang == "zh" and self.title_zh else self.title_en

    def seed(self, lang: str) -> str:
        return self.seed_zh if lang == "zh" and self.seed_zh else self.seed_en


# ---------------------------------------------------------------------------
# The graph: 15 obstacle nodes (1 → 2 → 4 → 4 → 4) + 5 endings
# ---------------------------------------------------------------------------
#
# Structure:
#   T1: hornet_oak                      (shared opening)
#   T2: troll_bridge | sphinx_riddle    (combat / wit fork)
#   T3: bandit_archers | wraith_fog     (from troll)
#       smuggler_bazaar | sunken_archive(from sphinx)
#   T4: spectral_ferryman | wailing_gorge | whispering_vault | hall_of_mirrors
#   T5 bosses: dragon_violent | dragon_greedy | dragon_ancient | dragon_mirrored
#   (the fifth "secret" ending is reachable via a meta route described below)
#
# Branching: each T1/T2/T3/T4 node lists 2 successors. The runtime
# picks one via an LLM call (see pick_next_node()).
# ---------------------------------------------------------------------------


STORY_GRAPH: dict = {

    # =====================================================================
    # TRIAL 1 — shared opening
    # =====================================================================
    "hornet_oak": StoryNode(
        id="hornet_oak",
        trial=1,
        shape="seekers",
        tag="opening",
        concept=(
            "OPENING SWARM. Countless small hostile things (insects, dust, "
            "shards, particles, drones, etc.) erupt from a natural opening "
            "and cover the only forward path. The apprentice cannot retreat. "
            "Establishes tone."
        ),
        setup_en=(
            "A black river of hornets boils out of a split hollow oak and "
            "covers the path ahead. The buzzing is so loud it shakes the "
            "leaves on the ground. The forest behind is shut by their "
            "wings; the only way forward is through them."
        ),
        setup_zh=(
            "黑色的胡蜂从一棵裂开的空心橡树里涌出，覆盖了前方的小径，"
            "嗡嗡声震得地上的落叶都在颤动。身后被它们的翅膀封住——只能"
            "穿过这片蜂海前行。"
        ),
        successors=["troll_bridge", "sphinx_riddle"],
    ),

    # =====================================================================
    # TRIAL 2 — first fork: combat path vs wit path
    # =====================================================================
    "troll_bridge": StoryNode(
        id="troll_bridge",
        trial=2,
        shape="beast",
        tag="combat",
        concept=(
            "FIRST GATEKEEPER. A single LARGE solitary antagonist with an "
            "obvious weapon stands on the only crossing/passage. It has "
            "refused to let anyone through for years. Combat-coded, no "
            "speech beyond threats."
        ),
        setup_en=(
            "A grey troll the size of an ox squats on the only stone bridge "
            "across the gorge. It has a rusted greataxe across its knees "
            "and a necklace of dried teeth, and it has not let anyone pass "
            "in seven years."
        ),
        setup_zh=(
            "一只灰色的山妖蹲在跨越峡谷的唯一石桥上，体形如牛，膝上横"
            "着一柄锈迹斑斑的巨斧，胸前挂着一串干瘪的牙齿。七年了，它"
            "没有放任何人过桥。"
        ),
        successors=["bandit_archers", "wraith_fog"],
    ),
    "sphinx_riddle": StoryNode(
        id="sphinx_riddle",
        trial=2,
        shape="seekers",
        tag="wit",
        concept=(
            "FIRST TEST OF WITS. A riddler / interrogator / oracle with the "
            "power to kill blocks the path and demands a correct answer to "
            "a single question. Surrounded by the remains of failures. "
            "Wit-coded."
        ),
        setup_en=(
            "A grey sphinx with the body of a lion and the cracked face of "
            "an old woman blocks the mountain pass. She offers a single "
            "riddle in a voice like wind through dry reeds — and warns "
            "that all who answer wrong have already been eaten."
        ),
        setup_zh=(
            "一只灰色的斯芬克斯挡住了山路，狮身，老妇人裂纹般的面容。她"
            "用风吹过干芦苇般的嗓音抛出一个谜语，并冷冷地告诉旅人——所有"
            "答错的人，她早已吃尽。"
        ),
        successors=["smuggler_bazaar", "sunken_archive"],
    ),

    # =====================================================================
    # TRIAL 3 — second fork (4 nodes)
    # =====================================================================
    "bandit_archers": StoryNode(
        id="bandit_archers",
        trial=3,
        shape="seekers",
        tag="action",
        concept=(
            "ARMED AMBUSH. Multiple hostile mortals (3-7) with ranged "
            "weapons rise from cover, weapons already aimed. They have "
            "done this many times. The apprentice is in the open. Quick decisive "
            "action required."
        ),
        setup_en=(
            "Five bandit archers rise from behind a low stone wall, arrows "
            "already nocked. Their faces are masked in soot and they say "
            "nothing — they only point their bows and wait, in a line, "
            "with the patience of people who have done this many times."
        ),
        setup_zh=(
            "五名蒙面强盗从矮石墙后站起，箭已搭弦。他们用煤灰涂黑脸，"
            "一言不发，只是排成一排把弓对准来者，那耐心是干过无数次的"
            "样子。"
        ),
        successors=["spectral_ferryman", "wailing_gorge"],
    ),
    "wraith_fog": StoryNode(
        id="wraith_fog",
        trial=3,
        shape="passage",
        tag="mystic",
        concept=(
            "DISORIENTING OTHERWORLDLY PASSAGE. A wall of fog / mist / "
            "void / static / shadow rolls across the road. Half-real "
            "figures inside mutter contradictory directions that loop the "
            "traveler. The air is colder. Mystic-coded."
        ),
        setup_en=(
            "A wall of grey fog rolls across the road, and within it the "
            "shadows of long-dead travelers stagger sideways, mumbling "
            "directions that always loop back to where they started. "
            "Stepping in feels like stepping into a colder country."
        ),
        setup_zh=(
            "一堵灰雾横在路上，雾里晃动着早已死去的旅人的影子，他们"
            "斜着身子，喃喃自语，所指的方向永远绕回原地。踏入雾中，仿"
            "佛踏进了另一个更冷的国度。"
        ),
        successors=["spectral_ferryman", "whispering_vault"],
    ),
    "smuggler_bazaar": StoryNode(
        id="smuggler_bazaar",
        trial=3,
        shape="trap",
        tag="cunning",
        concept=(
            "DANGEROUS MARKETPLACE. A black-market / hidden bazaar of "
            "contraband, lit unnaturally. A one-eyed / scarred merchant "
            "already knows the apprentice's name. He offers safe passage for "
            "a 'small' price — the price will ruin the apprentice. Cunning-coded."
        ),
        setup_en=(
            "A midnight bazaar opens between rotten warehouses — caged "
            "beasts, contraband relics, a one-eyed merchant who knows "
            "your name. He says he can sell you safe passage. He says "
            "his price is small. He says it with a smile that has no warmth."
        ),
        setup_zh=(
            "腐朽的仓库之间，一场午夜集市悄然开张：笼中走兽、私运的"
            "圣物，一名独眼商人径自唤出旅人的名字。他说他能贩售你一段"
            "安然无虞的路。他说价钱不高。他笑着说——笑里全无暖意。"
        ),
        successors=["wailing_gorge", "hall_of_mirrors"],
    ),
    "sunken_archive": StoryNode(
        id="sunken_archive",
        trial=3,
        shape="passage",
        tag="lore",
        concept=(
            "FLOODED REPOSITORY OF KNOWLEDGE. A half-ruined archive / "
            "library / data-vault / scriptorium under water/sand/snow. "
            "Holds a map or key the apprentice needs. Something is also waiting "
            "in here, patient. Lore-coded."
        ),
        setup_en=(
            "A door under the riverbank opens onto a flooded library — "
            "marble shelves, books rotting in still water up to your "
            "chest, a single guttering candle waiting. Somewhere in here "
            "is a map. Something else in here is waiting for the map "
            "to be found."
        ),
        setup_zh=(
            "河岸下一扇门通往一座被淹的藏书阁——大理石书架，浸到胸口"
            "的死水里腐烂的旧卷，一支孤零零的烛火等在那儿。这里某处藏"
            "着一张地图。这里某物正等着这张地图被找到。"
        ),
        successors=["whispering_vault", "hall_of_mirrors"],
    ),

    # =====================================================================
    # TRIAL 4 — convergence layer (4 themed gates)
    # =====================================================================
    "spectral_ferryman": StoryNode(
        id="spectral_ferryman",
        trial=4,
        shape="passage",
        tag="action+mystic",
        concept=(
            "TOLL-KEEPER OF PASSAGE. A liminal figure (ferryman / gate-"
            "keeper / customs officer) at the only crossing. Refuses "
            "money. Demands payment in the form of the apprentice confessing "
            "the most violent act of his life — aloud, in detail."
        ),
        setup_en=(
            "At the black river a hooded ferryman waits, his face two coins "
            "and a held breath. He takes no money. He takes the most violent "
            "thing the traveler has ever done, and he expects to be paid in "
            "the telling. The far bank is the only road on."
        ),
        setup_zh=(
            "黑河之畔，一名戴风帽的渡夫正等候，他的脸只剩两枚铜钱与一口"
            "屏住的气。他不收银钱，他收旅人此生最暴烈的一桩往事——并要"
            "你亲口讲出。彼岸是唯一可继续前行的路。"
        ),
        successors=["dragon_violent"],
    ),
    "wailing_gorge": StoryNode(
        id="wailing_gorge",
        trial=4,
        shape="trap",
        tag="action+cunning",
        concept=(
            "CROSSING OF FEAR. A precarious crossing (rope-bridge / "
            "narrow ledge / failing transit) over a deadly drop. The "
            "wind / silence / hum BECOMES a voice that knows the apprentice's "
            "specific debts and demands payment in backsteps. Each "
            "backstep degrades the crossing."
        ),
        setup_en=(
            "The gorge mouths out as a single rope-bridge over a drop so "
            "deep the bottom is just noise. Halfway across, the wind turns "
            "into a voice that knows the traveler's debts and demands "
            "payment in steps backwards. Every backstep is a length of "
            "rope that frays."
        ),
        setup_zh=(
            "峡谷口仅余一座绳桥，桥下深不见底，只剩呼啸的回声。行至中"
            "段，风化成了人声——它说出旅人欠下的每一笔账，要求他以倒退"
            "的步子偿还。每后退一步，绳索就磨损一段。"
        ),
        successors=["dragon_greedy"],
    ),
    "whispering_vault": StoryNode(
        id="whispering_vault",
        trial=4,
        shape="passage",
        tag="mystic+lore",
        concept=(
            "ANCIENT INTERLOCUTOR. A sealed chamber / hibernation pod / "
            "buried mind that opens only for THIS apprentice. Inside is a "
            "voice that has had centuries to think. It will trade the "
            "next step for the apprentice's most precious memory."
        ),
        setup_en=(
            "A vault sealed for nine hundred years opens to the traveler "
            "alone. Inside is one chair, one cup, and one voice that has "
            "had nothing to do but think since before the language was "
            "written. It will trade the next step for the traveler's "
            "favorite memory."
        ),
        setup_zh=(
            "一座封闭九百年的密室独为这位旅人开启。其中只一张椅、一只"
            "杯，与一道声音——它在语言诞生之前就独自思索，至今未停。它"
            "愿换旅人最爱的一段回忆，以换得下一步可走。"
        ),
        successors=["dragon_ancient"],
    ),
    "hall_of_mirrors": StoryNode(
        id="hall_of_mirrors",
        trial=4,
        shape="trap",
        tag="cunning+lore",
        concept=(
            "TEST OF IDENTITY. A space of reflections / parallel "
            "realities / branching screens. Each one shows the apprentice a "
            "possible alternate life (softer, richer, kinder, crueler, "
            "dead). Stepping into the wrong reflection becomes that life "
            "permanently."
        ),
        setup_en=(
            "A black-glass hall opens with a hundred reflections that "
            "do not quite move when the traveler moves. Each mirror "
            "shows him a possible life — softer, richer, dead, kind, "
            "cruel. Picking the wrong mirror means walking into it and "
            "becoming that life."
        ),
        setup_zh=(
            "一座黑曜镜厅敞开，百面镜子映出的影像——并不完全随旅人"
            "起步而动。每一面镜中都是他一种可能的人生：更柔软、更富"
            "足、已死、慈悲、残忍。选错了镜子，便会径直走入其中，从此"
            "成为那一生。"
        ),
        successors=["dragon_mirrored"],
    ),

    # =====================================================================
    # TRIAL 5 — the dragon, four faces (ending route encoded in node)
    # =====================================================================
    "dragon_violent": StoryNode(
        id="dragon_violent",
        trial=5, shape="finale", tag="boss", is_dragon=True,
        concept=(
            "WOUNDED APEX FINALE BOSS. The final adversary in this "
            "world. Half rage, half ancient injury (an old wound from "
            "someone long dead). Does not negotiate. Pure violence. "
            "Maximum stakes."
        ),
        setup_en=(
            "The dragon is half wound, half rage — its left flank scarred "
            "where a forgotten knight cut it a century back and bled out "
            "for the trouble. It does not roar. It opens its mouth and "
            "the cave gets a degree hotter every second it stays open."
        ),
        setup_zh=(
            "那条龙一半是旧伤，一半是怒火——左侧的鳞甲上仍有一道百年"
            "前一位无名骑士留下的剑痕，那骑士也因此流尽了血。它并不"
            "咆哮。它张口时，洞穴每过一息就再热一度。"
        ),
        ending_id="steel_and_ashes",
        successors=[],
    ),
    "dragon_greedy": StoryNode(
        id="dragon_greedy",
        trial=5, shape="finale", tag="boss", is_dragon=True,
        concept=(
            "MERCANTILE FINALE BOSS. The final adversary, who hoards "
            "wealth (literal coins / souls / data / records). Sees the "
            "apprentice not as prey but as an entry in an unbalanced "
            "ledger. Intends to settle the account."
        ),
        setup_en=(
            "The dragon lies on a hill of coins that move when it breathes. "
            "Each scale is a little ledger. It does not see prey when it "
            "looks at the traveler — it sees an entry in a column that has "
            "been short for a long time, and it intends to balance it."
        ),
        setup_zh=(
            "那条龙伏在金币之丘上，每一次呼吸都让金币微微涌动。鳞甲"
            "如一页页账本。它瞧向旅人的眼神里并无猎物，只有一笔久"
            "悬未平的账——它意欲就此结清。"
        ),
        ending_id="silver_tongue",
        successors=[],
    ),
    "dragon_ancient": StoryNode(
        id="dragon_ancient",
        trial=5, shape="finale", tag="boss", is_dragon=True,
        concept=(
            "TIRED ANCIENT FINALE BOSS. The final adversary has been "
            "aware for thousands of years and is exhausted by it. Does "
            "not lunge. Recites the apprentice's lineage from memory and asks "
            "an unanswerable question."
        ),
        setup_en=(
            "The dragon has been awake for three thousand years and is "
            "tired of being awake. It does not lunge. It tells the traveler "
            "the names of his grandparents' grandparents, in order, and "
            "asks if he knows the name of the thing that will end him."
        ),
        setup_zh=(
            "那条龙已醒了三千年，早已倦于醒着。它并不扑来。它将旅人"
            "祖辈以上历代先人的名字一一道出，按辈序而排，再问他可"
            "知，那将终结他的事物，姓甚名谁？"
        ),
        ending_id="hollow_crown",
        successors=[],
    ),
    "dragon_mirrored": StoryNode(
        id="dragon_mirrored",
        trial=5, shape="finale", tag="boss", is_dragon=True,
        concept=(
            "MIRROR-SELF FINALE BOSS. The final adversary wears the "
            "apprentice's own face / voice / movements. Anticipates every "
            "tactic before the apprentice names it. Perfectly symmetrical "
            "match. Whoever wins, both lose something."
        ),
        setup_en=(
            "The dragon wears the traveler's own face. When the traveler "
            "speaks, the dragon's jaw moves in time. When the traveler "
            "thinks of a tactic, the dragon's eyes flick to it before he "
            "has named it. It is going to be a very fair fight."
        ),
        setup_zh=(
            "那条龙长着旅人自己的面孔。旅人开口，龙的颌也随之而动；"
            "旅人心生一计，龙的眼神已先一步望向那处——尚未命名便已"
            "知晓。这将是一场极其公平的对决。"
        ),
        ending_id="the_last_laugh",
        successors=[],
    ),
}


# ---------------------------------------------------------------------------
# Endings — picked by the trial-5 boss the player ended up fighting
# ---------------------------------------------------------------------------

ENDINGS: dict = {
    "steel_and_ashes": Ending(
        id="steel_and_ashes",
        title_en="Steel and Ashes",
        title_zh="钢与灰烬",
        shape=(
            "HEROIC BUT COSTLY VICTORY. The apprentice won by direct "
            "violence. The weapon broke or failed at the last moment. The "
            "home was half-destroyed before he got back. People sing for "
            "him anyway, perhaps too loudly."
        ),
        seed_en=(
            "The apprentice won the way the old songs said it should be won: "
            "with a weapon that finally broke, a wound that did not close, "
            "and a home half-burned by the time he returned.\n\n"
            "WHY THE BOSS FELL: it died fighting because it had only ever "
            "known how to fight. Wounded a hundred times before this last "
            "meeting, it never learned a different posture; in the apprentice "
            "it met something that could not be talked down either, and that "
            "was the symmetry that ended it.\n\n"
            "WHAT THE APPRENTICE CARRIED HOME: a body that no longer moves "
            "without remembering the cost. He knows now that the songs leave "
            "out the parts where the iron tastes like copper and the silence "
            "after is not peaceful. He will not sing those parts back, but he "
            "will hear them every night."
        ),
        seed_zh=(
            "他赢得这一战的方式，与古老歌谣中所唱的一模一样：兵刃终于折"
            "断，伤口始终未合，等他回到家时，半座家园已成灰烬。\n\n"
            "那位最终的对手为何陨落：它战死，是因为它此生只懂得战斗。这"
            "之前已百次受伤，却从未学会另一种姿态；在他这里它遇上了同样"
            "无法被言语劝退的另一个人——正是这种对称，终结了它。\n\n"
            "他带回家的，是一具再不能不带着代价行动的身体。他懂了：歌谣"
            "唱的是凯旋，唱不出铁腥气压在舌底的滋味，唱不出胜利之后那并"
            "不安宁的寂静。这些他不会再唱出来，却会夜夜入耳。"
        ),
    ),
    "silver_tongue": Ending(
        id="silver_tongue",
        title_en="The Silver Tongue",
        title_zh="银舌的胜利",
        shape=(
            "BLOODLESS VICTORY THROUGH WORDS / CUNNING. The apprentice never "
            "fought. He talked the boss out of its anger, its hoard, almost "
            "out of being itself. The village got rich on its spoils — and "
            "never slept easy again."
        ),
        seed_en=(
            "The apprentice never lifted a weapon. He talked the boss out "
            "of its hoard, then out of its anger, then — almost — out of "
            "being itself.\n\n"
            "WHY THE BOSS GAVE UP THE HOARD: every ledger it kept was an "
            "argument it was having with someone long dead. The apprentice "
            "was the first to ask, in good faith, what the original debt was. "
            "The boss could not name it — and once it could not name what it "
            "was protecting, it could not protect it. It walked out into the "
            "open land, no longer a guardian of anything, and that was the "
            "shape its surrender took.\n\n"
            "WHAT THE APPRENTICE CARRIED HOME: the ability to make someone "
            "give up a thing they have been guarding for centuries by simply "
            "asking the right question. The village grew rich on coins still "
            "warm from the boss's belly and slept uneasily forever after — "
            "because every villager could now see the trick had a price, and "
            "the price was that the apprentice could never again be trusted "
            "with a confidence."
        ),
        seed_zh=(
            "他从未挥过一剑。他用一张嘴谈走了那位对手的财宝，又谈走了它"
            "的怒火，最后——几乎——谈走了它身为它自己这件事。\n\n"
            "它为何放下了所守之物：它所记的每一笔账，都是与一位早已亡故"
            "之人的旧争执。他是第一个真诚询问那笔原始债究竟为何之人。它"
            "答不上来——一旦答不上自己在守护什么，也就守不住了。它走入"
            "旷野，不再是任何东西的守护者；这便是它投降的方式。\n\n"
            "他带回家的，是一种本事：仅凭一句问得对的话，就能让一个守了"
            "千年的存在放下所守。家园靠着尚带它腹中余温的财货富了起来，"
            "却夜夜难眠，自此以往——因为每个人都看得见这门本事是有代价"
            "的，而代价是：他从此再不能被人托付任何秘密。"
        ),
    ),
    "hollow_crown": Ending(
        id="hollow_crown",
        title_en="The Hollow Crown",
        title_zh="空心的王冠",
        shape=(
            "PYRRHIC MEMORY-LOSS VICTORY. The apprentice won, but along "
            "the way he traded away the memory of why he came. He stands "
            "in the boss's domain trying to recall the name of his own "
            "home. Walks home; is never the same."
        ),
        seed_en=(
            "The apprentice won, but by trading away the memory of why he "
            "had come.\n\n"
            "WHY THE BOSS WALKED AWAY: it had asked the unanswerable "
            "question — the name of the thing that would end it. The "
            "apprentice's silence as he tried to remember his own home was "
            "the answer. The boss recognized him: not as prey, but as the "
            "next bearer of long memory. It bowed once, the way an exhausted "
            "thing bows when it can finally pass its burden along, and left "
            "the cave open. It had been waiting for someone who could carry "
            "the weight.\n\n"
            "WHAT THE APPRENTICE CARRIED HOME: a thousand years of names — "
            "ancestors, debts, treaties, the genealogies of strangers — "
            "lodged in his head where the simple memory of a village and a "
            "mentor used to be. He sat on the hoard three days trying to "
            "recall his own name. When he finally stood up and walked out, "
            "he understood why bosses are so still: their stillness is the "
            "only posture in which that much remembering does not crush a "
            "body. He is now that still."
        ),
        seed_zh=(
            "他赢了——却以遗忘自己当初为何启程为代价。\n\n"
            "那位对手为何转身离去：它抛出了那个无人能答的问题——那个能"
            "终结它之物，姓甚名谁？他沉默着，试图记起自己家园的名字——这"
            "沉默便是答案。它认出了他：不是猎物，而是漫长记忆的下一个承"
            "载者。它低头一礼，那是一件极度疲惫之物终于得以将重担交付时"
            "才有的姿态。它将洞口留为敞开，转身离去。它等的，本就是一个"
            "能背得起这副担子的人。\n\n"
            "他带回家的，是千年的名字——历代先人、旧债、盟约、陌生人的"
            "家谱——尽数挤进他脑中，把原本属于家园与导师的那份简单记忆"
            "挤了出去。他在那堆金山上枯坐三日，试图记起自己叫什么。当他"
            "终于站起身走出洞口，他明白了：那些古老的对手为何总是一动不"
            "动——那是唯一能扛起如此记忆而身躯不被压垮的姿态。如今他也"
            "学会了这般静止。"
        ),
    ),
    "the_last_laugh": Ending(
        id="the_last_laugh",
        title_en="The Last Laugh",
        title_zh="最后一笑",
        shape=(
            "COMIC STALEMATE / UNEXPECTED FRIENDSHIP. The apprentice and "
            "the boss fought to a perfect draw, looked at each other, "
            "started laughing — at the same thing. Left together, "
            "discussing supplies."
        ),
        seed_en=(
            "The boss and the apprentice fought to a perfect draw, looked at "
            "each other, and started laughing. They were laughing at the same "
            "thing.\n\n"
            "WHY THE BOSS LAUGHED FIRST: it had spent its long existence "
            "training to defeat one person — itself, eventually — and in the "
            "apprentice it finally met a fight where every move was countered "
            "by an equal move. The absurdity of an enemy this perfect, after "
            "all the imperfect ones, finally cracked it. The laugh was relief: "
            "I am not alone in the geometry of my own life, and I am not "
            "going to die today after all.\n\n"
            "WHAT THE APPRENTICE CARRIED HOME: a friend nobody back home would "
            "believe in, an inside joke a thousand years old, and the lifelong "
            "knowledge that a fair fight isn't a fight at all — it's the start "
            "of a conversation. He brings the boss to dinners and weddings "
            "now. People get used to it. Mostly."
        ),
        seed_zh=(
            "那位对手与他战至完全平手，对望一眼，便一起放声大笑。两人笑"
            "的，竟是同一件事。\n\n"
            "对手为何先笑出声：它毕生只为一战而练——最终要击败的，是它"
            "自己。而在他这里，它终于遇上一场每一招都被对等之招化解的对"
            "决。在经历过那么多并不对称的敌人之后，这种荒谬的、过分完美"
            "的对称，终究让它绷不住了。那一笑是松弛：原来我并不孤独于自"
            "己生命的几何之中，原来今日我也不会死。\n\n"
            "他带回家的，是一位家中无人肯信其存在的朋友、一个千年之久的"
            "内部笑话，以及一份伴他一生的领悟——真正公平的对决根本不是"
            "对决，而是一段对话的开端。如今他赴宴或参加婚礼，常将那位对"
            "手一同带去。众人也就慢慢习惯了。大致是这样。"
        ),
    ),
    "false_dawn": Ending(
        id="false_dawn",
        title_en="False Dawn",
        title_zh="伪明",
        shape=(
            "QUIET NON-RESOLUTION. The apprentice did not win. The boss "
            "did not lose. The apprentice turned around at the threshold "
            "and walked home. The story you are reading was found half-"
            "finished in an abandoned hearth. Some endings are like that."
        ),
        seed_en=(
            "The apprentice did not win. The boss did not lose. The story "
            "you are reading was found, half-finished, in the ash of a "
            "hearth that nobody remembers tending.\n\n"
            "WHY THERE WAS NO CONFRONTATION: at the threshold, the "
            "apprentice saw the boss for what it was — old, and tired, and "
            "still doing the work it had been set to do. He had been sent to "
            "end the work. He saw, in that moment, that ending the work "
            "would not change the world that asked for the work in the first "
            "place. The boss looked at him and recognized that recognition. "
            "Neither moved. Both understood. That was enough.\n\n"
            "WHAT THE APPRENTICE CARRIED HOME: nothing he could show the "
            "village, and one thing he could never explain — the knowledge "
            "that some stories are not meant to end, only to be witnessed by "
            "someone else for a moment, then handed back. He went home. He "
            "did not become a different person. The mentor never asked. "
            "Some songs end like that, too."
        ),
        seed_zh=(
            "他没有胜。那位对手也未败。你所读的这一卷故事，是有人在一处"
            "早已无人照看的炉灰里发现的，只写了一半。\n\n"
            "为何没有对决：他在门槛上，看见了那位对手的真实模样——年迈"
            "了，倦了，仍在做着它被安排去做的事。他被遣来终结这桩工作。"
            "他在那一刻明白，终结工作并不能改变那个最初要求工作的世界。"
            "那位对手望着他，也认出了这份认知。双方都未动。双方都明白。"
            "已然足够。\n\n"
            "他带回家的，是没有什么可以拿给众人看的东西，以及一件他永远"
            "无法解释的事——有些故事并非为了被讲完，只为了让另一人短暂"
            "见证一刻，再交还回去。他回了家。他没有变成另一个人。导师也"
            "从未追问。有的歌，结尾本就如此。"
        ),
    ),
}


ROOT_NODE_ID = "hornet_oak"
DEFAULT_ENDING_ID = "false_dawn"


# ---------------------------------------------------------------------------
# Runtime helpers
# ---------------------------------------------------------------------------


def get_node(node_id: str) -> Optional[StoryNode]:
    return STORY_GRAPH.get(node_id)


def get_ending(ending_id: str) -> Ending:
    return ENDINGS.get(ending_id, ENDINGS[DEFAULT_ENDING_ID])


def root_node() -> StoryNode:
    return STORY_GRAPH[ROOT_NODE_ID]


def candidate_nodes(current_node_id: str) -> list:
    """Return the list of StoryNode objects the player can transition to
    after resolving ``current_node_id``. Empty for trial-5 (boss) nodes."""
    node = get_node(current_node_id)
    if node is None:
        return []
    return [STORY_GRAPH[s] for s in node.successors if s in STORY_GRAPH]


def pick_next_node(
    current_node_id: str,
    oracle_history: list,        # list of {"text": str, "trial": int}
    last_narration: str,
    last_tactic: str,
    client,                       # LLMClient
    language: str = "English",
) -> str:
    """Ask the LLM to choose one of the candidate successor nodes given
    the player's narration so far + oracle history + recent tactic.

    Returns the chosen node id. On any failure (mock client, malformed
    LLM output, network), falls back to picking the candidate with the
    closest tag-match to the recent oracle vibe — but never blocks.
    """
    candidates = candidate_nodes(current_node_id)
    if not candidates:
        return ""
    if len(candidates) == 1:
        return candidates[0].id

    # Build the picker prompt — short, JSON-locked, no humor required.
    picker_system = (
        "You are the storyteller for a branching fairy-tale game. The "
        "apprentice has just survived a trial. Pick which of the candidate "
        "next obstacles best fits the tone of the story so far.\n\n"
        "Return ONLY a JSON object of the form:\n"
        "  {\"choice\": \"<one of the candidate IDs>\", \"reason\": \"<one sentence>\"}\n\n"
        f"Write the reason in {language}.\n"
    )
    cand_lines = "\n".join(
        f"  - id: {c.id}\n    tag: {c.tag}\n    setup: {c.setup_en[:240]}"
        for c in candidates
    )
    oracles_lines = "\n".join(
        f"  - trial {o.get('trial', '?')}: {o.get('text', '')[:80]}"
        for o in (oracle_history or [])
    ) or "  (none yet)"
    picker_user = (
        f"ORACLES THE APPRENTICE HAS USED SO FAR:\n{oracles_lines}\n\n"
        f"LAST TRIAL'S NARRATION (excerpt):\n{(last_narration or '')[:600]}\n\n"
        f"LAST TRIAL'S TACTIC ONE-LINER:\n{(last_tactic or '')[:200]}\n\n"
        f"CANDIDATE NEXT OBSTACLES:\n{cand_lines}\n\n"
        "Pick the one whose tag and setup best continues this story. "
        "Return only the JSON object."
    )

    try:
        result = client.complete_json(
            system=picker_system,
            user=picker_user,
            max_tokens=200,
            temperature=0.85,
            model=_picker_model_for_lang(language),
        )
        choice = (result or {}).get("choice", "")
        if any(choice == c.id for c in candidates):
            return choice
    except Exception as _e:
        # Silent on mock client (expected), log when a real LLM was used.
        if not getattr(client, "using_mock", True):
            import sys
            print(f"[story_graph.pick_next_node] LLM picker failed: "
                  f"{type(_e).__name__} {_e}", file=sys.stderr)

    # Deterministic fallback — keyword-match the most recent oracle to a
    # candidate's tag, else just take the first candidate.
    if oracle_history:
        last = (oracle_history[-1].get("text", "") or "").lower()
        for c in candidates:
            for keyword in _TAG_KEYWORDS.get(c.tag, []):
                if keyword in last:
                    return c.id
    return candidates[0].id


def _picker_model_for_lang(language: str) -> str:
    """Same routing rule as resolution._model_for_lang — use the base
    model for zh because the LoRA's English-bias would mangle the JSON
    reason field."""
    if language and ("Chinese" in language or "中文" in language):
        return "llm"
    return ""


# Tiny keyword → tag map used for the deterministic fallback when the
# LLM picker fails. Each tag's keyword list also includes neighbouring
# tags' words so the cascade still differentiates oracle vibes at T2
# (where only combat/wit exist) — e.g. a "deal" (cunning) oracle still
# steers to the wit branch at T2, and on to the cunning child at T3.
_TAG_KEYWORDS = {
    "combat":  ["fight", "sword", "strike", "blood", "rage", "burn",
                "smash", "run", "throw", "jump", "kick", "punch", "shoot",
                "wound", "hit"],
    "wit":     ["riddle", "trick", "puzzle", "joke", "lie", "word", "name",
                "book", "scroll", "memory", "history", "library", "knowledge",
                "coin", "deal", "trade", "smile", "wink", "barter", "steal",
                "ghost", "spirit", "fog", "dream", "shadow", "ancient", "rune",
                "think", "clever", "talk", "speak", "story"],
    "action":  ["run", "throw", "jump", "kick", "punch", "shoot",
                "fight", "strike", "rush", "chase"],
    "mystic":  ["ghost", "spirit", "fog", "dream", "shadow", "ancient",
                "rune", "magic", "spell", "wraith", "haunt", "echo"],
    "cunning": ["coin", "deal", "trade", "smile", "wink", "barter", "steal",
                "lie", "trick", "smuggle", "bribe", "swap"],
    "lore":    ["book", "scroll", "memory", "name", "history", "library",
                "knowledge", "word", "rune", "secret", "ancient", "tome"],
}


def total_node_count() -> int:
    return len(STORY_GRAPH)


def total_ending_count() -> int:
    return len(ENDINGS)


# ---------------------------------------------------------------------------
# Pre-walk-at-send-off — picks branches up front using the inscribed
# oracles as context. Keeps the existing precompute / resolution pipeline
# intact (we still produce a flat list of 5 obstacles by the time trials
# begin) and lets every oracle drive both a trial AND a branch decision.
# ---------------------------------------------------------------------------


def walk_story_tree(
    oracles_text: list,           # list of 5 oracle text strings (in order)
    client,                        # LLMClient (may be mock)
    language: str = "English",
) -> list:
    """Walk the tree from root to a leaf, picking each successor via an
    LLM call seeded by one inscribed oracle.

    Returns a list of 5 StoryNode objects [trial-1, ..., trial-5]. Trial 5
    is always a boss node so its ``ending_id`` is non-empty.

    When ``client.using_mock`` is True the LLM picker is skipped and we
    fall back to the deterministic keyword-match (or "first candidate")
    rule inside ``pick_next_node`` — playing through still works offline,
    just with less reactive branching.
    """
    path: list = []
    node = root_node()
    path.append(node)
    # Pretend oracle 1 was "used to clear" trial 1 → drives the T2 fork,
    # oracle 2 drives T3, oracle 3 drives T4, oracle 4 drives T5 (the boss).
    # Oracle 5 is reserved for the trial-5 RESOLUTION, not branch-picking.
    for i in range(4):     # 4 picks → trials 2..5
        if not node.successors:
            break
        oracle_text = oracles_text[i] if i < len(oracles_text) else ""
        chosen = _pick_next_with_oracle(
            node, oracle_text, client, language,
        )
        node = get_node(chosen) or candidate_nodes(node.id)[0]
        path.append(node)
    # Defensive pad if the tree is malformed (e.g. a leaf at trial 3)
    while len(path) < 5:
        path.append(path[-1])
    return path[:5]


def _pick_next_with_oracle(
    current: StoryNode,
    oracle_text: str,
    client,
    language: str,
) -> str:
    """Single-fork picker. Mirrors pick_next_node() but uses oracle text
    as the context signal (since narrations don't exist yet at send-off).
    """
    cands = candidate_nodes(current.id)
    if not cands:
        return ""
    if len(cands) == 1:
        return cands[0].id

    if getattr(client, "using_mock", True):
        # Mock client — skip the LLM call and use the deterministic fallback
        return _fallback_pick(cands, oracle_text)

    picker_system = (
        "You are the storyteller for a branching fairy-tale game. Given "
        "the player's chosen oracle for the upcoming trial, pick which "
        "candidate next obstacle best fits the tone.\n\n"
        "Return ONLY a JSON object of the form:\n"
        "  {\"choice\": \"<one of the candidate IDs>\", \"reason\": \"<one sentence>\"}\n\n"
        f"Write the reason in {language}."
    )
    cand_lines = "\n".join(
        f"  - id: {c.id}\n    tag: {c.tag}\n    setup: {c.setup_en[:240]}"
        for c in cands
    )
    picker_user = (
        f"PREVIOUS OBSTACLE (just resolved):\n  id: {current.id}\n"
        f"  setup: {current.setup_en[:240]}\n\n"
        f"THE PLAYER'S ORACLE FOR THE UPCOMING TRIAL:\n  {oracle_text[:160]}\n\n"
        f"CANDIDATE NEXT OBSTACLES:\n{cand_lines}\n\n"
        "Pick the candidate whose tag/setup best continues the story given "
        "what the player's oracle suggests they will improvise with. "
        "Return only the JSON object."
    )
    try:
        result = client.complete_json(
            system=picker_system,
            user=picker_user,
            max_tokens=200,
            temperature=0.85,
            model=_picker_model_for_lang(language),
        )
        choice = (result or {}).get("choice", "")
        if any(choice == c.id for c in cands):
            return choice
    except Exception:
        pass
    return _fallback_pick(cands, oracle_text)


def _fallback_pick(cands: list, oracle_text: str) -> str:
    """Keyword-match the oracle text against each candidate's tag-keyword
    list. Compound tags like ``"action+cunning"`` get their keyword sets
    merged. Returns the first candidate whose merged keyword set matches
    a token in ``oracle_text``; on no match (or empty oracle) returns the
    first candidate."""
    text = (oracle_text or "").lower()
    if not text:
        return cands[0].id
    best = None
    best_score = 0
    for c in cands:
        # Compound tags ("action+cunning") merge both sub-lists.
        keywords: list = []
        for sub_tag in (c.tag or "").split("+"):
            keywords.extend(_TAG_KEYWORDS.get(sub_tag.strip(), []))
        score = sum(1 for k in keywords if k in text)
        if score > best_score:
            best_score = score
            best = c
    if best is not None:
        return best.id
    return cands[0].id


# ---------------------------------------------------------------------------
# Theme expansion — render each visited node's setup in the target theme
# ---------------------------------------------------------------------------


def render_themed_setups(
    path: list,                  # list of StoryNode (the player's walked path)
    theme,                        # Theme dataclass (from oracles.themes)
    client,                       # LLMClient
    language: str = "English",
    hero_name: str = "the apprentice",
    village_name: str = "his village",
    max_workers: int = 5,
) -> dict:
    """For each node in ``path`` return a 2-3 sentence obstacle setup
    rendered in the active theme + language.

    Fantasy theme keeps each node's hand-authored setup_en/zh. Every
    other theme fires one LLM call per node that expands ``node.concept``
    into themed prose. Calls run in parallel.

    Returns a dict ``{node.id: setup_str}``. On per-node LLM failures
    falls back to the canonical setup_en/zh so the trial still has text.
    """
    import concurrent.futures as _f

    is_fantasy = (getattr(theme, "key", "") == "fantasy")
    lang_code = "zh" if (language and ("Chinese" in language or "中文" in language)) else "en"

    out: dict = {}

    if is_fantasy or client is None or getattr(client, "using_mock", True):
        for node in path:
            out[node.id] = node.setup(lang_code)
        return out

    def _one(node) -> tuple:
        try:
            txt = _llm_render_node(
                node, theme, client,
                language=language,
                hero_name=hero_name,
                village_name=village_name,
            )
            if txt and len(txt.strip()) > 30:
                return (node.id, txt.strip())
        except Exception:
            pass
        return (node.id, node.setup(lang_code))

    with _f.ThreadPoolExecutor(max_workers=max_workers) as ex:
        for node_id, setup in ex.map(_one, path):
            out[node_id] = setup
    return out


def _llm_render_node(
    node: StoryNode,
    theme,
    client,
    language: str = "English",
    hero_name: str = "the apprentice",
    village_name: str = "his village",
) -> str:
    """Single LLM call that expands ``node.concept`` into a vivid 2-3
    sentence obstacle setup IN the target theme + language. The output
    is what becomes ``Obstacle.setup`` for that trial.

    The prompt deliberately keeps the LLM tightly constrained to the
    concept's role (no extra trials, no resolution, no oracle-use) — it
    just writes the obstacle, not the story around it.
    """
    th_name = getattr(theme, "display_name", "the world")
    th_blurb = getattr(theme, "blurb", "")
    th_finale = getattr(theme, "finale_descriptor", "the final adversary")
    th_style = getattr(theme, "style_cues", "")

    system = (
        f"You are a setup writer for a branching fairy-tale game set in "
        f"the world of {th_name}. Brief: {th_blurb}\n"
        f"Style cues: {th_style}\n\n"
        f"You will receive an abstract OBSTACLE CONCEPT. Your job is to "
        f"render it as a vivid 2-3 sentence obstacle SETUP in this "
        f"world, in {language}. Do NOT write a resolution. Do NOT "
        f"narrate the apprentice's actions. Do NOT use the oracle. Just "
        f"describe the obstacle as the apprentice meets it, in present tense.\n\n"
        f"Apprentice name: {hero_name}. Village/home: {village_name}. "
        f"The finale of this run is {th_finale}. This is trial "
        f"{node.trial} of 5.\n\n"
        f"Output ONLY the obstacle setup — no preamble, no quotes, no "
        f"labels."
    )
    user = (
        f"OBSTACLE CONCEPT (trial {node.trial}, tag={node.tag}):\n"
        f"{node.concept}\n\n"
        f"Write the obstacle setup now, in {language}."
    )
    try:
        from oracles.resolution import _wrap_with_language_force
        system = _wrap_with_language_force(system, language)
    except Exception:
        pass
    text = client.complete_text(
        system=system, user=user,
        max_tokens=300, temperature=0.95,
        model=_picker_model_for_lang(language),
    )
    return (text or "").strip()


def render_themed_ending_seed(
    ending: Ending,
    theme,
    client,
    language: str = "English",
    hero_name: str = "the apprentice",
    village_name: str = "his village",
) -> str:
    """Single LLM call that expands ``ending.shape`` into a vivid 2-3
    sentence ending seed in the active theme + language. Falls back to
    the hand-authored seed_en/zh on any error.

    Used by ``generate_epilogue`` when theme != fantasy.
    """
    lang_code = "zh" if (language and ("Chinese" in language or "中文" in language)) else "en"
    if client is None or getattr(client, "using_mock", True):
        return ending.seed(lang_code)

    th_name = getattr(theme, "display_name", "the world")
    th_blurb = getattr(theme, "blurb", "")
    th_finale = getattr(theme, "finale_descriptor", "the final adversary")
    th_style = getattr(theme, "style_cues", "")

    system = (
        f"You are an ending seed writer for a branching fairy-tale game "
        f"set in the world of {th_name}. Brief: {th_blurb}\n"
        f"Style cues: {th_style}\n\n"
        f"You receive an abstract ENDING SHAPE. Render it as a vivid 3-4 "
        f"sentence ending seed in this world, in {language}. Stay TRUE "
        f"to the shape's outcome (heroic / cunning / pyrrhic / comic / "
        f"non-resolution). Do NOT use the word 'dragon' unless this "
        f"world has dragons. The boss in this world is {th_finale}.\n\n"
        f"Apprentice: {hero_name}. Home: {village_name}.\n\n"
        f"Output ONLY the ending seed — no preamble, no quotes."
    )
    user = (
        f"ENDING SHAPE (id={ending.id}):\n{ending.shape}\n\n"
        f"Write the ending seed now, in {language}."
    )
    try:
        from oracles.resolution import _wrap_with_language_force
        system = _wrap_with_language_force(system, language)
    except Exception:
        pass
    try:
        text = client.complete_text(
            system=system, user=user,
            max_tokens=400, temperature=0.9,
            model=_picker_model_for_lang(language),
        )
        text = (text or "").strip()
        if len(text) > 40:
            return text
    except Exception:
        pass
    return ending.seed(lang_code)