Metadata-Version: 2.1
Name: nle
Version: 1.3.0
Summary: The NetHack Learning Environment (NLE): a reinforcement learning environment based on NetHack
Author: The NLE Dev Team
License:                     NETHACK GENERAL PUBLIC LICENSE
                             (Copyright 1989 M. Stephenson)
         
                        (Based on the BISON general public license,
                            copyright 1988 Richard M. Stallman)
         
          Everyone is permitted to copy and distribute verbatim copies of this
          license, but changing it is not allowed.  You can also use this wording to
          make the terms for other programs.
         
           The license agreements of most software companies keep you at the mercy of
         those companies.  By contrast, our general public license is intended to give
         everyone the right to share NetHack.  To make sure that you get the rights we
         want you to have, we need to make restrictions that forbid anyone to deny you
         these rights or to ask you to surrender the rights.  Hence this license
         agreement.
         
           Specifically, we want to make sure that you have the right to give away
         copies of NetHack, that you receive source code or else can get it if you
         want it, that you can change NetHack or use pieces of it in new free
         programs, and that you know you can do these things.
         
           To make sure that everyone has such rights, we have to forbid you to
         deprive anyone else of these rights.  For example, if you distribute copies
         of NetHack, you must give the recipients all the rights that you have.  You
         must make sure that they, too, receive or can get the source code.  And you
         must tell them their rights.
         
           Also, for our own protection, we must make certain that everyone finds out
         that there is no warranty for NetHack.  If NetHack is modified by someone
         else and passed on, we want its recipients to know that what they have is
         not what we distributed.
         
           Therefore we (Mike Stephenson and other holders of NetHack copyrights) make
         the following terms which say what you must do to be allowed to distribute or
         change NetHack.
         
         
                                 COPYING POLICIES
         
           1. You may copy and distribute verbatim copies of NetHack source code as
         you receive it, in any medium, provided that you keep intact the notices on
         all files that refer to copyrights, to this License Agreement, and to the
         absence of any warranty; and give any other recipients of the NetHack
         program a copy of this License Agreement along with the program.
         
           2. You may modify your copy or copies of NetHack or any portion of it, and
         copy and distribute such modifications under the terms of Paragraph 1 above
         (including distributing this License Agreement), provided that you also do the
         following:
         
             a) cause the modified files to carry prominent notices stating that you
             changed the files and the date of any change; and
         
             b) cause the whole of any work that you distribute or publish, that in
             whole or in part contains or is a derivative of NetHack or any part
             thereof, to be licensed at no charge to all third parties on terms
             identical to those contained in this License Agreement (except that you
             may choose to grant more extensive warranty protection to some or all
             third parties, at your option)
         
             c) You may charge a distribution fee for the physical act of
             transferring a copy, and you may at your option offer warranty protection
             in exchange for a fee.
         
           3. You may copy and distribute NetHack (or a portion or derivative of it,
         under Paragraph 2) in object code or executable form under the terms of
         Paragraphs 1 and 2 above provided that you also do one of the following:
         
             a) accompany it with the complete machine-readable source code, which
             must be distributed under the terms of Paragraphs 1 and 2 above; or,
         
             b) accompany it with full information as to how to obtain the complete
             machine-readable source code from an appropriate archive site.  (This
             alternative is allowed only for noncommercial distribution.)
         
         For these purposes, complete source code means either the full source
         distribution as originally released over Usenet or updated copies of the
         files in this distribution used to create the object code or executable.
         
           4. You may not copy, sublicense, distribute or transfer NetHack except as
         expressly provided under this License Agreement.  Any attempt otherwise to
         copy, sublicense, distribute or transfer NetHack is void and your rights to
         use the program under this License agreement shall be automatically
         terminated.  However, parties who have received computer software programs
         from you with this License Agreement will not have their licenses terminated
         so long as such parties remain in full compliance.
         
         
         Stated plainly:  You are permitted to modify NetHack, or otherwise use parts
         of NetHack, provided that you comply with the conditions specified above;
         in particular, your modified NetHack or program containing parts of NetHack
         must remain freely available as provided in this License Agreement.  In
         other words, go ahead and share NetHack, but don't try to stop anyone else
         from sharing it farther.
         
