story-builder-sdk 0.1.1

Deterministic State-Driven Interactive Narrative Engine SDK

🚀 Story Builder Engine

Deterministic State-Driven Interactive Narrative Engine for Python Developers

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.

---

🏗 Key Features

• 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, and performance benchmarking.
• AI Extensions: Optional LLM-powered content generation via OpenRouter.

---

📜 Installation

# Basic installation
pip install story-builder

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

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

---

⚡ Quickstart (SDK Usage)

from story_builder import StoryGraph, Node, Choice, Effect, Engine

# 1. Define your story structure
story_graph = StoryGraph(
    start_node_id="intro",
    nodes={
        "intro": Node(
            id="intro",
            title="The Gatehouse",
            body="You stand before the ancient stone gate.",
            choices=[
                Choice(
                    trigger="Push the gate", 
                    target_node_id="inside",
                    effects=[Effect(target="strength", operation="increment", value=1)]
                )
            ]
        ),
        "inside": Node(
            id="inside",
            title="Castle Courtyard",
            body="Welcome to the inner sanctum.",
            choices=[]
        )
    }
)

# 2. Initialize the Engine
engine = Engine(story_graph)

# 3. Traverse the story
node, triggers, variables = engine.run("intro", variables={"strength": 10})
print(f"[{node.title}] {node.body}")

---

🕹️ CLI Usage

Play any story graph JSON directly from your terminal:

# Using the shortcut
story-builder play examples/minimal_story.json

# Or using python module
python -m story_builder.cli play examples/minimal_story.json

---

🎨 Visualize Your Story Graph

Generate a visual representation of your narrative graph.

1. Install extras

pip install "story-builder[viz]"

Note: This also requires GraphViz to be installed on your system if you want to render images.

2. Run the command

story-builder visualize examples/minimal_story.json

It will generate a .dot file and a .png file, and attempt to open the image.

Example Visualization: (Generated graph image will appear here)

---

Structure Your Story, Control Your World.