# 🚀 Story Builder Engine

> **Story Builder is an AI-powered branching narrative engine for games and interactive fiction.**

Story Builder is a framework-agnostic Python SDK that provides a deterministic, state-driven engine for executing branching narratives with built-in validation and performance tracking.

Unlike "vibes-based" AI wrappers, Story Builder provides a rigorous mathematical model for story traversal, ensuring logical consistency and reliable state management.

---

# 🚀 Quickstart

**1. Install the SDK**
```bash
pip install story-builder-sdk
```

**2. Generate a story**
```bash
story-builder generate "Cyberpunk detective story"
```

**3. Run the AI demo**
```bash
story-builder demo-ai
```
*This will generate a branching story graph and visualize it automatically.*

---

## 🏗 Key Features

- **AI-Powered Generation:** Create complex branching stories from a single prompt.
- **Deterministic Execution:** No AI hallucinations in your core story logic.
- **Unified Schema:** Pydantic-driven story graphs and node structures.
- **Stat-Based Branching:** Transition between nodes based on complex condition evaluations.
- **Mutable State Engine:** Snapshot and rollback support with isolated state variables.
- **Developer-First:** Built-in CLI, JSON export, Ink support, and visualization.

---

## 🕹️ CLI Usage

Play an interactive story, generate new ones, or visualize graphs.

```bash
# Initialize a starter project
story-builder init

# Play a story
story-builder play story.json

# Visualize a story
story-builder visualize story.json

# Validate a story
story-builder validate story.json

# Export to Ink
story-builder export story.json --format ink
```

---

## 🎨 AI Features

Story Builder integrates with OpenRouter for high-quality narrative generation.

```bash
export OPENROUTER_API_KEY="YOUR_KEY"
story-builder generate "A space horror odyssey" --nodes 10
```

---

## 📜 Installation

```bash
# Basic installation
pip install story-builder

# With AI features (Pro)
pip install "story-builder[ai]"

# With Visualization features
pip install "story-builder[viz]"
```

---

*Structure Your Story, Control Your World.*
