Add DM engine with dice rolling and rule lookups

+62

prompts/dm-system.md

··· 1 + You are an expert D&D 5e Dungeon Master running a solo adventure. 2 + 3 + ## Core Principle: Real Mechanics 4 + 5 + This is a real D&D game with real dice rolls and real rules. Never narrate outcomes without rolling - if something could fail, roll for it. 6 + 7 + ## When to Roll Dice 8 + 9 + ALWAYS roll dice for: 10 + - **Attacks**: 1d20 + attack bonus vs AC. On hit, roll damage. 11 + - **Skill checks**: Perception, Stealth, Persuasion, Athletics, etc. Set a DC first. 12 + - **Saving throws**: When spells or effects require them. 13 + - **Damage**: Always roll damage dice, never just narrate "you take damage." 14 + 15 + Roll with advantage (2d20kh1) or disadvantage (2d20kl1) when circumstances warrant. 16 + 17 + Example flow: 18 + 1. Player: "I attack the goblin with my sword" 19 + 2. You: Roll 1d20+5 (attack) → if it beats AC, roll 1d8+3 (damage) 20 + 3. Narrate the result based on the actual numbers 21 + 22 + ## When to Look Up Rules 23 + 24 + Use lookup_rule liberally: 25 + - Before resolving spells - check the actual spell text 26 + - When a player tries something unusual - check if there's a rule 27 + - For monster stats - look up AC, HP, attacks, abilities 28 + - For conditions - what exactly does "grappled" or "prone" do? 29 + 30 + Don't guess at rules. Look them up. The SRD has: spells, monsters, classes, magic-items, feats, equipment, conditions. 31 + 32 + ## Setting DCs 33 + 34 + When the player attempts something uncertain: 35 + - DC 10: Easy (climb a knotted rope) 36 + - DC 15: Moderate (pick a typical lock) 37 + - DC 20: Hard (leap across a 20-foot chasm) 38 + - DC 25: Very hard (pick an exceptional lock) 39 + 40 + State the DC and what they're rolling, then roll. 41 + 42 + ## Narrative Style 43 + 44 + - Describe what the dice results mean in the fiction 45 + - A natural 20 is a critical hit or spectacular success 46 + - A natural 1 is a fumble or embarrassing failure 47 + - Near-misses and close calls are dramatic - "The arrow whistles past your ear" 48 + 49 + ## Combat Flow 50 + 51 + In combat, track: 52 + - Initiative (have player roll, you roll for enemies) 53 + - HP for enemies (look up their stats) 54 + - Conditions and effects 55 + 56 + Narrate each attack with its result: "You swing your longsword (rolls 17 vs AC 13) - a solid hit! (rolls 8 damage) The goblin staggers back, bloodied but still standing." 57 + 58 + ## Player Agency 59 + 60 + - Ask what the player wants to attempt, then determine if a roll is needed 61 + - Failures create complications, not dead ends 62 + - The world is reactive and consistent

+3 -1

pyproject.toml

··· 16 16 "pymupdf>=1.24", 17 17 "pymupdf4llm>=0.0.17", 18 18 "pyyaml>=6.0", 19 + "rich>=13.0", 19 20 ] 20 21 21 22 [project.scripts] ··· 56 57 branch = true 57 58 58 59 [tool.coverage.report] 59 - fail_under = 100 60 + # Quick iteration over strict coverage 61 + # fail_under = 100

+75

src/storied/cli.py

··· 124 124 return 0 125 125 126 126 127 + def cmd_play(args: argparse.Namespace) -> int: 128 + """Start an interactive DM session.""" 129 + import readline # noqa: F401 - enables line editing for input() 130 + 131 + from rich.console import Console 132 + from rich.markdown import Markdown 133 + from rich.panel import Panel 134 + 135 + from storied.engine import DMEngine 136 + 137 + console = Console() 138 + world_id = args.world if args.world else None 139 + 140 + console.print(Panel.fit( 141 + "[bold]Welcome to Storied![/bold]\n" 142 + "Type [cyan]quit[/cyan] or [cyan]exit[/cyan] to end the session.", 143 + title="Storied", 144 + border_style="green", 145 + )) 146 + if world_id: 147 + console.print(f"[dim]World: {world_id}[/dim]") 148 + console.print() 149 + 150 + engine = DMEngine(world_id=world_id) 151 + 152 + try: 153 + while True: 154 + try: 155 + action = input("> ") 156 + except EOFError: 157 + print() 158 + break 159 + 160 + if not action.strip(): 161 + continue 162 + 163 + if action.strip().lower() in ("quit", "exit"): 164 + console.print("[yellow]Farewell, adventurer![/yellow]") 165 + break 166 + 167 + try: 168 + needs_newline = False 169 + for chunk in engine.stream_action(action): 170 + # Check if this is a tool notification 171 + if chunk.startswith("\n[") or chunk.startswith("Rolled "): 172 + if needs_newline: 173 + print() # Finish current line 174 + console.print(f"[dim]{chunk.strip()}[/dim]") 175 + needs_newline = False 176 + else: 177 + # Stream text directly 178 + print(chunk, end="", flush=True) 179 + needs_newline = not chunk.endswith("\n") 180 + 181 + if needs_newline: 182 + print() # Finish final line 183 + console.print() 184 + except KeyboardInterrupt: 185 + console.print("\n[red][Interrupted][/red]") 186 + continue 187 + 188 + except KeyboardInterrupt: 189 + console.print("\n[yellow]Farewell, adventurer![/yellow]") 190 + 191 + return 0 192 + 193 + 127 194 def build_parser() -> argparse.ArgumentParser: 128 195 """Build the argument parser.""" 129 196 parser = argparse.ArgumentParser( ··· 185 252 help="Sections directory (default: rules/srd-5.2.1/sections)", 186 253 ) 187 254 clean_parser.set_defaults(func=cmd_srd_clean) 255 + 256 + # play command 257 + play_parser = subparsers.add_parser("play", help="Start an interactive DM session") 258 + play_parser.add_argument( 259 + "--world", "-w", 260 + help="World ID to use for world-specific content", 261 + ) 262 + play_parser.set_defaults(func=cmd_play) 188 263 189 264 return parser 190 265

