🎮 Pokémon: AI Adventure

A text-based Pokémon RPG powered by LangChain and LangGraph, where an LLM narrates your journey, generates wild encounters, and drives the story — while deterministic game logic handles battles, catching, and stats.

See related Youtube video: https://www.youtube.com/embed/TMPeW-D6MvU

See related blog post: https://ivanmosquera.net/

Game Graph

        ┌──────────┐
        │  START    │
        └────┬─────┘
             │
        ┌────▼─────┐
        │  intro    │  ← Professor Oak welcomes you
        └────┬─────┘
             │
        ┌────▼─────┐ ◄──────────────────────────┐
        │ explore   │  ← interrupt() for input    │
        └────┬─────┘                              │
             │                                    │
      ┌──────┴──────┐                             │
      ▼             ▼                             │
 ┌────────┐  ┌──────────────┐                     │
 │  heal  │  │encounter_chk │                     │
 └───┬────┘  └──────┬───────┘                     │
     │        ┌─────┴──────┐                      │
     │   no encounter   encounter                 │
     │        │            │                      │
     │        │     ┌──────▼──────┐               │
     │        │     │   battle    │◄──┐           │
     │        │     │ interrupt() │   │ ongoing   │
     │        │     └──────┬──────┘   │           │
     │        │      ┌─────┼─────┐    │           │
     │        │     win   loss  loop──┘           │
     │        │      │     │                      │
     └────────┴──────┴─────┼──────────────────────┘
                           │
                    ┌──────▼──────┐
                    │  game_over  │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │     END     │
                    └─────────────┘

How It Works

Component	Role
LLM (Ollama)	Narrates scenes, generates wild Pokémon, powers Professor Oak
LangGraph StateGraph	Manages game phases (explore → encounter → battle → ...)
interrupt()	Pauses the graph to wait for player input each turn
Structured Output	Forces the LLM to return typed Pokémon data (Pydantic models)
MemorySaver	Checkpoints game state so the graph can resume after interrupts

Prerequisites

• Python 3.10+
• Ollama installed and running locally

Installing Ollama and a model

1. Install Ollama from ollama.com or via Homebrew:

   brew install ollama

2. Start the Ollama server:

   ollama serve

3. Pull a model that supports tool calling (required for structured output in this game). Recommended models:

   Model	Size	Command
   Qwen 2.5 (recommended)	7B	ollama pull qwen2.5
   Llama 3.1	8B	ollama pull llama3.1
   Mistral	7B	ollama pull mistral

   Note: The game uses structured output (with_structured_output) which requires tool/function calling support. Not all Ollama models support this — the models listed above do.

4. Update the model field in main.py to match the model you pulled:

   llm = ChatOllama(
       model="qwen2.5",  # must match the model name from `ollama list`
       base_url="http://localhost:11434",
       max_tokens=4096,
       temperature=0.7,
   )

Setup

# Clone the repo
git clone 
cd ivmos-langx-pokemon-game

# Create a virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install langchain langchain-ollama langgraph pydantic typing_extensions

Run

source venv/bin/activate
python3 main.py

Gameplay

Once the game starts, Professor Oak introduces you and hands you your starter Pokémon (Charmander). From there:

• Explore — Type explore or search grass to roam the area
• Heal — Type go to town or heal to visit a Pokémon Center
• Battle — When a wild Pokémon appears, choose a move name, catch, or run
• Quit — Type quit or exit at any prompt

Example Session

🎮 POKÉMON: AI ADVENTURE
What's your name, trainer? > Ash

🎮 Professor Oak smiles as he hands you a Poké Ball...

📍 Pallet Town | Team: Charmander (39/39 HP)
What do you do? (explore / search grass / go to town / check team)
> search grass

🎮 You wade into the tall grass north of Pallet Town...

⚡ A wild Pidgey (Lv.4, normal-type) appeared!
   HP: 28 | ATK: 18 | DEF: 15

⚔️  BATTLE — Turn 1
  Charmander: 39/39 HP
  Wild Pidgey: 28/28 HP
  Your moves: [Scratch / Ember / Growl / Smokescreen]
  Or: [catch] / [run]
> Ember

🎮 🗡️ Charmander uses Ember! CRITICAL HIT! (24 damage)
🐾 Wild Pidgey strikes back! (8 damage)
  Charmander: 31/39 HP | Pidgey: 4/28 HP

> catch

🎮 🎉 Gotcha! Pidgey was caught!
📦 Added to your team!

Project Structure

ivmos-langx-pokemon-game/
├── main.py          # Complete game — all nodes, graph, and game loop
├── README.md
└── venv/            # Virtual environment (not committed)

Configuration

The LLM connection is configured at the top of main.py:

llm = ChatOllama(
    model="qwen3.5:35b-a3b",
    base_url="http://localhost:11434",
    max_tokens=4096,
    temperature=0.7,
)

To use a different model or server, update model and base_url.

Extending the Game

• New locations — Add entries to a location map and update route_after_explore
• Gym battles — Create NPC trainer nodes with LLM-driven move selection
• Evolution — Track XP in GameState and trigger evolution at thresholds
• Save/Load — Swap MemorySaver for SqliteSaver to persist game sessions to disk
• Streaming — Use game.stream() for real-time typewriter-style narration

Concepts & Code Reference

This project demonstrates core LangChain and LangGraph patterns. Here's where each concept appears in main.py:

