boltcrypt 0.1.0__tar.gz

boltcrypt-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: boltcrypt
+Version: 0.1.0
+Summary: Boltcrypt environment
+Author: foreverska
+Project-URL: Github:, https://github.com/foreverska/boltcrypt
+Keywords: gymnasium,gym
+Description-Content-Type: text/markdown
+License-File: license.txt
+Requires-Dist: gymnasium>=1.0.0
+Requires-Dist: numpy
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: summary
+
+# BoltCrypt: Procedural Dungeon RL Environment #
+BoltCrypt is a lightweight, OpenAI Gymnasium-compatible environment featuring procedurally generated dungeons. It challenges Reinforcement Learning agents (and humans!) to navigate complex layouts, solve sokoban-style boulder puzzles, and manage inventory items like keys to reach the exit.
+## 🏰 Features ##
+Procedural Generation: Every reset generates a unique dungeon layout based on configurable parameters (density, connectivity, room size).
+Puzzle Mechanics: Includes boulder-pushing puzzles and locked doors that require finding a key.
+Gymnasium API: Fully compatible with standard RL workflows.
+Pygame Visualization: A built-in harness to play manually or watch your agent learn in real-time.
+Flexible Observation Space: Provides local room grids, global coordinates, and inventory status.
+🛠 Installation
+Since this project uses condavenv, ensure you have your environment active:
+``` bash
+# Example if using conda directly
+conda activate <your-env-name>
+pip install gymnasium pygame numpy matplotlib boltcrypt
+```
+
+## 🚀 Getting Started ##
+### Play Manually ###
+Test the dungeon generation and mechanics yourself using the Pygame harness:
+``` bash
+python boltcrypt_game.py
+```
+
+**Arrows:** Move the agent.  
+**R:** Reset/Regenerate the dungeon.  
+**Goal:** Find the key (if required) and reach the green Exit tile. 
+
+### Train an Agent ###  
+The project includes a tabular Q-Learning implementation to demonstrate how an agent can "memorize" a specific dungeon layout:
+``` bash
+python tabular_q.py
+```
+
+## ⚙️ Configuration ##
+
+The DungeonGenerator and BoltCrypt environment can be customized via a config dictionary:  
+
+### Parameter Description ###  
+**min_dist:** Minimum Manhattan distance between Start and Exit.  
+**mean_rooms:** Average number of rooms in the dungeon.  
+**connectivity:** Probability of creating loops between rooms (0.0 = Tree, 1.0 = Highly connected).  
+**puzzle_density:** Chance of a room containing a boulder puzzle.  
+**key_puzzle_prob:** Chance that the exit is locked and a key is hidden in a leaf room.  
+
+
+### 🗺 Tile Legend ###
+⬜ Floor: Walkable space.  
+⬛ Wall: Impassable.  
+🚪 Door: Transitions between rooms (may be locked by puzzles).  
+🟩 Exit: Your goal!  
+🔴 Switch: Target for boulders.  
+🟤 Boulder: Can be pushed onto switches.  
+🟡 Key: Required to open locked exit rooms.  
+
+
+### 🤖 Observation Space ###
+The environment returns a dictionary:  
+**grid:** A 10x10 local view of the current room.  
+**agent_pos:** (x, y) coordinates within the room.  
+**global_pos:** (gx, gy) coordinates in the dungeon layout.  
+**inventory:** Binary flag (1 if holding a key)  
+
+## 📦 Wrappers & Extensions ##
+BoltCrypt includes several gym.Wrapper implementations to modify observations or rewards, making it a versatile 
+testbed for different RL paradigms.
+
+### 📝 Natural Language Wrapper (NaturalLanguage) ####
+The crown jewel for testing Reasoning LLMs. This wrapper transforms the numeric observation space into a rich, 
+descriptive narrative. Instead of a grid, the agent receives a text-based description of its surroundings.  
+**Dynamic Narrative:** Provides room dimensions, relative positions of doors, boulder locations, and puzzle statuses 
+(e.g., "A loud mechanical clank echoes! The doors unlock.").  
+**LLM Ready:** Accepts string inputs like "NORTH", "SOUTH", "EAST", or "WEST" in the step() function.  
+**Physics Logic:** Includes an "Adventurer's Manual" to explain game rules to an LLM via the observation stream.  
+
+### 🌫️ Fog of War (FogOfWarWrapper) ###
+Transforms the global room view into a partially observable environment.  
+**Vision Range:** Limits the grid observation to a (2v+1) \times (2v+1) window centered on the agent.  
+**Memory Challenge:** Forces agents to map the room internally rather than having perfect spatial information.  
+
+### 🏆 Room Discovery Reward (RoomDiscoveryReward) ###
+Combats sparse rewards in large dungeons by incentivizing exploration.  
+**Exploration Bonus:** Grants a small configurable reward (e.g., +0.1) the first time the agent enters a new room in the dungeon.  
+**Global Navigation:** Helps agents learn the layout of the "macro-dungeon" before they’ve found the final exit.  
+
+🛠 Usage Example  
+You can stack wrappers to create complex experimental setups:
+``` python
+import gymnasium as gym
+from boltcrypt.env import BoltCrypt
+from boltcrypt.wrapper import NaturalLanguage, RoomDiscoveryReward
+
+env = BoltCrypt()
+env = RoomDiscoveryReward(env, discovery_reward=0.5)
+env = NaturalLanguage(env)
+
+# Now the agent receives text and extra rewards for exploration!
+obs, info = env.reset()
+print(obs) 
+
+action = "NORTH"
+obs, reward, done, trunc, info = env.step(action)
+```
+
+
+Happy Dungeon Crawling! 🗝️🏹

