TextArena

0.7.4 · active · verified Thu Apr 16

TextArena is a Python library that provides a collection of competitive text-based games designed for evaluating language models and developing reinforcement learning agents. It offers a framework for defining games, creating agents (including human and GPT agents), and running competitive battles. As of version 0.7.4, it's under active development with a somewhat irregular release cadence, often introducing significant changes between minor versions.

Common errors

```
ModuleNotFoundError: No module named 'textarena.agent.base'
```
cause You are trying to import the Agent base class from an old path that was refactored in `textarena` version 0.7.0.

fix Update your import statement: `from textarena.agent.agent import Agent`.
```
TypeError: 'NoneType' object is not callable (often seen when using GPTAgent)
```
cause The `GPTAgent` was instantiated without a valid OpenAI API key, and thus could not initialize its OpenAI client. This typically happens when `OPENAI_API_KEY` environment variable is not set.

fix Ensure `OPENAI_API_KEY` environment variable is set or pass `api_key` directly to the `GPTAgent` constructor: `GPTAgent(name="MyGPT", api_key="YOUR_KEY_HERE")`.
```
ValueError: Game 'my_custom_game' not found in registry.
```
cause You are attempting to create an `Arena` instance with a `game_name` that has not been registered with TextArena's environment system.

fix Before initializing `Arena`, register your custom game class using `TextEnv.register_game("my_custom_game", MyCustomGameClass)`.

Warnings

breaking Agent import paths were refactored in version 0.7.0. Classes like `Agent` and `GPTAgent` moved from `textarena.agent.base` and `textarena.agent.lm_agent` respectively to `textarena.agent.agent`.
Fix: Update your import statements: `from textarena.agent.agent import Agent, GPTAgent`.
breaking The system for registering Agents and Environments was significantly refactored in version 0.6.0. Global registration via a central registry was removed and moved to a factory-like pattern, primarily `TextEnv.register_game`.
Fix: For custom games, ensure you use `TextEnv.register_game("game_name", GameClass)` before creating an `Arena` instance. Agent registration is less explicit, typically agents are instantiated directly.
gotcha Using `GPTAgent` requires a valid OpenAI API key. If not provided via an environment variable (`OPENAI_API_KEY`) or the `api_key` parameter, the agent will not be able to interact with the OpenAI API, leading to errors or dummy behavior.
Fix: Set the `OPENAI_API_KEY` environment variable (e.g., `export OPENAI_API_KEY="sk-..."`) or pass it directly: `GPTAgent(name="Agent", api_key="sk-...")`.
gotcha TextArena is in active `0.x.x` development, meaning minor version updates (e.g., `0.7.0` to `0.8.0`) can and do introduce breaking API changes. Always review the release notes when upgrading to a new minor version.
Fix: Consult the GitHub releases page (`https://github.com/microsoft/TextArena/releases`) for detailed changelogs and migration guides before upgrading.

Install

pip install textarena Install TextArena

Imports

Arena
```
from textarena.arena import Arena
```
Agent
wrong:
```
from textarena.agent.base import Agent
```
correct:
```
from textarena.agent.agent import Agent
```
Import path for base agent class changed in v0.7.0. Previously it was 'textarena.agent.base.Agent'.
GPTAgent
wrong:
```
from textarena.agent.lm_agent import GPTAgent
```
correct:
```
from textarena.agent.agent import GPTAgent
```
Import path for GPTAgent class changed in v0.7.0. Previously it was 'textarena.agent.lm_agent.GPTAgent'.

TextEnv

from textarena.env.text_env import TextEnv

Quickstart

This quickstart demonstrates how to set up and run a simple game (Prisoner's Dilemma) using two base agents in TextArena. It initializes agents, configures an Arena instance with a specified game, and then executes the game, printing the final scores and full game history. For GPT-powered agents, ensure your OpenAI API key is set as an environment variable.

import os
from textarena.arena import Arena
from textarena.agent.agent import Agent, GPTAgent
from textarena.env.text_env import TextEnv
from textarena.game.prisoner_dilemma import PrisonerDilemmaGame

# 1. TextArena comes with pre-registered games, e.g., 'prisoner_dilemma'.
# If you define a custom game, you'd register it like this before use:
# TextEnv.register_game("my_custom_game", MyCustomGameClass)

# 2. Create agents
# For demonstration, we'll use base Agents. They generate random actions.
agent1 = Agent(name="Alice", temperature=0.7)
agent2 = Agent(name="Bob", temperature=0.7)

# To use GPTAgent, ensure OPENAI_API_KEY is set in your environment.
# The 'sk-dummy-key' is a placeholder and will not work with actual OpenAI API calls.
openai_api_key = os.environ.get('OPENAI_API_KEY', 'sk-dummy-key')
# agent1 = GPTAgent(name="Alice", api_key=openai_api_key, model="gpt-3.5-turbo")
# agent2 = GPTAgent(name="Bob", api_key=openai_api_key, model="gpt-3.5-turbo")

# 3. Initialize and run the arena with a pre-registered game
arena = Arena(
    game_name="prisoner_dilemma", # Using a pre-registered game
    agents=[agent1, agent2],
    max_turns=3 # Number of rounds for the dilemma
)

print(f"Starting TextArena with {arena.game_name} for {arena.max_turns} turns...")
results = arena.run()

print("\nArena run complete. Final Results:")
for agent_name, score in results['score'].items():
    print(f"- {agent_name}: {score} points")

print("\nFull game history:")
for turn_idx, turn_log in enumerate(arena.game_env.get_history()):
    print(f"--- Turn {turn_idx + 1} ---")
    print(turn_log)

view raw JSON →