LangChain Fundamentals

ChatOllama — LLM Connection Wraps the Ollama REST API into LangChain's unified chat model interface. Configured once and reused across all chains.

# main.py — top of file
llm = ChatOllama(
    model="qwen3.5:35b-a3b",
    base_url="http://localhost:11434",
    ...
)

Prompt Templates & Message Roles ChatPromptTemplate with SystemMessage sets the LLM's persona (narrator), while {variables} make prompts reusable across different game contexts.

# main.py — narrator chain
narrator = (
    ChatPromptTemplate.from_messages([
        ("system", """You are the narrator of a Pokémon text adventure game.
Player: {player_name} | Location: {location} ..."""),
        MessagesPlaceholder("history"),
        ("human", "{input}"),
    ])
    | llm
)

Structured Output with Pydantic Forces the LLM to return valid typed data instead of free text. Used to generate wild Pokémon with guaranteed fields and value ranges.

# main.py — schema + binding
class WildPokemonSchema(BaseModel):
    name: str
    type: str
    level: int = Field(ge=2, le=50)
    hp: int = Field(ge=20, le=120)
    ...

encounter_generator = llm.with_structured_output(WildPokemonSchema)

LCEL Chains (pipe operator) The | operator composes prompt → LLM into a single callable chain. The narrator chain uses this to go from template to response in one .invoke() call.

# main.py — chain composition
narrator = (
    ChatPromptTemplate.from_messages([...])
    | llm  # prompt output pipes into the LLM
)

Message History (Memory) MessagesPlaceholder("history") injects past conversation messages into the prompt, giving the LLM context about earlier events in the adventure.

# main.py — inside nodes like intro_node, explore_node
response = narrator.invoke({
    ...
    "history": state["messages"][-8:],  # last 8 messages for context
    "input": "...",
})

LangGraph Game Engine

StateGraph & TypedDict The entire game state is a TypedDict. LangGraph passes it through every node, and each node returns only the keys it wants to update.

# main.py — state definition
class GameState(TypedDict):
    messages: Annotated[list, add_messages]  # reducer: appends, not replaces
    player_name: str
    location: str
    pokemon_team: list[dict]
    wild_pokemon: dict | None
    badge_count: int
    game_phase: str
    turn_count: int

Nodes — Game Phase Functions Each node is a function that receives the full state and returns a partial update. The graph handles merging.

# main.py — node examples
def intro_node(state: GameState) -> dict:       # opening scene
def explore_node(state: GameState) -> dict:      # player roams
def encounter_check_node(state: GameState) -> dict:  # random encounter roll
def battle_node(state: GameState) -> dict:       # fight / catch / run
def heal_node(state: GameState) -> dict:         # Pokémon Center
def game_over_node(state: GameState) -> dict:    # defeat screen

Conditional Edges — Branching Logic add_conditional_edges calls a routing function that reads the state and returns a string key, directing the graph to the next node dynamically.

# main.py — routing
def route_after_explore(state: GameState) -> str:
    # checks player's last action
    if "town" in last or "heal" in last:
        return "heal"
    return "encounter_check"

graph.add_conditional_edges("explore", route_after_explore,
    {"heal": "heal", "encounter_check": "encounter_check"})

interrupt() — Human-in-the-Loop Pauses graph execution and surfaces a prompt to the player. When the player responds, Command(resume=...) feeds their input back into the node.

# main.py — inside explore_node
action = interrupt(
    f"\n📍 {state['location']} | Team: {team_str}\n"
    f"What do you do? (explore / search grass / go to town / check team)"
)

# main.py — inside the game loop
result = game.invoke(Command(resume=player_input), config)

MemorySaver — Checkpointing Required for interrupt() to work. Saves graph state between pauses so execution can resume exactly where it left off. Each game session gets a unique thread_id.

# main.py — compile with checkpointer
checkpointer = MemorySaver()
game = graph.compile(checkpointer=checkpointer)

# main.py — session config
config = {"configurable": {"thread_id": f"game-{name}"}}

add_messages Reducer The Annotated[list, add_messages] annotation on the messages field tells LangGraph to append new messages instead of overwriting the list — essential for building conversation history.

# main.py — in GameState
messages: Annotated[list, add_messages]

# When a node returns {"messages": [AIMessage(...)]},
# LangGraph appends it to the existing list automatically.

Graph Construction & Compilation Nodes are registered, edges define flow, and .compile() produces a runnable graph. The full wiring:

# main.py — graph assembly
graph = StateGraph(GameState)

graph.add_node("intro", intro_node)
graph.add_node("explore", explore_node)
graph.add_node("encounter_check", encounter_check_node)
graph.add_node("battle", battle_node)
graph.add_node("heal", heal_node)
graph.add_node("game_over", game_over_node)

graph.add_edge(START, "intro")
graph.add_edge("intro", "explore")
graph.add_conditional_edges("explore", route_after_explore, {...})
graph.add_edge("heal", "explore")
graph.add_conditional_edges("encounter_check", route_after_encounter_check, {...})
graph.add_conditional_edges("battle", route_after_battle, {...})
graph.add_edge("game_over", END)

game = graph.compile(checkpointer=checkpointer)

Built With

• LangChain — LLM orchestration
• LangGraph — Stateful graph execution
• Ollama — Local/remote LLM inference