boltcrypt-0.1.0/README.md

@@ -0,0 +1,105 @@
+# BoltCrypt: Procedural Dungeon RL Environment #
+BoltCrypt is a lightweight, OpenAI Gymnasium-compatible environment featuring procedurally generated dungeons. It challenges Reinforcement Learning agents (and humans!) to navigate complex layouts, solve sokoban-style boulder puzzles, and manage inventory items like keys to reach the exit.
+## 🏰 Features ##
+Procedural Generation: Every reset generates a unique dungeon layout based on configurable parameters (density, connectivity, room size).
+Puzzle Mechanics: Includes boulder-pushing puzzles and locked doors that require finding a key.
+Gymnasium API: Fully compatible with standard RL workflows.
+Pygame Visualization: A built-in harness to play manually or watch your agent learn in real-time.
+Flexible Observation Space: Provides local room grids, global coordinates, and inventory status.
+🛠 Installation
+Since this project uses condavenv, ensure you have your environment active:
+``` bash
+# Example if using conda directly
+conda activate <your-env-name>
+pip install gymnasium pygame numpy matplotlib boltcrypt
+```
+
+## 🚀 Getting Started ##
+### Play Manually ###
+Test the dungeon generation and mechanics yourself using the Pygame harness:
+``` bash
+python boltcrypt_game.py
+```
+
+**Arrows:** Move the agent.  
+**R:** Reset/Regenerate the dungeon.  
+**Goal:** Find the key (if required) and reach the green Exit tile. 
+
+### Train an Agent ###  
+The project includes a tabular Q-Learning implementation to demonstrate how an agent can "memorize" a specific dungeon layout:
+``` bash
+python tabular_q.py
+```
+
+## ⚙️ Configuration ##
+
+The DungeonGenerator and BoltCrypt environment can be customized via a config dictionary:  
+
+### Parameter Description ###  
+**min_dist:** Minimum Manhattan distance between Start and Exit.  
+**mean_rooms:** Average number of rooms in the dungeon.  
+**connectivity:** Probability of creating loops between rooms (0.0 = Tree, 1.0 = Highly connected).  
+**puzzle_density:** Chance of a room containing a boulder puzzle.  
+**key_puzzle_prob:** Chance that the exit is locked and a key is hidden in a leaf room.  
+
+
+### 🗺 Tile Legend ###
+⬜ Floor: Walkable space.  
+⬛ Wall: Impassable.  
+🚪 Door: Transitions between rooms (may be locked by puzzles).  
+🟩 Exit: Your goal!  
+🔴 Switch: Target for boulders.  
+🟤 Boulder: Can be pushed onto switches.  
+🟡 Key: Required to open locked exit rooms.  
+
+
+### 🤖 Observation Space ###
+The environment returns a dictionary:  
+**grid:** A 10x10 local view of the current room.  
+**agent_pos:** (x, y) coordinates within the room.  
+**global_pos:** (gx, gy) coordinates in the dungeon layout.  
+**inventory:** Binary flag (1 if holding a key)  
+
+## 📦 Wrappers & Extensions ##
+BoltCrypt includes several gym.Wrapper implementations to modify observations or rewards, making it a versatile 
+testbed for different RL paradigms.
+
+### 📝 Natural Language Wrapper (NaturalLanguage) ####
+The crown jewel for testing Reasoning LLMs. This wrapper transforms the numeric observation space into a rich, 
+descriptive narrative. Instead of a grid, the agent receives a text-based description of its surroundings.  
+**Dynamic Narrative:** Provides room dimensions, relative positions of doors, boulder locations, and puzzle statuses 
+(e.g., "A loud mechanical clank echoes! The doors unlock.").  
+**LLM Ready:** Accepts string inputs like "NORTH", "SOUTH", "EAST", or "WEST" in the step() function.  
+**Physics Logic:** Includes an "Adventurer's Manual" to explain game rules to an LLM via the observation stream.  
+
+### 🌫️ Fog of War (FogOfWarWrapper) ###
+Transforms the global room view into a partially observable environment.  
+**Vision Range:** Limits the grid observation to a (2v+1) \times (2v+1) window centered on the agent.  
+**Memory Challenge:** Forces agents to map the room internally rather than having perfect spatial information.  
+
+### 🏆 Room Discovery Reward (RoomDiscoveryReward) ###
+Combats sparse rewards in large dungeons by incentivizing exploration.  
+**Exploration Bonus:** Grants a small configurable reward (e.g., +0.1) the first time the agent enters a new room in the dungeon.  
+**Global Navigation:** Helps agents learn the layout of the "macro-dungeon" before they’ve found the final exit.  
+
+🛠 Usage Example  
+You can stack wrappers to create complex experimental setups:
+``` python
+import gymnasium as gym
+from boltcrypt.env import BoltCrypt
+from boltcrypt.wrapper import NaturalLanguage, RoomDiscoveryReward
+
+env = BoltCrypt()
+env = RoomDiscoveryReward(env, discovery_reward=0.5)
+env = NaturalLanguage(env)
+
+# Now the agent receives text and extra rewards for exploration!
+obs, info = env.reset()
+print(obs) 
+
+action = "NORTH"
+obs, reward, done, trunc, info = env.step(action)
+```
+
+
+Happy Dungeon Crawling! 🗝️🏹