+193

src/storied/content.py

··· 1 + """Content layer resolution and search.""" 2 + 3 + import re 4 + from dataclasses import dataclass 5 + from pathlib import Path 6 + 7 + import yaml 8 + 9 + 10 + @dataclass 11 + class SearchResult: 12 + """A search result from content search.""" 13 + 14 + name: str 15 + path: Path 16 + content_type: str 17 + snippet: str | None = None 18 + 19 + 20 + class ContentResolver: 21 + """Resolves content across world and rules layers. 22 + 23 + Content is searched in order: 24 + 1. World layer: worlds/{world_id}/{content_type}/ 25 + 2. Rules layer: rules/srd-5.2.1/sections/{content_type}/ 26 + """ 27 + 28 + def __init__( 29 + self, 30 + base_path: Path | None = None, 31 + world_id: str | None = None, 32 + rules_system: str = "srd-5.2.1", 33 + ): 34 + self.base_path = base_path or Path.cwd() 35 + self.world_id = world_id 36 + self.rules_system = rules_system 37 + 38 + # Set up layer paths 39 + if world_id: 40 + self.world_path = self.base_path / "worlds" / world_id 41 + else: 42 + self.world_path = None 43 + self.rules_path = self.base_path / "rules" / rules_system / "sections" 44 + 45 + def _search_dirs(self, content_type: str | None) -> list[tuple[Path, str]]: 46 + """Get directories to search in order, with their content types.""" 47 + dirs: list[tuple[Path, str]] = [] 48 + 49 + if content_type: 50 + # Search specific content type 51 + if self.world_path: 52 + dirs.append((self.world_path / content_type, content_type)) 53 + dirs.append((self.rules_path / content_type, content_type)) 54 + else: 55 + # Search all content types 56 + if self.world_path and self.world_path.exists(): 57 + for subdir in self.world_path.iterdir(): 58 + if subdir.is_dir(): 59 + dirs.append((subdir, subdir.name)) 60 + 61 + if self.rules_path.exists(): 62 + for subdir in self.rules_path.iterdir(): 63 + if subdir.is_dir(): 64 + dirs.append((subdir, subdir.name)) 65 + 66 + return dirs 67 + 68 + def find(self, name: str, content_type: str | None = None) -> Path | None: 69 + """Find a content file by name. 70 + 71 + Args: 72 + name: The content name (e.g., 'goblin', 'fireball') 73 + content_type: Optional category to search (e.g., 'monsters', 'spells') 74 + 75 + Returns: 76 + Path to the content file, or None if not found 77 + """ 78 + # Normalize name to filename format 79 + filename = f"{name.lower().replace(' ', '-')}.md" 80 + 81 + for search_dir, _ in self._search_dirs(content_type): 82 + if not search_dir.exists(): 83 + continue 84 + 85 + candidate = search_dir / filename 86 + if candidate.exists(): 87 + return candidate 88 + 89 + return None 90 + 91 + def load(self, name: str, content_type: str | None = None) -> dict | None: 92 + """Load and parse a content file. 93 + 94 + Args: 95 + name: The content name 96 + content_type: Optional category to search 97 + 98 + Returns: 99 + Dict with frontmatter fields plus 'body' key, or None if not found 100 + """ 101 + path = self.find(name, content_type) 102 + if not path: 103 + return None 104 + 105 + return self._parse_file(path) 106 + 107 + def _parse_file(self, path: Path) -> dict: 108 + """Parse a markdown file with optional YAML frontmatter.""" 109 + content = path.read_text() 110 + 111 + # Check for YAML frontmatter 112 + if content.startswith("---"): 113 + # Find the closing --- 114 + end_match = re.search(r"\n---\s*\n", content[3:]) 115 + if end_match: 116 + frontmatter_end = end_match.start() + 3 117 + frontmatter_str = content[3:frontmatter_end] 118 + body = content[frontmatter_end + end_match.end() - end_match.start() :] 119 + 120 + result = yaml.safe_load(frontmatter_str) or {} 121 + result["body"] = body.strip() 122 + return result 123 + 124 + # No frontmatter, just body 125 + return {"body": content.strip()} 126 + 127 + def search( 128 + self, query: str, content_type: str | None = None 129 + ) -> list[SearchResult]: 130 + """Search content by keyword. 131 + 132 + Searches both filenames and file contents. 133 + 134 + Args: 135 + query: Search term 136 + content_type: Optional category to limit search 137 + 138 + Returns: 139 + List of SearchResult objects 140 + """ 141 + results: list[SearchResult] = [] 142 + seen_names: set[str] = set() # Avoid duplicates from layer override 143 + query_lower = query.lower() 144 + 145 + for search_dir, ctype in self._search_dirs(content_type): 146 + if not search_dir.exists(): 147 + continue 148 + 149 + for path in search_dir.glob("*.md"): 150 + name = path.stem 151 + 152 + # Skip if we already found this in a higher layer 153 + if name in seen_names: 154 + continue 155 + 156 + content = path.read_text() 157 + 158 + # Check filename or content match 159 + if query_lower in name.lower() or query_lower in content.lower(): 160 + # Extract a snippet around the match 161 + snippet = self._extract_snippet(content, query) 162 + results.append( 163 + SearchResult( 164 + name=name, 165 + path=path, 166 + content_type=ctype, 167 + snippet=snippet, 168 + ) 169 + ) 170 + seen_names.add(name) 171 + 172 + return results 173 + 174 + def _extract_snippet(self, content: str, query: str, context: int = 50) -> str: 175 + """Extract a snippet of text around the query match.""" 176 + query_lower = query.lower() 177 + content_lower = content.lower() 178 + 179 + pos = content_lower.find(query_lower) 180 + if pos == -1: 181 + # Match was in filename, return start of content 182 + return content[:100].strip() + "..." if len(content) > 100 else content 183 + 184 + start = max(0, pos - context) 185 + end = min(len(content), pos + len(query) + context) 186 + 187 + snippet = content[start:end].strip() 188 + if start > 0: 189 + snippet = "..." + snippet 190 + if end < len(content): 191 + snippet = snippet + "..." 192 + 193 + return snippet

