🖥️ Project Page | 📃 Paper | 🤗 Demo
This is the official implementation of the paper "BOOKWORLD: From Novels to Interactive Agent Societies for Story Creation".
BookWorld is a comprehensive system for social simulation in fictional worlds through multi-agent interactions. The system features:
- Scene-based story progression with multiple character agents
- Continuous updating of agent memories, status, and goals
- World agent orchestration of the simulation
- Support for human intervention and control
- LLM-based story generation and refinement
git clone https://github.com/your-repo/bookworld.git
cd bookworldConda
conda create -n bookworld python=3.10
conda activate bookworld
pip install -r requirements.txtDocker
docker build -t bookworld .Fill in the configuration parameters in config.json:
role_llm_name: LLM model for character rolesworld_llm_name: LLM model for world simulationpreset_path: The path to the experiment presetif_save: Enable/disable saving (1/0)scene_mode: Scene progression moderounds: Number of simulation roundsmode: Simulation mode ("free" or "script")
Then enter the API key of the LLM provider you're using either in config.json or through the frontend interface.
python server.pyor
uvicorn server:app --host 127.0.0.1 --port 8000 Docker
docker run -p 8000:8000 bookworldOpen a browser and navigate to http://localhost:8000.
- Start/pause/stop story generation
- View character information and map details
- Monitor story progression and agent interactions
- Edit generated content if needed
- Locate the directory of the previous simulation within
/experiment_saves/ - Set its path to the
save_dirfield inconfig.json. Ensure that the selected directory directly containsserver_info.jsonandworld_agent.json.
- Create the roles, map, worldbuilding following the examples given in
/data/. Additionally, you can place an image namedicon.(png/jpg)inside the character's folder — this will be used as the avatar displayed in the interface. - You can improve the simulation quality by providing background settings about the world in
world_details/or put character dialogue lines inrole_lines.jsonl. - Enter the preset path to
preset_pathinconfig.json.
Utilize the script provided in /extract_data/ to extract key story elements using LLMs.
if_auto_extract to 0 in extract_config.json.
1. Configure the extraction model and API key in extract_config.json:
book_path: Path to the input book file. We currently support.epub(recommended),.pdf, and.txtformats.language: The language of the book (e.g.,en,zh). If not specified, the program will attempt to detect it automatically.book_source: The title or name of the book. If omitted, the program will try to infer it from the file.target_character_names: A list of characters to extract information about. It's best to use names or nicknames that appear most frequently in the text, rather than full formal names. If not provided, the program will attempt to extract them automatically. For higher-quality results, we strongly recommend specifying this field.target_location_names: A list of important locations. Again, using the most frequently occurring name or common synonym improves accuracy. If omitted, locations will be extracted automatically. For higher-quality results, we strongly recommend specifying this field.
2. Run the script
Characters and Locations
python extract_data.pySettings
python extract_settings.py- Put your character cards in
/data/sillytavern_cards/. - Run the script. It will convert all the cards into the role data that BookWorld needs.
python convert_sillytavern_cards_to_data.py- Input role codes of all the characters participating in this simulation to
role_agent_codesin the preset file.
.
├── data/
├── frontend/
│ ├── assets/
│ ├── css/
│ └── js/
├── modules/
│ ├── db/
│ ├── llm/
│ ├── prompt/
│ ├── main_role_agent.py
│ └── world_agent.py
├── experiment_configs/
├── BookWorld.py
├── server.py
├── config.json
└── index.html
Authors: Yiting Ran, Xintao Wang, Tian Qiu, Jiaqing Liang, Yanghua Xiao, Deqing Yang.
@misc{ran2025bookworldnovelsinteractiveagent,
title={BookWorld: From Novels to Interactive Agent Societies for Creative Story Generation},
author={Yiting Ran and Xintao Wang and Tian Qiu and Jiaqing Liang and Yanghua Xiao and Deqing Yang},
year={2025},
eprint={2504.14538},
archivePrefix={arXiv},
primaryClass={cs.CL},
url={https://arxiv.org/abs/2504.14538},
}This project is licensed under the Apache License 2.0.
- Fantasy Map: The background of map panel used in the frontend is from Free Fantasy Maps, created by Fantasy Map Maker. This map is free for non-commercial use.
BookWorld is a foundational framework that we aim to continuously optimize and enrich with custom modules. We welcome and greatly appreciate your suggestions and contributions!
If you have any suggestions or would like to contribute, please contact us at: ytran23@m.fudan.edu.cn