boltcrypt-0.1.0/boltcrypt/__init__.py

@@ -0,0 +1,7 @@
+from gymnasium.envs.registration import register
+
+register(
+    id='BoltCrypt-v0',
+    entry_point='boltcrypt.env:BoltCrypt',
+    max_episode_steps=1000
+)

boltcrypt-0.1.0/boltcrypt/examples/tabular_q.py

@@ -0,0 +1,96 @@
+import boltcrypt
+import gymnasium as gym
+
+import numpy as np
+import random
+import matplotlib.pyplot as plt
+from collections import defaultdict
+
+
+def train_tabular_agent():
+    config = {
+        'min_dist': 5,  # Small dungeon for fast learning
+        'mean_rooms': 10,  # ~10 Rooms total
+        'std_rooms': 0,  # Fixed size
+        'puzzle_density': 0.0,  # No puzzles, just navigation
+        'connectivity': 0.2,  # Mostly tree-like, few loops
+        'min_room_dim': 5,
+        'max_room_dim': 8
+    }
+
+    env = gym.make('BoltCrypt-v0', generator_config=config)
+
+    # 2. Hyperparameters
+    num_episodes = 1000
+    learning_rate = 0.1
+    discount_factor = 0.99
+
+    # Exploration (Epsilon Greedy)
+    epsilon = 1.0
+    epsilon_decay = 0.99
+    min_epsilon = 0.05
+
+    # The Q-Table
+    # Key: (global_x, global_y, local_x, local_y)
+    # Value: [Q_north, Q_south, Q_east, Q_west]
+    q_table = defaultdict(lambda: np.zeros(4))
+
+    episode_rewards = []
+    episode_lengths = []
+
+    print("--- Starting Training ---")
+    print(f"Map Config: Min Dist {config['min_dist']}, Total Rooms ~{config['mean_rooms']}")
+
+    for episode in range(num_episodes):
+        # Reset with FIXED SEED for every episode
+        # This ensures the map layout (Walls/Doors) never changes,
+        # allowing the agent to memorize the route.
+        obs, _ = env.reset(seed=42)
+
+        gx, gy = obs['global_pos']
+        lx, ly = obs['agent_pos']
+        state = (gx, gy, lx, ly)
+
+        total_reward = 0
+        done = False
+        steps = 0
+
+        while not done:
+            if random.random() < epsilon:
+                action = env.action_space.sample()  # Explore
+            else:
+                action = np.argmax(q_table[state])  # Exploit
+
+            next_obs, reward, done, trunc, _ = env.step(action)
+
+            next_gx, next_gy = next_obs['global_pos']
+            next_lx, next_ly = next_obs['agent_pos']
+            next_state = (next_gx, next_gy, next_lx, next_ly)
+
+            best_next_q = np.max(q_table[next_state])
+            current_q = q_table[state][action]
+
+            q_table[state][action] = current_q + learning_rate * (reward + discount_factor * best_next_q - current_q)
+
+            state = next_state
+            total_reward += reward
+            steps += 1
+
+            if trunc: break
+
+        epsilon = max(min_epsilon, epsilon * epsilon_decay)
+
+        episode_rewards.append(total_reward)
+        episode_lengths.append(steps)
+
+        if (episode + 1) % 50 == 0:
+            avg_rew = np.mean(episode_rewards[-50:])
+            avg_len = np.mean(episode_lengths[-50:])
+            print(
+                f"Episode {episode + 1:03d} | Avg Reward: {avg_rew:6.2f} | Avg Steps: {avg_len:6.1f} | Epsilon: {epsilon:.2f}")
+
+    return episode_rewards, episode_lengths
+
+
+if __name__ == "__main__":
+    rewards, lengths = train_tabular_agent()