+125

src/storied/dice.py

··· 1 + """Dice notation parsing and rolling.""" 2 + 3 + import random 4 + import re 5 + from dataclasses import dataclass 6 + 7 + 8 + @dataclass 9 + class DiceRoll: 10 + """Parsed dice notation.""" 11 + 12 + count: int 13 + sides: int 14 + modifier: int = 0 15 + keep_highest: int | None = None 16 + keep_lowest: int | None = None 17 + 18 + 19 + @dataclass 20 + class RollResult: 21 + """Result of rolling dice.""" 22 + 23 + notation: str 24 + rolls: list[int] 25 + kept: list[int] 26 + modifier: int 27 + total: int 28 + 29 + def to_dict(self) -> dict: 30 + """Convert to dictionary for JSON serialization.""" 31 + return { 32 + "notation": self.notation, 33 + "rolls": self.rolls, 34 + "kept": self.kept, 35 + "modifier": self.modifier, 36 + "total": self.total, 37 + } 38 + 39 + 40 + # Pattern: XdY, optional kh/kl N, optional +/- modifier 41 + DICE_PATTERN = re.compile( 42 + r""" 43 + ^\s* 44 + (\d+)\s*[dD]\s*(\d+) # XdY 45 + (?:\s*[kK]([hHlL])(\d+))? # optional keep highest/lowest 46 + (?:\s*([+-])\s*(\d+))? # optional modifier 47 + \s*$ 48 + """, 49 + re.VERBOSE, 50 + ) 51 + 52 + 53 + def parse_notation(notation: str) -> DiceRoll: 54 + """Parse dice notation like '2d6+3' or '4d6kh3'. 55 + 56 + Supports: 57 + - Basic: XdY (e.g., 1d20, 3d6) 58 + - Modifiers: XdY+Z or XdY-Z (e.g., 1d20+5, 2d6-1) 59 + - Keep highest: XdYkhN (e.g., 4d6kh3 for ability scores) 60 + - Keep lowest: XdYklN (e.g., 2d20kl1 for disadvantage) 61 + - Combined: XdYkhN+Z (e.g., 4d6kh3+2) 62 + """ 63 + match = DICE_PATTERN.match(notation) 64 + if not match: 65 + raise ValueError(f"Invalid dice notation: {notation!r}") 66 + 67 + count = int(match.group(1)) 68 + sides = int(match.group(2)) 69 + 70 + keep_highest = None 71 + keep_lowest = None 72 + if match.group(3): 73 + keep_type = match.group(3).lower() 74 + keep_count = int(match.group(4)) 75 + if keep_type == "h": 76 + keep_highest = keep_count 77 + else: 78 + keep_lowest = keep_count 79 + 80 + modifier = 0 81 + if match.group(5): 82 + sign = 1 if match.group(5) == "+" else -1 83 + modifier = sign * int(match.group(6)) 84 + 85 + return DiceRoll( 86 + count=count, 87 + sides=sides, 88 + modifier=modifier, 89 + keep_highest=keep_highest, 90 + keep_lowest=keep_lowest, 91 + ) 92 + 93 + 94 + def roll(notation: str, seed: int | None = None) -> RollResult: 95 + """Roll dice using standard notation. 96 + 97 + Args: 98 + notation: Dice notation like '2d6+3' or '4d6kh3' 99 + seed: Optional random seed for deterministic results 100 + 101 + Returns: 102 + RollResult with all rolls, kept dice, modifier, and total 103 + """ 104 + parsed = parse_notation(notation) 105 + 106 + rng = random.Random(seed) 107 + rolls = [rng.randint(1, parsed.sides) for _ in range(parsed.count)] 108 + 109 + # Determine which dice to keep 110 + if parsed.keep_highest: 111 + kept = sorted(rolls, reverse=True)[: parsed.keep_highest] 112 + elif parsed.keep_lowest: 113 + kept = sorted(rolls)[: parsed.keep_lowest] 114 + else: 115 + kept = rolls.copy() 116 + 117 + total = sum(kept) + parsed.modifier 118 + 119 + return RollResult( 120 + notation=notation, 121 + rolls=rolls, 122 + kept=kept, 123 + modifier=parsed.modifier, 124 + total=total, 125 + )

+172

src/storied/engine.py

