Quick Start Guide

git clone https://github.com/miladrezanezhad/story-toolkit.git
cd story-toolkit
pip install -r requirements.txt

# Or install directly
pip install -e .

from story_toolkit import StoryToolkit

# Create toolkit instance
toolkit = StoryToolkit()

# Create a fantasy story
story = toolkit.create_story(genre="fantasy", theme="courage")

print(story["metadata"]["genre"])   # "fantasy"
print(story["metadata"]["theme"])   # "courage"

# Add hero
hero = toolkit.add_character_to_story(story, "Kai", "protagonist")
hero.add_trait("brave")
hero.add_trait("determined")
hero.add_goal("Save the kingdom")
hero.add_skill("sword_mastery")
hero.add_fear("darkness")

# Add villain
villain = toolkit.add_character_to_story(story, "Shadow Lord", "antagonist")
villain.add_trait("cunning")
villain.add_trait("ruthless")
villain.add_goal("Conquer the realm")

# Create relationship
hero.add_relationship("Shadow Lord", "enemy", strength=9)

print(f"Hero: {hero.name}, Traits: {hero.personality_traits}")
print(f"Villain: {villain.name}, Goal: {villain.goals[0]}")

# Generate conflict dialogue
dialogue = toolkit.dialogue_gen.generate_dialogue(
    "Kai", "Shadow Lord",
    context="conflict",
    mood="tense"
)

for line in dialogue:
    print(line)

from story_toolkit.core.world_builder import WorldBuilder

world = WorldBuilder()
world.create_world("Eldoria", "fantasy")

# Add locations
world.add_location("Crystal City", "Ancient metropolis", "city")
world.add_location("Shadow Forest", "Mysterious woods", "forest")
world.add_location("Dragon's Peak", "Smoking volcano", "mountain")

# Connect locations
world.connect_locations("Crystal City", "Shadow Forest")

# Add rules
world.add_rule("magical", "Only pure hearts can use magic")
world.add_rule("social", "The Council of Seven rules")

# Add faction
world.add_faction(
    "Shadow Guild",
    "Secret organization",
    goals=["control_magic", "overthrow_council"]
)

summary = world.get_world_summary()
print(f"Locations: {summary['total_locations']}")

report = toolkit.check_story_coherence(story)

print(f"Coherence Score: {report['overall_score']:.0%}")

if report['plot_holes']:
    print("Plot holes found:")
    for hole in report['plot_holes']:
        print(f"  - {hole}")

if report['recommendations']:
    print("Recommendations:")
    for rec in report['recommendations']:
        print(f"  💡 {rec}")

from story_toolkit.utils.helpers import save_story, export_to_markdown

# Save as JSON
save_story(story, "my_story.json")

# Export as Markdown
export_to_markdown(story, "my_story.md")

# Or use toolkit method
toolkit.export_story(story, format="json", filename="my_story")

pip install story-toolkit[openai]      # OpenAI support
pip install story-toolkit[anthropic]   # Anthropic support
pip install story-toolkit[local]       # Local LLM (Ollama)
pip install story-toolkit[all]         # All backends

from story_toolkit.llm import LLMFactory, LLMProvider

# Create mock backend (no API key needed)
llm = LLMFactory.create_backend(provider=LLMProvider.MOCK)
toolkit = StoryToolkit(llm_backend=llm)

# Check LLM status
status = toolkit.get_llm_status()
print(status)  # {'available': True, 'provider': 'mock', 'model': 'mock'}

# Generate advanced dialogue with different styles
styles = ["natural", "dramatic", "poetic", "humorous"]

for style in styles:
    dialogue = toolkit.dialogue_gen.generate_dialogue(
        "Knight", "Dragon",
        context="final_battle",
        use_advanced=True,
        style=style,
        num_lines=4
    )
    print(f"\n--- {style.upper()} ---")
    for line in dialogue:
        print(line)

# First install Ollama
ollama pull llama2

