dndkit 0.4.0__py3-none-any.whl

dndkit/models/campaign.py

@@ -0,0 +1,209 @@
+"""The campaign container, its live game state and its journal.
+
+Older saves keyed characters, NPCs, locations and quests by name and kept a
+combat order of free-form dicts; the validators here read those saves as-is.
+"""
+
+import re
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import Field, ValidationError, field_validator
+
+from dndkit.models.base import GameModel, new_id, now
+from dndkit.models.battle import Battlefield
+from dndkit.models.bestiary import Encounter, Monster, Size
+from dndkit.models.character import Character
+from dndkit.models.world import NPC, Location, Quest
+
+
+class Combatant(GameModel):
+    """One entry in the initiative order.
+
+    A party character is linked by ``character_id`` and its hit points,
+    conditions and speed live on its sheet; any other combatant (monster, NPC)
+    keeps its own here, when they are known. ``ally`` puts a non-party
+    combatant on the party's side. On a battle map, ``position`` is the
+    top-left square it occupies, and the movement fields last one turn.
+    """
+
+    name: str = Field(min_length=1)
+    initiative: int
+    character_id: str | None = None
+    monster: str | None = None  # bestiary entry it was built from
+    hit_points: int | None = Field(default=None, ge=0)
+    hit_points_max: int | None = Field(default=None, ge=1)
+    armor_class: int | None = Field(default=None, ge=0)
+    xp: int = Field(default=0, ge=0)
+    conditions: list[str] = Field(default_factory=list)
+    condition_rounds: dict[str, int] = Field(default_factory=dict)  # turns left, if timed
+    concentration: str | None = None  # the spell held (a character's is on its sheet)
+    ally: bool = False
+    size: Size = "medium"
+    speed: int | None = Field(default=None, ge=0)  # feet; None: 30
+    reach: int = Field(default=5, ge=5)
+    position: str | None = None
+    hidden: bool = False  # unseen by the players: kept off their screens
+    boss: bool = False
+    legendary_actions: int = Field(default=0, ge=0)  # a round's worth, from the stat block
+    legendary_actions_left: int = Field(default=0, ge=0)  # back at the start of its turn
+    legendary_resistances_left: int = Field(default=0, ge=0)
+    movement_used: int = Field(default=0, ge=0)
+    dashed: bool = False
+    disengaged: bool = False
+    reaction_used: bool = False  # one a round, back at the start of its turn
+
+
+class Participant(GameModel):
+    """Someone joining a fight, as a tool call describes them."""
+
+    name: str = Field(min_length=1, description="Character, monster or NPC name")
+    initiative: int = Field(description="Initiative roll")
+    hit_points: int | None = Field(default=None, ge=1, description="HP, if not in bestiary")
+    armor_class: int | None = Field(default=None, ge=0, description="AC, if not in bestiary")
+
+
+class Seat(GameModel):
+    """A player at the table, as a tool call describes them."""
+
+    player: str = Field(min_length=1, description="Person's name, as their voice is named")
+    character: str | None = Field(default=None, description="Character they play")
+
+
+class CombatRecord(GameModel):
+    """What the last fight was, kept once it ends."""
+
+    rounds: int = 0
+    fighters: list[str] = Field(default_factory=list)
+    defeated: list[str] = Field(default_factory=list)
+    xp: int = 0
+    ended: datetime = Field(default_factory=now)
+
+
+class GameState(GameModel):
+    """Where the party is and what is happening right now."""
+
+    campaign_name: str
+    current_session: int = Field(default=1, ge=1)
+    current_date_in_game: str | None = None
+    current_location: str | None = None
+    party_level: int = Field(default=1, ge=1, le=20)  # legacy: each sheet has its level
+    party_funds: str = "0 gp"
+    in_combat: bool = False
+    initiative_order: list[Combatant] = Field(default_factory=list)
+    turn_index: int = Field(default=0, ge=0)
+    combat_round: int = Field(default=0, ge=0)
+    defeated: list[Combatant] = Field(default_factory=list)  # fallen this combat
+    encounter_id: str | None = None  # the planned encounter being fought
+    players_present: list[str] = Field(default_factory=list)  # the roll call, in seat order
+    roll_call_at: datetime | None = None  # when seat_players last changed it
+    battlefield: Battlefield | None = None
+    last_combat: CombatRecord | None = None
+    notes: str = ""
+    updated_at: datetime = Field(default_factory=now)
+
+    @field_validator("initiative_order", mode="before")
+    @classmethod
+    def _keep_playable_legacy_entries(cls, value: Any) -> Any:
+        # Older versions stored any dict the model sent ({"initiative": "15 (Dex)"},
+        # no name...): what cannot take a turn must not stop the campaign from loading.
+        if not isinstance(value, list):
+            return value
+        kept: list[Any] = []
+        for entry in value:
+            if isinstance(entry, dict):
+                entry = {**entry, "initiative": _legacy_initiative(entry.get("initiative"))}
+                try:
+                    Combatant.model_validate(entry)
+                except ValidationError:
+                    continue
+            kept.append(entry)
+        return kept
+
+    @property
+    def current_combatant(self) -> Combatant | None:
+        """Whose turn it is, when a fight is running."""
+        if not self.in_combat or not self.initiative_order:
+            return None
+        return self.initiative_order[self.turn_index % len(self.initiative_order)]
+
+
+def _legacy_initiative(value: Any) -> int:
+    """An old save's initiative as a number: 15, "15 (Dex)", or 0 when missing."""
+    if isinstance(value, int | float) and not isinstance(value, bool):
+        return int(value)
+    match = re.match(r"\s*(-?\d+)", str(value or ""))
+    return int(match.group(1)) if match else 0
+
+
+class SessionNote(GameModel):
+    """A summary of one play session."""
+
+    id: str = Field(default_factory=new_id)
+    session_number: int = Field(ge=1)
+    date: datetime = Field(default_factory=now)
+    title: str | None = None
+    summary: str
+    events: list[str] = Field(default_factory=list)
+    characters_present: list[str] = Field(default_factory=list)
+    experience_gained: int | None = Field(default=None, ge=0)
+    treasure_found: list[str] = Field(default_factory=list)
+    notes: str = ""
+
+
+class EventType(StrEnum):
+    """Categories of the adventure log."""
+
+    COMBAT = "combat"
+    ROLEPLAY = "roleplay"
+    EXPLORATION = "exploration"
+    QUEST = "quest"
+    CHARACTER = "character"
+    WORLD = "world"
+    SESSION = "session"
+
+
+class AdventureEvent(GameModel):
+    """One entry of the campaign's adventure log."""
+
+    id: str = Field(default_factory=new_id)
+    event_type: EventType
+    title: str
+    description: str
+    timestamp: datetime = Field(default_factory=now)
+    session_number: int | None = None
+    characters_involved: list[str] = Field(default_factory=list)
+    location: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    importance: int = Field(default=3, ge=1, le=5)  # 1 minor .. 5 major
+
+
+class Campaign(GameModel):
+    """Everything one campaign holds; saved as one JSON file."""
+
+    id: str = Field(default_factory=new_id)
+    name: str = Field(min_length=1)
+    description: str
+    dm_name: str | None = None
+    setting: str | None = None
+    characters: dict[str, Character] = Field(default_factory=dict)
+    npcs: dict[str, NPC] = Field(default_factory=dict)
+    locations: dict[str, Location] = Field(default_factory=dict)
+    quests: dict[str, Quest] = Field(default_factory=dict)
+    monsters: dict[str, Monster] = Field(default_factory=dict)
+    encounters: dict[str, Encounter] = Field(default_factory=dict)
+    sessions: list[SessionNote] = Field(default_factory=list)
+    events: list[AdventureEvent] = Field(default_factory=list)
+    game_state: GameState
+    world_notes: str = ""
+    created_at: datetime = Field(default_factory=now)
+    updated_at: datetime = Field(default_factory=now)
+
+    @field_validator(
+        "characters", "npcs", "locations", "quests", "monsters", "encounters", mode="after"
+    )
+    @classmethod
+    def _key_by_id(cls, value: dict[str, Any]) -> dict[str, Any]:
+        # Entities are keyed by ID: names change and two spellings may collide.
+        return {entity.id: entity for entity in value.values()}