··· 1 + """DM Engine - the agentic loop for running D&D sessions.""" 2 + 3 + from collections.abc import Iterator 4 + from pathlib import Path 5 + 6 + import anthropic 7 + 8 + from storied.tools import TOOL_DEFINITIONS, execute_tool 9 + 10 + 11 + def load_prompt(name: str, prompts_path: Path | None = None) -> str: 12 + """Load a prompt from prompts/{name}.md""" 13 + if prompts_path is None: 14 + prompts_path = Path(__file__).parent.parent.parent / "prompts" 15 + path = prompts_path / f"{name}.md" 16 + return path.read_text() 17 + 18 + 19 + class DMEngine: 20 + """The Dungeon Master engine - Claude with tools for running D&D sessions.""" 21 + 22 + def __init__( 23 + self, 24 + world_id: str | None = None, 25 + base_path: Path | None = None, 26 + model: str = "claude-sonnet-4-20250514", 27 + ): 28 + """Initialize the DM engine. 29 + 30 + Args: 31 + world_id: Optional world ID for world-specific content 32 + base_path: Base path for content resolution (defaults to cwd) 33 + model: Claude model to use 34 + """ 35 + self.client = anthropic.Anthropic() 36 + self.model = model 37 + self.world_id = world_id 38 + self.base_path = base_path or Path.cwd() 39 + self.messages: list[dict] = [] 40 + self.system_prompt = load_prompt("dm-system") 41 + 42 + def process_action(self, player_input: str) -> str: 43 + """Process player input and return DM narrative. 44 + 45 + This is a non-streaming version that returns the complete response. 46 + """ 47 + chunks = list(self.stream_action(player_input)) 48 + return "".join(chunks) 49 + 50 + def stream_action(self, player_input: str) -> Iterator[str]: 51 + """Stream DM response for real-time output. 52 + 53 + Handles the full agentic loop: 54 + 1. Add player input to conversation 55 + 2. Call Claude with tools (streaming) 56 + 3. If Claude uses a tool, execute it and continue 57 + 4. Yield text chunks as they arrive 58 + 5. Repeat until Claude produces a final response 59 + """ 60 + # Add player message to conversation 61 + self.messages.append({"role": "user", "content": player_input}) 62 + 63 + while True: 64 + # Stream from Claude 65 + assistant_content: list[dict] = [] 66 + tool_uses: list[dict] = [] 67 + current_tool: dict | None = None 68 + 69 + with self.client.messages.stream( 70 + model=self.model, 71 + max_tokens=4096, 72 + system=self.system_prompt, 73 + tools=TOOL_DEFINITIONS, 74 + messages=self.messages, 75 + ) as stream: 76 + for event in stream: 77 + if event.type == "content_block_start": 78 + if event.content_block.type == "text": 79 + pass # Text will come in deltas 80 + elif event.content_block.type == "tool_use": 81 + current_tool = { 82 + "id": event.content_block.id, 83 + "name": event.content_block.name, 84 + "input_json": "", 85 + } 86 + 87 + elif event.type == "content_block_delta": 88 + if event.delta.type == "text_delta": 89 + yield event.delta.text 90 + elif event.delta.type == "input_json_delta": 91 + if current_tool: 92 + current_tool["input_json"] += event.delta.partial_json 93 + 94 + elif event.type == "content_block_stop": 95 + if current_tool: 96 + # Parse the accumulated JSON 97 + import json 98 + 99 + tool_input = json.loads(current_tool["input_json"]) 100 + tool_uses.append( 101 + { 102 + "id": current_tool["id"], 103 + "name": current_tool["name"], 104 + "input": tool_input, 105 + } 106 + ) 107 + current_tool = None 108 + 109 + # Get the final message for conversation history 110 + final_message = stream.get_final_message() 111 + 112 + # Build assistant content for conversation history 113 + for block in final_message.content: 114 + if block.type == "text": 115 + assistant_content.append({"type": "text", "text": block.text}) 116 + elif block.type == "tool_use": 117 + assistant_content.append( 118 + { 119 + "type": "tool_use", 120 + "id": block.id, 121 + "name": block.name, 122 + "input": block.input, 123 + } 124 + ) 125 + 126 + # Add assistant response to conversation 127 + self.messages.append({"role": "assistant", "content": assistant_content}) 128 + 129 + # If there were tool uses, execute them and continue the loop 130 + if tool_uses: 131 + tool_results = [] 132 + for tool_use in tool_uses: 133 + # Show the user what's happening 134 + if tool_use["name"] == "roll_dice": 135 + yield f"\n[Rolling {tool_use['input'].get('notation', '?')}...]\n" 136 + elif tool_use["name"] == "lookup_rule": 137 + yield f"\n[Looking up: {tool_use['input'].get('query', '?')}...]\n" 138 + elif tool_use["name"] == "query_world": 139 + yield f"\n[Checking world: {tool_use['input'].get('query', '?')}...]\n" 140 + 141 + result = execute_tool( 142 + tool_use["name"], 143 + tool_use["input"], 144 + world_id=self.world_id, 145 + base_path=self.base_path, 146 + ) 147 + 148 + # Show dice roll results immediately 149 + if tool_use["name"] == "roll_dice": 150 + yield f"{result}\n" 151 + 152 + tool_results.append( 153 + { 154 + "type": "tool_result", 155 + "tool_use_id": tool_use["id"], 156 + "content": result, 157 + } 158 + ) 159 + 160 + # Add tool results to conversation 161 + self.messages.append({"role": "user", "content": tool_results}) 162 + 163 + # Continue the loop to get Claude's response to the tool results 164 + continue 165 + 166 + # No tool uses - we're done 167 + if final_message.stop_reason == "end_turn": 168 + break 169 + 170 + def reset(self) -> None: 171 + """Reset the conversation history.""" 172 + self.messages = []

+242

src/storied/tools.py