boltcrypt-0.1.0/boltcrypt/game/boltcrypt_game.py

@@ -0,0 +1,136 @@
+import pygame
+from boltcrypt.env import BoltCrypt
+
+# --- PYGAME HARNESS ---
+# Update Constants for Visualization
+COLORS = {
+    0: (230, 215, 180), # Floor
+    1: (40, 40, 40),    # Wall
+    2: (139, 69, 19),   # Door
+    3: (0, 255, 0),     # Exit
+    4: (200, 50, 50),   # Switch
+    5: (100, 80, 50),   # Boulder
+    6: (255, 215, 0),   # KEY (Gold)
+    'AGENT': (50, 100, 200),
+    'BG': (20, 20, 20),
+    'TEXT': (255, 255, 255)
+}
+
+def render_gym(screen, font, env, obs, reward, done, text_status):
+    screen.fill(COLORS['BG'])
+    grid = obs['grid']
+    agent_pos = obs['agent_pos']
+    global_pos = obs['global_pos']
+    has_key = obs['inventory']
+
+    # Draw Map
+    rows, cols = grid.shape
+    TILE_SIZE = 48
+    OFFSET_X, OFFSET_Y = 50, 50
+
+    for y in range(rows):
+        for x in range(cols):
+            rect = pygame.Rect(OFFSET_X + x*TILE_SIZE, OFFSET_Y + (rows-1-y)*TILE_SIZE, TILE_SIZE, TILE_SIZE)
+            tile_id = grid[y, x]
+
+            # Void vs Room
+            if x >= env.curr_room.w or y >= env.curr_room.h:
+                pygame.draw.rect(screen, (0,0,0), rect)
+            else:
+                if tile_id == 5:
+                    pygame.draw.circle(screen, COLORS.get(tile_id), rect.center, 16)
+                else:
+                    color = COLORS.get(tile_id, (255, 0, 255))
+                    pygame.draw.rect(screen, color, rect)
+                    pygame.draw.rect(screen, (0,0,0), rect, 1)
+
+                if tile_id == 6:
+                    pygame.draw.circle(screen, (255, 255, 0), rect.center, 10)
+
+    # Draw Agent
+    ax, ay = agent_pos
+    agent_rect = pygame.Rect(OFFSET_X + ax*TILE_SIZE, OFFSET_Y + (rows-1-ay)*TILE_SIZE, TILE_SIZE, TILE_SIZE)
+    pygame.draw.circle(screen, COLORS['AGENT'], agent_rect.center, 16)
+
+    # HUD
+    status = "SOLVED" if env.curr_room.check_solved() else "PUZZLE ACTIVE"
+    inv_text = "KEY: [YES]" if has_key else "KEY: [NO]"
+    inv_col = (0, 255, 0) if has_key else (150, 150, 150)
+
+    # Locked Room Warning
+    is_locked_room = env.curr_room.is_locked
+    room_type = "LOCKED EXIT (Need Key)" if is_locked_room else "Normal Room"
+
+    lines = [
+        f"Pos: {global_pos} | Local: {agent_pos}",
+        f"Room Status: {status}",
+        f"Room Type: {room_type}",
+        f"Inventory: {inv_text}",
+        f"Reward: {reward:.2f}",
+        f"{text_status}"
+    ]
+
+    for i, line in enumerate(lines):
+        col = COLORS['TEXT']
+        if "Inventory" in line: col = inv_col
+        if "LOCKED EXIT" in line: col = (255, 50, 50)
+
+        surf = font.render(line, True, col)
+        screen.blit(surf, (10, 600 + i*25))
+
+def play_dungeon():
+    # Config with Key Puzzle Enabled
+    config = {
+        'min_dist': 3,
+        'mean_rooms': 10,
+        'std_rooms': 2,
+        'puzzle_density': 0.3, # Disable boulder puzzles to focus on Key testing
+        'key_puzzle_prob': 0.25,
+        'min_room_dim': 5,
+        'max_room_dim': 8
+    }
+    env = BoltCrypt(generator_config=config)
+    obs, _ = env.reset()
+    total_reward = 0
+
+    pygame.init()
+    screen = pygame.display.set_mode((600, 750))
+    pygame.display.set_caption("Boltcrypt")
+    font = pygame.font.Font(None, 24)
+    clock = pygame.time.Clock()
+
+    running = True
+    done = False
+
+    while running:
+        action = None
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT: running = False
+            if event.type == pygame.KEYDOWN:
+                if event.key == pygame.K_r:
+                    obs, _ = env.reset()
+                    total_reward = 0
+                    done = False
+                if not done:
+                    if event.key == pygame.K_UP: action = 0
+                    elif event.key == pygame.K_DOWN: action = 1
+                    elif event.key == pygame.K_RIGHT: action = 2
+                    elif event.key == pygame.K_LEFT: action = 3
+
+        if not done:
+            status = "Press R to Restart"
+        else:
+            status = "YOU ESCAPED! Press R to Restart"
+        if action is not None:
+            obs, reward, done, trunc, info = env.step(action)
+            total_reward += reward
+            if reward == 1.0 and obs['inventory'] == 1: status = "🔑 KEY FOUND!"
+
+        render_gym(screen, font, env, obs, total_reward, done, status)
+        pygame.display.flip()
+        clock.tick(30)
+
+    pygame.quit()
+
+if __name__ == "__main__":
+    play_dungeon()

