| --- |
| tags: |
| - ml-intern |
| --- |
| <h1 align="center">StoryBox</h1> |
|
|
| <p align="center"> |
| <a href="https://ojs.aaai.org/index.php/AAAI/article/view/40288"><img src="https://img.shields.io/badge/AAAI_2026-Paper-4285F4?style=for-the-badge&logoColor=white" style="border-radius: 10px;"></a> |
| |
| <a href="https://arxiv.org/abs/2510.11618"><img src="https://img.shields.io/badge/Arxiv-2510.11618-A52C25?style=for-the-badge&logo=arxiv&logoColor=white" style="border-radius: 10px;"></a> |
| |
| <a href="https://storyboxproject.github.io/"><img src="https://img.shields.io/badge/Website-Project-2962FF?style=for-the-badge&logoColor=white" style="border-radius: 10px;"></a> |
| |
| <a href="https://docs.astral.sh/uv/"><img src="https://img.shields.io/badge/uv-astral-purple?style=for-the-badge&logoColor=white" style="border-radius: 10px;"></a> |
| </p> |
| |
| <p align="center"> |
| <img src="https://img.shields.io/badge/Task-Story_Generation-6d4aff?style=for-the-badge&logo=task&logoColor=white" style="border-radius: 10px;"> |
| |
| <a href="https://opensource.org/license/MIT"><img src="https://img.shields.io/badge/License-MIT-009CAB?style=for-the-badge&logo=book&logoColor=white" style="border-radius: 10px;"></a> |
| </p> |
| |
| ## 📝 Introduction |
|
|
| This is the repository for the paper [StoryBox: Collaborative Multi-Agent Simulation for Hybrid Bottom-Up Long-Form Story Generation Using Large Language Models](https://ojs.aaai.org/index.php/AAAI/article/view/40288), accepted by **AAAI 2026**. |
|
|
|  |
|
|
| **StoryBox** is a framework that leverages collaborative multi-agent simulation for hybrid bottom-up long-form story generation. By combining bottom-up character-driven agent interactions with top-down narrative planning, it dynamically constructs deep, coherent, and engaging story worlds. |
|
|
| --- |
|
|
| ## ⚡ Quick Start (with uv) |
|
|
| ```bash |
| # 1. Install uv |
| curl -LsSf https://astral.sh/uv/install.sh | sh |
| |
| # 2. Clone |
| git clone https://huggingface.co/raazkumar/storybox-reproduction |
| cd storybox-reproduction |
| |
| # 3. Install dependencies (uv handles everything) |
| uv sync |
| |
| # 4. Run quick test (1 day, mock LLM — no API key needed) |
| uv run python reverie/test_run.py |
| |
| # 5. Run full simulation (14 days, requires API key) |
| export OPENAI_API_KEY="sk-..." |
| uv run python reverie/run.py |
| ``` |
|
|
| --- |
|
|
| ## ⚙️ Installation Options |
|
|
| ```bash |
| # Base install (OpenAI only) |
| uv sync |
| |
| # Apple Silicon — native MLX (fastest on M1/M2/M3/M4) |
| uv sync --extra mlx |
| |
| # NVIDIA NIM inference |
| uv sync --extra nim |
| |
| # Ollama local inference |
| uv sync --extra ollama |
| |
| # All local backends (MLX + Ollama) |
| uv sync --extra local |
| |
| # Everything (all providers + dev tools) |
| uv sync --extra all --extra dev |
| ``` |
|
|
| --- |
|
|
| ## 🚀 Supported LLM Providers |
|
|
| | Provider | Config | Speed | Setup | |
| |----------|--------|-------|-------| |
| | **OpenAI** | `gpt-4o-mini` | Fastest | API key | |
| | **Ollama** | `gemma4` | Fast | `brew install ollama` | |
| | **MLX (Apple)** ⭐ | `llama3.1-8b-mlx` | **Fastest on Mac** | `uv sync --extra mlx` | |
| | **NVIDIA NIM** | `nvidia/meta/llama-3.1-8b-instruct` | Fast | API key | |
|
|
| Switch providers by changing **one line** in `reverie/config/config.py`: |
|
|
| ```python |
| llm_model_name = 'llama3.1-8b-mlx' # MLX native (Apple) |
| llm_model_name = 'gemma4' # Ollama |
| llm_model_name = 'nvidia/meta/llama-3.1-8b-instruct' # NIM |
| llm_model_name = 'gpt-4o-mini' # OpenAI |
| ``` |
|
|
| --- |
|
|
| ## 📁 Project Structure |
|
|
| ``` |
| storybox/ |
| ├── reverie/ |
| │ ├── run.py # Main entry point |
| │ ├── test_run.py # Quick 1-day test |
| │ ├── config/config.py # All settings |
| │ ├── agent/storyteller.py # Story generation |
| │ ├── persona/ # Characters + cognition |
| │ ├── environment/world.py # Sandbox world |
| │ ├── common/llm.py # LLM provider router |
| │ ├── common/mlx_llm.py # Native MLX (Apple) |
| │ └── prompts/prompt-1/ # 30+ prompt templates |
| ├── data/story01-20/ # 20 story settings |
| ├── pyproject.toml # uv project config |
| └── uv.lock # Locked dependencies |
| ``` |
|
|
| --- |
|
|
| ## 🛠️ Common Commands |
|
|
| ```bash |
| # Run with uv (recommended) |
| uv run python reverie/run.py |
| uv run python reverie/test_run.py |
| |
| # Install additional dependencies |
| uv add gradio |
| uv add --dev pytest |
| |
| # Lock dependencies |
| uv lock |
| |
| # Update dependencies |
| uv sync --upgrade |
| |
| # Run tests |
| uv run pytest |
| |
| # Format code |
| uv run ruff format . |
| uv run ruff check --fix . |
| |
| # Type check |
| uv run mypy reverie/ |
| ``` |
|
|
| --- |
|
|
| ## 🇮🇳 Hindi / Multilingual Stories |
|
|
| ```bash |
| # Generate English story |
| uv run python reverie/run.py |
| |
| # Translate to Hindi (post-generation) |
| # See GRADIO_UI_GUIDE.md for full pipeline |
| ``` |
|
|
| **Recommended approach**: English simulation → Hindi storyteller. Characters plan/chat in English, final story written in Hindi. |
|
|
| --- |
|
|
| ## 🏭 Synthetic Data Generation |
|
|
| ```bash |
| # Generate 1000 stories for training data |
| uv run python scripts/generate_synthetic_dataset.py \ |
| --num-stories 1000 \ |
| --output stories.jsonl |
| |
| # Convert to instruction format |
| uv run python scripts/to_instruction_format.py \ |
| --input stories.jsonl \ |
| --output train.json |
| ``` |
|
|
| --- |
|
|
| ## 📚 Citation |
|
|
| ```bibtex |
| @inproceedings{chen2026storybox, |
| title = {StoryBox: Collaborative Multi-Agent Simulation for Hybrid Bottom-Up Long-Form Story Generation Using Large Language Models}, |
| author = {Chen, Zehao and Pan, Rong and Li, Haoran}, |
| booktitle = {Proceedings of the AAAI Conference on Artificial Intelligence}, |
| volume = {40}, |
| number = {36}, |
| pages = {30359--30367}, |
| year = {2026} |
| } |
| ``` |
|
|
| --- |
|
|
| ## ⚖️ License |
|
|
| <a href="https://opensource.org/license/MIT"><img src="https://img.shields.io/badge/License-MIT-009CAB?style=for-the-badge&logo=book&logoColor=white" style="border-radius: 10px;"></a> |
|
|
| This project is licensed under the [MIT License](https://opensource.org/license/MIT). |
|
|
| <!-- ml-intern-provenance --> |
| ## Generated by ML Intern |
|
|
| This model repository was generated by [ML Intern](https://github.com/huggingface/ml-intern), an agent for machine learning research and development on the Hugging Face Hub. |
|
|
| - Try ML Intern: https://smolagents-ml-intern.hf.space |
| - Source code: https://github.com/huggingface/ml-intern |
|
|
| ## Usage |
|
|
| ```python |
| from transformers import AutoModelForCausalLM, AutoTokenizer |
| |
| model_id = 'raazkumar/storybox-reproduction' |
| tokenizer = AutoTokenizer.from_pretrained(model_id) |
| model = AutoModelForCausalLM.from_pretrained(model_id) |
| ``` |
|
|
| For non-causal architectures, replace `AutoModelForCausalLM` with the appropriate `AutoModel` class. |
|
|