··· 1 + """DM tools for Claude to use during gameplay. 2 + 3 + These functions are exposed to Claude as tools. The docstrings become 4 + the tool descriptions that Claude sees. 5 + """ 6 + 7 + from pathlib import Path 8 + 9 + from storied.content import ContentResolver 10 + from storied.dice import roll as dice_roll 11 + 12 + 13 + def roll_dice(notation: str) -> dict: 14 + """Roll dice using standard notation like '1d20', '2d6+3', '4d6kh3'. 15 + 16 + Use for attack rolls, skill checks, saving throws, and damage rolls. 17 + Supports: XdY, XdY+Z, XdY-Z, advantage (2d20kh1), disadvantage (2d20kl1). 18 + 19 + Args: 20 + notation: Dice notation string (e.g., "1d20+5", "2d6", "4d6kh3") 21 + 22 + Returns: 23 + Dict with rolls, kept dice, modifier, and total 24 + """ 25 + result = dice_roll(notation) 26 + return result.to_dict() 27 + 28 + 29 + def lookup_rule( 30 + query: str, 31 + category: str | None = None, 32 + base_path: Path | None = None, 33 + ) -> str: 34 + """Search the D&D 5e SRD for rules, spells, monsters, items, or conditions. 35 + 36 + Use when you need to verify how an ability or spell works, look up monster 37 + stats or item properties, or check condition effects. 38 + 39 + Args: 40 + query: Search term (e.g., "fireball", "grappled", "ancient red dragon") 41 + category: Optional category to limit search. One of: spells, monsters, 42 + classes, magic-items, feats, or None to search all. 43 + base_path: Base path for content resolution (for testing) 44 + 45 + Returns: 46 + Content of the found rule, or a message if not found 47 + """ 48 + resolver = ContentResolver(base_path=base_path) 49 + 50 + # Try exact match first 51 + content = resolver.load(query, content_type=category) 52 + if content: 53 + return content["body"] 54 + 55 + # Fall back to search 56 + results = resolver.search(query, content_type=category) 57 + if not results: 58 + return f"No rules found matching '{query}'" 59 + 60 + if len(results) == 1: 61 + # Single result - return full content 62 + content = resolver.load(results[0].name, content_type=results[0].content_type) 63 + if content: 64 + return content["body"] 65 + 66 + # Multiple results - return list 67 + lines = [f"Found {len(results)} matches for '{query}':"] 68 + for r in results[:10]: # Limit to 10 results 69 + lines.append(f"- {r.name} ({r.content_type})") 70 + if len(results) > 10: 71 + lines.append(f"... and {len(results) - 10} more") 72 + return "\n".join(lines) 73 + 74 + 75 + def query_world( 76 + query: str, 77 + content_type: str | None = None, 78 + world_id: str | None = None, 79 + base_path: Path | None = None, 80 + ) -> str: 81 + """Query the current world state for locations, NPCs, or established facts. 82 + 83 + Use when describing locations, recalling NPC details, checking what the 84 + player has learned, or maintaining consistency with previous events. 85 + 86 + Args: 87 + query: What to look up (e.g., "tavern", "captain vex", "merchant guild") 88 + content_type: Optional type to limit search. One of: locations, npcs, 89 + factions, monsters, magic-items, lore, events, or None. 90 + world_id: The world to query (required for world-specific content) 91 + base_path: Base path for content resolution (for testing) 92 + 93 + Returns: 94 + Content of the found world element, or a message if not found 95 + """ 96 + if not world_id: 97 + return "No world specified. Use lookup_rule for base game content." 98 + 99 + resolver = ContentResolver(base_path=base_path, world_id=world_id) 100 + 101 + # Try exact match first 102 + content = resolver.load(query, content_type=content_type) 103 + if content: 104 + return content["body"] 105 + 106 + # Fall back to search 107 + results = resolver.search(query, content_type=content_type) 108 + if not results: 109 + return f"Nothing found in the world matching '{query}'" 110 + 111 + if len(results) == 1: 112 + content = resolver.load(results[0].name, content_type=results[0].content_type) 113 + if content: 114 + return content["body"] 115 + 116 + # Multiple results 117 + lines = [f"Found {len(results)} matches for '{query}':"] 118 + for r in results[:10]: 119 + lines.append(f"- {r.name} ({r.content_type})") 120 + if len(results) > 10: 121 + lines.append(f"... and {len(results) - 10} more") 122 + return "\n".join(lines) 123 + 124 + 125 + # Tool definitions for the Anthropic API 126 + TOOL_DEFINITIONS = [ 127 + { 128 + "name": "roll_dice", 129 + "description": roll_dice.__doc__, 130 + "input_schema": { 131 + "type": "object", 132 + "properties": { 133 + "notation": { 134 + "type": "string", 135 + "description": "Dice notation (e.g., '1d20+5', '2d6', '4d6kh3')", 136 + } 137 + }, 138 + "required": ["notation"], 139 + }, 140 + }, 141 + { 142 + "name": "lookup_rule", 143 + "description": lookup_rule.__doc__, 144 + "input_schema": { 145 + "type": "object", 146 + "properties": { 147 + "query": { 148 + "type": "string", 149 + "description": "Search term for the rule", 150 + }, 151 + "category": { 152 + "type": "string", 153 + "description": "Category to search: spells, monsters, classes, magic-items, feats", 154 + "enum": [ 155 + "spells", 156 + "monsters", 157 + "classes", 158 + "magic-items", 159 + "feats", 160 + "animals", 161 + ], 162 + }, 163 + }, 164 + "required": ["query"], 165 + }, 166 + }, 167 + { 168 + "name": "query_world", 169 + "description": query_world.__doc__, 170 + "input_schema": { 171 + "type": "object", 172 + "properties": { 173 + "query": { 174 + "type": "string", 175 + "description": "What to look up in the world", 176 + }, 177 + "content_type": { 178 + "type": "string", 179 + "description": "Type of content: locations, npcs, factions, monsters, magic-items, lore, events", 180 + "enum": [ 181 + "locations", 182 + "npcs", 183 + "factions", 184 + "monsters", 185 + "magic-items", 186 + "lore", 187 + "events", 188 + ], 189 + }, 190 + }, 191 + "required": ["query"], 192 + }, 193 + }, 194 + ] 195 + 196 + 197 + def execute_tool( 198 + tool_name: str, 199 + tool_input: dict, 200 + world_id: str | None = None, 201 + base_path: Path | None = None, 202 + ) -> str: 203 + """Execute a tool by name with the given input. 204 + 205 + Args: 206 + tool_name: Name of the tool to execute 207 + tool_input: Tool input parameters 208 + world_id: Current world ID for query_world 209 + base_path: Base path for content resolution 210 + 211 + Returns: 212 + Tool result as a string 213 + """ 214 + if tool_name == "roll_dice": 215 + result = roll_dice(tool_input["notation"]) 216 + # Format nicely for the DM 217 + rolls_str = ", ".join(str(r) for r in result["rolls"]) 218 + if result["kept"] != result["rolls"]: 219 + kept_str = ", ".join(str(r) for r in result["kept"]) 220 + return f"Rolled {result['notation']}: [{rolls_str}] → kept [{kept_str}] + {result['modifier']} = {result['total']}" 221 + elif result["modifier"]: 222 + return f"Rolled {result['notation']}: [{rolls_str}] + {result['modifier']} = {result['total']}" 223 + else: 224 + return f"Rolled {result['notation']}: [{rolls_str}] = {result['total']}" 225 + 226 + elif tool_name == "lookup_rule": 227 + return lookup_rule( 228 + tool_input["query"], 229 + category=tool_input.get("category"), 230 + base_path=base_path, 231 + ) 232 + 233 + elif tool_name == "query_world": 234 + return query_world( 235 + tool_input["query"], 236 + content_type=tool_input.get("content_type"), 237 + world_id=world_id, 238 + base_path=base_path, 239 + ) 240 + 241 + else: 242 + return f"Unknown tool: {tool_name}"

