story-builder-sdk 0.1.2

Deterministic State-Driven Interactive Narrative Engine SDK

🚀 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

pip install story-builder-sdk

2. Generate a story

story-builder generate "Cyberpunk detective story"

3. Run the AI demo

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.

# 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.

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

---

📜 Installation

# 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.