boltcrypt-0.1.0/boltcrypt/wrapper/__init__.py

@@ -0,0 +1,3 @@
+from .roomdiscoveryreward import RoomDiscoveryReward
+from .fogofwar import FogOfWarWrapper
+from .natlang import NaturalLanguage

boltcrypt-0.1.0/boltcrypt/wrapper/fogofwar.py

@@ -0,0 +1,22 @@
+import gymnasium as gym
+
+from boltcrypt.env.boltgym import TILE_WALL
+
+class FogOfWarWrapper(gym.ObservationWrapper):
+    def __init__(self, env, vision_range=1):
+        super().__init__(env)
+        self.vision_range = vision_range
+
+    def observation(self, obs):
+        grid = obs['grid']
+        lx, ly = obs['agent_pos']
+
+        # Pad grid to handle edges
+        padded = np.pad(grid, self.vision_range, constant_values=TILE_WALL)
+
+        # Slice the window (adjusting for padding)
+        v = self.vision_range
+        window = padded[ly:ly + 2*v + 1, lx:lx + 2*v + 1]
+
+        obs['grid'] = window
+        return obs

boltcrypt-0.1.0/boltcrypt/wrapper/natlang.py

@@ -0,0 +1,200 @@
+import gymnasium as gym
+
+class NaturalLanguage(gym.Wrapper):
+    def __init__(self, env):
+        super().__init__(env)
+        self.last_gx, self.last_gy = None, None
+        self.last_solved = True
+        self.last_boulder_positions = []
+        self.entry_direction = None
+        self.last_obs = None
+
+        # Help text to be displayed once or upon request
+        self.manual_text = (
+            "\n--- ADVENTURER'S MANUAL ---\n"
+            "COMMANDS: This interface is primitive. It only accepts 4 commands:\n"
+            "  'NORTH', 'SOUTH', 'EAST', 'WEST'\n\n"
+            "PHYSICS:\n"
+            "- Movement: Typing a direction moves you 1 tile.\n"
+            "- Pushing: To move a boulder, walk INTO it. You will push it 1 tile forward.\n"
+            "- Constraints: Boulders are heavy. You cannot push them against walls or corners.\n"
+            "- Door Locks: If a room has switches, all doors stay locked until every switch is covered.\n"
+            "---------------------------\n"
+        )
+
+    def reset(self, **kwargs):
+        obs, info = self.env.reset(**kwargs)
+
+        self.last_gx, self.last_gy = obs['global_pos']
+        self.last_solved = self.env.curr_room.check_solved()
+        self.last_boulder_positions = [list(b) for b in self.env.curr_room.boulders]
+        self.entry_direction = "Start"
+        self.last_obs = obs
+
+        # Narrative initialization
+        objective_text = (
+            "MISSION: Escape the Labyrinth. Find the EXIT room located at a great distance.\n"
+            f"{self.manual_text}"
+            "You wake up on the cold floor. The journey begins."
+        )
+
+        return self._generate_narrative(obs, 0, False, objective_text), info
+
+    def step(self, action_input: str|int):
+        # Handle string input for LLMs
+        if isinstance(action_input, str):
+            cmd = action_input.lower().strip()
+            if cmd == "north": action = 0
+            elif cmd == "south": action = 1
+            elif cmd == "east": action = 2
+            elif cmd == "west": action = 3
+            elif cmd == "help":
+                return self._generate_narrative(self.last_obs, 0, False, self.manual_text), 0, False, False, {}
+            else:
+                return "Unknown command. Use NORTH, SOUTH, EAST, WEST, or HELP.", 0, False, False, {}
+        else:
+            action = action_input
+
+        # 1. Pre-Step State Capture
+        prev_room = self.env.curr_room
+        prev_boulders = [list(b) for b in prev_room.boulders]
+
+        # 2. Execute Step
+        obs, reward, done, trunc, info = self.env.step(action)
+
+        # 3. Analyze What Happened
+        event_log = []
+
+        # A. Room Transition Check
+        curr_gx, curr_gy = obs['global_pos']
+        just_entered_room = (curr_gx != self.last_gx or curr_gy != self.last_gy)
+
+        if just_entered_room:
+            # Determine Entry Direction
+            dx = curr_gx - self.last_gx
+            dy = curr_gy - self.last_gy
+            if dy == 1: self.entry_direction = "South" # Moved North, entered from South
+            elif dy == -1: self.entry_direction = "North"
+            elif dx == 1: self.entry_direction = "West"
+            elif dx == -1: self.entry_direction = "East"
+
+            event_log.append(f"You pass through the door and enter a new room from the {self.entry_direction}.")
+
+            # Reset room-specific memory
+            self.last_gx, self.last_gy = curr_gx, curr_gy
+            self.last_boulder_positions = [list(b) for b in self.env.curr_room.boulders]
+            self.last_solved = self.env.curr_room.check_solved()
+
+        else:
+            # B. Push/Blocked Check
+            # Check if we moved?
+            # Check if a boulder moved?
+            curr_boulders = self.env.curr_room.boulders
+            boulder_moved = False
+
+            for i, b_new in enumerate(curr_boulders):
+                if b_new != prev_boulders[i]:
+                    # Boulder Moved!
+                    boulder_moved = True
+                    # Check if it landed on a switch
+                    on_switch = tuple(b_new) in self.env.curr_room.switches
+                    click = " *CLICK!*" if on_switch else ""
+                    event_log.append(f"You push the heavy boulder. It grinds across the floor.{click}")
+                    break
+
+            if not boulder_moved and reward < 0:
+                # Heuristic: Negative reward usually implies wall bonk or time waste
+                # But we strictly want 'Wall Bump' detection.
+                # We can infer it if agent pos didn't change AND action was taken
+                pass # (Simplified for brevity, usually LLM can infer from 'You are at same pos')
+
+        # C. Puzzle Status Change
+        is_now_solved = self.env.curr_room.check_solved()
+        if is_now_solved and not self.last_solved:
+            event_log.append("A loud mechanical clank echoes! The doors unlock.")
+        elif not is_now_solved and self.last_solved and self.env.curr_room.has_puzzle:
+            event_log.append("The mechanism disengages. The doors slam shut!")
+
+        self.last_solved = is_now_solved
+        self.last_boulder_positions = [list(b) for b in self.env.curr_room.boulders]
+
+        # 4. Generate Full Text
+        text_obs = self._generate_narrative(obs, reward, done, " ".join(event_log))
+
+        return text_obs, reward, done, trunc, info
+
+    def _generate_narrative(self, obs, reward, done, event_text):
+        room = self.env.curr_room
+        lx, ly = obs['agent_pos']
+
+        # --- 1. The Header ---
+        puzzle_status = "SOLVED" if room.is_solved else "LOCKED"
+        narrative = [f"--- {puzzle_status} ROOM ({room.w}x{room.h}) ---"]
+
+        if event_text:
+            narrative.append(f"> {event_text}")
+
+        # --- 2. Relative Positioning (The "Where am I" Logic) ---
+        narrative.append(f"You are standing at coordinate ({lx}, {ly}).")
+
+        # List Doors relative to agent
+        doors_desc = []
+        for direction, offset in room.doors.items():
+            d_name = direction.name.title()
+
+            # Distance Calculation
+            # North (top), South (bottom), East (right), West (left)
+            # North door is at (offset, h-1)
+            dist_str = ""
+            if direction.name == "NORTH":
+                dist = (room.h - 1) - ly
+                dist_str = f"{dist} steps North"
+            elif direction.name == "SOUTH":
+                dist = ly
+                dist_str = f"{dist} steps South"
+            elif direction.name == "EAST":
+                dist = (room.w - 1) - lx
+                dist_str = f"{dist} steps East"
+            elif direction.name == "WEST":
+                dist = lx
+                dist_str = f"{dist} steps West"
+
+            state = "(OPEN)" if room.is_solved else "(LOCKED)"
+            doors_desc.append(f"- {d_name} Door: {dist_str} {state}")
+
+        narrative.append("Exits:")
+        narrative.extend(doors_desc)
+
+        # --- 3. Puzzle Elements ---
+        if room.has_puzzle:
+            narrative.append("Puzzle Elements:")
+            # Boulders
+            for i, b in enumerate(room.boulders):
+                bx, by = b[1], b[0] # Note: grid is (y,x), obs is usually (x,y) for text
+
+                # Check if on switch
+                on_switch = (by, bx) in room.switches
+                status = "sitting on a switch" if on_switch else "on the bare floor"
+
+                # Relative direction from agent
+                rel_dir = []
+                if by > ly: rel_dir.append("North")
+                elif by < ly: rel_dir.append("South")
+                if bx > lx: rel_dir.append("East")
+                elif bx < lx: rel_dir.append("West")
+
+                dir_str = "-".join(rel_dir) if rel_dir else "HERE"
+                narrative.append(f"- Boulder {i+1}: Located at ({bx}, {by}) [{dir_str} of you]. It is {status}.")
+
+            # Empty Switches
+            for s in room.switches:
+                sy, sx = s
+                # Is there a boulder on it?
+                covered = any(b[0] == sy and b[1] == sx for b in room.boulders)
+                if not covered:
+                    narrative.append(f"- Empty Switch: Located at ({sx}, {sy}).")
+
+        if done:
+            narrative.append("\n*** YOU HAVE FOUND THE EXIT! ***")
+
+        return "\n".join(narrative)

