dndkit 0.4.0__py3-none-any.whl

dndkit/tools/schema.py

@@ -0,0 +1,47 @@
+"""Compact the JSON schemas advertised to clients.
+
+An optional parameter (``int | None = None``) is advertised by Pydantic as
+``{"anyOf": [{"type": "integer"}, {"type": "null"}], "default": null}``. A
+model leaves an optional parameter out rather than sending null, so the
+advertised form keeps only the real type: about a third fewer schema tokens,
+which keeps the catalogue under roomkit's Tool Search threshold, and no
+``anyOf`` for Gemini to stumble on. A model parameter (``Participant``) also
+loses its docstring, which repeats the parameter's own description.
+Validation is untouched: FastMCP checks calls against the Python signature,
+which still accepts null.
+"""
+
+from typing import Any
+
+_NULL = {"type": "null"}
+
+
+def compact(schema: dict[str, Any]) -> dict[str, Any]:
+    """A copy of *schema* with nullable optionals reduced to their real type."""
+    result = dict(schema)
+    properties = schema.get("properties")
+    if isinstance(properties, dict):
+        result["properties"] = {name: _property(prop) for name, prop in properties.items()}
+    items = schema.get("items")
+    if isinstance(items, dict):
+        result["items"] = compact(items)
+    definitions = schema.get("$defs")
+    if isinstance(definitions, dict):  # models such as Participant; FastMCP inlines them later
+        result["$defs"] = {name: _definition(d) for name, d in definitions.items()}
+    return result
+
+
+def _definition(model: dict[str, Any]) -> dict[str, Any]:
+    # A model's docstring would repeat what the parameter using it already says.
+    return {key: value for key, value in compact(model).items() if key != "description"}
+
+
+def _property(prop: dict[str, Any]) -> dict[str, Any]:
+    variants = prop.get("anyOf")
+    if isinstance(variants, list) and len(variants) == 2 and _NULL in variants:
+        real = next(v for v in variants if v != _NULL)
+        rest = {key: value for key, value in prop.items() if key != "anyOf"}
+        if rest.get("default", ...) is None:
+            del rest["default"]
+        prop = {**real, **rest}
+    return compact(prop)

dndkit/tools/screen.py

@@ -0,0 +1,47 @@
+"""The data tool the MCP Apps widgets read; the conversation never needs it."""
+
+import json
+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.dice import DiceLog
+from dndkit.models import Campaign
+from dndkit.storage import CampaignStore
+from dndkit.tools.deps import READ_ONLY, get_dice_log, get_store
+from dndkit.views import everyone, widgets
+
+View = Literal["dice", "combat", "party", "character", "seating"]
+CAMPAIGN_VIEWS: dict[str, Callable[[Campaign], everyone.Json]] = {
+    "combat": widgets.combat,
+    "party": everyone.party,
+    "seating": everyone.seating_chart,
+}
+
+
+@tool(annotations=READ_ONLY)
+def get_screen_data(
+    view: Annotated[View, Field(description="Which widget")],
+    name: Annotated[str | None, Field(description="Character, for the character view")] = None,
+    store: CampaignStore = Depends(get_store),
+    log: DiceLog = Depends(get_dice_log),
+) -> str:
+    """JSON for the on-screen widgets. Never needed in conversation."""
+    if view == "dice":
+        data = everyone.dice(log)
+    elif view == "character" and not name:
+        raise InvalidChangeError("The character view needs a name.")
+    else:
+        with store.reading() as campaign:
+            if view == "character" and name:
+                data = everyone.character(campaign, name)
+            else:
+                data = CAMPAIGN_VIEWS[view](campaign)
+    return json.dumps(data, ensure_ascii=False, separators=(",", ":"))
+
+
+TOOLS: list[Callable[..., str]] = [get_screen_data]

dndkit/tools/spells.py

