 🚀 Story Builder

⭐ Star this repo if you find it useful!

> **AI-powered branching narrative engine for games and interactive fiction**

Story Builder is a deterministic Python engine for building, validating, and executing branching story graphs.

Generate stories with AI, validate them with a strict schema, and run them with a reliable state engine.

---

# ⚡ Install

```bash
pip install story-builder-sdk

Verify installation:

story-builder --help
🎬 Demo

Generate a story with one command:

story-builder generate "Cyberpunk detective story"

Output:

story.json
story_graph.dot

Visualize the graph:

story-builder visualize story.json --dot-only
🚀 Quickstart (1 minute)

Generate a branching story:

story-builder generate "A haunted mansion mystery"

Play the story:

story-builder play story.json

Visualize the graph:

story-builder visualize story.json --dot-only
🧠 AI Story Generation

Story Builder can generate complex story graphs using AI.

Set your API key:

**Windows**
```powershell
$env:OPENROUTER_API_KEY="YOUR_KEY"
```

**macOS / Linux**
```bash
export OPENROUTER_API_KEY="YOUR_KEY"
```

### Advanced Generation

Control the graph size and structure with flags:

```bash
story-builder generate "Cyberpunk detective story" --nodes 12 --branching 3 --depth 4
```

- `--nodes N`: Total target nodes (default 6)
- `--branching K`: Average branching factor (default 2)
- `--depth D`: Maximum depth from start (default 3)
- `--mock`: Force mock mode even if API key is available
- `--seed S`: Seed for deterministic generation

If no API key is provided OR `--mock` is used, Story Builder runs in a deterministic **mock mode**.

> [!NOTE]
> GraphViz binaries are required only for rendering images (PNG/SVG). Generating `.dot` files and `.json` graphs works without any external dependencies.

🕹 CLI Commands
story-builder init
story-builder generate
story-builder play
story-builder visualize
story-builder validate
story-builder export
story-builder demo-ai
🏗 Features

• AI-powered story generation
• Deterministic branching engine
• Graph validation with schema enforcement
• Stateful narrative execution
• Graph visualization
• Ink export support
• CLI-first developer workflow

💎 Pro Version

Advanced AI branch generation is available in Story Builder Pro.

Install Lite SDK first:

pip install story-builder-sdk

Then install Pro:

pip install story_builder_pro-0.1.2-py3-none-any.whl
📚 Examples

Example story graphs are available in the /examples directory.

Visualize one with:

story-builder visualize examples/cyberpunk_detective.json
📜 License

MIT License

Structure Your Story. Control Your World.