boltcrypt-0.1.0/boltcrypt/wrapper/roomdiscoveryreward.py

@@ -0,0 +1,24 @@
+import gymnasium as gym
+
+class RoomDiscoveryReward(gym.Wrapper):
+    def __init__(self, env, discovery_reward=0.1):
+        super().__init__(env)
+        self.discovery_reward = discovery_reward
+        self.visited_rooms = set()
+
+    def reset(self, **kwargs):
+        obs, info = self.env.reset(**kwargs)
+        start_pos = tuple(obs['global_pos'])
+        self.visited_rooms = {start_pos}
+        return obs, info
+
+    def step(self, action):
+        obs, reward, terminated, truncated, info = self.env.step(action)
+
+        curr_pos = tuple(obs['global_pos'])
+
+        if curr_pos not in self.visited_rooms:
+            reward += self.discovery_reward
+            self.visited_rooms.add(curr_pos)
+
+        return obs, reward, terminated, truncated, info

boltcrypt-0.1.0/boltcrypt.egg-info/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: boltcrypt
+Version: 0.1.0
+Summary: Boltcrypt environment
+Author: foreverska
+Project-URL: Github:, https://github.com/foreverska/boltcrypt
+Keywords: gymnasium,gym
+Description-Content-Type: text/markdown
+License-File: license.txt
+Requires-Dist: gymnasium>=1.0.0
+Requires-Dist: numpy
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: summary
+
+# BoltCrypt: Procedural Dungeon RL Environment #
+BoltCrypt is a lightweight, OpenAI Gymnasium-compatible environment featuring procedurally generated dungeons. It challenges Reinforcement Learning agents (and humans!) to navigate complex layouts, solve sokoban-style boulder puzzles, and manage inventory items like keys to reach the exit.
+## 🏰 Features ##
+Procedural Generation: Every reset generates a unique dungeon layout based on configurable parameters (density, connectivity, room size).
+Puzzle Mechanics: Includes boulder-pushing puzzles and locked doors that require finding a key.
+Gymnasium API: Fully compatible with standard RL workflows.
+Pygame Visualization: A built-in harness to play manually or watch your agent learn in real-time.
+Flexible Observation Space: Provides local room grids, global coordinates, and inventory status.
+🛠 Installation
+Since this project uses condavenv, ensure you have your environment active:
+``` bash
+# Example if using conda directly
+conda activate <your-env-name>
+pip install gymnasium pygame numpy matplotlib boltcrypt
+```
+
+## 🚀 Getting Started ##
+### Play Manually ###
+Test the dungeon generation and mechanics yourself using the Pygame harness:
+``` bash
+python boltcrypt_game.py
+```
+
+**Arrows:** Move the agent.  
+**R:** Reset/Regenerate the dungeon.  
+**Goal:** Find the key (if required) and reach the green Exit tile. 
+
+### Train an Agent ###  
+The project includes a tabular Q-Learning implementation to demonstrate how an agent can "memorize" a specific dungeon layout:
+``` bash
+python tabular_q.py
+```
+
+## ⚙️ Configuration ##
+
+The DungeonGenerator and BoltCrypt environment can be customized via a config dictionary:  
+
+### Parameter Description ###  
+**min_dist:** Minimum Manhattan distance between Start and Exit.  
+**mean_rooms:** Average number of rooms in the dungeon.  
+**connectivity:** Probability of creating loops between rooms (0.0 = Tree, 1.0 = Highly connected).  
+**puzzle_density:** Chance of a room containing a boulder puzzle.  
+**key_puzzle_prob:** Chance that the exit is locked and a key is hidden in a leaf room.  
+
+
+### 🗺 Tile Legend ###
+⬜ Floor: Walkable space.  
+⬛ Wall: Impassable.  
+🚪 Door: Transitions between rooms (may be locked by puzzles).  
+🟩 Exit: Your goal!  
+🔴 Switch: Target for boulders.  
+🟤 Boulder: Can be pushed onto switches.  
+🟡 Key: Required to open locked exit rooms.  
+
+
+### 🤖 Observation Space ###
+The environment returns a dictionary:  
+**grid:** A 10x10 local view of the current room.  
+**agent_pos:** (x, y) coordinates within the room.  
+**global_pos:** (gx, gy) coordinates in the dungeon layout.  
+**inventory:** Binary flag (1 if holding a key)  
+
+## 📦 Wrappers & Extensions ##
+BoltCrypt includes several gym.Wrapper implementations to modify observations or rewards, making it a versatile 
+testbed for different RL paradigms.
+
+### 📝 Natural Language Wrapper (NaturalLanguage) ####
+The crown jewel for testing Reasoning LLMs. This wrapper transforms the numeric observation space into a rich, 
+descriptive narrative. Instead of a grid, the agent receives a text-based description of its surroundings.  
+**Dynamic Narrative:** Provides room dimensions, relative positions of doors, boulder locations, and puzzle statuses 
+(e.g., "A loud mechanical clank echoes! The doors unlock.").  
+**LLM Ready:** Accepts string inputs like "NORTH", "SOUTH", "EAST", or "WEST" in the step() function.  
+**Physics Logic:** Includes an "Adventurer's Manual" to explain game rules to an LLM via the observation stream.  
+
+### 🌫️ Fog of War (FogOfWarWrapper) ###
+Transforms the global room view into a partially observable environment.  
+**Vision Range:** Limits the grid observation to a (2v+1) \times (2v+1) window centered on the agent.  
+**Memory Challenge:** Forces agents to map the room internally rather than having perfect spatial information.  
+
+### 🏆 Room Discovery Reward (RoomDiscoveryReward) ###
+Combats sparse rewards in large dungeons by incentivizing exploration.  
+**Exploration Bonus:** Grants a small configurable reward (e.g., +0.1) the first time the agent enters a new room in the dungeon.  
+**Global Navigation:** Helps agents learn the layout of the "macro-dungeon" before they’ve found the final exit.  
+
+🛠 Usage Example  
+You can stack wrappers to create complex experimental setups:
+``` python
+import gymnasium as gym
+from boltcrypt.env import BoltCrypt
+from boltcrypt.wrapper import NaturalLanguage, RoomDiscoveryReward
+
+env = BoltCrypt()
+env = RoomDiscoveryReward(env, discovery_reward=0.5)
+env = NaturalLanguage(env)
+
+# Now the agent receives text and extra rewards for exploration!
+obs, info = env.reset()
+print(obs) 
+
+action = "NORTH"
+obs, reward, done, trunc, info = env.step(action)
+```
+
+
+Happy Dungeon Crawling! 🗝️🏹