# Then use in Python
llm = LLMFactory.create_backend(
    provider=LLMProvider.LOCAL,
    model="llama2",
    temperature=0.7
)
toolkit = StoryToolkit(llm_backend=llm)

import os
os.environ["OPENAI_API_KEY"] = "sk-..."

llm = LLMFactory.create_backend(
    provider=LLMProvider.OPENAI,
    model="gpt-3.5-turbo",
    temperature=0.8
)
toolkit = StoryToolkit(llm_backend=llm)

dialogue = toolkit.generate_advanced_dialogue(
    "Hero", "Villain",
    context="betrayal",
    style="dramatic"
)

# Create toolkit with memory
toolkit = StoryToolkit(memory_backend="sqlite", db_path="stories.db")

# Create story and auto-save to memory
story = toolkit.create_story(
    genre="fantasy",
    theme="courage",
    name="My Epic Story",
    save_to_memory=True
)

# Add events to story timeline
toolkit.add_event(chapter=1, description="Kai finds the ancient map", importance=9)
toolkit.add_event(chapter=2, description="Shadow Lord attacks the village", importance=10)
toolkit.add_event(chapter=3, description="Kai meets the mysterious mentor", importance=7)
toolkit.add_event(chapter=4, description="Training montage begins", importance=6)
toolkit.add_event(chapter=5, description="Final battle approaches", importance=10)

# View timeline
timeline = toolkit.get_timeline()
for event in timeline:
    stars = "⭐" * event.importance + "☆" * (10 - event.importance)
    print(f"Ch.{event.chapter:2d} [{stars}] {event.description}")

# List all stored stories
stories = toolkit.list_stored_stories()
for s in stories:
    print(f"📖 {s.name} (ID: {s.id}) - {s.genre}/{s.theme}")

# Load a story from memory
loaded = toolkit.load_story_from_memory(story_id)

# Add character to loaded story
new_hero = toolkit.add_character_to_story(loaded, "New Hero", "protagonist")

# Close connection when done
toolkit.close_memory()

pip install story-toolkit[export]
# Or individually:
pip install reportlab   # PDF export
pip install ebooklib    # EPUB export

from story_toolkit.exporters import PDFExporter, ExportConfig, PDFStyle

# Print style (for books)
config = ExportConfig(title="The Crystal Saga", author="Kai", pdf_style=PDFStyle.PRINT)
exporter = PDFExporter(config)
exporter.export(story, "story_print.pdf")

# Manuscript style (for publishers)
config.pdf_style = PDFStyle.MANUSCRIPT
exporter.export(story, "story_manuscript.pdf")

# eBook style (for screen reading)
config.pdf_style = PDFStyle.EBOOK
exporter.export(story, "story_ebook.pdf")

from story_toolkit.exporters import EPUBExporter

config = ExportConfig(title="The Crystal Saga", author="Kai")
exporter = EPUBExporter(config)
exporter.export(story, "story.epub")

from story_toolkit.exporters import HTMLExporter, HTMLTemplate

templates = [
    (HTMLTemplate.MODERN, "story_modern.html"),
    (HTMLTemplate.CLASSIC, "story_classic.html"),
    (HTMLTemplate.DARK, "story_dark.html"),
    (HTMLTemplate.MINIMAL, "story_minimal.html")
]

for template, filename in templates:
    config = ExportConfig(title="My Story", author="Me", html_template=template)
    exporter = HTMLExporter(config)
    exporter.export(story, filename)
    print(f"✅ Created: {filename}")

from story_toolkit.exporters import to_bionic

text = "This is a normal sentence that can be read faster with Bionic Reading."

# Strength 1: bold first letter
bionic1 = to_bionic(text, strength=1)
print(bionic1)

# Strength 2: bold first two letters
bionic2 = to_bionic(text, strength=2)
print(bionic2)