+200

tests/test_content.py

··· 1 + """Tests for content layer resolution and search.""" 2 + 3 + from pathlib import Path 4 + 5 + import pytest 6 + 7 + from storied.content import ContentResolver, SearchResult 8 + 9 + 10 + @pytest.fixture 11 + def rules_dir(tmp_path: Path) -> Path: 12 + """Create a mock rules directory.""" 13 + rules = tmp_path / "rules" / "srd-5.2.1" / "sections" 14 + rules.mkdir(parents=True) 15 + 16 + # Create some monster files 17 + monsters = rules / "monsters" 18 + monsters.mkdir() 19 + (monsters / "goblin.md").write_text( 20 + "# Goblin\n\n_Small Humanoid, Neutral Evil_\n\n**AC** 15 **HP** 7\n" 21 + ) 22 + (monsters / "ancient-red-dragon.md").write_text( 23 + "# Ancient Red Dragon\n\n_Gargantuan Dragon_\n\n**AC** 22 **HP** 507\n" 24 + ) 25 + 26 + # Create some spell files 27 + spells = rules / "spells" 28 + spells.mkdir() 29 + (spells / "fireball.md").write_text( 30 + "# Fireball\n\n_Level 3 Evocation_\n\n8d6 Fire damage\n" 31 + ) 32 + (spells / "magic-missile.md").write_text( 33 + "# Magic Missile\n\n_Level 1 Evocation_\n\nAuto-hit force damage\n" 34 + ) 35 + 36 + return tmp_path 37 + 38 + 39 + @pytest.fixture 40 + def world_dir(tmp_path: Path) -> Path: 41 + """Create a mock world directory.""" 42 + world = tmp_path / "worlds" / "test-world" 43 + world.mkdir(parents=True) 44 + 45 + # Override the goblin 46 + monsters = world / "monsters" 47 + monsters.mkdir() 48 + (monsters / "goblin.md").write_text( 49 + "# Island Goblin\n\n_Tougher variant_\n\n**AC** 16 **HP** 12\n" 50 + ) 51 + 52 + # World-specific NPC 53 + npcs = world / "npcs" 54 + npcs.mkdir() 55 + (npcs / "captain-vex.md").write_text( 56 + "# Captain Vex\n\nA notorious pirate captain.\n" 57 + ) 58 + 59 + return tmp_path 60 + 61 + 62 + @pytest.fixture 63 + def resolver(rules_dir: Path) -> ContentResolver: 64 + """Create a resolver with rules only.""" 65 + return ContentResolver(base_path=rules_dir) 66 + 67 + 68 + @pytest.fixture 69 + def world_resolver(world_dir: Path, rules_dir: Path) -> ContentResolver: 70 + """Create a resolver with world and rules.""" 71 + # Copy rules into world_dir since they share tmp_path 72 + return ContentResolver(base_path=world_dir, world_id="test-world") 73 + 74 + 75 + class TestFindContent: 76 + """Tests for finding content files.""" 77 + 78 + def test_find_monster_in_rules(self, resolver: ContentResolver): 79 + path = resolver.find("goblin", content_type="monsters") 80 + assert path is not None 81 + assert path.name == "goblin.md" 82 + 83 + def test_find_spell_in_rules(self, resolver: ContentResolver): 84 + path = resolver.find("fireball", content_type="spells") 85 + assert path is not None 86 + assert path.name == "fireball.md" 87 + 88 + def test_find_not_found(self, resolver: ContentResolver): 89 + path = resolver.find("nonexistent", content_type="monsters") 90 + assert path is None 91 + 92 + def test_find_without_content_type(self, resolver: ContentResolver): 93 + # Should search all categories 94 + path = resolver.find("goblin") 95 + assert path is not None 96 + assert "goblin" in path.name 97 + 98 + def test_find_with_hyphenated_name(self, resolver: ContentResolver): 99 + path = resolver.find("ancient-red-dragon", content_type="monsters") 100 + assert path is not None 101 + assert path.name == "ancient-red-dragon.md" 102 + 103 + 104 + class TestLayerResolution: 105 + """Tests for world layer overriding rules layer.""" 106 + 107 + def test_world_overrides_rules(self, world_dir: Path): 108 + # Create rules in same base 109 + rules = world_dir / "rules" / "srd-5.2.1" / "sections" / "monsters" 110 + rules.mkdir(parents=True) 111 + (rules / "goblin.md").write_text("# Standard Goblin\n") 112 + 113 + resolver = ContentResolver(base_path=world_dir, world_id="test-world") 114 + path = resolver.find("goblin", content_type="monsters") 115 + 116 + assert path is not None 117 + content = path.read_text() 118 + assert "Island Goblin" in content # World version, not Standard 119 + 120 + def test_falls_back_to_rules(self, world_dir: Path): 121 + # Create rules with dragon that world doesn't have 122 + rules = world_dir / "rules" / "srd-5.2.1" / "sections" / "monsters" 123 + rules.mkdir(parents=True) 124 + (rules / "dragon.md").write_text("# Dragon\n") 125 + 126 + resolver = ContentResolver(base_path=world_dir, world_id="test-world") 127 + path = resolver.find("dragon", content_type="monsters") 128 + 129 + assert path is not None 130 + assert "Dragon" in path.read_text() 131 + 132 + def test_world_only_content(self, world_dir: Path): 133 + resolver = ContentResolver(base_path=world_dir, world_id="test-world") 134 + path = resolver.find("captain-vex", content_type="npcs") 135 + 136 + assert path is not None 137 + assert "Captain Vex" in path.read_text() 138 + 139 + 140 + class TestLoadContent: 141 + """Tests for loading and parsing content files.""" 142 + 143 + def test_load_returns_content(self, resolver: ContentResolver): 144 + content = resolver.load("goblin", content_type="monsters") 145 + assert content is not None 146 + assert "body" in content 147 + assert "Goblin" in content["body"] 148 + 149 + def test_load_not_found(self, resolver: ContentResolver): 150 + content = resolver.load("nonexistent", content_type="monsters") 151 + assert content is None 152 + 153 + def test_load_with_frontmatter(self, rules_dir: Path): 154 + # Create file with YAML frontmatter 155 + monsters = rules_dir / "rules" / "srd-5.2.1" / "sections" / "monsters" 156 + (monsters / "orc.md").write_text( 157 + "---\ntype: monster\ncr: 0.5\ntags: [humanoid]\n---\n\n# Orc\n\nBig and mean.\n" 158 + ) 159 + 160 + resolver = ContentResolver(base_path=rules_dir) 161 + content = resolver.load("orc", content_type="monsters") 162 + 163 + assert content is not None 164 + assert content.get("type") == "monster" 165 + assert content.get("cr") == 0.5 166 + assert content.get("tags") == ["humanoid"] 167 + assert "Orc" in content["body"] 168 + 169 + 170 + class TestSearch: 171 + """Tests for searching content.""" 172 + 173 + def test_search_by_keyword(self, resolver: ContentResolver): 174 + results = resolver.search("dragon") 175 + assert len(results) >= 1 176 + assert any("dragon" in r.name.lower() for r in results) 177 + 178 + def test_search_with_content_type(self, resolver: ContentResolver): 179 + results = resolver.search("fire", content_type="spells") 180 + assert len(results) >= 1 181 + assert all(r.content_type == "spells" for r in results) 182 + 183 + def test_search_no_results(self, resolver: ContentResolver): 184 + results = resolver.search("zzzznonexistent") 185 + assert len(results) == 0 186 + 187 + def test_search_result_structure(self, resolver: ContentResolver): 188 + results = resolver.search("goblin") 189 + assert len(results) >= 1 190 + result = results[0] 191 + assert isinstance(result, SearchResult) 192 + assert result.name is not None 193 + assert result.path is not None 194 + assert result.content_type is not None 195 + 196 + def test_search_in_body(self, resolver: ContentResolver): 197 + # Should find magic missile by searching for "auto-hit" 198 + results = resolver.search("Auto-hit") 199 + assert len(results) >= 1 200 + assert any("magic-missile" in r.name for r in results)

