dndkit 0.4.0__py3-none-any.whl

dndkit/tools/campaign.py

@@ -0,0 +1,208 @@
+"""Campaign tools: create, open, list, describe, edit and delete campaigns."""
+
+from collections.abc import Callable
+from typing import Annotated
+
+from fastmcp.dependencies import Depends
+from fastmcp.tools import tool
+from pydantic import Field
+
+from dndkit.errors import InvalidChangeError
+from dndkit.game import readiness, world
+from dndkit.game.world import EntityKind
+from dndkit.storage import CampaignStore
+from dndkit.tools import render
+from dndkit.tools.deps import (
+    DESTRUCTIVE,
+    READ_ONLY,
+    ConfirmationCode,
+    NameOrId,
+    get_store,
+    provided,
+)
+
+SETTING_PREVIEW = 1500  # a voice model reads the rest when it needs it
+Setting = Annotated[str | None, Field(description="World and tone, in prose or markdown")]
+SettingFile = Annotated[
+    str | None,
+    Field(description="Name of a .md or .txt file in the server's settings folder"),
+]
+
+
+def _setting_text(
+    store: CampaignStore, setting: str | None, setting_file: str | None
+) -> str | None:
+    if setting and setting_file:
+        raise InvalidChangeError("Give either setting or setting_file, not both.")
+    return store.read_setting_file(setting_file) if setting_file else setting
+
+
+@tool
+def create_campaign(
+    name: Annotated[str, Field(min_length=1, max_length=100, description="Campaign name")],
+    description: Annotated[str, Field(description="Pitch shown to the players, no spoilers")],
+    dm_name: Annotated[str | None, Field(description="Game master's name")] = None,
+    setting: Setting = None,
+    setting_file: SettingFile = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Create a campaign and make it active. An existing campaign is never replaced."""
+    text = _setting_text(store, setting, setting_file)
+    campaign = store.create(name, description, dm_name=dm_name, setting=text)
+    return f"Campaign '{campaign.name}' created and active."
+
+
+@tool(annotations=READ_ONLY)
+def get_campaign_info(
+    full: Annotated[bool, Field(description="The whole setting, not its start")] = False,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Describe the active campaign: pitch, setting, sizes and world notes."""
+    with store.reading() as c:
+        setting = c.setting or "not described yet"
+        if not full and len(setting) > SETTING_PREVIEW:
+            rest = len(setting) - SETTING_PREVIEW
+            setting = f"{setting[:SETTING_PREVIEW]}… ({rest} more characters: full=true)"
+        lines = [
+            f"{c.name} (id {c.id}): {c.description}",
+            f"Game master: {c.dm_name or 'unknown'}.",
+            f"{len(c.characters)} characters, {len(c.npcs)} NPCs, {len(c.locations)} locations, "
+            f"{len(c.quests)} quests, {len(c.sessions)} session notes, "
+            f"{len(c.events)} log events.",
+            f"Setting: {setting}",
+        ]
+        if c.world_notes:
+            lines.append(f"World notes: {c.world_notes}")
+    return "\n".join(lines)
+
+
+@tool(annotations=READ_ONLY)
+def check_campaign(store: CampaignStore = Depends(get_store)) -> str:
+    """Before play: what breaks the 5e rules or is missing (sheets, quest, places, fights)."""
+    with store.reading() as campaign:
+        found = readiness.check(campaign)
+        name, players = campaign.name, len(campaign.characters)
+    if not found:
+        return (
+            f"{name} is ready to play, {players} characters. At the session's start, "
+            "ask who is at the table (seat_players)."
+        )
+    lines = [f"Before playing {name}:"]
+    for certain, title in ((True, "Against the rules:"), (False, "Probably forgotten:")):
+        group = [f for f in found if f.certain is certain]
+        if group:
+            lines += [title, *(f"- {f.subject}: {f.problem}. Fix: {f.fix}." for f in group)]
+    lines.append(
+        "Fix them with those tools, asking the player what is theirs to choose "
+        "(scores, gear, spells), then call check_campaign again."
+    )
+    return "\n".join(lines)
+
+
+@tool(annotations=READ_ONLY)
+def list_campaigns(store: CampaignStore = Depends(get_store)) -> str:
+    """List saved campaigns, most recently used first, with their size and session."""
+    entries = store.list_campaigns()
+    if not entries:
+        return f"No campaign saved yet in {store.campaigns_dir}."
+    active = store.current.name if store.current else None
+    return "Campaigns:\n" + "\n".join(
+        f"- {render.campaign_entry(e, e.name == active)}" for e in entries
+    )
+
+
+@tool
+def load_campaign(
+    name: Annotated[str, Field(min_length=1, description="Campaign name")],
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Open a saved campaign and make it active."""
+    campaign = store.load(name)
+    return f"Campaign '{campaign.name}' is active."
+
+
+@tool
+def update_campaign(
+    description: Annotated[str | None, Field(description="New pitch, shown to players")] = None,
+    dm_name: Annotated[str | None, Field(description="Game master's name")] = None,
+    setting: Setting = None,
+    setting_file: SettingFile = None,
+    world_notes: Annotated[str | None, Field(description="Replaces the world notes")] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Edit the active campaign's pitch, game master, setting or world notes."""
+    changes = provided(
+        description=description,
+        dm_name=dm_name,
+        setting=_setting_text(store, setting, setting_file),
+        world_notes=world_notes,
+    )
+    if not changes:
+        raise InvalidChangeError("Nothing to change: give at least one field.")
+    with store.transaction() as campaign:
+        for field, value in changes.items():
+            setattr(campaign, field, value)
+    return f"Campaign '{campaign.name}' updated: {', '.join(changes)}."
+
+
+@tool(annotations=DESTRUCTIVE)
+def remove_from_campaign(
+    kind: Annotated[EntityKind, Field(description="What to remove")],
+    name_or_id: NameOrId,
+    confirmation_code: ConfirmationCode = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Permanently remove a character, NPC, location or quest in two calls. The first only
+    returns a code: ask the user, and call again with it only after a clear yes."""
+    with store.reading() as campaign:
+        entity = world.find_entity(campaign, kind, name_or_id)
+        target = f"{campaign.id}/{kind}/{entity.id}"
+    if confirmation_code is None:
+        code = store.confirmations.issue(target)
+        return (
+            f"Nothing removed yet. Ask the user to confirm removing the {kind} "
+            f"'{entity.name}'. Only if they clearly say yes, call remove_from_campaign again "
+            f"with confirmation_code '{code}' (valid {store.confirmations.ttl_minutes} minutes)."
+        )
+    if not store.confirmations.consume(target, confirmation_code):
+        raise InvalidChangeError(
+            "That confirmation code is wrong or expired, so nothing was removed. "
+            "Call remove_from_campaign without a code to get a new one."
+        )
+    with store.transaction() as campaign:
+        name = world.remove_entity(campaign, kind, entity.id)
+    return f"Removed {kind} '{name}'."
+
+
+@tool(annotations=DESTRUCTIVE)
+def delete_campaign(
+    name: Annotated[str, Field(min_length=1, description="Campaign name")],
+    confirmation_code: ConfirmationCode = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Delete a campaign in two calls. The first only returns a code and what would be lost:
+    ask the user out loud, and call again with the code only after a clear yes."""
+    if confirmation_code is None:
+        entry, code = store.request_deletion(name)
+        return (
+            f"Nothing deleted yet. Campaign '{entry.name}' holds "
+            f"{render.campaign_contents(entry)}. Ask the user to confirm the deletion. "
+            f"Only if they clearly say yes, call delete_campaign again with "
+            f"confirmation_code '{code}' (valid {store.confirmations.ttl_minutes} minutes)."
+        )
+    entry, moved_to = store.delete(name, confirmation_code)
+    active = store.current.name if store.current else None
+    after = f" '{active}' is still active." if active else " No campaign is active now."
+    return f"Campaign '{entry.name}' deleted (file moved to {moved_to}).{after}"
+
+
+TOOLS: list[Callable[..., str]] = [
+    create_campaign,
+    get_campaign_info,
+    check_campaign,
+    list_campaigns,
+    load_campaign,
+    update_campaign,
+    delete_campaign,
+    remove_from_campaign,
+]

dndkit/tools/characters.py

@@ -0,0 +1,189 @@
+"""Character tools: create, read and change player characters."""
+
+from collections.abc import Callable
+from typing import Annotated
+
+from fastmcp.dependencies import Depends
+from fastmcp.tools import tool
+from pydantic import Field
+
+from dndkit.errors import InvalidChangeError
+from dndkit.game import characters, combatants, rules
+from dndkit.models import AbilityScore, Character, CharacterClass, Race
+from dndkit.storage import CampaignStore
+from dndkit.tools import render
+from dndkit.tools.apps import CHARACTER_APP, app_meta
+from dndkit.tools.deps import READ_ONLY, NameOrId, get_store, provided
+
+Score = Annotated[int, Field(ge=1, le=30, description="Ability score (1-30)")]
+NewScore = Annotated[int | None, Field(ge=1, le=30, description="New score (1-30)")]
+Text = Annotated[str | None, Field(description="New value")]
+
+
+@tool
+def create_character(
+    name: Annotated[str, Field(min_length=1, description="Character name")],
+    character_class: Annotated[str, Field(min_length=1, description="Class, e.g. Wizard")],
+    race: Annotated[str, Field(min_length=1, description="Race or species, e.g. Elf")],
+    class_level: Annotated[int, Field(ge=1, le=20, description="Class level")] = 1,
+    hit_points_max: Annotated[
+        int | None, Field(ge=1, description="Max HP; from class and CON if omitted")
+    ] = None,
+    armor_class: Annotated[
+        int | None, Field(ge=0, description="AC; 10 + DEX (no armor) if omitted")
+    ] = None,
+    speed: Annotated[int | None, Field(ge=0, description="Feet; from race if omitted")] = None,
+    player_name: Annotated[str | None, Field(description="Player controlling it")] = None,
+    description: Annotated[str | None, Field(description="Appearance and demeanor")] = None,
+    bio: Annotated[str | None, Field(description="Backstory and motivations")] = None,
+    background: Annotated[str | None, Field(description="Background, e.g. Sage")] = None,
+    alignment: Annotated[str | None, Field(description="Alignment")] = None,
+    strength: Score = 10,
+    dexterity: Score = 10,
+    constitution: Score = 10,
+    intelligence: Score = 10,
+    wisdom: Score = 10,
+    charisma: Score = 10,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Create a player character at full hit points. The name must be new."""
+    scores = dict(
+        strength=strength,
+        dexterity=dexterity,
+        constitution=constitution,
+        intelligence=intelligence,
+        wisdom=wisdom,
+        charisma=charisma,
+    )
+    mods = {key: (value - 10) // 2 for key, value in scores.items()}
+    if hit_points_max is None:
+        hit_points_max = rules.starting_hit_points(
+            character_class, class_level, mods["constitution"]
+        )
+    if armor_class is None:
+        armor_class = 10 + mods["dexterity"]
+    character = Character(
+        name=name.strip(),
+        player_name=player_name,
+        character_class=CharacterClass(name=character_class, level=class_level),
+        race=Race(name=race),
+        background=background,
+        alignment=alignment,
+        description=description,
+        bio=bio,
+        armor_class=armor_class,
+        speed=speed if speed is not None else rules.base_speed(race),
+        hit_points_max=hit_points_max,
+        hit_points_current=hit_points_max,
+        abilities={k: AbilityScore(score=v) for k, v in scores.items()},
+    )
+    with store.transaction() as campaign:
+        characters.create(campaign, character)
+        caught_up = combatants.refresh(campaign)  # a fighter of that name joins its sheet
+    casting = render.spellcasting_line(character)
+    return " ".join([f"Created {render.character_line(character)}.", casting, *caught_up]).strip()
+
+
+@tool(annotations=READ_ONLY, meta=app_meta(CHARACTER_APP))
+def get_character(
+    name_or_id: Annotated[
+        str | None, Field(description="Name or ID; omit for whose turn it is")
+    ] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Full character sheet: abilities, hit points, spell attack and DC, spells, inventory."""
+    with store.reading() as campaign:
+        return render.character_sheet(characters.pick(campaign, name_or_id))
+
+
+@tool(annotations=READ_ONLY)
+def list_characters(store: CampaignStore = Depends(get_store)) -> str:
+    """List the party's characters with level, class and hit points."""
+    with store.reading() as campaign:
+        party = sorted(campaign.characters.values(), key=lambda c: c.name)
+        if not party:
+            return "No characters yet."
+        lines = [f"- {render.character_line(c)}" for c in party]
+        return "\n".join(["Characters:", *lines, render.table(campaign, store.opened_at)])
+
+
+@tool
+def update_character(
+    name_or_id: NameOrId,
+    name: Annotated[str | None, Field(description="New name")] = None,
+    player_name: Text = None,
+    description: Text = None,
+    bio: Text = None,
+    background: Text = None,
+    alignment: Text = None,
+    class_level: Annotated[
+        int | None, Field(ge=1, le=20, description="Corrected level; level_up gains one")
+    ] = None,
+    hit_points_current: Annotated[int | None, Field(ge=0, description="Current HP")] = None,
+    hit_points_max: Annotated[int | None, Field(ge=1, description="Maximum HP")] = None,
+    temporary_hit_points: Annotated[int | None, Field(ge=0, description="Temporary HP")] = None,
+    armor_class: Annotated[int | None, Field(ge=0, description="Armor class")] = None,
+    speed: Annotated[int | None, Field(ge=0, description="Walking speed, feet")] = None,
+    inspiration: Annotated[bool | None, Field(description="Has inspiration")] = None,
+    exhaustion: Annotated[int | None, Field(ge=0, le=6, description="Exhaustion level")] = None,
+    notes: Text = None,
+    skills: Annotated[list[str] | None, Field(description="Proficient skills")] = None,
+    expertise: Annotated[
+        list[str] | None, Field(description="Skills with double proficiency")
+    ] = None,
+    saving_throws: Annotated[list[str] | None, Field(description="Proficient saves: DEX")] = None,
+    languages: Annotated[list[str] | None, Field(description="Languages spoken")] = None,
+    features: Annotated[list[str] | None, Field(description="Features, traits, feats")] = None,
+    strength: NewScore = None,
+    dexterity: NewScore = None,
+    constitution: NewScore = None,
+    intelligence: NewScore = None,
+    wisdom: NewScore = None,
+    charisma: NewScore = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Set character sheet values (absolute; a list replaces the old one). For damage or
+    healing use change_hit_points. Skills and saves take English or French names."""
+    changes = provided(
+        name=name,
+        player_name=player_name,
+        description=description,
+        bio=bio,
+        background=background,
+        alignment=alignment,
+        class_level=class_level,
+        hit_points_current=hit_points_current,
+        hit_points_max=hit_points_max,
+        temporary_hit_points=temporary_hit_points,
+        armor_class=armor_class,
+        speed=speed,
+        inspiration=inspiration,
+        exhaustion=exhaustion,
+        notes=notes,
+        skill_proficiencies=skills,
+        skill_expertise=expertise,
+        saving_throw_proficiencies=saving_throws,
+        languages=languages,
+        features_and_traits=features,
+    )
+    abilities = provided(
+        strength=strength,
+        dexterity=dexterity,
+        constitution=constitution,
+        intelligence=intelligence,
+        wisdom=wisdom,
+        charisma=charisma,
+    )
+    if not changes and not abilities:
+        raise InvalidChangeError("Nothing to change: give at least one field.")
+    with store.transaction() as campaign:
+        character = characters.update(campaign, name_or_id, changes, abilities)
+    return f"Updated {', '.join([*changes, *abilities])}. Now: {render.character_line(character)}."
+
+
+TOOLS: list[Callable[..., str]] = [
+    create_character,
+    get_character,
+    list_characters,
+    update_character,
+]

dndkit/tools/combat.py

@@ -0,0 +1,169 @@
+"""Combat tools: the initiative order, turns, newcomers and the end of the fight."""
+
+from collections.abc import Callable
+from typing import Annotated, Literal
+
+from fastmcp.dependencies import Depends
+from fastmcp.tools import tool
+from pydantic import Field
+
+from dndkit.errors import InvalidChangeError
+from dndkit.game import battlefield, bestiary, combat, combatants, effects, pathing
+from dndkit.game.dice import DiceLog
+from dndkit.models import Participant
+from dndkit.storage import CampaignStore
+from dndkit.tools import render_combat
+from dndkit.tools.apps import COMBAT_APP, app_meta
+from dndkit.tools.deps import get_dice_log, get_store
+
+
+@tool(meta=app_meta(COMBAT_APP))
+def start_combat(
+    participants: Annotated[
+        list[Participant] | None,
+        Field(description="Who fights, with initiative; the party rolls if left out"),
+    ] = None,
+    encounter: Annotated[
+        str | None, Field(description="Planned encounter: its monsters join, initiative rolled")
+    ] = None,
+    store: CampaignStore = Depends(get_store),
+    log: DiceLog = Depends(get_dice_log),
+) -> str:
+    """Start a combat. Party characters use their sheet; bestiary monsters get their stats;
+    same-named foes become 'Goblin 1', 'Goblin 2'."""
+    with store.transaction() as campaign:
+        fighters = [combatants.build(campaign, p) for p in participants or []]
+        planned = bestiary.find_encounter(campaign, encounter) if encounter else None
+        state = campaign.game_state
+        if planned is not None:
+            fighters += combatants.from_encounter(campaign, planned)
+            planned.status = "running"
+            if planned.battlefield is not None:
+                state.battlefield = planned.battlefield.model_copy(deep=True)
+        if not fighters:
+            raise InvalidChangeError("Give participants, an encounter, or both.")
+        party = any(f.character_id for f in fighters)
+        rolled = [] if party else combatants.party_at_the_table(campaign)
+        fighters += [fighter for fighter, _ in rolled]
+        first = combat.start(state, fighters, planned.id if planned else None)
+        if state.battlefield is not None:
+            battlefield.settle(state)
+            battlefield.place_the_rest(state)
+        order = render_combat.initiative(campaign)
+    for _, result in rolled:
+        log.record(result)
+    rolls = ", ".join(f"{c.name} {r.total}" for c, r in rolled)
+    note = f"Initiative rolled for the party: {rolls}.\n" if rolls else ""
+    return f"Combat started. {first.name} acts first.\n{note}{order}"
+
+
+@tool
+def add_combatant(
+    participant: Annotated[Participant, Field(description="The newcomer and its initiative")],
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Bring someone into the running fight (reinforcements, a late arrival)."""
+    with store.transaction() as campaign:
+        added = combat.add(campaign.game_state, combatants.build(campaign, participant))
+        battlefield.place_the_rest(campaign.game_state)
+        order = render_combat.initiative(campaign)
+    return f"{added.name} joins the fight.\n{order}"
+
+
+@tool
+def next_turn(store: CampaignStore = Depends(get_store)) -> str:
+    """End the current turn and give the next combatant theirs."""
+    with store.transaction() as campaign:
+        state = campaign.game_state
+        caught_up = combatants.refresh(campaign)
+        ending = state.current_combatant
+        caught_up += effects.end_of_turn(campaign, ending) if ending else []
+        current = combat.next_turn(state)
+        prefix = f"Round {state.combat_round} begins. " if state.turn_index == 0 else ""
+        line = render_combat.combatant_line(campaign, current)
+        hint = render_combat.turn_hint(campaign, current)
+    return "\n".join([*caught_up, f"{prefix}{current.name}'s turn: {line}", *filter(None, [hint])])
+
+
+@tool
+def remove_combatant(
+    name: Annotated[str, Field(min_length=1, description="Combatant name, e.g. 'Goblin 2'")],
+    reason: Annotated[
+        Literal["defeated", "fled", "withdrawn"],
+        Field(description="withdrawn: a mistake or change of plan, no XP"),
+    ] = "defeated",
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Take a combatant out of the fight and off the battle map. Defeated or fled foes
+    count for XP; a withdrawn one is as if it never joined."""
+    with store.transaction() as campaign:
+        removed, acting = combat.remove(campaign.game_state, name, overcome=reason != "withdrawn")
+    gone = (
+        f"{removed.name} withdrawn: as if it never joined, no XP."
+        if reason == "withdrawn"
+        else f"{removed.name} removed ({reason})."
+    )
+    if acting is None:
+        return f"{gone} No one is left: call end_combat."
+    return f"{gone} Current turn: {acting.name}."
+
+
+@tool
+def use_legendary(
+    name: Annotated[str, Field(min_length=1, description="The legendary creature")],
+    resistance: Annotated[bool, Field(description="Turn a failed save into a success")] = False,
+    cost: Annotated[int, Field(ge=1, le=3, description="Actions the option costs")] = 1,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Spend a legendary action (at the end of another creature's turn) or resistance."""
+    with store.transaction() as campaign:
+        creature = combat.use_legendary(campaign.game_state, name, resistance, cost)
+    if resistance:
+        return (
+            f"{creature.name} succeeds instead; "
+            f"{creature.legendary_resistances_left} legendary resistance(s) left."
+        )
+    return (
+        f"{creature.name} takes a legendary action; "
+        f"{creature.legendary_actions_left} left until its turn."
+    )
+
+
+@tool
+def take_reaction(
+    name: Annotated[str, Field(min_length=1, description="Who reacts")],
+    reaction: Annotated[str, Field(description="e.g. opportunity attack, Shield")] = "",
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Spend a creature's reaction: one a round, back at the start of its turn. One that
+    has reacted provokes no more opportunity attacks this round."""
+    with store.transaction() as campaign:
+        state = campaign.game_state
+        able = pathing.can_react(campaign, combat.find(state, name))
+        creature = combat.use_reaction(state, name, able)
+    what = f" ({reaction})" if reaction else ""
+    return f"{creature.name} uses its reaction{what}; it comes back at the start of its turn."
+
+
+@tool
+def end_combat(store: CampaignStore = Depends(get_store)) -> str:
+    """End the combat: says who was overcome and the XP they are worth."""
+    with store.transaction() as campaign:
+        encounter_id = campaign.game_state.encounter_id
+        summary = combat.end(campaign.game_state)
+        if encounter_id and encounter_id in campaign.encounters:
+            campaign.encounters[encounter_id].status = "done"
+    defeated = ", ".join(c.name for c in summary.defeated) or "no one"
+    award = f" Award it with award_experience ({summary.xp} XP)." if summary.xp else ""
+    return f"Combat over after {summary.rounds} round(s). Overcome: {defeated}.{award}"
+
+
+TOOLS: list[Callable[..., str]] = [
+    start_combat,
+    add_combatant,
+    next_turn,
+    remove_combatant,
+    use_legendary,
+    take_reaction,
+    end_combat,
+]

dndkit/tools/deps.py

@@ -0,0 +1,42 @@
+"""What tools share: the campaign store dependency and common parameter types."""
+
+from typing import Annotated, Any
+
+from fastmcp import Context
+from fastmcp.dependencies import CurrentContext
+from pydantic import Field
+
+from dndkit.game.dice import DiceLog
+from dndkit.storage import CampaignStore
+
+STORE_KEY = "store"
+DICE_LOG_KEY = "dice_log"
+
+READ_ONLY: dict[str, Any] = {"readOnlyHint": True}
+DESTRUCTIVE: dict[str, Any] = {"destructiveHint": True}
+
+NameOrId = Annotated[str, Field(min_length=1, description="Name or ID")]
+ConfirmationCode = Annotated[
+    str | None, Field(description="Code from the first call, once the user has said yes")
+]
+
+
+def get_store(ctx: Context = CurrentContext()) -> CampaignStore:
+    """The store opened by the server's lifespan (see ``app.build_server``)."""
+    store = ctx.lifespan_context.get(STORE_KEY)
+    if not isinstance(store, CampaignStore):
+        raise RuntimeError("The campaign store is not open: the server lifespan did not run.")
+    return store
+
+
+def get_dice_log(ctx: Context = CurrentContext()) -> DiceLog:
+    """The session's dice log, opened by the server's lifespan."""
+    log = ctx.lifespan_context.get(DICE_LOG_KEY)
+    if not isinstance(log, DiceLog):
+        raise RuntimeError("The dice log is not open: the server lifespan did not run.")
+    return log
+
+
+def provided(**fields: Any) -> dict[str, Any]:
+    """The fields the model actually sent: None means "leave unchanged"."""
+    return {name: value for name, value in fields.items() if value is not None}