Metadata-Version: 2.4
Name: wanderer-kada
Version: 0.1.0
Summary: Wanderer: An Open-Ended Embodied Agent with Large Language Models
Home-page: https://github.com/orewamash/Wanderer
Author: orewamash
License: MIT License
Keywords: Open-Ended Learning,Lifelong Learning,Embodied Agents,Large Language Models,Minecraft
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3.9
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tqdm
Requires-Dist: langchain==0.0.352
Requires-Dist: openai==0.28.1
Requires-Dist: javascript
Requires-Dist: setuptools
Requires-Dist: chardet
Requires-Dist: chromadb==0.4.24
Requires-Dist: tiktoken
Requires-Dist: requests
Requires-Dist: gymnasium
Requires-Dist: psutil
Requires-Dist: minecraft_launcher_lib
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Wanderer: An Open-Ended Embodied Agent with Large Language Models

![Python Version](https://img.shields.io/badge/Python-3.9-blue.svg) ![GitHub license](https://img.shields.io/github/license/orewamash/Wanderer) ![PyPI](https://img.shields.io/pypi/v/wanderer-kada)

Wanderer is an LLM-powered embodied lifelong learning agent for Minecraft that continuously explores the world, acquires diverse skills, and makes novel discoveries without human intervention. It is a re-imagined, rebranded distribution of the [Voyager](https://github.com/MineDojo/Voyager) research project, packaged as a pip-installable Python package.

Wanderer consists of three key components:

1. **Automatic Curriculum** – a curriculum agent that maximizes exploration and proposes the next task to learn.
2. **Ever-Growing Skill Library** – an executable-code skill library that stores and retrieves complex behaviors.
3. **Iterative Prompting Mechanism** – a self-verifying loop that incorporates environment feedback, execution errors, and critique to iteratively improve generated programs.

Wanderer interacts with LLMs (e.g., GPT-4) via blackbox API queries, bypassing the need for model parameter fine-tuning. The skills it develops are temporally extended, interpretable, and compositional — compounding the agent's abilities rapidly while alleviating catastrophic forgetting.

## Highlights

- Open-ended, lifelong learning agent for Minecraft (Java 1.19)
- Automatic curriculum + skill library + iterative self-verification
- Minimal, hackable Python API (`Wanderer` class)
- MIT licensed, research-ready codebase

## Installation

Wanderer requires Python ≥ 3.9 and Node.js ≥ 16.13.0. Tested on Ubuntu 20.04, Windows 11, and macOS.

### From PyPI (recommended)

```bash
pip install wanderer-kada
```

> Note: the package is published as `wanderer-kada` on PyPI, but you import it as `wanderer`.

### From source

```bash
git clone https://github.com/orewamash/Wanderer
cd Wanderer
pip install -e .
```

### Node.js Install

In addition to the Python dependencies, you need to install the following Node.js packages:

```bash
cd wanderer/env/mineflayer
npm install -g npx
npm install
cd mineflayer-collectblock
npx tsc
cd ..
npm install
```

### Minecraft Instance Install

Wanderer depends on the Minecraft game. You need to install Minecraft and set up a Minecraft instance.

Follow the instructions in [Minecraft Login Tutorial](installation/minecraft_instance_install.md) to set up your Minecraft Instance.

### Fabric Mods Install

You need to install fabric mods to support all the features in Wanderer. Remember to use the correct Fabric version of all the mods.

Follow the instructions in [Fabric Mods Install](installation/fabric_mods_install.md) to install the mods.

## Getting Started

Wanderer uses an LLM (e.g., OpenAI's GPT-4) as the language model. You need to have an OpenAI API key to use Wanderer. You can get one from [here](https://platform.openai.com/account/api-keys).

After the installation process, you can run Wanderer by:

```python
from wanderer import Wanderer

# You can also use mc_port instead of azure_login, but azure_login is highly recommended
azure_login = {
    "client_id": "YOUR_CLIENT_ID",
    "redirect_url": "https://127.0.0.1/auth-response",
    "secret_value": "[OPTIONAL] YOUR_SECRET_VALUE",
    "version": "fabric-loader-0.14.18-1.19", # the version Wanderer is tested on
}
openai_api_key = "YOUR_API_KEY"

wanderer = Wanderer(
    azure_login=azure_login,
    openai_api_key=openai_api_key,
)

# start lifelong learning
wanderer.learn()
```

- If you are running with `Azure Login` for the first time, it will ask you to follow the command line instruction to generate a config file.
- For `Azure Login`, you also need to select the world and open the world to LAN by yourself. After you run `wanderer.learn()` the game will pop up soon, you need to:
  1. Select `Singleplayer` and press `Create New World`.
  2. Set Game Mode to `Creative` and Difficulty to `Peaceful`.
  3. After the world is created, press `Esc` key and press `Open to LAN`.
  4. Select `Allow cheats: ON` and press `Start LAN World`. You will see the bot join the world soon.

## Resume from a checkpoint during learning

If you stop the learning process and want to resume from a checkpoint later, you can instantiate Wanderer by:

```python
from wanderer import Wanderer

wanderer = Wanderer(
    azure_login=azure_login,
    openai_api_key=openai_api_key,
    ckpt_dir="YOUR_CKPT_DIR",
    resume=True,
)
```

## Run Wanderer for a specific task with a learned skill library

If you want to run Wanderer for a specific task with a learned skill library, you should first pass the skill library directory to Wanderer:

```python
from wanderer import Wanderer

# First instantiate Wanderer with skill_library_dir.
wanderer = Wanderer(
    azure_login=azure_login,
    openai_api_key=openai_api_key,
    skill_library_dir="./skill_library/trial1", # Load a learned skill library.
    ckpt_dir="YOUR_CKPT_DIR", # Feel free to use a new dir. Do not use the same dir as skill library because new events will still be recorded to ckpt_dir.
    resume=False, # Do not resume from a skill library because this is not learning.
)
```

Then, you can run task decomposition. Notice: Occasionally, the task decomposition may not be logical. If you notice the printed sub-goals are flawed, you can rerun the decomposition.

```python
# Run task decomposition
task = "YOUR TASK" # e.g. "Craft a diamond pickaxe"
sub_goals = wanderer.decompose_task(task=task)
```

Finally, you can run the sub-goals with the learned skill library:

```python
wanderer.inference(sub_goals=sub_goals)
```

For all valid skill libraries, see [Learned Skill Libraries](skill_library/README.md).

## FAQ

If you have any questions, please check our [FAQ](FAQ.md) first before opening an issue.

## Credits

Wanderer is a rebranded, packaging-focused distribution of **[Voyager: An Open-Ended Embodied Agent with Large Language Models](https://github.com/MineDojo/Voyager)** by Guanzhi Wang, Yuqi Xie, Yunfan Jiang, Ajay Mandlekar, Chaowei Xiao, Yuke Zhu, Linxi Fan, and Anima Anandkumar (NVIDIA / Stanford / UT Austin).

If you find this work useful, please consider citing the original paper:

```bibtex
@article{wang2023voyager,
  title   = {Voyager: An Open-Ended Embodied Agent with Large Language Models},
  author  = {Guanzhi Wang and Yuqi Xie and Yunfan Jiang and Ajay Mandlekar and Chaowei Xiao and Yuke Zhu and Linxi Fan and Anima Anandkumar},
  year    = {2023},
  journal = {arXiv preprint arXiv: Arxiv-2305.16291}
}
```

Disclaimer: This project is for research and educational purposes, and is not an official product from NVIDIA.