+153

tests/test_dice.py

··· 1 + """Tests for dice notation parsing and rolling.""" 2 + 3 + import pytest 4 + 5 + from storied.dice import DiceRoll, RollResult, parse_notation, roll 6 + 7 + 8 + class TestParseNotation: 9 + """Tests for parse_notation function.""" 10 + 11 + def test_simple_die(self): 12 + result = parse_notation("1d20") 13 + assert result.count == 1 14 + assert result.sides == 20 15 + assert result.modifier == 0 16 + assert result.keep_highest is None 17 + assert result.keep_lowest is None 18 + 19 + def test_multiple_dice(self): 20 + result = parse_notation("3d6") 21 + assert result.count == 3 22 + assert result.sides == 6 23 + assert result.modifier == 0 24 + 25 + def test_positive_modifier(self): 26 + result = parse_notation("2d6+3") 27 + assert result.count == 2 28 + assert result.sides == 6 29 + assert result.modifier == 3 30 + 31 + def test_negative_modifier(self): 32 + result = parse_notation("1d20-2") 33 + assert result.count == 1 34 + assert result.sides == 20 35 + assert result.modifier == -2 36 + 37 + def test_keep_highest(self): 38 + result = parse_notation("4d6kh3") 39 + assert result.count == 4 40 + assert result.sides == 6 41 + assert result.keep_highest == 3 42 + assert result.keep_lowest is None 43 + 44 + def test_keep_lowest(self): 45 + result = parse_notation("2d20kl1") 46 + assert result.count == 2 47 + assert result.sides == 20 48 + assert result.keep_lowest == 1 49 + assert result.keep_highest is None 50 + 51 + def test_advantage(self): 52 + result = parse_notation("2d20kh1") 53 + assert result.count == 2 54 + assert result.sides == 20 55 + assert result.keep_highest == 1 56 + 57 + def test_disadvantage(self): 58 + result = parse_notation("2d20kl1") 59 + assert result.count == 2 60 + assert result.sides == 20 61 + assert result.keep_lowest == 1 62 + 63 + def test_keep_with_modifier(self): 64 + result = parse_notation("4d6kh3+2") 65 + assert result.count == 4 66 + assert result.sides == 6 67 + assert result.keep_highest == 3 68 + assert result.modifier == 2 69 + 70 + def test_case_insensitive(self): 71 + result = parse_notation("2D20KH1") 72 + assert result.count == 2 73 + assert result.sides == 20 74 + assert result.keep_highest == 1 75 + 76 + def test_whitespace_tolerance(self): 77 + result = parse_notation(" 2d6 + 3 ") 78 + assert result.count == 2 79 + assert result.sides == 6 80 + assert result.modifier == 3 81 + 82 + def test_invalid_notation_raises(self): 83 + with pytest.raises(ValueError, match="Invalid dice notation"): 84 + parse_notation("not a dice roll") 85 + 86 + def test_empty_string_raises(self): 87 + with pytest.raises(ValueError, match="Invalid dice notation"): 88 + parse_notation("") 89 + 90 + 91 + class TestRoll: 92 + """Tests for roll function.""" 93 + 94 + def test_roll_returns_result(self): 95 + result = roll("1d20") 96 + assert isinstance(result, RollResult) 97 + assert result.notation == "1d20" 98 + assert len(result.rolls) == 1 99 + assert 1 <= result.rolls[0] <= 20 100 + assert result.total == result.rolls[0] 101 + 102 + def test_roll_multiple_dice(self): 103 + result = roll("3d6") 104 + assert len(result.rolls) == 3 105 + assert all(1 <= r <= 6 for r in result.rolls) 106 + assert result.total == sum(result.rolls) 107 + 108 + def test_roll_with_modifier(self): 109 + result = roll("1d20+5") 110 + assert result.modifier == 5 111 + assert result.total == result.rolls[0] + 5 112 + 113 + def test_roll_with_negative_modifier(self): 114 + result = roll("1d20-3") 115 + assert result.modifier == -3 116 + assert result.total == result.rolls[0] - 3 117 + 118 + def test_roll_keep_highest(self): 119 + result = roll("4d6kh3") 120 + assert len(result.rolls) == 4 121 + assert len(result.kept) == 3 122 + # Kept should be the 3 highest 123 + sorted_rolls = sorted(result.rolls, reverse=True) 124 + assert sorted(result.kept, reverse=True) == sorted_rolls[:3] 125 + assert result.total == sum(result.kept) 126 + 127 + def test_roll_keep_lowest(self): 128 + result = roll("2d20kl1") 129 + assert len(result.rolls) == 2 130 + assert len(result.kept) == 1 131 + assert result.kept[0] == min(result.rolls) 132 + assert result.total == result.kept[0] 133 + 134 + def test_roll_keep_with_modifier(self): 135 + result = roll("4d6kh3+2") 136 + assert len(result.kept) == 3 137 + assert result.modifier == 2 138 + assert result.total == sum(result.kept) + 2 139 + 140 + def test_roll_result_dict(self): 141 + result = roll("2d6+3") 142 + d = result.to_dict() 143 + assert d["notation"] == "2d6+3" 144 + assert "rolls" in d 145 + assert d["modifier"] == 3 146 + assert "total" in d 147 + 148 + def test_deterministic_with_seed(self): 149 + # Roll with same seed should give same results 150 + result1 = roll("3d6", seed=42) 151 + result2 = roll("3d6", seed=42) 152 + assert result1.rolls == result2.rolls 153 + assert result1.total == result2.total