boltcrypt-0.1.0/boltcrypt.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+license.txt
+setup.py
+boltcrypt/__init__.py
+boltcrypt.egg-info/PKG-INFO
+boltcrypt.egg-info/SOURCES.txt
+boltcrypt.egg-info/dependency_links.txt
+boltcrypt.egg-info/entry_points.txt
+boltcrypt.egg-info/requires.txt
+boltcrypt.egg-info/top_level.txt
+boltcrypt/examples/tabular_q.py
+boltcrypt/game/boltcrypt_game.py
+boltcrypt/wrapper/__init__.py
+boltcrypt/wrapper/fogofwar.py
+boltcrypt/wrapper/natlang.py
+boltcrypt/wrapper/roomdiscoveryreward.py

boltcrypt-0.1.0/boltcrypt.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

boltcrypt-0.1.0/boltcrypt.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+boltcrypt = boltcrypt.game.boltcrypt_game:play_dungeon
+
+[gym.envs]
+boltcrypt = boltcrypt.env:BoltCrypt

boltcrypt-0.1.0/boltcrypt.egg-info/requires.txt

@@ -0,0 +1,2 @@
+gymnasium>=1.0.0
+numpy

boltcrypt-0.1.0/boltcrypt.egg-info/top_level.txt

@@ -0,0 +1 @@
+boltcrypt

boltcrypt-0.1.0/license.txt

@@ -0,0 +1,7 @@
+Copyright 2025 Adam Parker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

boltcrypt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

boltcrypt-0.1.0/setup.py

@@ -0,0 +1,22 @@
+from importlib.metadata import entry_points
+
+from setuptools import setup
+
+long_description = open('README.md').read()
+
+setup(
+    name="boltcrypt",
+    description="Boltcrypt environment",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    version="0.1.0",
+    author="foreverska",
+    install_requires=["gymnasium>=1.0.0", "numpy"],
+    keywords="gymnasium, gym",
+    license_files = ('license.txt',),
+    project_urls={"Github:": "https://github.com/foreverska/boltcrypt"},
+    entry_points={
+        'gym.envs': ['boltcrypt=boltcrypt.env:BoltCrypt'],
+        'console_scripts': 'boltcrypt=boltcrypt.game.boltcrypt_game:play_dungeon'
+    }
+)