dndkit/models/character.py

@@ -0,0 +1,149 @@
+"""Player characters and what they carry."""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import Field
+
+from dndkit.models.base import GameModel, new_id, now
+
+ABILITIES = ("strength", "dexterity", "constitution", "intelligence", "wisdom", "charisma")
+CONDITIONS = (
+    "blinded",
+    "charmed",
+    "deafened",
+    "frightened",
+    "grappled",
+    "incapacitated",
+    "invisible",
+    "paralyzed",
+    "petrified",
+    "poisoned",
+    "prone",
+    "restrained",
+    "stunned",
+    "unconscious",
+)
+
+
+class AbilityScore(GameModel):
+    """One ability score; the modifier is derived from it."""
+
+    score: int = Field(ge=1, le=30, description="Raw ability score")
+
+    @property
+    def mod(self) -> int:
+        """The 5e ability modifier."""
+        return (self.score - 10) // 2
+
+
+class CharacterClass(GameModel):
+    """Class, level and hit dice."""
+
+    name: str
+    level: int = Field(default=1, ge=1, le=20)
+    hit_dice: str = "1d8"
+    subclass: str | None = None
+
+
+class Race(GameModel):
+    """Race (species) and its traits."""
+
+    name: str
+    subrace: str | None = None
+    traits: list[str] = Field(default_factory=list)
+
+
+class Item(GameModel):
+    """An inventory entry; identical items stack through ``quantity``."""
+
+    id: str = Field(default_factory=new_id)
+    name: str = Field(min_length=1)
+    description: str | None = None
+    quantity: int = Field(default=1, ge=1)
+    weight: float | None = Field(default=None, ge=0)
+    value: str | None = None  # e.g. "50 gp"
+    item_type: str = "misc"  # weapon, armor, consumable, misc
+    properties: dict[str, Any] = Field(default_factory=dict)
+
+
+class Spell(GameModel):
+    """A known spell; only the name and level are required."""
+
+    id: str = Field(default_factory=new_id)
+    name: str = Field(min_length=1)
+    level: int = Field(ge=0, le=9)  # 0 is a cantrip
+    school: str = ""
+    casting_time: str = ""
+    range: int | str = ""  # free text: "Self", "Touch", "120 feet"
+    duration: str = ""
+    components: list[str] = Field(default_factory=list)
+    description: str = ""
+    material_components: str | None = None
+    prepared: bool = False
+
+
+def _default_abilities() -> dict[str, AbilityScore]:
+    return {ability: AbilityScore(score=10) for ability in ABILITIES}
+
+
+class Character(GameModel):
+    """A complete character sheet.
+
+    ``hit_points_current`` above ``hit_points_max`` is refused by the game
+    logic, not here: a save written by an older version may hold one, and it
+    must still load.
+    """
+
+    id: str = Field(default_factory=new_id)
+    name: str = Field(min_length=1)
+    player_name: str | None = None
+    character_class: CharacterClass
+    race: Race
+    background: str | None = None
+    alignment: str | None = None
+    description: str | None = None  # appearance and demeanor
+    bio: str | None = None  # backstory, personality, motivations
+
+    abilities: dict[str, AbilityScore] = Field(default_factory=_default_abilities)
+
+    armor_class: int = Field(default=10, ge=0)
+    speed: int = Field(default=30, ge=0)  # walking, in feet
+    hit_points_max: int = Field(default=1, ge=1)
+    hit_points_current: int = Field(default=1, ge=0)
+    temporary_hit_points: int = Field(default=0, ge=0)
+    hit_dice_remaining: str = "1d8"
+    death_saves_success: int = Field(default=0, ge=0, le=3)
+    death_saves_failure: int = Field(default=0, ge=0, le=3)
+    stable: bool = False  # at 0 HP without death saves (three successes, a Medicine check)
+    conditions: list[str] = Field(default_factory=list)  # names from CONDITIONS
+    condition_rounds: dict[str, int] = Field(default_factory=dict)  # turns left, if timed
+    concentration: str | None = None  # the spell held
+    exhaustion: int = Field(default=0, ge=0, le=6)
+    experience_points: int = Field(default=0, ge=0)
+
+    proficiency_bonus: int = 2
+    skill_proficiencies: list[str] = Field(default_factory=list)
+    skill_expertise: list[str] = Field(default_factory=list)  # proficiency counted twice
+    saving_throw_proficiencies: list[str] = Field(default_factory=list)
+
+    inventory: list[Item] = Field(default_factory=list)
+    equipment: dict[str, Item | None] = Field(default_factory=dict)
+
+    spellcasting_ability: str | None = None
+    spell_slots: dict[int, int] = Field(default_factory=dict)  # level -> max slots
+    spell_slots_used: dict[int, int] = Field(default_factory=dict)  # level -> used
+    spells_known: list[Spell] = Field(default_factory=list)
+
+    features_and_traits: list[str] = Field(default_factory=list)
+    languages: list[str] = Field(default_factory=list)
+
+    inspiration: bool = False
+    notes: str = ""
+    created_at: datetime = Field(default_factory=now)
+    updated_at: datetime = Field(default_factory=now)
+
+    @property
+    def hp_maximum(self) -> int:
+        """The hit point maximum now: halved from exhaustion level 4 (PHB appendix A)."""
+        return max(1, self.hit_points_max // 2) if self.exhaustion >= 4 else self.hit_points_max

dndkit/models/world.py

@@ -0,0 +1,62 @@
+"""The world around the party: NPCs, places and quests."""
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import Field
+
+from dndkit.models.base import GameModel, new_id, now
+
+Attitude = Literal["friendly", "neutral", "hostile", "unknown"]
+QuestStatus = Literal["active", "completed", "failed", "on_hold"]
+
+
+class NPC(GameModel):
+    """A non-player character."""
+
+    id: str = Field(default_factory=new_id)
+    name: str = Field(min_length=1)
+    description: str | None = None  # public
+    bio: str | None = None  # private: backstory, motivations, secrets
+    race: str | None = None
+    occupation: str | None = None
+    location: str | None = None
+    attitude: Attitude | None = None
+    notes: str = ""
+    stats: dict[str, Any] | None = None
+    relationships: dict[str, str] = Field(default_factory=dict)  # who -> relationship
+
+
+class Location(GameModel):
+    """A place: settlement, dungeon, region."""
+
+    id: str = Field(default_factory=new_id)
+    name: str = Field(min_length=1)
+    location_type: str  # city, town, village, dungeon, forest...
+    description: str
+    population: int | None = Field(default=None, ge=0)
+    government: str | None = None
+    notable_features: list[str] = Field(default_factory=list)
+    npcs: list[str] = Field(default_factory=list)
+    connections: list[str] = Field(default_factory=list)
+    notes: str = ""
+
+
+class Quest(GameModel):
+    """A quest and its objectives."""
+
+    id: str = Field(default_factory=new_id)
+    title: str = Field(min_length=1)
+    description: str
+    giver: str | None = None
+    status: QuestStatus = "active"
+    objectives: list[str] = Field(default_factory=list)
+    completed_objectives: list[str] = Field(default_factory=list)
+    reward: str | None = None
+    notes: str = ""
+    created_at: datetime = Field(default_factory=now)
+
+    @property
+    def name(self) -> str:
+        """The title, so quests are looked up like every other entity."""
+        return self.title

dndkit/skills/__init__.py

@@ -0,0 +1,14 @@
+"""Agent Skills shipped with the server, and their publication over MCP.
+
+Each folder here holding a ``SKILL.md`` is a skill (agentskills.io). The
+server publishes them by the MCP Skills extension (SEP-2640,
+``io.modelcontextprotocol/skills``): every file as a ``skill://<name>/<path>``
+resource, and the ``skills/list`` and ``skills/get`` methods. A skill's
+``allowed_tools`` frontmatter is roomkit's: it keeps those tools out of the
+model's catalogue until the skill is activated.
+"""
+
+from dndkit.skills.catalog import Skill, load_catalog
+from dndkit.skills.extension import SkillsExtension, register_skills
+
+__all__ = ["Skill", "SkillsExtension", "load_catalog", "register_skills"]

dndkit/skills/catalog.py

@@ -0,0 +1,113 @@
+"""The skills in this package: their frontmatter, their files, and the digests of those.
+
+A skill is a folder with a ``SKILL.md`` whose YAML frontmatter names it; the
+name must be the folder's (Agent Skills specification). Every file under the
+folder belongs to the skill. Files are read once, at load: the digests then
+describe exactly what the server serves.
+"""
+
+import hashlib
+import json
+import mimetypes
+from dataclasses import dataclass
+from functools import cache
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from typing import Any
+
+import yaml
+
+SKILL_FILE = "SKILL.md"
+SCHEME = "skill://"
+
+
+@dataclass(frozen=True)
+class SkillFile:
+    """One file of a skill, as served."""
+
+    path: str  # relative to the skill's folder, "/"-separated
+    content: bytes
+
+    @property
+    def digest(self) -> str:
+        """``sha256:<hex>`` of the raw bytes (SEP-2640)."""
+        return "sha256:" + hashlib.sha256(self.content).hexdigest()
+
+    @property
+    def mime_type(self) -> str:
+        if self.path.endswith(".md"):
+            return "text/markdown"
+        return mimetypes.guess_type(self.path)[0] or "application/octet-stream"
+
+
+@dataclass(frozen=True)
+class Skill:
+    """A skill: its frontmatter as written, and all its files."""
+
+    name: str
+    frontmatter: dict[str, Any]
+    files: tuple[SkillFile, ...]
+
+    @property
+    def uri(self) -> str:
+        """The URI of its ``SKILL.md``, which identifies the skill."""
+        return self.file_uri(SKILL_FILE)
+
+    def file_uri(self, path: str) -> str:
+        return f"{SCHEME}{self.name}/{path}"
+
+    def entry(self) -> dict[str, Any]:
+        """Its ``skills/list`` entry: uri, verbatim frontmatter, every file's digest and size."""
+        return {
+            "uri": self.uri,
+            "frontmatter": self.frontmatter,
+            "resources": [
+                {"uri": self.file_uri(f.path), "digest": f.digest, "size": len(f.content)}
+                for f in self.files
+            ],
+        }
+
+
+@cache
+def load_catalog() -> tuple[Skill, ...]:
+    """Every skill shipped in this package, by name."""
+    root = files(__name__.rsplit(".", 1)[0])
+    skills = [_load(folder) for folder in root.iterdir() if folder.joinpath(SKILL_FILE).is_file()]
+    return tuple(sorted(skills, key=lambda s: s.name))
+
+
+def frontmatter_of(text: str) -> dict[str, Any]:
+    """The YAML frontmatter of a ``SKILL.md``, as a JSON-ready mapping: between a
+    first line ``---`` and the next line that is ``---`` alone."""
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        raise ValueError("SKILL.md must begin with YAML frontmatter.")
+    end = next((i for i, line in enumerate(lines[1:], 1) if line.strip() == "---"), None)
+    if end is None:
+        raise ValueError("SKILL.md frontmatter has no closing '---'.")
+    data = yaml.safe_load("\n".join(lines[1:end]))
+    if not isinstance(data, dict) or not data.get("name") or not data.get("description"):
+        raise ValueError("SKILL.md frontmatter needs a name and a description.")
+    # skills/list sends it as JSON: a YAML date becomes its text.
+    return dict(json.loads(json.dumps(data, default=str)))
+
+
+def _load(folder: Traversable) -> Skill:
+    frontmatter = frontmatter_of(folder.joinpath(SKILL_FILE).read_text(encoding="utf-8"))
+    if frontmatter["name"] != folder.name:
+        raise ValueError(f"Skill folder {folder.name} holds a skill named {frontmatter['name']}.")
+    found = sorted(_walk(folder, ""), key=lambda f: (f.path != SKILL_FILE, f.path))
+    return Skill(name=folder.name, frontmatter=frontmatter, files=tuple(found))
+
+
+def _walk(folder: Traversable, prefix: str) -> list[SkillFile]:
+    found: list[SkillFile] = []
+    for entry in folder.iterdir():
+        if entry.name.startswith((".", "__")):
+            continue
+        path = f"{prefix}{entry.name}"
+        if entry.is_dir():
+            found += _walk(entry, f"{path}/")
+        else:
+            found.append(SkillFile(path, entry.read_bytes()))
+    return found

dndkit/skills/dnd-battle-map/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: dnd-battle-map
+description: Run a D&D 5e fight on a grid battle map with the dndkit tools - lay out the room, place and hide combatants, move them by the rules (speed, terrain, opportunity attacks), areas of effect, cover. Activate when a fight starts where positions matter.
+allowed_tools:
+  - set_battlefield
+  - place_tokens
+  - move_token
+  - area_of_effect
+  - check_target
+---
+
+# Fighting on the battle map
+
+The map is a grid of 5-foot squares named like a chessboard: a column letter
+and a row number, A1 at the top left. The players see it on the table screen
+and on their phones; you only read it through the tools, so never guess a
+position or a distance: `get_game_state` lists every square and the distances
+from whoever is acting, and every move says who is now in reach.
+
+## Set the scene
+
+- Use a map when position matters: several foes, cover, a corridor, a ledge.
+  A duel or a brawl can stay in words.
+- Turn your description into `set_battlefield`: width and height in squares
+  (a 30-foot room is 6 squares), walls and pillars as `walls`, rubble, mud or
+  undergrowth as `difficult`. Blocks are written `C1:C6`.
+- `start_combat` places everyone with no square yet: the party on the left
+  edge, its foes on the right. Use `place_tokens` for a formation; a big
+  creature is placed by its top-left square.
+- A planned encounter can carry its map and its monsters' squares
+  (`plan_encounter` with `battlefield`, and `at` per group): `start_combat`
+  with that encounter lays them out.
+- Changed your mind about who is in the fight? `remove_combatant` with
+  `reason: withdrawn` takes a creature off the map and out of the initiative,
+  as if it never joined (no XP); `add_combatant` brings one in, at its side's
+  edge, and `place_tokens` puts it where you want. A redrawn map
+  (`set_battlefield`) keeps everyone who still fits.
+- Foes the players have not noticed are `hidden` (in the plan, or with
+  `place_tokens`): they stay off the players' screens and out of the
+  initiative they see. Reveal them with `place_tokens` (`hidden: false`) when
+  they are spotted or attack.
+- Save monsters with their `size` and `speed` (`save_monster`) first: a Large
+  ogre holds 2x2 squares, and the speed decides how far it goes.
+
+## Each turn
+
+- When a player says where they go, call `move_token`:
+  - "I charge the goblin" -> `toward`: it stops within reach, or as close as
+    it can and says how far it still is;
+  - "I back off" -> `away_from`, with `feet` if they say how far;
+  - "I go to D7" -> `to`; it is refused if they cannot afford it: say so and
+    offer the Dash action, or to go toward it.
+- Dash (`dash`) doubles this turn's movement; Disengage (`disengage`) means
+  no opportunity attack. A prone character stands up first, for half their
+  speed; grappled or restrained ones cannot move.
+- When the result lists opportunity attacks, resolve them right away: the
+  foe attacks the mover (`roll_dice`), then the move goes on.
+- Shoves, Thunderwave, Misty Step and other pushes, pulls or teleports use
+  `forced`: no movement spent, no opportunity attack. A push stops at a wall
+  or a creature.
+- Move monsters on their turns too, sensibly: toward the nearest or weakest
+  character, away when they flee.
+- Before an attack, `check_target`: the distance (normal or long range),
+  reach, cover (+2 or +5 AC and Dexterity saves, or no target at all), a foe
+  adjacent to a ranged attacker (disadvantage), hidden attackers or targets.
+- For a spell or breath with an area, `area_of_effect`: a `sphere` (or
+  cylinder, radius) `at` a square or a creature, a `cone`, `line` or `cube`
+  from its `source` `toward` a square or a creature. It names everyone caught,
+  allies too, and walls stop it; it shows on the map until the next turn.
+  Each creature caught then makes its saving throw (`roll_dice`). Fireball
+  goes around corners: rule by hand when it matters.
+- `next_turn` gives the next combatant its full movement.
+
+## Speaking about it
+
+Say squares only when the players use them; otherwise describe ("you reach
+the goblin by the pillar"). The players' French books count in metres: 5 feet
+is 1.5 metres, so 30 feet is 9 metres.