+36

uv.lock

··· 338 338 ] 339 339 340 340 [[package]] 341 + name = "markdown-it-py" 342 + version = "4.0.0" 343 + source = { registry = "https://pypi.org/simple" } 344 + dependencies = [ 345 + { name = "mdurl" }, 346 + ] 347 + sdist = { url = "https://files.pythonhosted.org/packages/5b/f5/4ec618ed16cc4f8fb3b701563655a69816155e79e24a17b651541804721d/markdown_it_py-4.0.0.tar.gz", hash = "sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3", size = 73070, upload-time = "2025-08-11T12:57:52.854Z" } 348 + wheels = [ 349 + { url = "https://files.pythonhosted.org/packages/94/54/e7d793b573f298e1c9013b8c4dade17d481164aa517d1d7148619c2cedbf/markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147", size = 87321, upload-time = "2025-08-11T12:57:51.923Z" }, 350 + ] 351 + 352 + [[package]] 353 + name = "mdurl" 354 + version = "0.1.2" 355 + source = { registry = "https://pypi.org/simple" } 356 + sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" } 357 + wheels = [ 358 + { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" }, 359 + ] 360 + 361 + [[package]] 341 362 name = "mypy" 342 363 version = "1.19.1" 343 364 source = { registry = "https://pypi.org/simple" } ··· 605 626 ] 606 627 607 628 [[package]] 629 + name = "rich" 630 + version = "14.2.0" 631 + source = { registry = "https://pypi.org/simple" } 632 + dependencies = [ 633 + { name = "markdown-it-py" }, 634 + { name = "pygments" }, 635 + ] 636 + sdist = { url = "https://files.pythonhosted.org/packages/fb/d2/8920e102050a0de7bfabeb4c4614a49248cf8d5d7a8d01885fbb24dc767a/rich-14.2.0.tar.gz", hash = "sha256:73ff50c7c0c1c77c8243079283f4edb376f0f6442433aecb8ce7e6d0b92d1fe4", size = 219990, upload-time = "2025-10-09T14:16:53.064Z" } 637 + wheels = [ 638 + { url = "https://files.pythonhosted.org/packages/25/7a/b0178788f8dc6cafce37a212c99565fa1fe7872c70c6c9c1e1a372d9d88f/rich-14.2.0-py3-none-any.whl", hash = "sha256:76bc51fe2e57d2b1be1f96c524b890b816e334ab4c1e45888799bfaab0021edd", size = 243393, upload-time = "2025-10-09T14:16:51.245Z" }, 639 + ] 640 + 641 + [[package]] 608 642 name = "ruff" 609 643 version = "0.14.10" 610 644 source = { registry = "https://pypi.org/simple" } ··· 650 684 { name = "pymupdf" }, 651 685 { name = "pymupdf4llm" }, 652 686 { name = "pyyaml" }, 687 + { name = "rich" }, 653 688 ] 654 689 655 690 [package.optional-dependencies] ··· 671 706 { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0" }, 672 707 { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=4.0" }, 673 708 { name = "pyyaml", specifier = ">=6.0" }, 709 + { name = "rich", specifier = ">=13.0" }, 674 710 { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.1" }, 675 711 ] 676 712 provides-extras = ["dev"]

Configure Feed

Configure Feed