jericho

Jericho serves as a specialized learning environment designed to facilitate research in Artificial Intelligence and Reinforcement Learning by connecting autonomous agents with man-made Interactive Fiction (IF) games. Built as a lightweight Python-based interface, it leverages the Frotz emulator to provide a standardized way for agents to interact with text-based adventure games. **Core Capabilities and Environment** The primary function of Jericho is to expose IF games as Gym-like environments, allowing researchers to train agents to navigate complex narrative structures through natural language commands. Key components include: * **Frotz Environment:** The core interface that handles game state, actions, and observations. * **Object Tree:** Provides structural insights into the game world, helping agents understand spatial relationships and object interactions. * **Game Dictionary:** Assists in parsing and understanding the vocabulary specific to each game. * **Template Action Generator:** A utility for creating valid action templates to guide agent exploration. **Version 4.0 Updates and Determinism** A significant change in Jericho 4.0 addresses the handling of random seeds to improve scientific rigor. Prior to this version, omitting a seed argument would silently use the game's walkthrough seed, making episodes deterministic. This behavior was identified as a handicap for learning agents, as it removed necessary stochasticity. In version 4.0: * **Stochastic by default:** If no seed is specified, a fresh random seed is drawn for each episode. * **Reproducibility:** The seed used in an episode is reported in the `reset()` info dictionary and accessible via `FrotzEnv.episode_seed`, allowing researchers to reproduce specific episodes after the fact. * **Walkthrough Control:** Users can explicitly request the walkthrough seed using `use_walkthrough_seed=True` in `reset()` or by accessing `env.walkthrough_seed`. An `ImplicitRandomSeedWarning` is issued if an agent begins an episode without an explicit seeding choice for games with known walkthroughs, encouraging best practices in experimental design. **Requirements and Installation** Jericho requires Linux, Python 3.12+, SpaCy, and basic build tools (gcc, make, curl). It is installable via pip, with dependencies managed through Conda or standard Python environments. The project includes extensive documentation covering quickstarts, API references, and utility functions. **Research Integration** The repository highlights several AI agents that have utilized Jericho for training, including Reading Comprehension Deep Q-Network (RCDQN), Contextual Action Language Model (CALM), Q*BERT, and Knowledge Graph Advantage Actor Critic (KG-A2C). This demonstrates its utility in testing natural language understanding, planning, and reinforcement learning algorithms in complex, text-based domains.