dndkit 0.4.0__py3-none-any.whl

dndkit/tools/journal.py

@@ -0,0 +1,102 @@
+"""Journal tools: session notes and the adventure log."""
+
+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 journal
+from dndkit.models import AdventureEvent, EventType, SessionNote
+from dndkit.storage import CampaignStore
+from dndkit.tools import render
+from dndkit.tools.deps import READ_ONLY, get_store
+
+Names = Annotated[list[str] | None, Field(description="Character names")]
+
+
+@tool
+def add_session_note(
+    session_number: Annotated[int, Field(ge=1, description="Session number")],
+    summary: Annotated[str, Field(min_length=1, description="What happened")],
+    title: Annotated[str | None, Field(description="Session title")] = None,
+    events: Annotated[list[str] | None, Field(description="Key moments")] = None,
+    characters_present: Names = None,
+    experience_gained: Annotated[int | None, Field(ge=0, description="XP earned")] = None,
+    treasure_found: Annotated[list[str] | None, Field(description="Loot")] = None,
+    notes: Annotated[str, Field(description="Notes")] = "",
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Save the summary of a play session."""
+    note = SessionNote(
+        session_number=session_number,
+        summary=summary,
+        title=title,
+        events=events or [],
+        characters_present=characters_present or [],
+        experience_gained=experience_gained,
+        treasure_found=treasure_found or [],
+        notes=notes,
+    )
+    with store.transaction() as campaign:
+        journal.add_session_note(campaign, note)
+    return f"Saved notes for session {session_number}."
+
+
+@tool(annotations=READ_ONLY)
+def get_sessions(store: CampaignStore = Depends(get_store)) -> str:
+    """Session notes in play order, summaries shortened."""
+    with store.reading() as campaign:
+        notes = journal.sessions(campaign)
+        if not notes:
+            return "No session notes yet."
+        return "\n".join(render.session_line(note) for note in notes)
+
+
+@tool
+def add_event(
+    event_type: Annotated[EventType, Field(description="Kind of event")],
+    title: Annotated[str, Field(min_length=1, description="Short title")],
+    description: Annotated[str, Field(description="What happened")],
+    session_number: Annotated[
+        int | None, Field(ge=1, description="Session; defaults to the current one")
+    ] = None,
+    characters_involved: Names = None,
+    location: Annotated[str | None, Field(description="Where it happened")] = None,
+    importance: Annotated[int, Field(ge=1, le=5, description="1 minor to 5 major")] = 3,
+    tags: Annotated[list[str] | None, Field(description="Tags for search")] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Log a notable moment in the active campaign's adventure log."""
+    event = AdventureEvent(
+        event_type=event_type,
+        title=title,
+        description=description,
+        session_number=session_number,
+        characters_involved=characters_involved or [],
+        location=location,
+        importance=importance,
+        tags=tags or [],
+    )
+    with store.transaction() as campaign:
+        journal.add_event(campaign, event)
+    return f"Logged {event.event_type} event '{event.title}'."
+
+
+@tool(annotations=READ_ONLY)
+def get_events(
+    limit: Annotated[int | None, Field(ge=1, description="At most this many")] = 10,
+    event_type: Annotated[EventType | None, Field(description="Only this kind")] = None,
+    search: Annotated[str | None, Field(description="Text in title, description or tags")] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Recent adventure log entries, newest first; filters combine."""
+    with store.reading() as campaign:
+        events = journal.find_events(campaign, event_type=event_type, search=search, limit=limit)
+        if not events:
+            return "No matching events."
+        return "\n".join(render.event_line(event) for event in events)
+
+
+TOOLS: list[Callable[..., str]] = [add_session_note, get_sessions, add_event, get_events]

dndkit/tools/locations.py

@@ -0,0 +1,98 @@
+"""Location tools."""
+
+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 world
+from dndkit.models import Location
+from dndkit.storage import CampaignStore
+from dndkit.tools import render
+from dndkit.tools.deps import READ_ONLY, NameOrId, get_store, provided
+
+Text = Annotated[str | None, Field(description="New value")]
+Population = Annotated[int | None, Field(ge=0, description="Population")]
+Features = Annotated[list[str] | None, Field(description="Notable features")]
+
+
+@tool
+def create_location(
+    name: Annotated[str, Field(min_length=1, description="Location name")],
+    location_type: Annotated[str, Field(description="city, town, village, dungeon, forest...")],
+    description: Annotated[str, Field(description="What it looks and feels like")],
+    population: Population = None,
+    government: Annotated[str | None, Field(description="Who rules it")] = None,
+    notable_features: Features = None,
+    notes: Annotated[str, Field(description="Notes")] = "",
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Create a location. The name must be new; use update_location to change one."""
+    location = Location(
+        name=name.strip(),
+        location_type=location_type,
+        description=description,
+        population=population,
+        government=government,
+        notable_features=notable_features or [],
+        notes=notes,
+    )
+    with store.transaction() as campaign:
+        world.create_location(campaign, location)
+    return f"Created location {location.name} ({location.location_type}, id {location.id})."
+
+
+@tool(annotations=READ_ONLY)
+def get_location(name_or_id: NameOrId, store: CampaignStore = Depends(get_store)) -> str:
+    """A location's description, features, NPCs and connections."""
+    with store.reading() as campaign:
+        return render.location(world.find_location(campaign, name_or_id))
+
+
+@tool
+def update_location(
+    name_or_id: NameOrId,
+    name: Annotated[str | None, Field(description="New name")] = None,
+    location_type: Text = None,
+    description: Text = None,
+    population: Population = None,
+    government: Text = None,
+    notable_features: Features = None,
+    npcs: Annotated[list[str] | None, Field(description="NPC names found here")] = None,
+    connections: Annotated[list[str] | None, Field(description="Linked locations")] = None,
+    notes: Text = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Change a location. Lists given here replace the stored ones."""
+    changes = provided(
+        name=name,
+        location_type=location_type,
+        description=description,
+        population=population,
+        government=government,
+        notable_features=notable_features,
+        npcs=npcs,
+        connections=connections,
+        notes=notes,
+    )
+    if not changes:
+        raise InvalidChangeError("Nothing to change: give at least one field.")
+    with store.transaction() as campaign:
+        location = world.update_location(campaign, name_or_id, changes)
+    return f"Updated location {location.name}: {', '.join(changes)}."
+
+
+@tool(annotations=READ_ONLY)
+def list_locations(store: CampaignStore = Depends(get_store)) -> str:
+    """List locations with their type."""
+    with store.reading() as campaign:
+        places = sorted(campaign.locations.values(), key=lambda loc: loc.name)
+        if not places:
+            return "No locations yet."
+        return "Locations:\n" + "\n".join(f"- {p.name} ({p.location_type})" for p in places)
+
+
+TOOLS: list[Callable[..., str]] = [create_location, get_location, update_location, list_locations]

dndkit/tools/npcs.py

@@ -0,0 +1,101 @@
+"""NPC tools."""
+
+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 world
+from dndkit.models import NPC, Attitude
+from dndkit.storage import CampaignStore
+from dndkit.tools import render
+from dndkit.tools.deps import READ_ONLY, NameOrId, get_store, provided
+
+Text = Annotated[str | None, Field(description="New value")]
+Description = Annotated[str | None, Field(description="Public description")]
+Bio = Annotated[str | None, Field(description="Private bio, secrets included")]
+NpcAttitude = Annotated[Attitude | None, Field(description="Attitude towards the party")]
+
+
+@tool
+def create_npc(
+    name: Annotated[str, Field(min_length=1, description="NPC name")],
+    description: Description = None,
+    bio: Bio = None,
+    race: Annotated[str | None, Field(description="Race or species")] = None,
+    occupation: Annotated[str | None, Field(description="Occupation")] = None,
+    location: Annotated[str | None, Field(description="Where the NPC is")] = None,
+    attitude: NpcAttitude = None,
+    notes: Annotated[str, Field(description="Notes")] = "",
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Create an NPC. The name must be new; use update_npc to change one."""
+    npc = NPC(
+        name=name.strip(),
+        description=description,
+        bio=bio,
+        race=race,
+        occupation=occupation,
+        location=location,
+        attitude=attitude,
+        notes=notes,
+    )
+    with store.transaction() as campaign:
+        world.create_npc(campaign, npc)
+    return f"Created NPC {npc.name} (id {npc.id})."
+
+
+@tool(annotations=READ_ONLY)
+def get_npc(name_or_id: NameOrId, store: CampaignStore = Depends(get_store)) -> str:
+    """An NPC's details, private bio included (for the game master only)."""
+    with store.reading() as campaign:
+        return render.npc(world.find_npc(campaign, name_or_id))
+
+
+@tool
+def update_npc(
+    name_or_id: NameOrId,
+    name: Annotated[str | None, Field(description="New name")] = None,
+    description: Description = None,
+    bio: Bio = None,
+    race: Text = None,
+    occupation: Text = None,
+    location: Text = None,
+    attitude: NpcAttitude = None,
+    notes: Text = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Change an NPC: attitude, location, notes, secrets..."""
+    changes = provided(
+        name=name,
+        description=description,
+        bio=bio,
+        race=race,
+        occupation=occupation,
+        location=location,
+        attitude=attitude,
+        notes=notes,
+    )
+    if not changes:
+        raise InvalidChangeError("Nothing to change: give at least one field.")
+    with store.transaction() as campaign:
+        npc = world.update_npc(campaign, name_or_id, changes)
+    return f"Updated NPC {npc.name}: {', '.join(changes)}."
+
+
+@tool(annotations=READ_ONLY)
+def list_npcs(store: CampaignStore = Depends(get_store)) -> str:
+    """List NPCs with where they are."""
+    with store.reading() as campaign:
+        npcs = sorted(campaign.npcs.values(), key=lambda n: n.name)
+        if not npcs:
+            return "No NPCs yet."
+        return "NPCs:\n" + "\n".join(
+            f"- {n.name}{f', at {n.location}' if n.location else ''}" for n in npcs
+        )
+
+
+TOOLS: list[Callable[..., str]] = [create_npc, get_npc, update_npc, list_npcs]

dndkit/tools/play.py

@@ -0,0 +1,118 @@
+"""Tools used at the table: game state, hit points and conditions."""
+
+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 effects
+from dndkit.models import now
+from dndkit.storage import CampaignStore
+from dndkit.tools import render
+from dndkit.tools.apps import PARTY_APP, app_meta
+from dndkit.tools.deps import READ_ONLY, get_store, provided
+
+Targets = Annotated[
+    list[str], Field(min_length=1, description="Characters or combatants, e.g. 'Goblin 2'")
+]
+Condition = Literal[
+    "blinded", "charmed", "deafened", "frightened", "grappled", "incapacitated", "invisible",
+    "paralyzed", "petrified", "poisoned", "prone", "restrained", "stunned", "unconscious",
+]  # fmt: skip
+
+
+@tool(annotations=READ_ONLY, meta=app_meta(PARTY_APP))
+def get_game_state(store: CampaignStore = Depends(get_store)) -> str:
+    """Where the party is: session, location, date, funds, party HP, quests, combat."""
+    with store.reading() as campaign:
+        return render.game_state(campaign, store.opened_at)
+
+
+@tool
+def update_game_state(
+    current_location: Annotated[str | None, Field(description="Party's location")] = None,
+    current_session: Annotated[int | None, Field(ge=1, description="Session number")] = None,
+    current_date_in_game: Annotated[str | None, Field(description="In-game date")] = None,
+    party_funds: Annotated[str | None, Field(description="Shared funds, e.g. '120 gp'")] = None,
+    notes: Annotated[str | None, Field(description="Current situation, replaces notes")] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Record where the party is, the date, the session, funds or the situation."""
+    changes = provided(
+        current_location=current_location,
+        current_session=current_session,
+        current_date_in_game=current_date_in_game,
+        party_funds=party_funds,
+        notes=notes,
+    )
+    if not changes:
+        raise InvalidChangeError("Nothing to change: give at least one field.")
+    with store.transaction() as campaign:
+        state = campaign.game_state
+        for field, value in changes.items():
+            setattr(state, field, value)
+        state.updated_at = now()
+    return f"Game state updated: {', '.join(changes)}."
+
+
+@tool
+def change_hit_points(
+    names: Targets,
+    amount: Annotated[int, Field(description="Negative for damage, positive for healing")],
+    temporary: Annotated[
+        bool, Field(description="Grant temporary HP instead (they don't stack)")
+    ] = False,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Damage or heal characters and monsters. Temporary HP absorb damage first; a monster
+    at 0 HP leaves the fight; a character at 0 HP falls unconscious."""
+    if amount == 0:
+        raise InvalidChangeError("The amount must not be 0.")
+    with store.transaction() as campaign:
+        if temporary:
+            if amount < 0:
+                raise InvalidChangeError(
+                    "Temporary hit points are granted with a positive amount."
+                )
+            return "\n".join(effects.grant_temporary_hp(campaign, names, amount))
+        return "\n".join(effects.change_hit_points(campaign, names, amount))
+
+
+@tool
+def set_condition(
+    names: Targets,
+    condition: Annotated[Condition, Field(description="5e condition")],
+    active: Annotated[bool, Field(description="false to remove it")] = True,
+    rounds: Annotated[
+        int | None, Field(ge=1, le=100, description="Ends after its Nth turn (1 minute: 10)")
+    ] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Add or remove a condition (poisoned, prone...) on characters or monsters. With
+    rounds, next_turn ends it at the end of the target's turn that many turns on."""
+    with store.transaction() as campaign:
+        return "\n".join(effects.set_condition(campaign, names, condition, active, rounds))
+
+
+@tool
+def set_concentration(
+    name: Annotated[str, Field(min_length=1, description="Character or monster")],
+    spell: Annotated[str | None, Field(description="The spell held; omit to end it")] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Concentrate on a spell (ending any other), or stop. Damage then asks for the
+    Constitution save; 0 HP or incapacitation ends it."""
+    with store.transaction() as campaign:
+        return effects.set_concentration(campaign, name, spell)
+
+
+TOOLS: list[Callable[..., str]] = [
+    get_game_state,
+    update_game_state,
+    change_hit_points,
+    set_condition,
+    set_concentration,
+]

dndkit/tools/players.py

@@ -0,0 +1,44 @@
+"""The table: who plays tonight, and which character each plays."""
+
+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 seating
+from dndkit.models import Seat, now
+from dndkit.storage import CampaignStore
+from dndkit.tools import render
+from dndkit.tools.apps import SEATING_APP, app_meta
+from dndkit.tools.deps import get_store
+
+
+@tool(meta=app_meta(SEATING_APP))
+def seat_players(
+    players: Annotated[
+        list[Seat] | None, Field(description="People sitting down, with their character")
+    ] = None,
+    leaving: Annotated[list[str] | None, Field(description="Players who left")] = None,
+    start_over: Annotated[
+        bool, Field(description="New session: forget who was here before")
+    ] = False,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Who is at the table and which character each plays (shown on screen).
+    Without arguments, just shows it."""
+    if not (players or leaving or start_over):
+        with store.reading() as campaign:
+            return render.table(campaign, store.opened_at)
+    with store.transaction() as campaign:
+        if start_over:
+            seating.clear(campaign)
+        notes = [seating.seat(campaign, s.player, s.character) for s in players or []]
+        for player in leaving or []:
+            seating.leave(campaign, player)
+        campaign.game_state.roll_call_at = now()
+        return "\n".join([*(note for note in notes if note), render.table(campaign)])
+
+
+TOOLS: list[Callable[..., str]] = [seat_players]

dndkit/tools/progression.py

@@ -0,0 +1,41 @@
+"""Progression tools: experience and levelling up."""
+
+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 progression
+from dndkit.storage import CampaignStore
+from dndkit.tools.deps import NameOrId, get_store
+
+
+@tool
+def award_experience(
+    total_xp: Annotated[int, Field(ge=1, description="XP to split, e.g. the monsters' total")],
+    names_or_ids: Annotated[
+        list[str] | None, Field(description="Who shares it; omit for the whole party")
+    ] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Split XP evenly and say who has enough for a new level."""
+    with store.transaction() as campaign:
+        return "\n".join(progression.award_experience(campaign, names_or_ids or [], total_xp))
+
+
+@tool
+def level_up(
+    name_or_id: NameOrId,
+    hit_die_roll: Annotated[
+        int | None, Field(ge=1, le=12, description="The hit die roll; omit for the average")
+    ] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Raise a character one level: HP (die + CON), proficiency, hit dice, spell slots."""
+    with store.transaction() as campaign:
+        return progression.level_up(campaign, name_or_id, hit_die_roll)
+
+
+TOOLS: list[Callable[..., str]] = [award_experience, level_up]

dndkit/tools/quests.py

@@ -0,0 +1,95 @@
+"""Quest tools."""
+
+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 world
+from dndkit.models import Quest, QuestStatus
+from dndkit.storage import CampaignStore
+from dndkit.tools import render
+from dndkit.tools.deps import READ_ONLY, NameOrId, get_store
+
+
+@tool
+def create_quest(
+    title: Annotated[str, Field(min_length=1, description="Quest title")],
+    description: Annotated[str, Field(description="What the quest is about")],
+    giver: Annotated[str | None, Field(description="Who gave it (NPC name)")] = None,
+    objectives: Annotated[list[str] | None, Field(description="Objectives, in order")] = None,
+    reward: Annotated[str | None, Field(description="Promised reward")] = None,
+    notes: Annotated[str, Field(description="Notes")] = "",
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Create an active quest. The title must be new."""
+    quest = Quest(
+        title=title.strip(),
+        description=description,
+        giver=giver,
+        objectives=objectives or [],
+        reward=reward,
+        notes=notes,
+    )
+    with store.transaction() as campaign:
+        world.create_quest(campaign, quest)
+    return f"Created quest '{quest.title}' with {len(quest.objectives)} objective(s)."
+
+
+@tool(annotations=READ_ONLY)
+def get_quest(title_or_id: NameOrId, store: CampaignStore = Depends(get_store)) -> str:
+    """A quest with its numbered objectives, each marked done or open."""
+    with store.reading() as campaign:
+        return render.quest(world.find_quest(campaign, title_or_id))
+
+
+@tool
+def update_quest(
+    title_or_id: NameOrId,
+    status: Annotated[QuestStatus | None, Field(description="New status")] = None,
+    complete_objective: Annotated[
+        str | None, Field(description="Objective done: its number (1, 2...) or its text")
+    ] = None,
+    add_objective: Annotated[str | None, Field(description="New objective to add")] = None,
+    notes: Annotated[str | None, Field(description="Replaces the notes")] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Change a quest's status, complete or add an objective, or rewrite its notes."""
+    if not any((status, complete_objective, add_objective, notes is not None)):
+        raise InvalidChangeError("Nothing to change: give at least one field.")
+    with store.transaction() as campaign:
+        quest, changes = world.update_quest(
+            campaign,
+            title_or_id,
+            status=status,
+            complete_objective=complete_objective,
+            add_objective=add_objective,
+            notes=notes,
+        )
+    return f"Quest '{quest.title}': {'; '.join(changes) or 'unchanged'}."
+
+
+@tool(annotations=READ_ONLY)
+def list_quests(
+    status: Annotated[
+        QuestStatus | None, Field(description="Only quests with this status")
+    ] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """List quests with their status and progress."""
+    with store.reading() as campaign:
+        quests = [q for q in campaign.quests.values() if status is None or q.status == status]
+        if not quests:
+            return f"No {status} quests." if status else "No quests yet."
+        rows = [
+            f"- {q.title} [{q.status}], "
+            f"{len(q.completed_objectives)}/{len(q.objectives)} objectives done"
+            for q in sorted(quests, key=lambda q: q.created_at)
+        ]
+        return "Quests:\n" + "\n".join(rows)
+
+
+TOOLS: list[Callable[..., str]] = [create_quest, get_quest, update_quest, list_quests]

dndkit/tools/recorder.py

@@ -0,0 +1,63 @@
+"""The middleware that writes every tool call and skill read to the activity log.
+
+The widgets' own data calls (``get_screen_data``, every second or two) are
+left out: they say nothing about what the model does.
+"""
+
+import json
+import time
+from typing import Any
+
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.base import ToolResult
+from mcp import types as mt
+
+from dndkit.activity import ActivityLog
+
+QUIET_TOOLS = frozenset({"get_screen_data"})
+
+
+class Recorder(Middleware):
+    """Records the model's calls in *log*."""
+
+    def __init__(self, log: ActivityLog) -> None:
+        self.log = log
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mt.CallToolRequestParams],
+        call_next: CallNext[mt.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        name = context.message.name
+        if name in QUIET_TOOLS:
+            return await call_next(context)
+        arguments = json.dumps(context.message.arguments or {}, ensure_ascii=False)
+        started = time.perf_counter()
+        try:
+            result = await call_next(context)
+        except Exception as exc:
+            self.log.record("tool", name, arguments, str(exc), True, started)
+            raise
+        self.log.record("tool", name, arguments, _text(result), False, started)
+        return result
+
+    async def on_read_resource(
+        self,
+        context: MiddlewareContext[mt.ReadResourceRequestParams],
+        call_next: CallNext[mt.ReadResourceRequestParams, Any],
+    ) -> Any:
+        uri = str(context.message.uri)
+        if not uri.startswith("skill://"):
+            return await call_next(context)
+        started = time.perf_counter()
+        try:
+            result = await call_next(context)
+        except Exception as exc:
+            self.log.record("skill", "resources/read", uri, str(exc), True, started)
+            raise
+        self.log.record("skill", "resources/read", uri, "read", False, started)
+        return result
+
+
+def _text(result: ToolResult) -> str:
+    return "\n".join(getattr(block, "text", "") for block in result.content)