Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python

Add tutorial for text based game (#8451)

TomuHirata7483cf5b3897
diff --git a/docs/docs/tutorials/ai_text_game/index.md b/docs/docs/tutorials/ai_text_game/index.md
new file mode 100644
index 000000000..76c3e4e82
--- /dev/null
+++ b/docs/docs/tutorials/ai_text_game/index.md
@@ -0,0 +1,666 @@
+# Building a Creative Text-Based AI Game with DSPy
+
+This tutorial demonstrates how to create an interactive text-based adventure game using DSPy's modular programming approach. You'll build a dynamic game where AI handles narrative generation, character interactions, and adaptive gameplay.
+
+## What You'll Build
+
+An intelligent text-based adventure game featuring:
+
+- Dynamic story generation and branching narratives
+- AI-powered character interactions and dialogue
+- Adaptive gameplay that responds to player choices
+- Inventory and character progression systems
+- Save/load game state functionality
+
+## Setup
+
+```bash
+pip install dspy rich typer
+```
+
+## Step 1: Core Game Framework
+
+```python
+import dspy
+import json
+from typing import Dict, List, Optional, Any
+from dataclasses import dataclass, field
+from enum import Enum
+import random
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+import typer
+
+# Configure DSPy
+lm = dspy.LM(model='openai/gpt-4o-mini')
+dspy.configure(lm=lm)
+
+console = Console()
+
+class GameState(Enum):
+ MENU = "menu"
+ PLAYING = "playing"
+ INVENTORY = "inventory"
+ CHARACTER = "character"
+ GAME_OVER = "game_over"
+
+@dataclass
+class Player:
+ name: str
+ health: int = 100
+ level: int = 1
+ experience: int = 0
+ inventory: List[str] = field(default_factory=list)
+ skills: Dict[str, int] = field(default_factory=lambda: {
+ "strength": 10,
+ "intelligence": 10,
+ "charisma": 10,
+ "stealth": 10
+ })
+
+ def add_item(self, item: str):
+ self.inventory.append(item)
+ console.print(f"[green]Added {item} to inventory![/green]")
+
+ def remove_item(self, item: str) -> bool:
+ if item in self.inventory:
+ self.inventory.remove(item)
+ return True
+ return False
+
+ def gain_experience(self, amount: int):
+ self.experience += amount
+ old_level = self.level
+ self.level = 1 + (self.experience // 100)
+ if self.level > old_level:
+ console.print(f"[bold yellow]Level up! You are now level {self.level}![/bold yellow]")
+
+@dataclass
+class GameContext:
+ current_location: str = "Village Square"
+ story_progress: int = 0
+ visited_locations: List[str] = field(default_factory=list)
+ npcs_met: List[str] = field(default_factory=list)
+ completed_quests: List[str] = field(default_factory=list)
+ game_flags: Dict[str, bool] = field(default_factory=dict)
+
+ def add_flag(self, flag: str, value: bool = True):
+ self.game_flags[flag] = value
+
+ def has_flag(self, flag: str) -> bool:
+ return self.game_flags.get(flag, False)
+
+class GameEngine:
+ def __init__(self):
+ self.player = None
+ self.context = GameContext()
+ self.state = GameState.MENU
+ self.running = True
+
+ def save_game(self, filename: str = "savegame.json"):
+ """Save current game state."""
+ save_data = {
+ "player": {
+ "name": self.player.name,
+ "health": self.player.health,
+ "level": self.player.level,
+ "experience": self.player.experience,
+ "inventory": self.player.inventory,
+ "skills": self.player.skills
+ },
+ "context": {
+ "current_location": self.context.current_location,
+ "story_progress": self.context.story_progress,
+ "visited_locations": self.context.visited_locations,
+ "npcs_met": self.context.npcs_met,
+ "completed_quests": self.context.completed_quests,
+ "game_flags": self.context.game_flags
+ }
+ }
+
+ with open(filename, 'w') as f:
+ json.dump(save_data, f, indent=2)
+ console.print(f"[green]Game saved to {filename}![/green]")
+
+ def load_game(self, filename: str = "savegame.json") -> bool:
+ """Load game state from file."""
+ try:
+ with open(filename, 'r') as f:
+ save_data = json.load(f)
+
+ # Reconstruct player
+ player_data = save_data["player"]
+ self.player = Player(
+ name=player_data["name"],
+ health=player_data["health"],
+ level=player_data["level"],
+ experience=player_data["experience"],
+ inventory=player_data["inventory"],
+ skills=player_data["skills"]
+ )
+
+ # Reconstruct context
+ context_data = save_data["context"]
+ self.context = GameContext(
+ current_location=context_data["current_location"],
+ story_progress=context_data["story_progress"],
+ visited_locations=context_data["visited_locations"],
+ npcs_met=context_data["npcs_met"],
+ completed_quests=context_data["completed_quests"],
+ game_flags=context_data["game_flags"]
+ )
+
+ console.print(f"[green]Game loaded from {filename}![/green]")
+ return True
+
+ except FileNotFoundError:
+ console.print(f"[red]Save file {filename} not found![/red]")
+ return False
+ except Exception as e:
+ console.print(f"[red]Error loading game: {e}![/red]")
+ return False
+
+# Initialize game engine
+game = GameEngine()
+```
+
+## Step 2: AI-Powered Story Generation
+
+```python
+class StoryGenerator(dspy.Signature):
+ """Generate dynamic story content based on current game state."""
+ location: str = dspy.InputField(desc="Current location")
+ player_info: str = dspy.InputField(desc="Player information and stats")
+ story_progress: int = dspy.InputField(desc="Current story progress level")
+ recent_actions: str = dspy.InputField(desc="Player's recent actions")
+
+ scene_description: str = dspy.OutputField(desc="Vivid description of current scene")
+ available_actions: List[str] = dspy.OutputField(desc="List of possible player actions")
+ npcs_present: List[str] = dspy.OutputField(desc="NPCs present in this location")
+ items_available: List[str] = dspy.OutputField(desc="Items that can be found or interacted with")
+
+class DialogueGenerator(dspy.Signature):
+ """Generate NPC dialogue and responses."""
+ npc_name: str = dspy.InputField(desc="Name and type of NPC")
+ npc_personality: str = dspy.InputField(desc="NPC personality and background")
+ player_input: str = dspy.InputField(desc="What the player said or did")
+ context: str = dspy.InputField(desc="Current game context and history")
+
+ npc_response: str = dspy.OutputField(desc="NPC's dialogue response")
+ mood_change: str = dspy.OutputField(desc="How NPC's mood changed (positive/negative/neutral)")
+ quest_offered: bool = dspy.OutputField(desc="Whether NPC offers a quest")
+ information_revealed: str = dspy.OutputField(desc="Any important information shared")
+
+class ActionResolver(dspy.Signature):
+ """Resolve player actions and determine outcomes."""
+ action: str = dspy.InputField(desc="Player's chosen action")
+ player_stats: str = dspy.InputField(desc="Player's current stats and skills")
+ context: str = dspy.InputField(desc="Current game context")
+ difficulty: str = dspy.InputField(desc="Difficulty level of the action")
+
+ success: bool = dspy.OutputField(desc="Whether the action succeeded")
+ outcome_description: str = dspy.OutputField(desc="Description of what happened")
+ stat_changes: Dict[str, int] = dspy.OutputField(desc="Changes to player stats")
+ items_gained: List[str] = dspy.OutputField(desc="Items gained from this action")
+ experience_gained: int = dspy.OutputField(desc="Experience points gained")
+
+class GameAI(dspy.Module):
+ """Main AI module for game logic and narrative."""
+
+ def __init__(self):
+ super().__init__()
+ self.story_gen = dspy.ChainOfThought(StoryGenerator)
+ self.dialogue_gen = dspy.ChainOfThought(DialogueGenerator)
+ self.action_resolver = dspy.ChainOfThought(ActionResolver)
+
+ def generate_scene(self, player: Player, context: GameContext, recent_actions: str = "") -> Dict:
+ """Generate current scene description and options."""
+
+ player_info = f"Level {player.level} {player.name}, Health: {player.health}, Skills: {player.skills}"
+
+ scene = self.story_gen(
+ location=context.current_location,
+ player_info=player_info,
+ story_progress=context.story_progress,
+ recent_actions=recent_actions
+ )
+
+ return {
+ "description": scene.scene_description,
+ "actions": scene.available_actions,
+ "npcs": scene.npcs_present,
+ "items": scene.items_available
+ }
+
+ def handle_dialogue(self, npc_name: str, player_input: str, context: GameContext) -> Dict:
+ """Handle conversation with NPCs."""
+
+ # Create NPC personality based on name and context
+ personality_map = {
+ "Village Elder": "Wise, knowledgeable, speaks in riddles, has ancient knowledge",
+ "Merchant": "Greedy but fair, loves to bargain, knows about valuable items",
+ "Guard": "Dutiful, suspicious of strangers, follows rules strictly",
+ "Thief": "Sneaky, untrustworthy, has information about hidden things",
+ "Wizard": "Mysterious, powerful, speaks about magic and ancient forces"
+ }
+
+ personality = personality_map.get(npc_name, "Friendly villager with local knowledge")
+ game_context = f"Location: {context.current_location}, Story progress: {context.story_progress}"
+
+ response = self.dialogue_gen(
+ npc_name=npc_name,
+ npc_personality=personality,
+ player_input=player_input,
+ context=game_context
+ )
+
+ return {
+ "response": response.npc_response,
+ "mood": response.mood_change,
+ "quest": response.quest_offered,
+ "info": response.information_revealed
+ }
+
+ def resolve_action(self, action: str, player: Player, context: GameContext) -> Dict:
+ """Resolve player actions and determine outcomes."""
+
+ player_stats = f"Level {player.level}, Health {player.health}, Skills: {player.skills}"
+ game_context = f"Location: {context.current_location}, Progress: {context.story_progress}"
+
+ # Determine difficulty based on action type
+ difficulty = "medium"
+ if any(word in action.lower() for word in ["fight", "battle", "attack"]):
+ difficulty = "hard"
+ elif any(word in action.lower() for word in ["look", "examine", "talk"]):
+ difficulty = "easy"
+
+ result = self.action_resolver(
+ action=action,
+ player_stats=player_stats,
+ context=game_context,
+ difficulty=difficulty
+ )
+
+ return {
+ "success": result.success,
+ "description": result.outcome_description,
+ "stat_changes": result.stat_changes,
+ "items": result.items_gained,
+ "experience": result.experience_gained
+ }
+
+# Initialize AI
+ai = GameAI()
+```
+
+## Step 3: Game Interface and Interaction
+
+```python
+def display_game_header():
+ """Display the game header."""
+ header = Text("🏰 MYSTIC REALM ADVENTURE 🏰", style="bold magenta")
+ console.print(Panel(header, style="bright_blue"))
+
+def display_player_status(player: Player):
+ """Display player status panel."""
+ status = f"""
+[bold]Name:[/bold] {player.name}
+[bold]Level:[/bold] {player.level} (XP: {player.experience})
+[bold]Health:[/bold] {player.health}/100
+[bold]Skills:[/bold]
+ • Strength: {player.skills['strength']}
+ • Intelligence: {player.skills['intelligence']}
+ • Charisma: {player.skills['charisma']}
+ • Stealth: {player.skills['stealth']}
+[bold]Inventory:[/bold] {len(player.inventory)} items
+ """
+ console.print(Panel(status.strip(), title="Player Status", style="green"))
+
+def display_location(context: GameContext, scene: Dict):
+ """Display current location and scene."""
+ location_panel = f"""
+[bold yellow]{context.current_location}[/bold yellow]
+
+{scene['description']}
+ """
+
+ if scene['npcs']:
+ location_panel += f"\n\n[bold]NPCs present:[/bold] {', '.join(scene['npcs'])}"
+
+ if scene['items']:
+ location_panel += f"\n[bold]Items visible:[/bold] {', '.join(scene['items'])}"
+
+ console.print(Panel(location_panel.strip(), title="Current Location", style="cyan"))
+
+def display_actions(actions: List[str]):
+ """Display available actions."""
+ action_text = "\n".join([f"{i+1}. {action}" for i, action in enumerate(actions)])
+ console.print(Panel(action_text, title="Available Actions", style="yellow"))
+
+def get_player_choice(max_choices: int) -> int:
+ """Get player's choice with input validation."""
+ while True:
+ try:
+ choice = typer.prompt("Choose an action (number)")
+ choice_num = int(choice)
+ if 1 <= choice_num <= max_choices:
+ return choice_num - 1
+ else:
+ console.print(f"[red]Please enter a number between 1 and {max_choices}[/red]")
+ except ValueError:
+ console.print("[red]Please enter a valid number[/red]")
+
+def show_inventory(player: Player):
+ """Display player inventory."""
+ if not player.inventory:
+ console.print(Panel("Your inventory is empty.", title="Inventory", style="red"))
+ else:
+ items = "\n".join([f"• {item}" for item in player.inventory])
+ console.print(Panel(items, title="Inventory", style="green"))
+
+def main_menu():
+ """Display main menu and handle selection."""
+ console.clear()
+ display_game_header()
+
+ menu_options = [
+ "1. New Game",
+ "2. Load Game",
+ "3. How to Play",
+ "4. Exit"
+ ]
+
+ menu_text = "\n".join(menu_options)
+ console.print(Panel(menu_text, title="Main Menu", style="bright_blue"))
+
+ choice = typer.prompt("Select an option")
+ return choice
+
+def show_help():
+ """Display help information."""
+ help_text = """
+[bold]How to Play:[/bold]
+
+• This is a text-based adventure game powered by AI
+• Make choices by selecting numbered options
+• Talk to NPCs to learn about the world and get quests
+• Explore different locations to find items and adventures
+• Your choices affect the story and character development
+• Use 'inventory' to check your items
+• Use 'status' to see your character info
+• Type 'save' to save your progress
+• Type 'quit' to return to main menu
+
+[bold]Tips:[/bold]
+• Different skills affect your success in various actions
+• NPCs remember your previous interactions
+• Explore thoroughly - there are hidden secrets!
+• Your reputation affects how NPCs treat you
+ """
+ console.print(Panel(help_text.strip(), title="Game Help", style="blue"))
+ typer.prompt("Press Enter to continue")
+```
+
+## Step 4: Main Game Loop
+
+```python
+def create_new_character():
+ """Create a new player character."""
+ console.clear()
+ display_game_header()
+
+ name = typer.prompt("Enter your character's name")
+
+ # Character creation with skill point allocation
+ console.print("\n[bold]Character Creation[/bold]")
+ console.print("You have 10 extra skill points to distribute among your skills.")
+ console.print("Base skills start at 10 each.\n")
+
+ skills = {"strength": 10, "intelligence": 10, "charisma": 10, "stealth": 10}
+ points_remaining = 10
+
+ for skill in skills.keys():
+ if points_remaining > 0:
+ console.print(f"Points remaining: {points_remaining}")
+ while True:
+ try:
+ points = int(typer.prompt(f"Points to add to {skill} (0-{points_remaining})"))
+ if 0 <= points <= points_remaining:
+ skills[skill] += points
+ points_remaining -= points
+ break
+ else:
+ console.print(f"[red]Enter a number between 0 and {points_remaining}[/red]")
+ except ValueError:
+ console.print("[red]Please enter a valid number[/red]")
+
+ player = Player(name=name, skills=skills)
+ console.print(f"\n[green]Welcome to Mystic Realm, {name}![/green]")
+ return player
+
+def game_loop():
+ """Main game loop."""
+ recent_actions = ""
+
+ while game.running and game.state == GameState.PLAYING:
+ console.clear()
+ display_game_header()
+
+ # Generate current scene
+ scene = ai.generate_scene(game.player, game.context, recent_actions)
+
+ # Display game state
+ display_player_status(game.player)
+ display_location(game.context, scene)
+
+ # Add standard actions
+ all_actions = scene['actions'] + ["Check inventory", "Character status", "Save game", "Quit to menu"]
+ display_actions(all_actions)
+
+ # Get player choice
+ choice_idx = get_player_choice(len(all_actions))
+ chosen_action = all_actions[choice_idx]
+
+ # Handle special commands
+ if chosen_action == "Check inventory":
+ show_inventory(game.player)
+ typer.prompt("Press Enter to continue")
+ continue
+ elif chosen_action == "Character status":
+ display_player_status(game.player)
+ typer.prompt("Press Enter to continue")
+ continue
+ elif chosen_action == "Save game":
+ game.save_game()
+ typer.prompt("Press Enter to continue")
+ continue
+ elif chosen_action == "Quit to menu":
+ game.state = GameState.MENU
+ break
+
+ # Handle game actions
+ if chosen_action in scene['actions']:
+ # Check if it's dialogue with an NPC
+ npc_target = None
+ for npc in scene['npcs']:
+ if npc.lower() in chosen_action.lower():
+ npc_target = npc
+ break
+
+ if npc_target:
+ # Handle NPC interaction
+ console.print(f"\n[bold]Talking to {npc_target}...[/bold]")
+ dialogue = ai.handle_dialogue(npc_target, chosen_action, game.context)
+
+ console.print(f"\n[italic]{npc_target}:[/italic] \"{dialogue['response']}\"")
+
+ if dialogue['quest']:
+ console.print(f"[yellow]💼 Quest opportunity detected![/yellow]")
+
+ if dialogue['info']:
+ console.print(f"[blue]ℹ️ {dialogue['info']}[/blue]")
+
+ # Add NPC to met list
+ if npc_target not in game.context.npcs_met:
+ game.context.npcs_met.append(npc_target)
+
+ recent_actions = f"Talked to {npc_target}: {chosen_action}"
+ else:
+ # Handle general action
+ result = ai.resolve_action(chosen_action, game.player, game.context)
+
+ console.print(f"\n{result['description']}")
+
+ # Apply results
+ if result['success']:
+ console.print("[green]✅ Success![/green]")
+
+ # Apply stat changes
+ for stat, change in result['stat_changes'].items():
+ if stat in game.player.skills:
+ game.player.skills[stat] += change
+ if change > 0:
+ console.print(f"[green]{stat.title()} increased by {change}![/green]")
+ elif stat == "health":
+ game.player.health = max(0, min(100, game.player.health + change))
+ if change > 0:
+ console.print(f"[green]Health restored by {change}![/green]")
+ elif change < 0:
+ console.print(f"[red]Health decreased by {abs(change)}![/red]")
+
+ # Add items
+ for item in result['items']:
+ game.player.add_item(item)
+
+ # Give experience
+ if result['experience'] > 0:
+ game.player.gain_experience(result['experience'])
+
+ # Update story progress
+ game.context.story_progress += 1
+ else:
+ console.print("[red]❌ The action didn't go as planned...[/red]")
+
+ recent_actions = f"Attempted: {chosen_action}"
+
+ # Check for game over conditions
+ if game.player.health <= 0:
+ console.print("\n[bold red]💀 You have died! Game Over![/bold red]")
+ game.state = GameState.GAME_OVER
+ break
+
+ typer.prompt("\nPress Enter to continue")
+
+def main():
+ """Main game function."""
+ while game.running:
+ if game.state == GameState.MENU:
+ choice = main_menu()
+
+ if choice == "1":
+ game.player = create_new_character()
+ game.context = GameContext()
+ game.state = GameState.PLAYING
+ console.print("\n[italic]Your adventure begins...[/italic]")
+ typer.prompt("Press Enter to start")
+
+ elif choice == "2":
+ if game.load_game():
+ game.state = GameState.PLAYING
+ typer.prompt("Press Enter to continue")
+
+ elif choice == "3":
+ show_help()
+
+ elif choice == "4":
+ game.running = False
+ console.print("[bold]Thanks for playing! Goodbye![/bold]")
+
+ elif game.state == GameState.PLAYING:
+ game_loop()
+
+ elif game.state == GameState.GAME_OVER:
+ console.print("\n[bold]Game Over[/bold]")
+ restart = typer.confirm("Would you like to return to the main menu?")
+ if restart:
+ game.state = GameState.MENU
+ else:
+ game.running = False
+
+if __name__ == "__main__":
+ main()
+```
+
+## Example Gameplay
+
+When you run the game, you'll experience:
+
+**Character Creation:**
+```
+🏰 MYSTIC REALM ADVENTURE 🏰
+
+Enter your character's name: Aria
+
+Character Creation
+You have 10 extra skill points to distribute among your skills.
+Base skills start at 10 each.
+
+Points remaining: 10
+Points to add to strength (0-10): 2
+Points to add to intelligence (0-8): 4
+Points to add to charisma (0-4): 3
+Points to add to stealth (0-1): 1
+
+Welcome to Mystic Realm, Aria!
+```
+
+**Dynamic Scene Generation:**
+```
+┌──────────── Current Location ────────────┐
+│ Village Square │
+│ │
+│ You stand in the bustling heart of │
+│ Willowbrook Village. The ancient stone │
+│ fountain bubbles cheerfully as merchants │
+│ hawk their wares and children play. A │
+│ mysterious hooded figure lurks near the │
+│ shadows of the old oak tree. │
+│ │
+│ NPCs present: Village Elder, Merchant │
+│ Items visible: Strange Medallion, Herbs │
+└──────────────────────────────────────────┘
+
+┌────────── Available Actions ─────────────┐
+│ 1. Approach the hooded figure │
+│ 2. Talk to the Village Elder │
+│ 3. Browse the merchant's wares │
+│ 4. Examine the strange medallion │
+│ 5. Gather herbs near the fountain │
+│ 6. Head to the forest path │
+└───────────────────────────────────────────┘
+```
+
+**AI-Generated Dialogue:**
+```
+Talking to Village Elder...
+
+Village Elder: "Ah, young traveler, I sense a great destiny
+surrounds you like morning mist. The ancient prophecy speaks
+of one who would come bearing the mark of courage. Tell me,
+have you noticed anything... unusual in your travels?"
+
+💼 Quest opportunity detected!
+ℹ️ The Village Elder knows about an ancient prophecy that might involve you
+```
+
+## Next Steps
+
+- **Combat System**: Add turn-based battles with strategy
+- **Magic System**: Spellcasting with resource management
+- **Multiplayer**: Network support for cooperative adventures
+- **Quest System**: Complex multi-step missions with branching outcomes
+- **World Building**: Procedurally generated locations and characters
+- **Audio**: Add sound effects and background music
+
+This tutorial demonstrates how DSPy's modular approach enables complex, interactive systems where AI handles creative content generation while maintaining consistent game logic and player agency.
diff --git a/docs/docs/tutorials/real_world_examples/index.md b/docs/docs/tutorials/real_world_examples/index.md
index 120573051..679192ef7 100644
--- a/docs/docs/tutorials/real_world_examples/index.md
+++ b/docs/docs/tutorials/real_world_examples/index.md
@@ -23,3 +23,13 @@ Create conversational agents with persistent memory using DSPy ReAct and Mem0 in
Develop financial analysis agents that fetch real-time market data, analyze news sentiment, and provide investment insights using LangChain tool integration.
**Key Concepts:** Tool integration, financial data, real-time analysis
+
+### 🔄 [Automated Code Generation from Documentation](../sample_code_generation/index.md)
+Build a system that automatically fetches documentation from URLs and generates working code examples for any library using DSPy's intelligent analysis.
+
+**Key Concepts:** Web scraping, documentation parsing, automated learning, code generation
+
+### 🎮 [Building a Creative Text-Based AI Game](../ai_text_game/index.md)
+Create an interactive text-based adventure game with dynamic storytelling, AI-powered NPCs, and adaptive gameplay using DSPy's modular programming approach.
+
+**Key Concepts:** Interactive storytelling, game state management, character progression, AI-driven narratives
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index bdb94661d..27e69e40f 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -65,6 +65,7 @@ nav:
- Memory-Enabled ReAct Agents: tutorials/mem0_react_agent/index.md
- Financial Analysis with Yahoo Finance: tutorials/yahoo_finance_react/index.md
- Email Information Extraction: tutorials/email_extraction/index.md
+ - Building a Creative Text-Based AI Game: tutorials/ai_text_game/index.md
- DSPy in Production: production/index.md
- Community:
- Community Resources: community/community-resources.md