TALES: Text-Adventure Learning Environment Suite

This repository contains the files needed to benchmark language agents on a curated list of text-based games from the following frameworks: Jericho, TextWorld, TextWorld-Express, ScienceWorld, ALFWorld).

[Technical Report] [Project Page]

1. Installation

It is recommended to create and activate a conda or virtual environment. tales requires Python>=3.12:

conda create -n tales python=3.12
conda activate tales

Then, install tales directly from PyPI:

pip install tale-suite

[!WARNING] The name of the Python package on PyPI is tale-suite and not tales.

Alternatively, clone the repository and install locally:

git clone https://github.com/microsoft/tale-suite
cd tale-suite
pip install -e .

[!WARNING] You will need Java 1.8+ installed to run the environments TextWorld-Express and ScienceWorld.

sudo apt update && apt install openjdk-8-jre-headless -y

Alternatively, if the above isn't working:

 sudo apt-get update && apt-get install default-jre default-jdk

Using Docker

We provide a pre-built docker image at

docker pull czcui/twb:prebuilt

Please see the following docs page for more details on how to set up a local vllm for use with the text world benchmark.

An example script can be found in the scripts folder.

2. Getting Started

1. Run benchmark evaluation on all the games for the specified random agent:

   python benchmark.py random
   
   

2. Run benchmark evaluation on a subset of the games:

   python benchmark.py random --env textworld
   
   

3. Run benchmark evaluation on specific games:

   python benchmark.py random --envs JerichoEnvZork1 JerichoEnvDetective
   
   

4. Run benchmark evaluation using as a HumanAgent:

   python benchmark.py human --envs TWCookingLevel1
   
   

5. Run benchmark evaluation where the ground-truth walkthrough is being followed:

   python benchmark.py walkthrough --envs JerichoEnvZork1
   
   

3. Benchmarking LLMs

In order to benchmark a given LLM acting as language agent playing text-based games, you will need to first configure it. tales is leveraging the llm library to handle communication with different LLMs.

python benchmark.py zero-shot --envs TWCookingLevel1

Continuing a Previous Run

Use the --continue-from flag to replay a previous wandb-logged trajectory. The replay is deterministic (no LLM calls) and preserves the original token usage stats. This is useful for:

• Extending a short run (e.g., 100 steps → 1000): replays the original trajectory, then lets the LLM take over for the remaining steps.
• Reproducing a previous run exactly: set --nb-steps equal to or less than the original run's length to replay without any new LLM calls.

When auto-finding, the longest matching run is always selected and truncated to --nb-steps if needed.

With an explicit run ID:

python benchmark.py reasoning --llm gpt-4o --conversation --continue-from <wandb_run_id> --nb-steps 1000 --envs JerichoEnvZork1 --wandb

Auto-find matching run (searches wandb for a run matching the current game, agent, and seed):

python benchmark.py reasoning --llm gpt-4o --conversation --continue-from --nb-steps 1000 --envs JerichoEnvZork1 --wandb

How it works:

1. Fetches the original run's config and rollout from the wandb API (or auto-finds the longest matching run)
2. Truncates the trajectory to --nb-steps if the original run is longer
3. Recreates the environment with the same seed for deterministic replay
4. Replays recorded actions (no LLM calls, preserving original token usage stats)
5. Verifies observations match the logged trajectory (warns on divergence)
6. If the game completed during replay (max score reached), stops early
7. Otherwise, hands off to the LLM agent for any remaining steps
8. Logs as a new wandb run referencing the original run ID

[!NOTE] The --continue-from flag expects a wandb run ID (e.g., abc123de) from your wandb project, or no value to auto-find. The agent type and parameters must match the original run. When auto-finding, if no matching run is found, the game runs from scratch.

API-based LLMs

llm natively supports OpenAI models and self-hosted models that offer an OpenAI-compatible API (e.g. like vLLM does - more on this below).

Adding support to other LLMs

llm offers different plugins to include other LLMs. E.g.

llm install llm-anthropic

See the llmplugins page for more information.

Deploying a model locally using vLLM

To serve a custom HugginFace model with vLLM, one can use the vllm docker image like this:

docker run --runtime nvidia --gpus all --restart unless-stopped --name vllm-Llama-3.1-8B-Instruct --env "HUGGING_FACE_HUB_TOKEN=${HUGGING_FACE_HUB_TOKEN}" -v ~/.cache/huggingface:/root/.cache/huggingface -p 8000:8000 --ipc=host vllm/vllm-openai:latest --model meta-llama/Llama-3.1-8B-Instruct --tensor-parallel-size 4 --host 0.0.0.0

Then, add the following entrypoint in ~/.config/io.datasette.llm/extra-openai-models.yaml

- model_id: meta-llama/Llama-3.1-8B-Instruct
  model_name: meta-llama/Llama-3.1-8B-Instruct
  api_base: "http://0.0.0.0:8000/v1"

You can check that everything is working properly with this simple command:

llm -m meta-llama/Llama-3.1-8B-Instruct "Hi. What's your name?"

4. Building Custom Agents

To build a custom agent, you need to create a new file (e.g., custom.py) and implement the Agent class and implement the proper arguments parser.

This is the beginning of the README. Read the rest at the original. Read the full README ↗