@@ -0,0 +1,67 @@
+"""Spell tools: slots and the spells a character knows."""
+
+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.game import spellbook
+from dndkit.storage import CampaignStore
+from dndkit.tools.deps import NameOrId, get_store, provided
+
+SpellLevel = Annotated[int, Field(ge=1, le=9, description="Spell slot level (1-9)")]
+
+
+@tool
+def set_spell_slots(
+    character_name_or_id: NameOrId,
+    level: SpellLevel,
+    max_slots: Annotated[int, Field(ge=0, le=9, description="Slots at this level; 0 removes")],
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Set how many spell slots a character has at one level (level_up does it by class)."""
+    with store.transaction() as campaign:
+        character = spellbook.set_spell_slots(campaign, character_name_or_id, level, max_slots)
+    return f"{character.name}'s spell slots: {spellbook.describe_slots(character)}."
+
+
+@tool
+def use_spell_slot(
+    character_name_or_id: NameOrId,
+    level: SpellLevel,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Spend one spell slot when a character casts a levelled spell."""
+    with store.transaction() as campaign:
+        character, left = spellbook.use_spell_slot(campaign, character_name_or_id, level)
+    return f"{character.name} has {left} level {level} slot(s) left."
+
+
+@tool
+def set_known_spell(
+    character_name_or_id: NameOrId,
+    spell: Annotated[str, Field(min_length=1, description="Spell name")],
+    level: Annotated[int | None, Field(ge=0, le=9, description="0 for a cantrip")] = None,
+    prepared: Annotated[bool | None, Field(description="Prepared today")] = None,
+    description: Annotated[str | None, Field(description="Short reminder of its effect")] = None,
+    forget: Annotated[bool, Field(description="Remove it from the list")] = False,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Add, change or remove (forget=true) a spell on a character's spell list."""
+    with store.transaction() as campaign:
+        if forget:
+            character, known = spellbook.forget_spell(campaign, character_name_or_id, spell)
+            return f"{character.name} no longer knows {known.name}."
+        changes = provided(level=level, prepared=prepared, description=description)
+        character, known, created = spellbook.set_known_spell(
+            campaign, character_name_or_id, spell, changes
+        )
+    verb = "learns" if created else "updates"
+    level_text = "cantrip" if known.level == 0 else f"level {known.level}"
+    prepared_text = ", prepared" if known.prepared else ""
+    return f"{character.name} {verb} {known.name} ({level_text}{prepared_text})."
+
+
+TOOLS: list[Callable[..., str]] = [set_spell_slots, use_spell_slot, set_known_spell]

dndkit/tools/utility.py

@@ -0,0 +1,42 @@
+"""Utility tools that need no campaign: dice and rules reminders."""
+
+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.game import dice, reference
+from dndkit.game.dice import DiceLog
+from dndkit.tools.apps import DICE_APP, app_meta
+from dndkit.tools.deps import READ_ONLY, get_dice_log
+
+
+@tool(meta=app_meta(DICE_APP))
+def roll_dice(
+    notation: Annotated[
+        str, Field(min_length=1, description="Dice to roll, e.g. d20, 1d20+5, 2d6+1d4+3")
+    ],
+    advantage: Annotated[bool, Field(description="Roll a d20 twice, keep the higher")] = False,
+    disadvantage: Annotated[bool, Field(description="Roll a d20 twice, keep the lower")] = False,
+    secret: Annotated[bool, Field(description="Kept off the players' screens")] = False,
+    log: DiceLog = Depends(get_dice_log),
+) -> str:
+    """Roll dice (shown rolling on screen). Advantage and disadvantage cancel out. A secret
+    roll (a hidden foe's Stealth, an NPC's lie) shows on the backstage only."""
+    result = dice.roll(notation, advantage=advantage, disadvantage=disadvantage)
+    log.record(result, secret=secret)
+    return f"{'Secret: ' if secret else ''}{result.notation}: {result.detail}"
+
+
+@tool(annotations=READ_ONLY)
+def lookup_rule(
+    topic: Annotated[str, Field(description="A condition or rule, e.g. prone, cover, à terre")],
+) -> str:
+    """A short reminder of a 5e rule: conditions, death saves, rests, cover, grapple..."""
+    key, text = reference.lookup(topic)
+    return f"{key}: {text}"
+
+
+TOOLS: list[Callable[..., str]] = [roll_dice, lookup_rule]

dndkit/ui/__init__.py

@@ -0,0 +1,52 @@
+"""The pages: MCP Apps widgets and the web pages.
+
+Each ``<name>.html`` holds one page; the shared styles and scripts replace its
+``<!--gm:shared-->`` marker, so every page served is self-contained:
+roomkit-ui serves a widget's HTML alone, relative URLs 404, and sessions may
+be offline. A web page also gets ``window.GM_WEB``, which makes ``shared.js``
+read the server's event stream instead of calling MCP tools.
+
+The scripts are written as ES modules, so tools (knip) can follow who uses
+what; a page inlines them as one classic script, their import lines dropped and
+their exports left as plain declarations, in ``SCRIPTS`` order (a module after
+those it imports).
+"""
+
+import re
+from functools import cache
+from importlib.resources import files
+
+_MARKER = "<!--gm:shared-->"
+_STYLES = ("shared.css", "components.css")
+SCRIPTS = (
+    "words.js",
+    "shared.js",
+    "dicetray.js",
+    "battlemap.js",
+    "backstage.js",
+    "world.js",
+    "sheet.js",
+    "desk.js",
+    "components.js",
+)
+_WEB = '<script>window.GM_WEB = { feed: "feed" };</script>\n'
+IMPORT = re.compile(r'^import \{[^}]*\} from "\./([\w-]+\.js)";\n', re.MULTILINE)
+_EXPORT = re.compile(r"^export (?=(?:const|function|class) )", re.MULTILINE)
+
+
+@cache
+def page(name: str, web: bool = False) -> str:
+    """The complete HTML of page *name*; *web* for a page served by the web server."""
+    css = "".join(_read(style) for style in _STYLES)
+    js = "\n".join(_inline(_read(script)) for script in SCRIPTS)
+    shared = f"<style>\n{css}</style>\n{_WEB if web else ''}<script>\n{js}</script>"
+    return _read(f"{name}.html").replace(_MARKER, shared, 1)
+
+
+def _inline(module: str) -> str:
+    """A module as part of the page's one classic script."""
+    return _EXPORT.sub("", IMPORT.sub("", module))
+
+
+def _read(name: str) -> str:
+    return files(__name__).joinpath(name).read_text(encoding="utf-8")

dndkit/ui/backstage.js

@@ -0,0 +1,41 @@
+/* The game master's plans: encounters still to fight, and every quest with
+ * its objectives, reward and notes. */
+"use strict";
+
+import { GM } from "./shared.js";
+
+export function Backstage() {
+  const { h, fill, t } = GM;
+  const section = (title, ...content) => h("div", { class: "section" }, h("h4", {}, title), ...content);
+  const empty = (key) => h("div", { class: "empty small" }, t(key));
+  const encounters = h("div");
+  const quests = h("div");
+  const el = h("div", { class: "card backstage" },
+    h("div", { class: "head" }, h("span", { class: "title" }, t("backstage"))),
+    section(t("encounters"), encounters), section(t("allQuests"), quests));
+  const note = (label, text) => (text ? h("div", { class: "note small" }, h("b", {}, `${label} `), text) : null);
+  const line = (...parts) => parts.filter(Boolean).join(" — ");
+
+  const encounter = (e) => h("div", { class: "entry" + (e.status === "done" ? " done" : "") },
+    h("div", { class: "row" }, h("b", {}, e.name), h("span", { class: "chip" }, t(e.status)),
+      e.difficulty ? h("span", { class: `chip rating ${e.difficulty}` }, `${t(e.difficulty)} · ${e.xp} ${t("xp")}`) : null),
+    h("div", { class: "muted small" }, line(e.monsters.join(", "), e.location)),
+    e.description ? h("div", { class: "small" }, e.description) : null,
+    note(t("notes"), e.notes));
+
+  const quest = (q) => h("div", { class: "entry" },
+    h("div", { class: "row" }, h("b", {}, q.title), h("span", { class: "chip" }, t(q.status)),
+      q.total ? h("span", { class: "muted small" }, `${q.done}/${q.total}`) : null),
+    q.giver || q.description ? h("div", { class: "small" },
+      q.giver ? h("span", { class: "muted" }, `${t("from", { name: q.giver })}. `) : null, q.description) : null,
+    q.objectives.length ? h("ul", { class: "objectives small" },
+      q.objectives.map((o) => h("li", { class: o.done ? "done" : "" }, o.text))) : null,
+    note(t("reward"), q.reward), note(t("notes"), q.notes));
+
+  function render(data) {
+    fill(encounters, data.encounters.length ? data.encounters.map(encounter) : empty("noEncounter"));
+    fill(quests, data.quests.length ? data.quests.map(quest) : empty("noQuest"));
+  }
+
+  return { el, render };
+}

dndkit/ui/battlemap.js

@@ -0,0 +1,70 @@
+/* The battle map in SVG: 5-foot squares named like a chessboard (A1 top left),
+ * walls, difficult terrain, a token per combatant (the party gold, its foes
+ * red, the hidden ones faint on the game master's screen), the squares the
+ * acting creature can still reach this turn, and the last area of effect. */
+"use strict";
+
+export function BattleMap(map, me) {
+  const NS = "http://www.w3.org/2000/svg";
+  const CELL = 40;
+  const GUTTER = 22;
+  const at = (n) => GUTTER + n * CELL;
+
+  function s(tag, attrs, ...children) {
+    const el = document.createElementNS(NS, tag);
+    for (const [key, value] of Object.entries(attrs || {})) {
+      if (value !== null && value !== undefined && value !== false) el.setAttribute(key, value);
+    }
+    el.append(...children.flat().filter((child) => child !== null && child !== undefined));
+    return el;
+  }
+
+  const square = (cls) => ([x, y]) => s("rect", { x: at(x), y: at(y), width: CELL, height: CELL, class: cls });
+
+  function initials(name) {
+    const words = name.trim().split(/\s+/);
+    const last = words[words.length - 1];
+    if (words.length > 1 && /^\d+$/.test(last)) return words[0].charAt(0).toUpperCase() + last;
+    if (words.length > 1) return (words[0].charAt(0) + words[1].charAt(0)).toUpperCase();
+    return name.slice(0, 2);
+  }
+
+  function token(t) {
+    const radius = (t.size * CELL) / 2;
+    const cx = at(t.x) + radius;
+    const cy = at(t.y) + radius;
+    const classes = ["token", t.party ? "party" : "foe", t.current && "current", t.down && "down",
+      t.hidden && "hidden", t.boss && "boss", me && t.name === me && "me", t.health].filter(Boolean).join(" ");
+    const ratio = t.hp_max ? Math.max(0, Math.min(1, t.hp / t.hp_max)) : null;
+    const bar = ratio === null ? null : [
+      s("rect", { x: cx - radius + 6, y: cy + radius - 7, width: 2 * radius - 12, height: 4, class: "life" }),
+      s("rect", { x: cx - radius + 6, y: cy + radius - 7, width: (2 * radius - 12) * ratio, height: 4,
+        class: "life-left" + (ratio > 0.5 ? "" : ratio > 0.25 ? " mid" : " low") }),
+    ];
+    return s("g", { class: classes }, s("title", {}, t.name),
+      s("circle", { cx, cy, r: radius - 5 }),
+      s("text", { x: cx, y: cy + 4.5 }, initials(t.name)), bar,
+      t.boss ? s("text", { x: cx, y: cy - radius + 9, class: "crown" }, "♛") : null);
+  }
+
+  const width = at(map.width);
+  const height = at(map.height);
+  const lines = [];
+  for (let x = 0; x <= map.width; x++) lines.push(`M${at(x)},${GUTTER}V${height}`);
+  for (let y = 0; y <= map.height; y++) lines.push(`M${GUTTER},${at(y)}H${width}`);
+
+  return s("svg", { viewBox: `0 0 ${width + 2} ${height + 2}`, class: "battlemap", role: "img" },
+    s("defs", {}, s("pattern", { id: "gm-rough", width: 8, height: 8, patternUnits: "userSpaceOnUse" },
+      s("path", { d: "M0,8 L8,0 M-2,2 L2,-2 M6,10 L10,6", class: "hatch" }))),
+    s("rect", { x: GUTTER, y: GUTTER, width: width - GUTTER, height: height - GUTTER, class: "floor" }),
+    map.moves.map(square("reach")),
+    map.difficult.map(square("rough")),
+    s("path", { d: lines.join(""), class: "grid" }),
+    map.walls.map(square("wall")),
+    (map.area || []).map(square("area")),
+    Array.from({ length: map.width }, (_, x) =>
+      s("text", { x: at(x) + CELL / 2, y: GUTTER - 7, class: "label" }, String.fromCharCode(65 + x))),
+    Array.from({ length: map.height }, (_, y) =>
+      s("text", { x: GUTTER - 5, y: at(y) + CELL / 2 + 4, class: "label row" }, String(y + 1))),
+    map.tokens.map(token));
+}

dndkit/ui/character.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Character sheet</title>
+    <!--gm:shared-->
+  </head>
+  <body>
+    <div id="app"></div>
+    <div id="status"></div>
+    <script>
+      const sheet = Views.character();
+      document.getElementById("app").append(sheet.el);
+      GM.start(async () => {
+        const args = await GM.toolInput();
+        const name = args.name_or_id;
+        if (!name) return GM.status("?");
+        GM.live("character", { name }, sheet.render, 2500);
+      });
+    </script>
+  </body>
+</html>

dndkit/ui/combat.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Combat tracker</title>
+    <!--gm:shared-->
+  </head>
+  <body>
+    <div id="app"></div>
+    <div id="status"></div>
+    <script>
+      const tracker = Views.combat();
+      document.getElementById("app").append(tracker.el);
+      GM.start(() => GM.live("combat", null, tracker.render, 1500));
+    </script>
+  </body>
+</html>