Classifier: License :: OSI Approved :: Nethack General Public License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Games/Entertainment
Project-URL: Homepage, https://github.com/NetHack-LE/nle
Requires-Python: >=3.10
Requires-Dist: pybind11>=2.2
Requires-Dist: numpy>=1.16
Requires-Dist: gymnasium==1.2.0
Provides-Extra: agent
Requires-Dist: torch>=1.3.1; extra == "agent"
Provides-Extra: dev
Requires-Dist: pre-commit>=2.0.1; extra == "dev"
Requires-Dist: cmake_format>=0.6.10; extra == "dev"
Requires-Dist: memory-profiler>=0.60.0; extra == "dev"
Requires-Dist: pytest>=6.2.5; extra == "dev"
Requires-Dist: pytest-benchmark>=3.4.1; extra == "dev"
Requires-Dist: sphinx>=2.4.4; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=0.4.3; extra == "dev"
Requires-Dist: setuptools>=69.5.1; extra == "dev"
Requires-Dist: ruff==0.4.3; extra == "dev"
Provides-Extra: all
Requires-Dist: nle[agent,dev]; extra == "all"
Description-Content-Type: text/markdown

![NetHack Learning Environment (NLE)](https://github.com/NetHack-LE/nle/raw/main/dat/nle/logo.png)

--------------------------------------------------------------------------------

<p align="center">
  <a href="https://github.com/NetHack-LE/nle/actions/workflows/test_and_deploy.yml"><img src="https://github.com/NetHack-LE/nle/actions/workflows/test_and_deploy.yml/badge.svg?branch=main" /></a>
  <a href="https://pypi.python.org/pypi/nle/"><img src="https://img.shields.io/pypi/v/nle.svg" /></a>
  <a href="https://pepy.tech/project/nle"><img src="https://static.pepy.tech/personalized-badge/nle?period=total&units=international_system&left_color=black&right_color=orange&left_text=Downloads" /></a>
  <a href="https://twitter.com/NetHack_LE"><img src="https://img.shields.io/twitter/follow/NetHack_LE?label=Twitter&style=social" alt="Twitter" /></a>
 </p>

The NetHack Learning Environment (NLE) is a Reinforcement Learning environment originally presented at [NeurIPS 2020](https://neurips.cc/Conferences/2020).
This version of NLE is based on [NetHack 3.6.7](https://github.com/NetHack/NetHack/releases/tag/NetHack-3.6.7_Released) and designed to provide a standard RL interface to the game, and comes with tasks that function as a first step to evaluate agents on this new environment.

NetHack is one of the oldest and arguably most impactful videogames in history,
as well as being one of the hardest roguelikes currently being played by humans.
It is procedurally generated, rich in entities and dynamics, and overall an
extremely challenging environment for current state-of-the-art RL agents, while
being much cheaper to run compared to other challenging testbeds. Through NLE,
we wish to establish NetHack as one of the next challenges for research in
decision making and machine learning.

You can read more about NLE in the [NeurIPS 2020 paper](https://arxiv.org/abs/2006.13760), and about NetHack in its [original
README](./README.nh), at [nethack.org](https://nethack.org/), and on the
[NetHack wiki](https://nethackwiki.com).

![Example of an agent running on NLE](https://github.com/NetHack-LE/nle/raw/main/dat/nle/example_run.gif)

This version of NLE uses the [Farama Organisation Gymnasium Environment](https://gymnasium.farama.org) APIs.


# Getting started

Starting with NLE environments is extremely simple, provided one is familiar
with other gym (or Gynmasium) / RL environments.


## Installation

NLE requires `python>=3.10`, `cmake>=3.28` to be installed and available both when building the
package, and at runtime.

On **MacOS**, one can use `Homebrew` as follows:

``` bash
$ brew install cmake
```

On a plain **Ubuntu 18.04** distribution, `cmake` and other dependencies
can be installed by doing:

```bash
# Python and most build deps
$ sudo apt-get install -y build-essential autoconf libtool pkg-config \
    python3-dev python3-pip python3-numpy git flex bison libbz2-dev

# recent cmake version
$ wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add -
$ sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main'
$ sudo apt-get update && apt-get --allow-unauthenticated install -y \
    cmake \
    kitware-archive-keyring
```

Afterwards it's a matter of setting up your environment. We advise using a conda
environment for this:

```bash
$ conda create -y -n nle python=3.10
$ conda activate nle
$ pip install nle
```


NOTE: If you want to extend / develop NLE, please install the package as follows:

``` bash
$ git clone https://github.com/NetHack-LE/nle
$ pip install -e ".[dev]"
$ pre-commit install
```


## Docker

We have provided some docker images. Please see the [relevant
README](https://github.com/NetHack-LE/nle/blob/main/docker/README.md). 


## Trying it out

After installation, one can try out any of the provided tasks as follows:

```python
>>> import gymnasium as gym
>>> import nle
>>> env = gym.make("NetHackScore-v0")
>>> env.reset()  # each reset generates a new dungeon
>>> env.step(1)  # move agent '@' north
>>> env.render()
```

NLE also comes with a few scripts that allow to get some environment rollouts,
and play with the action space:

```bash
# Play NetHackStaircase-v0 as a human
$ python -m nle.scripts.play

# Use a random agent
$ python -m nle.scripts.play --mode random

# Play the full game using directly the NetHack internal interface
# (Useful for debugging outside of the gymnasium environment)
$ python -m nle.scripts.play --env NetHackScore-v0 # works with random agent too

# See all the options
$ python -m nle.scripts.play --help
```

Note that `nle.scripts.play` can also be run with `nle-play`, if the package
has been properly installed.

Additionally, a [TorchBeast](https://github.com/facebookresearch/torchbeast)
agent is bundled in `nle.agent` together with a simple model to provide a
starting point for experiments:

``` bash
$ pip install "nle[agent]"
$ python -m nle.agent.agent --num_actors 80 --batch_size 32 --unroll_length 80 --learning_rate 0.0001 --entropy_cost 0.0001 --use_lstm --total_steps 1000000000
```

Plot the mean return over the last 100 episodes:
```bash
$ python -m nle.scripts.plot
```
```
                              averaged episode return

  140 +---------------------------------------------------------------------+
      |             +             +            ++-+ ++++++++++++++++++++++++|
      |             :             :          ++++++++||||||||||||||||||||||||
  120 |-+...........:.............:...+-+.++++|||||||||||||||||||||||||||||||
      |             :        +++++++++++++++||||||||||AAAAAAAAAAAAAAAAAAAAAA|
      |            +++++++++++++||||||||||||||AAAAAAAAAAAA|||||||||||||||||||
  100 |-+......+++++|+|||||||||||||||||||||||AA||||||||||||||||||||||||||||||
      |       +++|||||||||||||||AAAAAAAAAAAAAA|||||||||||+++++++++++++++++++|
      |    ++++|||||AAAAAAAAAAAAAA||||||||||||++++++++++++++-+:             |
   80 |-++++|||||AAAAAA|||||||||||||||||||||+++++-+...........:...........+-|
      | ++|||||AAA|||||||||||||||++++++++++++-+ :             :             |
   60 |++||AAAAA|||||+++++++++++++-+............:.............:...........+-|
      |++|AA||||++++++-|-+        :             :             :             |
      |+|AA|||+++-+ :             :             :             :             |
   40 |+|A+++++-+...:.............:.............:.............:...........+-|
      |+AA+-+       :             :             :             :             |
      |AA-+         :             :             :             :             |
   20 |AA-+.........:.............:.............:.............:...........+-|
      |++-+         :             :             :             :             |
      |+-+          :             :             :             :             |
    0 |-+...........:.............:.............:.............:...........+-|
      |+            :             :             :             :             |
      |+            +             +             +             +             |
  -20 +---------------------------------------------------------------------+
      0           2e+08         4e+08         6e+08         8e+08         1e+09
                                       steps
```

### NLE Language Wrapper

We thank [ngoodger](https://github.com/ngoodger) for implementing the [NLE Language Wrapper](https://github.com/ngoodger/nle-language-wrapper) that translates the non-language observations from NetHack tasks into similar language representations. Actions can also be optionally provided in text form which are converted to the Discrete actions of the NLE.

### NetHack Learning Dataset

The NetHack Learning Dataset (NLD) code now ships with `NLE`, allowing users to the load large-scale datasets featured in [Dungeons and Data: A Large-Scale NetHack Dataset](https://papers.neurips.cc/paper_files/paper/2022/file/9d9258fd703057246cb341e615426e2d-Paper-Datasets_and_Benchmarks.pdf), while also generating and loading their own datasets.

```python
import nle.dataset as nld

if not nld.db.exists():
    nld.db.create()
    # NB: Different methods are used for data based on NLE and data from NAO.
    nld.add_nledata_directory("/path/to/nld-aa", "nld-aa-v0")
    nld.add_altorg_directory("/path/to/nld-nao", "nld-nao-v0")

dataset = nld.TtyrecDataset("nld-aa-v0", batch_size=128, ...)
for i, mb in enumerate(dataset):
    foo(mb) # etc...
```

For information on how to download NLD-AA and NLD-NAO, see the dataset doc [here](https://github.com/NetHack-LE/nle/blob/main/DATASET.md).

Otherwise checkout the tutorial Colab notebook [here](https://colab.research.google.com/drive/1GRP15SbOEDjbyhJGMDDb2rXAptRQztUD?usp=sharing).

# Papers using the NetHack Learning Environment
- Paglieri et al. [BALROG: Benchmarking Agentic LLM and VLM Reasoning On Games](https://arxiv.org/abs/2411.13543) (UCL, IDEAS NCBR, NYU, Oxford, Anthropic, ICLR 2025)
- Klissarov et al. [MaestroMotif: Skill Design from Artificial Intelligence Feedback](https://arxiv.org/abs/2412.08542) (Mila, FAIR, UT Austin, Alberta, Amii, ICLR 2025) 
- Klissarov et al. [Motif: Intrinsic Motivation from Artificial Intelligence Feedback](https://arxiv.org/abs/2310.00166) (Mila, FAIR, UT Austin, ICLR 2024) 
- Izumiya and Simo-Serra [Inventory Management with Attention-Based Meta Actions](https://esslab.jp/~ess/publications/IzumiyaCOG2021.pdf) (Waseda University, CoG 2021).
- Samvelyan et al. [MiniHack the Planet: A Sandbox for Open-Ended Reinforcement Learning Research](https://arxiv.org/abs/2109.13202) (FAIR, UCL, Oxford, NeurIPS 2021).
- Zhang et al. [BeBold: Exploration Beyond the Boundary of Explored Regions](https://arxiv.org/abs/2012.08621) (Berkley, FAIR, Dec 2020).
- Küttler et al. [The NetHack Learning Environment](https://arxiv.org/abs/2006.13760) (FAIR, Oxford, NYU, Imperial, UCL, NeurIPS 2020).

Open a [pull
request](https://github.com/NetHack-LE/nle/edit/main/README.md)
to add papers.



# Contributing

We welcome contributions to NLE. If you are interested in contributing please
see [this document](https://github.com/NetHack-LE/nle/blob/main/CONTRIBUTING.md).


# Architecture

NLE is direct fork of [NetHack](https://github.com/nethack/nethack) and
therefore contains code that operates on many different levels of abstraction.
This ranges from low-level game logic, to the higher-level administration of
repeated nethack games, and finally to binding of these games to Python 
`gymnasium` environment.

If you want to learn more about the architecture of `nle` and how it works
under the hood, checkout the [architecture document](https://github.com/NetHack-LE/nle/blob/main/doc/nle/ARCHITECTURE.md).
This may be a useful starting point for anyone looking to contribute to the
lower level elements of NLE.


# Related Environments
- [gym\_nethack](http://campbelljc.com/research/gym_nethack/)
- [rogueinabox](https://github.com/rogueinabox/rogueinabox)
- [rogue-gym](https://github.com/kngwyu/rogue-gym)
- [MiniGrid](https://github.com/maximecb/gym-minigrid)
- [CoinRun](https://github.com/openai/coinrun)
- [MineRL](http://minerl.io/docs)
- [Project Malmo](https://www.microsoft.com/en-us/research/project/project-malmo/)
- [OpenAI Procgen Benchmark](https://openai.com/blog/procgen-benchmark/)
- [Obstacle Tower](https://github.com/Unity-Technologies/obstacle-tower-env)

# Interview about the environment with Weights&Biases
[Facebook AI Research’s Tim & Heiner on democratizing reinforcement learning research.](https://www.youtube.com/watch?v=oYSNXTkeCtw)

[![Interview with Weigths&Biases](https://img.youtube.com/vi/oYSNXTkeCtw/0.jpg)](https://www.youtube.com/watch?v=oYSNXTkeCtw)

# Citation

If you use NLE in any of your work, please cite:

```
@inproceedings{kuettler2020nethack,
  author    = {Heinrich K{\"{u}}ttler and
               Nantas Nardelli and
               Alexander H. Miller and
               Roberta Raileanu and
               Marco Selvatici and
               Edward Grefenstette and
               Tim Rockt{\"{a}}schel},
  title     = {{The NetHack Learning Environment}},
  booktitle = {Proceedings of the Conference on Neural Information Processing Systems (NeurIPS)},
  year      = {2020},
}
```

If you use NLD or the datasets in any of your work, please cite:

```
@article{hambro2022dungeons,
  title={Dungeons and Data: A Large-Scale NetHack Dataset},
  author={Hambro, Eric and Raileanu, Roberta and Rothermel, Danielle and Mella, Vegard and Rockt{\"a}schel, Tim and K{\"u}ttler, Heinrich and Murray, Naila},
  journal={Advances in Neural Information Processing Systems},
  volume={35},
  pages={24864--24878},
  year={2022}
}
```