# HTML output with <strong> tags
bionic_html = to_bionic(text, as_html=True)
print(bionic_html)

from story_toolkit import StoryToolkit

toolkit = StoryToolkit()

# List all templates
templates = toolkit.list_templates()
for t in templates:
    print(f"📋 {t['name']}: {t['stage_count']} stages - {t['genre']}")

# Create epic fantasy story
story = toolkit.use_template("hero_journey", genre="fantasy", theme="redemption")

# View all 12 stages
for i, stage in enumerate(story['plot']['main_plot'], 1):
    print(f"{i}. {stage['name']}")

story = toolkit.use_template("three_act", theme="revenge")

for stage in story['plot']['main_plot']:
    print(f"📍 {stage['name']}: {stage['description'][:60]}...")

story = toolkit.use_template("mystery_clues", theme="whodunnit")

stages = story['plot']['main_plot']
print(f"📖 {len(stages)} stages for your mystery story:")
for stage in stages:
    print(f"   - {stage['name']}")

# Create a new story
story-toolkit story new --genre fantasy --theme courage

# Create story with specific complexity
story-toolkit story new --genre sci_fi --theme survival --complexity 5

# Save story to JSON file
story-toolkit story new --genre fantasy --theme courage --output my_story.json

# List all stories in database
story-toolkit story list

# List all available templates
story-toolkit template list

# Use a template
story-toolkit template use hero_journey

# Use template with custom theme
story-toolkit template use three_act --theme redemption --output three_act.json

# Step 1: Create a story using hero_journey template
story-toolkit template use hero_journey --genre fantasy --theme courage --output epic.json

# Step 2: Check what's in the story
# (Open epic.json or use Python to inspect)

# Step 3: List all your stories
story-toolkit story list

# Step 4: Load a story from database (if saved with memory)
story-toolkit story load --id abc123

from story_toolkit import StoryToolkit
from story_toolkit.llm import LLMFactory, LLMProvider
from story_toolkit.exporters import PDFExporter, ExportConfig, PDFStyle

# 1. Create toolkit with LLM and Memory (v2.0.0 + v2.1.0)
llm = LLMFactory.create_backend(provider=LLMProvider.MOCK)
toolkit = StoryToolkit(llm_backend=llm, memory_backend="sqlite", db_path="my_stories.db")

# 2. Create story using template (v2.2.1)
story = toolkit.use_template("hero_journey", genre="fantasy", theme="redemption")

# 3. Add custom characters (v1.0.0)
hero = toolkit.add_character_to_story(story, "Kai", "protagonist")
hero.add_trait("brave")
hero.add_goal("Save the kingdom")

villain = toolkit.add_character_to_story(story, "Shadow Lord", "antagonist")
villain.add_trait("cunning")

# 4. Generate advanced dialogue (v2.0.0)
dialogue = toolkit.dialogue_gen.generate_dialogue(
    "Kai", "Shadow Lord",
    context="final_battle",
    use_advanced=True,
    style="dramatic",
    num_lines=8
)

# 5. Add to timeline (v2.1.0)
toolkit.add_event(1, "Hero discovers ancient map", "plot", 9)
toolkit.add_event(2, "Villain attacks village", "conflict", 10)
toolkit.add_event(3, "Hero meets mentor", "character_development", 7)

# 6. Check coherence (v1.0.0)
report = toolkit.check_story_coherence(story)
print(f"Coherence Score: {report['overall_score']:.0%}")

# 7. Export to PDF (v2.2.0)
config = ExportConfig(title="The Crystal Saga", author="Kai", pdf_style=PDFStyle.PRINT)
exporter = PDFExporter(config)
exporter.export(story, "crystal_saga.pdf")

# 8. View timeline
print("\n📅 Story Timeline:")
for event in toolkit.get_timeline():
    print(f"   Ch.{event.chapter}: {event.description}")

# 9. Close memory connection
toolkit.close_memory()

print("\n✅ Complete story created with all features!")