Skip to content

Commit 3a1576e

Browse files
sagara-rsagara-r
committed
Release 0.2.0
0 parents  commit 3a1576e

102 files changed

Lines changed: 45933 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
ckpt*
2+
mc_server/**/data/
3+
4+
# Byte-compiled / optimized / DLL files
5+
__pycache__/
6+
*.py[cod]
7+
*$py.class
8+
9+
# C extensions
10+
*.so
11+
12+
# Distribution / packaging
13+
.Python
14+
build/
15+
develop-eggs/
16+
dist/
17+
downloads/
18+
eggs/
19+
.eggs/
20+
lib64/
21+
parts/
22+
sdist/
23+
var/
24+
wheels/
25+
*.egg-info/
26+
.installed.cfg
27+
*.egg
28+
29+
# PyInstaller
30+
# Usually these files are written by a python script from a template
31+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
32+
*.manifest
33+
*.spec
34+
35+
# Installer logs
36+
pip-log.txt
37+
pip-delete-this-directory.txt
38+
39+
# Unit test / coverage reports
40+
htmlcov/
41+
.tox/
42+
.coverage
43+
.coverage.*
44+
.cache
45+
nosetests.xml
46+
coverage.xml
47+
*.cover
48+
.hypothesis/
49+
50+
# Translations
51+
*.mo
52+
*.pot
53+
54+
# Django stuff:
55+
*.log
56+
.static_storage/
57+
.media/
58+
local_settings.py
59+
60+
# Flask stuff:
61+
instance/
62+
.webassets-cache
63+
64+
# Scrapy stuff:
65+
.scrapy
66+
67+
# Sphinx documentation
68+
docs/build/
69+
70+
# PyBuilder
71+
target/
72+
73+
# Jupyter Notebook
74+
.ipynb_checkpoints
75+
76+
# pyenv
77+
.python-version
78+
79+
# celery beat schedule file
80+
celerybeat-schedule
81+
82+
# SageMath parsed files
83+
*.sage.py
84+
85+
# Environments
86+
.env
87+
.venv
88+
# env/
89+
venv/
90+
# ENV/
91+
env.bak/
92+
venv.bak/
93+
94+
# Spyder project settings
95+
.spyderproject
96+
.spyproject
97+
98+
# Rope project settings
99+
.ropeproject
100+
101+
# mkdocs documentation
102+
/site
103+
104+
# mypy
105+
.mypy_cache/
106+
107+
# Mac
108+
.DS_Store
109+
110+
# MuJoCo License key
111+
mjkey.txt
112+
113+
.mujocomanip_temp_model.xml
114+
115+
# Python IDE
116+
.idea
117+
118+
# Locally generated files
119+
dump.rdb
120+
*.local.ipynb
121+
runs/
122+
temp*
123+
debug_*
124+
*.swp
125+
126+
.tabnine_root
127+
128+
logs/
129+
plot_iter.py
130+
*.svg

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Rikunari SAGARA, Koichiro TERAO, Naoto IWAHASHI
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# BeliefNest: A Joint Action Simulator for Embodied Agents with Theory of Mind
2+
<div align="right">
3+
4+
[日本語はこちら(Japanese)](README_jp.md)
5+
6+
</div>
7+
8+
<div align="center">
9+
10+
[[Arxiv]]()
11+
12+
[![Python Version](https://img.shields.io/badge/Python-3.9-blue.svg)](https://github.com/sagara-r/BeliefNest)
13+
[![GitHub license](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/sagara-r/BeliefNest/blob/main/LICENSE)
14+
______________________________________________________________________
15+
16+
![](images/overview.png)
17+
18+
</div>
19+
20+
We propose an open-source simulator, BeliefNest, designed to enable embodied agents to perform collaborative tasks by leveraging Theory of Mind. BeliefNest dynamically and hierarchically constructs simulators within a Minecraft environment, allowing agents to explicitly represent nested belief states about themselves and others. This enables agent control in open-domain tasks that require Theory of Mind reasoning. The simulator provides a prompt generation mechanism based on each belief state, facilitating the design and evaluation of methods for agent control utilizing large language models (LLMs).
21+
22+
In this repo, we provide BeliefNest code. This codebase is under [MIT License](LICENSE).
23+
24+
# Installation
25+
Download the latest version [here](https://github.com/sagara-r/BeliefNest/releases). BeliefNest requires Python ≥ 3.9 and Node.js ≥ 16.13.0. We have tested on Windows 11. You need to follow the instructions below to install BeliefNest.
26+
27+
## Step 1. Python Install
28+
```
29+
cd BeliefNest
30+
pip install -e .
31+
```
32+
33+
## Step 2. Node.js Install
34+
```
35+
cd belief_nest/env/mineflayer
36+
npm install
37+
```
38+
39+
## Step 3. Docker Install
40+
If you are using Windows, download the installer from [Docker Docs](https://docs.docker.com/desktop/setup/install/windows-install/) and execute it.
41+
42+
## Step 4. Minecraft Client Install
43+
Install the [Minecraft Launcher](https://www.minecraft.net/) and ensure that you can play Minecraft: Java Edition (version 1.19). It will be used as a client. A valid Java Edition license is required.
44+
45+
From the "Installations" tab in the launcher, create a new launch configuration and select version 1.19.
46+
47+
# Usage
48+
## Getting Started
49+
Start the RabbitMQ server, the Minecraft server, and the main program in three different terminals.
50+
51+
### Launch the RabbitMQ server
52+
If you are using Docker Desktop, make sure to launch the application beforehand.
53+
```
54+
docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:4.1-management
55+
```
56+
57+
### Launch the Minecraft server
58+
See [here](https://www.minecraft.net/download/server) to launch a Minecraft server. Alternatively, you can launch the server using the command below.
59+
```
60+
cd mc_server/flat
61+
docker compose up -d
62+
docker attach minecraft-server
63+
```
64+
65+
It is possible to use `Open to LAN` in `Singleplayer` mode, though it is not recommended, as only up to 8 players can log in and thus only very small-scale experiments can run.
66+
67+
Run `/op operator` in the Minecraft server terminal; this only needs to be done once unless you switch to a different world.
68+
69+
Launch the Minecraft client and join the world from `Multiplayer`. If the world doesn't appear, use `Add Server` and specify the server address (e.g., `localhost:25565`).
70+
71+
### Run the example code
72+
```
73+
cd examples/sally_anne/
74+
```
75+
After writing the API key value into `api_key.py`, please execute the following command.
76+
```
77+
python main.py
78+
```
79+
80+
## Use own world
81+
Change the initial state and config.
82+
83+
### Create initial state
84+
```
85+
cd belief_nest/env/mineflayer/
86+
node generate_init_state.js
87+
mv state#-1.js /path/to/main_dir
88+
```
89+
90+
## API
91+
See [doc/API.md](doc/API.md)
92+
93+
# License
94+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
95+
96+
Some portions of the code are adapted from [MineDojo/Voyager](https://github.com/MineDojo/Voyager), which is also licensed under the MIT License.
97+
98+
# Citation
99+
~~~
100+
@article{sagara2025beliefnest,
101+
title={####},
102+
author={Rikunari SAGARA, Koichiro TERAO, Naoto IWAHASHI},
103+
year={2025},
104+
journal={arXiv preprint arXiv: ####}
105+
}
106+
~~~

‎README_jp.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# BeliefNest: 心の理論を持つ身体化エージェントのための共同行為シミュレータ
2+
3+
<div align="center">
4+
5+
[\[Arxiv\]]()
6+
7+
[![Python Version](https://img.shields.io/badge/Python-3.9-blue.svg)](https://github.com/sagara-r/BeliefNest)
8+
[![GitHub license](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/sagara-r/BeliefNest/blob/main/LICENSE)
9+
10+
---
11+
12+
![](images/overview.png)
13+
14+
</div>
15+
16+
**BeliefNest** は、身体化エージェントが心の理論を活用して共同行為タスクを遂行することを可能にする、オープンソースシミュレータです。BeliefNestは Minecraft 環境内に動的かつ階層的にシミュレータを生成し、エージェント自身および他者の入れ子構造の信念状態を明示的に表現します。これによりオープンドメインタスクで心の理論を用いたエージェント制御を可能とします。本シミュレータは各信念に基づくプロンプト生成機構を備えており、大規模言語モデル(LLM)を活用したエージェント制御手法の設計・検証を可能とします。
17+
18+
このリポジトリには BeliefNest のコードを含みます。コードは [MITライセンス](LICENSE) のもとで提供されています。
19+
20+
---
21+
22+
# インストール方法
23+
24+
[こちら](https://github.com/sagara-r/BeliefNest/releases)から最新版をダウンロードしてください．BeliefNest の動作には Python 3.9 以上および Node.js 16.13.0 以上が必要です。動作確認は Windows 11 上で行っています。以下の手順に従ってインストールしてください。
25+
26+
インストール方法の詳細は[こちら](doc/INSTALL_jp.md)
27+
28+
## ステップ 1: Python のインストール
29+
30+
```
31+
cd BeliefNest
32+
pip install -e .
33+
```
34+
35+
## ステップ 2: Node.js のインストール
36+
37+
```
38+
cd belief_nest/env/mineflayer
39+
npm install
40+
```
41+
42+
## ステップ 3: Docker のインストール
43+
44+
Windows を使用している場合は、[Docker Docs](https://docs.docker.com/desktop/setup/install/windows-install/) からインストーラをダウンロードして実行してください。
45+
46+
## ステップ 4: Minecraft のインストール
47+
48+
[Minecraft Launcher](https://www.minecraft.net/)をインストールし，Minecraft: Java Edition（バージョン1.19）をプレイできるようにしてください．クライアントとして使用します．Java Edition のライセンスが必要です．
49+
50+
Minecraft Launcherの「起動構成」タブの「新規作成」から，バージョン1.19 を選択してください．
51+
52+
---
53+
54+
# 使用方法
55+
56+
## はじめに
57+
RabbitMQ サーバ，Minecraftサーバ, mainプログラムの3つを異なるターミナルで起動します．
58+
59+
### RabbitMQ サーバの起動
60+
61+
Docker Desktop を使用している場合は、あらかじめアプリケーションを起動しておいてください。
62+
63+
```
64+
docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:4.1-management
65+
```
66+
67+
### Minecraft サーバの起動
68+
69+
[Minecraft公式サイト](https://www.minecraft.net/download/server) を参照してサーバを起動するか、以下のコマンドを使用して起動できます。
70+
71+
```
72+
cd mc_server/flat
73+
docker compose up -d
74+
docker attach minecraft-server
75+
```
76+
77+
「Singleplayer」モードの「Open to LAN」を使用することも可能ですが、最大8体のプレイヤーしかログインできないため、非常に小規模な実験しか実行できません。
78+
79+
Minecraftサーバのターミナルで `/op operator` を一度実行してください。異なるワールドを使用する場合を除き、複数回実行する必要はありません。
80+
81+
Minecraft クライアントを起動し、「Multiplayer」からワールドに参加してください。ワールドが表示されない場合は、「Add Server」で `localhost:25565` のようなサーバアドレスを指定してください。
82+
83+
---
84+
85+
### サンプルコードの実行
86+
87+
```
88+
cd examples/sally_anne/
89+
```
90+
91+
`api_key.py` に API キーの値を記入した後、以下のコマンドを実行してください。
92+
93+
```
94+
python main.py
95+
```
96+
97+
---
98+
99+
## 独自ワールドの使用
100+
101+
初期状態と設定ファイルを変更してください。
102+
103+
### 初期状態の作成
104+
105+
```
106+
cd belief_nest/env/mineflayer/
107+
node generate_init_state.js
108+
mv state#-1.js /path/to/main_dir
109+
```
110+
111+
---
112+
113+
## API
114+
115+
[doc/API.md](doc/API_jp.md) を参照してください。
116+
117+
---
118+
119+
# ライセンス
120+
121+
本プロジェクトはMITライセンスの下で公開しています．詳細はLICENSEファイルを参照してください．
122+
123+
本プロジェクトの一部には，[MineDojo/Voyager](https://github.com/MineDojo/Voyager)から改変したコードを含んでおり，こちらもMITライセンスの下で公開されています．
124+
125+
# 論文
126+
127+
```bibtex
128+
@article{sagara2025beliefnest,
129+
title={####},
130+
author={Rikunari SAGARA, Koichiro TERAO, Naoto IWAHASHI},
131+
year={2025},
132+
journal={arXiv preprint arXiv: ####}
133+
}
134+
```

0 commit comments

Comments
 (0)